内容
# 《企业级 Agent 从入门到专家（2026 版）》
> 面向有后端/大数据经验、正在转型 Agent 方向的工程师。
> 主线逻辑：**能力递进为主线、专题深潜为支线**——从 150 行的最小 ReAct 循环出发，27 章增量构建出一个具备生产四件套（安全/观测/评测/成本）的完整 Agent 系统。
> 全书七篇 · 27 章 · 附录两层（附录 1–6 审读态工具书 + 附录 7–30 全文收录资料层，新增顺延编号）· 附贯穿实战项目 **示例助手**（Python 实现，全部代码经真实测试可运行）。
## 本书回答的核心问题
- **认知**：Agent 与 Chatbot / Workflow 的本质区别是什么？（控制流的归属）
- **机制**：一个生产级 Agent 的循环、上下文、工具、记忆各自怎么设计？
- **质量**：概率组件怎么做安全、观测、评测和成本治理？
- **规模**：什么时候需要多 Agent？八种拓扑各值多少钱？
- **落地**：企业环境的部署选型、存量集成与组织流程怎么走？
---
## 完整目录
### 第一篇 认知与基础（入门）
| 章节 | 核心问题 | 贯穿项目交付物 | 深读 |
|---|---|---|---|
| [第 1 章 Agent 是什么](第一篇-认知与基础/第01章-Agent是什么.md) | 演进阶梯、AutoGPT 三教训、五要素地图、Agent vs Workflow——本质区别是**控制流的归属** | 项目最终形态的一页纸架构预告图 | [详解版](详解扩展版/详解01-Agent是什么.md) |
| [第 2 章 第一个 Agent](第一篇-认知与基础/第02章-第一个Agent.md) | 不依赖框架手写最小 ReAct Loop——**Agent = LLM + Loop + Tools**，核心循环不到 40 行 | `minimal_agent.py` + 项目骨架与核心接口 | [详解版](详解扩展版/详解02-第一个Agent.md) |
### 第二篇 单 Agent 核心机制（原理）
| 章节 | 核心问题 | 贯穿项目交付物 | 深读 |
|---|---|---|---|
| [第 3 章 Agentic Loop 解剖](第二篇-单Agent核心机制/第03章-AgenticLoop解剖.md) | 终止条件三层设计、预算熔断四种刹车、内外循环分离、流式中断的一致性 | `budget.py` 可组合终止策略 + 收尾轮 | [详解版](详解扩展版/详解03-AgenticLoop解剖.md) |
| [第 4 章 规划与推理](第二篇-单Agent核心机制/第04章-规划与推理.md) | 规划谱系四档（CoT/P2E/TODO/ReWOO）三维选型、ToT 与自洽采样的边界、Reflexion 闭环、重规划三信号 | `planning.py` Plan-then-Execute 策略 | [详解版](详解扩展版/详解04-规划与推理.md) |
| [第 5 章 Context Window 管理](第二篇-单Agent核心机制/第05章-ContextWindow管理.md) | 窗口即预算（三重成本）、Compaction 四步管线、注入三路径纵深防御、lost in the middle | `compaction.py` 压缩器 + token 对账 | [详解版](详解扩展版/详解05-ContextWindow管理.md) |
| [第 6 章 提示工程、Skills 与 Hooks](第二篇-单Agent核心机制/第06章-提示工程Skills与Hooks.md) | 三种控制面的边界：Prompt 概率引导 / Skill 按需知识 / Hook 确定性拦截 | `hooks.py` Hook 注册表 + PreToolUse 管线 | [详解版](详解扩展版/详解06-提示工程Skills与Hooks.md) |
| [第 7 章 工具调用](第二篇-单Agent核心机制/第07章-工具调用.md) | 约束解码为何可靠、粒度=意图、幂等是重试前提、错误三分法、返回值为 LLM 设计 | `tools.py`/`retry.py` 注册表 + 分类重试器 | [详解版](详解扩展版/详解07-工具调用.md) |
| [第 8 章 MCP 协议](第二篇-单Agent核心机制/第08章-MCP协议.md) | M×N→M+N、三角色三原语三传输、描述投毒防御、MCP vs 原生四维取舍 | `mcp/client.py` stdio Client + 快照指纹 | [详解版](详解扩展版/详解08-MCP协议.md) |
| [第 9 章 代码执行与环境交互](第二篇-单Agent核心机制/第09章-代码执行与环境交互.md) | 三层沙箱各拦什么、文件系统为何成为共享状态、LSP 的符号级跃迁、副作用三级分级 | `tools/shell.py` 白名单执行器 + 分级标注 | [详解版](详解扩展版/详解09-代码执行与环境交互.md) |
| [第 10 章 记忆系统](第二篇-单Agent核心机制/第10章-记忆系统.md) | 短期/长期两级 × CoALA 四分类映射、何时记/记什么/怎么忘、过时记忆比无知更糟 | `memory/store.py` SQLite 仓储 + 启动注入 | [详解版](详解扩展版/详解10-记忆系统.md) |
| [第 11 章 RAG 与检索](第二篇-单Agent核心机制/第11章-RAG与检索.md) | 检索从前置管线降格为工具、入库五步质量链、混合检索+RRF、grep 反超向量的三理由 | `tools/doc_search.py` 混合检索工具 | [详解版](详解扩展版/详解11-RAG与检索.md) |
### 第三篇 单 Agent 生产工程化（质量层）
| 章节 | 核心问题 | 贯穿项目交付物 | 深读 |
|---|---|---|---|
| [第 12 章 运行时架构](第三篇-单Agent生产工程化/第12章-运行时架构.md) | **Harness 决定同一模型的表现上限**（45% vs 78%）、六大件、三种集成方式、事件模型 | `events.py` 事件总线 + `checkpoint.py` shadow git | [详解版](详解扩展版/详解12-运行时架构.md) |
| [第 13 章 安全与权限](第三篇-单Agent生产工程化/第13章-安全与权限.md) | PDP/PEP 分离、三级策略（allow/ask/deny）、HITL 疲劳治理、污点机制防组合攻击 | `security/` 策略引擎 + Hook 形态 PEP | [详解版](详解扩展版/详解13-安全与权限.md) |
| [第 14 章 可观测性](第三篇-单Agent生产工程化/第14章-可观测性.md) | 四层 Span、三类指标框架（效果/效率/行为健康）、全采样论证、Trace 回放排障 | `obs/otel_bridge.py` OTel 桥接 + 三核心指标 | [详解版](详解扩展版/详解14-可观测性.md) |
| [第 15 章 评测（Eval）](第三篇-单Agent生产工程化/第15章-评测Eval.md) | 三重困难（非确定/多步/环境）、三类 Scorer 组合、Judge 校准、评测↔监控双向闭环 | `eval/` Scorer 协议 + 回归运行器 + 10 用例集 | [详解版](详解扩展版/详解15-评测Eval.md) |
| [第 16 章 成本与性能](第三篇-单Agent生产工程化/第16章-成本与性能.md) | 成本杠杆排序（缓存>路由）、失败税、降级四级阶梯、北极星 = cost per successful task | `cost/ledger.py` 成本台账 + 命中率统计 | [详解版](详解扩展版/详解16-成本与性能.md) |
### 第四篇 多 Agent（进阶）
| 章节 | 核心问题 | 贯穿项目交付物 | 深读 |
|---|---|---|---|
| [第 17 章 多 Agent 拓扑分类学](第四篇-多Agent/第17章-多Agent拓扑分类学.md) | 八种拓扑的代价模型（token 放大 1.1×–10×）、三维选型、拓扑≠图 | 拓扑选型 Checklist 文档 | [详解版](详解扩展版/详解17-多Agent拓扑分类学.md) |
| [第 18 章 编排、通信与图执行](第四篇-多Agent/第18章-编排通信与图执行.md) | **簿记下沉运行时**、DELEGATOR/WORKER/GUARD、交接包与损耗报告、有界回边、interrupt | `orchestration/graph.py` 最小图执行器 | [详解版](详解扩展版/详解18-编排通信与图执行.md) |
| [第 19 章 可行性权衡与工程约束](第四篇-多Agent/第19章-可行性权衡与工程约束.md) | "劝退章"：基础设施约束→拓扑排除判定法、三种协调失败、归因证据链 | `graph_trace.py` 跨节点 trace + 边快照归因 | [详解版](详解扩展版/详解19-可行性权衡与工程约束.md) |
### 第五篇 企业落地（差异化）
| 章节 | 核心问题 | 贯穿项目交付物 | 深读 |
|---|---|---|---|
| [第 20 章 部署与选型](第五篇-企业落地/第20章-部署与选型.md) | 三档部署光谱、评测集驱动选型（非榜单）、数据出域三类通道、审计"同源分管" | 模型选型评分卡模板 | [详解版](详解扩展版/详解20-部署与选型.md) |
| [第 21 章 与存量系统集成](第五篇-企业落地/第21章-与存量系统集成.md) | MQ 幂等（重放≠重现）、大数据接入的权限收敛与大结果三板斧、凭证三形态 | `tools/data_query.py` 受防护数据查询工具 | [详解版](详解扩展版/详解21-与存量系统集成.md) |
| [第 22 章 组织与流程](第五篇-企业落地/第22章-组织与流程.md) | Spec 驱动开发（OpenSpec 三阶段）、评审重心转移、成本治理组织化 | 真实 OpenSpec 变更包（三件套） | [详解版](详解扩展版/详解22-组织与流程.md) |
### 第六篇 Coding Agent
| 章节 | 核心问题 | 贯穿项目交付物 | 深读 |
|---|---|---|---|
| [第 23 章 代码库理解与编辑](第六篇-CodingAgent/第23章-代码库理解与编辑.md) | 为什么代码先跑通（验证信号天然存在）、三层导航与探索外包、理解底座四层金字塔（grep/AST/符号索引/LSP）与检索选型、项目知识文件内容学、编辑三策略、沙箱权限特化与平台 Agent 六维对比、遗留仓考古三步 | `coding/repo_map.py` Repo Map 构建器（签名骨架+引用度排序） | [详解版](详解扩展版/详解23-代码库理解与编辑.md) |
| [第 24 章 验证闭环与质量工程](第六篇-CodingAgent/第24章-验证闭环与质量工程.md) | test-driven repair loop、测试基建三适配（分层/选测/flaky）、SWE-bench 原理与局限、依赖幻觉与供应链卫生 | `coding/repair.py` 端到端修复环（issue→测试通过） | [详解版](详解扩展版/详解24-验证闭环与质量工程.md) |
| [第 25 章 协作形态与交付工程](第六篇-CodingAgent/第25章-协作形态与交付工程.md) | 人机协作四档谱系、Reviewer 与并行 worktree、冲突治理四件套、下游容量、机制总图回收全书 | `coding/wt_dispatch.py` worktree 分派（文件亲和+合并预检） | [详解版](详解扩展版/详解25-协作形态与交付工程.md) |
### 第七篇 专家视野（前沿与收尾）
| 章节 | 核心问题 | 贯穿项目交付物 | 深读 |
|---|---|---|---|
| [第 26 章 前沿方向](第七篇-专家视野/第26章-前沿方向.md) | 克制前瞻：自进化=自动化的变更管理、后训练四道闸、SFT/LoRA/DPO/GRPO 速览、三问判断框架 | `training/export.py` 轨迹导出（SFT/DPO 数据通路） | [详解版](详解扩展版/详解26-前沿方向.md) |
| [第 27 章 完整实战收尾](第七篇-专家视野/第27章-完整实战收尾.md) | 终态巡礼（四层十六模块）、端到端 14 机制演示、"如果重来"复盘、三条延伸路径 | v1.0.0 tag + 项目 README | [详解版](详解扩展版/详解27-完整实战收尾.md) |
### 附录（两层结构，均不必通读；按数字编号，新增顺延 27、28…）
#### 工具书层（附录 1–6，已审读）
经本书审读与来源核验纪律的六本工具书——机制、方法论、来源账本、产品定位、辨析与图版索引：
| 附录 | 定位 |
|---|---|
| [附录 1：LLM 基础 Wiki](附录/附录01-LLM基础Wiki.md) | 词条式机制兜底——"模型为什么是这样"（1.1 模型机制 / 1.2 推理参数 / 1.3 Token / 1.4 训练谱系 / 1.5 能力缺陷 / 1.6 结构化输出 / 1.7 选型速查 / 1.8 向量表示） |
| [附录 2：Agent Engineering 方法论速查](附录/附录02-AgentEngineering方法论速查.md) | 方法论词典与正文导航——Prompt/Context/Loop/Graph 四件 + Harness 载体 + SDD 外层过程，含"先分诊再开方"使用法 |
| [附录 3：参考文献与版本核验](附录/附录03-参考文献与版本核验.md) | 论文、协议、基准与时效性信息的来源账本；发行前按清单复核版本、价格与链接 |
| [附录 4：常见 Agent 产品与框架速览](附录/附录04-常见Agent产品与框架速览.md) | 产品全景 + 本书坐标系定位法（六大件 × 拓扑 × 集成/部署）——Coding/通用/研究/低代码/编排框架/托管运行时，及开源社区生态（opencode/codex/Superpowers 等）、模型侧 Harness、Vibe Coding 实践、同赛道开源项目四分类速览（社区快照）；名单会过期、定位法不过期 |
| [附录 5：易混概念辨析速查](附录/附录05-易混概念辨析速查.md) | 跨章近亲概念横向对比——信息进出上下文（压缩/记忆/RAG/截断）、输出把关（Verifier/反思/Reviewer/Eval/Guard）、定制三手段、有界性机制总表、检索路线；"X 和 Y 有什么区别"先查这里 |
| [附录 6：关键知识点·经典图版索引](附录/附录06-关键知识点经典图版索引.md) | 为各关键机制索引经典论文原图（图号+出处+链接）并标注书中已有的自绘等价图；版权红线：查阅/授权/重绘，不直接复制原图 |
#### 资料层（附录 7–30，全文收录快照）
二十本全文收录的深度资料：五本详解上手、十一张赛道地图、四册源码解剖。各附录定位 blurb 与页脚"分工列表"是层内导航。
<details>
<summary><b>详解上手（附录 7–11、28、29、30，8 本）</b></summary>
| 附录 | 定位 |
|---|---|
| [附录 7：OpenTelemetry 详解与 Agent 可观测性指南](附录/附录07-OpenTelemetry详解.md) | OTel 机制兜底 + Agent 观测接入原理（全文收录，信息基准 2026-08-31）——OTel 本体 24 节详解（数据模型/五信号/API·SDK/语义约定/OTLP/Collector/采样/排障）、四层 Agent 观测模型、Python 零侵入探针原理、LangChain/LangGraph/OpenAI/ChromaDB 接入机制、Span 所有权治理、自研 Runtime 观测设计、全书用件对照表；第 14 章讲用法、附录 13 盘平台、本附录讲机制 |
| [附录 8：DeepEval 实战指南](附录/附录08-DeepEval实战指南.md) | DeepEval 完整实战教程（全文收录）——安装到 CI/CD 全流程：工作模型、数据模型、G-Eval/DAG、RAG/Agent/Tracing/多轮四条实战线、自定义 Judge 与 Metric、分层门禁与阈值校准、排查与落地清单；第 15 章讲方法论、本附录讲落地（API 快照 4.2.0） |
| [附录 9：评测与观测平台详解与选型](附录/附录09-评测与观测平台详解与选型.md) | DeepEval/Ragas/Arize Phoenix/Langfuse/MLflow 完整调研（全文收录）——逐项定位、数据模型、能力、优劣与适用场景，横向对比、典型场景选型、推荐组合、统一评测模型与分阶段实施路线；第 15 章是地图、本附录是地形志 |
| [附录 10：Mem0 实战指南](附录/附录10-Mem0实战指南.md) | Mem0 完整实战教程（全文收录，信息基线 2026-08-30）——新版算法（ADD-only 写入/混合检索）、Platform-OSS-自托管三形态、Python 与 Node SDK 上手、作用域与 CRUD、冲突治理、多租户架构、安全合规、评估测试与上线清单；第 10 章讲机制、附录 15 是赛道地图、本附录讲落地（SDK 快照 v2.0.19/v3.1.7） |
| [附录 11：Agent 记忆机制详解——从短期到长期](附录/附录11-Agent记忆机制详解.md) | 记忆晋升机制工程详解（全文收录，信息基准 2026-08-31）——"记忆编译"闭环（提取→判断→晋升→维护）、价值判断策略、维护七纪律、检索注入、安全治理与评测、五条实现路线对比、Coding Agent 记忆方案、多 Agent 统一记忆架构、情景记忆晋升 Skill；第 10 章讲机制、附录 10 上手 Mem0、附录 15 盘赛道、本附录讲晋升纵切面 |
| [附录 28：Vibe Coding 实战教程](附录/附录28-VibeCoding实战教程.md) | Vibe Coding 完整工程化教程（全文收录，信息基准 2026-09）——Spec-Driven Vibe Coding：核心架构十件、五工作模式、可控开发环境、需求→规格→上下文→计划→执行→验证→审查→提交→沉淀九阶段工作流、提示词与上下文工程、SDD 约束、验证驱动、多 Agent、安全治理、工具选型与成熟度模型；附录 4 讲姿态定位、本附录讲操作流程 |
| [附录 29：SDD 规范驱动开发实战教程与框架选型](附录/附录29-SDD规范驱动开发实战教程.md) | SDD 完整教程与框架选型（全文收录，信息基准 2026-09）——五层契约、与 Vibe Coding/TDD/BDD/DDD/ADR 关系、核心闭环与工件体系、Current/Change/Delta Spec 三分、Requirement/Scenario 写法、完整实施流程、主流框架全景对比与选型、存量引入、多 Agent SDD、企业治理、反模式与可复制模板；第 22 章讲组织流程、本附录讲工具落地 |
| [附录 30：LangGraph 实战教程](附录/附录30-LangGraph实战教程.md) | LangGraph 完整实战教程（全文收录，含 19 张架构 SVG，实验基线 1.1.2/Python 3.13）——StateGraph 三要素与 Pregel/Superstep 运行时、State/Channels/Reducer、控制流原语（Send/Command/MapReduce/ReAct）、持久化与 Durable Execution/Time Travel、记忆与运行时上下文、中断与 HITL、工具与 ReAct Agent、流式、子图、多 Agent 模式、部署与企业运行时；第 18 章讲图执行机制、本附录讲 LangGraph 落地 |
</details>
<details>
<summary><b>赛道地图与平台架构（附录 12–22、27，12 篇）</b></summary>
| 附录 | 定位 |
|---|---|
| [附录 12：主流 Coding Agent 系统全景](附录/附录12-主流CodingAgent系统全景.md) | Coding Agent 赛道全景调研·增强版（全文收录，信息基准 2026-08-30）——七类盘点、能力九维度、增强六专题（平台 Agent 对比/代码理解/LSP·AST·符号索引·Repo Map/代码检索/沙箱隔离/权限治理）、互操作标准、评测体系与场景选型；附录 4 管全品类速览、本附录深潜这一个赛道 |
| [附录 13：主流 Agent 可观测系统全景](附录/附录13-主流Agent可观测系统全景.md) | Agent 可观测赛道全景调研（全文收录，信息基准 2026-08）——标准与埋点生态（GenAI SemConv/OpenInference）、开源自托管/商业专用/传统 APM/云厂商/框架原生五路平台盘点、指标体系、生产参考架构与成熟度模型；第 14 章讲方法、附录 7 讲机制、附录 9 深评五家、本附录是赛道地图 |
| [附录 14：主流 Agent 评估系统全景](附录/附录14-主流Agent评估系统全景.md) | Agent 评估赛道全景调研·指标增强版（全文收录，信息基准 2026-08-30）——四类产品盘点（平台/框架/云厂商/Benchmark）、十八类评估维度与逐域指标清单、多 Agent 评估、工程闭环与发布门禁；第 15 章讲方法、附录 8 上手 DeepEval、附录 9 深评五家、本附录是赛道地图 |
| [附录 15：主流 Agent Memory 系统全景](附录/附录15-主流AgentMemory系统全景.md) | Agent 记忆赛道全景调研（全文收录，信息基准 2026-08）——定义边界与认知分类、通用架构与数据模型、独立系统十二家盘点（Mem0/Zep/Letta 等）、框架原生/云厂商/文件型记忆、研究演进、Benchmark 解读、企业参考架构与选型；第 10 章讲机制、本附录是赛道地图 |
| [附录 16：主流 Agent 自进化/自优化系统全景](附录/附录16-主流Agent自进化系统全景.md) | Agent 自我改进赛道全景调研（全文收录，信息基准 2026-09）——两条主线：按进化对象（经验/记忆/技能/Prompt工作流/模型自博弈/代码递归）与按优化机制（推理期反思自纠错、Prompt 程序自动优化 DSPy/MIPROv2/GEPA/TextGrad 工具链）、反馈信号分级与多目标函数、群体进化、风险治理与参考架构；第 26 章讲克制判断、本附录是赛道地图（研究为主，成熟度分层标注） |
| [附录 17：主流多 Agent 系统全景](附录/附录17-主流多Agent系统全景.md) | 多 Agent 赛道全景调研（全文收录，信息基准 2026-08-30）——定义辨析与生态全景、通用框架逐家盘点（Agent Framework/LangGraph/OpenAI SDK/ADK/CrewAI 等）、云厂商平台、编排模式、协议栈（MCP/A2A/AG-UI）、状态记忆/沙箱权限/可观测/评估、该用不该用判据与生产参考架构；第四篇讲机制与克制判断、本附录是赛道地图 |
| [附录 18：主流 MCP 系统全景](附录/附录18-主流MCP系统全景.md) | MCP 生态赛道全景调研（全文收录，信息基准 2026-08-30）——协议演进动态、Host/SDK/Server/Registry/Gateway 生态四层盘点、与其他协议关系、安全风险全景与企业基线、工具膨胀治理、参考架构与选型、开发测试与可观测体系；第 8 章讲协议机制、本附录是生态地图 |
| [附录 19：主流 Agent 沙箱系统全景](附录/附录19-主流Agent沙箱系统全景.md) | Agent 沙箱赛道全景调研（全文收录，信息基准 2026-08-30）——"Computer as an API"形态、原生云沙箱/云厂商/Coding Agent/浏览器桌面/K8s 自建五路盘点、底层隔离技术比较、参考架构与状态模型、多 Agent 沙箱模式、安全威胁矩阵与凭证设计、评测与选型；第 9 章讲机制、第 23 章 2.6 讲特化、本附录是赛道地图 |
| [附录 20：主流 RAG 系统全景与工程实践](附录/附录20-主流RAG系统全景与工程实践.md) | RAG 赛道全景与逐环节工程手册（全文收录，信息基准 2026-08-31，18 部分 155 节）——生态六大阵营与五路产品盘点、导入状态机与删除传播、解析分块、Embedding 与向量存储、索引优化、检索前后处理、生成与引用、Agentic/GraphRAG、分层评测、观测治理、选型矩阵与失败归因；第 11 章讲机制、本附录是手册 |
| [附录 21：主流 LLM Wiki 系统全景](附录/附录21-主流LLMWiki系统全景.md) | LLM Wiki（知识编译系统）赛道全景调研（全文收录，信息基准 2026-08-31）——"检索时增强 vs 写入时编译"辨析、四路生态盘点（代码仓库型 DeepWiki 类/持久知识编译型/企业知识 Wiki 与搜索/开源知识平台）、企业参考架构、核心机制、面向 Agent 的接口、选型与失败模式；与附录 1"关于 LLM 的词条书"是两回事 |
| [附录 22：主流 Loop Engineering 系统全景](附录/附录22-主流LoopEngineering系统全景.md) | 四类 Engineering（Prompt/Context/Loop/Graph）系统全景（全文收录，信息基准 2026-09-01）——统一认知与分层、四件职责边界/反模式/指标、主流系统盘点、Loop 与 Graph 模式库、生产级 Loop Contract、状态恢复与收敛、成熟度 L0–L5、选型与实施路线；附录 2 是词典、第 3/18 章讲机制、本附录是赛道地图 |
| [附录 27：企业级 Agent 平台系统全景](附录/附录27-企业级Agent平台系统全景.md) | 企业级 Agent 平台全景架构蓝图（全文收录，信息基准 2026-09）——七层架构与五平面、十大产品中心与 40 子系统盘点、构建→执行→观测→评估→优化→反馈完整闭环、统一资产模型、云服务拆分与部署拓扑、分阶段建设路线、非功能要求与架构误区；正文讲每块机制、本附录讲整栋平台怎么装配 |
</details>
<details>
<summary><b>源码解剖（附录 23–26，4 册）</b></summary>
| 附录 | 定位 |
|---|---|
| [附录 23：Pi 源码架构全景解析](附录/附录23-Pi源码架构全景解析.md) | 开源 Coding Agent「Pi」整仓源码解析（全文收录，锁定 main@853a80d）——多 Provider 隔离、Agent Loop 双层循环、会话树与压缩、扩展与信任、TUI 差分渲染、远程协议与遥测旁路，附文件级导读卡片与二次开发蓝图；第六篇讲通用机制、本附录是真实实现的完整解剖 |
| [附录 24：Claude Code 源码架构深度解析](附录/附录24-ClaudeCode源码架构深度解析.md) | Claude Code 还原源码整仓解析（全文收录，社区 source map 还原仓库、非官方，基线 b78dd22）——QueryEngine 与 Agent Loop、工具/权限/沙箱、压缩与记忆、MCP/Plugin/Skill、多 Agent 编排、50 Tool 与 87 命令参考手册；证据分级严格标注，与附录 23 互为对照 |
| [附录 25：Codex 源码架构深度解析](附录/附录25-Codex源码架构深度解析.md) | OpenAI Codex（openai/codex，Rust）整仓源码解析（全文收录，快照 main@0ae94fd）——Thread/Turn/Item 会话内核、工具编排、审批与跨平台沙箱纵深、JSONL+SQLite 持久化恢复、MCP/Plugin/多 Agent、逐 crate 导读与 28 条故障推演；附录 23/24/25 三套运行时互为对照 |
| [附录 26：OpenCode 源码全景技术解析](附录/附录26-OpenCode源码全景技术解析.md) | OpenCode（anomalyco/opencode，TS/Bun Monorepo）整仓源码解析（全文收录，锁定 dev@10765ff，v1.18.25）——V1/V2 双内核迁移活标本：SessionPrompt 聚合运行时 vs Durable Input/Event Store/Projector 可恢复架构、Location 路由、工具平台与 MCP/LSP/插件、Permission 与 Doom Loop、Electron/TUI/Web 多产品表面、27 章 + 14 份工程附录；附录 23–26 四册源码互为对照 |
</details>
---
## 双入口：正文 vs 详解扩展版
全部 27 章每章有两个入口，已在上方目录表并排给出：
- **正文**（章节列）：主线版本——六段体例、贯穿项目代码经真实测试、来源经附录 3 核验、全书交叉引用网完整。**引用与发行以正文为准。**
- **[详解版](详解扩展版/)**（深读列）：独立成文的深读版，单章约为正文十倍篇幅（更完整的推导、状态机与图示）。初稿性质：未经审读与来源核验、体例自由、代码为独立参考实现。适合正文读完后按章深潜。
两版的边界与维护规则见[该目录 README](详解扩展版/README.md)。
## 三条阅读路线
- **完整路线（转型工程师）**：按章顺读。第一、二篇建机制，第三篇上生产件，四至七篇按需——这是能力累加的设计顺序。
- **速成路线（急于上手）**：第 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（含本地需 `npm ci` 后单独执行的 `make check-mermaid`）：
| Job | 门禁 |
|---|---|
| `book-structure` | `book.yml` 与磁盘/README/outline 目录一致、章号连续、每章六段结构 |
| `markdown-render` | 全书渲染无失效加粗（cmarkgfm，GitHub 同款渲染器） |
| `cross-reference-check` | 章/附录/图号内部引用全部指向真实目标 |
| `snippet-sync-check` | 章节内代码与贯穿项目源码**逐字符一致**，漂移即失败 |
| `diagram-source-check` | 每个 D2 图源已渲染为 SVG、被正文引用且可在 GitHub 显示 |
| `mermaid-check` | 全书 1300+ 幅 Mermaid 经 mermaid.js 真实解析（与 GitHub 同引擎），语法失效即失败 |
| `contract-tests` | 贯穿项目 `pytest`（事件契约 + OTel/成本消费者，真实 OTel SDK） |
| `source-freshness` | `references/sources.yaml` 与正文/附录 3/代码常量一致，协议版本一致，时效与「待确认」可机器判定 |
> 目录单一来源 `book.yml`（`book-structure`）与来源账本 `references/sources.yaml`（`source-freshness`）均已接入：新增章节改 `book.yml` + 正文即可，时效性来源与「待确认」条目可机器判定。发行前用 `make check-sources-strict` 把「待确认」/过期升级为失败。外链存活检查已实装为独立定时 workflow（`links.yml`，每周 + 手动触发，非 PR 门禁；发行前跑 `make 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 章 / 附录 N 或 附录 N.x"；各章不重复彼此内容，交叉处一句概括 + 引用；量化、协议和时效性断言按附录 3 标记来源与核验日期。
- 完整章节大纲见 [agent-book-outline.md](agent-book-outline.md)。
连接信息
猜你喜欢
暂无推荐服务器