auto-sync: 2026-05-15 22:54:57

docs/design/topic4-decomposition-skill-proposal.md

@@ -276,99 +276,157 @@ simple 任务跳过方案确认，直接创建。complex 任务必须确认。
 
 ---
 
+
 ## Part B：Skill 体系工程落地
 
 ### 4. 设计目标
 
 三个课题产出了大量"Agent 需要知道怎么做"的内容（28 项 Skill TODO），需要一个系统的 Skill 体系来承载。
 
-### 5. 设计决策
+### 5. 核心洞察：被动触发不可靠
 
-#### D4-6：五层 Skill 架构
+> **问题**：我们写了好多个 Skill，但除了用户明文指定"用 PAV""用 delegation"，几乎没见哪个 Skill 被主动触发过。
+>
+> **根因**：Agent 不知道自己不知道什么。OpenClaw 的 Skill 列表注入 system prompt 后，Agent 需要自己判断需要哪个——但 Agent 根本不知道"我应该先读一个 Skill 来学怎么做"。
+>
+> **优秀实践验证**：superpowers / GSD / open-multi-agent 没有一个是靠被动 Skill 触发的——全部是编排器构造好 prompt 直接注入。
+
+**结论**：moziplus 的关键操作规范不走被动 Skill 发现，走引擎注入。
+
+### 6. 设计决策
+
+#### D4-6：四层上下文架构
 
 > **参考实践**：
-> - **Claude Code**：4 层渐进式加载（Discovery → Matching → Full Load → Overflow）
-> - **oh-my-claudecode**：三层组合（Execution + Enhancement + Guarantee）
-> - **nuwa-skill**：5 阶段蒸馏 + 检查点 + 诚实边界
-> - **v3.1 Skill 体系设计**（已确认）：Hook 铁律 + Agent 角色 + 通用 Skill + moziplus 注入
+> - **superpowers**：每个 subagent 有独立 prompt 模板（implementer-prompt.md / spec-reviewer-prompt.md），模板里写死操作步骤
+> - **open-multi-agent**：`buildTaskPrompt()` 拼 task title + description + 依赖产出 + messages
+> - **GSD**：每个 executor 拿到 PLAN.md + PROJECT.md + STATE.md + CONTEXT.md，按 context window 大小自适应
+> - **OpenClaw**：Hook `agent_turn_prepare` 可注入 prependContext/appendContext
+
+共同模式：**操作规范（模板）+ 项目背景（固定）+ 任务上下文（动态）**，编排器拼装，不靠 Agent 自己找。
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │ Layer 0: 铁律（Iron Rules）                                  │
-│   机制: OpenClaw Hook before_prompt_build                    │
-│   自由度: 无 | 每轮强制注入                                   │
+│   机制: OpenClaw Hook agent_turn_prepare                     │
+│   保证: 每轮强制注入 | Token: ~500                            │
 │   内容: IR-1~IR-5（每个 Agent 可定制）                        │
-│   Token: ~500                                                │
 ├─────────────────────────────────────────────────────────────┤
 │ Layer 1: 角色（Agent Identity）                               │
 │   机制: SOUL.md + IDENTITY.md + AGENTS.md                    │
-│   自由度: 无 | 全量加载                                       │
+│   保证: 每轮强制 | Token: ~2000                               │
 │   内容: 角色定义 + 行为准则 + 记忆                            │
-│   Token: ~2000                                               │
+│   变化频率: 极少（换平台不变）                                 │
 ├─────────────────────────────────────────────────────────────┤
-│ Layer 2: 准则（Guidelines）                                   │
-│   机制: SKILL.md (type=guideline)                            │
-│   自由度: 中 | 按需加载（Discovery → Full Load）             │
-│   内容: 检查清单 + 边界 + 诚实边界                            │
-│   Token: 列表 ~100, 全文 ~500                                 │
+│ Layer 2: 操作规范 + 任务上下文（引擎注入）                     │
+│   机制: Daemon spawn 时拼装 bootstrap 消息                    │
+│   保证: 每次 spawn 强制注入 | Token: ~1000-2000              │
+│   三段式：                                                    │
+│   ① 角色操作规范模板（executor.md / reviewer.md / planner.md）│
+│      → 固定部分，写死关键操作步骤（scope/output/handoff等）   │
+│      → 变化频率: 很少（moziplus 平台变了才改）                │
+│   ② 项目背景（项目路径/框架/NAS/回测服务）                    │
+│      → 半固定部分，按项目配置                                 │
+│   ③ 任务上下文（truths/artifacts/constraints + depends_on产出）│
+│      → 动态部分，每次 spawn 不同                              │
 ├─────────────────────────────────────────────────────────────┤
