baa-conductor

README.md

 1# runtime
 2
 3当前 runtime 只定义 `mini` 单节点的正式长期运行方式。
 4
 5## 内容
 6
 7- [`layout.md`](./layout.md): runtime 目录布局
 8- [`environment.md`](./environment.md): 必要环境变量和默认值
 9- [`launchd.md`](./launchd.md): `mini` 上的 launchd 安装与日常操作
10- [`node-verification.md`](./node-verification.md): `mini` 节点 on-node 检查
11- [`codexd.md`](./codexd.md): `codexd` 的正式运行边界
12
13## 当前约定
14
15- 长期运行节点只有 `mini`
16- canonical local API: `http://100.71.210.78:4317`
17- canonical local Firefox WS: `ws://100.71.210.78:4317/ws/firefox`
18- codexd local API: `http://127.0.0.1:4319`
19- codexd event stream: `ws://127.0.0.1:4319/v1/codexd/events`
20- canonical public host: `https://conductor.makefile.so`
21- `conductor` `http://100.71.210.78:4317` 现在直接提供 `/v1/status` 和 `/v1/status/ui` 只读状态视图
22- `status-api` `http://100.71.210.78:4318` 只作为本地只读兼容包装层，默认回源 `BAA_CONDUCTOR_LOCAL_API`
23- `https://conductor.makefile.so` 是同一套 conductor 主接口的公网入口
24- `BAA_CONDUCTOR_PUBLIC_API_BASE` 是 `conductor` upstream/public API base 的 canonical 变量名；launchd 会连同 legacy `BAA_CONTROL_API_BASE` 一起写给 `conductor`
25- `status-api` 只保留对 legacy `BAA_CONTROL_API_BASE` 的代码层兼容回退，不再把它当 canonical truth source
26- 推荐仓库路径：`/Users/george/code/baa-conductor`
27- repo 内的 plist 只作为模板；真正加载的是脚本渲染出来的安装副本
28
29## 当前正式服务
30
31- `conductor`: `launchd` 托管的主控制面，承载 `4317` 本地 API，也承接 `/v1/status` 和 `/v1/status/ui`
32- `codexd`: `launchd` 托管的独立 Codex 运行面，只走 `codex app-server` 路线，监听 `127.0.0.1:4319`
33- `status-api`: 可选 `launchd` 本地只读兼容包装层，监听 `4318`，默认读取 `4317` 上的 conductor `/v1/system/state`
34
35`codexd` 正式能力面只保留：
36
37- `GET /healthz`
38- `GET /describe`
39- `GET /v1/codexd/status`
40- `GET /v1/codexd/sessions`
41- `GET /v1/codexd/sessions/:session_id`
42- `POST /v1/codexd/sessions`
43- `POST /v1/codexd/turn`
44- `WS /v1/codexd/events`
45
46当前 runtime / launchd / 运维只验 `status / sessions / turn / events` 这条 `app-server` 会话链路。
47
48## 最短路径
49
501. `./scripts/runtime/install-mini.sh`
512. `./scripts/runtime/status-launchd.sh`
523. `./scripts/runtime/restart-launchd.sh`
534. `./scripts/runtime/verify-mini.sh`
545. `./scripts/runtime/codexd-e2e-smoke.sh`
556. `./scripts/runtime/browser-control-e2e-smoke.sh`
56
57如果还需要保留 `4318` 的 legacy 状态包装层，再显式加：
58
597. `./scripts/runtime/install-mini.sh --with-status-api`
608. `./scripts/runtime/status-launchd.sh --service status-api`
61
62## 当前推荐入口
63
64- 安装并切到当前正式仓库路径：
65  - `./scripts/runtime/install-mini.sh`
66- 读取默认只读状态视图：
67  - `curl "${BAA_CONDUCTOR_LOCAL_API:-http://100.71.210.78:4317}/v1/status"`
68- 如果旧脚本仍要求 `4318` wrapper，再安装：
69  - `./scripts/runtime/install-mini.sh --with-status-api`
70- 查看 `launchd` / HTTP 状态：
71  - `./scripts/runtime/status-launchd.sh`
72  - 默认同时检查 `conductor`、`codexd`
73  - 需要确认 `4318` 兼容包装层时，用 `--service status-api`
74- 停止 / 启动 / 重启：
75  - `./scripts/runtime/stop-launchd.sh`
76  - `./scripts/runtime/start-launchd.sh`
77  - `./scripts/runtime/restart-launchd.sh`
78  - 默认同时操作 `conductor`、`codexd`
79  - 需要单独管理时，用 `--service codexd`、`--service conductor` 或 `--service status-api`
80- 节点检查：
81  - `./scripts/runtime/verify-mini.sh`
82  - 或在仓库根跑 `pnpm verify:mini`
83  - 默认顺序执行 `check-launchd.sh` + `check-node.sh --skip-static-check`
84  - 默认只检查 `conductor`、`codexd`
85  - 需要把 `4318` 兼容包装层纳入检查时，显式加 `--service status-api`
86  - 需要单独定位静态或运行态问题时，再直接调用底层 `check-launchd.sh` / `check-node.sh`
87- 会话链路 smoke：
88  - `./scripts/runtime/codexd-e2e-smoke.sh`
89  - 会起临时 `codexd` + `conductor`，覆盖 `codexd status`、`GET /v1/codex`、session create/read、turn create/read，以及 `logs/codexd/**`、`state/codexd/**` 落盘
90- 浏览器控制链路 smoke：
91  - `./scripts/runtime/browser-control-e2e-smoke.sh`
92  - 会起临时 `conductor` + fake Firefox bridge client，覆盖 `GET /v1/browser` 的元数据上报、持久化读取、`fresh/stale/lost`、敏感值不泄露，以及 `POST /v1/browser/actions`、`POST /v1/browser/request`、`POST /v1/browser/request/cancel`、正式 SSE、legacy Claude wrapper 和 `/ws/firefox` 上的 `open_tab` / `request_cancel` / `api_request` / `stream_*`
93
94职责边界：
95
96- `launchd` 负责开机自启动和硬重启
97- `conductor-daemon` 和 `codexd` 只负责健康感知、重连和降级
98- 不做两个进程互相直接拉起