# 开发环境运行手册

## 前置

- Bun 1.4.3(锁定)、Docker；Linux 解析沙箱构建需要 C 编译器和 Node-API 头文件(Debian: `build-essential libnode-dev`)。不需要单独安装 Node.js / pnpm。
- 端口:web 5180、API 4390、PG 55433。4380 留给本机部署版(Caddy),本机 3000/5175/5176/55432 已被其他项目占用,不要改用。

## 首次启动

```sh
cp .env.example .env          # 按需修改;server 与 db 脚本都读仓库根 .env
bun install --frozen-lockfile # 按 bun.lock 装 workspace 依赖
bun run dev:up              # 起开发库 postgres:18.6(docker-compose.dev.yml)并迁移到最新;拉代码后也跑一次
bun run dev                 # 同时起 server(4390)与 web(5180)
```

单独起:`bun run dev:server`(`bun --watch`,默认 `--role all`,API + worker 同进程)、`bun run dev:web`。

## 验证

```sh
curl localhost:4390/api/v1/health
# 开发模式可用 .env 的 DEV_ADMIN_KEY 作 admin
curl -N -H "Authorization: Bearer umt-dev-admin-key" "localhost:4390/api/v1/events?after=0"          # SSE 流(控制台用)
curl -H "Authorization: Bearer umt-dev-admin-key" "localhost:4390/api/v1/events?after=0&limit=50"   # JSON 补读页(API Key 调用者用)
```

- OpenAPI:http://localhost:4390/api/openapi.json,文档页 http://localhost:4390/api/docs
- 控制台:http://localhost:5180,右上角钥匙按钮设置 API Key(存 localStorage `umt-api-key`)

## 常用命令

| 命令 | 作用 |
|---|---|
| `bun run ci` | typecheck(tsc 7.0.2)→ lint(biome)→ test(vitest)→ check:tokens / check:copy → build → check:binary,提交前必须全绿 |
| `bun run typecheck` | 逐个成员跑 tsc 7.0.2 |
| `bun run lint` / `bun run fmt` | biome 检查 / 自动修复(含 import 排序;相对 import 必须带扩展名) |
| `bun run test` | 逐个成员跑 vitest(`bun x --bun vitest run`);单包:`cd packages/<x> && bun run test` |
| `bun run db:reset` | 清空 public schema 并重新迁移(生产环境拒绝执行) |
| `bun run gen:types` | 从已迁移的库反射生成 `packages/db/src/types.ts` |
| `bun run gen:tokens` | 改了 app.css 后重新生成 token 登记表 |
| `bun run build` | web 构建到 `apps/web/build/client` + server 编译为单文件 `dist/umt-server` |
| `cd apps/server && bun run start` | 直接跑源码；外部字节解析另走 Linux seccomp 子进程 |

依赖:各成员包在 `package.json` 登记依赖,根 `package.json` 管理 workspace 与共用工具。修改依赖后运行 `bun install` 更新 `bun.lock`；正常拉取使用 `bun install --frozen-lockfile`。解析沙箱测试前运行 `bun run sandbox:build`(`test:all` 会自动构建)。

## 工程设计与适度抽象

适度抽象用于减少重复修改、统一可靠行为,方便后续维护与开发。判断依据是已有实现的共同语义,不只看代码外形相似。

