diff --git a/docs/design/11-context-layers-redesign.md b/docs/design/11-context-layers-redesign.md index 3ec7f2b..8886871 100644 --- a/docs/design/11-context-layers-redesign.md +++ b/docs/design/11-context-layers-redesign.md @@ -808,13 +808,238 @@ Base:`http://localhost:8083/api/mail` | 维度 | 旧设计(05) | 新设计(11) | 变化 | |------|-----------|-----------|------| -| L2 定位 | 引擎注入 + 角色模板 + 操作规范 + 审查协议 + 经验 | 只放引擎流转数据+约束 | **大幅瘦身** | -| 操作规范位置 | L2 prompt_templates/{role}.md | L3 blackboard-{role} Skill | **降级到 L3** | -| 经验机制 | experiences 表 + tag 匹配 | L3 经验型 Skill | **简化** | -| Skill 发现 | 两套(OpenClaw + SkillRegistry) | 一套(OpenClaw extraDirs) | **统一** | -| BootstrapBuilder 复杂度 | 7 个组件 | 4 个组件 + 状态约束 | **减半** | -| L2 token 预算 | ~1500 | ≤800 | **减半** | -| 总 Skill 数量 | 42(现有)+ 4(蒸馏)| 42 + ~15(新增操作规范+方法论+经验)| **+15 个 Skill** | +| L2 定位 | 引擎注入 + 角色模板 + 操作规范 + 审查协议 + 经验 | 任务上下文 + 角色操作规范全文 + 硬约束 | **重塑** | +| 操作规范位置 | L2 prompt_templates/{role}.md | L3 A 类 Skill，由 L2 引擎读入注入 | **单一数据源** | +| 经验机制 | experiences 表 + tag 匹配 | L3 D 类 Skill | **简化** | +| Skill 发现 | 两套（OpenClaw + SkillRegistry） | 一套（extraDirs）+ skill-router 路由 | **统一** | +| BootstrapBuilder 复杂度 | 7 个组件 | 4 段（ROLE_SKILL_MAP） | **减半** | +| L2 token 预算 | ~1500 | ~600 | **减半多** | +| Skill 分类 | 无分类 | A/B/C/D 四类 + skill-router | **结构化** | +| Skill 注入方式 | 全部靠 Description 触发 | A 类引擎注入 + B/C/D 类 Description 触发 | **双轨制** | +| 总 Skill 数量 | 42（现有）+ 4（蒸馏）| 42 + 15（新增）| **+15 个 Skill** | + +--- + +## 十一、skill-router 详细设计 + +### 11.1 定位 + +`skill-router` 是 L3 路由层 Skill，作为 Agent 发现和使用其他 Skill 的入口。Agent 从 L1 SOUL.md 决策模式得知“执行任务前先读 skill-router”，在路由速查表中快速定位需要的 Skill。 + +### 11.2 内容结构 + +路由速查表按三个分类组织： + +#### 分类 1：操作规范（A 类，6 个） + +| Skill 名称 | 一句话定位 | 适用角色 | +|------------|-----------|----------| +| `blackboard-executor` | 执行者操作规范，定义能力列表、执行纪律、产出标准 | executor | +| `blackboard-reviewer` | 通用审查者操作规范，审查思维 + Scope Reduction Detection | reviewer | +| `blackboard-reviewer-simayi` | 司马懿特化审查，挑战者思维 + 审查层级 + 反驳权 | reviewer-simayi | +| `blackboard-reviewer-pangtong` | 庞统 Review，三问框架 + 目标漂移检测 | reviewer-pangtong | +| `blackboard-planner` | 规划者操作规范，规划思维 + 终态定义 | planner | +| `blackboard-claim` | 广播认领操作规范，三级响应规则 | claim | + +#### 分类 2：方法论（B 类，4 个） + +| Skill 名称 | 一句话定位 | 触发场景 | +|------------|-----------|----------| +| `metacognition` | 置信度自评 + 升级机制 | 任务执行中不确定时 | +| `scope-reduction-detection` | 反静默降级检查 | executor 自检 + reviewer 复检 | +| `plan-approval-workflow` | 复杂任务先计划后执行 | 非平凡任务开始前 | +| `team-collaboration` | Boids 协作规则 + 共享意识 | 多 Agent 协作时 | + +#### 分类 3：经验参考（C 类 1 个 + D 类 3 个） + +| Skill 名称 | 一句话定位 | 触发场景 | +|------------|-----------|----------| +| `review-quality` | 4 个评审质量模式 | 审查任务时 | +| `trial-and-error-patterns` | 6 个试错模式 | 遇到类似问题时 | +| `proven-practices` | 9 个成功最佳实践 | 寻找参考方案时 | +| `self-reflection-wisdom` | 3 个自我反思模式 | 任务复盘时 | + +### 11.3 L1 引导机制 + +在所有 Agent 的 SOUL.md 决策模式中加一条： + +> 执行任务前，先读 skill-router Skill 查找相关操作规范和方法论 + +### 11.4 维护方式 + +- **维护者**：庞统（副军师）人工维护 +- **更新时机**：新增/修改/删除 Skill 时同步更新 skill-router 路由表 +- **更新流程**：创建/修改 Skill 文件 → 更新 skill-router 表格 → 重启 OpenClaw + +### 11.5 Skill Description 编写规范 + +所有 Skill 的 description 必须包含以下要素，总长 ≤ 200 字： + +1. **一句话定位**：这个 Skill 是什么 +2. **触发场景**：什么时候该用 +3. **核心能力**：能解决什么问题 +4. **触发词**（5-8 个关键词） +5. **不触发词**：什么场景不该用 + +**示例**： + +```yaml +description: | + 黑板执行者操作规范。收到 moziplus 投递的执行任务时使用。 + 包含能力列表、执行纪律、产出标准、交接责任。 + 触发词：executor、执行、黑板执行、task execution、blackboard executor、任务执行、产出标准。 + 不触发词：review、审查、规划、claim。 +``` + +### 11.6 BootstrapBuilder ROLE_SKILL_MAP 定义 + +```python +ROLE_SKILL_MAP = { + "executor": "blackboard-executor", + "reviewer": "blackboard-reviewer", + "reviewer-simayi": "blackboard-reviewer-simayi", + "reviewer-pangtong": "blackboard-reviewer-pangtong", + "planner": "blackboard-planner", + "claim": "blackboard-claim", +} +``` + +### 11.7 Skill 目录结构（15 个新 Skill） + +所有 Skill 放在 `~/.sanguo_projects/sanguo_mozi/skills/` 目录下： + +``` +skills/ +├── skill-router/SKILL.md # 路由速查表 +├── blackboard-executor/SKILL.md # A 类 +├── blackboard-reviewer/SKILL.md # A 类 +├── blackboard-reviewer-simayi/SKILL.md # A 类 +├── blackboard-reviewer-pangtong/SKILL.md # A 类 +├── blackboard-planner/SKILL.md # A 类 +├── blackboard-claim/SKILL.md # A 类 +├── metacognition/SKILL.md # B 类 +├── scope-reduction-detection/SKILL.md # B 类 +├── plan-approval-workflow/SKILL.md # B 类 +├── team-collaboration/SKILL.md # B 类 +├── review-quality/SKILL.md # C 类 +├── trial-and-error-patterns/SKILL.md # D 类 +├── proven-practices/SKILL.md # D 类 +└── self-reflection-wisdom/SKILL.md # D 类 +``` + +--- + +## 十二、L2 BootstrapBuilder 代码改动设计 + +### 12.1 输出结构 + +BootstrapBuilder 的 `build()` 方法输出 4 段内容： + +``` +┌─────────────────────────────────────────────┐ +│ 段 1: 任务上下文（~200 tokens） │ +│ title / description / must_haves / status │ +├─────────────────────────────────────────────┤ +│ 段 2: 前序产出（有依赖时注入） │ +│ depends_on 产出摘要 + handoff comment │ +├─────────────────────────────────────────────┤ +│ 段 3: 角色操作规范全文（~300 tokens） │ +│ 通过 ROLE_SKILL_MAP 从 Skill 文件读取 │ +│ 精确注入对应角色的 A 类 Skill 全文 │ +├─────────────────────────────────────────────┤ +│ 段 4: 硬约束（~100 tokens） │ +│ 完成后标 review / 产出物非空 / handoff ≥ 50字│ +└─────────────────────────────────────────────┘ +``` + +### 12.2 build() 核心逻辑 + +```python +class BootstrapBuilder: + """L2 引擎注入层构建器""" + + ROLE_SKILL_MAP = { + "executor": "blackboard-executor", + "reviewer": "blackboard-reviewer", + "reviewer-simayi": "blackboard-reviewer-simayi", + "reviewer-pangtong": "blackboard-reviewer-pangtong", + "planner": "blackboard-planner", + "claim": "blackboard-claim", + } + + SKILL_BASE_PATH = os.path.expanduser( + "~/.sanguo_projects/sanguo_mozi/skills" + ) + + def build(self, task: dict, role: str) -> str: + """构建 Agent 启动 prompt""" + sections = [] + + # 段 1: 任务上下文 + sections.append(self._format_task_context(task)) + + # 段 2: 前序产出（有依赖时） + if task.get("depends_on"): + sections.append(self._format_prior_outputs(task)) + + # 段 3: 角色操作规范全文 + skill_name = self.ROLE_SKILL_MAP.get(role) + if skill_name: + skill_content = self._read_skill(skill_name) + sections.append(skill_content) + + # 段 4: 硬约束 + sections.append(self._format_constraints(role)) + + return "\n\n".join(sections) + + def _read_skill(self, skill_name: str) -> str: + """从 Skill 文件读取全文""" + path = os.path.join(self.SKILL_BASE_PATH, skill_name, "SKILL.md") + with open(path) as f: + return f.read() + + def _format_constraints(self, role: str) -> str: + """格式化硬约束""" + constraints = ["## 硬约束"] + if role == "executor": + constraints.extend([ + "- 完成后必须标 review", + "- 产出物不能为空", + "- handoff comment ≥ 50 字", + ]) + elif role.startswith("reviewer"): + constraints.extend([ + "- 审查结果必须明确 pass/fail", + "- 评审意见须附证据（文件:行号）", + ]) + return "\n".join(constraints) +``` + +### 12.3 需要改的文件清单 + +| 文件 | 操作 | 说明 | +|------|------|------| +| `bootstrap.py` | **改造** | 加 ROLE_SKILL_MAP + _read_skill + _format_constraints | +| `spawner.py` | **改造** | build_message() 走 BootstrapBuilder.build() 路径 | +| `prompt_templates/executor.md` | **删除** | 已移到 Skill 文件 | +| `prompt_templates/reviewer.md` | **删除** | 已移到 Skill 文件 | +| `prompt_templates/review_simayi.md` | **删除** | 已移到 Skill 文件 | +| `prompt_templates/review_pangtong.md` | **删除** | 已移到 Skill 文件 | +| `prompt_templates/planner.md` | **删除** | 已移到 Skill 文件 | +| `skill_system.py` | **删除** | 不再需要 SkillRegistry | +| `experiences/` 目录 | **删除** | 已提炼为 D 类 Skill | + +### 12.4 与旧版对比 + +| 维度 | 旧版 BootstrapBuilder | 新版 BootstrapBuilder | +|------|----------------------|---------------------| +| 数据源 | prompt_templates/ 目录 | Skill 文件 | +| 组件数 | 7 个（任务上下文/项目背景/状态约束/前序信息/Guardrail/广播规则/审查规则） | 4 段（任务上下文/前序产出/角色操作规范/硬约束） | +| 角色模板 | 读 .md 文件 | 读 Skill 文件（ROLE_SKILL_MAP） | +| token 预算 | ~1500 | ~600 | +| 经验注入 | experiences 表查询 | 无（靠 B/C/D 类 Skill 自主触发） | +| 复杂度 | 高（7 个组件 + 条件注入 + tag 匹配） | 低（4 段 + 1 个映射表） | ---