baa-conductor

T-020-status-host.md

  1---
  2task_id: T-020
  3title: Status API 本地宿主进程
  4status: done
  5branch: feat/T-020-status-host
  6repo: /Users/george/code/baa-conductor
  7base_ref: main@458d7cf
  8depends_on:
  9  - T-017
 10write_scope:
 11  - apps/status-api/**
 12updated_at: 2026-03-22
 13---
 14
 15# T-020 Status API 本地宿主进程
 16
 17## 目标
 18
 19把 `status-api` 从“可挂载运行时入口”推进到“带本地宿主进程或 node server adapter，可直接启动监听”的程度。
 20
 21## 本任务包含
 22
 23- 在 `apps/status-api/**` 内实现本地宿主进程或 node HTTP adapter
 24- 把 `createStatusApiRuntime()` 真正挂到监听端口
 25- 整理 `GET /healthz`、`GET /v1/status`、`GET /v1/status/ui` 的本地启动方式
 26- 补最小启动/冒烟验证
 27
 28## 本任务不包含
 29
 30- 修改 conductor-daemon
 31- 修改 control-api-worker
 32- 真实部署到 launchd
 33- D1 线上接入
 34
 35## 建议起始文件
 36
 37- `apps/status-api/src/index.ts`
 38- `apps/status-api/src/runtime.ts`
 39- `apps/status-api/src/service.ts`
 40
 41## 交付物
 42
 43- 可直接启动的 status-api 本地宿主进程
 44- 明确的本地端口和启动接口
 45- 后续 launchd 可直接复用的入口
 46
 47## 验收
 48
 49- `npx --yes pnpm --filter @baa-conductor/status-api typecheck`
 50- `npx --yes pnpm --filter @baa-conductor/status-api build`
 51- 能说明本地如何启动和访问 `healthz` / `status` / `ui`
 52
 53## 更新要求
 54
 55完成时更新 frontmatter 的：
 56
 57- `status`
 58- `base_ref`
 59- `updated_at`
 60
 61并补充下面这些内容：
 62
 63## files_changed
 64
 65- `apps/status-api/package.json`
 66- `apps/status-api/tsconfig.json`
 67- `apps/status-api/src/index.ts`
 68- `apps/status-api/src/cli.ts`
 69- `apps/status-api/src/host.ts`
 70- `apps/status-api/src/node-shims.d.ts`
 71- `coordination/tasks/T-020-status-host.md`
 72
 73## commands_run
 74
 75- `npx --yes pnpm install`
 76- `npx --yes pnpm --filter @baa-conductor/status-api typecheck`
 77- `npx --yes pnpm --filter @baa-conductor/status-api build`
 78- `npx --yes pnpm --filter @baa-conductor/status-api smoke`
 79- `node apps/status-api/dist/index.js --host 127.0.0.1 --port 4328`
 80- `curl --silent --show-error http://127.0.0.1:4328/healthz`
 81- `curl --silent --show-error http://127.0.0.1:4328/v1/status`
 82- `curl --silent --show-error http://127.0.0.1:4328/v1/status/ui | sed -n '1,8p'`
 83
 84## result
 85
 86- 已在 `apps/status-api/**` 内补齐 Node 宿主层，新增本地 HTTP request listener 与 `startStatusApiServer()`，把 `createStatusApiRuntime()` 真正挂到监听端口。
 87- 已补 `runStatusApiCli()` 与主入口直启逻辑，`node apps/status-api/dist/index.js` 现在默认监听 `127.0.0.1:4318`，可直接给 launchd 复用。
 88- 已新增包内脚本：`pnpm --filter @baa-conductor/status-api serve`、`start`、`smoke`；本地可访问 `GET /healthz`、`GET /v1/status`、`GET /v1/status/ui`。
 89- 已补最小真实 HTTP 冒烟验证：`smoke` 会拉起临时端口并验证三条 GET 路由，另外也手动确认了 `node apps/status-api/dist/index.js --host 127.0.0.1 --port 4328` 的实际监听响应。
 90
 91## risks
 92
 93- 当前宿主进程默认仍使用 `StaticStatusSnapshotLoader`，返回的是本地空快照；真实 D1 / 控制平面接线仍需后续整合任务注入。
 94- `dist/index.js` 的直启能力依赖当前统一 build 产物布局；如果后续全仓库再调整 `BAA_DIST_ENTRY` 或 shim 结构，需要同步验证直启检测逻辑。
 95
 96## next_handoff
 97
 98- 在后续整合中，把真实 snapshot loader 注入 `startStatusApiServer()` 或 CLI 启动路径，让 `/v1/status` 返回真实控制平面状态。
 99- 视 launchd/bootstrap 任务需要，在安装副本里补 `BAA_STATUS_API_HOST` / `BAA_STATUS_API_PORT` 等环境变量，或继续沿用默认 `127.0.0.1:4318`。
100- 如果后续希望把 status-api 嵌入到更大的 Node 宿主里，可直接复用本任务新增的 request listener / server adapter，而不必再改 service/runtime 层。
101
102开始时建议直接把 `status` 改为 `in_progress`。
103
104做完并推送后：
105
106- 如果等待整合，改为 `review`
107- 如果确认结束，改为 `done`