- 有稳定的重复机制时及时提取,例如协议分帧、消息上限、进程退出与回收；新增业务任务应能复用这些行为,不必重复写管道循环。
- 调用方各自决定的策略保持显式。文件操作按进度停滞判断超时,解析按总时长和 RSS 判断；权限、业务重试、取消后的文件清理不放进通信层。
- 共用机制放在双方可依赖的最小内部模块,按用途导出。不要为了复用创建完整框架,也不要用大量模式开关把不同业务揉成一个类。
- 保留清晰的类型边界。协议载荷在共用层是 unknown,具体输入、进度和结果由业务模块定义与校验；业务代码不直接依赖传输细节。
- 只有第二个实际使用方出现相同的管理逻辑时,再提取排队、常驻 worker 管理或进程池。没有性能证据时,不因为别的项目复用了进程就提前改运行方式。
- 持久业务任务与本地执行任务分别建模。下载、整理等流程的恢复与去重归任务引擎和业务记录；文件/解析 worker 只完成一次执行。通信失败不能自动重做有副作用的操作。
- 定时任务的触发与执行分开考虑:短巡检可直接运行；长耗时、需要恢复或产生重要副作用的任务应入持久队列。新任务不要在调度器里另建一套重试与恢复逻辑。
- 抽象后的测试覆盖真实边界:分块传输、异常退出、取消、大小超限、故障回收；业务模块继续验证各自的超时与副作用。不要只测试一层转发调用。

当前共用入口为 `@umt/runtime/worker`(`packages/runtime/src/worker.ts`):一次性连接、逐行 JSON 协议及有界回收。文件代理和解析代理分别选择启动环境、消息上限和终止策略；仍使用一次性子进程,未引入常驻池或自动重试。

协议为 `{id,task,input}` 请求,以及 `{id,type:"progress",value}` / `{id,type:"result",result}` / `{id,type:"error",error:{code,message,detail?}}` 响应。每条消息必须以换行结束。文件协议单条上限 16 MiB(内容走文件系统),解析协议单条上限 128 MiB(包括 base64)；stderr 持续排空且仅保留末尾 2000 字符用于诊断。大小限制不替代任务的解压与资源限制。

服务端 `FS_PROXY_MODE` 缺省为 `subprocess`,启动失败报错。`auto` 的进程内回退仅在明确选择时使用,不能保证回收阻塞在系统调用中的线程。解析隔离失败始终报错。

### 模块与业务入口

- 业务操作由所属模块的 service 提供,负责业务不变量、写入和事务边界。HTTP 路由负责协议、访问权限、参数与响应；能力处理器负责能力输入与授权上下文,然后调用同一业务入口。服务不从路由文件或 Agent 会话编排里取业务实现。
- 跨模块的同步操作可以显式调用已有 service,无需为一次调用再建接口、注册表或消息总线。需要随业务提交可靠触发的异步后续动作,在同一事务写 outbox；接收方按业务 ID 回查并幂等执行。
- 共用计划绑定、持续授权范围和预算检查放在 `src/authorization/grants.ts`；Agent 专有的会话、审批交互策略留在 `modules/agent/authorize.ts`。共用数据检查不依赖 Agent 会话装配。
- 示例:策略预演/发布由 `acquisition-organize/services/policies.ts` 提供,路由与能力共用；整理入口仍是 `services/organize.ts`,内部按计划、执行、收尾拆分。首次完成与恢复重放共用收尾处理,移除 qB 的不同判断留在各自调用处。
- 任务由所属模块用 `defineTask` 注册真实 handler,`@umt/tasks` 只提供执行机制；未注册任务明确报错,不注册空壳兜底。同步业务规则直接实现,出现实际扩展需求后再判断是否需要钩子。
- 同一含义的类型只定义一份,例如 domain 与 contracts 共用 `ContentType`。`@umt/mapping` 只处理真实语义差异,例如下载暂停原因或 `undefined ↔ unknown`,不为同值枚举保留转换表。

### 状态与配置归属

每个阶段维护自己的业务事实,引擎成功只表示本次任务尝试完成。业务仍在等待授权、资源或磁盘空间时,不能因为引擎成功就显示业务已完成。时间线与页面应按这些事实生成只读投影,不要另存一套总流程状态。

