From 44bc019da484f3b922acd1a639421796b81d0915 Mon Sep 17 00:00:00 2001 From: cfdaily Date: Sat, 30 May 2026 23:03:36 +0800 Subject: [PATCH] auto-sync: 2026-05-30 23:03:36 --- docs/design/05-context-layers.md | 632 +++++++++++++++++++++++++++++++ 1 file changed, 632 insertions(+) create mode 100644 docs/design/05-context-layers.md diff --git a/docs/design/05-context-layers.md b/docs/design/05-context-layers.md new file mode 100644 index 0000000..789448f --- /dev/null +++ b/docs/design/05-context-layers.md @@ -0,0 +1,632 @@ +# #05 上下文四层架构 — 现状分析与改造方案 + +> 版本: v1.0 +> 日期: 2026-05-30 +> 作者: 庞统（副军师） +> 状态: 设计中 +> 前置: #02 Main Session + Delegation, #03 Prompt 进化, #04 黑板协作模型 + +--- + +## 一、四层架构定义 + +Agent 收到的完整上下文由四个独立层叠加而成。每层有不同的注入时机、职责边界和变更频率。 + +``` +┌──────────────────────────────────────────────────────────┐ +│ L1 Workspace 层（Gateway 自动注入） │ +│ 时机：每次 turn 的 system prompt │ +│ 来源：Agent workspace 目录下的 .md 文件 │ +│ 职责：我是谁、我擅长什么、团队规则、怎么协作 │ +│ 频率：低频变更（人格/角色/规则稳定后基本不动） │ +├──────────────────────────────────────────────────────────┤ +│ L2 Hook 层（Gateway Plugin 注入） │ +│ 时机：每次 turn 的 user message 前（prependContext） │ +│ 来源：gate-enforcer plugin │ +│ 职责：安全铁律 + 执行策略底线 │ +│ 频率：极低频变更（铁律级，不改则不变） │ +├──────────────────────────────────────────────────────────┤ +│ L3 Daemon 投递层（moziplus 构建的 message） │ +│ 时机：Daemon spawn Agent 时 │ +│ 来源：ticker/dispatcher 的 prompt 模板 │ +│ 职责：这次具体要做什么 + 能用什么 API + 约束 │ +│ 频率：每次投递不同（任务信息变化） │ +├──────────────────────────────────────────────────────────┤ +│ L4 Bootstrap 层（结构化上下文增强） │ +│ 时机：Daemon spawn Agent 时，拼接到 L3 message 中 │ +│ 来源：BootstrapBuilder + prompt_templates + 经验 + 知识 │ +│ 职责：角色模板 + 前序产出 + Guardrail + 审查协议 + 经验 │ +│ 频率：中频（按任务类型/角色动态拼装） │ +└──────────────────────────────────────────────────────────┘ +``` + +### 各层原则 + +| 原则 | 说明 | +|------|------| +| **不重复** | 同一信息只在一层注入，不在多层重复 | +| **职责单一** | 每层只负责自己的事，不越界 | +| **身份归 L1** | Agent 的"我是谁"由 Workspace 决定，不是 Daemon 告诉它 | +| **安全归 L2** | 铁律级约束由 Hook 保证，不依赖 Daemon prompt | +| **任务归 L3** | Daemon 只传任务信息和 API 能力，不教 Agent 怎么做 | +| **增强归 L4** | 动态上下文（经验/知识/审查协议）由 Bootstrap 拼装 | + +--- + +## 二、L1 Workspace 层 — 现状与改造 + +### 2.1 现状 + +**文件结构**（每个 Agent 的 workspace 目录）： + +| 文件 | 当前内容 | 问题 | +|------|---------|------| +| SOUL.md | 人格 + 核心信条 + 底线 | ✅ 合理，但**缺少专长声明** | +| AGENTS.md | 团队配置 + 沟通方式 + 编排纪律 | ⚠️ **缺少黑板使用教程**、内容是 v1 mozi 时代的 | +| MEMORY.md | 长期记忆 | ✅ 合理 | +| TOOLS.md | 工具配置 | ⚠️ **缺少黑板 API 参考** | +| HEARTBEAT.md | 当前工作状态 | ✅ 合理 | +| USER.md | 用户信息 | ✅ 合理 | +| IDENTITY.md | 身份元数据 | ⚠️ 空模板，未填 | + +**各 Agent 的 SOUL.md 差异**： +- 张飞：编码先锋，豪爽直率 ✅ +- 司马懿：质量总监，深沉狡诈 ✅ +- 其他 Agent：类似结构 ✅ + +**关键缺失**： +1. **Agent 不知道自己的专长列表** — SOUL.md 说了"我是谁"但没说"我擅长什么" +2. **Agent 不知道怎么用黑板** — AGENTS.md 有 Mail 使用教程但没有黑板操作教程 +3. **Agent 不知道协作规则** — 怎么 @ 别人、怎么讨论、什么时候该问问题 +4. **AGENTS.md 还是 v1 编排纪律** — 写的是 mozi 的 `cli.py` 命令，不是 v2 黑板 API + +### 2.2 改造方案 + +#### SOUL.md 改造 + +在"我是谁"段落后新增**专长声明**段： + +```markdown +## 我的专长 +- ✅ 擅长：编码、实现、回测脚本、策略编码 +- ❌ 不擅长：风控审核（找关羽）、数据获取（找赵云）、部署（找姜维） + +只认领和执行符合专长的任务，不适合的不要抢。 +``` + +**每个 Agent 的专长声明**： + +| Agent | 擅长 | 不擅长 | +|-------|------|--------| +| zhangfei-dev | 编码、实现、脚本、策略编码 | 风控、数据、部署 | +| guanyu-dev | 风控、合规、仓位检查 | 编码实现、数据获取 | +| zhaoyun-data | 数据获取、清洗、验证 | 编码实现、风控 | +| jiangwei-infra | 部署、Docker、vnpy、NAS | 策略编码、风控 | +| simayi-challenger | 审查、质量检查、辩论 | 数据获取、部署 | +| pangtong-fujunshi | 规划、协调、策略研究 | 不执行具体编码 | + +#### AGENTS.md 改造 + +移除 v1 编排纪律（`cli.py`、mozi daemon 相关），替换为 **v2 黑板协作指南**： + +```markdown +## 黑板协作（moziplus v2） + +黑板是你的工作空间。所有任务、讨论、产出都在黑板上。 + +### 你能做什么 +- 读任务详情: GET http://localhost:8083/api/projects/{pid}/tasks/{id}?expand=all +- 读活跃任务: GET http://localhost:8083/api/projects/{pid}/tasks?status=working,claimed,review +- 认领任务: POST .../tasks/{id}/claim body: {"agent": "你的id"} +- 更新状态: POST .../tasks/{id}/status body: {"status": "working", "agent": "你的id"} +- 写产出: POST .../tasks/{id}/outputs body: {"agent": "你的id", "content_type": "code", ...} +- 写评论: POST .../tasks/{id}/comments body: {"author": "你的id", "body": "..."} +- 创建子任务: POST .../tasks body: {"title": "...", "parent_task": "父任务id", ...} + +### 协作规则 +1. **讨论用 comment** — 有疑问、要讨论、给反馈，写在黑板 comment 里 +2. **@ 别人协作** — comment 中提到 @zhangfei-dev 会自动通知对方 +3. **不懂就问** — 任务描述不清、验收标准模糊、上下文不够，先在黑板 comment 提问，不要猜 +4. **写交接** — 完成任务时写 comment_type=handoff，告诉下一个人你做了什么 +5. **产出物 > 消息** — 产出写在 output 里，不只是 comment + +### 状态流转 +pending → claimed → working → review → done + ↘ failed + +### 对应 Skill +- 非平凡编码任务 → plan-act-verify skill +- 代码审查 → code-review skill +- 数据获取 → data-acquisition skill +- 部署 → deployment-infra skill +- 调研分析 → 先出方案等确认 +``` + +#### TOOLS.md 改造 + +新增黑板 API 速查段： + +```markdown +## 黑板 API（moziplus v2） +- 端口: 8083 +- 前端: http://localhost:8083/ +- API Base: http://localhost:8083/api +- 项目 ID: 通过任务消息中的 project_id 获取 +``` + +### 2.3 文件变更清单 + +| Agent | SOUL.md | AGENTS.md | TOOLS.md | +|-------|---------|-----------|----------| +| zhangfei-dev | +专长段 | 重写 | +黑板API | +| guanyu-dev | +专长段 | 重写 | +黑板API | +| zhaoyun-data | +专长段 | 重写 | +黑板API | +| jiangwei-infra | +专长段 | 重写（已有定制版） | +黑板API | +| simayi-challenger | +专长段 | 重写 | +黑板API | +| pangtong-fujunshi | +专长段 | 重写 | +黑板API | + +--- + +## 三、L2 Hook 层 — 现状与改造 + +### 3.1 现状 + +**gate-enforcer plugin**（`~/.openclaw/node_modules/gate-enforcer/index.js`） + +两个 hook： + +| Hook | 注入内容 | 注入方式 | 问题 | +|------|---------|---------|------| +| `before_prompt_build` | `` + `` | prependContext | ✅ 合理 | +| `before_tool_call` | ``（GATE 未通过时） | prependContext | ✅ 合理 | + +**GATE_RULES 内容**： +``` +GATE 门控铁律（L2/L3 非平凡任务必遵守）： +1. 需求不清不动手 +2. 根因不明不修复 +3. 方案未定不实现 +4. 评估过影响范围才动手 +5. 涉及代码改动或调研分析的非平凡任务，使用 plan-act-verify skill +L1 小改动可跳过。 +``` + +**DELEGATION_RULE 内容**： +``` +收到 moziplus 投递的编码/文档/调研等独立任务时，优先使用 subagent-delegation skill +``` + +### 3.2 改造方案 + +L2 层是铁律级约束，改造极小——**只调内容，不改机制**。 + +#### 改造 1：GATE_RULES 保持不变 + +GATE 五条铁律经过实践验证，不需要改。 + +#### 改造 2：DELEGATION_RULE 适配 Main Session + +当前写的是"使用 subagent-delegation skill"，但 #02 改造后 Agent 已在 main session， delegation 逻辑应该更智能： + +``` + +收到 moziplus 投递的独立任务时： +- 如果是编码/文档/调研等重活 → sessions_spawn(subagent, cleanup:"delete") +- 如果只需决策或确认 → 直接做 +- 如果需要其他人协作 → 黑板 comment @ 对应 Agent +- 如果不懂 → 先在黑板提问，不要猜 + +``` + +#### 改造 3：注入方式保持不变 + +`prependContext` 注入到 user message 前，这个机制没问题。不改。 + +### 3.3 改动量 + +- gate-enforcer `index.js`：修改 DELEGATION_RULE 内容（~5 行） +- 不改 hook 机制、不改注入方式 + +--- + +## 四、L3 Daemon 投递层 — 现状与改造 + +### 4.1 现状 + +**6 种 prompt 模板**，分散在 3 个文件中： + +| 模板 | 文件 | 行为 | 问题 | +|------|------|------|------| +| SPAWN_PROMPT_TEMPLATE | spawner.py | 固定4步骤 + curl 指令 | ❌ 太死板，重复注入身份 | +| CLAIM_PROMPT | ticker.py `_build_claim_prompt` | 身份注入 + 任务列表 + 步骤 | ❌ 身份不应由 Daemon 注入 | +| MENTION_PROMPT | ticker.py `_build_mention_prompt` | 身份注入 + @信息 + 步骤 | ❌ 身份不应由 Daemon 注入 | +| REVIEW_PROMPT | ticker.py `_build_review_prompt` | 三问框架 + 状态汇总 | ⚠️ 只给庞统，缺司马懿版 | +| DELEGATE_PROMPT | dispatcher.py | 团队列表让庞统选 | ✅ 合理，小改 | +| MAIL_RETRY_PROMPT | spawner.py | 续杯提醒 | ✅ 合理 | + +**核心问题**： + +1. **身份重复注入** — L1 Workspace 已有 SOUL.md（我是谁），L3 又在 prompt 里写"你是 zhangfei-dev，专长: 编码" +2. **固定步骤指令** — 手把手教 curl，不信任 Agent 自主能力 +3. **Review 不区分角色** — 庞统（进度review）和司马懿（质量review）用同一套逻辑 +4. **缺少"引导提问"** — Agent 不知道可以问问题、可以讨论 + +### 4.2 改造方案 + +#### 原则：L3 只传任务信息，不传身份 + +身份（"你是谁、你擅长什么"）由 L1 Workspace 负责。L3 只负责： +- 这次的任务是什么 +- 你能用什么 API +- 硬性约束（红线、产出要求） + +#### 改造 1：统一 prompt 结构（三段式） + +所有 L3 模板统一为： + +``` +┌──────────────────────┐ +│ 任务段（变化） │ 具体任务信息 + 上下文 +├──────────────────────┤ +│ 能力段（半固定） │ API 端点列表 + 操作指引 +├──────────────────────┤ +│ 约束段（固定） │ 产出要求 + 红线 + 协作引导 +└──────────────────────┘ +``` + +**身份段删除**（已由 L1 负责）。 + +#### 改造 2：各模板重写 + +**A. Task 执行模板**（替代 SPAWN_PROMPT_TEMPLATE） + +```markdown +## 任务 +{title} +{description} + +项目: {project_id} | ID: {task_id} +类型: {task_type} | 优先级: {priority} +验收标准: {must_haves} + +{retry_context} + +## 操作 +- 读任务详情（含依赖、讨论、产出）: GET {api_base}/projects/{project_id}/tasks/{task_id}?expand=all +- 写产出: POST {api_base}/projects/{project_id}/tasks/{task_id}/outputs +- 写评论/提问/讨论: POST {api_base}/projects/{project_id}/tasks/{task_id}/comments +- 更新状态: POST {api_base}/projects/{project_id}/tasks/{task_id}/status +- 创建子任务: POST {api_base}/projects/{project_id}/tasks + +## 约束 +- 完成后必须写产出物并标 review +- 失败了标 failed 并写明原因 +- 不懂就问（黑板 comment 提问） +- 需要其他人协作时 @ 对应 Agent +- 禁止使用 sessions_send（用 Mail API 或黑板 comment） +``` + +**B. 广播认领模板**（替代 _build_claim_prompt） + +```markdown +## 待认领任务 +{task_list} + +## 操作 +- 读任务详情: GET {api_base}/projects/{project_id}/tasks?status=pending +- 认领: POST {api_base}/projects/{project_id}/tasks/{{TASK_ID}}/claim + body: {"agent": "{agent_id}"} +- 认领后标 working: POST .../tasks/{{TASK_ID}}/status + body: {"status": "working", "agent": "{agent_id}"} +- 没有适合你的任务则 NO_REPLY + +## 约束 +- 只认领符合你专长的任务（参考你的 SOUL.md） +- 一个 tick 只认领一个 +- 不确定时不要认领 +``` + +**C. @mention 模板**（替代 _build_mention_prompt） + +```markdown +你在黑板上被 @ 了。 + +## 相关讨论 +{mentions_text} + +## 任务上下文 +- 项目: {project_id} | 任务: {task.title} +- 描述: {task.description} + +## 操作 +- 读完整上下文: GET {api_base}/projects/{project_id}/tasks/{task.id}?expand=all +- 回应: POST {api_base}/projects/{project_id}/tasks/{task.id}/comments +- 如果讨论收敛到可执行任务，创建 sub task + +## 约束 +- 只回应与你专长相关的内容 +- 不懂就问 +``` + +**D. Review 模板 — 分两个** + +**庞统 Review**（进度 review，多轮迭代）： + +```markdown +## 庞统 Review（第 {round_num} 轮） + +### Goal +{goal} + +### 验收标准 +{must_haves} + +### 本轮 Sub Task 状态 +- 完成: {done} | 失败: {failed} | 取消: {cancelled} | 总计: {total} + +### 成果物 +{outputs} + +### 黑板讨论 +{comments} + +### 三问 +1. Goal 还清晰吗？ +2. 成果物覆盖 goal 了吗？ +3. 下一轮需要做什么？ + +### 操作 +- 创建新一轮 sub tasks / 标 GOAL_ACHIEVED / 调整方向 +- Round 上限: {MAX_ROUNDS}（当前第 {round_num} 轮） +``` + +**司马懿 Review**（质量 review，单任务审查）： + +```markdown +## 司马懿 Review + +### 任务 +{title}: {description} + +### 产出物 +{outputs} + +### 审查要点 +1. 代码质量：命名、结构、可维护性 +2. 正确性：逻辑、边界、异常处理 +3. 安全性：是否有注入、越权等风险 +4. 符合验收标准 + +### 操作 +- 写审查意见: POST {api_base}/projects/{pid}/tasks/{tid}/comments + body: {"author": "simayi-challenger", "body": "...", "comment_type": "review"} +- 写审查结论: POST {api_base}/projects/{pid}/tasks/{tid}/reviews + body: {"reviewer": "simayi-challenger", "verdict": "approved/rejected/needs_revision", "notes": "..."} + +### 约束 +- 审查意见必须具体到行号和修改方向，不做模糊评价 +- rejected 时必须给出改进建议 +- 涉及风控/实盘相关，额外关注安全性 +``` + +**E. Delegate 模板**（保留，小改） + +庞统专用的任务委派模板，保留不变。 + +**F. 续杯模板**（保留） + +已有 MAIL_RETRY_PROMPT，保持不变。 + +#### 改造 3：ticker 触发司马懿 Review + +当前 ticker 的 `_check_round_complete` 只 spawn 庞统 review。改造后： + +``` +_check_round_complete(): + for parent in done_parents: + → spawn 庞统 review（多轮迭代判断） + +_check_single_task_review(): + for task in review_status_tasks: + if task.risk_level == "high": + → spawn 司马懿 review（对抗辩论） + else: + → spawn 司马懿 review（标准审查） +``` + +### 4.3 文件变更清单 + +| 文件 | 改动 | 行数 | +|------|------|------| +| spawner.py | 重写 SPAWN_PROMPT_TEMPLATE，去掉身份段 | ~30 行 | +| ticker.py | 重写 _build_claim_prompt、_build_mention_prompt、_build_review_prompt；新增 _build_simayi_review_prompt、_check_single_task_review | ~80 行 | +| dispatcher.py | _build_delegate_prompt 小改 | ~5 行 | + +--- + +## 五、L4 Bootstrap 层 — 现状与改造 + +### 5.1 现状 + +**BootstrapBuilder**（`src/daemon/bootstrap.py`，~216 行） + +| 组件 | 设计 | 实现 | 实际使用 | +|------|------|------|---------| +| L2a 角色模板 | `_load_template(role.md)` | ✅ 代码存在 | ❌ `prompt_templates/` 目录不存在，返回 None | +| L2b 项目背景 | `_format_project_context()` | ✅ 代码存在 | ❌ 从未被调用 | +| L2c 任务上下文 | `_format_task_context()` | ✅ 代码存在 | ❌ 从未被调用 | +| L2d 前序产出 | `_format_depends_on()` | ✅ 代码存在 | ❌ 从未被调用 | +| L2e Guardrail | 传入 guardrail_rules | ✅ 代码存在 | ❌ 从未被调用 | +| L2f 审查协议 | 传入 review_protocols | ✅ 代码存在 | ❌ `review_protocols/` 不存在 | +| L2g 经验注入 | `_format_experiences()` | ✅ 代码存在 | ❌ 从未被调用 | +| L3 Skill 描述 | `_format_skills()` | ✅ 代码存在 | ❌ 从未被调用 | + +**关键事实**：BootstrapBuilder 从未被实例化。`main.py` 中 Spawner 初始化时 `bootstrap_builder=None`，所以所有 L4 功能完全未启用。 + +Spawner 的 `build_message()` 方法中： +```python +if self.bootstrap_builder and task is not None: + # 走 BootstrapBuilder 路径 + ... +else: + # fallback 到 L3 的硬编码模板 +``` +**永远走 else 分支**。 + +### 5.2 改造方案 + +#### Phase 1：最小可用 — 接入 BootstrapBuilder + +不建 `prompt_templates/` 目录（模板量小，先在代码中管理），只做： + +1. **main.py 中实例化 BootstrapBuilder** 并传给 Spawner +2. **Spawner 的 build_message() 走 BootstrapBuilder 路径** +3. BootstrapBuilder 拼装内容与 L3 新模板对齐 + +```python +# main.py 改造 +from src.daemon.bootstrap import BootstrapBuilder + +bootstrap = BootstrapBuilder( + template_dir=None, # Phase 1 不用文件模板 + max_tokens=4096, +) +spawner = AgentSpawner( + ..., + bootstrap_builder=bootstrap, +) +``` + +#### Phase 2：接入动态数据源 + +BootstrapBuilder 的 `build_for_task()` 增强数据获取： + +| 数据 | 来源 | 注入条件 | +|------|------|---------| +| 任务上下文 | 黑板 DB (tasks 表) | 始终 | +| 前序产出 | 黑板 DB (outputs 表，查 depends_on) | 有依赖时 | +| Guardrail 规则 | GuardrailEngine | executor 角色 | +| 审查协议 | review_protocols/ 目录 | executor+reviewer 角色 | +| 经验 | experiences 表 | 有相关经验时 | +| Skill 描述 | SkillRegistry | 按需 | + +#### Phase 3：prompt_templates 目录 + +当模板内容稳定后，从代码中提取到文件： +- `prompt_templates/executor.md` — 执行者角色模板 +- `prompt_templates/reviewer_simayi.md` — 司马懿审查模板 +- `prompt_templates/reviewer_pangtong.md` — 庞统进度模板 +- `prompt_templates/planner.md` — 规划者模板 + +### 5.3 与 L3 的关系 + +L4 的产出**拼接在 L3 消息的尾部**。具体来说： + +``` +openclaw agent --message "{L3_template}\n\n---\n\n{L4_bootstrap}" +``` + +L3 提供任务段 + 操作段 + 约束段（骨架），L4 提供动态增强（前序产出、经验、Guardrail）。 + +两者职责不重叠： +- L3 是**模板**，每次结构相同只是参数不同 +- L4 是**增强**，根据任务类型/角色/历史动态拼装 + +### 5.4 文件变更清单 + +| 文件 | 改动 | 阶段 | +|------|------|------| +| main.py | 实例化 BootstrapBuilder 传给 Spawner | Phase 1 | +| spawner.py | build_message() 接入 BootstrapBuilder | Phase 1 | +| bootstrap.py | build_for_task() 增强数据获取 | Phase 2 | +| ticker.py | spawn 调用点传入更多上下文 | Phase 2 | +| prompt_templates/*.md | 从代码提取模板 | Phase 3 | + +--- + +## 六、四层信息分配总表 + +改造后，各类信息的归属层： + +| 信息类型 | 归属层 | 注入方式 | 变更频率 | +|---------|--------|---------|---------| +| Agent 人格/身份 | L1 | SOUL.md | 极低 | +| Agent 专长/能力 | L1 | SOUL.md 专长段 | 低 | +| 团队通讯录 | L1 | AGENTS.md | 低 | +| 黑板使用教程 | L1 | AGENTS.md | 低 | +| 黑板 API 参考 | L1 | TOOLS.md | 低 | +| 项目目录 | L1 | AGENTS.md | 中 | +| GATE 安全铁律 | L2 | gate-enforcer prependContext | 极低 | +| Delegation 策略 | L2 | gate-enforcer prependContext | 低 | +| GATE 产出物检查 | L2 | gate-enforcer before_tool_call | 低 | +| 任务信息 | L3 | Daemon prompt 模板 | 每次不同 | +| API 操作指引 | L3 | Daemon prompt 模板 | 半固定 | +| 产出约束 | L3 | Daemon prompt 模板 | 固定 | +| 前序产出摘要 | L4 | BootstrapBuilder | 每次不同 | +| Guardrail 规则 | L4 | BootstrapBuilder | 低 | +| 审查协议 | L4 | BootstrapBuilder | 低 | +| 经验注入 | L4 | BootstrapBuilder | 每次不同 | +| Skill 描述 | L4 | BootstrapBuilder | 低 | + +### 信息去重检查 + +| 信息 | L1 | L2 | L3 | L4 | 唯一归属 | +|------|----|----|----|----|---------| +| "你是 zhangfei-dev" | ✅ SOUL | — | — | — | L1 | +| "你的专长是编码" | ✅ SOUL | — | ~~❌ 删除~~ | — | L1 | +| GATE 五条铁律 | — | ✅ Hook | — | — | L2 | +| 任务标题/描述 | — | — | ✅ 模板 | — | L3 | +| API 端点列表 | — | — | ✅ 模板 | — | L3 | +| 前序 Agent 产出 | — | — | — | ✅ Bootstrap | L4 | +| 审查协议 | — | — | — | ✅ Bootstrap | L4 | +| 黑板使用教程 | ✅ AGENTS | — | — | — | L1 | + +--- + +## 七、实施路线 + +### Step 1：L1 Workspace 改造（独立，可先行） + +- 各 Agent SOUL.md 加专长段 +- 各 Agent AGENTS.md 重写（v1 编排纪律 → v2 黑板协作指南） +- 各 Agent TOOLS.md 加黑板 API 段 +- **验证**：直接在 Control UI 对话中测试 Agent 是否知道自己的专长和黑板用法 + +### Step 2：L2 Hook 微调（独立，可先行） + +- gate-enforcer DELEGATION_RULE 内容更新 +- **验证**：`plugins doctor` + session 文件检查 + +### Step 3：L3 Prompt 模板重写（依赖 Step 1） + +- 去掉所有模板中的身份注入 +- 重写 6 个模板 +- 新增司马懿 Review 模板 + 触发逻辑 +- **验证**：E2E 单任务测试 + +### Step 4：L4 BootstrapBuilder 接入（依赖 Step 3） + +- main.py 实例化 BootstrapBuilder +- spawner build_message() 走 BootstrapBuilder 路径 +- **验证**：E2E 全流程测试 + +### Step 5：E2E 验证 + +- E1 广播认领（Agent 凭 SOUL.md 专长自主判断） +- E2 任务执行（无固定步骤，Agent 自主决策） +- E3 多轮迭代（庞统 Review 三问框架） +- E4 @mention 协作（黑板讨论） +- E5 mention 重试 +- E6 质量审查（司马懿 Review） +- 新 E7：Agent 主动提问（黑板 comment 提问） + +--- + +## 八、风险 + +| 风险 | 概率 | 缓解 | +|------|------|------| +| Agent 看不到 L1 专长段，不按专长认领 | 中 | L3 claim 模板保留"只认领符合专长"约束作为双保险 | +| L4 BootstrapBuilder 拼装内容过长 | 低 | max_tokens=4096 限制 + 自动截断 | +| 去掉固定步骤后 Agent 不知道怎么操作 | 中 | L1 AGENTS.md 有黑板教程 + L3 有 API 列表 | +| 司马懿 Review 触发时机不对 | 中 | 先接 basic flow，观察后调整 |