UHD_Media_Tool/apps/server/README.md

@umt/server

服务进程(Bun 1.4.3):Hono HTTP API(/api/v1)、SSE 与 worker 入口。默认 --role all 单进程运行；部署按 api、worker(IO)、worker:agent 分进程。OpenAPI 见 /api/openapi.json、/api/docs。业务编排和写入放在模块 service,确定性规则放在 @umt/domain。

模块骨架

src/
  main.ts                 按 --role 装配进程
  context.ts              装配 ServerContext、实际任务注册表与 outbox 路由
  http/app.ts             系统路由 + 模块 registerRoutes
  worker/index.ts         任务 worker、OutboxRelay、模块后台循环
  authorization/grants.ts 共用计划绑定、持续授权范围与预算检查
  sandbox/                外部字节解析子进程与 seccomp 策略
  modules/
    types.ts              ServerModule / ServerContext 等装配契约
    index.ts              SERVER_MODULES 清单
    decision-hooks.ts     待处理事项的实际业务处理器
    auth-settings/        鉴权、密钥与设置
    sources-identity/     站点、资源、识别与元数据
    acquisition-organize/ 订阅、收录、下载、整理与刮削
    file-manager/         文件浏览与操作
    agent/                Agent 会话、交互与能力调用编排
    …                     其余模块见 SERVER_MODULES

跨模块的同步业务操作显式调用 service；可靠的异步后续动作随业务事务写 outbox。路由和能力处理器共用业务入口,service 不依赖 HTTP 路由或 Agent 会话编排。共用语义类型直接复用,有实际取值差异才用 @umt/mapping。完整边界、状态归属和抽象约定见 开发指南。

模块装配

modules/<area>/index.ts 导出 ServerModule,按实际需求实现:

入口	职责
registerRoutes(app, ctx)	注册相对 /api/v1 的路由,声明 scope、校验输入、调用 service
registerTasks(registry, ctx)	用 defineTask 注册真实 handler；任务名和版本不能重复,没有空壳兜底
registerCapabilities(registry, ctx)	规格取自 contracts,处理器调用 service
outboxRoutes(ctx)	事件 → 任务、任务数组或 null；生命周期事件允许多个订阅方,内部流程事件只有一个认领方
start(ctx) / stop()	后台循环与回收；需要恢复的长任务进入持久队列

ServerContext 提供 db、config、logger、events、engine、outbox、secrets、settings、capabilities。注册阶段只做装配,不要使用尚未连接的引擎。all 连接时顺带迁移引擎；分进程部署先执行 --role migrate,再以 runMigrations:false 连接。

业务写入与 ctx.outbox.emit(trx, type, payload, { idempotencyKey }) 同事务提交。payload 在 contracts 定义并校验,订阅任务按 ID 回查业务记录、幂等执行。引擎步骤与租约不替代业务表的状态。

新增功能模块

以 modules/subtitles/ 为样板,只接入实际需要的入口:

1. 在 packages/contracts/src/features.ts 登记 manifest(名称、用法、事件、能力、页面与插槽)。它进入 Agent 功能清单,由 test/modules.test.ts 核对。
2. 导出 ServerModule,设置 manifest: featureManifest("<id>"),加入 modules/index.ts。
3. 需要事后动作时订阅生命周期事件,用 parseEventPayload 读取；自己发新事件时在 contracts 登记类型、schema 与 LIFECYCLE_EVENTS。
4. 需要前端入口时在 apps/web/app/features/<id>.tsx 注册插槽并加入 features/index.ts,默认直接显示。
5. 新增 Agent 能力时同时登记 Skill 与能力地图,见根目录 CLAUDE.md。

同步规则直接在所属 service 实现。目前没有通用链式钩子；decision-hooks.ts 只处理已有待处理事项的业务动作。功能默认启用,无需另建插件系统或开关。

开发、测试和容器说明见 开发手册 与 部署手册。