im_wower
·
2026-03-28
README.md
1# baa-conductor
2
3`baa-conductor` 当前主线只为一件事服务：把 `mini` 本地接口收口成唯一主接口，并把对外入口统一到 `conductor.makefile.so`。
4
5当前主线口径：
6
7- canonical local API: `http://100.71.210.78:4317`
8- canonical public host: `https://conductor.makefile.so`
9- `control-api.makefile.so`、Cloudflare Worker、D1 只算迁移期 legacy 兼容件和残留依赖盘点目标，不再作为默认控制面
10- `baa-hand` / `baa-shell` 只保留为接口参考，不再继续维护为主系统
11
12主备切换、failover、switchback 和其它历史方案已经从当前主线移除；如需回溯，直接查看 tag `ha-failover-archive-2026-03-22`。
13
14## 先读什么
15
161. [`DESIGN.md`](./DESIGN.md)
172. [`docs/api/business-interfaces.md`](./docs/api/business-interfaces.md)
183. [`docs/api/control-interfaces.md`](./docs/api/control-interfaces.md)
194. [`docs/api/README.md`](./docs/api/README.md)
205. [`docs/runtime/README.md`](./docs/runtime/README.md)
216. [`docs/ops/README.md`](./docs/ops/README.md)
227. [`tasks/TASK_OVERVIEW.md`](./tasks/TASK_OVERVIEW.md)
23
24如果你关心“Codex 不再手工开 TUI，而是作为本地常驻代理工作”，再读：
25
26- [`docs/runtime/codexd.md`](./docs/runtime/codexd.md)
27- [`docs/decisions/0002-codexd-independent-daemon.md`](./docs/decisions/0002-codexd-independent-daemon.md)
28
29其中当前结论已经固定：
30
31- `codex app-server` 是未来 `codexd` 的主接口
32- 不实现 `codex exec` 式无交互正式模式
33- 直接调用 `codexd` 时，先读 `GET /describe`
34
35## 面向 AI 的推荐阅读顺序
36
37如果是网页版 AI、CLI AI 或手机网页 AI，推荐按这个顺序：
38
391. 先读 [`docs/api/business-interfaces.md`](./docs/api/business-interfaces.md)
402. 再读 [`docs/api/control-interfaces.md`](./docs/api/control-interfaces.md)
413. 然后按用途调：
42 - `GET /describe/business`
43 - 或 `GET /describe/control`
444. 如有需要，再调 `GET /v1/capabilities`
455. 完成能力感知后，再执行业务查询、通用 browser request、browser/plugin 管理动作或控制动作；如果要调用 `/v1/exec` 或 `/v1/files/*`，必须带 `Authorization: Bearer <BAA_SHARED_TOKEN>`
46
47## 当前目录结构
48
49```text
50apps/
51 conductor-daemon/
52 status-api/
53 worker-runner/
54plugins/
55 baa-firefox/
56packages/
57 auth/
58 checkpointing/
59 db/
60 git-tools/
61 host-ops/
62 logging/
63 planner/
64 schemas/
65 step-templates/
66ops/
67 launchd/
68 nginx/
69 sql/
70scripts/
71 ops/
72 runtime/
73plans/
74 STATUS_SUMMARY.md
75 archive/
76tasks/
77 TASK_OVERVIEW.md
78 archive/
79bugs/
80 README.md
81 archive/
82docs/
83 api/
84 auth/
85 decisions/
86 firefox/
87 ops/
88 runtime/
89```
90
91已完成的任务卡、需求文档和缺陷文档现在统一放在各自目录下的 `archive/` 子目录。
92
93## 当前约定
94
95- 所有新接口设计默认先落 `mini` 本地 `4317`
96- 所有新公网说明统一写 `conductor.makefile.so`
97- 只读状态视图的推荐入口已收口到 `conductor` 的 `/v1/status` 和 `/v1/status/ui`
98- `status-api` 当前决定是继续保留为本地只读观察兼容层，不立即删除
99- `mini` on-node 静态+运行态检查统一入口是 `./scripts/runtime/verify-mini.sh`（仓库根可用 `pnpm verify:mini`）
100- 运行中的浏览器插件代码以 [`plugins/baa-firefox`](./plugins/baa-firefox) 为准
101- 浏览器桥接正式模型已经固定为“登录态元数据持久化 + 单平台单空壳页 + 浏览器本地代发”；页面对话 UI 不是正式主能力
102- `GET /v1/browser` 是当前正式浏览器桥接读面：返回活跃 bridge 和持久化登录态记录，只暴露 `account`、凭证指纹、端点元数据与 `fresh/stale/lost`
103- 正式浏览器写接口已经收口到 `POST /v1/browser/request`、`POST /v1/browser/request/cancel` 和 `POST /v1/browser/actions`；`/v1/browser/claude/*` 只保留为 Claude legacy 包装与辅助读
104- `codexd` 目前还是半成品，不是已上线组件
105- `codexd` 必须作为独立常驻进程存在，不接受长期内嵌到 `conductor-daemon`
106- `codexd` 后续默认以 `app-server` 为主，不以 TUI 或 `exec` 作为主双工接口
107
108## Canonical 入口
109
110| 面 | 地址 | 定位 | 说明 |
111| --- | --- | --- | --- |
112| local API | `http://100.71.210.78:4317` | 唯一主接口、内网真相源 | 当前已承接 `/describe`、`/health`、`/version`、`/v1/capabilities`、`/v1/status`、`/v1/status/ui`、`/v1/browser/*`、`/v1/system/state`、`/v1/controllers`、`/v1/tasks`、`/v1/runs`、`pause/resume/drain`、`/v1/exec`、`/v1/files/read` 和 `/v1/files/write`；其中 `GET /v1/browser` 返回浏览器登录态元数据与持久化状态，`POST /v1/browser/request` / `cancel` / `actions` 走本地插件代发，Claude 专用 `/v1/browser/claude/*` 只保留 legacy 包装，host-ops 统一要求 `Authorization: Bearer <BAA_SHARED_TOKEN>` |
113| public host | `https://conductor.makefile.so` | 唯一公网域名 | 由 VPS Nginx 回源到 `100.71.210.78:4317`；`/v1/exec` 和 `/v1/files/*` 不再允许匿名调用 |
114| local status view | `http://100.71.210.78:4318` | 本地只读观察兼容层 | 显式 opt-in 保留，继续提供 `/describe`、`/v1/status`、`/v1/status/ui` 和 `/ui` 等 legacy 合同，不是主控制面 |
115
116legacy 兼容说明：
117
118- `https://control-api.makefile.so` 只用于迁移期间 legacy 兜底和识别残留依赖
119- 业务查询和系统控制写入已经不再依赖 Cloudflare Worker / D1 真相源
120- `apps/control-api-worker` 已从当前仓库移除；剩余 legacy 只保留在线上资产和历史文档背景里
121
122## 迁移顺序
123
1241. 把 `/describe`、能力发现、状态/任务/运行查询与控制动作并到 `mini` 本地 API，并保持 `conductor.makefile.so` 同步暴露。
1252. 让浏览器、CLI、AI、运维文档全部默认走 `conductor.makefile.so` / `100.71.210.78:4317`。
1263. 让 `status-api` 退回本地兼容包装层，并把 `/v1/status`、`/v1/status/ui` 并到 `conductor` 主接口。
1274. 删除 `control-api.makefile.so`、Cloudflare Worker、D1 和 hand/shell 的主系统角色。
128
129## 当前最重要的事
130
131- 保持 `mini` launchd、自启动和本地探针稳定
132- 保持 `conductor.makefile.so -> 100.71.210.78:4317` 的链路稳定
133- 保持 `/v1/browser`、通用 browser request/SSE、浏览器登录态持久化与 Claude legacy 包装合同稳定
134- 保持 `pnpm smoke` 和 browser-control e2e smoke 对浏览器链路持续可回归
135
136## 当前已知 gap
137
138- `verify-mini.sh` 只收口静态检查和运行态探针；会话级链路回归仍要单独跑 `pnpm smoke` 或 `./scripts/runtime/codexd-e2e-smoke.sh`
139- `status-api` 已降为显式 opt-in 的本地只读兼容包装层；旧调用方仍可能继续依赖 `4318`
140- `4318/status-api` 删旧与共享模块提取目前只是低优先级 backlog，不再是当前主线
141- `status-api` 和 `conductor /v1/status` 现在共享同一套状态拼装/渲染语义；如果未来要删 `status-api`，还需要先清 `4318` 调用方，并拆掉当前构建时复用
142
143## 本机能力层
144
145[`packages/host-ops`](./packages/host-ops) 现在提供本机能力层基础包，包含：
146
147- `exec`
148- `files/read`
149- `files/write`
150
151这个包负责本地 Node 能力、输入输出合同和结构化错误；当前已经通过 `conductor-daemon` 暴露到：
152
153- `/v1/exec`
154- `/v1/files/read`
155- `/v1/files/write`
156
157这些 host-ops 路由统一要求：
158
159- `Authorization: Bearer <BAA_SHARED_TOKEN>`
160- token 来自 daemon 启动时配置的 `BAA_SHARED_TOKEN`
161- 缺少或错误 token 时直接返回 `401` JSON 错误