| 事实 | 维护方 |
|---|---|
| 发布资源解析、身份绑定与证据 | sources-identity 的资源/身份记录 |
| 订阅目标、单元满足度、候选与收录计划 | acquisition-organize 的 subscription / slot / acquisition_plan |
| 下载提交与下载进度 | download_task 与下载服务 |
| 整理计划、执行结果与文件证据 | organization_record / organization_file_result 与整理服务 |
| 刮削结果 | scrape_record 与刮削服务 |
| 步骤、租约、重试与唤醒 | 任务引擎；不替代上述业务状态 |

部署环境负责连接地址、密钥、基础目录等；settings 负责日常业务策略；单次请求只覆盖明确允许的选项,需要恢复的执行计划冻结本次有效值。读取与校验放在所属模块已有的配置入口,调用方不各写一遍合并规则。存量配置的优先级仍按各模块现有约定执行,有实际重复再统一；对用户有影响的覆盖应说明有效值与来源。

收录策略的适度抽象：`domain/acquisition/policy.ts` 维护分类选择顺序，`domain/slot/season-release.ts` 维护规格身份与排序，候选判断仍在 `evaluateCandidate`。`services/collection-strategy.ts` 统一策略模板到订阅版本的创建入口，分类查询在事务外，版本创建在订阅锁内。追更与洗版通过同一 `SlotSpec` 的阶段规则表达，不创建两套计划执行器。季级目标从资产与计划事实计算，计划冻结在途规格；分集完成、界面和旧文件处置都使用这些事实。

资源属性属于 sources-identity：`service/release-facts.ts` 合成解析输入，Agent 补充只存 `raw._facts` 并保留出处，重解析不会抹掉它，新的明确解析值优先。`release-facts-admin.ts` 提供窄的补全入口，调查编排和持续授权仍由 agent 模块处理；两者不互相承接业务状态。修改规则编辑器时应保留未编辑的 JSON 字段，同时显式清除用户删除的已编辑字段。

后续优先扩展现有纯判断和业务服务；出现共同不变量时抽成有明确输入输出的函数，文件 IO、事务锁、授权和重试继续留在执行阶段。默认策略更新只影响后续模板创建，不隐式改写已建订阅版本；需要调整已有作品时直接编辑其保留版本。新增规则字段必须同时检查候选评估、完成口径、覆盖展示和物理替换，避免各自形成第二套规则。

配置收敛先确定编辑归属：订阅表单维护追踪与下载安排，具体版本维护质量、组合规则和洗版；删掉重复入口时同步删除草稿与序列化，不留下两套普通写入路径。旧导入字段保留在兼容入口，普通保存不得清除或重建它们。总览与执行复用 `resolveRuleChain` 的版本优先级，订阅级自动补全继承主版本的收录链；显式开关仍优先。业务记录跳转复用 `subjectLink`，异常状态复用现有决策状态，不另造处理中心。

手动下载以默认值直接提交，高级选项仅覆盖本次操作。搜索与工作台复用 `ManualDownloadActions` 的提交反馈、未识别确认和高级选项窗口，资源摘要与 API 参数仍由各入口转换；原站页面保留必须先解析详情的准备步骤。默认下载不先加载目录、作品详情或已有版本，不为三个入口引入通用流程引擎。

维护时先验证真实的成功、失败和恢复路径,尤其是授权、文件替换、取消与外部副作用；删除空壳或无使用者的机制时同步删除其专属测试与文档。不要为了目录对称增加转发层,也不要把不同阶段的状态合并成一个枚举。

## 进程角色

`umt-server --role api|worker|worker:agent|all`(源码:`bun apps/server/src/main.ts --role ...`)。

| 角色 | 引擎 worker | OutboxRelay / 模块后台循环 |
|---|---|---|
| `api` | 不起(只入队/信号/取消) | 不跑 |
| `worker`(io 组) | 除 agent 道外的全部任务,分文件 / 网络 / 维护三条道(见下) | 跑 |
| `worker:agent` | 只跑 agent 道(`runAgent`/`resolveDecision`),并发 `WORKER_AGENT_CONCURRENCY`(缺省 2) | 不跑 |
| `all` | io 三条道 + agent 共四个池(开发缺省) | 跑 |

