baa-conductor

BAA_INSTRUCTION_CENTER_REQUIREMENTS.md

  1# BAA 指令解析中心与最小执行闭环需求
  2
  3## 状态
  4
  5- `已实现 Phase 1 最小闭环（2026-03-27，对应 T-S030）`
  6- 优先级：`high`
  7- 记录时间：`2026-03-27`
  8
  9## 关联文档
 10
 11- [BAA_INSTRUCTION_SYSTEM.md](/Users/george/code/baa-conductor/plans/BAA_INSTRUCTION_SYSTEM.md)
 12- [BAA_BROWSER_FINAL_MESSAGE_RELAY_REQUIREMENTS.md](/Users/george/code/baa-conductor/plans/archive/BAA_BROWSER_FINAL_MESSAGE_RELAY_REQUIREMENTS.md)
 13- [README.md](/Users/george/code/baa-conductor/docs/baa-instruction-system-v5/README.md)
 14- [02-protocol-spec.md](/Users/george/code/baa-conductor/docs/baa-instruction-system-v5/docs/02-protocol-spec.md)
 15- [04-execution-loop-state-machine.md](/Users/george/code/baa-conductor/docs/baa-instruction-system-v5/docs/04-execution-loop-state-machine.md)
 16- [06-integration-with-current-baa-conductor.md](/Users/george/code/baa-conductor/docs/baa-instruction-system-v5/docs/06-integration-with-current-baa-conductor.md)
 17
 18## 背景
 19
 20`BAA_INSTRUCTION_SYSTEM.md` 已经把总模型定义清楚了：
 21
 22- ` ```baa ` 一块一指令
 23- `@target::tool::params`
 24- conductor 是唯一解释中心
 25- 插件不解析 BAA
 26
 27现在缺的不是继续讨论语法，而是把这套模型拆成当前 repo 可执行的第一阶段工程需求：
 28
 29- 从完整 assistant message 中提取 ` ```baa `
 30- 解析为标准化指令
 31- 做去重、权限和最小路由
 32- 先跑通最小执行闭环
 33
 34## 核心结论
 35
 36- 语法层直接冻结在 v3 / v5 当前定义，不再反复改格式
 37- parser / normalize / dedupe / policy / router / executor 全部放进 conductor
 38- 首版只消费“完整最终消息文本”，不依赖 streaming 中间态
 39- 首版先做精确 target，不做 `pool.*` / `role.*`
 40- 首版先做最小工具集，不把 artifact / upload barrier 一次性塞进同一任务
 41
 42## 已落地结果
 43
 44### conductor 侧模块
 45
 46已新增：
 47
 48```text
 49apps/conductor-daemon/src/instructions/
 50  extract.ts
 51  parse.ts
 52  normalize.ts
 53  dedupe.ts
 54  policy.ts
 55  router.ts
 56  executor.ts
 57  loop.ts
 58```
 59
 60并从 `apps/conductor-daemon/src/index.ts` 统一导出，方便后续把浏览器 `final_message` relay 直接接到同一套核心逻辑。
 61
 62### 当前已覆盖能力
 63
 64- 只提取 ` ```baa `，普通代码块忽略
 65- 四种参数形式全部可解析：
 66  - 单行字符串
 67  - 单行 JSON
 68  - 多行 body
 69  - 无参数
 70- 标准化 envelope 内保留最小可审计字段，并生成稳定 `dedupe_key`
 71- 当前精确 target 只允许：
 72  - `conductor`
 73  - `system`
 74- 当前最小工具集已打通：
 75  - `@conductor::describe`
 76  - `@conductor::status`
 77  - `@conductor::exec`
 78  - `@conductor::files/read`
 79  - `@conductor::files/write`
 80
 81### 当前验证方式
 82
 83- 单元测试覆盖提取、解析、normalize、dedupe 稳定性
 84- conductor 侧集成测试使用 synthetic complete assistant text 驱动最小执行闭环
 85- 同一条 assistant message replay 时会被 dedupe，避免重复执行
 86- 任一指令在 policy / route 阶段失败时，整批 fail-closed，不会半解析半执行
 87
 88## 首版范围
 89
 90### 输入
 91
 92- 完整 assistant message 文本
 93- 最小上下文：
 94  - `platform`
 95  - `conversation_id`
 96  - `assistant_message_id` 或等价 dedupe 字段
 97
 98### 语法与解析
 99
100- 提取 ` ```baa ` 代码块
101- 支持四种参数形式：
102  - 单行字符串
103  - 单行 JSON
104  - 多行 body
105  - 无参数
106- 忽略普通代码块
107- 一块一指令，多块并行语义
108
109### 标准化与去重
110
111- 生成标准化 instruction envelope
112- 生成稳定 dedupe key
113- 明确 block index、message identity、target、tool、params
114- 失败必须 fail-closed，不允许“半解析半执行”
115
116### 最小执行闭环
117
118首版建议先支持：
119
120- `@conductor::describe`
121- `@conductor::status`
122- `@conductor::exec`
123- `@conductor::files/read`
124- `@conductor::files/write`
125
126### 当前明确不要求
127
128- 不要求首版就接 `@browser.*::send`
129- 不要求首版就做 artifact upload / download
130- 不要求首版就做 `pool.*` / `role.*`
131- 不要求首版就做多轮 gossip / consensus / task pool
132
133## conductor 侧模块建议
134
135建议优先新增：
136
137```text
138apps/conductor-daemon/src/instructions/
139  extract.ts
140  parse.ts
141  normalize.ts
142  dedupe.ts
143  policy.ts
144  router.ts
145  executor.ts
146  loop.ts
147```
148
149## 路由与执行边界
150
151### 路由原则
152
153- 先只做精确 target：
154  - `conductor`
155  - `system`
156- `browser.chatgpt` / `browser.gemini` 的真正业务执行留给后续阶段
157
158### 执行原则
159
160- 优先复用当前 `conductor-daemon` 已有能力
161- 不要再实现一套平行 shell / file 执行器
162- executor 只负责把标准化指令映射到现有能力入口
163
164## 明确不做
165
166- 不在插件里放 parser
167- 不在本需求里要求 ChatGPT / Gemini 页面拦截完工；那是平行方向
168- 不在本需求里强行完成最终注入、上传确认、artifact barrier
169- 不把语法讨论重新打开成新一轮格式设计
170
171## 与平行任务的关系
172
173- `T-S029` 负责浏览器最终消息 raw relay
174- 本需求负责 conductor 侧 instruction center
175- 为了并行推进，本需求必须允许先用 synthetic message / fixture 跑通，而不阻塞于浏览器端最终消息中继
176
177## 刻意留到下一阶段
178
179- 浏览器 `final_message` 真实 relay 接线仍由 `T-S029` 收口
180- artifact materialization / manifest / upload receipt / delivery plan 仍未并入本阶段
181- `pool.*` / `role.*` 逻辑路由和多节点分发仍未开启
182- browser / codex / node.* 等非本机 target 仍未接入本轮 executor
183
184## 验收条件
185
186- parser 能稳定提取 ` ```baa `，并忽略普通代码块
187- 四种参数形式都有自动化测试
188- dedupe key 稳定且可解释
189- 最小工具集能通过标准化指令跑通执行闭环
190- 插件侧仍没有 parser 逻辑
191- 文档已同步到 `plans/`、`tasks/` 和必要的 `docs/baa-instruction-system-v5/`
192
193## 当前残余边界
194
195- dedupe 当前已做成单节点本地持久化，进程重启后可恢复，但不做跨节点共享
196- 当前只做本机精确 target，跨节点分发和多轮闭环还没接
197- 当前 Firefox bridge live `browser.final_message` 已接入 instruction center，最近摘要也已落到 bounded journal；但 journal 只保留最近窗口
198- 当前 live 路径已把执行结果接到 artifact / upload / inject / send，但还没有扩到跨节点或完整 task/run 编排