baa-conductor

commit

77573ae

parent

532c4ee

author

im_wower

date

2026-03-22 22:17:09 +0800 CST

docs(codexd): require standalone daemon

 1@@ -83,9 +83,9 @@
 2 - 当前仍依赖 `BAA_CONTROL_API_BASE`
 3 - 定位是迁移期本地只读观察服务，不是主控制面
 4 
 5-### `codexd`（设计中，尚未实现）
 6+### `codexd`（设计中，尚未完整实现）
 7 
 8-- `mini` 本地常驻的 Codex 代理/执行组件
 9+- `mini` 本地常驻的独立 Codex 代理/执行组件
10 - 不是 TUI，不要求人工盯界面
11 - 负责把 Codex 作为双工工作组件来使用：
12   - 执行 worker step
13@@ -97,6 +97,7 @@
14   - 辅助兜底：`codex exec`
15   - 不驱动 TUI
16 - 负责 Codex 特有的会话、子进程、重试、超时和恢复语义
17+- 必须作为独立进程运行，不接受长期内嵌在 `conductor-daemon` 里的方案
18 
19 和现有组件的边界：
20 
21@@ -107,9 +108,10 @@
22 当前状态：
23 
24 - 仓库里已经有 `codex` step kind、planner 和 step template 抽象
25-- 但还没有真正的 `codexd` 进程、Codex 子进程管理或常驻代理实现
26-- 所以 `codexd` 现在仍是设计项，不是已落地组件
27+- `apps/codexd` 已有 daemon scaffold，但还没有完成 conductor 集成
28+- 所以 `codexd` 现在仍是半成品，不是已落地组件
29 - 后续实现时，不再把 `exec` 当作主双工方案；`exec` 只用于简单调用、测试和兜底
30+- 后续实现时，`conductor-daemon` 只能通过本地接口调用 `codexd`，不能自己长期维护一套并行 bridge
31 
32 ### `apps/worker-runner`
33 
34@@ -202,6 +204,7 @@
35 - 浏览器插件和后续调用方默认走新的 canonical host
36 - legacy control plane 依赖被逐步盘点并删除
37 - 为后续 `codexd` 预留清晰边界：`conductor` 管真相，`codexd` 管 Codex 会话和执行
38+- `launchd` 负责自启动和硬重启，`conductor-daemon` 与 `codexd` 负责健康感知、重连和降级
39 
40 ## 11. 当前已知残留
41 

 1@@ -24,6 +24,7 @@
 2 如果你关心“Codex 不再手工开 TUI，而是作为本地常驻代理工作”，再读：
 3 
 4 - [`docs/runtime/codexd.md`](./docs/runtime/codexd.md)
 5+- [`docs/decisions/0002-codexd-independent-daemon.md`](./docs/decisions/0002-codexd-independent-daemon.md)
 6 
 7 其中当前结论已经固定：
 8 
 9@@ -87,7 +88,8 @@ docs/
10 - 所有新公网说明统一写 `conductor.makefile.so`
11 - `status-api` 只作为本地只读观察面，不再作为默认对外业务接口
12 - 运行中的浏览器插件代码以 [`plugins/baa-firefox`](./plugins/baa-firefox) 为准
13-- `codexd` 目前只是设计项，还不是已实现组件
14+- `codexd` 目前还是半成品，不是已上线组件
15+- `codexd` 必须作为独立常驻进程存在，不接受长期内嵌到 `conductor-daemon`
16 - `codexd` 后续默认以 `app-server` 为主，不以 TUI 或 `exec` 作为主双工接口
17 
18 ## Canonical 入口

 1@@ -0,0 +1,46 @@
 2+# 0002 codexd 独立常驻进程决策
 3+
 4+## 状态
 5+
 6+已采纳。
 7+
 8+## 决策
 9+