分组 worker 只认领自己的任务(`@umt/tasks` 按任务名过滤认领),Agent 长会话不占文件复制的槽,反之亦然。
worker 里有事件循环延迟探针:偏差超过 5s 打 `worker 事件循环延迟超过阈值` warn,次数随心跳事件(`loopLagWarnings`)发出;
每 15s 的进程心跳另记延迟与峰值(`process_heartbeat` / `process_heartbeat_sample`),运行状态页可看历史。

### IO Worker 分道(WK-1)

io worker 进程内按任务声明的 `lane` 起三个引擎 worker,各自独立并发、各自排队,一条道占满不影响另一条道领取:

| 道 | 缺省并发 | 放什么 |
|---|---|---|
| 文件 `file` | 2 | 整理(复制/硬链接/移动)、ffprobe、校验、接管整理、下载盘阈值清理 |
| 网络 `network` | 4 | 站点快照、RSS、TMDB、元数据刷新、搜索、下载器提交、识别(单站限流照旧另计,见 sites.md) |
| 维护 `maintenance` | 1 | 回收站清理、资产对账、调度器里内联的清理 / 回填 / 保留期裁剪;**空闲时跑** |

- **声明**:任务在 `defineTask({ lane })` 里显式声明(`@umt/tasks` 的 `TASK_LANES`)。没声明的任务运行时归网络道并在启动日志里
  warn「这些任务没有声明 lane」;ci 里 `apps/server/test/worker-lanes.test.ts` 会失败(注册表与下表逐项核对,新增任务必须同时改这里)。
  选"ci 报错 + 运行时兜底网络道"而不是"启动即失败":漏声明不该让生产进程起不来,但不能悄悄进 main。
- **维护道让路**:维护道每次领取前查全库文件道 + 网络道有没有已到点排队或正在运行的 run(1s 缓存),有就不领;已经在跑的维护任务
  不打断。连续让路超过 10 分钟放行一个(日志「维护道让路超时」),防止网络道长期有活时维护永远跑不上。实现是给维护道 worker 的
  认领加闸门(`StartWorkerOptions.claimGate`),不改 OpenWorkflow;取舍:按"全库有无活"判断,多个 io 实例时别的实例忙也会让路,
  判断有 1s 滞后,够用且简单。
- **调度器内联的维护任务**:`ScheduledJobDef.lane = "maintenance"` 的定时任务(下表)在调度器里直接执行,与维护道共用并发与让路规则:
  进不了维护道就保持到期、下一轮再试;在计划页点「立即执行」不让路。其余定时任务只入队或很快结束,不占道。
- **并发配置**:设置 → 系统 →「后台任务并发」(`settings.automation.workerLanes`),保存后约 5 秒内热生效(每道开 16 个槽,
  按设置值收)。环境变量 `WORKER_FILE_CONCURRENCY` / `WORKER_NETWORK_CONCURRENCY` / `WORKER_MAINTENANCE_CONCURRENCY` 设了就以变量为准
  (运行状态页悬停提示"由环境变量指定")。旧变量 `WORKER_CONCURRENCY` 映射到**网络道**(`WORKER_NETWORK_CONCURRENCY` 未设时):它原来
  是 io 组总并发,缺省 4,与网络道缺省相同;文件 / 维护道按设置页走。compose 不再给 `WORKER_CONCURRENCY` 缺省值。
- **观测**:运行状态页「进程」表的并发列,io 进程按道显示「运行中/并发 · 排队 N」,维护道让路时标「让路中」;数据在心跳行
  `concurrency.{file,network,maintenance}` 与 `extra.lanes`(排队是全库数,运行中是本进程数)。
- **拆进程的触发条件**(未实施):整理期间心跳事件循环延迟峰值持续 > 200ms,或整理需要贴近存储部署到另一台机器。

#### 任务归属表

