sanguo/sanguo_moziplus_v2

Fork 0

Files

T

cfdaily c87c02da32 auto-sync: 2026-06-04 08:24:52

2026-06-04 08:24:52 +08:00

20 KiB

Raw Blame History

#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 输出结构

# 任务指令

## 任务上下文
任务ID: {task_id}
标题: {title}
描述: {description}
必须完成: {must_haves}
风险级别: {risk_level}

## 前序产出
{depends_on_summary}

## 角色操作规范
{role_skill_content}

## 流转约束
- 产出物必须有实际内容，不能空提交
- 失败标 failed 并写明原因
{role_specific_constraints}

2.2 角色操作规范注入逻辑

# 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

---
name: blackboard-executor
description: |
  黑板执行者操作规范。引擎 spawn executor 时注入全文。
  包含对齐全局→确认设计→实现→交接完整流程。
  触发词：执行、executor、产出、working、实现。
  不触发：review、审查、规划、planning。
---

内容要点（从 executor.md 迁移）：

对齐：读黑板全局计划 → 确认设计文档位置 → 读设计
执行：确认需求无歧义 → 实现 → 复杂任务参考 plan-act-verify
交接：handoff 写决策/踩坑/建议 → 产出写入黑板 → 标 review
异常：需求不清 @pangtong → 技术阻塞 @jiangwei → 发现降级参考 scope-reduction-detection

Related Skills: plan-act-verify, scope-reduction-detection, trial-and-error-patterns

blackboard-reviewer

---
name: blackboard-reviewer
description: |
  黑板审查者通用操作规范。引擎 spawn reviewer 时注入全文。
  包含审查→verdict→交接完整流程。
  触发词：review、审查、评审、verdict、approved、rejected。
  不触发：执行、编码、规划。
---

内容要点（从 reviewer.md 迁移）：

审查：读黑板全局计划 → 读设计文档 → 读产出 → 对齐检查
Verdict：approved/rejected/needs_revision，rejected 必须给改进方向
Rebuttal：被反驳时重新审视，2轮不一致 → @pangtong 仲裁
不确定时参考 metacognition

Related Skills: review-quality, metacognition, self-reflection-wisdom

blackboard-reviewer-simayi

---
name: blackboard-reviewer-simayi
description: |
  司马懿特化审查操作规范。引擎 spawn reviewer-simayi 时注入全文。
  司马懿的审查思维：鹰视狼顾看正文、先扫一致性再评内容、正反两面挑战。
  触发词：司马懿审查、挑战者、魔鬼代言人、simayi review。
  不触发：执行、编码、规划。
---

内容要点（从 review_simayi.md 迁移 + 蒸馏教训）：

审查前：先理解目标和设计者意图
一致性扫描：先扫内部一致性，再评内容。看到"已修改"→ grep 确认
证据驱动：每条意见附文件:行号 + 当前值 + 建议值
挑战者角色：正反两面，找"哪里假设了但没说"
不确定时参考 metacognition，审查标准参考 review-quality

Related Skills: review-quality, metacognition, self-reflection-wisdom

blackboard-reviewer-pangtong

---
name: blackboard-reviewer-pangtong
description: |
  庞统特化审查操作规范。引擎 spawn reviewer-pangtong 时注入全文。
  庞统的审查思维：方向一致性 > 内容质量 > 细节打磨。
  触发词：庞统审查、方向检查、目标漂移、仲裁。
  不触发：执行、编码。
---

内容要点（从 review_pangtong.md 迁移）：

方向一致性：改动是否偏离原始目标？
拒绝降级：实现和目标不一致时指出差距
仲裁：2 轮 rebuttal 不一致时做最终裁决

Related Skills: scope-reduction-detection, review-quality

blackboard-planner

---
name: blackboard-planner
description: |
  黑板规划者操作规范。引擎 spawn planner 时注入全文。
  包含需求澄清→拆解→子任务创建完整流程。
  触发词：规划、拆解、子任务、planning、需求分析。
  不触发：执行、review、编码。
---

内容要点（从 planner.md 迁移）：

需求澄清：苏格拉底式追问，1-2 轮定位
拆解：每个子任务有明确终态、可验证
分配：按角色专长分配
不确定时参考 team-collaboration

Related Skills: team-collaboration, metacognition

blackboard-claim

---
name: blackboard-claim
description: |
  黑板广播认领操作规范。引擎 spawn claim 时注入全文。
  收到任务广播时使用，判断是否认领。
  触发词：认领、claim、broadcast、广播、观察。
  不触发：执行、review、规划。
---

