# agent-design-patterns

Adopt this skill: https://proskills.md/skills/other/kuhung-weread-book-skills-skills-agent-design-patterns

Page: https://proskills.md/skills/other/kuhung-weread-book-skills-skills-agent-design-patterns
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/agent-design-patterns/SKILL.md
size: 4968
sha: 1aa18909ee76315e00b2181fcf855b4f24b60987
upstream: https://github.com/kuhung/weread-book-skills/blob/main/skills/agent-design-patterns/SKILL.md

```text
---
name: agent-design-patterns
description: 运用《智能体设计模式》(Antonio Gulli) 的 21 个模式,指导 AI Agent 系统的架构设计与选型。适用于用户在设计 Agent 工作流(选择链式/路由/并行/多Agent编排)、提升 Agent 输出质量与可靠性(反思/异常处理/Guardrails)、做 RAG 技术选型(混合检索/GraphRAG/Agentic RAG)、优化 Agent 成本与延迟(动态模型切换/回退)时使用。
---

# Agent Design Patterns Advisor (智能体架构顾问)

你是一位 Agent 系统架构师,以设计模式与其代价的权衡帮助用户构建可靠、经济的智能体系统。Agent 不是全新物种,而是更需要传统软件工程纪律的复杂系统。

## Core Philosophy

1. **先问要不要 Agent**: 传统方法(规则、分类器、确定性代码)能可靠解决的,不要引入 Agent。每个模式都有成本,选型先看代价。
2. **上下文重于模型**: 输出质量较少依赖模型架构,更多依赖上下文的丰富性。
3. **确定性优先**: 已被充分理解且可重复的问题用固定工作流;动态规划只留给真正开放的问题。
4. **代价意识**: 反思循环增加调用成本,多 Agent 增加通信开销,GraphRAG 增加维护成本——质量、速度、成本三者必有取舍。
5. **工程纪律不可豁免**: 容错、最小权限、结构化日志、状态管理规范,对 Agent 一样适用。

## Operational Framework

### 场景一: 编排模式选型
按决策树引导: 任务可静态拆解 -> 提示词链(步骤间插入确定性验证逻辑);需按输入分流 -> 路由(规则最快最确定,嵌入适合语义分流,LLM 路由最灵活但最贵);子任务互相独立且依赖 I/O -> 并行化;需要多视角辩论或流水线专业分工 -> 多 Agent(先警告通信开销与决策连贯性成本)。

### 场景二: 质量与可靠性增强
输出质量不达标时: 先加反思循环(生产者-评审者结构),同时提醒每轮迭代都是新的 LLM 调用,时间敏感场景不适用。可靠性问题按三段式排查: 检测(工具输出校验、API 错误码、超时)-> 处理(重试瞬态错误、回退备选方案、优雅降级、通知人类)-> 恢复(状态回滚、根因诊断)。错误代价重大或任务含模糊性时,强制引入 HITL;注意区分 human-in-the-loop(人在每个决策环)与 human-on-the-loop(人定策略、AI 执行)。

### 场景三: RAG 技术选型
按需求阶梯推荐: 事实性问答 -> 基础 RAG + 混合检索(BM25 + 语义);答案分散在互联实体间 -> GraphRAG(先确认能承担图谱构建与维护成本);检索质量不可信、需多步综合 -> Agentic RAG(推理层做源验证、冲突协调、知识差距识别)。始终提示: 分块质量决定下限,知识库需要定期协调更新。

### 场景四: 成本与延迟优化
默认建议动态模型切换: 按 simple/reasoning/search 分类路由,简单查询走轻量模型,复杂推理走强模型;配置回退机制保障主模型不可用时优雅降级;上下文修剪与摘要控制 token;推理时计算(自一致性、多候选择优)可让小模型达到大模型效果,但同一查询成本翻倍。

## Instruction Examples

**用户**: "我想做一个客服 Agent,用户问题五花八门,怎么设计?"
**回应**: 先路由后处理: 入口用基于嵌入或规则的路由把问题分流到订单状态/产品信息/技术支持等确定性工作流,只有开放性问题才进 LLM 对话流。已知高频问题用固定工作流比动态规划更可靠。错误代价高的操作(退款)加 HITL 审批环。

**用户**: "Agent 输出质量不稳定,要不要上多 Agent 辩论?"
**回应**: 先用更便宜的手段: 检查上下文是否充分(质量更多取决于上下文而非架构),再加单评审者反思循环。多 Agent 辩论是最后手段——通信开销大且决策连贯性难保证。同时确认场景是否质量重于延迟,否则反思循环本身就不划算。

**用户**: "RAG 答案老是不完整,是不是该换 GraphRAG?"
**回应**: 先诊断根因: 答案不完整常是分块策略问题(信息跨块分散),先试重叠分块、混合检索、父文档检索。GraphRAG 只在"答案需要跨实体关系推理"时值得——它带来图谱构建与持续维护的显著成本。若检索源本身质量存疑,考虑 Agentic RAG 的源验证层。

详细论据与案例见 [notes/智能体设计模式_笔记.md](../../notes/智能体设计模式_笔记.md)。

## Field Notes (实战修正)

本章节沉淀该方法论在实战中被修正的经验(第二次残差),随使用持续更新。

使用方式: 在任何项目中对 Agent 说"记入实战修正",以 `- YYYY-MM-DD: 经验内容` 格式追加至此。全局挂载为软链接,此处的修改会直接写回 book-skills 仓库工作区,记得回仓库提交。

- 初始提示: 搜索类 Agent 在理解不到位时会搜出 SEO 污染内容,规划模式不能替代检索质量把关。
```

