baa-conductor

T-015-conductor-runtime.md

 1---
 2task_id: T-015
 3title: Conductor 运行时接线
 4status: done
 5branch: feat/T-015-conductor-runtime
 6repo: /Users/george/code/baa-conductor
 7base_ref: main@c5e007b
 8depends_on:
 9  - T-004
10write_scope:
11  - apps/conductor-daemon/**
12updated_at: 2026-03-22
13---
14
15# T-015 Conductor 运行时接线
16
17## 目标
18
19把 conductor 从“状态机骨架”推进到“有可启动入口、有 env/CLI 配置、有 control-api client 接线”的程度。
20
21## 统一开工要求
22
23- 必须从当前最新 `origin/main` 切出该分支
24- 新 worktree 进入后先执行 `npx --yes pnpm install`
25- 不允许从其他任务分支切分支
26
27## 本任务包含
28
29- env / CLI 配置解析
30- 构造可启动的 daemon 入口
31- 组织 heartbeat / lease loop 启动流程
32- 暴露最小状态快照或运行时接口
33
34## 本任务不包含
35
36- 修改 `packages/db/**`
37- 修改 control-api-worker
38- 完整调度器
39
40## 建议起始文件
41
42- `apps/conductor-daemon/src/index.ts`
43- `apps/conductor-daemon/src/index.test.js`
44
45## 交付物
46
47- 可以启动的 conductor 运行时入口
48- 更明确的主备启动流程
49
50## 验收
51
52- `npx --yes pnpm --filter @baa-conductor/conductor-daemon typecheck`
53- `npx --yes pnpm --filter @baa-conductor/conductor-daemon build`
54- `node --test --experimental-strip-types apps/conductor-daemon/src/index.test.js`
55
56## files_changed
57
58- `apps/conductor-daemon/package.json`
59- `apps/conductor-daemon/src/index.ts`
60- `apps/conductor-daemon/src/index.test.js`
61
62## commands_run
63
64- `npx --yes pnpm install`
65- `npx --yes pnpm --filter @baa-conductor/conductor-daemon typecheck`
66- `node --test --experimental-strip-types apps/conductor-daemon/src/index.test.js`
67- `npx --yes pnpm --filter @baa-conductor/conductor-daemon build`
68- `node apps/conductor-daemon/dist/index.js start --node-id mini-main --host mini --role primary --control-api-base http://127.0.0.1:9 --run-once --json`
69- `git diff --check`
70
71## result
72
73- `apps/conductor-daemon` 现在有可执行的 CLI/runtime 入口，支持 `start`、`config`、`checklist`，并能从 env/CLI 解析节点身份、control-api 地址、共享 token 与本地目录配置。
74- control-api client 已按第三波 contract 补上 Bearer 认证、统一 envelope 解包，以及 `snake_case` 请求/响应兼容，能对接 `/v1/controllers/heartbeat` 和 `/v1/leader/acquire`。
75- runtime 侧新增最小快照接口 `ConductorRuntime.getRuntimeSnapshot()`，并把启动流程整理为：初始 heartbeat、初始 lease cycle、本地 runs hook、后台 loop 启动；同时补了 CLI/config/client/runtime 相关测试。
76- `conductor-daemon` 自身 `build` 脚本现在会产出 `dist/index.js`，验证过构建后的入口可以直接启动并在 control-api 不可达时稳定落到 `degraded` 快照。
77
78## risks
79
80- `apps/control-api-worker` 当前主线仍以占位 handler 为主；虽然 client 侧协议已对齐，但真实 heartbeat / lease 持久化效果仍依赖 `T-014` 把 handler 接到 repository。
81- 最小 runtime 接口当前是进程内快照与 CLI 输出，还没有单独的 loopback HTTP 服务；如果后续需要让 status-api 或 launchd 直接探活，可能还要在 `apps/conductor-daemon/**` 内补本地只读端点。
82- `conductor-daemon` 的 app 级 build 现已可产出 dist，但根级统一构建链路仍需 `T-013` 做最终收口，避免后续在脚本层重复调整。
83
84## next_handoff
85
86- `T-014` 可以直接用当前 client 期望的 Bearer + envelope + `snake_case` 约定实现真实 handler，并把 `/v1/controllers/heartbeat`、`/v1/leader/acquire` 返回值收敛到已测试的兼容形状。
87- 后续 scheduler / status 相关任务可以直接复用 `ConductorRuntime` 与 `getRuntimeSnapshot()` 作为启动态、主备态和配置态的最小读取接口。
88- `T-013` 如需统一根级 build/launchd 行为，应保留 `apps/conductor-daemon/dist/index.js` 作为稳定入口路径。
89
90## notes
91
92- `2026-03-21`: 创建第三波任务卡