baa-conductor

BAA_INSTRUCTION_SYSTEM.md

  1# BAA 指令系统（当前正式合同）
  2
  3日期：`2026-04-01`
  4
  5> 这份文档只描述 `main` 当前已经成立的正式合同。未来目标、扩展 target 和远期编排，统一移到 [`./BAA_INSTRUCTION_ROADMAP.md`](./BAA_INSTRUCTION_ROADMAP.md)。
  6
  7## 状态
  8
  9- `当前正式合同`
 10- 当前主分支：`main@b8d69c8`
 11- canonical local API：`http://100.71.210.78:4317`
 12- canonical public host：`https://conductor.makefile.so`
 13
 14## 关联文档
 15
 16- [`./STATUS_SUMMARY.md`](./STATUS_SUMMARY.md)
 17- [`./BAA_INSTRUCTION_ROADMAP.md`](./BAA_INSTRUCTION_ROADMAP.md)
 18- [`./archive/BAA_BROWSER_PROXY_DELIVERY_REQUIREMENTS.md`](./archive/BAA_BROWSER_PROXY_DELIVERY_REQUIREMENTS.md)
 19- [`../docs/AI_BAA_QUICKSTART.md`](../docs/AI_BAA_QUICKSTART.md)
 20
 21## 1. 当前范围
 22
 23当前 `main` 里，BAA 指令系统已经收口到这条主链：
 24
 25- AI 页面输出 ` ```baa ` 代码块
 26- Firefox 插件把最终回复转成 `browser.final_message`
 27- conductor 负责提取、解析、去重、权限校验、执行和结果回写
 28- 回写主链是 proxy-first：
 29  - 优先 `browser.proxy_delivery`
 30  - 失败时才退回 DOM `inject / send`
 31
 32职责边界固定如下：
 33
 34- conductor：唯一解释中心、唯一路由真相源、唯一审计点
 35- 插件：观察最终回复、在 page context 执行真实请求、必要时做最小 fallback
 36
 37## 2. 语法合同
 38
 39### 2.1 一个代码块 = 一条指令
 40
 41一个 ` ```baa ``` ` 代码块只表示一条指令。多条独立指令用多个代码块表示，默认并行。
 42
 43### 2.2 基本格式
 44
 45```text
 46@target::tool::params
 47```
 48
 49### 2.3 当前支持的参数形式
 50
 51- 单行字符串参数
 52- 单行 JSON 参数
 53- 多行参数
 54- 无参数
 55
 56示例：
 57
 58```baa
 59@conductor::exec::pwd
 60```
 61
 62```baa
 63@conductor::files/read::{"path":"README.md"}
 64```
 65
 66```baa
 67@conductor::exec
 68cd .
 69git status
 70```
 71
 72### 2.4 当前解析规则
 73
 74- 只解析最终权威消息，不在 streaming 半截文本上执行
 75- 只解析 ` ```baa ` 代码块，不执行普通代码块
 76- 每个 block 独立去重
 77
 78## 3. 当前正式 target
 79
 80| target | 状态 | 说明 |
 81|---|---|---|
 82| `conductor` | 正式支持 | 本机 conductor API |
 83| `system` | 正式支持 | `conductor` 的别名视角 |
 84| `browser.claude` | 正式支持 | 正式 browser target |
 85| `browser.chatgpt` | 正式支持 | 正式 browser target |
 86| `browser.gemini` | 正式支持 | 正式 browser target |
 87| `codex` / `node.*` / `pool.*` / `role.*` | 未放开 | 仍在路线图 |
 88
 89## 4. 当前正式 tool 面
 90
 91### 4.1 `@conductor` / `@system`
 92
 93当前正式支持：
 94
 95- `describe`
 96- `describe/business`
 97- `describe/control`
 98- `status`
 99- `exec`
100- `files/read`
101- `files/write`
102- `browser/status`
103- `browser/actions`
104
105### 4.2 `@browser.claude` / `@browser.chatgpt` / `@browser.gemini`
106
107当前正式支持：
108
109- `send`
110- `current`
111
112说明：
113
114- `browser.request` 是浏览器桥接的底层正式能力
115- 但对 AI 暴露成 BAA 指令时，当前正式放开的 browser target 只有：
116  - `browser.claude`
117  - `browser.chatgpt`
118  - `browser.gemini`
119
120## 5. 当前 ingress / delivery 合同
121
122### 5.1 ingress
123
124当前三个页面平台都可作为 `browser.final_message` 的来源：
125
126- `ChatGPT`
127- `Claude`
128- `Gemini`
129
130这表示它们既能把最终回复送进 conductor 的 ingest 主链，也已经成为当前正式 BAA browser target。
131
132### 5.2 delivery
133
134当前正式 delivery 合同如下：
135
136- conductor 记录最近观察到的 conversation / page route
137- 回写优先走 `browser.proxy_delivery`
138- 插件只在目标页面上下文里执行真实请求
139- DOM `browser.inject_message` / `browser.send_message` 只保留为 fallback
140
141### 5.3 成功语义
142
143当前 `proxy_delivery` 的成功语义是：
144
145- 请求已经成功派发到目标页面上下文
146
147当前不保证：
148
149- 下游 AI 已经完整回复
150- 平台已经把这一轮响应持久写回业务线程
151
152## 6. 当前明确不包含
153
154下面这些不属于当前正式合同：
155
156- upload / download / binary delivery
157- artifact / manifest / upload receipt 方案
158- 多客户端、多节点 orchestrator
159- `pool.*` / `role.*` 能力池和角色池
160- `codex` / `node.*` 的完整路由协议
161- 任务池与后台长流程
162
163## 7. 当前已知边界
164
165- `Gemini` 当前仍不是 `/v1/browser/request` 的正式 raw relay 支持面；`@browser.gemini` 走 helper / proxy mix
166- ChatGPT proxy send 仍依赖最近捕获的真实发送模板；冷启动时可能退回 DOM fallback
167- Claude 的 `organizationId` 仍依赖最近观测到的 org 上下文
168- relay / dedupe / delivery 仍主要服务于单节点主线
169
170## 8. 当前最小示例
171
172### 本机执行
173
174```baa
175@conductor::exec::pwd
176```
177
178### 读文件
179
180```baa
181@conductor::files/read::{"path":"README.md"}
182```
183
184### Claude browser target
185
186```baa
187@browser.claude::send::请总结上一轮执行结果
188```
189
190### ChatGPT browser target
191
192```baa
193@browser.chatgpt::send::请总结上一轮执行结果
194```
195
196### Gemini browser target
197
198```baa
199@browser.gemini::send::请总结上一轮执行结果
200```
201
202## 9. 设计分层
203
204当前应按下面这组文档理解：
205
206- [`./BAA_INSTRUCTION_SYSTEM.md`](./BAA_INSTRUCTION_SYSTEM.md)：当前正式合同
207- [`./BAA_INSTRUCTION_ROADMAP.md`](./BAA_INSTRUCTION_ROADMAP.md)：未来目标与扩展方向
208- [`./STATUS_SUMMARY.md`](./STATUS_SUMMARY.md)：当前主线状态与优先级
209- [`./archive/BAA_BROWSER_PROXY_DELIVERY_REQUIREMENTS.md`](./archive/BAA_BROWSER_PROXY_DELIVERY_REQUIREMENTS.md)：本轮 proxy-first delivery 收口记录