sanguo/sanguo_moziplus_v2
8
0
Fork 0
Code Issues Pull Requests 1 Actions 1 Packages Projects Releases Wiki Activity

auto-sync: 2026-06-04 08:33:42

Browse Source
This commit is contained in:
cfdaily
2026-06-04 08:33:42 +08:00
parent c87c02da32
commit 0de078e97a
1 changed files with 0 additions and 595 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/12-l2-l3-skill-system.md
-595
View File
@@ -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/<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 必须包含：
```yaml
---
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 提炼，不编造 |