内容
# 《企业级 Agent 从入门到专家（2026 版）》
> 面向有后端/大数据经验、正在转型 Agent 方向的工程师。
> 主线逻辑：**能力递进为主线、专题深潜为支线**——从 150 行的最小 ReAct 循环出发，27 章增量构建出一个具备生产四件套（安全/观测/评测/成本）的完整 Agent 系统。
> 全书七篇 · 27 章 · 附录 A/B/C/D/E/F · 附贯穿实战项目 **示例助手**（Python 实现，全部代码经真实测试可运行）。
## 本书回答的核心问题
- **认知**：Agent 与 Chatbot / Workflow 的本质区别是什么？（控制流的归属）
- **机制**：一个生产级 Agent 的循环、上下文、工具、记忆各自怎么设计？
- **质量**：概率组件怎么做安全、观测、评测和成本治理？
- **规模**：什么时候需要多 Agent？八种拓扑各值多少钱？
- **落地**：企业环境的部署选型、存量集成与组织流程怎么走？
---
## 完整目录
### 第一篇 认知与基础（入门）
| 章节 | 核心问题 | 贯穿项目交付物 |
|---|---|---|
| [第 1 章 Agent 是什么](第一篇-认知与基础/第01章-Agent是什么.md) | 演进阶梯、AutoGPT 三教训、五要素地图、Agent vs Workflow——本质区别是**控制流的归属** | 项目最终形态的一页纸架构预告图 |
| [第 2 章 第一个 Agent](第一篇-认知与基础/第02章-第一个Agent.md) | 不依赖框架手写最小 ReAct Loop——**Agent = LLM + Loop + Tools**，核心循环不到 40 行 | `minimal_agent.py` + 项目骨架与核心接口 |
### 第二篇 单 Agent 核心机制（原理）
| 章节 | 核心问题 | 贯穿项目交付物 |
|---|---|---|
| [第 3 章 Agentic Loop 解剖](第二篇-单Agent核心机制/第03章-AgenticLoop解剖.md) | 终止条件三层设计、预算熔断四种刹车、内外循环分离、流式中断的一致性 | `budget.py` 可组合终止策略 + 收尾轮 |
| [第 4 章 规划与推理](第二篇-单Agent核心机制/第04章-规划与推理.md) | 规划谱系四档（CoT/P2E/TODO/ReWOO）三维选型、ToT 与自洽采样的边界、Reflexion 闭环、重规划三信号 | `planning.py` Plan-then-Execute 策略 |
| [第 5 章 Context Window 管理](第二篇-单Agent核心机制/第05章-ContextWindow管理.md) | 窗口即预算（三重成本）、Compaction 四步管线、注入三路径纵深防御、lost in the middle | `compaction.py` 压缩器 + token 对账 |
| [第 6 章 提示工程、Skills 与 Hooks](第二篇-单Agent核心机制/第06章-提示工程Skills与Hooks.md) | 三种控制面的边界：Prompt 概率引导 / Skill 按需知识 / Hook 确定性拦截 | `hooks.py` Hook 注册表 + PreToolUse 管线 |
| [第 7 章 工具调用](第二篇-单Agent核心机制/第07章-工具调用.md) | 约束解码为何可靠、粒度=意图、幂等是重试前提、错误三分法、返回值为 LLM 设计 | `tools.py`/`retry.py` 注册表 + 分类重试器 |
| [第 8 章 MCP 协议](第二篇-单Agent核心机制/第08章-MCP协议.md) | M×N→M+N、三角色三原语三传输、描述投毒防御、MCP vs 原生四维取舍 | `mcp/client.py` stdio Client + 快照指纹 |
| [第 9 章 代码执行与环境交互](第二篇-单Agent核心机制/第09章-代码执行与环境交互.md) | 三层沙箱各拦什么、文件系统为何成为共享状态、LSP 的符号级跃迁、副作用三级分级 | `tools/shell.py` 白名单执行器 + 分级标注 |
| [第 10 章 记忆系统](第二篇-单Agent核心机制/第10章-记忆系统.md) | 短期/长期两级 × CoALA 四分类映射、何时记/记什么/怎么忘、过时记忆比无知更糟 | `memory/store.py` SQLite 仓储 + 启动注入 |
| [第 11 章 RAG 与检索](第二篇-单Agent核心机制/第11章-RAG与检索.md) | 检索从前置管线降格为工具、入库五步质量链、混合检索+RRF、grep 反超向量的三理由 | `tools/doc_search.py` 混合检索工具 |
### 第三篇 单 Agent 生产工程化（质量层）
| 章节 | 核心问题 | 贯穿项目交付物 |
|---|---|---|
| [第 12 章 运行时架构](第三篇-单Agent生产工程化/第12章-运行时架构.md) | **Harness 决定同一模型的表现上限**（45% vs 78%）、六大件、三种集成方式、事件模型 | `events.py` 事件总线 + `checkpoint.py` shadow git |
| [第 13 章 安全与权限](第三篇-单Agent生产工程化/第13章-安全与权限.md) | PDP/PEP 分离、三级策略（allow/ask/deny）、HITL 疲劳治理、污点机制防组合攻击 | `security/` 策略引擎 + Hook 形态 PEP |
| [第 14 章 可观测性](第三篇-单Agent生产工程化/第14章-可观测性.md) | 四层 Span、三类指标框架（效果/效率/行为健康）、全采样论证、Trace 回放排障 | `obs/otel_bridge.py` OTel 桥接 + 三核心指标 |
| [第 15 章 评测（Eval）](第三篇-单Agent生产工程化/第15章-评测Eval.md) | 三重困难（非确定/多步/环境）、三类 Scorer 组合、Judge 校准、评测↔监控双向闭环 | `eval/` Scorer 协议 + 回归运行器 + 10 用例集 |
| [第 16 章 成本与性能](第三篇-单Agent生产工程化/第16章-成本与性能.md) | 成本杠杆排序（缓存>路由）、失败税、降级四级阶梯、北极星 = cost per successful task | `cost/ledger.py` 成本台账 + 命中率统计 |
### 第四篇 多 Agent（进阶）
| 章节 | 核心问题 | 贯穿项目交付物 |
|---|---|---|
| [第 17 章 多 Agent 拓扑分类学](第四篇-多Agent/第17章-多Agent拓扑分类学.md) | 八种拓扑的代价模型（token 放大 1.1×–10×）、三维选型、拓扑≠图 | 拓扑选型 Checklist 文档 |
| [第 18 章 编排、通信与图执行](第四篇-多Agent/第18章-编排通信与图执行.md) | **簿记下沉运行时**、DELEGATOR/WORKER/GUARD、交接包与损耗报告、有界回边、interrupt | `orchestration/graph.py` 最小图执行器 |
| [第 19 章 可行性权衡与工程约束](第四篇-多Agent/第19章-可行性权衡与工程约束.md) | "劝退章"：基础设施约束→拓扑排除判定法、三种协调失败、归因证据链 | `graph_trace.py` 跨节点 trace + 边快照归因 |
### 第五篇 企业落地（差异化）
| 章节 | 核心问题 | 贯穿项目交付物 |
|---|---|---|
| [第 20 章 部署与选型](第五篇-企业落地/第20章-部署与选型.md) | 三档部署光谱、评测集驱动选型（非榜单）、数据出域三类通道、审计"同源分管" | 模型选型评分卡模板 |
| [第 21 章 与存量系统集成](第五篇-企业落地/第21章-与存量系统集成.md) | MQ 幂等（重放≠重现）、大数据接入的权限收敛与大结果三板斧、凭证三形态 | `tools/data_query.py` 受防护数据查询工具 |
| [第 22 章 组织与流程](第五篇-企业落地/第22章-组织与流程.md) | Spec 驱动开发（OpenSpec 三阶段）、评审重心转移、成本治理组织化 | 真实 OpenSpec 变更包（三件套） |
### 第六篇 Coding Agent
| 章节 | 核心问题 | 贯穿项目交付物 |
|---|---|---|
| [第 23 章 代码库理解与编辑](第六篇-CodingAgent/第23章-代码库理解与编辑.md) | 为什么代码先跑通（验证信号天然存在）、三层导航与探索外包、项目知识文件内容学、编辑三策略、遗留仓考古三步 | `coding/repo_map.py` Repo Map 构建器（签名骨架+引用度排序） |
| [第 24 章 验证闭环与质量工程](第六篇-CodingAgent/第24章-验证闭环与质量工程.md) | test-driven repair loop、测试基建三适配（分层/选测/flaky）、SWE-bench 原理与局限、依赖幻觉与供应链卫生 | `coding/repair.py` 端到端修复环（issue→测试通过） |
| [第 25 章 协作形态与交付工程](第六篇-CodingAgent/第25章-协作形态与交付工程.md) | 人机协作四档谱系、Reviewer 与并行 worktree、冲突治理四件套、下游容量、机制总图回收全书 | `coding/wt_dispatch.py` worktree 分派（文件亲和+合并预检） |
### 第七篇 专家视野（前沿与收尾）
| 章节 | 核心问题 | 贯穿项目交付物 |
|---|---|---|
| [第 26 章 前沿方向](第七篇-专家视野/第26章-前沿方向.md) | 克制前瞻：自进化=自动化的变更管理、后训练四道闸、SFT/LoRA/DPO/GRPO 速览、三问判断框架 | `training/export.py` 轨迹导出（SFT/DPO 数据通路） |
| [第 27 章 完整实战收尾](第七篇-专家视野/第27章-完整实战收尾.md) | 终态巡礼（四层十六模块）、端到端 14 机制演示、"如果重来"复盘、三条延伸路径 | v1.0.0 tag + 项目 README |
### 附录（工具书，不必通读）
| 附录 | 定位 |
|---|---|
| [附录 A：LLM 基础 Wiki](附录/附录A-LLM基础Wiki.md) | 词条式机制兜底——"模型为什么是这样"（A.1 模型机制 / A.2 推理参数 / A.3 Token / A.4 训练谱系 / A.5 能力缺陷 / A.6 结构化输出 / A.7 选型速查 / A.8 向量表示） |
| [附录 B：Agent Engineering 方法论速查](附录/附录B-AgentEngineering方法论速查.md) | 方法论词典与正文导航——Prompt/Context/Loop/Graph 四件 + Harness 载体 + SDD 外层过程，含"先分诊再开方"使用法 |
| [附录 C：参考文献与版本核验](附录/附录C-参考文献与版本核验.md) | 论文、协议、基准与时效性信息的来源账本；发行前按清单复核版本、价格与链接 |
| [附录 D：常见 Agent 产品与框架速览](附录/附录D-常见Agent产品与框架速览.md) | 产品全景 + 本书坐标系定位法（六大件 × 拓扑 × 集成/部署）——Coding/通用/研究/低代码/编排框架/托管运行时，及开源社区生态（opencode/codex/Superpowers 等）、模型侧 Harness、Vibe Coding 实践、同赛道开源项目四分类速览（社区快照）；名单会过期、定位法不过期 |
| [附录 E：易混概念辨析速查](附录/附录E-易混概念辨析速查.md) | 跨章近亲概念横向对比——信息进出上下文（压缩/记忆/RAG/截断）、输出把关（Verifier/反思/Reviewer/Eval/Guard）、定制三手段、有界性机制总表、检索路线；"X 和 Y 有什么区别"先查这里 |
| [附录 F：关键知识点·经典图版索引](附录/附录F-关键知识点经典图版索引.md) | 为各关键机制索引经典论文原图（图号+出处+链接）并标注书中已有的自绘等价图；版权红线：查阅/授权/重绘，不直接复制原图 |
| [附录 G：OpenTelemetry 详解](附录/附录G-OpenTelemetry详解.md) | OTel 机制兜底——三支柱数据模型、API/SDK 流水线、traceparent/baggage 传播、Collector 管线与配置、语义约定稳定级、全书用件对照表；第 14 章讲用法、本附录讲原理 |
---
## 三条阅读路线
- **完整路线（转型工程师）**：按章顺读。第一、二篇建机制，第三篇上生产件，四至七篇按需——这是能力累加的设计顺序。
- **速成路线（急于上手）**：第 1→2→3→7→6→12 章（认知、循环、工具、控制面、Harness），再回补第 5/15 章（上下文与评测）——最小可用知识闭环。
- **决策者路线（评审与选型）**：第 1 章（认知）→ 第 12 章（Harness 视角）→ 第三篇（质量四件套）→ 第五篇（落地三章）→ 第 17/19 章（多 Agent 的账）——跳过全部代码不影响阅读。
## 贯穿项目：示例助手
企业运维/客服场景的 Agent 参考实现（Python ≥ 3.10，唯一硬依赖 `requests`），从第 2 章约 150 行长成四层十六模块。模块地图与教学简化清单见[第 27 章](第七篇-专家视野/第27章-完整实战收尾.md)第 3 节的项目 README——**它是教学参考实现，不是生产框架**；每处简化都标注了对应章节的补齐路标。全部章节代码均经真实测试（含真实 OTel SDK、真实 pytest、模拟 MCP Server 的端到端协议往返（server/discover + tools/call））。
## 仓库验证与 CI
书稿与贯穿项目的一致性由脚本门禁保证，干净克隆后：
```bash
make setup # 安装锁定依赖（requirements-ci.txt）+ 可编辑装入贯穿项目
make verify # 运行全部真实门禁
```
`make verify` 包含五道门禁，GitHub Actions（`.github/workflows/verify.yml`）对每个 PR 逐 job 运行：
| Job | 门禁 |
|---|---|
| `book-structure` | `book.yml` 与磁盘/README/outline 目录一致、章号连续、每章六段结构 |
| `markdown-render` | 全书渲染无失效加粗（cmarkgfm，GitHub 同款渲染器） |
| `cross-reference-check` | 章/附录/图号内部引用全部指向真实目标 |
| `snippet-sync-check` | 章节内代码与贯穿项目源码**逐字符一致**，漂移即失败 |
| `diagram-source-check` | 每个 D2 图源已渲染为 SVG、被正文引用且可在 GitHub 显示 |
| `contract-tests` | 贯穿项目 `pytest`（事件契约 + OTel/成本消费者，真实 OTel SDK） |
| `source-freshness` | `references/sources.yaml` 与正文/附录 C/代码常量一致，协议版本一致，时效与「待确认」可机器判定 |
> 目录单一来源 `book.yml`（`book-structure`）与来源账本 `references/sources.yaml`（`source-freshness`）均已接入：新增章节改 `book.yml` + 正文即可，时效性来源与「待确认」条目可机器判定。发行前用 `make check-sources-strict` 把「待确认」/过期升级为失败。外链存活检查与文档站构建（`check-links` / `docs-build`）为后续里程碑，当前在 `Makefile` 中显式标注 pending，不伪造通过。
## 全书的五条不折旧判断
若只带走五句话（出处见各章）：
1. **控制流的归属**区分 Chatbot、Workflow 与 Agent（第 1 章）。
2. **一切迭代结构都要有界**——终止权必须部分握在运行时手里（第 3/4/17/18 章，同一铁律五次落地）。
3. **确定性下沉**——簿记、安全、验收交给代码，模型只做需要智能的决策（第 6/13/18 章）。
4. **窗口即预算**——每个 token 背负计费/延迟/注意力三重成本（第 5 章）。
5. **Harness 决定同一模型的表现上限**——转型工程师的工作物是 Harness，不是模型（第 12 章）。
## 许可证与贡献
许可证分离：**代码 MIT**（[`LICENSE-CODE`](LICENSE-CODE)）、**正文与图表 CC BY 4.0**（[`LICENSE-CONTENT`](LICENSE-CONTENT)），概览见 [`LICENSE`](LICENSE)。
参与贡献前请读 [`CONTRIBUTING.md`](CONTRIBUTING.md) 并本地跑通 `make verify`；行为准则见 [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)，安全问题走 [`SECURITY.md`](SECURITY.md) 的非公开渠道。路线图见 [`ROADMAP.md`](ROADMAP.md)，引用方式见 `CITATION.cff`。
## 写作约定
- 每章六段固定模板（场景/原理/实现/生产/坑/面试）；正文 8000–12000 字，代码不超正文 1/3。
- Mermaid 图统一配色：主色 `#4F6D7A`、强调 `#C0D6DF`、警示 `#DD6E42`、中性 `#E8DAB2`；每图配"回答什么问题"的图注。
- 制图三分工（详见根目录《[图表规范](图表规范.md)》）：**架构/分层用 D2**（源 `diagrams/d2/`→`assets/*.svg`）、**时序/流程用 Mermaid**（内联）、**原理示意用 Excalidraw**（`diagrams/excalidraw/` briefs→手绘导出）。
- 交叉引用："参见第 X 章 / 附录 A.x / B.x / C.x"；各章不重复彼此内容，交叉处一句概括 + 引用；量化、协议和时效性断言按附录 C 标记来源与核验日期。
- 完整章节大纲见 [agent-book-outline.md](agent-book-outline.md)。
连接信息
猜你喜欢
暂无推荐服务器