10+`codexd` 必须是 `mini` 上的独立常驻进程，不允许把 Codex 的长期运行面内嵌到 `conductor-daemon` 里。
11+
12+同时明确：
13+
14+- `codexd` 由 `launchd` 托管
15+- `codexd` 是唯一 Codex 运行面
16+- `conductor-daemon` 只通过本地接口调用 `codexd`
17+- `codexd` 主接口基于 `codex app-server`
18+- `codex exec` 仅作为 smoke、简单调用和兜底路径
19+
20+## 原因
21+
22+- 目标需求是 Codex 常驻、双工、多轮和可恢复，不是一次性调用
23+- 内嵌在 `conductor-daemon` 内会把系统真相和 Codex 会话状态混在一起
24+- 独立进程更容易做崩溃隔离、日志落盘、会话恢复和运行态排障
25+- `conductor-daemon` 与 `codexd` 都由 `launchd` 管理时，可以各自重启并重新建立连接
26+
27+## 直接影响
28+
29+- 不再接受“把 `/v1/codex/*` 直接绑到 conductor 进程内 bridge”作为最终方案
30+- 后续 `conductor` 侧的 `/v1/codex/*` 只能作为 `codexd` 的代理面
31+- `codexd` 自己维护：
32+  - `logs/codexd/**`
33+  - `state/codexd/**`
34+  - session / turn / recent event 真相
35+
36+## 运行边界
37+
38+- `launchd` 负责硬重启和开机自启动
39+- `conductor-daemon` 与 `codexd` 负责健康感知、重连和降级
40+- 不做“一个进程直接拉起另一个进程”的无约束互救
41+
42+## 接口方向
43+
44+- 本地命令/查询面：HTTP
45+- 本地双工事件流：WS 或 SSE
46+- 远程 AI / CLI / 网页入口仍通过 `conductor.makefile.so`
47+

 1@@ -36,11 +36,14 @@ Firefox WS 说明：
 2   - 启动或占位一个 `codex app-server` 子进程配置
 3   - 持久化 daemon identity、child state、session registry、recent event cache
 4   - 提供 `start` / `status` / `smoke`
 5+- 运行约束：
 6+  - `codexd` 是独立常驻进程，不是 `conductor-daemon` 的内嵌 bridge
 7+  - `/v1/codex/*` 后续应以 `conductor-daemon -> codexd` 代理方式提供
 8+  - `launchd` 负责自启动和硬重启，不做两个进程互相直接拉起
 9 - 当前还没有：
10   - 对外 IPC / HTTP 面
11   - 真正的 `thread` / `turn` 管理
12-  - conductor 集成
13-  - 自动安装脚本里的 codexd service 渲染
14+  - `conductor-daemon -> codexd` 正式接线
15 
16 ## 最短路径
17 

 1@@ -52,6 +52,7 @@
 2 - 只跑在 `mini`
 3 - 由 `launchd` 托管
 4 - 通过本地 IPC、HTTP 或 WS 与 `conductor-daemon` 协作
 5+- 必须是独立进程，不接受长期内嵌在 `conductor-daemon` 内
 6 
 7 它不是：
 8 
 9@@ -97,6 +98,11 @@
10 - `worker-runner` 管通用执行框架
11 - `codexd` 管 Codex 本身
12 
13+额外约束：
14+
15+- `conductor-daemon` 不自己长期持有 Codex 会话状态
16+- `codexd` 是唯一 Codex 会话 / turn / recent events 的真相源
17+
18 ## 运行模型
19 
20 `codexd` 最合理的运行模型是：
21@@ -111,6 +117,13 @@
22    - 返回 step 结果或对话结果
23 4. `conductor-daemon` 把结果写回本地真相源
24 
25+进程恢复规则：
26+
27+- `launchd` 负责把挂掉的 `conductor-daemon` 或 `codexd` 拉起
28+- `conductor-daemon` 负责发现 `codexd` 不可用并重连
29+- `codexd` 负责发现 Codex child 不可用并重建子进程
30+- 不做“conductor 直接 spawn codexd”或“codexd 直接 spawn conductor”
31+
32 ## 官方接口结论
33 
34 基于当前本机已验证的 Codex CLI 公开接口，`codexd` 的设计结论应明确为：
35@@ -180,7 +193,7 @@
36 - HTTP / WS / IPC 入口
37 - conductor-daemon 适配层
38 - crash recovery 的自动复连和 session 恢复
39-- install-launchd 脚本里的 codexd service 渲染
40+- `conductor-daemon -> codexd` 的正式代理面
41 
42 ## 支持的两类工作
43 
44@@ -252,6 +265,9 @@
45   - turn 启动 / 打断 / 继续
46   - 增量事件日志
47 - 对 `conductor-daemon` 暴露稳定的本地适配层
48+- 这层至少拆成：
49+  - 本地 HTTP：session / turn / run / status
50+  - 本地 WS 或 SSE：增量事件流
51 
52 ### v1 兜底能力
53