ci 逐行核对这张表与任务注册表(`apps/server/test/worker-lanes.test.ts`),改任务的 lane 或新增任务时同步改。

| 任务 | 道 | 说明 |
|---|---|---|
| `verifyAndImport` | file | 下载完成后的校验、ffprobe、复制/硬链接/移动入库(含接管整理) |
| `cleanupDownloadCache` | file | 下载盘到暂停线时的清理;要尽快腾空间,不放维护道 |
| `scrapeMedia` | file | 刮削:写 NFO 与图片到媒体库目录(入库后自动 / 作品详情 / 文件管理),图片下载限并发 4 |
| `ingestFeed` | network | RSS 抓取 |
| `resolveObservation` | network | 标题识别 + TMDB |
| `enrichPoolEntry` | network | 未识别资源的元数据补全 |
| `refreshMetadata` | network | TMDB 元数据刷新 |
| `prewarmMetadata` | network | 关注作品预热:详情 / 各季 / 剧集组 / 海报背景标志进缓存(docs/runbook/cache.md) |
| `reresolveIdentifyWords` | network | 全局识别词保存后分批扫资源,标题命中改动行的重新识别(docs/design/identify-words.md) |
| `searchSubscription` | network | 订阅搜索 |
| `snapshotSite` | network | 站点快照 |
| `refreshSiteAccount` | network | 站点登录 / 用户数据刷新 |
| `evaluateAcquisition` | network | 获取策略评估(查库为主,随上游链路放网络道) |
| `submitDownload` | network | 提交下载器 |
| `identifyRemote` | network | 文件管理「识别」的 TMDB 查询 |
| `refreshPiTokens` | network | 模型服务 OAuth 令牌刷新 |
| `reconcileLibrary` | maintenance | 资产对账(扫库) |
| `purgeTrash` | maintenance | 回收站到期清除 |
| `scanOrganizeSource` | maintenance | 整理来源基线与增量快照，候选整理进入文件道 |
| `runAgent` | agent | Agent 会话(worker:agent) |
| `resolveDecision` | agent | 决策处理(worker:agent) |

调度器内联、走维护道的定时任务:`cache.sweep`、`cache.images_clean`、`cache.images_lru`、`auth.cleanup`、`system.heartbeat_cleanup`、
各保留期裁剪(`system/retention.ts` 的 `RETENTION_JOBS`)、`metadata.backfill_languages`(元数据语言回刷)。
只入队的定时任务(如 `trash.purge`、`cache.threshold`、`library.reconcile`、`pi.token_refresh`)按所入队任务的道执行。

启动时 `bootstrap()` 装配 `apps/server/src/modules/` 下的业务模块(见 apps/server/README.md),并连接任务引擎。数据库不可达时进程启动失败并退出。

acquisition-organize 的后台循环只做编排:qB 同步(含阈值暂停/恢复)一个定时器;另一个定时器按阈值入队 `cleanupDownloadCache`、
巡检补投 `submitDownload`/`verifyAndImport`、每 6h 入队 `reconcileLibrary`,重活都在任务里跑。
`POST /download-cache/cleanup`、`POST /library/reconcile` 同样只入队,返回 `{taskId, runId}`(202)。
HTTP 调用外部 IO 型能力(`release.search` 实时搜索、`release.inspect` 刷新详情、`identity.resolve`、`catalog.lookup` includeRemote)
限时 15s,站点并发 2、TMDB 并发 4,超时 502 / 排队满 429。

一次性子命令(容器入口用):`--role migrate`(迁移到最新,迁移文件已编进二进制;随后迁移任务引擎的 openworkflow schema)、`--role preflight`(启动自检:生产环境拒绝占位符密钥与 root、DB 可达、`WEB_ROOT/index.html` 存在)、`--role probe`(打本机 `/api/v1/health`,HEALTHCHECK 用)。

设置 `WEB_ROOT` 后 API 进程在同一端口托管 web 构建产物:存在的文件直接返回,其余非 `/api` 路径回退 `index.html`。

