From 3685b323057799f12ee37a13c70fa102ed75e194 Mon Sep 17 00:00:00 2001 From: cfdaily Date: Fri, 15 May 2026 22:54:57 +0800 Subject: [PATCH] auto-sync: 2026-05-15 22:54:57 --- .../topic4-decomposition-skill-proposal.md | 376 ++++++++++++------ 1 file changed, 246 insertions(+), 130 deletions(-) diff --git a/docs/design/topic4-decomposition-skill-proposal.md b/docs/design/topic4-decomposition-skill-proposal.md index 27b9d06..b16c9e4 100644 --- a/docs/design/topic4-decomposition-skill-proposal.md +++ b/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 里嵌入 `` 标签，用对话示例教 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 |