im_wower
·
2026-03-25
hand-shell-migration.md
1# BAA Hand / Shell 接口迁移方案
2
3日期：2026-03-22
4
5## 1. 目标
6
7把 `baa-hand` / `baa-shell` 已经验证可用的 HTTP 交互方式迁到 `baa-conductor`，但承载面统一改为：
8
9- canonical local API: `http://100.71.210.78:4317`
10- canonical public host: `https://conductor.makefile.so`
11
12这次迁移的重点不是复用旧代码，而是复用旧系统已经被验证过的交互经验：
13
14- 先 `GET /describe`
15- 再决定调用哪个接口
16- 支持只读查询
17- 支持同步小操作
18- 支持异步任务提交与结果查询
19
20## 2. 当前判断
21
22`baa-conductor` 已经具备承接接口层的内核条件：
23
24- `task`
25- `run`
26- `step`
27- `worker`
28- `checkpoint`
29- `logging`
30- `mini` 单节点自启动
31- `conductor-daemon` / `worker-runner` / `status-api`
32
33所以后续不再继续平行维护三套系统：
34
35- `baa-hand`
36- `baa-shell`
37- `baa-conductor`
38
39目标是：
40
41- `baa-hand` / `baa-shell` 只作为参考实现
42- `baa-conductor` 成为唯一主项目
43- `control-api.makefile.so` 不再作为默认业务接口；如果线上仍保留同名域名，也只按 legacy 兼容背景理解
44
45## 3. 迁移边界
46
47### 3.1 本次要迁
48
49- 自描述接口
50- 控制型接口
51- 非控制型只读接口
52- 本机执行能力
53- 文件访问能力
54- 异步任务接口
55- 任务 / run / log 查询
56
57### 3.2 本次不迁
58
59- AI 接口优先级降低
60- `POST /ask`
61- `POST /chat`
62- 多轮 AI 会话
63
64说明：
65
66当前先把“本机访问能力”和“业务控制接口”统一进 `baa-conductor`；AI 代理如仍有需要，后续再单独设计。
67
68## 4. 设计原则
69
70### 4.1 不做兼容优先层
71
72不要为了兼容旧系统，把 `baa-hand` / `baa-shell` 的老实现直接搬进来。
73
74迁移的是：
75
76- 接口语义
77- 使用体验
78- 能力发现方式
79
80不是：
81
82- 旧代码结构
83- 旧内存状态机
84- 旧散装 server
85
86### 4.2 新接口围绕 `mini` 本地接口设计
87
88底层应直接接入：
89
90- `apps/conductor-daemon`
91- `task/run/step`
92- `worker`
93- `logs/checkpoints`
94
95控制面已经统一收口到 `apps/conductor-daemon`，不再保留单独 Worker 兼容层作为主架构。
96
97### 4.3 先读后写
98
99和 `baa-hand` / `baa-shell` 一样，建议约定：
100
1011. 先调 `GET /describe`
1022. 再调只读接口看当前状态
1033. 最后才调写接口
104
105### 4.4 单节点优先
106
107当前项目已经收口为 `mini` 单节点，所以新接口文档和行为都以单节点为准，不再继续围绕主备切换设计。
108
109## 5. 目标接口分层
110
111### 5.1 服务发现层
112
113- `GET /describe`
114- `GET /health`
115- `GET /version`
116- `GET /v1/capabilities`
117
118### 5.2 控制层
119
120- `GET /v1/system/state`
121- `POST /v1/system/pause`
122- `POST /v1/system/resume`
123- `POST /v1/system/drain`
124
125### 5.3 查询层
126
127- `GET /v1/controllers`
128- `GET /v1/tasks`
129- `GET /v1/tasks/:task_id`
130- `GET /v1/tasks/:task_id/logs`
131- `GET /v1/runs`
132- `GET /v1/runs/:run_id`
133
134### 5.4 本机能力层
135
136- `POST /v1/exec`
137- `POST /v1/files/read`
138- `POST /v1/files/write`
139
140当前进度：
141
142- 底层合同与最小 Node 实现已经落到 `packages/host-ops`
143- 已经正式挂到 `conductor-daemon` 本地 HTTP 面
144- 不会再对外暴露成单独 `control-api` 路由
145
146说明：
147
148- 这层承接 `baa-shell` 的“小而直接”的使用体验
149- 它属于本机访问能力，不是 legacy control-plane 状态写入
150
151### 5.5 异步任务层
152
153- `POST /v1/tasks`
154- `GET /v1/tasks`
155- `GET /v1/tasks/:task_id`
156- `GET /v1/tasks/:task_id/logs`
157- `GET /v1/runs`
158- `GET /v1/runs/:run_id`
159
160说明：
161
162- `exec/read/write` 适合同步小操作
163- 长活、worker 编排、日志跟踪应走 task/run
164
165## 6. 旧接口到新接口的映射
166
167### 6.1 `baa-shell`
168
169| 旧接口 | 新接口方向 |
170| --- | --- |
171| `GET /describe` | `GET /describe` |
172| `GET /health` | `GET /health` |
173| `GET /version` | `GET /version` |
174| `POST /exec` | `POST /v1/exec` |
175| `POST /read` | `POST /v1/files/read` |
176| `POST /write` | `POST /v1/files/write` |
177| `POST /task` | `POST /v1/tasks` |
178| `GET /task/:id` | `GET /v1/tasks/:task_id` |
179| `GET /tasks` | `GET /v1/tasks` |
180| `GET /reports` | 优先收口为 `GET /v1/tasks/:task_id/logs`，必要时再单独补 report 面 |
181
182### 6.2 `baa-hand`
183
184| 旧接口 | 新接口方向 |
185| --- | --- |
186| `GET /describe` | `GET /describe` |
187| `POST /ask` | 暂缓，不是当前优先级 |
188| `POST /chat` | 暂缓，不是当前优先级 |
189| `POST /plan` | 长期可考虑转成 `POST /v1/tasks` + planner 策略 |
190
191## 7. 推荐接口面
192
193对外推荐只保留一套：
194
195- local: `http://100.71.210.78:4317`
196- public: `https://conductor.makefile.so`
197
198不再把单独 `control-api.makefile.so` 写成默认或推荐目标；如果线上仍保留同名域名，也只按 legacy 兼容或残留依赖盘点目标理解。
199
200## 8. 实施顺序
201
202### 第一批
203
204- `GET /describe`
205- `GET /health`
206- `GET /version`
207- `GET /v1/capabilities`
208- `GET /v1/tasks`
209- `GET /v1/runs`
210- `GET /v1/controllers`
211
212目标：
213
214- 让 Claude、浏览器和 CLI 能先发现能力
215- 让新调用方直接走 `4317` / `conductor.makefile.so`
216
217### 第二批
218
219- `GET /v1/system/state`
220- `POST /v1/system/pause`
221- `POST /v1/system/resume`
222- `POST /v1/system/drain`
223
224目标：
225
226- 把当前 control-plane 的关键读写能力切到 canonical 接口面
227
228### 第三批
229
230- `POST /v1/exec`
231- `POST /v1/files/read`
232- `POST /v1/files/write`
233- `POST /v1/tasks`
234- `GET /v1/tasks/:task_id`
235- `GET /v1/tasks/:task_id/logs`
236- `GET /v1/runs/:run_id`
237
238目标：
239
240- 把 hand / shell 的本机能力和异步任务体验统一进 `baa-conductor`
241
242当前状态：
243
244- `POST /v1/exec`
245- `POST /v1/files/read`
246- `POST /v1/files/write`
247
248已经在本地 `conductor-daemon` 上线；`POST /v1/tasks` 和详情类接口仍按原计划推进。
249
250### 第四批（当前主线已完成）
251
252- 浏览器、CLI、运维脚本和文档默认目标已经切到 `conductor.makefile.so`
253- `control-api.makefile.so`、Cloudflare Worker、D1 与 public `status-api` 即使仍有线上残留，也不再承担默认控制面角色
254
255## 9. 删旧范围
256
257cutover 完成后，优先删除或归档：
258
259- 把 `control-api.makefile.so` 写成主业务接口的所有当前时态描述
260- Cloudflare Worker / D1 的默认控制面角色
261- `status-api` 的公网职责
262- `baa-hand` / `baa-shell` 作为主系统的维护承诺
263- 运行文档和 launchd 模板中默认把 `BAA_CONTROL_API_BASE` 当真相源的口径
264
265## 10. 文档与使用方式
266
267迁移完成后，所有新对话都应该遵循这个使用方式：
268
2691. 先调 `GET /describe`
2702. 再看 `GET /v1/capabilities`
2713. 只读查询：
272 - `GET /v1/system/state`
273 - `GET /v1/tasks`
274 - `GET /v1/runs`
2754. 需要真正操作时，再调写接口：
276 - `POST /v1/system/pause`
277 - `POST /v1/system/resume`
278 - `POST /v1/exec`
279 - `POST /v1/files/read`
280 - `POST /v1/files/write`
281 - `POST /v1/tasks`
282
283## 11. 当前结论
284
285这次迁移的目标不是“把 hand/shell 保留成旧子系统”，而是：
286
287- 让 `baa-conductor` 成为唯一主项目
288- 让外部 HTTP 交互方式继续保持简单
289- 让 Claude / 手机网页 / 浏览器都直接通过 `conductor.makefile.so` 和 `100.71.210.78:4317` 工作
290
291一句话：
292
293`baa-hand` / `baa-shell` 继续保留为参考样例，但业务控制接口和本机访问能力应该整体收口到 `baa-conductor` 的 local API。