## Docker 单容器部署

```sh
export SECRET_MASTER_KEY=$(openssl rand -hex 32) POSTGRES_PASSWORD=$(openssl rand -hex 16)
docker compose up -d --build        # 服务:app(4380)+ postgres(数据卷 umt-pg-data)
curl localhost:4380/api/v1/health
```

- 镜像:`oven/bun:1.4.3` 构建 web 与 `bun build --compile` 出二进制,并构建 `sandbox-policy.node`,运行时 `debian:trixie-slim` + gosu + postgresql-client + 静态 ffprobe,root 启动修 `/data` 属主后降权到 PUID(缺省 10001)。
- 入口 `docker/entrypoint.sh`:迁移 → 自检 → 同时起 api、worker、worker:agent 三个进程;任一退出则停掉其余并以非 0 退出,由 `restart: unless-stopped` 拉起。
- 主进程使用非 root 用户和只读的 `/app` 产物；外部字节解析另起子进程,由原生 seccomp 策略限制文件、网络与进程访问。镜像带静态 ffprobe；运行期写入落在 `DATA_DIR`(容器内 `/data`)。完整部署说明见 [deploy.md](deploy.md)。
- 构建版本号:`APP_VERSION=v0.1.0 docker compose build`(写入 web 的 `version.json`)。

## 测试数据库

需要 PG 的测试默认连 `DATABASE_URL` 或 55433 开发库。单包测试在库不可达时会跳过集成用例,`bun run test:all` 会先检查连接并直接失败,不能把跳过当作通过。tasks 包可用 `TASKS_TEST_DATABASE_URL` 指定独立库;每个测试文件使用带 pid+随机后缀的独立 schema,结束时删除,多份测试并发跑也不冲突。

测试被中断(超时、kill、并发跑挂掉)时 schema 不会删,开发库会越积越多。清理脚本:

```sh
bun scripts/dev-db-clean.ts            # dry-run:只打印清单
bun scripts/dev-db-clean.ts --verbose  # 同上,逐个列出 schema 名
bun scripts/dev-db-clean.ts --yes      # 真正删除
```

- 只在 `DATABASE_URL`(缺省 `postgres://umt:umt@localhost:55433/umt`)指向 localhost:55433 时运行,否则直接拒绝。
- 删除的 schema:`tasks_test_`、`test_`、`e2e_`、`umt_test_`、`ao_test_`、`fm_test_`、`w2a_test_`、`w2b_`、`w7a_mig_`、`w9g_search_`、`server_test_` 前缀。`public`、`openworkflow` 不动;有其它会话持锁的 schema(测试正在跑)跳过,但最好在没有测试运行时执行。
- 删除的 public 数据:名字以 `w32-`、`w33-`、`fe4-`、`qa-` 开头的作品(title)、站点(name)、订阅(title_query),以及按 restrict 外键挂在它们下面的行,在一个事务里删。`admin_user`(`w31-admin`)、`pi_upstream`、没有这些前缀的站点(fake 上游)和手工登记的数据不动;要牵连到受保护表时脚本中止。

## 排障

- `配置无效`:按提示检查 `.env`,`SECRET_MASTER_KEY` 至少 16 字符,`DATABASE_URL` 必须是 postgres://。
- health 返回 `db: "down"`:`docker compose -f docker-compose.dev.yml ps` 看容器健康状态。
- 解析沙箱提示策略模块不存在:先跑 `bun run sandbox:build`；编译部署需把 `sandbox-policy.node` 放在二进制旁边。
- tsc 使用 `config/tsconfig.base.json`；运行时类型来自 Node / Bun,不再生成 Deno 声明。
- 日志中的 passkey/token/cookie/authorization/password 字段与 URL query 参数会被替换为 `[REDACTED]`(含 `logger.child()` 绑定字段与 `err` 的 message/stack);若发现明文,属于缺陷。