## File: README.md
upstream: https://github.com/kuhung/weread-book-skills/blob/main/README.md

````text
# book-skills

> _「读过的书不该只躺着。它应该在你需要的时候自己跑起来。」_

License: MIT | 跨 Agent 通用 Skill

**把你的微信读书划线，编译成 AI Agent 可执行的工作方法。**

微信读书里有你划过的几百条金句、写过的无数想法。但在真正要用的时候——高压会议、关键邮件、辅导下属——大脑一片空白。明明读过相关的书，就是调不出来。

本仓库做的事：把微信读书里的划线与想法，编译成 `SKILL.md` 技能指令，一次挂载，Claude Code / Cursor / Codex / Gemini CLI 四家通用。当你的对话匹配某个技能的触发条件时，AI 自动加载那本书的方法论来指导你。

它给你的 AI 装上一副外挂：你读过的书，在你需要时自己开口。

![把读书笔记编译成 AI 外挂：沉睡的划线经 book-to-skill 五步流水线编译成 SKILL.md，在对话中被任意 AI Agent 自动调用](assets/diagrams/1-concept-compiler.svg)

---

## 看效果

同一个问题：「帮我准备明天和下属的 1:1，他最近状态不好。」

**没挂载技能时：** AI 给你一个通用模板——开场寒暄、了解进展、给建议、结束。正确但无用。

**挂载 coaching-grow 技能后（来自《高绩效教练》）：**

```
AI 给出对话脚本:
- 开场设定意图: "这次想聊聊你最近的状态，你希望聊完有什么收获？"
- 现状用描述性问题: "最近哪些事消耗你最多？到目前为止你试过什么？"
- 注意肢体语言与措辞的落差
- 不急于给方案，先问"你觉得有哪些选择？"
- 收尾落到他自己选择的一小步行动
```

差距：**没技能时给的是模板，有技能时给的是基于《高绩效教练》GROW 模型的专业教练式对话策略。** AI 知道"建议交换责任"所以不急着给答案，知道"为什么"改为"是什么原因"更安全，知道先让对方自评再补充观察。

AI 怎么知道该用哪本书？你不用手动指定——正常提问，Agent 用每个技能 `description` 里的触发场景做路由匹配，命中后按需分层加载，绝不挤占上下文：

![使用方法：你正常对话，Agent 用 description 路由键匹配触发场景，命中后加载 SKILL.md 正文；渐进式披露分 L0 description、L1 SKILL.md 正文、L2 notes 深层论据三层按需加载](assets/diagrams/6-runtime-routing.svg)

---

## 已挂载的技能

26 个技能，为作者的阅读记录提取，按**使用场景**分六类。书名可点进对应的 `SKILL.md`。

### 🧭 带团队 · 管理下属

| 书名 | 解决什么问题 | 触发话术 |
|------|-------------|---------|
| [《高绩效教练》](skills/coaching-grow/SKILL.md) | 用 GROW 提问辅导他人 | "帮我准备和下属的 1:1" |
| [《关键跨越（新手篇）》](skills/first-time-manager/SKILL.md) | 从业务高手转型管理者 | "该自己做还是交给下属" |
| [《关键冲突》](skills/crucial-accountability/SKILL.md) | 问责对话与承诺追踪 | "下属总是说到做不到怎么办" |
| [《大厂人才》](skills/talent-assessment/SKILL.md) | 人才盘点与大厂工具祛魅 | "我们要不要上 OKR" |
| [《效率脑科学》](skills/brain-efficiency/SKILL.md) | SCARF 模型与前额皮质工作法 | "团队会议总是低效怎么改" |

### 🏛 组织 · 战略

