# @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`。

## 模块骨架

```text
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`。完整边界、状态归属和抽象约定见 [开发指南](../../docs/runbook/dev.md#工程设计与适度抽象)。

## 模块装配

`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` 只处理已有待处理事项的业务动作。功能默认启用,无需另建插件系统或开关。

开发、测试和容器说明见 [开发手册](../../docs/runbook/dev.md) 与 [部署手册](../../docs/runbook/deploy.md)。