baa-conductor

commit

5e7ea0f

parent

eb2b6b3

author

im_wower

date

2026-03-22 16:49:55 +0800 CST

Add hand and shell migration plan

  1@@ -0,0 +1,337 @@
  2+# BAA Hand / Shell 接口迁移方案
  3+
  4+日期：2026-03-22
  5+
  6+## 1. 目标
  7+
  8+把 `baa-hand` / `baa-shell` 已经验证可用的“HTTP 交互方式”整体迁移到 `baa-conductor`，由 `baa-conductor` 成为唯一对外服务面。
  9+
 10+本次迁移的重点不是复用旧代码，而是复用旧系统已经被验证过的交互经验：
 11+
 12+- 先 `GET /describe`
 13+- 再决定调用哪个接口
 14+- 支持只读查询
 15+- 支持同步小操作
 16+- 支持异步任务提交与结果查询
 17+
 18+## 2. 当前判断
 19+
 20+`baa-conductor` 已经具备承接接口层的内核条件：
 21+
 22+- `task`
 23+- `run`
 24+- `step`
 25+- `worker`
 26+- `checkpoint`
 27+- `logging`
 28+- `control-api`
 29+- `status-api`
 30+- `mini` 单节点自启动
 31+
 32+所以后续不再继续平行维护三套系统：
 33+
 34+- `baa-hand`
 35+- `baa-shell`
 36+- `baa-conductor`
 37+
 38+目标是：
 39+
 40+- `baa-hand` / `baa-shell` 只作为参考实现
 41+- `baa-conductor` 成为唯一主项目
 42+
 43+## 3. 迁移边界
 44+
 45+### 3.1 本次要迁
 46+
 47+- 自描述接口
 48+- 控制型接口
 49+- 非控制型只读接口
 50+- 本机执行能力
 51+- 文件访问能力
 52+- 异步任务接口
 53+- 任务 / run / log / report 查询
 54+
 55+### 3.2 本次不迁
 56+
 57+- AI 接口优先级降低
 58+- `POST /ask`
 59+- `POST /chat`
 60+- 多轮 AI 会话
 61+
 62+说明：
 63+
 64+当前先把“本机访问能力”和“业务控制接口”统一进 `baa-conductor`，AI 代理后续如仍需要，再单独设计。
 65+
 66+## 4. 设计原则
 67+
 68+### 4.1 不做兼容层
 69+
 70+不要为了兼容旧系统，把 `baa-hand` / `baa-shell` 的老实现直接搬进来。
 71+
 72+迁移的是：
 73+
 74+- 接口语义
 75+- 使用体验
 76+- 能力发现方式
 77+
 78+不是：
 79+
 80+- 旧代码结构
 81+- 旧内存状态机
 82+- 旧散装 server
 83+
 84+### 4.2 新接口围绕 `baa-conductor` 真实内核设计
 85+
 86+底层必须直接接入：
 87+
 88+- `control-api-worker`
 89+- `task/run/step`
 90+- `db`
 91+- `worker`
 92+- `logs/checkpoints`
 93+
 94+### 4.3 先读后写
 95+
 96+和 `baa-hand` / `baa-shell` 一样，建议约定：
 97+
 98+1. 先调 `GET /describe`
 99+2. 再调只读接口看当前状态