-│ Layer 3: 技能（Procedures）                                   │
-│   机制: SKILL.md (type=procedure)                            │
-│   自由度: 高 | 按需加载                                       │
-│   内容: 具体步骤 + 模板 + 脚本 + 示例                        │
-│   Token: 列表 ~100, 全文 ~2000                                │
-├─────────────────────────────────────────────────────────────┤
-│ Layer 4: 引擎注入（Engine Context）                           │
-│   机制: Daemon 构造 L1 bootstrap 消息                        │
-│   自由度: 无 | 每次 spawn 强制注入                           │
-│   内容: 任务上下文 + Review Protocol + Guardrail 配置        │
-│   Token: ~1000                                               │
+│ Layer 3: 参考信息（OpenClaw Skill 被动发现）                  │
+│   机制: OpenClaw Skill 列表注入 system prompt                │
+│   保证: ❌ 不保证触发（锦上添花）                              │
+│   内容: 具体操作方法（回测流程/数据获取/部署步骤等）          │
+│   优化: description 中加触发场景+示例对话+触发词（见D4-8）    │
 └─────────────────────────────────────────────────────────────┘
 ```
 
-#### D4-7：两种 Skill 类型
+**张飞编码时靠什么**：
+- L0+L1：身份和纪律（每轮都有）
+- L2 ① executor.md："读黑板→写scope→执行→写output→写Handoff"（引擎注入，不会忘）
+- L2 ③ 任务上下文："这次要做什么、truths 是什么、前序产出是什么"（引擎注入）
+- L3 quant-backtest Skill：具体回测代码怎么写（自己判断要不要读）
+
+#### D4-7：L2 引擎注入的拼装原则
 
 > **参考实践**：
-> - **oh-my-claudecode**：区分 ralplan（规划型）和 ralph（执行型）
-> - **nuwa-skill**：每个 Skill 有 Agentic Protocol（定义"怎么做"）
+> - **superpowers**：implementer/spec-reviewer/code-quality-reviewer 三个独立 prompt 模板，只包含该角色需要的信息
+> - **open-multi-agent**：`buildTaskPrompt()` 只注入依赖链上的产出（default-deny），不是全量
+> - **GSD**：按 context window 大小自适应（200K 只给任务级，1M 给全量）
 
-| 类型 | 作用 | 加载时机 | 示例 |
-|------|------|---------|------|
-| **guideline（准则型）** | 定义"应该考虑什么"、"边界在哪" | Agent 判断需要时 | 审查准则、编码规范、风控边界 |
-| **procedure（过程型）** | 定义"具体怎么操作" | Agent 判断需要时 | 回测流程、数据获取、部署步骤 |
+**原则：按角色和任务阶段精确注入，不统一拼装，不多不少。**
 
-**区分标准**：
-- guideline 回答"应该注意什么"
-- procedure 回答"具体怎么做"
+| Agent 角色 | 注入内容 | 不注入 |
+|-----------|---------|--------|
+| **执行者** | executor.md + Guardrail 配置 + 任务上下文 | Review Protocol |
+| **审查者** | reviewer.md + Review Protocol + required_reading | Guardrail 配置 |
+| **庞统（规划）** | planner.md + template_components + Plan Checker | Review Protocol |
+| **庞统（裁决）** | adjudicator.md + 正方 comment + 反方 comment | Guardrail 配置 |
+| **反驳者** | rebuttal.md + 审查者 review + ACCEPT/REJECT 指令 | Review Protocol |
+| **Plan Checker** | plan_checker.md + 需求列表 + 拆解方案 | 全部角色模板 |
 
-#### D4-8：Skill 注册和发现
+**拼装逻辑**（Daemon 代码）：
+```python
+def build_bootstrap(agent_id, role, task):
+    parts = []
+    
+    # ① 角色操作规范模板
+    template = load_template(f"prompt_templates/{role}.md")
+    parts.append(template)
+    
+    # ② 项目背景（半固定）
+    parts.append(format_project_context(task))
+    
+    # ③ 任务上下文（动态）
+    parts.append(format_task_context(task))
+    
+    # 按角色追加（只注入该角色需要的）
+    if role == "executor":
+        parts.append(format_guardrails(task.task_type))
+    elif role == "reviewer":
+        parts.append(format_review_protocol(task.review_type))
+        parts.append(format_required_reading(task))
+    elif role == "planner":
+        parts.append(format_template_components())
+    elif role == "rebuttal":
+        parts.append(format_review_to_respond(task))
+    
+    return "\n\n".join(parts)
+```
+
+#### D4-8：L3 Skill 被动触发的优化写法
 
 > **参考实践**：
-> - **GSD**：文件系统扫描 + SKILL.md frontmatter + trigger hints
-> - **Claude Code**：skillListingBudgetFraction 控制 Skill 列表 token 占比
+> - **superpowers code-reviewer**：description 里嵌入 `<example>` 标签，用对话示例教 Agent 触发场景
+> - **wiki-query**：description 里加 Chinese/English triggers 列表
+> - **gstack plan-design-review**：加 `Proactively suggest when...` 指令
+> - **SkillRouter 论文**（2026）：Agent 自主搜索（agentic）比纯关键词/纯语义准确率最高
+
+即使 L3 不保证触发，也要优化写法提高命中率。**moziplus 的 Skill 全部按以下规范写 description**：
 
 ```yaml
