diff --git a/docs/design/topic4-decomposition-skill-proposal.md b/docs/design/topic4-decomposition-skill-proposal.md new file mode 100644 index 0000000..27b9d06 --- /dev/null +++ b/docs/design/topic4-decomposition-skill-proposal.md @@ -0,0 +1,487 @@ +# 课题4 设计方案：智能拆解机制 + Skill 体系工程落地 + +**作者**: 庞统士元 +**日期**: 2026-05-15 +**状态**: 方案待确认 +**前置**: 课题1/2/3 已结题 +**调研报告**: `docs/research/v2.6-research-04-decomposition-skills.md` + +--- + +## Part A：智能拆解机制 + +### 1. 设计目标 + +v1.0 的拆解是"关键词匹配 → 固定 DAG 模板"，问题是： +- 模板太死板（5个固定DAG），无法根据需求动态调整 +- 关键词匹配粗糙，复杂需求容易匹配错模板 +- 庞统拆解时靠 LLM 理解，没有结构化引导 + +课题4要解决：**庞统收到用户需求后，如何把它变成黑板上的任务（含依赖关系、角色分配、风险等级）。** + +### 2. 和课题1/2/3的关系 + +课题1-3 已经定义了"任务在黑板上长什么样"（tasks 表 schema、状态机、reviews 表、Guardrail 配置）。课题4定义的是"任务怎么被创建出来"。 + +``` +课题4（创建） → 课题2（触发执行） → 课题3（审查） → 课题1（失败处理） +``` + +### 3. 设计决策 + +#### D4-1：模板组件库替代固定 DAG + +> **参考实践**： +> - **MetaGPT**：SOP 自动链 + `_watch` 声明式订阅，不是固定 DAG +> - **get-shit-done**：discuss→plan→execute→verify→ship 五阶段，但每阶段内部灵活 +> - **open-multi-agent**：Goal → DAG 自动分解，按 complexity 决定粒度 +> - **v1.0**：5 个固定模板（full_role_development / circular_review_test / multi_stage_review / data_acquisition / multi_edge_discussion） + +**方案**：不是 5 个完整 DAG，而是**模板组件库（Phase Components）**。庞统按需组合。 + +```yaml +# template_components.yaml +components: + research: + trigger: "需要调研/分析" + mandatory: false + steps: + - id: lit_search + name: "资料调研" + agent: zhaoyun-data + output: "research_report.md" + - id: analysis + name: "分析总结" + agent: pangtong-fujunshi + output: "analysis.md" + + design: + trigger: "需要架构/设计" + mandatory: false + steps: + - id: arch_design + name: "架构设计" + agent: pangtong-fujunshi + output: "design.md" + - id: design_review + name: "设计评审" + agent: simayi-challenger + review_type: plan_review + + coding: + trigger: "需要编码/实现" + mandatory: false + steps: + - id: implement + name: "编码实现" + agent: zhangfei-dev + output: "code/" + - id: code_review + name: "代码评审" + agent: simayi-challenger + review_type: output_review + + data: + trigger: "需要数据获取/处理" + mandatory: false + steps: + - id: data_acquire + name: "数据获取" + agent: zhaoyun-data + output: "data/" + - id: data_validate + name: "数据验证" + agent: zhaoyun-data + + deploy: + trigger: "需要部署" + mandatory: false + steps: + - id: deploy + name: "部署" + agent: jiangwei-infra + output: "deploy_log.md" + - id: deploy_verify + name: "部署验证" + agent: jiangwei-infra + + risk_control: + trigger: "涉及实盘/资金/策略" + mandatory: true # 触发条件满足时强制包含 + steps: + - id: risk_check + name: "风控检查" + agent: guanyu-dev + + review: + trigger: "always" + mandatory: true # 铁律 IR-1 + steps: + - id: final_review + name: "最终审查" + agent: simayi-challenger + review_type: final_review +``` + +**庞统的拆解流程**： + +``` +Step 1：需求结构化 + - 分析用户输入，提取需求列表 + - 每个需求标注类型（数据/编码/分析/部署/风控） + - 评估复杂度（简单/中等/复杂） + - 隐含需求挖掘（如用户说"回测"→ 隐含需要数据获取） + - 产出：structured_requirements → 写入黑板 decisions 表 + +Step 2：组件选择 + 组合 + - 根据需求类型，从组件库选择需要的 phases + - 检查 mandatory 组件是否被遗漏 + - 组合 phases，排列依赖关系 + - AI 增强：增删调整（如"这次数据已有，跳过 data_acquire"） + - 产出：draft_plan → 写入黑板 decisions 表 + +Step 3：Plan Checker 验证 + - 独立验证（不是庞统自己验证自己） + - 检查项： + - 覆盖性：每个需求是否被至少一个 step 覆盖 + - 依赖性：step 依赖是否合理（无环、无遗漏前置） + - 粒度性：step 是否过大/过小 + - 铁律：IR-1（每任务至少2 Agent）是否满足 + - 风险：risk_level 是否合理，高风险任务是否有对抗审查 + - 不通过 → 回 Step 2 调整（最多 2 轮） + - 通过 → 进入 Step 4 + +Step 4：任务创建 + - 将 plan 转为黑板 tasks + - 每个 step → 一个 task（含 truths / artifacts / constraints / risk_level / assigned_to） + - 依赖关系 → tasks 的 depends_on 字段 + - 庞统在黑板上写 scope_declaration + - 产出：tasks 写入黑板 → Daemon 检测 → 开始执行 +``` + +#### D4-2：需求结构化的输出格式 + +庞统分析用户需求后，输出结构化需求到黑板： + +```json +{ + "original_input": "实现一个双均线策略的回测", + "requirements": [ + { + "id": "req-001", + "description": "获取标的分钟线数据", + "type": "data", + "acceptance_criteria": "数据文件存在于 NAS 指定路径", + "complexity": "simple", + "implicit": true + }, + { + "id": "req-002", + "description": "编写双均线策略逻辑", + "type": "coding", + "acceptance_criteria": "策略代码通过单元测试", + "complexity": "medium", + "implicit": false + }, + { + "id": "req-003", + "description": "回测并生成报告", + "type": "analysis", + "acceptance_criteria": "回测报告包含收益曲线和关键指标", + "complexity": "medium", + "implicit": false + } + ], + "inferred_components": ["data", "coding", "analysis"], + "risk_level": "standard", + "estimated_tasks": 3 +} +``` + +#### D4-3：Plan Checker 独立验证 + +> **参考实践**： +> - **superpowers**：plan-document-reviewer subagent 独立验证方案 +> - **oh-my-claudecode Critic**：预判→验证→自审五阶段 +> - **get-shit-done**：Scope Reduction Detection（完成后反向检查覆盖） + +Plan Checker 是一个 Subagent（不需要 Agent 身份），Daemon spawn 后执行： + +```yaml +# review_protocols/plan_check.yaml +name: plan_check +description: "验证庞统的拆解方案是否合理" + +dimensions: + - id: coverage + description: "每个需求是否被至少一个 task 覆盖" + weight: critical + method: "需求 ID → task ID 映射矩阵，检查是否有遗漏" + + - id: dependency + description: "依赖是否合理" + weight: critical + method: "拓扑排序检查无环，前置是否完整" + + - id: granularity + description: "粒度是否合适" + weight: major + method: "检查每个 task 的 truths 是否是一个 Agent 一次 spawn 能完成的" + + - id: iron_rules + description: "铁律是否满足" + weight: critical + method: "IR-1: 至少 2 Agent 参与；IR-2: 每个 task 有 truths" + + - id: risk_alignment + description: "风险等级是否合理" + weight: major + method: "涉及资金/部署 → high；纯分析 → research" + +output_schema: "schemas/plan-check-output.schema.json" +verdict_options: ["approved", "needs_revision"] +``` + +#### D4-4：复杂度驱动的粒度控制 + +> **参考实践**： +> - **open-multi-agent**：按 complexity 决定是否拆分子任务 +> - **wanman**：Token 预算控制执行深度 + +| 复杂度 | 判断标准 | 拆解策略 | truths 定义 | +|--------|---------|---------|------------| +| **simple** | 单一文件、单一操作、< 50 行 | 1 个 task | 1-2 条 truths | +| **medium** | 多文件、有依赖、需要验证 | 1-3 个 task + 依赖 | 每个 2-3 条 truths | +| **complex** | 跨模块、多角色、需要调研 | 多 phase 组件组合 | 每个 3-5 条 truths | + +**粒度自检规则**（庞统的 Skill 中定义）： +- 一个 task 的 truths > 5 条 → 拆分 +- 一个 task 需要跨 3+ 角色 → 拆分 +- 一个 task 预计 > 30 分钟 → 拆分 + +#### D4-5：用户确认点 + +> **参考实践**： +> - **get-shit-done**：discuss phase 是必须的用户确认步骤 +> - **v2.0 PRD**：Phase 1 需求探索（苏格拉底对话） + +不是每步都问用户，但在关键节点确认： + +| 检查点 | 触发条件 | 用户看到什么 | +|--------|---------|------------| +| 需求确认 | Step 1 完成后 | 结构化需求列表 + 隐含需求 | +| 方案确认 | Step 2 完成后（complex 任务） | 任务列表 + 依赖关系 + 预估时间 | + +simple 任务跳过方案确认，直接创建。complex 任务必须确认。 + +--- + +## Part B：Skill 体系工程落地 + +### 4. 设计目标 + +三个课题产出了大量"Agent 需要知道怎么做"的内容（28 项 Skill TODO），需要一个系统的 Skill 体系来承载。 + +### 5. 设计决策 + +#### D4-6：五层 Skill 架构 + +> **参考实践**： +> - **Claude Code**：4 层渐进式加载（Discovery → Matching → Full Load → Overflow） +> - **oh-my-claudecode**：三层组合（Execution + Enhancement + Guarantee） +> - **nuwa-skill**：5 阶段蒸馏 + 检查点 + 诚实边界 +> - **v3.1 Skill 体系设计**（已确认）：Hook 铁律 + Agent 角色 + 通用 Skill + moziplus 注入 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Layer 0: 铁律（Iron Rules） │ +│ 机制: OpenClaw Hook before_prompt_build │ +│ 自由度: 无 | 每轮强制注入 │ +│ 内容: IR-1~IR-5（每个 Agent 可定制） │ +│ Token: ~500 │ +├─────────────────────────────────────────────────────────────┤ +│ Layer 1: 角色（Agent Identity） │ +│ 机制: SOUL.md + IDENTITY.md + AGENTS.md │ +│ 自由度: 无 | 全量加载 │ +│ 内容: 角色定义 + 行为准则 + 记忆 │ +│ Token: ~2000 │ +├─────────────────────────────────────────────────────────────┤ +│ Layer 2: 准则（Guidelines） │ +│ 机制: SKILL.md (type=guideline) │ +│ 自由度: 中 | 按需加载（Discovery → Full Load） │ +│ 内容: 检查清单 + 边界 + 诚实边界 │ +│ Token: 列表 ~100, 全文 ~500 │ +├─────────────────────────────────────────────────────────────┤ +│ Layer 3: 技能（Procedures） │ +│ 机制: SKILL.md (type=procedure) │ +│ 自由度: 高 | 按需加载 │ +│ 内容: 具体步骤 + 模板 + 脚本 + 示例 │ +│ Token: 列表 ~100, 全文 ~2000 │ +├─────────────────────────────────────────────────────────────┤ +│ Layer 4: 引擎注入（Engine Context） │ +│ 机制: Daemon 构造 L1 bootstrap 消息 │ +│ 自由度: 无 | 每次 spawn 强制注入 │ +│ 内容: 任务上下文 + Review Protocol + Guardrail 配置 │ +│ Token: ~1000 │ +└─────────────────────────────────────────────────────────────┘ +``` + +#### D4-7：两种 Skill 类型 + +> **参考实践**： +> - **oh-my-claudecode**：区分 ralplan（规划型）和 ralph（执行型） +> - **nuwa-skill**：每个 Skill 有 Agentic Protocol（定义"怎么做"） + +| 类型 | 作用 | 加载时机 | 示例 | +|------|------|---------|------| +| **guideline（准则型）** | 定义"应该考虑什么"、"边界在哪" | Agent 判断需要时 | 审查准则、编码规范、风控边界 | +| **procedure（过程型）** | 定义"具体怎么操作" | Agent 判断需要时 | 回测流程、数据获取、部署步骤 | + +**区分标准**： +- guideline 回答"应该注意什么" +- procedure 回答"具体怎么做" + +#### D4-8：Skill 注册和发现 + +> **参考实践**： +> - **GSD**：文件系统扫描 + SKILL.md frontmatter + trigger hints +> - **Claude Code**：skillListingBudgetFraction 控制 Skill 列表 token 占比 + +```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] # 可选，松耦合推荐 +--- +``` + +**发现机制**： +1. 系统启动时扫描 skills/ 目录 +2. 读取 frontmatter 构建索引 +3. Agent 每轮推理时注入 Skill 列表（只有 name + description，~100 token/skill） +4. Agent 用 `read` 工具按需加载全文 + +#### D4-9：Skill 诚实边界 + +> **参考实践**：nuwa-skill 的 Agentic Protocol 要求每个 Skill 声明自己做不到什么 + +每个 Skill 必须包含 `## 诚实边界` section： + +```markdown +## 诚实边界 +- 本 Skill 不覆盖实盘交易逻辑（实盘请参考 live-trading Skill） +- 性能问题需要实际测试数据，纯代码审查无法确认 +- 复杂策略可能需要拆分为多个 task +``` + +#### D4-10：moziplus 专用 Skill 目录 + +moziplus 的 Skill 不是放在 OpenClaw 的 skills/ 下，而是放在 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 +``` + +#### D4-11：Layer 4 引擎注入的具体内容 + +Daemon 每次 spawn Agent 时，在 L1 bootstrap 消息中注入： + +``` +[任务上下文] +任务 ID: task-001 +任务标题: 双均线策略回测 +任务状态: pending +风险等级: standard +truths: ["回测报告包含收益曲线", "策略代码通过单元测试"] +artifacts: ["task-001/output.md", "task-001/backtest_report.pdf"] +constraints: ["使用 vnpy 框架", "不超过 500 行"] + +[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 + +[Guardrail 配置]（如果是执行者角色） +output_guardrails: + - file_exists (blocking) + - json_valid (blocking) + - artifacts_exist (blocking) + +[前序信息] +最近 3 条 comments: + [pangtong] 任务已创建，请开始工作 + [zhangfei] ## Handoff: 完成了策略编码，产出 task-001/strategy.py +最新 output: task-001/strategy.py (summary: 双均线策略实现) +``` + +这些内容是 Daemon 根据 tasks 表 + reviews 表 + comments 表 + guardrails.yaml + review_protocols/ 动态拼装的。Agent 不需要自己找这些信息。 + +--- + +## 6. 和现有设计的对齐检查 + +| 已有设计 | 课题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.9 Agent vs Subagent | D4-3 Plan Checker 走 Subagent | ✅ 无身份一次性检查 | +| Skill TODO 28项 | D4-10 Skill 目录结构 | ✅ S-01~S-28 有归属目录 | + +## 7. 遗留 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 | 结构测试 + 干跑测试 + 场景测试 |