baa-conductor

T-019-conductor-http.md

  1---
  2task_id: T-019
  3title: Conductor 本地 HTTP 入口
  4status: done
  5branch: feat/T-019-conductor-http
  6repo: /Users/george/code/baa-conductor
  7base_ref: main@458d7cf
  8depends_on:
  9  - T-015
 10write_scope:
 11  - apps/conductor-daemon/**
 12updated_at: 2026-03-22
 13---
 14
 15# T-019 Conductor 本地 HTTP 入口
 16
 17## 目标
 18
 19把 `conductor-daemon` 从“只有 CLI/runtime 快照”推进到“具备本地只读 HTTP 探活入口”的程度，至少覆盖 `GET /healthz`、`GET /readyz`、`GET /rolez`。
 20
 21## 本任务包含
 22
 23- 在 `apps/conductor-daemon/**` 内实现最小本地 HTTP server
 24- 暴露 `healthz` / `readyz` / `rolez`，必要时补 `GET /v1/runtime`
 25- 把现有 runtime snapshot 接到这些只读接口
 26- 为本地 HTTP server 补最小测试或冒烟验证
 27
 28## 本任务不包含
 29
 30- 修改 `packages/db/**`
 31- 修改 control-api-worker
 32- 修改 status-api
 33- 完整任务调度器
 34
 35## 建议起始文件
 36
 37- `apps/conductor-daemon/src/index.ts`
 38- `apps/conductor-daemon/src/index.test.js`
 39
 40## 交付物
 41
 42- 本地 loopback HTTP 探活入口
 43- 清晰的 `healthz` / `readyz` / `rolez` 语义
 44- launchd 或 Nginx 后续可复用的读取面
 45
 46## 验收
 47
 48- `npx --yes pnpm --filter @baa-conductor/conductor-daemon typecheck`
 49- `npx --yes pnpm --filter @baa-conductor/conductor-daemon build`
 50- `node --test --experimental-strip-types apps/conductor-daemon/src/index.test.js`
 51
 52## 更新要求
 53
 54完成时更新 frontmatter 的：
 55
 56- `status`
 57- `base_ref`
 58- `updated_at`
 59
 60并补充下面这些内容：
 61
 62## files_changed
 63
 64- `apps/conductor-daemon/src/index.ts`
 65- `apps/conductor-daemon/src/index.test.js`
 66- `apps/conductor-daemon/src/node-shims.d.ts`
 67- `apps/conductor-daemon/tsconfig.json`
 68- `coordination/tasks/T-019-conductor-http.md`
 69
 70## commands_run
 71
 72- `git worktree add /Users/george/code/baa-conductor-T019 -b feat/T-019-conductor-http 458d7cf`
 73- `npx --yes pnpm install`
 74- `npx --yes pnpm --filter @baa-conductor/conductor-daemon typecheck`
 75- `npx --yes pnpm --filter @baa-conductor/conductor-daemon build`
 76- `node --test --experimental-strip-types apps/conductor-daemon/src/index.test.js`
 77- `git diff --check`
 78
 79## result
 80
 81- 已在 `apps/conductor-daemon` 内补上最小本地只读 HTTP server，基于 `BAA_CONDUCTOR_LOCAL_API` 暴露 `GET /healthz`、`GET /readyz`、`GET /rolez` 与 `GET /v1/runtime`，并限制为 loopback `http://` 地址。
 82- 已把现有 runtime snapshot 接到 HTTP 读取面，`ConductorRuntime` 现在会随启动/停止一起管理本地 server 生命周期，并在快照中回填实际监听地址。
 83- 已补测试覆盖降级态 `readyz/rolez` 语义与真实本地 HTTP 冒烟请求，`typecheck`、`build`、`node --test` 均通过。
 84
 85## risks
 86
 87- 当前 `/readyz` 的语义是“runtime 已启动且 lease 未降级”；后续如果要把本地 runs 恢复、调度器预热或更多依赖也纳入 readiness，需要再扩展判定。
 88- 为避免越出本任务 `write_scope`，Node 内建模块类型声明目前以 `apps/conductor-daemon/src/node-shims.d.ts` 本地 shim 形式维护；如果仓库后续统一引入 `@types/node`，应顺手收敛这里的声明。
 89
 90## next_handoff
 91
 92- launchd、Nginx 或后续 status 相关整合可以直接复用 `http://127.0.0.1:4317/healthz`、`/readyz`、`/rolez`、`/v1/runtime` 作为 conductor 的本地读取面。
 93- 如果后续需要更严格的运维判断，可在不改外部路由的前提下继续细化 `/readyz` 与 `/v1/runtime` 的字段。
 94
 95开始时建议直接把 `status` 改为 `in_progress`。
 96
 97做完并推送后：
 98
 99- 如果等待整合，改为 `review`
100- 如果确认结束，改为 `done`