-# SKILL.md frontmatter 规范
 ---
 name: quant-backtest
-description: "量化策略回测执行流程。触发：回测、backtest。"
-type: procedure  # procedure | guideline
-version: "1.0.0"
-agents: [zhangfei-dev, jiangwei-infra]  # 可选，空=所有 Agent 可见
-triggers: [回测, backtest, 策略测试]     # 可选，辅助匹配
-related_skills: [data-acquisition, risk-assessment]  # 可选，松耦合推荐
+description: >
+  标准化量化回测技能。
+  
+  When to use: 当需要回测量化策略、验证策略历史表现、测试策略参数时。
+  
+  Chinese triggers: 回测、backtest、策略测试、历史表现验证、参数优化。
+  English triggers: backtest, strategy test, historical performance, parameter optimization.
+  
+  Proactively suggest when: 用户提到策略实现完成后，主动建议运行回测验证。
+  
+  Example: user says "帮我测一下双均线策略" → use quant-backtest skill.
 ---
 ```
 
-**发现机制**：
-1. 系统启动时扫描 skills/ 目录
-2. 读取 frontmatter 构建索引
-3. Agent 每轮推理时注入 Skill 列表（只有 name + description，~100 token/skill）
-4. Agent 用 `read` 工具按需加载全文
+**description 四要素**：
+1. **功能描述**：这个 Skill 干什么
+2. **触发场景**（When to use）：什么情况下该用
+3. **触发词**（Chinese/English triggers）：中英文关键词
+4. **主动建议**（Proactively suggest）：Agent 看到相关场景时主动推荐
 
 #### D4-9：Skill 诚实边界
 
-> **参考实践**：nuwa-skill 的 Agentic Protocol 要求每个 Skill 声明自己做不到什么
+> **参考实践**：nuwa-skill Agentic Protocol 要求每个 Skill 声明自己做不到什么
 
 每个 Skill 必须包含 `## 诚实边界` section：
 
@@ -379,109 +437,167 @@ related_skills: [data-acquisition, risk-assessment]  # 可选，松耦合推荐
 - 复杂策略可能需要拆分为多个 task
 ```
 
-#### D4-10：moziplus 专用 Skill 目录
-
-moziplus 的 Skill 不是放在 OpenClaw 的 skills/ 下，而是放在 moziplus 项目内部：
+#### D4-10：moziplus 目录结构
 
 ```
 sanguo_moziplus/