内容要点（从 spawner.py _build_claim_prompt 提取）：

读广播内容 → 判断是否属于自己专长
属于 → 认领，不属于 → 跳过
认领时确认：目标明确、有能力完成、时间允许

3.2 B 类：方法论型（Description 自主触发）

metacognition

---
name: metacognition
description: |
  元认知评估。对当前判断不确定时使用。评估置信度 → 决定是否升级。
  触发词：不确定、犹豫、可能、也许、置信度、没把握。
  不触发：明确判断、高置信度。
---

内容：

置信度自评：0-100%，低于 70% 标注"待验证"
不确定时升级：@pangtong-fujunshi 或在黑板 comment 提问
不编造——不确定的标明是假设

scope-reduction-detection

---
name: scope-reduction-detection
description: |
  反静默降级检查。发现自己可能在砍需求/跳步骤/减少交付时使用。
  触发词：降级、砍需求、跳步骤、简化、减少、来不及。
  不触发：正常执行。
---

内容：

检查清单：我在砍需求吗？跳步骤了吗？减少交付了吗？
降级必须显式声明：在黑板 comment 写明降级内容和原因
用户/庞统确认后才降级

plan-approval-workflow

---
name: plan-approval-workflow
description: |
  复杂任务审批流程。多文件/多模块任务先计划后执行，等异议窗口。
  触发词：审批、异议、计划确认、多文件、多模块。
  不触发：单文件小改动。
---

内容：

复杂任务先在 comment 写计划
5 分钟无异议再执行（或 @reviewer 确认）
异议出现 → 修改计划 → 重新等确认

team-collaboration

---
name: team-collaboration
description: |
  团队协作规则（Boids 模型）。规划/协调任务时参考。
  触发词：协作、冲突、边界、团队、分工。
  不触发：独立执行。
---

内容：Boids 四规则

Separation：不重复别人正在做的事
Alignment：和全局目标对齐
Cohesion：产出物互相衔接
Boundary：只认领自己专长范围内的任务

3.3 C 类：审查协议型

review-quality

---
name: review-quality
description: |
  审查质量标准。审查/评审时参考的四个质量维度。
  触发词：审查标准、评审维度、review quality、验收标准。
  不触发：执行、编码。
---

内容（从 wiki-vault 蒸馏）：

正确性：逻辑是否正确，边界是否覆盖
一致性：设计↔实现是否对齐，不同位置描述是否一致
完整性：是否有遗漏，异常处理是否到位
可维护性：代码风格、命名、注释

3.4 D 类：经验型

trial-and-error-patterns

---
name: trial-and-error-patterns
description: |
  常见试错模式。从团队历史教训提炼的 6 个高频错误模式。
  触发词：踩坑、失败、错误、教训、经验。
  不触发：正常执行、成功经验。
---

内容（从 wiki-vault practices + JSONL 分析提炼）：

前端开发完先 E2E 再评审
跨模块接口必须文档化+测试验证
测试和开发必须分离
关键阻塞修根因不手动改 DB
改了源码忘同步安装目录
通知渠道必须有冒烟测试

proven-practices

---
name: proven-practices
description: |
  成功最佳实践。从 wiki-vault practices 提炼的已验证做法。
  触发词：最佳实践、成功经验、proven、做法。
  不触发：踩坑、失败。
---

内容（从 wiki-vault practices 提炼）：

先两层蒸馏再扩展
Experience → Skill 延迟转化
Skill 自包含原则
检查点驱动的流程控制
增量更新而非全量重建
迭代上限防止无限循环

self-reflection-wisdom

---
name: self-reflection-wisdom
description: |
  自我反思模式。审查/复盘时参考的反思方法论。
  触发词：反思、复盘、教训、改进、自评。
  不触发：正常执行。
---

内容（从 wiki-vault practices + 蒸馏提炼）：

HOW not WHAT：提炼思维方式而非知识内容
诚实边界：每个产出声明局限性
矛盾是特征不是 Bug：记录不调和的矛盾

四、skill-router 设计

4.1 定位

skill-router 是一个 L3 Skill，内容就是一张路由速查表。Agent 从 L1 决策模式得知"执行任务前先读 skill-router"，到 skill-router 中查找当前场景对应的 Skill。

4.2 内容结构

---
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 名称/描述/关键词

更新流程：

创建/修改 L3 Skill 文件（加/改/删 SKILL.md）
同步更新 skill-router 表格
重启 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/<skill-name>/
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 必须包含：

---
name: <skill-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 提炼，不编造

20 KiB Raw Blame History Unescape Escape