im_wower
·
2026-03-28
T-S021.md
1# Task T-S021：收口 conductor describe 与通用 browser HTTP 合同
2
3## 直接给对话的提示词
4
5读 `/Users/george/code/baa-conductor/tasks/archive/T-S021.md` 任务文档，完成开发任务。
6
7如需补背景，再读：
8
9- `/Users/george/code/baa-conductor/plans/archive/FIREFOX_BRIDGE_CONTROL_REQUIREMENTS.md`
10- `/Users/george/code/baa-conductor/plans/archive/BROWSER_BRIDGE_PERSISTENCE_REQUIREMENTS.md`
11- `/Users/george/code/baa-conductor/plans/discuss/DISCUSS-FIREFOX-BRIDGE-CONTROL.md`
12- `/Users/george/code/baa-conductor/docs/api/README.md`
13- `/Users/george/code/baa-conductor/docs/api/business-interfaces.md`
14- `/Users/george/code/baa-conductor/docs/api/control-interfaces.md`
15- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/local-api.ts`
16
17## 当前基线
18
19- 仓库：`/Users/george/code/baa-conductor`
20- 分支：`main`
21- 提交：`0f218b9`
22- 开工要求：如需新分支，从当前 `main` 新切
23
24## 当前状态
25
26- `已完成`
27
28## 建议分支名
29
30- `feat/browser-agent-surface`
31
32## 目标
33
34把 `conductor` 的 AI 调用面收口成稳定的两层 describe，并定义通用 browser HTTP 合同，同时保留现有 Claude 专用路径兼容。
35
36## 背景
37
38当前 `conductor` 已有：
39
40- `/describe`
41- `/describe/business`
42- `/describe/control`
43- `/v1/browser/claude/*`
44
45但浏览器能力仍偏 Claude 专用路径，通用 browser 请求和插件管理能力还没有正式并入现有两层 describe。
46
47本任务不新增第三层 `browser describe`，而是把浏览器能力并入现有：
48
49- `business`
50- `control`
51
52## 涉及仓库
53
54- `/Users/george/code/baa-conductor`
55
56## 范围
57
58- 收口 `/describe`、`/describe/business`、`/describe/control`
59- 为通用 browser 接口定义稳定 HTTP 合同
60- 保留现有 `/v1/browser/claude/*` 兼容位次
61- 更新对应 API 文档和最小测试
62
63## 路径约束
64
65- 不新增 `/describe/browser`
66- 不新增 `/describe/plugin`
67- `GET /describe` 只保留为入口索引
68- 通用 browser 路由以：
69 - `GET /v1/browser`
70 - `POST /v1/browser/actions`
71 - `POST /v1/browser/request`
72 - `POST /v1/browser/request/cancel`
73 为目标模型
74
75## 推荐实现边界
76
77建议优先做：
78
79- `local-api.ts` 路由定义与 describe 输出
80- `docs/api/*` 的正式合同更新
81- 现有 Claude 专用接口到通用接口的 legacy 标记
82- 最小 route / describe 测试
83
84## 允许修改的目录
85
86- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/`
87- `/Users/george/code/baa-conductor/docs/api/`
88- `/Users/george/code/baa-conductor/tests/`
89
90## 尽量不要修改
91
92- `/Users/george/code/baa-conductor/plugins/baa-firefox/`
93- `/Users/george/code/baa-conductor/packages/db/`
94- `/Users/george/code/baa-conductor/README.md`
95- `/Users/george/code/baa-conductor/docs/firefox/`
96
97## 必须完成
98
99### 1. 收口 describe 分层
100
101- 保持 `conductor` 只有：
102 - `/describe`
103 - `/describe/business`
104 - `/describe/control`
105- `/describe/business` 要纳入浏览器功能类能力
106- `/describe/control` 要纳入插件管理类能力
107
108### 2. 定义通用 browser HTTP 合同
109
110- 增加或明确通用 browser 路由合同：
111 - `POST /v1/browser/actions`
112 - `POST /v1/browser/request`
113 - `POST /v1/browser/request/cancel`
114- 路由命名、参数约束、错误语义要写进 describe 或 API 文档
115
116### 3. 保持兼容与最小验证
117
118- 现有 `/v1/browser/claude/open`
119- 现有 `/v1/browser/claude/send`
120- 现有 `/v1/browser/claude/current`
121- 现有 `/v1/browser/claude/reload`
122
123这些路径要继续可用，并标记为 legacy 包装层或过渡路径。
124
125## 需要特别注意
126
127- 不要把插件 WS bridge message 直接暴露成 AI-facing describe 主模型
128- 不要在这个任务里顺手实现整套 SSE 执行链路
129- 浏览器功能类归 `business`，插件管理类归 `control`
130- 与并行任务边界：
131 - 本任务不负责 Firefox 插件 runtime 细节
132 - 本任务不负责浏览器侧 SSE 执行实现
133
134## 验收标准
135
136- `conductor` 的 describe 模型只剩两层：`business/control`
137- 通用 browser HTTP 合同在代码和文档中存在
138- Claude 专用路径仍然可用
139- 相关 describe / route 测试通过
140- `git diff --check` 通过
141
142## 推荐验证命令
143
144- `node --test /Users/george/code/baa-conductor/apps/conductor-daemon/src/index.test.js`
145- `pnpm -C /Users/george/code/baa-conductor -F @baa-conductor/conductor-daemon build`
146- `git -C /Users/george/code/baa-conductor diff --check`
147
148## 交付要求
149
150完成后请说明：
151
152- 调整了哪些 route 和 describe 输出
153- 通用 browser HTTP 合同最终如何命名
154- 现有 Claude 路径如何兼容
155- 跑了哪些验证
156- 还有哪些剩余风险
157
158## 最新接力说明
159
160- 本任务已完成，`conductor` 的浏览器能力发现继续收口到 `business` / `control` 两层 describe。
161- 当前剩余集成工作已经转入：
162 - `/Users/george/code/baa-conductor/tasks/archive/T-S023.md`
163 - `/Users/george/code/baa-conductor/tasks/archive/T-S024.md`
164
165## 当前残余风险
166
167- `conductor` 目前还不会消费新增的 `shell_runtime` 字段。
168- 正式的插件管理动作回执合同还未完全收口；插件侧 runtime 和 payload 已准备好，后续由服务端接入。