-  skills/
-    moziplus/
-      blackboard-operations/      # S-01: blackboard.py CLI 使用
-        SKILL.md
-      handoff-write/              # S-03: 写 Handoff Comment
-        SKILL.md
-      handoff-read/               # S-04: 读 Handoff Comment
-        SKILL.md
-      scope-declaration/          # S-10: claim 后写 scope_declaration
-        SKILL.md
-      review-output/              # S-15/17/18/19: 审查者全套
-        SKILL.md
-      review-protocol/            # S-13/14/18/19/20: 审查协议
-        SKILL.md
-      task-creation/              # S-21/22/23: 庞统创建任务
-        SKILL.md
-      task-decomposition/         # S-27: 庞统拆解方法
-        SKILL.md
-      l1-bootstrap/               # S-28: L1 消息构建
-        SKILL.md
-    review_protocols/             # D3-9: 审查协议 YAML
-      plan_review.yaml
-      output_review.yaml
-      guardrail_l2.yaml
-      analysis_review.yaml
-      plan_check.yaml             # D4-3: Plan Checker 协议
-    schemas/                      # D2-12: Schema 文件
-      handoff.schema.json
-      output.schema.json
-      decide.schema.json
-      observe.schema.json
-      review-output.schema.json
-    template_components.yaml      # D4-1: 模板组件库
-    guardrails.yaml               # D3-8: 声明式 Guardrail
+  prompt_templates/              ← L2 ① 角色操作规范（Daemon 读取拼装）
+    executor.md                  ← 执行者操作步骤（读黑板→scope→执行→output→handoff）
+    reviewer.md                  ← 审查者操作步骤（读Protocol→审查→写review）
+    planner.md                   ← 庞统拆解步骤（需求结构化→组件选择→PlanChecker）
+    adjudicator.md               ← 庞统裁决步骤（正方反方→判断→写决策）
+    rebuttal.md                  ← 反驳步骤（读review→ACCEPT/REJECT/PARTIAL）
+    plan_checker.md              ← Plan Checker 步骤（覆盖性→依赖→粒度→铁律）
+  
+  review_protocols/              ← L2 审查协议（Daemon 构造 reviewer bootstrap 时读取）
+    plan_review.yaml             ← 方案审查协议
+    output_review.yaml           ← 产出审查协议
+    guardrail_l2.yaml            ← L2 轻量AI检查协议
+    analysis_review.yaml         ← 分析审查协议
+    plan_check.yaml              ← Plan Checker 协议
+  
+  schemas/                      ← CLI 层 Schema 校验（blackboard.py 读取）
+    handoff.schema.json          ← Handoff 格式校验
+    output.schema.json           ← Output 格式校验
+    decide.schema.json           ← Decision 格式校验
+    observe.schema.json          ← Observation 格式校验
+    review-output.schema.json    ← Review 格式校验
+  
+  template_components.yaml      ← 模板组件库（庞统拆解时参考）
+  guardrails.yaml               ← 声明式 Guardrail（Daemon 执行检查）
+  project_context.yaml          ← L2 ② 项目背景（NAS路径/回测服务/框架）
 ```
 
-#### D4-11：Layer 4 引擎注入的具体内容
+**各目录作用**：
 
-Daemon 每次 spawn Agent 时，在 L1 bootstrap 消息中注入：
+| 目录/文件 | 谁读 | 作用 | 变化频率 |
+|----------|------|------|----------|
+| `prompt_templates/` | Daemon | 按 Agent 角色拼装 bootstrap 消息 | 很少变 |
+| `review_protocols/` | Daemon | 构造审查者的 bootstrap 消息 | 偶尔变 |
+| `schemas/` | blackboard.py CLI | 写入时校验数据格式 | 偶尔变 |
+| `template_components.yaml` | 庞统（通过 L2 注入） | 拆解需求时选择组件 | 偶尔变 |
+| `guardrails.yaml` | Daemon | 自动检查产出 | 偶尔变 |
+| `project_context.yaml` | Daemon | 拼装项目背景信息 | 换项目时变 |
+
+**注意**：Agent 不直接读这些文件——全部由 Daemon 读取后拼装到 bootstrap 消息中注入。
+
+#### D4-11：L2 引擎注入示例（张飞编码场景）
+
+Daemon spawn 张飞时拼装的完整 bootstrap 消息：
 
 ```
