sanguo_moziplus_v2/docs/research/v2.6-research-04-decomposition-skills.md

# 调研报告：智能拆解机制 + Skill 体系

**日期**: 2026-05-15
**作者**: 庞统士元 (pangtong-fujunshi)
**版本**: v2.6-research-04
**用途**: moziplus v2.6 AI Native DevOps 平台设计参考

---

## 目录

- [课题 4：智能拆解机制](#课题-4智能拆解机制)
  - [已有经验（知识库/wiki）](#已有经验知识库wiki)
  - [业界优秀实践对比表](#业界优秀实践对比表课题4)
  - [约束 vs 灵活性分析](#约束-vs-灵活性分析)
  - [推荐方案（结合 AI Native 目标）](#推荐方案结合-ai-native-目标课题4)
- [课题 8：Skill 体系工程落地](#课题-8skill-体系工程落地)
  - [已有经验（知识库/wiki + OpenClaw 现有 Skill）](#已有经验知识库wiki--openclaw-现有-skill)
  - [业界优秀实践对比表](#业界优秀实践对比表课题8)
  - [Skill 三层约束工程化方案](#skill-三层约束工程化方案)
  - [推荐方案（结合 AI Native 目标）](#推荐方案结合-ai-native-目标课题8)

---

# 课题 4：智能拆解机制

## 已有经验（知识库/wiki）

### moziplus v1.0 现有拆解机制

moziplus v1.0 采用 **"模板 + 自然语言描述"** 的混合拆解方式：

1. **CLI create 接口**：接收 `--description "需求描述"` + `--template 模板名`
2. **模板库**：5 个预定义模板（`full_role_development`, `circular_review_test`, `multi_stage_review`, `data_acquisition`, `multi_edge_discussion`）
3. **自动匹配**：不传 template 时，按关键词优先级匹配模板（循环+测试 → 多阶段 → 讨论 → 数据 → 兜底 full_role）
4. **每个模板定义了固定的 DAG 图**：节点、边、角色分配、output_schema

**局限性**：
- 模板是固定的 DAG 结构，无法根据需求动态调整节点和边
- 关键词匹配太粗糙，复杂需求容易匹配到错误模板
- 庞统拆解时完全靠 LLM 理解，没有结构化引导
- 无法动态增减步骤（如"这次不需要数据获取"）

### 知识库中已积累的相关实践

从知识库中获取的 6 个相关项目（get-shit-done、wanman、nuwa-skill、oh-my-claudecode、open-multi-agent、TradingAgents），为本次调研提供了丰富的参考素材。

---

## 业界优秀实践对比表（课题4）

### 1. MetaGPT：SOP 自动链 + _watch 声明式订阅

**核心理念**：将人类软件公司的 SOP（标准操作流程）编码为 prompt 序列，Agent 之间通过发布-订阅自动链接。

**拆解机制**：
- **SOP 流水线**：ProductManager → Architect → ProjectManager → Engineer，每步自动触发
- **_watch 声明式订阅**：每个 Role 通过 `self._watch({UpstreamAction})` 订阅上游产出，上游完成后自动触发下游
- **Action 基类**：每个 Action 接收 `with_messages`（上游消息），返回 `Message`（结构化产出）
- **Environment 对象**：所有 Agent 放入同一个 Environment，自动调度订阅关系

```python
class Architect(Role):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.set_actions([WriteDesign])
        self._watch({WritePRD})  # 订阅 PRD 产出，自动触发设计

class Engineer(Role):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.set_actions([WriteCode])
        self._watch({WriteDesign})  # 订阅设计产出，自动触发编码
```

**优点**：
- SOP 流水线保证步骤不遗漏
- _watch 机制实现松耦合的自动链
- 每步产出结构化文档（PRD→设计→任务→代码），便于下游消费

**缺点**：
- SOP 是固定的，灵活性有限
- 不适合非软件开发场景
- 粒度在 Role 级别，不能在同一 Role 内动态调整

### 2. get-shit-done：discuss→plan→execute→verify→ship 流程

**核心理念**：Spec-driven development，通过上下文工程解决 context rot（上下文窗口填满后质量退化）。

**拆解机制**：
- **5 阶段流水线**：new-project → discuss-phase → plan-phase → execute-phase → verify
- **Fresh Context Per Agent**：每个子任务 spawn 新 agent（独立上下文窗口），避免 context rot
- **File-Based State**：所有状态存储在 `.planning/` 目录（PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md）
- **Thin Orchestrator**：Workflow 文件不做重活，只加载上下文、spawn agent、收集结果
- **Progressive Disclosure**：workflow 按需加载子模块（modes/、templates/），避免一次性注入过多内容
- **Agent Size-Budget**：XL(1700行)、Large(1500行)、Default(1000行)，防止 prompt 过长

```
用户 → /gsd-new-project → 初始化
    → /gsd-discuss → 需求讨论（questioning → dream extraction）
    → /gsd-plan → 规划（analyst → architect → critic → plan checker）
    → /gsd-execute → 执行（按 phase 分任务，独立 agent 执行）
    → /gsd-verify → 验证（多维度自动化验证）
```

**优点**：
- 分阶段拆解，每阶段有明确产出
- 需求讨论阶段（discuss）会做 dream extraction，挖掘隐含需求
- Plan checker agent 专门验证计划的完整性
- Scope reduction detection 防止规划时静默丢弃需求

**缺点**：
- 仍然是预定义的 5 阶段流程
- 不适合非软件项目
- Token 成本高（每任务独立上下文窗口）

### 3. wanman：Explore→Evaluate→Execute 三阶段 + Token 预算

**核心理念**：Agent Matrix 框架，通过 JSON-RPC Supervisor 协调多个 Claude Code/Codex 子进程。

**拆解机制**：
- **Agent 配置**：JSON 文件定义 agents（name, lifecycle, model tier, systemPrompt）
- **三种生命周期**：`24/7`（持续运行）、`on-demand`（按需触发）、`idle_cached`（空闲但保持上下文）
- **Task Pool**：支持 `--after` 依赖的任务池，自然形成 DAG
- **Initiative**：长期目标管理，将目标分解为任务
- **Capsule**：变更胶囊，追踪每个 agent 的产出变更
- **Per-agent 隔离**：每个 agent 独立 worktree + 独立 $HOME，互不干扰

**关键设计**：
- **CEO Agent** 负责全局协调和最终决策
- **Steer/Follow-up 优先级**：消息分为中断性指令和跟进性消息
- **共享 Skill 发现**：agents 自动发现 `~/.claude/skills/` 下的共享 skill
- **Skill Snapshot**：运行时将 skill 文件 materialize 为快照

**优点**：
- CEO 模式适合需要集中决策的场景
- Task Pool + `--after` 依赖天然支持 DAG 调度
- Agent 隔离保证稳定性

**缺点**：
- 拆解依赖 CEO agent 的 LLM 能力
- 没有结构化的拆解模板
- Token 预算管理需要手动配置

### 4. ChatDev：角色流水线 + 环检测

**核心理念**：通过 Chat Chain 组织多角色对话，每个 phase 由两个角色（如 CTO + PM）的对话完成。

**拆解机制**：
- **Chat Chain**：将软件开发分解为有序的 phases（Demand Analysis → Language Model → Coding → Code Complete → Code Review → Testing → Environment Configuration）
- **角色配对**：每个 phase 由两个角色对话完成（CTO↔PM, CTO↔Programmer, CTO↔Art Designer, etc.）
- **Communicative Dehallucination**：通过角色间的质疑和验证减少幻觉
- **环检测**：当角色陷入死循环（反复说"我同意"）时自动打破
- **ChatChain Visualizer**：可视化查看每个 phase 的对话和产出

```
用户需求 → [Demand Analysis: CEO↔CTO]
         → [Language Design: CTO↔CPO]
         → [Coding: CTO↔Programmer]
         → [Code Complete: Programmer↔CTO]
         → [Code Review: Programmer↔Reviewer]
         → [Testing: CTO↔Tester]
         → [Environment Config: CTO↔CTO]
```

**优点**：
- 角色配对确保每步都有质疑和验证（类似我们的"做+挑战"）
- Chat Chain 是半结构化的：phase 顺序固定，但对话内容自由
- 环检测是实用的工程优化

**缺点**：
- Phase 顺序完全固定
- 角色配对固定，不能动态调整
- 只适用于软件开发

### 5. TradingAgents：动态图构建

**核心理念**：模拟真实交易公司的协作结构，通过 `selected_analysts` 参数动态决定图的节点和边。

**拆解机制**：
- **动态图构建**：`selected_analysts` 参数决定激活哪些分析师（Fundamental, Sentiment, Technical, News）
- **结构化输出**：Research Manager 汇总分析师报告，Trader 做决策，Portfolio Manager 管理仓位
- **LangGraph checkpoint**：支持断点续跑
- **Decision Log**：持久化决策记录

```
selected_analysts = ["fundamental", "sentiment", "technical"]
    ↓ 自动构建图:
    Fundamental Analyst → Research Manager
    Sentiment Analyst   → Research Manager
    Technical Analyst   → Research Manager
                         Research Manager → Trader → Portfolio Manager
```

**优点**：
- **真正的动态图**：参数决定节点和边，不是固定模板
- 适合不同复杂度的任务（简单任务少选 analyst，复杂任务全选）
- 结构清晰：分析 → 汇总 → 交易 → 仓位管理

**缺点**：
- 动态范围有限（只能选/不选预定义的 analyst 类型）
- 不能动态创建新的 agent 类型
- 没有拆解验证机制

### 6. open-multi-agent：Goal → DAG 自动分解

**核心理念**：Goal-first，用户描述目标，Coordinator 自动分解为 Task DAG。

**拆解机制**：
- **`runTeam(team, goal)`**：一个调用，Coordinator 自动分解目标为任务 DAG
- **自动并行化**：无依赖的任务自动并行执行
- **混合 Provider**：10+ LLM 适配器，不同 agent 可用不同模型
- **Observability**：`onProgress` 事件流 + `onTrace` span + HTML dashboard
- **Loop Detection**：内置循环检测
- **Token Budget**：支持 token 预算管理
- **Context Compaction**：上下文压缩

```
goal: "Build a REST API"
    ↓ Coordinator 自动分解:
    task: design-api (no deps)
    task: implement-handlers (after design-api)
    task: scaffold-tests (after design-api, parallel with implement)
    task: review-code (after implement + tests)
```

**优点**：
- **最接近"AI Native 拆解"的理想**：目标→DAG 全自动
- 不需要预定义模板
- 依赖关系自动解析 + 并行化

**缺点**：
- 拆解质量完全依赖 Coordinator LLM 能力
- 没有拆解结果的验证/挑战机制
- 对于复杂领域任务，可能遗漏关键步骤

### 7. guidance-aws / Databricks：Supervisor 模式

**核心理念**：Supervisor Agent 负责意图分析 + Agent 选择，单次 LLM 调用同时完成两个决策。

**拆解机制**：
- **Supervisor Agent**：接收用户输入，一次性完成意图识别 + Agent 选择 + 参数提取
- **Hybrid Routing**：确定性快速路径 + LLM fallback（生产系统推荐混合路由）
- **Message Queue**：Agent 间通过消息队列通信
- **Human-in-the-loop**：支持无缝衔接人工介入

```
用户输入 → Supervisor (单次 LLM)
    → 意图分析: "这是一个编码任务"
    → Agent 选择: "分配给 Developer Agent"
    → 参数提取: {language: "Python", framework: "FastAPI"}
    → 路由到 Developer Agent
```

**优点**：
- 单次 LLM 调用效率高
- Hybrid Routing 平衡速度和灵活性
- 生产级设计

**缺点**：
- Supervisor 是单点，能力决定上限
- 没有拆解结果的验证

### 8. Claude Code 的 Task Decomposition

**核心理念**：隐式分解，通过 Headless Mode + Subagent 自动完成。

**拆解机制**：
- **Headless Mode**：`claude -p "task"` 非交互模式，自动处理
- **Task Tool**：Agent 可 spawn 子 agent 处理子任务
- **TodoRead/TodoWrite**：内置 todo 管理，Agent 自己创建和追踪子任务
- **Skills**：通过 SKILL.md 注入领域知识，引导 Agent 的分解策略
- **Progressive Context Loading**：只加载 frontmatter（~100 token），匹配后才加载全文

**优点**：
- 拆解完全由 Agent 自主完成，不需要显式定义
- Todo 系统让 Agent 自己追踪分解结果
- Skill 注入可以引导分解方向

**缺点**：
- 没有结构化约束，质量不稳定
- 没有"拆解验证"机制

---

## 约束 vs 灵活性分析

### 核心矛盾

| 维度 | 固定模板 | 完全自由 | AI Native 理想 |
|------|---------|---------|---------------|
| **步骤完整性** | ✅ 保证不遗漏 | ❌ 可能遗漏 | ✅ AI 确保覆盖 |
| **灵活性** | ❌ 死板 | ✅ 适应任何场景 | ✅ 根据需求动态调整 |
| **可预测性** | ✅ 行为可预期 | ❌ 不确定 | ⚠️ 有约束的灵活 |
| **粒度控制** | ❌ 固定粒度 | ⚠️ 不稳定 | ✅ AI 根据复杂度调整 |
| **调试性** | ✅ 容易定位问题 | ❌ 难复现 | ✅ 有检查点 |

### 五个关键问题的回答

#### Q1: 拆解模板 vs 动态生成的权衡点在哪？

**结论：模板作为骨架，AI 负责填充和调整。**

- **简单/常见任务**：直接用模板（如"开发一个新策略"→ `full_role_development`）
- **复杂/独特任务**：AI 动态生成 DAG，但必须经过验证
- **混合任务**：选择最接近的模板，AI 增减节点和边

**权衡点判断标准**：

| 需求特征 | 建议策略 | 示例 |
|---------|---------|------|
| 需求清晰 + 场景常见 | 直接模板 | "开发MACD策略" |
| 需求清晰 + 场景不常见 | 模板 + AI 调整 | "对比3个平台的回测结果" |
| 需求模糊 + 场景常见 | AI 分析 + 模板对齐 | "优化我的交易系统" |
| 需求模糊 + 场景不常见 | AI 完全动态生成 + 强验证 | "研究新因子并整合到生产" |

#### Q2: 是否有"模板 + AI 增强"的混合模式？

**是的，这是最佳方案。** 参考：

| 项目 | 混合模式 |
|------|---------|
| MetaGPT | SOP 骨架（固定角色流水线） + _watch 动态订阅 |
| GSD | 5 阶段骨架（固定流水线） + discuss dream extraction（AI 挖掘隐含需求） |
| TradingAgents | 预定义 analyst 类型（固定节点池） + `selected_analysts` 动态选择 |
| open-multi-agent | Goal → DAG（AI 动态生成） + fixed team definition（固定角色池） |

**推荐混合模式**：
1. **模板库提供骨架**：5-10 个场景模板，每个定义了典型节点和边
2. **AI 负责三件事**：
   - 选择最合适的模板
   - 增减节点和边（如"这次不需要风控审核"或"加一个数据验证步骤"）
   - 调整粒度（简单任务合并节点，复杂任务拆细）
3. **结构约束**：模板定义了"必须有的节点"（如 review 节点不可删除）

#### Q3: 拆解结果是否需要验证/挑战？

**必须！这是所有项目的共识。** 参考：

| 项目 | 验证机制 |
|------|---------|
| MetaGPT | 每个 Role 验证上游产出 |
| GSD | plan-checker agent + scope reduction detection |
| ChatDev | 角色配对（做+审核）+ 环检测 |
| oh-my-claudecode | Architect → Critic → Planner 三方验证 |

**推荐方案**：
1. **Plan Checker Agent**：拆解完成后，独立的 Plan Checker 验证：
   - 是否覆盖所有需求（与原始需求逐项对照）
   - 依赖关系是否合理
   - 粒度是否适当（太粗/太细）
   - 是否遗漏关键步骤
2. **需求回溯**：拆解结果的每个节点都能追溯到原始需求的哪个部分
3. **完整性检查清单**：按任务类型生成检查清单

#### Q4: 如何确保拆解覆盖所有需求（不遗漏）？

**多层次保障**：

1. **需求结构化**（GSD 的 discuss phase 思路）：
   - 用户描述 → AI 提取为结构化需求列表
   - 每个需求项有 ID、描述、验收标准
   - 用户确认需求列表后才开始拆解

2. **需求-节点映射矩阵**（正向+反向验证）：
   - 正向：每个需求至少被一个节点覆盖
   - 反向：每个节点至少对应一个需求

3. **Plan Checker 的覆盖检查**：
   - 读取需求列表
   - 遍历 DAG 节点
   - 报告未被覆盖的需求

4. **Scope Reduction Detection**（GSD 思路）：
   - 监控规划者是否静默丢弃了需求
   - 如果发现需求消失，自动标记并询问用户

#### Q5: 拆解粒度怎么控制？

**自适应粒度策略**：

| 任务复杂度 | 粒度策略 | 节点数 |
|-----------|---------|--------|
| 简单（<3 个需求） | 粗粒度，合并步骤 | 3-5 |
| 中等（3-8 个需求） | 标准粒度，按功能模块拆分 | 5-10 |
| 复杂（>8 个需求） | 细粒度，每需求可能拆为多个节点 | 10-20 |

**粒度控制原则**：
1. **每个节点有且只有一个 Agent 负责**（不共享责任）
2. **每个节点有明确的 input/output**（可验证）
3. **节点产出不超过 2000 字**（避免上下文溢出）
4. **合并准则**：如果两个节点总是被同一个 Agent 按顺序执行，考虑合并

---

## 推荐方案（结合 AI Native 目标，课题4）

### 方案名称：混合式智能拆解（Hybrid Intelligent Decomposition）

### 架构设计

```
┌─────────────────────────────────────────────────────────────┐
│                    用户需求输入                               │
│              （自然语言 / 结构化描述）                         │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              Step 1: 需求结构化（Requirement Extraction）      │
│                                                              │
│  庞统分析用户输入，提取为结构化需求列表：                       │
│  - 需求项 ID + 描述 + 验收标准                                │
│  - 需求类型标签（数据/编码/分析/部署/审查/讨论）               │
│  - 复杂度评估（简单/中等/复杂）                                │
│  - 隐含需求挖掘（discuss phase 的 dream extraction）          │
│                                                              │
│  产出：structured_requirements.json                          │
│  ✋ 检查点：用户确认需求列表                                   │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              Step 2: 模板匹配 + AI 增强                       │
│                                                              │
│  2a. 模板选择（两层匹配）：                                    │
│      - 第一层：需求类型标签 → 候选模板集                       │
│      - 第二层：LLM 语义匹配 → 最佳模板                        │
│                                                              │
│  2b. AI 增强（动态调整）：                                     │
│      - 增：遗漏的步骤（如缺少数据验证）                        │
│      - 删：不需要的步骤（如纯分析不需要部署）                   │
│      - 调：粒度调整（合并/拆分节点）                           │
│      - 角色适配：根据节点调整 Agent 分配                      │
│                                                              │
│  约束：某些节点不可删除（如 review 节点，铁律 IR-1）           │
│                                                              │
│  产出：draft_dag.json（节点 + 边 + Agent 分配）               │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              Step 3: Plan Checker 验证                        │
│                                                              │
│  独立的 Plan Checker Agent 验证：                             │
│  - 覆盖性：每个需求是否被至少一个节点覆盖                      │
│  - 依赖性：节点依赖是否合理（无环、无遗漏前置）                │
│  - 粒度性：节点是否过大/过小                                   │
│  - 完整性：是否遗漏常见步骤（对比模板库的经验）                │
│  - 角色匹配：Agent 能力是否匹配节点要求                       │
│                                                              │
│  产出：plan_check_result.json + 修改建议                      │
│  如果不通过 → 回到 Step 2 调整（最多 2 轮）                    │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              Step 4: 最终 DAG 输出                            │
│                                                              │
│  通过验证的 DAG，包含：                                        │
│  - 节点定义（ID, name, agent, input_schema, output_schema）   │
│  - 边定义（source → target, condition）                       │
│  - 需求映射矩阵（requirement_id → node_ids）                  │
│  - 检查点定义（哪些节点需要人工确认）                          │
│                                                              │
│  产出：final_dag.json → 传入 moziplus 引擎执行               │
└─────────────────────────────────────────────────────────────┘
```

### 关键设计决策

| 决策 | 选择 | 理由 |
|------|------|------|
| 拆解由谁做 | 庞统（副军师） | 定位就是"策略研究+任务协调" |
| 模板角色 | 骨架+约束 | 保证基本完整性，AI 负责灵活调整 |
| 验证机制 | 独立 Plan Checker | 不信任 LLM 自律（业界共识） |
| 需求覆盖 | 需求-节点映射矩阵 | 正向+反向双重保证 |
| 粒度控制 | 自适应（复杂度驱动） | 避免"一刀切" |
| 不可删除节点 | review 类节点 | 铁律 IR-1（每任务至少 2 Agent） |

### 模板库设计

不是 5 个固定模板，而是 **模板组件库**：

```json
{
  "template_components": {
    "phases": {
      "requirement_clarification": {
        "mandatory": false,
        "trigger": "需求含糊",
        "nodes": ["requirement_analysis", "requirement_review"]
      },
      "research": {
        "mandatory": false,
        "trigger": "需要调研",
        "nodes": ["literature_search", "analysis", "research_review"]
      },
      "design": {
        "mandatory": false,
        "trigger": "需要设计",
        "nodes": ["architecture_design", "design_review"]
      },
      "implementation": {
        "mandatory": false,
        "trigger": "需要编码",
        "nodes": ["coding", "code_review", "testing"]
      },
      "data": {
        "mandatory": false,
        "trigger": "需要数据",
        "nodes": ["data_acquisition", "data_validation"]
      },
      "deployment": {
        "mandatory": false,
        "trigger": "需要部署",
        "nodes": ["deployment", "deployment_verification"]
      },
      "risk_control": {
        "mandatory": true,  // 如果涉及交易
        "trigger": "涉及实盘/资金",
        "nodes": ["risk_check", "position_check"]
      },
      "final_review": {
        "mandatory": true,  // 铁律
        "trigger": "always",
        "nodes": ["integration_review", "final_summary"]
      }
    }
  }
}
```

庞统的拆解流程变为：
1. 分析需求 → 识别需要哪些 phases
2. 从 phase 组件中选择节点
3. 排列依赖关系 → 构建 DAG
4. Plan Checker 验证

### 与 moziplus v1.0 的对比

| 维度 | v1.0 | v2.6（推荐方案） |
|------|------|-----------------|
| 拆解方式 | 关键词 → 固定模板 | 需求分析 → 模板组件组合 → AI 增强 |
| 模板类型 | 5 个完整 DAG | 组件库（~8 个 phase 组件） |
| 灵活性 | ❌ 固定结构 | ✅ 动态增减节点 |
| 需求覆盖 | ❌ 无检查 | ✅ 需求-节点映射矩阵 |
| 验证 | ❌ 无 | ✅ 独立 Plan Checker |
| 粒度 | ❌ 固定 | ✅ 复杂度自适应 |
| 铁律保证 | ❌ 无 | ✅ 不可删除节点 |

---

# 课题 8：Skill 体系工程落地

## 已有经验（知识库/wiki + OpenClaw 现有 Skill）

### OpenClaw 现有 Skill 体系

**SKILL.md 规范**：
- 每个 Skill 是一个目录，包含 `SKILL.md` 文件
- YAML frontmatter：`name`、`description`
- 正文：指令性内容（工作流、最佳实践、指引）
- 注册：放在 `workspace/skills/` 或 `~/.openclaw/skills/` 下，系统自动发现
- 发现：系统启动时扫描所有 Skill 目录，将 name+description 注入 Agent 上下文
- 加载：Agent 匹配到相关 Skill 后，用 `read` 工具加载全文

**当前 Skill 列表**（42 个，来自 AGENTS.md）：
- 编排类：mozi-task-manager, subagent-delegation, plan-act-verify
- 数据类：data-acquisition, data-verification
- 开发类：coding-implementation, code-review, deployment-infra
- 设计类：design-architecture, requirement-clarification, requirements-analysis
- 分析类：risk-assessment, summary-report, quant-backtest
- Wiki 类：wiki-agent, wiki-capture, wiki-query, wiki-research, wiki-synthesize, wiki-update, wiki-ingest, wiki-export, llm-wiki, data-ingest, ingest-url, cross-linker, graph-colorize, tag-taxonomy, impl-validator, memory-bridge, daily-update
- 通用：skill-creator, summarize, taskflow, taskflow-inbox-triage
- 系统：healthcheck, node-connect, openai-whisper, video-frames, weather, clawhub

### v3.1 Skill 体系设计（已确认）

我们已在 `skill-system-v3.1-design.md` 中确认了四部分架构：

| 部分 | 机制 | Token |
|------|------|-------|
| A. Hook 铁律层 | before_prompt_build Hook | ~500 |
| B. Agent 角色层 | SOUL.md / AGENTS.md | ~2000 |
| C. 通用 Skill 层 | 关键词匹配 + 按需加载 | 列表~1250, 正文按需 |
| D. moziplus 专用层 | 引擎注入 | ~1000 |

### nuwa-skill 的 5 阶段蒸馏经验

nuwa-skill 证明了"蒸馏思维框架"是可行的：
- 5 层提取：表达DNA → 心智模型 → 决策启发式 → 反模式 → 诚实边界
- 6 Agent 并行采集：著作/对话/表达/他者/决策/时间线
- 多重检查点：调研 Review → 提炼确认 → 质量验证 → 双 Agent 精炼

**对 moziplus Skill 体系的启发**：
1. Skill 可以通过"蒸馏"方式创建，不必手写
2. 质量验证需要独立 Agent
3. 多检查点保证质量
4. 诚实边界很重要——Skill 应说明自己做不到什么

---

## 业界优秀实践对比表（课题8）

### 1. Claude Code Skills 体系

**架构：4 层渐进式上下文加载**

| 层 | 内容 | 何时加载 | Token 成本 |
|----|------|---------|-----------|
| L1: Discovery | YAML frontmatter（name + description） | 系统启动 | ~100 token/skill |
| L2: Matching | 检查 description 是否匹配当前任务 | 每轮推理 | 0（已有 L1） |
| L3: Full Load | SKILL.md 正文 | 确认匹配后 | 完整内容 |
| L4: Overflow | 低频 Skill description 被截断 | 超预算时 | 降级为更短描述 |

**关键设计**：
- **skillListingBudgetFraction**：技能列表占上下文的百分比（默认约 2%）
- **Progressive disclosure**：从轻到重，按需加载
- **Workflow vs Reference**：Skill 正文是"做什么"（workflow），不是"为什么"（narrative）
- **allowed_tools / model / disable_model_invocation**：frontmatter 可选字段

**SKILL.md 结构**：
```yaml
---
name: my-skill
description: "简短描述，决定是否被选中"
allowed_tools: [Read, Write, Bash]
---
# 具体指令内容（workflow + best practices）
```

**优点**：
- Token 效率极高（L1 只需 ~100 token）
- 渐进式加载减少无关上下文
- 文件系统即注册中心，简单可靠

**缺点**：
- Skill 之间没有组合机制
- 没有 Skill 版本管理
- 没有 Skill 测试标准

### 2. oh-my-claudecode：三层组合

**架构：Execution + Enhancement + Guarantee**

| 层 | 作用 | 代表 Skill |
|----|------|-----------|
| Execution | 执行具体任务 | ralph, ultrawork, autopilot, team |
| Enhancement | 增强执行质量 | deep-interview, plan, verify, ultraqa |
| Guarantee | 保证交付标准 | omc-doctor, trace, hud, cancel |

**Skill 管理机制**：
- **`/skill list`**：扫描 built-in / user / project 三层
- **`/skill add`**：交互式创建向导
- **`/skill search`**：搜索 Skill
- **Built-in**：不可编辑（只读）
- **User**：`~/.claude/skills/omc-learned/`
- **Project**：`.omc/skills/`

**Skill 等级**：
- Level 1：简单查询/操作
- Level 2：中等复杂度，需要工具调用
- Level 3：复杂，可能 spawn 子任务
- Level 4：全自动（如 autopilot）

**关键设计**：
- **autopilot 5 阶段**：Expansion → Planning → Execution → QA → Validation
- **ralplan 3 阶段**：Planner → Architect → Critic（3 个独立 LLM 验证）
- **deep-interview**：苏格拉底式提问，先澄清再动手
- **ralph**：持久化执行循环（state 文件跨 session）

**优点**：
- 三层分类清晰（做→增强→保证）
- Skill 等级系统控制复杂度
- 跨 session 持久化（state 文件）

**缺点**：
- 三层之间没有明确的接口协议
- 组合依赖 Agent 自行判断
- 没有标准化的测试框架

### 3. nuwa-skill：5 阶段蒸馏 + 检查点

**架构：蒸馏式 Skill 创建**

| 阶段 | 内容 | 产出 |
|------|------|------|
| Phase 0 | 入口分流（直接路径 vs 诊断路径） | Skill 目录 |
| Phase 1 | 6 Agent 并行采集 | 6 份调研文件 |
| Phase 2 | 框架提炼（心智模型+决策启发式+表达DNA） | 提炼结果 |
| Phase 3 | Skill 构建（填充模板） | SKILL.md |
| Phase 4 | 质量验证（已知/边缘/风格 3 项测试） | 验证报告 |
| Phase 5 | 双 Agent 精炼 | 最终 SKILL.md |

**关键创新**：
- **Agentic Protocol**：Skill 不只是"知道什么"，还定义了"怎么做"（遇到事实问题先搜索再回答）
- **诚实边界**：每个 Skill 必须声明自己做不到什么
- **质量自检脚本**：`quality_check.py` 自动检查 6 项通过标准
- **心智模型驱动**：从蒸馏出的心智模型推导回答策略

**优点**：
- Skill 可以通过半自动化流程创建
- 多检查点保证质量
- 诚实边界增加了可信度
- 心智模型驱动是创新点

**缺点**：
- 创建流程复杂（6 phase）
- 主要针对"人物 Skill"，通用化需要改造
- 没有 Skill 之间的组合机制

### 4. MetaGPT Action 基类

**架构：面向对象的 Action 继承**

```python
class Action:
    name: str
    context: Context  # 共享上下文
    
    async def run(self, with_messages: List[Message] = None, **kwargs) -> Message:
        """子类实现具体逻辑"""
        raise NotImplementedError

class Role:
    actions: List[Action]
    _watch: Set[Type[Action]]  # 订阅上游 Action
    
    def set_actions(self, actions: List[Action]):
        self.actions = actions
    
    async def _think(self):
        """决定执行哪个 Action"""
        
    async def _react(self):
        """执行 Action 并发布结果"""
```

**关键设计**：
- **Action 是最小执行单元**：输入 Message → 输出 Message
- **Role 组合 Action**：一个 Role 可以有多个 Action
- **_watch 声明式订阅**：自动触发链
- **Context 共享**：所有 Role/Action 共享同一上下文

**优点**：
- 面向对象，结构清晰
- Action 可复用（不同 Role 可共享同一 Action）
- _watch 机制优雅

**缺点**：
- 需要写 Python 代码，不是纯 Skill 描述
- 绑定 Python 生态
- 对非开发人员门槛高

### 5. GSD 的 Skill Discovery Contract

**架构：文件系统 + 规范化扫描**

```
项目根目录：
  .claude/skills/
  .agents/skills/
  .cursor/skills/
  .github/skills/
  .codex/skills/

全局：
  ~/.claude/skills/
  ~/.codex/skills/
```

**规范化规则**：
- 只扫描包含 `SKILL.md` 的子目录
- 从 YAML frontmatter 读取 name 和 description
- 缺少 name 时用目录名
- 提取 trigger hints（`TRIGGER when: ...` 行）
- `gsd-*` 目录识别为框架 Skill

**Skill Manifest**（清单）：
```json
{
  "skills": [...],
  "roots": ["扫描了哪些根目录"],
  "installation": {"gsd_skills_installed": true, "legacy_claude_commands_installed": false},
  "counts": {"total": 25, "project": 5, "global": 20}
}
```

**优点**：
- 规范化程度高
- 跨运行时兼容（Claude Code / Codex / Gemini CLI）
- 清单系统方便审计

**缺点**：
- 只做发现，不做组合和验证
- 没有版本管理

### 6. CrewAI Tool 装饰器

**架构：装饰器模式 + Tool 注册**

```python
@tool("stock_price")
def get_stock_price(symbol: str) -> str:
    """获取股票价格"""
    return f"Stock price of {symbol} is $100"

agent = Agent(
    role="Analyst",
    tools=[get_stock_price]
)
```

**优点**：
- 装饰器语法简洁
- Tool 自动注册

**缺点**：
- 是 Tool 而非 Skill（能力扩展 vs 行为指导）
- 绑定 Python

### 7. LangChain Runnable 接口

**架构：函数式组合**

```python
chain = prompt | model | parser
result = chain.invoke({"input": "..."})
```

**优点**：组合灵活（pipe 操作符）
**缺点**：是代码级组合，不是 Skill 级

---

## Skill 三层约束工程化方案

### 核心概念：三层约束

基于 v3.1 设计和我们调研的业界实践，Skill 的三层约束定义为：

| 层 | 自由度 | 内容 | 类比 |
|----|--------|------|------|
| **铁律层（Iron Rules）** | 低自由 | 强制执行的硬规则 | 法律 |
| **准则层（Guidelines）** | 中自由 | 推荐的最佳实践 | 行业规范 |
| **技能层（Skills）** | 高自由 | 具体的操作方法 | 工具手册 |

### 工程化方案

#### A. 铁律层工程化

**机制**：OpenClaw Plugin Hook `before_prompt_build`

```typescript
// iron-rules hook
api.on("before_prompt_build", async (event, ctx) => {
  const agentId = resolveAgentId(ctx);
  const rules = loadIronRules(agentId);
  return {
    prependContext: `<iron-rules>\n${rules}\n</iron-rules>`
  };
});
```

**特点**：
- 每轮强制注入，不受 compaction 影响
- 按 Agent 定制（庞统的铁律 ≠ 张飞的铁律）
- 集中管理（一个配置文件，而非分散在各 SOUL.md）

**铁律内容示例**：
```
IR-1: 每个任务至少 2 个 Agent（做 + 挑战）
IR-2: Plan → Act → Verify 三步法
IR-3: 结论必须有证据
IR-4: 改代码先改文档
IR-5: 语义含糊先确认
```

#### B. 准则层工程化

**机制**：SKILL.md（准则型 Skill）

与"技能型 Skill"的区别：
- 准则型 Skill：不定义具体步骤，只定义"应该考虑什么"、"边界在哪里"
- 技能型 Skill：定义具体的操作步骤

**准则型 Skill 示例**：

```yaml
---
name: code-review-guideline
description: "代码审查准则。做审查时参考。"
type: guideline  # 区别于 type: procedure
---
# 代码审查准则

## 必须检查
- [ ] 是否有未处理的异常
- [ ] 是否有硬编码的密钥/密码
- [ ] 是否有死循环风险
- [ ] 是否符合项目命名规范

## 禁止
- 不得批准自己写的代码（IR-1）
- 不得在没有运行测试的情况下批准

## 诚实边界
- 审查者可能遗漏深层逻辑问题
- 性能问题需要实际测试数据
```

**技能型 Skill 示例**：

```yaml
---
name: quant-backtest
description: "量化策略回测执行流程。"
type: procedure
---
# 量化回测流程

## 步骤
1. 从 NAS 获取数据（路径：/Volumes/stock/...）
2. 编写策略代码（模板：...）
3. 提交回测请求（API：http://192.168.2.154:8088）
4. 等待结果 + 验证
5. 生成报告

## 工具
- 数据：赵云 data-acquisition skill
- 验证：关羽 risk-assessment skill
```

#### C. 技能层工程化

**机制**：SKILL.md（过程型 Skill）+ 模板 + 脚本

**Skill 目录结构**：
```
skills/
  quant-backtest/
    SKILL.md           # 主文件
    templates/          # 代码模板
    scripts/            # 辅助脚本
    examples/           # 示例
    tests/              # 测试（可选）
```

**测试方案**：
- **干跑测试**：给 Skill 一个输入，检查输出是否符合 schema
- **场景测试**：3-5 个典型场景，验证 Skill 覆盖度
- **回归测试**：修改 Skill 后，确保已有场景不被破坏

---

## 推荐方案（结合 AI Native 目标，课题8）

### 方案名称：分层渐进式 Skill 体系（Layered Progressive Skill System）

### 架构总览

```
┌─────────────────────────────────────────────────────────────┐
│ Layer 0: 铁律（Iron Rules）                                  │
│   机制: Hook 注入 | 自由度: 无 | 每轮强制                    │
│   内容: IR-1~IR-5                                            │
│   Token: ~500                                                │
├─────────────────────────────────────────────────────────────┤
│ Layer 1: 角色（Agent Identity）                               │
│   机制: SOUL.md + AGENTS.md | 自由度: 无 | 全量加载          │
│   内容: 角色定义 + 行为准则 + Skill 列表                      │
│   Token: ~2000                                               │
├─────────────────────────────────────────────────────────────┤
│ Layer 2: 准则（Guidelines）                                   │
│   机制: SKILL.md (type=guideline) | 自由度: 中 | 按需加载    │
│   内容: 检查清单 + 边界 + 诚实边界                            │
│   Token: 描述~100, 全文~500                                   │
├─────────────────────────────────────────────────────────────┤
│ Layer 3: 技能（Procedures）                                   │
│   机制: SKILL.md (type=procedure) | 自由度: 高 | 按需加载    │
│   内容: 具体步骤 + 模板 + 脚本 + 示例                        │
│   Token: 描述~100, 全文~2000                                  │
├─────────────────────────────────────────────────────────────┤
│ Layer 4: 引擎注入（Engine Context）                           │
│   机制: moziplus engine | 自由度: 无 | 每轮强制              │
│   内容: output-schema + 任务约束 + 检查点参数                │
│   Token: ~1000                                               │
└─────────────────────────────────────────────────────────────┘
```

### Skill 注册、发现、加载

#### 注册

```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, 策略测试]
---
```

#### 发现

```typescript
// 启动时扫描
const skillRegistry = {
  scan() {
    // 扫描 workspace/skills/ + ~/.openclaw/skills/
    // 读取 frontmatter
    // 构建索引：name → path, triggers → names, agents → skills
  },
  
  match(context: string, agentId: string): Skill[] {
    // 1. 过滤 agentId 可见的 Skill
    // 2. 语义匹配 description
    // 3. 返回匹配的 Skill 列表（只有 name + description）
  }
}
```

#### 加载

```
Agent 收到任务
  → 系统注入 L0 铁律 + L1 角色 + L4 引擎上下文
  → 系统注入 L2/L3 Skill 列表（只有 name+description）
  → Agent 自主决定需要哪些 Skill
  → Agent 用 read 工具加载具体 Skill 全文
  → Agent 执行
```

### Skill 组合和编排

**核心原则**：Skill 不直接调用 Skill，而是通过"推荐"机制松耦合。

```yaml
---
name: quant-backtest
description: "量化策略回测执行流程"
type: procedure
related_skills:
  - data-acquisition       # 获取数据
  - risk-assessment        # 风控检查
  - plan-act-verify        # 执行模式
---
```

**编排方式**：

| 编排类型 | 示例 | 机制 |
|---------|------|------|
| 顺序编排 | 回测前先获取数据 | moziplus DAG 边定义 |
| 条件编排 | 如果涉及实盘，触发风控检查 | DAG 条件边 |
| 互斥编排 | 新建 vs 更新策略，走不同 Skill | LLM 判断 + Plan Checker |

### Skill 测试和验证

参考 nuwa-skill 的质量验证思路 + GSD 的 agent-contracts：

| 测试类型 | 方法 | 标准 |
|---------|------|------|
| **结构测试** | 检查 SKILL.md 是否包含必要 section | name/description/type 必填 |
| **干跑测试** | 给 Skill 一个输入，检查输出是否合理 | 输出符合 output_schema |
| **场景测试** | 3-5 个典型场景覆盖 | 每个场景有预期输出 |
| **回归测试** | 修改后重跑场景测试 | 已有场景不退化 |
| **诚实边界测试** | 给超出 Skill 能力的问题 | Skill 应主动声明"无法处理" |

### Skill 版本管理和进化

参考 nuwa-skill 的更新机制 + GSD 的 state 管理：

| 维度 | 方案 |
|------|------|
| **版本号** | SKILL.md frontmatter 的 `version` 字段，遵循 semver |
| **变更记录** | Skill 目录下的 `CHANGELOG.md` |
| **兼容性** | `version` 变更时检查依赖 Skill 的 frontmatter |
| **进化机制** | Agent 使用 Skill 后，如果发现问题，可以建议修改（不直接改，走 PR 流程） |
| **蒸馏创建** | 参考 nuwa-skill 的 5 阶段流程，可以半自动化创建新 Skill |

### 与 v3.1 设计的关系

本方案完全兼容 v3.1 的四部分架构，做了以下细化：

| v3.1 部分 | 本方案对应 | 细化内容 |
|-----------|----------|---------|
| A. Hook 铁律层 | Layer 0: 铁律 | 铁律内容具体化（IR-1~IR-5） |
| B. Agent 角色层 | Layer 1: 角色 | 不变 |
| C. 通用 Skill 层 | Layer 2: 准则 + Layer 3: 技能 | 细分为准则型 + 过程型 |
| D. moziplus 专用层 | Layer 4: 引擎注入 | 不变 |

新增：
- Skill 注册/发现/加载的工程化方案
- Skill 测试框架
- Skill 版本管理
- Skill 组合编排机制
- 诚实边界要求

### 实施路线

| Phase | 内容 | 时间 |
|-------|------|------|
| **P0** | 铁律 Hook + Skill type 字段（区分 guideline/procedure） | 2 天 |
| **P1** | 现有 42 个 Skill 打标分类（guideline vs procedure） | 1 天 |
| **P2** | Skill 测试框架（结构测试 + 干跑测试） | 3 天 |
| **P3** | Skill 版本管理 + 变更记录 | 2 天 |
| **P4** | Skill 蒸馏工具（参考 nuwa-skill） | 5 天 |

---

## 总结：两个课题的协同关系

课题 4（智能拆解）和课题 8（Skill 体系）不是孤立的，它们协同工作：

```
用户需求
  │
  ├→ [课题4] 庞统智能拆解
  │   ├ 分析需求（用 plan-act-verify skill）
  │   ├ 选择模板组件（用 mozi-task-manager skill）
  │   ├ AI 增强（用 design-architecture skill）
  │   └ Plan Checker 验证（用 code-review skill 作为 guideline）
  │
  └→ [课题8] Skill 体系支撑
      ├ 铁律层保证基本纪律
      ├ 准则层保证质量标准
      ├ 技能层提供具体操作方法
      └ 引擎层注入任务上下文
```

**核心原则**：
1. **Skill 是"执行准则"不是"执行步骤"** — 给 Agent 方向和边界，不绑死每一步
2. **拆解是"模板 + AI 增强"不是"完全自由"** — 有约束的灵活才是可靠的灵活
3. **验证是"独立 Agent"不是"自我检查"** — 不信任 LLM 自律
4. **渐进式加载** — 不浪费 token，按需提供信息
5. **诚实边界** — 每个 Skill 和拆解结果都声明自己的局限