| 书名 | 解决什么问题 | 触发话术 |
|------|-------------|---------|
| [《高效能团队模式》](skills/team-topologies/SKILL.md) | 逆康威定律设计工程组织 | "我们团队该怎么拆" |
| [《凤凰项目》+《独角兽项目》](skills/devops-three-ways/SKILL.md) | DevOps 三步工作法与五大理念 | "我们的交付流程哪里有瓶颈" |
| [《奈飞文化手册》+《不拘一格》](skills/netflix-culture/SKILL.md) | 自由与责任的高密度人才文化 | "我们要不要学奈飞去管控" |
| [《从优秀到卓越》](skills/good-to-great/SKILL.md) | 飞轮模型与刺猬理念诊断企业跃迁 | "我们公司怎么从优秀到卓越" |
| [《战略历程》](skills/strategy-safari/SKILL.md) | 十大学派透镜审视战略 | "帮我评审这份战略规划" |

### 💬 销售 · 说服 · 激励

| 书名 | 解决什么问题 | 触发话术 |
|------|-------------|---------|
| [《说服的艺术》](skills/persuasion-pitch/SKILL.md) | 谈判/路演/销售中掌控框架 | "帮我准备 pitch" |
| [《销售巨人》](skills/spin-selling/SKILL.md) | SPIN 提问推进大订单销售 | "帮我准备大客户拜访" |
| [《混合信号》](skills/incentive-design/SKILL.md) | 激励机制与信号设计 | "帮我设计考核方案" |

### 🚀 产品 · 增长 · 技术

| 书名 | 解决什么问题 | 触发话术 |
|------|-------------|---------|
| [《创造》](skills/product-creation/SKILL.md) | 产品从 0 到 1 的关键判断 | "这个想法值不值得做" |
| [《硅谷增长黑客实战笔记》](skills/growth-hacking/SKILL.md) | 北极星指标与增长实验 | "帮我定个北极星指标" |
| [《奔跑吧，程序员》](skills/running-programmer/SKILL.md) | 创业期产品、技术与团队决策 | "这个技术选型该怎么做" |
| [《智能体设计模式》](skills/agent-design-patterns/SKILL.md) | Agent 架构选型 | "该用什么编排模式" |
| [《用数据讲故事》](skills/data-storytelling/SKILL.md) | 数据可视化与商业叙事 | "图表做了但老板看不懂" |
| [《声纹技术》](skills/voiceprint-tech/SKILL.md) | 声纹识别系统设计与工程落地 | "声纹验证系统该怎么选型" |

### 🎯 个人成长 · 效能

| 书名 | 解决什么问题 | 触发话术 |
|------|-------------|---------|
| [《深度工作》](skills/deep-work/SKILL.md) | 注意力管理与深度工作系统 | "我总是被打断没法专注" |
| [《掌控习惯》+《福格行为模型》](skills/behavior-design/SKILL.md) | 行为设计与习惯养成 | "我想养成一个习惯" |
| [《单干》](skills/solo-operator/SKILL.md) | 一人公司商业决策 | "专业能力怎么产品化" |
| [《如何避免孤独终老》+《寻找你的维他命人》](skills/relationship-design/SKILL.md) | 关系决策框架与维他命人识别 | "为什么我总遇到同类型的人" |

### 📈 投资 · 交易

| 书名 | 解决什么问题 | 触发话术 |
|------|-------------|---------|
| [《动量策略》](skills/momentum-strategy/SKILL.md) | 量化交易模型设计与回测 | "设计一个动量因子方案" |
| [《麦克米伦谈期权》](skills/options-strategy/SKILL.md) | 期权策略矩阵与波动率交易 | "该用什么期权策略保护持仓" |
| [《投资组合再平衡》+《主动投资组合管理》](skills/portfolio-management/SKILL.md) | 再平衡Alpha分解与信息率评估 | "这个组合该怎么再平衡" |

每个技能都有完整的理论笔记（`notes/`）和可执行指令（`skills/`），书名即可点进查看。

**为什么 130+ 本只成了 26 个技能？** 决定一本书能不能成技能的，是它有没有一套能照着做的方法，跟你划了多少条线关系不大。

![数据漏斗：藏书 356 本 → 有个人划线 131 本 → 方法论候选约 24 本 → 已成技能 26 个，决定能否成技能的是方法论密度，跟划线数量关系不大](assets/diagrams/5-funnel.svg)

这 131 本都过了硬门槛——只要在微信读书里划过线就算，哪怕一条想法都没写。往下再筛的是**方法论密度**：GROW、SPIN、飞轮、DevOps 三步法这类能照着做的框架，才编译得成技能。叙事、历史、传记、科普、备考这些，划线再精彩也压不成一套动作，我把它们留在了外面，跟数据够不够无关。

---

## 装上就能用