-[任务上下文]
+═══ 操作规范（executor.md 模板）═══
+
+你是任务执行者。按以下步骤工作：
+
+## 1. 理解任务
+- 读黑板任务详情（blackboard.py read --task {task_id}）
+- 理解 truths（可观测行为标准）、artifacts（必须产出）、constraints（约束）
+
+## 2. 声明范围
+- 写 scope_declaration（blackboard.py decide --task {task_id} --decider zhangfei-dev）
+- 格式：{"decision": "我计划做什么", "rationale": "为什么", "artifacts": ["路径"]}
+
+## 3. 执行工作
+- 按你的专业能力完成任务
+- 发现风险 → blackboard.py observe --task {task_id} --severity warning
+- 需要协作 → blackboard.py comment --task {task_id} @mention
+
+## 4. 提交产出
+- blackboard.py output --task {task_id} --summary "一句话" --content-path "文件路径"
+
+## 5. 写交接
+- blackboard.py comment --task {task_id} --author zhangfei-dev \
+  --handoff '{"completed":"...", "artifacts":["..."]}'
+
+## 6. 通知引擎
+- 写 inbox 文件通知 Daemon 完成
+
+═══ 项目背景（project_context.yaml）═══
+
+项目：sanguo_quant_live
+框架：vnpy
+NAS 数据：/Volumes/stock/
+回测服务：http://192.168.2.154:8088
+编码规范：类型注解必须、禁止 any、match 现有风格
+
+═══ 任务上下文（黑板动态读取）═══
+
 任务 ID: task-001
-任务标题: 双均线策略回测
-任务状态: pending
-风险等级: standard
-truths: ["回测报告包含收益曲线", "策略代码通过单元测试"]
-artifacts: ["task-001/output.md", "task-001/backtest_report.pdf"]
+任务标题: 实现双均线策略
+truths: ["策略代码通过单元测试", "回测结果包含收益曲线"]
+artifacts: ["task-001/strategy.py", "task-001/backtest_report.pdf"]
 constraints: ["使用 vnpy 框架", "不超过 500 行"]
+risk_level: standard
 
-[Review Protocol]（如果是审查者角色）
-协议: output_review
-审查维度: [requirement_traceability, scope_alignment, correctness, completeness]
-审查方法: pre_commitment → verification → multi_perspective → gap_analysis → self_audit
-多视角: 安全 / 新人 / 运维
-对抗性指令: [DO NOT trust the report, ...]
-输出 Schema: review-output.schema.json
+═══ 前序信息（depends_on 产出）═══
 
-[Guardrail 配置]（如果是执行者角色）
-output_guardrails:
-  - file_exists (blocking)
-  - json_valid (blocking)
-  - artifacts_exist (blocking)
+[赵云 Handoff] 完成了分钟线数据下载，产出 task-000/data/
+数据路径: /Volumes/stock/min_data/IF888.csv
 
