Skill 设计模式目录

像 GOF 设计模式在面向对象编程中的地位一样，本章系统梳理 Agent Skill 开发中的六大核心设计模式，提供模式定义、适用场景、完整示例和反模式警示 | 预计阅读时间：40 分钟

一、引言

为什么 Agent Skill 需要模式语言

1994 年，Gang of Four（GOF）出版的《设计模式：可复用面向对象软件的基础》改变了软件工程的思考方式。它将反复出现的架构问题归类为 23 种模式，让开发者站在前人的肩膀上进行设计，而不是每次从零开始思考"怎么实现一个可扩展的类层次结构"。

Agent Skill 开发正处于类似的转折点。

当开发者开始编写 SKILL.md 时，他们很快会发现：尽管每个 Skill 的领域不同，但解决问题的结构却呈现出很强的共性。一个"批量代码迁移"Skill 和一个"批量文件重命名"Skill 虽然在工具调用上完全不同，但它们的执行拓扑都遵循"拆分任务 → 并行执行 → 聚合结果"的结构。这套结构——我们称之为 Map-Reduce 模式——可以抽象、命名、文档化，然后在不同领域的 Skill 中复用。

本章定义的六大设计模式，就是 Agent Skill 领域的"模式语言"。它们不是凭空发明的，而是从 Claude Code 的社区生态（ClawHub 上超过 3,200 个已发布 Skills）、CrewAI 的生产实践、以及企业级 Skill 部署中提炼出的可复用策略骨架。

模式语言的三个层次

技术社区的模式语言通常分为三个层次：

架构模式（Architectural Patterns）：最高抽象层次，描述整个 Skill 系统的组织结构（如本章的裁决者模式、管道模式）
设计模式（Design Patterns）：中等抽象层次，描述 Skill 内部的结构关系（如本章的 Map-Reduce、重试回退）
惯用法（Idioms）：最低抽象层次，与具体框架绑定的编码约定（如 SKILL.md 的 YAML 约定、依赖声明方式）

本章聚焦"设计模式"和"架构模式"两个层次。惯用法相关的内容已在第 3 章中详细讨论。

模式学习路线图

建议初学者按以下顺序阅读本章：

管道模式 ──→ 裁决者模式 ──→ Map-Reduce 模式
  │                              │
  │                              │
  └──→ 重试回退模式 ←──── 渐进式精化模式
              │
              │
        护栏模式（贯穿所有模式的安全基底）

管道模式是最容易理解的起点，裁决者模式是复杂编排的核心，Map-Reduce 覆盖批量场景，重试回退和渐进式精化是质量保障手段，护栏模式则是贯穿所有模式的安全红线。

二、管道模式（Pipeline）

2.1 模式定义

管道模式将 Skill 的执行过程组织为一个固定步骤的流水线，每个步骤的输出结构化为下一步的输入。

这是 Skill 设计中最基础的模式——它的核心思想是"分而治之"：将一个复杂任务分解为一系列可预测的、顺序执行的步骤，每个步骤专注于一个子任务。

输入 ──→ [步骤1] ──→ [步骤2] ──→ [步骤3] ──→ [步骤4] ──→ 输出
          │             │             │             │
        过滤/转换      分析         生成         格式化

管道模式与面向对象中的责任链模式（Chain of Responsibility）有相似之处，但关键区别在于：管道模式中每个步骤必须按预定义顺序执行，没有动态跳过或重排的能力。这既是约束，也是保证——它让管道的执行结果是确定性的。

2.2 适用场景

场景	典型步骤	管道长度
代码审查	diff 获取 → 逐个文件审查 → 报告生成 → 结果通知	3-5 步
部署验证	环境检查 → 代码构建 → 自动化测试 → 健康检查 → 部署确认	4-6 步
数据处理	数据提取 → 清洗转换 → 统计分析 → 可视化 → 报告输出	3-5 步
文档生成	内容采集 → 结构规划 → 段落生成 → 排版格式化 → 导出	3-5 步
多语言翻译	原文解析 → 初译 → 审校 → 格式化输出	3-4 步

管道模式最擅长的是步骤顺序固定、前后依赖明确的工作流。如果你的任务中步骤之间存在回环、条件跳转或动态组合的需求，管道模式可能不是最佳选择。

2.3 完整 SKILL.md 示例

下面是一个"部署验证管道"的完整 SKILL.md：

yaml