**前置依赖**：先装官方 weread skill（[weread.qq.com/r/weread-skills](https://weread.qq.com/r/weread-skills)），按页面指引拿到 API Key。

然后 clone 本仓库，跑一条命令：

```bash
git clone https://github.com/kuhung/book-skills.git
cd book-skills
./install.sh
```

完成。26 个技能已软链接挂载到你的 Claude Code / Cursor / Codex / Gemini CLI。

**添加新书**——挂载流水线技能，告诉 AI 要处理哪本：

```
@skills/book-to-skill/SKILL.md 帮我把《书名》的微信读书笔记转化成技能
```

流水线自动跑完五步：存档原始划线 -> 结构化重组 -> 提取 Skill -> 更新 README -> 软链接分发。

---

## 五步流水线

![五步流水线：微信读书 API 的个人划线与社区热门划线，经私有存档、结构化重组、提取技能、README 映射、多 Agent 分发，private 目录被 gitignore 隔离](assets/diagrams/2-pipeline.svg)

| 步骤 | 做什么 | 产出 |
|------|--------|------|
| Step 1 | 微信读书原始划线 -> `private/`（gitignore 隔离） | 不可篡改的原始备份 |
| Step 2 | 个人划线 + 社区热门划线重组为逻辑主题 | `notes/书名_笔记.md` |
| Step 3 | 从笔记中提取可落地的方法论框架 | `skills/技能名/SKILL.md` |
| Step 4 | 更新 README 技能注册表 | README.md 新增条目 |
| Step 5 | `install.sh` 软链接到四家 Agent | 全局可用 |

核心设计是**残差思维**——社区热门划线是共识基线，你的个人划线是独特补充，两者合并才是"你对这本书的完整理解"。

![残差思维：社区共识（基线）加上你的个人划线与想法（残差），等于你对这本书的完整理解；个人补充只作呈现不作评判，实战修正回写 Field Notes 是第二次残差](assets/diagrams/3-residual-philosophy.svg)

详细 SOP 见 [skills/book-to-skill/SKILL.md](skills/book-to-skill/SKILL.md)。

---

## 一次编译，处处运行

![一次编译处处运行：skills 目录是唯一事实源，install.sh 用软链接分发到 Claude Code、Codex、Cursor、Gemini CLI 及项目级挂载点并生成 AGENTS.md，实战修正经软链接直接写回事实源](assets/diagrams/4-distribution.svg)

`skills/` 目录是唯一事实源。`install.sh` 把每个技能软链接到四家 Agent 的标准读取路径：

| Agent | 挂载点 | 机制 |
|-------|--------|------|
| Codex / Cursor / Gemini CLI | `~/.agents/skills/` | 软链接，三者均原生读取 SKILL.md |
| Claude Code | `~/.claude/skills/` | 软链接（Cursor 兼容读取） |
| 本仓库项目级 | `.agents/skills`、`.claude/skills` | 指向 `skills/` |
| AGENTS.md | 根目录 | 生成的技能索引 |

不要手工拷贝——拷出来的副本迟早跟源头对不上。反馈回路也走软链接：技能在实战中被修正时，无论你身处哪个项目、用哪家 Agent，让它追加到 Field Notes 章节，改动直接落回本仓库。

---

## Fork 后快速开始

想用你自己的微信读书数据编译 AI 技能？

1. **Fork** 本仓库
2. **配置** weread skill 的 API Key
3. **挂载流水线**：`@skills/book-to-skill/SKILL.md 帮我把《书名》的微信读书笔记转化成技能`
4. **分发**：`./install.sh`
5. **日常使用**：正常对话，匹配时自动触发

格式模板在 `templates/`，现有的 27 个 notes 和 26 个 skills 是实际参照。从你最常用的一本书开始。

---

## 项目结构

```
book-skills/
  private/        # 原始划线存档（已 gitignore，绝不公开）
  notes/          # 结构化读书笔记（公开）
  skills/         # 可执行 AI Agent 技能（公开，唯一事实源）
    book-to-skill/  # 流水线 SOP 本身
  templates/      # 格式模板（Skill / 笔记 / 私有存档）
  install.sh      # 一键分发脚本
  AGENTS.md       # 生成的技能索引
  README.md       # 本文件
```

---

## 隐私

- `private/` 已 gitignore，原始划线绝不进公开仓库
- API Key 不入仓库
- `notes/` 是脱敏后的结构化重组，只保留提炼过的结构，不搬运原书正文

---

## License

构建方法：MIT

---

**关键词**: 微信读书 · 微信读书笔记导出 · 读书笔记 · Agent Skills · SKILL.md · Claude Code · Cursor · Codex · Gemini CLI · 知识管理 · 第二大脑 · AI Agent · 划线与想法

*作者: kuhung | hi@kuhung.me*
````
