# 课题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 | 结构测试 + 干跑测试 + 场景测试 |