一个 7×6 的 agent 架构设计框架。28 个模式，每个模式都有坐标位置，每个都附带可跑代码 + 真实生产代码引用。
模型负责花，Harness 负责管账。这个仓库是你明天就能用进项目里的设计语言。
English README · 模式文档 · Manning · Designing AI Agents · 论文 · arXiv:2605.13850 · 极客时间专栏 · Substack Newsletter · 作者主页
📖 完整模式文档 —— 每个模式一页白皮书，按认知功能组织，左栏全量导航：adpsagent.com/zh/patterns。企业落地实践（蓝皮书）在 adpsagent.com/zh/cases。
想看完整 Argus running example 作为一个一章一章长出来的代码库？ 配套仓库在 huangjia2019/designing-ai-agents —— Argus 从第 2 章长到第 10 章，每章
patterns/+argus/并列。 那个仓库按书的章节叙事走；这个仓库是独立的模式 catalog。
Designing AI Agents —— 生产级 AI Agent 设计模式的工程参考。(Manning)
双轴框架、27 个命名模式、五条模式选型定律，都出自论文 A Two-Dimensional Framework for AI Agent Design Patterns: Cognitive Function × Execution Topology （Huang & Zhou, arXiv:2605.13850）。这个仓库是这篇论文的可跑配套代码。
市面上大多数"agent 架构"指南给你的是一张平铺清单——Reflection、ReAct、Multi-Agent、Tree of Thoughts、Reflexive Metacognitive 等等。清单回答了"有哪些模式存在"，但回答不了"我的问题落在哪儿、应该用哪一个"。
银行贷款评审 agent 翻车，不是因为缺了 Reflection，是 Perception 层 budget 分配把关键文档丢了。多 agent 代码评审漂移，不是因为 ReAct 错了，是两个 Reflection critic 互相矛盾且没有 governance gate 收口。这些不是不同的模式，是坐落在设计空间不同坐标上的模式。没有坐标系，这些差异看不见。
这个仓库给你坐标系。
每一个 agent 模式都坐落在两条正交轴的交点上。
- 认知功能——agent 在做什么 ↳ perceive / remember / reason / act / reflect / collaborate / govern
- 执行拓扑——runtime 是怎么编排的 ↳ single-step / sequential / parallel / loop / router / hierarchy
七 × 六 = 42 格。其中 28 个有意思的格子，就是 Designing AI Agents 这本书的章节、极客时间专栏的讲次、和这个仓库的代码。
框架不主张"所有东西都能塞进矩阵"。它主张的是：给一个模式分配坐标，强制你回答"为什么这个模式在这儿、不在别处"。平铺清单允许你跳过这个问题，矩阵不允许。
下面每个模式都坐落在一个坐标上。点击模式名直接进入文件夹看代码和 README。✅ 表示有可跑代码，🟡 表示占位脚手架。
| 串行 | 并行 | 路由 | 循环 | 交接 | 层级 | |
|---|---|---|---|---|---|---|
| 感知 | 语义压缩 ✅ | 多模态融合 ✅ | 上下文分诊 ✅ | — | 渐进发现 ✅ | — |
| 记忆 | RAG ✅ | — | 分层保留 ✅ | 失败日记 ✅ | 进度追踪 ✅ | — |
| 推理 | 思维链 ✅ | 并行探索 ✅ | 复杂度路由 ✅ | 迭代假设 ✅ | — | — |
| 行动 | 提示链 ✅ | — | 工具调度 ✅ | — | 规划执行 ✅ | 护栏三明治 ✅ |
| 反思 | 生成评审 ✅ | — | 技能包 🟡 | 自愈循环 🟡 | — | 经验回放 🟡 |
| 协作 | 交接链 🟡 | 扇出聚合 🟡 | — | 对抗评审 🟡 | — | 层级委派 🟡 |
| 治理 | 渐进承诺 ✅ | — | 审批门 ✅ | — | 可观测性 ✅ | 爆炸半径 ✅ |
组合（把模式组装起来）： 模式选型卡 · 六步选型法 · Argus 完整案例 · 清单抽取基准案例
14 个空格子标的是工业还没填上的空白，或那种拓扑-功能组合下还没有结晶的模式。
每个模式文件夹结构一致：pattern.py（最小诚实参考实现，50-250 行）+ example.py（拟真场景，无需 API key 也能跑）+ test_pattern.py（不变量测试）+ 中英双语 README。
每个模式 README 都引用真实生产代码。引用都是上游开源仓库的具体文件和行号，落稿时全部核对过。如果你发现某条引用跟当前上游对不上，请提 issue——那是 bug 不是文档选择。
框架追踪的 8 个生产 harness：Claude Code、Codex CLI、Aider、OpenCode、OpenClaw、Hermes Agent、DeepAgents、DeerFlow、OpenHands。每个模式的 README 都从其中至少一个抽出真实生产形态，而不是 toy 代码。
- 不是框架。要生产 runtime，请用 LangGraph、agno、DeerFlow 或 OpenHands。本仓库是你应用在它们之上的设计语言。换框架不改矩阵。
- 不是平铺清单。清单回答"有哪些模式存在"。矩阵回答**"你的问题落在哪儿、哪些模式是错位选择"**。
- 不是 toy 代码。每个
pattern.py故意保持小（50-250 行），但里面是有真不变量、有测试的诚实代码。每个example.py跑在像生产数据的输入上。README 里的工程切片都是核对过的上游真实文件。
git clone https://github.com/huangjia2019/agent-design-patterns.git
cd agent-design-patterns
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
# 跑一个模式的演示
python perception/a-context-triage/example.py
python perception/b-semantic-compaction/example.py
# 跑全部不变量测试
pytest每个模式文件夹自包含，没有中心框架，没有 plugin 系统要学。读文件夹的 README → 看 pattern.py → 跑 example.py → 看测试。
<pattern-folder>/
README.md # Why 段 + 工程切片引用
README.zh-CN.md # 中文版
pattern.py # 最小诚实实现
example.py # 拟真场景，可跑
test_pattern.py # 不变量测试
先读 README 理解 why，再读 pattern.py 看最小解法，跑 example.py 看它在有 shape 的数据上的行为，测试钉死你改造时不该破坏的边界。
书里反复出现的三句话：
- 设计一个 agent，是在解一个有约束的资源分配问题。
- 固定的 token 预算要在多种竞争的认知需求之间分配，路径不确定。
- 模型是花钱的那一方。Harness 是管账的那一方。模式是分配策略。
矩阵里的每个模式都是这三个角色之一的策略——harness 怎么管账、模式怎么分配、模型怎么被放在合适位置去花。矩阵让这些策略可以作为一个系统讨论，而不是一张孤立清单。
| Manning · Designing AI Agents | 生产级 AI Agent 设计模式的工程参考。27 模式 × 7 认知功能 × 6 拓扑。 |
| 极客时间 · 《Agent 设计模式之美》 | 中文视频专栏。模式逐讲讲透，配真实生产 harness 工程切片。 |
| Substack · Agent Design Patterns | 免费英文 newsletter，1-2 周一篇。结构性观察，不写 hype。 |
| 极客时间 · Claude Code 工程化实战 | 已上线的中文视频专栏，讲 Claude Code 上做 agent 工程化。 |
书给你理论。专栏给你讲解。这里给你可跑的代码。
黄佳 Jia Huang——新加坡 A*STAR 主任研究工程师，前埃森哲新加坡资深咨询师。20 年 NLP / LLM / AI 应用经验，覆盖医疗科技与金融科技。两本英文新书（Manning Designing AI Agents + Packt RAG from First Principles）+ 六本中文书（机器学习、GPT、AI Agent、RAG、数据分析），累计读者数十万。
双轴框架是作者的原创贡献；构成要素（7 个认知功能、6 个执行拓扑）不是新发明，作者的贡献是把它们正交组织起来这件事。
kage-ai.com · LinkedIn · Substack · tohuangjia@gmail.com
欢迎 issue。下面这几类特别有用：
- 引用漂移——README 里某条工程切片引用跟上游对不上了
- 不变量缺口——测试没覆盖到你在生产里见过的某种翻车
- 新语言移植——TypeScript / Go 移植某个模式，新建顶层目录
- 新工程切片——你做过的某个生产 harness 有这个模式但 README 没记录
新模式的 PR：请先开 issue 讨论它在矩阵里的坐标。
如果这个框架对你的工作有帮助，请引用论文：
@misc{huang_zhou_2026_dual_axis,
author = {Huang, Jia and Zhou, Joey Tianyi},
title = {A Two-Dimensional Framework for AI Agent Design Patterns:
Cognitive Function and Execution Topology},
year = {2026},
eprint = {2605.13850},
archivePrefix = {arXiv},
primaryClass = {cs.AI},
doi = {10.5281/zenodo.19036557},
url = {https://arxiv.org/abs/2605.13850}
}MIT。见 LICENSE。