100+3. 最后才调写接口
101+
102+### 4.4 单节点优先
103+
104+当前项目已经收口为 `mini` 单节点，所以新接口文档和行为都以单节点为准，不再继续围绕主备切换设计。
105+
106+## 5. 新接口分层
107+
108+## 5.1 服务发现层
109+
110+### `GET /describe`
111+
112+用途：
113+
114+- 返回完整自描述 JSON
115+- 给 Claude / 手机网页 / 浏览器工具“先发现能力，再调用”
116+
117+建议内容：
118+
119+- `name`
120+- `version`
121+- `description`
122+- `deployment_mode`
123+- `auth_mode`
124+- `endpoints`
125+- `capabilities`
126+- `examples`
127+- `notes`
128+
129+### `GET /health`
130+
131+用途：
132+
133+- 最小健康检查
134+
135+### `GET /version`
136+
137+用途：
138+
139+- 返回版本信息
140+
141+## 5.2 控制层
142+
143+保留并继续使用：
144+
145+- `GET /v1/system/state`
146+- `POST /v1/system/pause`
147+- `POST /v1/system/resume`
148+- `POST /v1/system/drain`
149+
150+这是当前最稳定的公网控制入口。
151+
152+## 5.3 只读功能层
153+
154+建议统一成以下接口：
155+
156+- `GET /v1/capabilities`
157+- `GET /v1/controllers`
158+- `GET /v1/tasks`
159+- `GET /v1/tasks/:task_id`
160+- `GET /v1/tasks/:task_id/logs`
161+- `GET /v1/runs`
162+- `GET /v1/runs/:run_id`
163+
164+这些接口的目标不是控制，而是：
165+
166+- 看当前系统里有什么
167+- 看任务跑到哪里了
168+- 看最近执行过什么
169+- 看日志和结果
170+
171+## 5.4 本机能力层
172+
173+这层承接 `baa-shell` 的思路，但直接接入 `baa-conductor`：
174+
175+- `POST /v1/exec`
176+- `POST /v1/files/read`
177+- `POST /v1/files/write`
178+
179+建议行为：
180+
181+- 同步小操作
182+- 明确 cwd / timeout / path
183+- 返回结构化结果
184+
185+注意：
186+
187+这层属于“本机访问能力”，不是 control-plane 状态写入。
188+
189+## 5.5 异步任务层
190+
191+这层承接 `baa-shell /task` 的使用体验，但底层直接接 `baa-conductor` 的 task/run 模型：
192+
193+- `POST /v1/tasks`
194+- `GET /v1/tasks`
195+- `GET /v1/tasks/:task_id`
196+- `GET /v1/tasks/:task_id/logs`
197+- `GET /v1/runs`
198+- `GET /v1/runs/:run_id`
199+
200+说明：
201+
202+- 同步 `exec/read/write` 适合小操作
203+- 真正的长活、worker 编排、日志跟踪，应该走 task/run
204+
205+## 6. 旧接口到新接口的映射
206+
207+### 6.1 `baa-shell`
208+
209+| 旧接口 | 新接口方向 |
210+| --- | --- |
211+| `GET /describe` | `GET /describe` |
212+| `GET /health` | `GET /health` |
213+| `GET /version` | `GET /version` |
214+| `POST /exec` | `POST /v1/exec` |
215+| `POST /read` | `POST /v1/files/read` |
216+| `POST /write` | `POST /v1/files/write` |
217+| `POST /task` | `POST /v1/tasks` |
218+| `GET /task/:id` | `GET /v1/tasks/:task_id` |
219+| `GET /tasks` | `GET /v1/tasks` |
220+| `GET /reports` | 可拆成 `GET /v1/tasks/:task_id/logs` 或后续 `GET /v1/reports/:id` |
221+
222+### 6.2 `baa-hand`
223+
224+| 旧接口 | 新接口方向 |
225+| --- | --- |
226+| `GET /describe` | `GET /describe` |
227+| `POST /ask` | 暂缓，不是当前优先级 |
228+| `POST /chat` | 暂缓，不是当前优先级 |
229+| `POST /plan` | 长期可考虑转成 `POST /v1/tasks` + planner 策略 |
230+
231+## 7. 一次性迁移后的推荐接口面
232+
233+对外推荐只保留一套：
234+
235+### 服务发现
236+
237+- `GET /describe`
238+- `GET /health`
239+- `GET /version`
240+- `GET /v1/capabilities`
241+
242+### 控制
243+
244+- `GET /v1/system/state`
245+- `POST /v1/system/pause`
246+- `POST /v1/system/resume`
247+- `POST /v1/system/drain`
248+
249+### 查询
250+
251+- `GET /v1/controllers`
252+- `GET /v1/tasks`
253+- `GET /v1/tasks/:task_id`
254+- `GET /v1/tasks/:task_id/logs`
255+- `GET /v1/runs`
256+- `GET /v1/runs/:run_id`
257+
258+### 本机能力
259+
260+- `POST /v1/exec`
261+- `POST /v1/files/read`
262+- `POST /v1/files/write`
263+
264+### 异步任务
265+
266+- `POST /v1/tasks`
267+
268+## 8. 实施顺序
269+
270+### 第一批
271+
272+- `GET /describe`
273+- `GET /health`
274+- `GET /version`
275+- `GET /v1/capabilities`
276+- `GET /v1/tasks`
277+- `GET /v1/runs`
278+- `GET /v1/controllers`
279+
280+目标：
281+
282+- 让 Claude 能先发现能力
283+- 让 Claude 能先读状态和列表
284+
285+### 第二批
286+
287+- `POST /v1/exec`
288+- `POST /v1/files/read`
289+- `POST /v1/files/write`
290+
291+目标：
292+
293+- 把 `shell` 的本机能力迁进来
294+
295+### 第三批
296+
297+- `POST /v1/tasks`
298+- `GET /v1/tasks/:task_id`
299+- `GET /v1/tasks/:task_id/logs`
300+- `GET /v1/runs/:run_id`
301+
302+目标：
303+
304+- 把异步任务体验统一进 `baa-conductor`
305+
306+### 第四批
307+
308+- 如仍然有需要，再考虑 AI 代理接口
309+
310+## 9. 文档与使用方式
311+
312+迁移完成后，所有新对话都应该遵循这个使用方式：
313+
314+1. 先调 `GET /describe`
315+2. 再看 `GET /v1/capabilities`
316+3. 只读查询：
317+   - `GET /v1/system/state`
318+   - `GET /v1/tasks`
319+   - `GET /v1/runs`
320+4. 需要真正操作时，再调写接口：
321+   - `POST /v1/system/pause`
322+   - `POST /v1/system/resume`
323+   - `POST /v1/exec`
324+   - `POST /v1/files/read`
325+   - `POST /v1/files/write`
326+   - `POST /v1/tasks`
327+
328+## 10. 当前结论
329+
330+这次迁移的目标不是“把 hand/shell 保留成旧子系统”，而是：
331+
332+- 让 `baa-conductor` 成为唯一主项目
333+- 让外部 HTTP 交互方式继续保持简单
334+- 让 Claude / 手机网页 / 浏览器都能直接通过统一域名和统一接口工作
335+
336+一句话：
337+
338+`baa-hand` / `baa-shell` 继续保留为参考样例，但业务控制接口和本机访问能力应该整体收口到 `baa-conductor`。