diff --git a/docs/design/12-l2-l3-skill-system.md b/docs/design/12-l2-l3-skill-system.md deleted file mode 100644 index f0d2e31..0000000 --- a/docs/design/12-l2-l3-skill-system.md +++ /dev/null @@ -1,595 +0,0 @@ -# #12 L2 瘦身 + L3 Skill 体系详细设计 - -> 版本: v1.0 -> 日期: 2026-06-04 -> 作者: 庞统（副军师） -> 状态: **待确认** -> 前置: #11 上下文四层架构重新定位方案（已完成） - ---- - -## 一、总体架构 - -``` -┌─────────────────────────────────────────────────────────┐ -│ L0 铁律（OpenClaw 注入，不改） │ -│ gate-rules + delegation-rule │ -├─────────────────────────────────────────────────────────┤ -│ L1 认知操作系统（每次必看） │ -│ SOUL.md / AGENTS / TOOLS / IDENTITY / USER │ -│ ← 含"执行任务前，先读 skill-router 选取最合适的 Skill" │ -├─────────────────────────────────────────────────────────┤ -│ L2 引擎注入（BootstrapBuilder，spawn 时注入） │ -│ │ -│ ① 任务上下文（task_id/title/desc/must_haves）~150 tokens │ -│ ② 前序产出（depends_on 摘要） ~50 tokens │ -│ ③ A 类操作规范全文（按角色精确注入） ~300 tokens │ -│ ④ 硬约束（通用流转规则） ~100 tokens │ -│ 总计: ~600 tokens│ -├─────────────────────────────────────────────────────────┤ -│ L3 被动参考（OpenClaw extraDirs，Agent 按需 read） │ -│ │ -│ skill-router（路由速查表） │ -│ A 类: blackboard-executor/reviewer/...（引擎注入时全文） │ -│ B 类: metacognition/scope-reduction/...（Description触发）│ -│ C 类: review-quality（Description触发） │ -│ D 类: trial-and-error/proven-practices/...（Description）│ -│ 现有: 42 个 Skill 保留不动 │ -└─────────────────────────────────────────────────────────┘ -``` - ---- - -## 二、L2 BootstrapBuilder 新版设计 - -### 2.1 输出结构 - -```markdown -# 任务指令 - -## 任务上下文 -任务ID: {task_id} -标题: {title} -描述: {description} -必须完成: {must_haves} -风险级别: {risk_level} - -## 前序产出 -{depends_on_summary} - -## 角色操作规范 -{role_skill_content} - -## 流转约束 -- 产出物必须有实际内容，不能空提交 -- 失败标 failed 并写明原因 -{role_specific_constraints} -``` - -### 2.2 角色操作规范注入逻辑 - -```python -# BootstrapBuilder.build() 核心逻辑 - -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", -} - -def build(self, role, task_context, depends_on_outputs): - parts = [] - - # ① 任务上下文 - parts.append(self._format_task_context(task_context)) - - # ② 前序产出（有依赖时） - if depends_on_outputs: - parts.append(self._format_depends_on(depends_on_outputs)) - - # ③ A 类操作规范全文（按角色精确注入） - skill_name = ROLE_SKILL_MAP.get(role, "blackboard-executor") - skill_content = self._read_skill(skill_name) - parts.append(f"## 角色操作规范\n{skill_content}") - - # ④ 硬约束 - parts.append(self._format_constraints(role)) - - return "\n\n".join(parts) - -def _read_skill(self, skill_name): - """读取 L3 Skill 全文注入 L2""" - skill_path = SKILLS_DIR / skill_name / "SKILL.md" - content = skill_path.read_text() - # 去掉 YAML frontmatter（已在 description 中可见） - return strip_frontmatter(content) - -def _format_constraints(self, role): - """按角色附加额外约束""" - COMMON = "产出物必须有实际内容，不能空提交。失败标 failed 并写明原因。" - if role == "executor": - return f"- handoff comment ≥ 50 字符：写决策、踩坑、建议\n- 需求不清时 @pangtong-fujunshi 提问\n{COMMON}" - elif role == "reviewer": - return f"- verdict: approved / rejected / needs_revision\n- rejected 必须给具体改进方向\n{COMMON}" - elif role == "planner": - return f"- 需求不清在黑板 comment 提问\n- 每个子任务有明确终态\n{COMMON}" - else: - return COMMON -``` - -### 2.3 与旧版对比 - -| 维度 | 旧版 BootstrapBuilder | 新版 | -|------|----------------------|------| -| 操作规范来源 | `prompt_templates/` 目录读文件 | 读 L3 Skill 文件 | -| 注入内容 | 角色模板全文（含操作规范+经验） | 纯数据 + Skill 全文 + 硬约束 | -| 硬约束位置 | 散在模板里 | 统一在"流转约束"段 | -| token 量 | ~1200 | ~600 | -| 扩展性 | 改 prompt_templates/ | 改 L3 Skill 文件 | - -### 2.4 需要改的代码文件 - -| 文件 | 改动 | -|------|------| -| `src/daemon/bootstrap.py` | 重写 `BootstrapBuilder`：去掉 template_dir，改为读 Skill 文件 | -| `src/daemon/spawner.py` | 适配新 `BootstrapBuilder` 接口：传入 role + task_context | -| `prompt_templates/*.md`（5个） | 迁移到 L3 Skill 后删除 | - ---- - -## 三、L3 Skill 清单 - -### 3.1 A 类：操作规范型（引擎直接注入全文） - -从现有 `prompt_templates/` 迁移，加 YAML frontmatter header，砍掉和 L2 硬约束重复的部分。 - -#### blackboard-executor - -```yaml ---- -name: blackboard-executor -description: | - 黑板执行者操作规范。引擎 spawn executor 时注入全文。 - 包含对齐全局→确认设计→实现→交接完整流程。 - 触发词：执行、executor、产出、working、实现。 - 不触发：review、审查、规划、planning。 ---- -``` - -**内容要点**（从 executor.md 迁移）： -1. 对齐：读黑板全局计划 → 确认设计文档位置 → 读设计 -2. 执行：确认需求无歧义 → 实现 → 复杂任务参考 `plan-act-verify` -3. 交接：handoff 写决策/踩坑/建议 → 产出写入黑板 → 标 review -4. 异常：需求不清 @pangtong → 技术阻塞 @jiangwei → 发现降级参考 `scope-reduction-detection` - -**Related Skills**: `plan-act-verify`, `scope-reduction-detection`, `trial-and-error-patterns` - -#### blackboard-reviewer - -```yaml ---- -name: blackboard-reviewer -description: | - 黑板审查者通用操作规范。引擎 spawn reviewer 时注入全文。 - 包含审查→verdict→交接完整流程。 - 触发词：review、审查、评审、verdict、approved、rejected。 - 不触发：执行、编码、规划。 ---- -``` - -**内容要点**（从 reviewer.md 迁移）： -1. 审查：读黑板全局计划 → 读设计文档 → 读产出 → 对齐检查 -2. Verdict：approved/rejected/needs_revision，rejected 必须给改进方向 -3. Rebuttal：被反驳时重新审视，2轮不一致 → @pangtong 仲裁 -4. 不确定时参考 `metacognition` - -**Related Skills**: `review-quality`, `metacognition`, `self-reflection-wisdom` - -#### blackboard-reviewer-simayi - -```yaml ---- -name: blackboard-reviewer-simayi -description: | - 司马懿特化审查操作规范。引擎 spawn reviewer-simayi 时注入全文。 - 司马懿的审查思维：鹰视狼顾看正文、先扫一致性再评内容、正反两面挑战。 - 触发词：司马懿审查、挑战者、魔鬼代言人、simayi review。 - 不触发：执行、编码、规划。 ---- -``` - -**内容要点**（从 review_simayi.md 迁移 + 蒸馏教训）： -1. 审查前：先理解目标和设计者意图 -2. 一致性扫描：先扫内部一致性，再评内容。看到"已修改"→ grep 确认 -3. 证据驱动：每条意见附文件:行号 + 当前值 + 建议值 -4. 挑战者角色：正反两面，找"哪里假设了但没说" -5. 不确定时参考 `metacognition`，审查标准参考 `review-quality` - -**Related Skills**: `review-quality`, `metacognition`, `self-reflection-wisdom` - -#### blackboard-reviewer-pangtong - -```yaml ---- -name: blackboard-reviewer-pangtong -description: | - 庞统特化审查操作规范。引擎 spawn reviewer-pangtong 时注入全文。 - 庞统的审查思维：方向一致性 > 内容质量 > 细节打磨。 - 触发词：庞统审查、方向检查、目标漂移、仲裁。 - 不触发：执行、编码。 ---- -``` - -**内容要点**（从 review_pangtong.md 迁移）： -1. 方向一致性：改动是否偏离原始目标？ -2. 拒绝降级：实现和目标不一致时指出差距 -3. 仲裁：2 轮 rebuttal 不一致时做最终裁决 - -**Related Skills**: `scope-reduction-detection`, `review-quality` - -#### blackboard-planner - -```yaml ---- -name: blackboard-planner -description: | - 黑板规划者操作规范。引擎 spawn planner 时注入全文。 - 包含需求澄清→拆解→子任务创建完整流程。 - 触发词：规划、拆解、子任务、planning、需求分析。 - 不触发：执行、review、编码。 ---- -``` - -**内容要点**（从 planner.md 迁移）： -1. 需求澄清：苏格拉底式追问，1-2 轮定位 -2. 拆解：每个子任务有明确终态、可验证 -3. 分配：按角色专长分配 -4. 不确定时参考 `team-collaboration` - -**Related Skills**: `team-collaboration`, `metacognition` - -#### blackboard-claim - -```yaml ---- -name: blackboard-claim -description: | - 黑板广播认领操作规范。引擎 spawn claim 时注入全文。 - 收到任务广播时使用，判断是否认领。 - 触发词：认领、claim、broadcast、广播、观察。 - 不触发：执行、review、规划。 ---- -``` - -**内容要点**（从 spawner.py `_build_claim_prompt` 提取）： -1. 读广播内容 → 判断是否属于自己专长 -2. 属于 → 认领，不属于 → 跳过 -3. 认领时确认：目标明确、有能力完成、时间允许 - -### 3.2 B 类：方法论型（Description 自主触发） - -#### metacognition - -```yaml ---- -name: metacognition -description: | - 元认知评估。对当前判断不确定时使用。评估置信度 → 决定是否升级。 - 触发词：不确定、犹豫、可能、也许、置信度、没把握。 - 不触发：明确判断、高置信度。 ---- -``` - -**内容**： -1. 置信度自评：0-100%，低于 70% 标注"待验证" -2. 不确定时升级：@pangtong-fujunshi 或在黑板 comment 提问 -3. 不编造——不确定的标明是假设 - -#### scope-reduction-detection - -```yaml ---- -name: scope-reduction-detection -description: | - 反静默降级检查。发现自己可能在砍需求/跳步骤/减少交付时使用。 - 触发词：降级、砍需求、跳步骤、简化、减少、来不及。 - 不触发：正常执行。 ---- -``` - -**内容**： -1. 检查清单：我在砍需求吗？跳步骤了吗？减少交付了吗？ -2. 降级必须显式声明：在黑板 comment 写明降级内容和原因 -3. 用户/庞统确认后才降级 - -#### plan-approval-workflow - -```yaml ---- -name: plan-approval-workflow -description: | - 复杂任务审批流程。多文件/多模块任务先计划后执行，等异议窗口。 - 触发词：审批、异议、计划确认、多文件、多模块。 - 不触发：单文件小改动。 ---- -``` - -**内容**： -1. 复杂任务先在 comment 写计划 -2. 5 分钟无异议再执行（或 @reviewer 确认） -3. 异议出现 → 修改计划 → 重新等确认 - -#### team-collaboration - -```yaml ---- -name: team-collaboration -description: | - 团队协作规则（Boids 模型）。规划/协调任务时参考。 - 触发词：协作、冲突、边界、团队、分工。 - 不触发：独立执行。 ---- -``` - -**内容**：Boids 四规则 -1. Separation：不重复别人正在做的事 -2. Alignment：和全局目标对齐 -3. Cohesion：产出物互相衔接 -4. Boundary：只认领自己专长范围内的任务 - -### 3.3 C 类：审查协议型 - -#### review-quality - -```yaml ---- -name: review-quality -description: | - 审查质量标准。审查/评审时参考的四个质量维度。 - 触发词：审查标准、评审维度、review quality、验收标准。 - 不触发：执行、编码。 ---- -``` - -**内容**（从 wiki-vault 蒸馏）： -1. 正确性：逻辑是否正确，边界是否覆盖 -2. 一致性：设计↔实现是否对齐，不同位置描述是否一致 -3. 完整性：是否有遗漏，异常处理是否到位 -4. 可维护性：代码风格、命名、注释 - -### 3.4 D 类：经验型 - -#### trial-and-error-patterns - -```yaml ---- -name: trial-and-error-patterns -description: | - 常见试错模式。从团队历史教训提炼的 6 个高频错误模式。 - 触发词：踩坑、失败、错误、教训、经验。 - 不触发：正常执行、成功经验。 ---- -``` - -**内容**（从 wiki-vault practices + JSONL 分析提炼）： -1. 前端开发完先 E2E 再评审 -2. 跨模块接口必须文档化+测试验证 -3. 测试和开发必须分离 -4. 关键阻塞修根因不手动改 DB -5. 改了源码忘同步安装目录 -6. 通知渠道必须有冒烟测试 - -#### proven-practices - -```yaml ---- -name: proven-practices -description: | - 成功最佳实践。从 wiki-vault practices 提炼的已验证做法。 - 触发词：最佳实践、成功经验、proven、做法。 - 不触发：踩坑、失败。 ---- -``` - -**内容**（从 wiki-vault practices 提炼）： -1. 先两层蒸馏再扩展 -2. Experience → Skill 延迟转化 -3. Skill 自包含原则 -4. 检查点驱动的流程控制 -5. 增量更新而非全量重建 -6. 迭代上限防止无限循环 - -#### self-reflection-wisdom - -```yaml ---- -name: self-reflection-wisdom -description: | - 自我反思模式。审查/复盘时参考的反思方法论。 - 触发词：反思、复盘、教训、改进、自评。 - 不触发：正常执行。 ---- -``` - -**内容**（从 wiki-vault practices + 蒸馏提炼）： -1. HOW not WHAT：提炼思维方式而非知识内容 -2. 诚实边界：每个产出声明局限性 -3. 矛盾是特征不是 Bug：记录不调和的矛盾 - ---- - -## 四、skill-router 设计 - -### 4.1 定位 - -skill-router 是一个 L3 Skill，内容就是一张路由速查表。Agent 从 L1 决策模式得知"执行任务前先读 skill-router"，到 skill-router 中查找当前场景对应的 Skill。 - -### 4.2 内容结构 - -```markdown ---- -name: skill-router -description: | - Skill 路由速查表。Agent 执行任务前查找当前场景该用什么 Skill。 - 触发词：不确定用什么 skill、找 skill、场景匹配、skill 路由。 - 不触发：已知该用什么 skill 的场景。 ---- - -# Skill Router Map - -## 操作规范（引擎按角色自动注入） - -| 角色 | Skill | 内容 | -|------|-------|------| -| executor | `blackboard-executor` | 对齐→实现→交接 | -| reviewer（通用） | `blackboard-reviewer` | 审查→verdict | -| reviewer（司马懿） | `blackboard-reviewer-simayi` | 挑战者审查 | -| reviewer（庞统） | `blackboard-reviewer-pangtong` | 方向审查 | -| planner | `blackboard-planner` | 需求→子任务 | -| 认领者 | `blackboard-claim` | 广播→认领 | - -## 方法论（按场景查找） - -| 你在做什么 | 推荐Skill | 关键词 | -|-----------|----------|--------| -| 复杂任务（多文件/多模块） | `plan-act-verify` | 复杂、多文件、多步骤 | -| 发现自己在砍需求/跳步骤 | `scope-reduction-detection` | 降级、砍需求、跳步骤 | -| 对判断不确定（置信度 < 70%） | `metacognition` | 不确定、犹豫、没把握 | -| 复杂计划需要审批 | `plan-approval-workflow` | 审批、异议、计划确认 | -| 团队协作规则 | `team-collaboration` | 协作、冲突、分工边界 | - -## 经验参考（遇到问题时查找） - -| 你遇到什么 | 推荐Skill | 关键词 | -|-----------|----------|--------| -| 踩坑了 | `trial-and-error-patterns` | 踩坑、失败、错误 | -| 想参考成功做法 | `proven-practices` | 最佳实践、成功经验 | -| 需要自我反思 | `self-reflection-wisdom` | 反思、复盘、教训 | -| 审查质量标准 | `review-quality` | 审查标准、评审维度 | -``` - -### 4.3 维护方式 - -skill-router 由人工维护（庞统负责）。更新时机： - -| 事件 | 操作 | -|------|------| -| 新增 Skill | 在对应分类（操作规范/方法论/经验）表格中加一行 | -| 删除 Skill | 从表格中移除对应行 | -| 修改 Skill 定位 | 更新 Skill 名称/描述/关键词 | - -**更新流程**： -1. 创建/修改 L3 Skill 文件（加/改/删 SKILL.md） -2. 同步更新 skill-router 表格 -3. 重启 OpenClaw 生效 - ---- - -## 五、Skill 生命周期管理 - -### 5.1 Skill 目录结构 - -``` -~/.sanguo_projects/sanguo_mozi/skills/ -├── skill-router/SKILL.md # 路由速查表 -├── blackboard-executor/SKILL.md # A1 -├── blackboard-reviewer/SKILL.md # A2 -├── blackboard-reviewer-simayi/SKILL.md # A3 -├── blackboard-reviewer-pangtong/SKILL.md # A4 -├── blackboard-planner/SKILL.md # A5 -├── blackboard-claim/SKILL.md # A6 -├── metacognition/SKILL.md # B7 -├── scope-reduction-detection/SKILL.md # B8 -├── plan-approval-workflow/SKILL.md # B9 -├── team-collaboration/SKILL.md # B10 -├── review-quality/SKILL.md # C11 -├── trial-and-error-patterns/SKILL.md # D12 -├── proven-practices/SKILL.md # D13 -├── self-reflection-wisdom/SKILL.md # D14 -├── ...（42 个现有 Skill 保留不动） -``` - -### 5.2 Skill 新增流程 - -``` -1. 确定分类：A(操作规范)/B(方法论)/C(审查协议)/D(经验) -2. 创建目录：~/.sanguo_projects/sanguo_mozi/skills// -3. 编写 SKILL.md： - - YAML frontmatter（name + description + 触发词） - - 正文（How-to 内容） - - Related Skills 串联 -4. 更新 skill-router SKILL.md：在对应分类表格中加一行 -5. 如果是 A 类（引擎注入）：同步改 BootstrapBuilder.ROLE_SKILL_MAP -6. 重启 OpenClaw 生效 -``` - -### 5.3 Skill 修改流程 - -``` -1. 修改 SKILL.md 内容 -2. 如果改了 name/description/定位：同步更新 skill-router -3. 如果是 A 类且改了文件名：同步改 BootstrapBuilder.ROLE_SKILL_MAP -4. 重启 OpenClaw 生效 -``` - -### 5.4 Skill 删除流程 - -``` -1. 从 skill-router 中移除对应行 -2. 如果是 A 类：从 BootstrapBuilder.ROLE_SKILL_MAP 中移除 -3. 删除 Skill 目录 -4. 重启 OpenClaw 生效 -``` - -### 5.5 Skill Description 编写规范 - -每个 Skill 的 YAML frontmatter description 必须包含： - -```yaml ---- -name: -description: | - <一句话定位>。<触发场景>。<核心能力>。 - 触发词：<5-8个关键词，逗号分隔>。 - 不触发：<排除词，逗号分隔>。 ---- -``` - -**质量标准**（来自优秀实践）： -- Description ≤ 200 字 -- 触发词 5-8 个，覆盖直接型+隐含型+动作型 -- 不触发词明确排除易混淆场景 -- SKILL.md 全文 ≤ 5000 tokens（A 类可放宽，因为引擎注入不受 Description 触发限制） - ---- - -## 六、实施计划 - -| Step | 内容 | 产出 | 预计工作量 | -|------|------|------|-----------| -| 1 | 创建 skill-router Skill | 1 个 SKILL.md | 小 | -| 2 | 创建 A 类 6 个操作规范 Skill（从 prompt_templates 迁移） | 6 个 SKILL.md | 中 | -| 3 | 创建 B 类 4 个方法论 Skill | 4 个 SKILL.md | 中 | -| 4 | 创建 C 类 1 个审查协议 Skill | 1 个 SKILL.md | 小 | -| 5 | 创建 D 类 3 个经验型 Skill | 3 个 SKILL.md | 中 | -| 6 | 改 BootstrapBuilder（瘦身 + 读 Skill 文件） | bootstrap.py | 中 | -| 7 | 改 spawner.py（适配新接口） | spawner.py | 小 | -| 8 | 清理旧 prompt_templates（迁移后删除） | 删除 5 个 .md | 小 | -| 9 | 更新设计文档 §11（同步 L1 改动） | 11-context-layers-redesign.md | 小 | -| 10 | E2E 验证 | 测试通过 | 中 | - -**依赖关系**：Step 1-5 可并行 → Step 6-8 依赖 Step 2 → Step 10 依赖全部 - ---- - -## 七、风险与缓解 - -| 风险 | 缓解 | -|------|------| -| A 类 Skill 全文注入 token 超标 | 每个 Skill ≤ 500 tokens，6 个共 3000，可接受。实际只注入 1 个 | -| B/C/D 类 Skill Description 触发不准 | 有 L1 "先读 skill-router"兜底，不纯靠 Description | -| 迁移 prompt_templates 遗漏内容 | 旧文件保留到 Step 10 E2E 验证通过后再删 | -| 经验型 Skill 数据源质量 | 从 wiki-vault 已有 practices 提炼，不编造 |