《AI Agent 工程实战》全 55 篇，是一套以把 Agent 引擎装成产品为主线的工程书：卷一的
minagent在这里不再改动，而是被四层边界（引擎 / 服务 / worker / 存储）包起来，长成一个研究助理服务ResearchCopilot——用户提问，Agent 多跳检索本地语料、调用工具（含本地 Postgres 查询）、生成带引用的报告，后台 worker 周期跑语料更新与日报。全卷按工程推进顺序展开：需求与验收标准、架构边界、配置与密钥、REST 与 SSE 契约、认证与租户隔离、Schema 与事务、查询优化、缓存与限流、异步队列、结构化并发、TS 流式前端、MCP 工具接入、记忆服务、评测与质量门、追踪与指标、延迟与成本、安全护栏、双栈镜像、compose 编排、CI/CD 与灰度、容量评审与故障演练。所有示例基于 Python 3.14（本机实测 3.14.6）与 Node 26（本机实测 26.5.0）实跑，默认走假模型路径，零凭据、零成本；Postgres 17.11 与 Redis 7.4.11 由本机容器提供。
本页是《AI Agent 工程实战》的全书目录：按章节顺序列出全部 55 篇，点击标题直达正文。也可以从各节末尾的「阅读导航」按顺序通读，或先看目录篇 里的三条阅读路径与六周计划。
全书概览
| 项目 | 内容 |
|---|---|
| 书稿 | 《AI Agent 工程实战》 |
| 篇数 | 55 篇（目录篇 + 正文 18 章 54 节） |
| 领域 | Agent 服务的工程化：从接口契约到上线交付 |
| 贯穿项目 | ResearchCopilot —— 一个由 minagent 驱动的研究助理服务，18 章逐步长大 |
| 阅读方式 | 从目录篇 进入按顺序通读，或按症状跳读 |
| 实测版本 | Python 3.14.6、Node 26.5.0、PostgreSQL 17.11、Redis 7.4.11 |
| 依赖 | 本卷放心使用工程库：pydantic-settings / FastAPI / psycopg / redis / mcp 等均为真装真用 |
| 前置 | 建议先读卷一《AI Agent 开发入门》，本卷复用其核心契约 |
| 上级专题 | 书稿专题 |
全书目录
前置
| 节 | 文章 | 核心内容 |
|---|---|---|
| — | 目录与学习路径 | 全书导航页：本卷怎么读、三条阅读路径与六周计划、六部分依赖关系与 54 节逐节索引、常见问题速查表 |
第一部分：项目地基（第 1–4 章）
| 节 | 文章 | 核心内容 |
|---|---|---|
| 1.1 | 1.1 需求与用例：3 个核心用例与验收标准 | 定下三个用例与可判定的验收标准，明确「不做什么」，并给出用例与章节的映射 |
| 1.2 | 1.2 架构总览：引擎 / 服务 / worker / 存储边界 | 划清四层边界与依赖方向，走一遍请求从进来到出结果的完整时序 |
| 1.3 | 1.3 仓库与工程骨架：monorepo + TS 包，CI 跑通 lint/test | 建 monorepo 目录树，本地真跑通 pytest 与 node –test，附 CI 形态 |
| 2.1 | 2.1 分层配置：pydantic-settings 加载与校验 | 四级来源合并（默认 → 文件 → 环境变量 → 显式参数）与校验，配置靠注入而非全局读取 |
| 2.2 | 2.2 密钥管理：Anthropic key / DB / Redis 本地注入 | 密钥不落库、不进镜像、不进日志三条线，缺失即 fail-fast，SecretStr 自动脱敏 |
| 2.3 | 2.3 模型路由与降级：真/假模型开关，离线默认假模型 | 默认假模型零凭据可跑，主模型失败时按链降级且降级必须透明 |
| 3.1 | 3.1 REST 设计：session / run / message 资源建模 | 为什么 run 是独立资源而不是 session 的一个动作，OpenAPI 契约的形态 |
| 3.2 | 3.2 流式接口：SSE 推送事件 | 事件 envelope（id / event / data）设计，SSE 与 WebSocket 的取舍表 |
| 3.3 | 3.3 幂等、分页与统一错误契约 | Idempotency-Key 重复 POST 只建一次 run，游标分页与统一错误响应体 |
| 4.1 | 4.1 认证：JWT 与 API Key 中间件 | 两种凭证并行支持，过期、篡改签名、无凭证各自返回什么错误码 |
| 4.2 | 4.2 授权与租户隔离：workspace 行级隔离 | 跨租户访问返回 404 而非 403，以及 PostgreSQL 行级安全策略兜底 |
| 4.3 | 4.3 工具权限与审批：高危工具二次确认 | 工具分只读 / 写入 / 危险三档，危险调用挂起等人工审批再继续 |
第二部分：数据与性能底座（第 5–6 章）
| 节 | 文章 | 核心内容 |
|---|---|---|
| 5.1 | 5.1 Schema 设计：会话/消息/运行/记忆表 + 迁移 | 四张表的 DDL 与迁移版本表，消息体存原始 JSON 以保真 |
| 5.2 | 5.2 事务与并发：run 状态机原子更新、行锁防重复执行 | 「先查再改」为什么会跑两遍，原子抢占与 SKIP LOCKED 怎么写 |
| 5.3 | 5.3 查询优化：EXPLAIN 定位慢查询并加索引 | 五万行数据上的真实执行计划对比、部分索引与写放大的取舍 |
| 6.1 | 6.1 Redis 缓存：检索结果与嵌入缓存命中率 | 缓存 key 必须带租户，穿透 / 击穿 / 雪崩在 Agent 场景的具体形态 |
| 6.2 | 6.2 语义缓存：相似问题复用与错配检测 | 为什么阈值分不开对错，哪些类型的问题绝不能走语义缓存 |
| 6.3 | 6.3 限流与配额：按租户 token 预算的令牌桶 | Lua 原子限流与 token 预算扣减，被限流时 Agent 该怎么办 |
第三部分：异步与前端（第 7–9 章）
| 节 | 文章 | 核心内容 |
|---|---|---|
| 7.1 | 7.1 任务队列：run 丢给 worker 异步执行 | 可靠队列与裸队列的区别，以及 202 返回后的完整生命周期 |
| 7.2 | 7.2 重试、死信与幂等 | 指数退避加抖动、超过上限进死信并记录原因，重试必须配幂等 |
| 7.3 | 7.3 定时与延迟任务：周期语料更新与日报 | 分布式锁的 token 校验与续期，延迟任务用有序集合实现 |
| 8.1 | 8.1 引擎内并发：并行工具与并行子 Agent | asyncio.TaskGroup 真并发，结果按调用顺序而非完成顺序回填 |
| 8.2 | 8.2 背压与资源池：信号量限并发 | 并发上限怎么估，生产快于消费时怎么让上游慢下来而不是无限堆积 |
| 8.3 | 8.3 取消、超时与泄漏：慢工具注入验证止损 | 注入慢工具验证超时止损，以及游离任务与取消传播 |
| 9.1 | 9.1 事件协议：token/tool/step 统一 schema，TS 与 Python 共享类型 | TypeScript 判别联合类型与三种共享类型做法的代价对照 |
| 9.2 | 9.2 前端渲染：TS 最小聊天 UI 逐步显示 | 纯函数归约器与渲染器，增量渲染与全量重渲染的取舍 |
| 9.3 | 9.3 断线重连：Last-Event-ID 续传不丢步 | 服务端事件缓冲、缓冲淘汰后的 resync 全量重取降级 |
第四部分：生态、记忆与质量（第 10–12 章）
| 节 | 文章 | 核心内容 |
|---|---|---|
| 10.1 | 10.1 MCP 客户端接入：minagent 作为 client 连本地 Server | 远程工具适配成 Tool、命名冲突处理与错误映射，协议本身不展开 |
| 10.2 | 10.2 工具设计模式：读写分离、幂等、可观测 | 描述即提示词、工具粒度、幂等键设计与调用留痕 |
| 10.3 | 10.3 工具沙箱：子进程/容器隔离高危工具 | 子进程只能隔离崩溃，容器才能隔离权限；未部署的方案如实标注 |
| 11.1 | 11.1 写入流水线：抽取、去重、冲突消解 | 抽取 → 去重 → 冲突消解，以及重放同一段对话不产生重复记忆 |
| 11.2 | 11.2 检索注入：长期记忆接入 run 并量化收益 | 注入位置取舍，以及只改一个变量的对照实验与得分差异 |
| 11.3 | 11.3 记忆治理：TTL、隐私与按用户删除 | 写入侧拒绝清单、级联删除与审计留痕 |
| 12.1 | 12.1 评测集与评分器：成功率/引用准确率/成本 | 可版本化评测集的维护纪律与三个评分器，自动与人工打分分界 |
| 12.2 | 12.2 离线回放与夹具：假模型 + 录制样本确定性回归 | 夹具回放机制，以及夹具失配必须报错而不是静默给错响应 |
| 12.3 | 12.3 CI 质量门：分数下降即拦截 | 基线怎么维护、为什么不能只看均值、退化怎么被拦住 |
第五部分：可观测、性能与安全（第 13–15 章）
| 节 | 文章 | 核心内容 |
|---|---|---|
| 13.1 | 13.1 结构化日志与追踪：OTel GenAI 语义约定埋点 | span 树与上下文传播，字段名对齐 GenAI 语义约定 |
| 13.2 | 13.2 指标与看板：延迟/成功率/成本/工具错误 | 为什么平均值会骗人、指标基数陷阱与看板四块布局 |
| 13.3 | 13.3 告警与 on-call：从 trace 到告警演练 | 告警规则表、SLO 与错误预算、从告警到具体 trace 的排查动作 |
| 14.1 | 14.1 延迟剖析：模型/检索/工具各占多少 | 分阶段计时与占比，以及同步阻塞拖垮异步服务 |
| 14.2 | 14.2 成本优化：缓存、路由、小模型降级 + 评测兜底 | 三招降本、误判代价，以及降本必须过评测兜底 |
| 14.3 | 14.3 吞吐与并发压测：找容量上限与拐点 | 四档并发找拐点，以及加超时后 QPS 虚高、错误率飙升的假象 |
| 15.1 | 15.1 输入侧：提示注入与越权工具拦截 | 间接注入最危险，内容与指令必须分离，危险工具要白名单拦截 |
| 15.2 | 15.2 输出侧：敏感信息、越狱与幻觉引用校验 | 引用存在不等于引用支持，校验必须回语料核对 |
| 15.3 | 15.3 审计与合规：不可篡改审计日志 | 哈希链审计日志，以及它与「按用户删除」之间的张力 |
第六部分：交付（第 16–18 章）
| 节 | 文章 | 核心内容 |
|---|---|---|
| 16.1 | 16.1 TS 落点三：Python + Node 双栈镜像瘦身 | 多阶段构建与四个瘦身杠杆，为什么 latest 是坑 |
| 16.2 | 16.2 本地编排：compose 起 API/worker/postgres/redis | depends_on 不等于依赖就绪，healthcheck 加 service_healthy 才有用 |
| 16.3 | 16.3 配置注入、健康检查与优雅退出 | liveness 与 readiness 的区别，收到 SIGTERM 后要做什么 |
| 17.1 | 17.1 流水线：lint/test/评测/构建串联 | 阶段顺序的代价权衡，评测必须在 CI 里用夹具回放跑 |
| 17.2 | 17.2 灰度与回滚：新提示/新模型小流量 | 提示词也是可发布的配置，回滚必须演练过才算回滚 |
| 17.3 | 17.3 版本与迁移：不中断 schema 迁移演练 | expand–contract 五阶段，以及长事务锁表与并发建索引的坑 |
| 18.1 | 18.1 容量与架构评审清单 | 五组带通过标准的评审清单与一份可执行的容量估算 |
| 18.2 | 18.2 故障演练：模型超时/DB 宕机/队列积压 | 三个受控演练的注入方式、观测点与复盘问题 |
| 18.3 | 18.3 上线、观察与迭代 + 真实 API 端到端冒烟（可选） | 观察节奏、迭代闭环，以及需自备密钥的可选真实冒烟流程 |
怎么用这份索引
- 顺序通读：从第 1 章 1.1 开始，每一节末尾都有上一节 / 下一节的导航。若不确定从哪开始，先看目录篇的三条阅读路径 。
- 按症状跳读：配置散落看 2.1、密钥进了日志看 2.2、模型挂了服务就挂看 2.3、前端要边生成边显示看 3.2 与 9.2、同一 run 跑了两次看 5.2 与 7.2、查询变慢看 5.3、账单爆了看 6.3 与 14.2、并发一高就卡死看 8.2 与 14.3、慢工具拖死整个 run 看 8.3、断线丢了一段看 9.3、模型选错工具看 10.2、不知道慢在哪看 13.1、告警太多没人看 13.3、不知道扩几台机器看 18.1。目录篇另有一张按现象索引的速查表。
- 只补工程短板：已经会写 Agent 但没做过服务化的读者，重点读第 3、5、7、8、13、16 章。
- 想动手：18 章全程只有
ResearchCopilot一个项目，每一节都在它的真实代码上推进。Postgres 与 Redis 用docker run -d --name ab-pg -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=research -p 15435:5432 postgres:17-alpine与docker run -d --name ab-redis -p 16380:6379 redis:7-alpine起即可。
相关阅读
- 《AI Agent 开发入门》目录
— 本卷的前置卷，从零手写引擎
minagent；本卷复用其核心契约 - LLM / AI 开发专题 — Agent 架构、工具调用、记忆与多 Agent 协作的概念与方法；本卷把它们落成服务代码
- MCP 专题 — Model Context Protocol 的协议、Server 与传输细节；本卷只讲「作为 client 接工具源」
- LLMOps 专题 — 模型侧的上线与运维；本卷讲应用侧的评测门、追踪、SLO 与成本治理
- 可观测性专题 — 日志、指标、链路追踪的通用方法，与本卷第 13 章衔接
- 测试专题 — 测试策略与质量体系，与本卷第 12 章衔接
- 书稿专题 — 全部在线电子书与创作手记