-[前序信息]
-最近 3 条 comments:
-  [pangtong] 任务已创建，请开始工作
-  [zhangfei] ## Handoff: 完成了策略编码，产出 task-001/strategy.py
-最新 output: task-001/strategy.py (summary: 双均线策略实现)
+═══ 可选参考 ═══
+
+如果需要具体操作方法，用 read 加载：
+- 编码：~/.openclaw/skills/coding-implementation/SKILL.md
+- 回测：~/.openclaw/skills/quant-backtest/SKILL.md
 ```
 
-这些内容是 Daemon 根据 tasks 表 + reviews 表 + comments 表 + guardrails.yaml + review_protocols/ 动态拼装的。Agent 不需要自己找这些信息。
+**对比审查者（司马懿）收到的 bootstrap**：
+
+```
+═══ 操作规范（reviewer.md 模板）═══
+
+你是质量审查者。按 Review Protocol 执行审查：
+
+## 审查步骤
+1. 预判：先不读产出，预测 3-5 个最可能出问题的点
+2. 验证：读实际产出（不是报告），逐条验证每个 truth
+3. 多视角：从安全/新人/运维三个角度看产出
+4. 缺口分析：不只看"什么有问题"，还看"什么缺失了"
+5. 自审：给每个 finding 打 confidence，低 confidence 降级
+
+## 写 Review
+- blackboard.py review --task {task_id} --verdict [approved|rejected|needs_revision] ...
+
+[... 对抗性指令 ...]
+
+═══ Review Protocol（output_review.yaml）═══
+
+[审查维度、方法、输出 Schema 等详细协议内容]
+
+═══ 任务上下文 ═══
+[同上]
+
+═══ Required Reading ═══
+- 执行者 scope_declaration: ...
+- 产出物: task-001/strategy.py
+- must_haves truths: [...]
+```
 
 ---
 
-## 6. 和现有设计的对齐检查
+## 7. 和现有设计的对齐检查
 
 | 已有设计 | 课题4 补充 | 一致性 |
 |---------|-----------|--------|
 | §3.2 tasks 表 schema | D4-1 模板组件输出 → tasks 写入 | ✅ truths/artifacts/constraints/risk_level/depends_on 对齐 |
 | §9.2 分级审查矩阵 | D4-4 复杂度→粒度控制 | ✅ risk_level 在创建时标注 |
 | §4.2 Tick+Inbox | D4-1 Step 4 创建任务后 Daemon tick 检测 | ✅ 创建是事件源 |
-| §9.4 Review Protocol Registry | D4-10 moziplus Skill 目录 | ✅ review_protocols/ 在 Skill 目录下 |
+| §9.4 Review Protocol Registry | D4-10 review_protocols/ 目录 | ✅ Daemon 构造审查者 bootstrap 时读取 |
 | §9.9 Agent vs Subagent | D4-3 Plan Checker 走 Subagent | ✅ 无身份一次性检查 |
-| Skill TODO 28项 | D4-10 Skill 目录结构 | ✅ S-01~S-28 有归属目录 |
+| Skill TODO 28项 | D4-10 prompt_templates/ 承载关键操作 | ✅ S-01~S-28 的关键操作写死在模板中 |
 
-## 7. 遗留 TODO
+## 8. 遗留 TODO
 
 | # | 待解决事项 | 归属 | 说明 |
 |---|----------|------|------|
-| T4-1 | template_components.yaml 完整定义 | Phase 2 | 所有 phase 组件的详细定义 |
-| T4-2 | Plan Checker 的 subagent 实现 | Phase 2 | plan_check.yaml + spawn 逻辑 |
-| T4-3 | 需求结构化的 Skill（庞统） | Phase 2 | S-21 task-creation Skill |
-| T4-4 | 拆解方法的 Skill（庞统） | Phase 2 | S-27 task-decomposition Skill |
-| T4-5 | L1 bootstrap 消息拼装逻辑（Daemon） | Phase 1 | S-28 + Daemon 代码 |
-| T4-6 | Skill 注册/发现机制工程化 | Phase 2 | frontmatter 扫描 + 索引构建 |
-| T4-7 | 铁律 Hook 实现 | Phase 1 | OpenClaw Plugin Hook |
-| T4-8 | 现有 42 个 Skill 打标（guideline/procedure） | Phase 2 | 分类 + 加 type 字段 |
-| T4-9 | Skill 诚实边界补充 | Phase 2 | 每个 Skill 加 ## 诚实边界 |
-| T4-10 | Skill 测试框架 | Phase 3 | 结构测试 + 干跑测试 + 场景测试 |
+| T4-1 | template_components.yaml 完整定义 | Phase 2 | 所有 phase 组件 + custom 类型 |
+| T4-2 | Plan Checker 的 plan_check.yaml 实现 | Phase 2 | 验证维度定义 |
+| T4-3 | prompt_templates/ 编写（executor/reviewer/planner/rebuttal/adjudicator/plan_checker） | Phase 1 | 6个模板文件 |
+| T4-4 | project_context.yaml 定义 | Phase 1 | 项目背景配置 |
+| T4-5 | Daemon build_bootstrap() 拼装逻辑实现 | Phase 1 | 按 role + task 拼装 |
+| T4-6 | 铁律 Hook 实现（L0） | Phase 1 | OpenClaw Plugin Hook agent_turn_prepare |
+| T4-7 | 现有 Skill description 优化（加四要素） | Phase 2 | 所有 Skill 加 When to use / triggers / Proactively suggest |
+| T4-8 | Skill 诚实边界补充 | Phase 2 | 每个 Skill 加 ## 诚实边界 |
+| T4-9 | Skill 测试框架 | Phase 3 | 结构测试 + 干跑测试 + 场景测试 |
+| T4-10 | Skill 进化/蒸馏机制 | Phase 3 | 参考 nuwa-skill 半自动化创建和更新 Skill |