---
name: deploy_pipeline
version: 1.0.0
description: "完整的部署验证管道：环境检查 → 构建 → 测试 → 健康检查 → 部署确认"
scope:
  directories: [deploy/, ci/]
  branches: [main, release/*]
tools:
  required:
    - ssh_check         # SSH 连接检查
    - build_tool        # 构建工具（如 npm build、go build）
    - test_runner       # 测试运行器
    - health_endpoint   # 健康检查端点
    - rollback_ctl      # 回滚控制
  optional:
    - notification      # 通知服务（Slack/邮件）
execution:
  mode: sync
  timeout: 600           # 整个管道 10 分钟超时
  step_timeout: 120      # 每个步骤 2 分钟超时
output:
  required:
    - deploy_status      # 部署状态：success / failed / rolled_back
    - pipeline_log       # 执行日志
  optional:
    - test_summary       # 测试结果摘要
---

## 执行策略

### 步骤一：环境检查

使用 `ssh_check` 验证目标服务器的基本可访问性和资源就绪状态。

检查清单：
1. SSH 连接可达（超时 15 秒）
2. 磁盘使用率 < 85%
3. 内存可用 > 512MB
4. 目标进程未占用冲突端口

如果任何检查项失败，**跳过后续步骤，立即报告失败**。

### 步骤二：代码构建

使用 `build_tool` 执行构建，构建产物输出到 `dist/` 目录。

```bash
npm run build -- --mode production

构建成功的标志：

退出码为 0
dist/ 目录非空
构建日志中无 Error 级别条目

构建缓存策略：优先复用 CI 缓存，若缓存 Miss 则全量构建。

步骤三：自动化测试

使用 test_runner 执行完整的测试套件：

bash

npm run test:ci

测试通过标准：

全部测试通过（不允许已知失败）
代码覆盖率 >= 80%
无 flaky test 识别警告

测试失败时：

收集失败测试的堆栈信息
标记 test_summary 为失败
继续执行后续步骤，但部署状态标记为 degraded（降级部署）

失败策略的选择

在管道模式中，"失败后是否继续执行"是一个关键的设计决策。代码审查管道通常选择"一票否决"（任何步骤失败即终止），而部署验证管道则可能选择"降级继续"（即使测试有小问题也继续部署，但标记降级状态）。具体策略应根据业务场景和风险承受能力决定。

步骤四：健康检查

使用 health_endpoint 对新部署的服务进行健康检查：

GET /health
预期响应: {"status": "ok", "version": "x.y.z"}

检查指标：

HTTP 状态码 200
响应时间 < 500ms
版本号与构建产物一致
依赖服务均可用（数据库、缓存、消息队列）

健康检查重试：最多 3 次，间隔 10 秒。

步骤五：部署确认与通知

汇总管道执行结果，生成最终状态报告：

success：所有步骤通过
degraded：测试有小问题但部署成功
rolled_back：健康检查失败，已触发自动回滚
failed：前置步骤失败，部署未执行

使用 notification（可选）发送结果通知。通知内容包含部署状态摘要和执行日志链接。

反模式警示

反模式一：过于僵化的流水线

yaml

# ❌ 反模式：没有可选步骤的概念
steps:
  - step1: 安全检查（必需）
  - step2: 单元测试（必需）
  - step3: 集成测试（必需）     # 如果项目没有集成测试？
  - step4: 性能测试（必需）     # 性能测试可能需要特殊环境
  - step5: 部署（必需）
  - step6: 通知（必需）

上述设计的问题在于将所有步骤标记为"必需"，导致管道的适用场景极度狭窄。正确的做法是使用 optional 标记和条件分支来设计灵活性。

反模式二：步骤间隐式耦合

如果一个步骤的输出格式发生变化会连锁影响后续所有步骤，说明步骤间存在隐式耦合。解决方案是显式定义步骤间契约（Step Contract），明确每个步骤的输出 Schema。

yaml

# ✅ 正确做法：显式定义步骤间契约
step_1_output:
  format: json
  schema:
    required: [file_path, diff_content, risk_level]
    optional: [test_coverage]

step_2_output:
  format: json
  schema:
    required: [findings, severity, line_numbers]
    optional: [suggested_fix]

三、裁决者模式（Orchestrator）

3.1 模式定义

裁决者模式引入一个中央裁决 Agent，负责将复杂任务分解为子任务、分配给多个专业子 Skill 执行，并聚合子 Skill 的结果做出最终决策。

                ┌─────────────────┐
                │  裁决者 Agent     │
                │  (Orchestrator)  │
                └────────┬────────┘
                         │
          ┌──────────────┼──────────────┐
          │              │              │
          ▼              ▼              ▼
    ┌──────────┐   ┌──────────┐   ┌──────────┐
    │ Skill A  │   │ Skill B  │   │ Skill C  │
    │ (代码生成)│   │ (代码审查)│   │ (测试生成)│
    └──────────┘   └──────────┘   └──────────┘
          │              │              │
          └──────────────┼──────────────┘
                         │
                         ▼
                ┌─────────────────┐
                │  结果聚合与决策   │
                └─────────────────┘

裁决者模式与管道模式的关键区别在于：控制流的复杂性。管道的控制流是线性的，而裁决者可以做出非线性的决策——选择不同的子 Skill 组合、决定执行顺序甚至并发执行的策略。

3.2 适用场景

场景	裁决者职责	子 Skill 示例
代码开发	分解需求，协调各阶段	代码生成、代码审查、测试生成、文档生成
安全审计	协调多维度安全检查	SAST、DAST、依赖扫描、密钥检测
数据分析	选择分析方法，聚合洞察	数据清洗、统计分析、可视化、报告生成
内容创作	统筹多角色内容产出	内容规划、初稿、审校、排版、发布

3.3 裁决者的三种决策逻辑

裁决者的核心是决策逻辑（Decision Logic）。根据场景的不同，裁决者可以采用三种基本的决策模式：

顺序执行模式（Sequential）

子 Skill 依次执行，后一个 Skill 可以访问前一个的输出。适用于有依赖关系的子任务。

裁决者决策逻辑：
1. 执行 代码生成 Skill → 得到代码片段
2. 执行 代码审查 Skill（输入 = 生成的代码）→ 得到审查意见
3. IF 审查通过 THEN 执行 测试生成 Skill ELSE 退回步骤 1
4. 执行 文档生成 Skill

条件分支模式（Conditional）

根据中间结果动态选择不同的执行路径。适用于有决策点的工作流。

裁决者决策逻辑：
IF 安全审查发现严重漏洞 THEN
  执行 深度安全分析 Skill
ELSE IF 安全审查发现中低风险 THEN
  执行 常规修复建议 Skill
ELSE
  执行 正常发布流程 Skill

投票模式（Voting）

多个子 Skill 并行执行同一任务的不同视角，裁决者对结果进行投票或加权聚合。适用于需要多角度判断的场景。

裁决者决策逻辑：
1. 并行执行 3 个代码审查 Skill（不同侧重）：
   - 代码审查 Skill A：安全视角
   - 代码审查 Skill B：性能视角
   - 代码审查 Skill C：可维护性视角
2. 聚合三个结果：
   - 2 票以上"通过" → 批准
   - 安全"不通过" → 一票否决
   - 其他 2 票以上"不通过" → 打回修改

3.4 完整示例：多 Agent 协作的代码开发 Skill

yaml

---
name: multi_agent_code_dev
version: 1.0.0
description: "裁决者模式示例：裁决 Agent 协调代码生成、审查和测试三个子 Skill"
execution:
  mode: async
  orchestrator:
    type: conditional     # 条件分支为主
    max_iterations: 3     # 代码修改最多迭代 3 轮
  concurrency: 3          # 最大并行子 Skill 数
sub_skills:
  - name: code_generator
    ref: .claude/skills/code_generation/SKILL.md
  - name: code_reviewer
    ref: .claude/skills/code_review/SKILL.md
  - name: test_generator
    ref: .claude/skills/test_generation/SKILL.md
  - name: doc_generator
    ref: .claude/skills/doc_generation/SKILL.md
---

## 裁决者执行策略

### 阶段一：任务分解

分析用户需求，将其分解为：
1. **代码生成任务**：需要生成哪些文件？涉及哪些模块？
2. **审查标准**：安全底线、性能要求、代码规范的级别
3. **测试需求**：单元测试覆盖目标、集成测试范围
4. **文档需求**：API 文档、使用说明、变更日志

### 阶段二：裁决与执行

ROUND 1:

调用 code_generator Skill，提交需求上下文
等待 code_generator 完成，获取代码产物
调用 code_reviewer Skill，输入代码产物 → IF 审查通过（无严重问题）THEN 进入阶段三 → IF 审查发现严重问题 THEN： a. 汇总审查意见 b. 跳转到 ROUND 2（回退到 code_generator 修复） → IF 审查发现致命安全问题 THEN： a. 终止执行 b. 返回"需求需要安全重设计"消息

ROUND 2 (仅当需要修复时进入):

将审查意见附加为 code_generator 的额外输入
调用 code_generator Skill，生成修复版本
调用 code_reviewer Skill 复审 → IF 再次不通过 THEN 进入 ROUND 3 → IF 通过 THEN 进入阶段三

ROUND 3 (最后一轮):

再次修复和审查
IF 仍不通过 THEN 终止并报告"无法满足所有审查标准"

阶段三：

调用 test_generator Skill，生成测试代码
执行测试验证（run_tests）
IF 测试通过 THEN 调用 doc_generator Skill
汇总所有输出，返回最终结果


### 裁决者决策规则

优先级规则（解决冲突）：

安全相关问题 → 否决权最高，任何安全 Skill 的一票即否决
性能退化 > 20% → 标记为 warning，但可通过
代码规范问题 → 收集为建议，不阻塞流程
测试覆盖率 < 目标值 → 需要人工确认


---

## 四、Map-Reduce 模式

### 4.1 模式定义

**Map-Reduce 模式**借鉴了 Google 在 2004 年提出的分布式计算模型，将大规模任务分解为"拆分（Map）→ 并行处理 → 聚合（Reduce）"三个阶段。在 Agent Skill 场景中，这个模式解决了"如何让 Agent 高效处理大量同类任务"的问题。

输入（大规模数据） │ ▼ ┌──────────────────────────────┐ │ Map 阶段 │ │ │ │ ┌────────┐ ┌────────┐ │ │ │ 子任务1 │ │ 子任务2 │ ... │ 并行执行 │ └───┬────┘ └───┬────┘ │ │ │ │ │ │ ┌───▼────┐ ┌───▼────┐ │ │ │ 结果1 │ │ 结果2 │ ... │ │ └────────┘ └────────┘ │ └──────────────┬───────────────┘ │ ▼ ┌──────────────────────────────┐ │ Reduce 阶段 │ │ │ │ 聚合结果 → 排序/筛选/统计 │ │ │ └──────────────┬───────────────┘ │ ▼ 最终输出


### 4.2 适用场景

| 场景 | Map 阶段 | Reduce 阶段 | 并发数 |
|------|---------|-------------|-------|
| 批量文件审查 | 每个文件独立审查 | 聚合所有审查意见 | 10-50 |
| 大规模代码迁移 | 每个文件独立迁移 | 验证整体一致性 | 10-100 |
| 多数据源爬取 | 每个源独立抓取 | 去重合并结果 | 5-20 |
| 批量文档翻译 | 每个文档独立翻译 | 术语一致性检查 | 5-30 |
| 测试用例批量生成 | 每个函数/模块生成测试 | 去重合并 + 覆盖率分析 | 10-50 |

### 4.3 完整示例：批量文件审查

```yaml
---
name: batch_code_review
version: 1.0.0
description: "Map-Reduce 模式：批量审查 Pull Request 中的所有变更文件"
execution:
  mode: async
  map:
    strategy: file_based       # 按文件拆分
    key_selector: file_path    # 分片键
    max_concurrency: 20        # 最大并行数
  reduce:
    strategy: merge_sort       # 聚合策略
    dedup: true               # 去重
    sort_by: severity         # 按严重程度排序
tools:
  required: [git_diff, read_file, search_code]
output:
  format: json
  schema:
    required: [summary, file_results, overall_verdict]
---

## 执行策略

### 阶段一：收集变更文件列表

使用 `git_diff` 获取所有变更文件，排除非代码文件（图片、二进制等）。

变更文件数量评估：

<= 5 个文件：直接逐个审查
6-50 个文件：进入 Map-Reduce 流程
50 个文件：分批处理，每批最多 30 个


### 阶段二：Map - 文件级并行审查

对每个变更文件执行独立的审查流程：

对 file_path in changed_files: 并行执行 { 1. read_file(file_path) → 获取完整内容 2. search_code(patterns) → 查找相关引用 3. 独立分析： a. 安全漏洞扫描 b. 逻辑正确性检查 c. 代码规范检查 d. 性能影响评估 4. 输出每个文件的审查结果 }


::: warning 并发控制设计
并发数是 Map-Reduce 模式中最关键的控制参数。设置过高可能导致：
- Agent 上下文切换开销过大
- 工具调用频率触发限流
- LLM 推理质量下降

建议的并发数计算公式：

并发上限 = min(20, ⌊总任务数 × 0.3⌋, API 限流阈值 / 3)

:::

### 阶段三：Reduce - 结果聚合

将每个文件的审查结果聚合为全局报告：

去重：合并跨文件的重复发现（如全局变量污染）
排序：按严重程度排序（CRITICAL > HIGH > MEDIUM > LOW > INFO）
汇总统计：
- 文件总数 / 审查文件数
- 各类发现计数
- 高风险文件列表
生成总体评价：
- PASS：无 CRITICAL 或 HIGH 级别发现
- WARNING：有 HIGH 但 ≤ 3 个，且无 CRITICAL
- FAIL：有 CRITICAL 或 > 3 个 HIGH


Map-Reduce 模式的关键设计原则是 **Map 阶段的独立性**——每个子任务必须不依赖其他子任务的结果。如果子任务间存在依赖关系，应该考虑使用管道模式或裁决者模式，而非 Map-Reduce。

::: tip Map-Reduce 变体：增量处理
对于大型代码库的初次审查，可以使用"增量 Map-Reduce"策略：
1. 维护上次审查的时间戳
2. Map 阶段只处理时间戳之后变更的文件
3. Reduce 阶段合并历史结果和增量结果

这样避免了每次全量扫描的开销，适合 CI/CD 管线中的持续审查场景。
:::

---

## 五、重试回退模式（Retry with Fallback）

### 5.1 模式定义

**重试回退模式**应对的是 Agent Skill 执行中的不确定性——工具调用可能失败、外部服务可能不可用、LLM 推理可能偏离预期。该模式提供三条保障线：**初次尝试 → 重试（修正条件）→ 降级（备选方案）**。

           成功
  ┌─────── 初次尝试 ───────┐
  │                        │
  │ 失败                   │
  ▼                        │

┌─────────┐ │ │ 重试逻辑 │ ←── 首次失败 │ │ 修正条件 │ │ └────┬────┘ │ │ │ ┌────▼────┐ │ │ 重试成功 │ ──── 成功 ───────┤ └────┬────┘ │ │ │ ┌────▼────────┐ │ │ 降级备选方案 │ ←── 仍失败 │ │ (Fallback) │ │ └────┬────────┘ │ │ │ ┌────▼────┐ │ │ 降级成功 │ ──── 降级成功 ───┤ └─────────┘ │ │ ▼ 任务完成


### 5.2 适用场景

| 场景 | 失败原因 | 重试策略 | 降级路径 |
|------|---------|---------|---------|
| API 调用 | 网络超时 / 限流 / 5xx | 指数退避 + 抖动 | 本地缓存数据 |
| 外部搜索 | 搜索引擎不可用 | 切换搜索源 | 使用本地索引 |
| 代码审查 LLM 推理 | 输出格式不符合 Schema | 修正提示词重试 | 简化结构输出 |
| 文件写入 | 权限不足 / 磁盘满 | 等待后重试 | 写入临时目录 |
| 数据库查询 | 连接超时 / 死锁 | 断开重连 | 使用只读副本 |

### 5.3 降级路径设计原则

降级不是"放弃"——它是一种**有管理的服务降级**，确保核心功能在受限条件下仍然可用。降级设计应遵循两个原则：

**功能性降级（Functional Degradation）**：降低输出质量但保留核心功能。

正常路径 → 降级路径 ───────────────────────────────────── 生成详细报告 → 生成摘要报告执行完整测试套件 → 执行关键路径测试三方 LLM 推理 → 本地规则引擎推理实时数据查询 → 缓存数据查询（标记"可能过期"）


**体验降级（Experience Degradation）**：保持输出质量但降低交互体验。

正常路径 → 降级路径 ───────────────────────────────────── 自动分类处理 → 列出选项让用户手动选择异步并行执行 → 同步串行执行一键完成所有操作 → 分步确认执行


::: warning 降级策略的选择
功能性降级和体验降级并非互斥——在实际设计中通常结合使用。关键原则是：**降级后的行为对调用方保持可预期**。换句话说，调用方（可以是用户或其他 Skill）应该知道降级后获得的结果"是什么"和"不是什么"。
:::

### 5.4 完整 SKILL.md 示例

```yaml
---
name: resilient_search
version: 1.0.0
description: "带重试和降级的弹性搜索 Skill，支持多搜索源切换"
tools:
  required: [web_search_api, local_search_engine]
  optional: [cache_service, fallback_api]
execution:
  mode: sync
  retry:
    max_attempts: 3
    strategy: exponential_backoff
    initial_delay: 2          # 首次重试延迟 2 秒
    max_delay: 30             # 最大延迟 30 秒
    jitter: true              # 启用抖动，避免 thundering herd
    retryable_errors:
      - timeout
      - rate_limit
      - server_error
      - service_unavailable
    non_retryable_errors:
      - invalid_query          # 查询无效，重试也没用
      - authentication_failed  # 鉴权失败，需要人工介入
  fallback:
    - strategy: switch_source  # 切换到备用搜索引擎
      error_types: [timeout, server_error]
    - strategy: use_cache      # 使用缓存数据
      error_types: [rate_limit, service_unavailable]
      cache_ttl: 3600          # 缓存有效期为 1 小时
    - strategy: degrade_output
      error_types: [all]       # 所有失败的最终兜底
      description: "返回简化的本地索引结果"
---

## 执行策略

### 主路径：搜索引擎查询

1. 使用 `web_search_api` 执行查询
2. 解析返回结果，提取摘要、链接和相关性评分
3. 格式化输出为统一的结果结构

### 重试逻辑

尝试 1：web_search_api(query) → 成功：返回结果 → 失败（timeout / rate_limit / server_error）：延迟 = min(2^attempt × 2s + random(0, 1s), 30s) 等待延迟后 → 进入重试

尝试 2（延迟 4s ± 抖动）： → 成功：返回结果 → 失败：再次等待 → 进入重试

尝试 3（延迟 8s ± 抖动）： → 成功：返回结果 → 失败：进入降级路径


### 降级路径一：切换搜索源

```yaml
# 策略：switch_source
条件：连续 3 次 timeout 或 server_error
操作：切换到 local_search_engine
标记：结果中包含 "source: fallback - local"

降级路径二：使用缓存

yaml

# 策略：use_cache
条件：触发 rate_limit 或 service_unavailable
操作：从 cache_service 读取上次结果
标记：结果中包含 "source: cached - YYYY-MM-DD HH:mm"
注意事项：缓存超过 cache_ttl 的返回空结果而非过期数据

降级路径三：兜底降级

yaml

# 策略：degrade_output
条件：所有上游路径均失败
操作：使用 local_search_engine 的简化模式，仅返回文件名匹配
标记：结果中包含 "source: degraded - local_index_only"

重试策略中的"不可重试"错误

不是所有失败都值得重试。invalid_query 表示查询本身有问题——重试一百次也不会成功。authentication_failed 可能需要凭据更新，重试只会浪费 Token。将这些错误标记为 non_retryable 可以避免无意义的消耗。

6.1 模式定义

渐进式精化模式从粗粒度输出开始，通过多轮迭代逐步精化到细粒度结果。每轮迭代都在前一轮结果的基础上增加细节、修正偏差、提升质量。

                    ┌──────────┐
                    │  第 1 轮   │  粗粒度：确定整体框架和方向
                    │  骨架     │
                    └────┬─────┘
                         │ 反馈
                    ┌────▼─────┐
                    │  第 2 轮   │  中粒度：填充主要内容
                    │  内容     │
                    └────┬─────┘
                         │ 反馈
                    ┌────▼─────┐
                    │  第 3 轮   │  细粒度：细节打磨和优化
                    │  精化     │
                    └────┬─────┘
                         │ 反馈
                    ┌────▼─────┐
                    │  第 4 轮   │  交付：最终检查和输出
                    │  交付     │
                    └──────────┘

这个模式模拟了人类的专业创作过程——没有人在写第一句话时就确定终稿。优秀的写作者会先搭建大纲，再填充内容，最后逐段精化。渐进式精化模式将这种"人类创作者思维"引入 Agent Skill。

6.2 适用场景

场景	第 1 轮（骨架）	第 2 轮（内容）	第 3+ 轮（精化）
文档写作	大纲/章节结构	段落内容填充	措辞润色、逻辑连贯性检查
代码重构	模块划分/接口设计	实现细节	性能优化、代码风格统一
架构设计	系统边界/组件图	接口定义/数据流	异常处理、性能建模
数据分析报告	分析框架/关键问题	数据收集与初步分析	深度洞察和可视化
教学设计	课程大纲/学习目标	讲义内容	习题设计、互动环节

6.3 每轮的颗粒度控制策略

渐进式精化的关键挑战是如何控制每轮的"颗粒度"——太粗则下一轮需要大量重写，太细则轮次过多导致 Token 浪费。

颗粒度控制策略矩阵

| 轮次 | 颗粒度 | 检查标准 | 判定是否进入下一轮 |
|------|-------|---------|------------------|
| 第 1 轮 | 仅结构 | 结构完整 vs 有缺口 | 缺口超过 30% → 回到第 1 轮 |
| 第 2 轮 | 要点级 | 每个章节有 3-5 个要点 | 要点质量低于阈值 → 精化要点 |
| 第 3 轮 | 段落级 | 连贯性、逻辑性、准确性 | 段落问题超过 3 处 → 定向修复 |
| 第 4 轮 | 句子级 | 措辞、术语一致性、风格统一 | 可选轮次，资源充足时执行 |

yaml

---
name: progressive_doc_writer
version: 1.0.0
description: "渐进式精化模式示例：分轮迭代地生成高质量技术文档"
execution:
  mode: sync
  refinement:
    max_rounds: 4            # 最大精化轮次
    quality_gate:            # 质量门禁
      early_exit: true       # 允许提前退出（第 2 轮即满足质量要求）
      min_acceptable_round: 2 # 最少执行轮数
    feedback_source:         # 精化输入的来源
      - self_review          # Agent 自检
      - schema_validation    # Schema 校验
      - external_check       # 外部工具检查（如拼写检查）
---

## 执行策略

### 第 1 轮：骨架生成

输出文档大纲，符合以下结构模板：

```yaml
大纲结构：
  - 标题
  - 引言（1-2 段，说明文档背景和目标读者）
  - 章节列表（每个章节有主题句和预期的 2-3 个子主题）
  - 总结
  - 附录清单（如果有的话）

轮次退出检查：大纲覆盖了所有必要主题？每个章节有清晰的边界？

通过 → 进入第 2 轮
不通过 → 补充缺失章节后回到第 1 轮

第 2 轮：内容填充

对每个章节，填充实质内容：

对每个章节 section in 大纲：
  1. 为章节编写 3-5 个关键段落
  2. 每个段落包含 1 个核心观点 + 支撑细节
  3. 插入必要的代码示例或数据引用

轮次退出检查：所有章节内容完整？核心观点已经被覆盖？

通过 → 进入第 3 轮
质量已达可接受标准 → 可选提前退出（如果 quality_gate.early_exit 为 true）

第 3 轮：精化打磨

逐段检查文档质量：

检查清单：
  1. 逻辑连贯性：段落间过渡是否自然？
  2. 术语一致性：同一概念是否使用了同一术语？
  3. 代码准确性：示例代码能否实际运行？
  4. 引用准确性：引用是否正确？
  5. 冗余检查：是否有重复表达？

每发现一个问题 → 记录并修复
超过 3 个问题 → 标记为"需要二次检查"

第 4 轮：终审交付（可选轮次）

最终检查，侧重格式和风格：

终审清单：
  - 拼写和语法错误
  - Markdown 格式正确性
  - 链接可访问性
  - 字数符合预期范围
  - 标题层级正确

七、护栏模式（Guardrails）

7.1 模式定义

护栏模式为 Skill 的执行建立安全边界，通过前置校验 → 执行监控 → 后置验证三道防线，确保 Skill 的行为不超出预定义的约束范围。

这个模式是六大模式中唯一一个不直接产生业务价值但所有模式都应该集成的模式。它类似于面向对象编程中的防御性编程（Defensive Programming）——不改变程序的功能，但极大地提升程序的健壮性。

输入 ──→ ┌──────────┐ ──→ ┌──────────┐ ──→ ┌──────────┐ ──→ 输出
         │ 前置校验   │     │ 执行监控   │     │ 后置验证   │
         │ (Input    │     │ (Runtime  │     │ (Output   │
         │  Guard)   │     │  Monitor) │     │  Guard)   │
         └──────────┘     └──────────┘     └──────────┘
              │                │                │
              ▼                ▼                ▼
         拒绝非法输入      记录异常行为       拦截不安全输出

7.2 适用场景

场景	前置校验	执行监控	后置验证
用户输入处理	注入检测、长度限制	敏感操作确认	输出过滤
敏感数据操作	操作白名单检查	操作审计日志	脱敏验证
合规检查	合规规则加载	执行路径合规标记	合规报告生成
文件系统操作	路径沙箱检查	写入量监控	文件完整性校验
外部 API 调用	参数 Schema 校验	频率限制监控	响应 Schema 校验

7.3 三道防线的实现

第一道防线：前置校验

前置校验在 Skill 主逻辑执行之前运行，过滤非法输入和不可执行的条件。

yaml

# 前置校验配置示例
input_guardrails:
  - name: injection_detection
    severity: block           # block 或 warn
    check: |
      检查输入中是否包含：
      - SQL 注入特征（SELECT、DROP、UNION 等 SQL 关键字 + 用户输入拼接）
      - 命令注入特征（;、|、`、$(...) 等 shell 元字符）
      - Prompt 注入特征（"忽略上文"、"你是一个" 等元指令）
    action_on_fail: reject    # reject 或 sanitize

  - name: path_safety
    severity: block
    check: |
      检查文件路径：
      - 是否为绝对路径？ → 拒绝
      - 是否包含 ../ 穿越？ → 拒绝
      - 是否在白名单目录中？ → 校验
    allowed_directories:
      - /tmp/workspace/
      - ./output/
    action_on_fail: reject

  - name: input_size_limit
    severity: warn
    check: |
      输入文件大小是否 < 10MB？
      输入文本长度是否 < 100,000 字符？
    action_on_fail: truncate   # 拒绝或截断

第二道防线：执行监控

执行监控在 Skill 执行期间持续检测异常行为。

yaml

# 执行监控配置示例
runtime_monitors:
  - name: tool_call_rate
    description: "监控工具调用频率，防止意外循环"
    threshold: 30             # 每分钟最大调用次数
    action: slow_down         # slow_down（降速）或 pause（暂停）

  - name: file_write_volume
    description: "监控文件写入量，防止磁盘写满"
    threshold: 100MB
    action: pause

  - name: token_consumption
    description: "监控 Token 消耗，防止预算失控"
    threshold: 50000          # 每次 Skill 调用的 Token 预算
    action: notify            # 通知调用方

  - name: execution_time
    description: "监控执行时间"
    threshold: 300            # 5 分钟超时
    action: terminate         # 超时终止

第三道防线：后置验证

后置验证在 Skill 完成执行后，对输出结果进行安全检查。

yaml

# 后置验证配置示例
output_guardrails:
  - name: sensitive_data_leak
    severity: block
    check: |
      检查输出中是否包含：
      - API Key / Token / 密码
      - 个人身份信息（身份证号、手机号、邮箱）
      - 内部 URL 或 IP 地址
    action_on_fail: redact    # redact（脱敏）或 block（阻止输出）

  - name: output_schema
    severity: block
    check: |
      验证输出是否符合声明的 Schema：
      - 必需字段是否存在
      - 字段类型是否正确
      - 字段值是否在允许范围内
    action_on_fail: reject

  - name: factual_consistency
    severity: warn
    check: |
      检查输出中的事实性声明：
      - 数字与代码引用是否一致
      - 版本号是否与项目匹配
      - 引用来源是否可验证
    action_on_fail: flag      # 标记为需要人工确认

7.4 护栏的层次化架构

在实践中，护栏模式应该分层实现，每层关注不同粒度的安全问题：

层次 1：框架级护栏（最外层）
├── 通用的安全策略
├── 跨所有 Skill 生效
├── 如：所有文件写入必须在工作目录内
└── 所有网络请求必须走代理

层次 2：Skill 级护栏（中间层）
├── 当前 Skill 特有的安全策略
├── 在 SKILL.md 的 guardrails 字段中声明
├── 如：代码审查 Skill 不修改文件
└── 搜索 Skill 不执行命令

层次 3：工具级护栏（最内层）
├── 工具自带的约束
├── 由工具实现者提供
├── 如：git_diff 工具只读
└── search_code 工具限制搜索范围

护栏不是摆设

在 ClawHub 社区的安全事件分析中，超过 70% 的安全事故可以通过基本的护栏模式预防。最常见的问题是 "Skill 执行了设计者没有预期到的操作"——护栏模式正是通过三道防线来捕获这些"意料之外"。

八、模式选择指南

面对一个实际的 Skill 设计问题，如何选择最合适的模式？下面提供了模式适用场景矩阵和选择流程图。

8.1 场景-模式矩阵

场景特征	管道	裁决者	Map-Reduce	重试回退	渐进精化	护栏
步骤固定、顺序明确	★★★	★	—	—	—	★
需要多 Agent 协作	—	★★★	—	—	—	★
大量同类并行任务	—	★★	★★★	—	—	★
不可靠的外部依赖	—	—	—	★★★	—	★★
需要迭代精化质量	—	★★	—	—	★★★	★
安全/合规要求高	—	—	—	—	—	★★★
需要人工参与确认	★★	★★	—	★	★★	★
执行开销敏感	★★★	★★	★★	★★	★	★

注：★★★ = 最佳匹配，★★ = 可以匹配，★ = 辅助作用，— = 不适用

8.2 模式组合策略

在实际项目中，模式很少单独使用。常见的组合策略包括：

组合	典型场景	说明
管道 + 护栏	部署验证	管道提供固定步骤，护栏确保每一步操作安全
裁决者 + Map-Reduce	大型代码迁移	裁决者协调多个迁移策略，Map-Reduce 处理批量文件
管道 + 重试回退	CI/CD 管线	管道提供步骤流程，每步独立处理失败重试
渐进精化 + 裁决者	文档生成	渐进精化提升输出质量，裁决者协调多人协作
所有模式 + 护栏	任何生产环境 Skill	护栏是最低要求

8.3 模式选择决策树

是否有固定的步骤序列？
├── 是 → 步骤数固定且顺序不变？
│   ├── 是 → 管道模式
│   └── 否 → 裁决者模式（条件分支）
├── 否 → 任务是否可拆分为独立子任务？
│   ├── 是 → 子任务数量大且同类？
│   │   ├── 是 → Map-Reduce 模式
│   │   └── 否 → 裁决者模式
│   └── 否 → 需要多次迭代提升质量？
│       ├── 是 → 渐进式精化模式
│       └── 否 → 单次执行
│
└── 是否有外部依赖？
    └── 是 → 重试回退模式包裹外部调用
    
始终需要 → 护栏模式

九、思考题

管道模式 vs 裁决者模式：假设你要设计一个"自动发布"Skill，发布流程包括：构建 → 测试 → 打包 → 部署 → 健康检查 → 通知。你会选择管道模式还是裁决者模式？请给出你的设计理由，以及在什么条件下你会换用另一种模式。
Map-Reduce 的并发数设计：一个批量文件审查任务需要处理 100 个文件，每个文件的审查需要约 2,000 Token。你所在的框架对单个 Agent 的上下文窗口限制为 32K Token。如果每个并发的子 Agent 需要独立的上下文窗口，如何设计最优的并发策略？画图说明你的分批策略。
降级路径设计：一个"智能搜索"Skill 依赖于三个外部搜索 API，每个 API 有不同的可靠性、响应速度和结果质量。请设计一个重试回退策略，在可靠性和搜索质量之间取得平衡。特别考虑：如果主要 API 都不可用，应该返回空结果还是返回过期的缓存数据？
护栏与灵活性的平衡：过多的护栏会限制 Skill 的能力发挥，过少的护栏会带来安全风险。请分析在一个"代码重构"Skill 中，哪些操作需要强制护栏（block），哪些需要警告（warn），哪些可以完全放开。你的判断依据是什么？

十、本章小结

本章系统介绍了 Agent Skill 设计中的六大核心模式：

管道模式：固定步骤流水线，适合步骤明确、顺序固定的任务流
裁决者模式：中央协调者调度多个子 Skill，适合复杂多 Agent 协作
Map-Reduce 模式：拆分并行化处理同类任务，适合大规模批量场景
重试回退模式：失败恢复 + 降级策略，适合不可靠的外部依赖
渐进式精化模式：多轮迭代提升质量，适合高质量内容创作
护栏模式：三道防线保障安全，是所有生产级 Skill 的必备组件

这六大模式构成了 Agent Skill 设计的基础模式语言。它们不是互斥的，而是互补的——在实际项目中，几乎总是需要多个模式的组合使用。第 8 章将在此基础上，深入探讨多个 Skill 如何组合和编排，形成更复杂的 Agent 系统。

从 GOF 设计模式到 Agent Skill 设计模式，我们看到的不仅是技术范式的迁移，更是软件工程思维方式的一次演进——从"代码复用"到"策略复用"的跃迁。

十一、参考资料

Gamma, E., Helm, R., Johnson, R., & Vlissides, J. (1994). Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley. —— GOF 设计模式的开山之作，本章的设计模式目录结构受其启发
Dean, J., & Ghemawat, S. (2004). "MapReduce: Simplified Data Processing on Large Clusters". OSDI'04. —— 本章 Map-Reduce 模式的理论来源
Fowler, M. (2002). Patterns of Enterprise Application Architecture. Addison-Wesley. —— 企业应用架构模式，其中的管道和裁决者模式对本章有直接影响
Nygard, M. (2007). Release It!: Design and Deploy Production-Ready Software. Pragmatic Bookshelf. —— 本章重试回退模式和熔断概念的来源
Agent Skills Open Standard (agentskills.io) —— 官方开放标准，模式中的 execution 字段定义参考了该标准
Anthropic Skills 构建指南 —— Anthropic 官方实践指南，本章模式示例中的 YAML 字段命名遵循了该指南建议
ClawHub Skills Marketplace —— 社区 Skills 市场，本章模式的提炼来源（3,200+ 社区 Skills 的实际使用分析）
Hohpe, G., & Woolf, B. (2003). Enterprise Integration Patterns. Addison-Wesley. —— 消息集成模式，对本章的管道模式和裁决者模式设计有重要参考价值

← 上一章：跨框架互操作性与标准融合 | 返回索引 | 下一章：复杂 Skill 组合与编排 →

Skill 设计模式目录 ​

一、引言 ​

为什么 Agent Skill 需要模式语言 ​

模式学习路线图 ​

二、管道模式（Pipeline） ​

2.1 模式定义 ​

2.2 适用场景 ​

2.3 完整 SKILL.md 示例 ​

步骤三：自动化测试 ​

步骤四：健康检查 ​

步骤五：部署确认与通知 ​

反模式警示 ​

三、裁决者模式（Orchestrator） ​

3.1 模式定义 ​

3.2 适用场景 ​

3.3 裁决者的三种决策逻辑 ​

顺序执行模式（Sequential） ​

条件分支模式（Conditional） ​

投票模式（Voting） ​

3.4 完整示例：多 Agent 协作的代码开发 Skill ​

降级路径二：使用缓存 ​

降级路径三：兜底降级 ​

六、渐进式精化模式（Progressive Refinement） ​

6.1 模式定义 ​

6.2 适用场景 ​

6.3 每轮的颗粒度控制策略 ​

第 2 轮：内容填充 ​

第 3 轮：精化打磨 ​

第 4 轮：终审交付（可选轮次） ​

七、护栏模式（Guardrails） ​

7.1 模式定义 ​

7.2 适用场景 ​

7.3 三道防线的实现 ​

第一道防线：前置校验 ​

第二道防线：执行监控 ​

第三道防线：后置验证 ​

7.4 护栏的层次化架构 ​

八、模式选择指南 ​

8.1 场景-模式矩阵 ​

8.2 模式组合策略 ​

8.3 模式选择决策树 ​

九、思考题 ​

十、本章小结 ​

十一、参考资料 ​

Skill 设计模式目录

一、引言

为什么 Agent Skill 需要模式语言

模式学习路线图

二、管道模式（Pipeline）

2.1 模式定义

2.2 适用场景

2.3 完整 SKILL.md 示例

步骤三：自动化测试

步骤四：健康检查

步骤五：部署确认与通知

反模式警示

三、裁决者模式（Orchestrator）

3.1 模式定义

3.2 适用场景

3.3 裁决者的三种决策逻辑

顺序执行模式（Sequential）

条件分支模式（Conditional）

投票模式（Voting）

3.4 完整示例：多 Agent 协作的代码开发 Skill

降级路径二：使用缓存

降级路径三：兜底降级

六、渐进式精化模式（Progressive Refinement）

6.1 模式定义

6.2 适用场景

6.3 每轮的颗粒度控制策略

第 2 轮：内容填充

第 3 轮：精化打磨

第 4 轮：终审交付（可选轮次）

七、护栏模式（Guardrails）

7.1 模式定义

7.2 适用场景

7.3 三道防线的实现

第一道防线：前置校验

第二道防线：执行监控

第三道防线：后置验证

7.4 护栏的层次化架构

八、模式选择指南

8.1 场景-模式矩阵

8.2 模式组合策略

8.3 模式选择决策树

九、思考题

十、本章小结

十一、参考资料