吃透 AI Agent 开发

原创系列 · Agent 工程课程

从一个用户请求出发，完整拆解 Agent 的认知、Loop、工具、上下文、记忆、协作、Harness 与质量保障。文章重点放在可以迁移到不同项目的工程思想。

这套课程从 2026 年 3 月开始，到 2026 年 7 月 31 日收束，共 33 篇。我们不把 Agent 讲成某个框架的 API 清单，而是沿着真实请求逐层回答：模型如何决定下一步，工具如何安全地产生副作用，上下文和记忆如何保持新鲜，多 Agent 如何协作，系统又如何证明自己真的完成了任务。

每篇都包含一个生活化场景、一张 Mermaid 路线图、失败反例、可选源码索引和 10 至 30 分钟练习。q-code 只承担“把思想落到真实代码”的参考角色，不阅读它也不影响理解。

发布周期：2026-03-01 至 2026-07-31　文章数量：33　正文规模：约 15 万字

第一章 · 认知校准

1. 01
   从聊天到执行：Agent 系统有哪些核心层次2026-03-01

   先不急着选框架，沿着一次读取文件的请求，认识入口、上下文、Loop、工具、状态、界面和观测七层边界。

2. 02
   Agent 应用如何启动：入口层与运行层为什么要分开2026-03-06

   用户只想看帮助时，不应该先加载模型、MCP 和终端 UI。启动边界决定了速度、可测试性和故障半径。

3. 03
   六大支柱地图：为什么不同 Agent 产品仍然有共同骨架2026-03-11

   Claude Code、Cursor、Manus 看起来差异很大，但都在处理同一组问题：循环、工具、上下文、记忆、协作和 Harness。

4. 04
   做 Agent 开发前，哪些大模型机制必须先懂2026-03-16

   不需要先读完论文，但要理解 token、上下文窗口、reasoning、tool call 和 provider 差异，否则很多工程问题会被误判成 Prompt 问题。

5. 05
   2026 年了，Agent 架构还要不要依赖大框架2026-03-21

   框架可以节省样板代码，却不能替你决定权限、状态、失败恢复和观测边界。先理解原理，再决定抽象层。

第二章 · Agent Loop

1. 06
   Agent Loop：模型、工具与消息如何形成闭环2026-03-26

   模型看一眼、决定下一步、系统执行，再把结果交回模型。真正的难点在消息演进和停止条件。

2. 07
   把 Agent Loop 做成状态机：每一步到底处于什么状态2026-03-31

   当 Loop 加入中断、重试、并发和后台任务后，单个布尔值 done 已经不够。显式状态能让行为可测试。

3. 08
   流式响应、Reasoning 与重试：不要把模型输出当一段字符串2026-04-05

   模型返回的可能是文字、思考、工具调用、用量和警告。正确拆分这些 part，才能同时做好 UI、审计和下一轮请求。

第三章 · Tool System

1. 09
   Function Calling 与 Structured Output：模型如何学会调用函数2026-04-10

   工具调用不是模型直接执行代码，而是模型按照 schema 表达一个结构化意图，再由应用决定是否执行。

2. 10
   工具系统：统一执行入口为什么比工具函数更重要2026-04-15

   工具一多，超时、权限、Hook、审计和结果裁剪不能靠每个函数各写一套。注册表是副作用的统一边界。

3. 11
   一次工具调用背后发生了什么：从意图到副作用2026-04-20

   把一次读文件或跑命令拆成可检查的流水线，才能知道问题出在参数、路径、进程、输出还是模型理解。

4. 12
   工具太多模型选不准：Deferred Loading 与动态工具集2026-04-25

   工具描述也占上下文。工具数量变多后，按需加载、搜索和动态注册比把全部工具常驻更可靠。

5. 13
   MCP 的工程真相：协议很好，但连接不是免费的2026-04-30

   MCP 让远程能力有了统一插槽，但连接、超时、版本、权限和数据边界仍然要由宿主应用负责。

6. 14
   你敢让 AI 直接跑 rm -rf 吗：生产级权限的四层防线2026-05-05

   权限不是工具名称上的一个 readonly 标记，而是路径、参数、环境、审批和审计共同组成的纵深防线。

第四章 · Context Engineering

1. 15
   Context Engineering 全景：上下文不是一段 Prompt2026-05-10

   上下文同时涉及选择、顺序、预算、时机和新鲜度。只会写 system prompt，还远远不够。

2. 16
   System Prompt 工程化：稳定规则与动态上下文怎么分层2026-05-15

   把 Prompt 变成带稳定性和类别元数据的管道，避免每轮变化的 Git 状态、日期和任务列表污染稳定前缀。

3. 17
   上下文快爆了怎么办：压缩、预算与 Offload2026-05-20

   对话、工具输出和子任务结果都会增长。压缩保留语义，预算控制注入，Offload 保存完整正文，三者不能混为一谈。

4. 18
   Cache 与成本控制：稳定前缀为什么值钱2026-05-25

   Prompt Cache、KV Cache、Context Collapse 不是一回事。理解缓存边界，才能解释延迟和成本为什么突然上升。

5. 19
   Just-In-Time Context：信息不是越早塞越好2026-05-30

   启动时把所有文件、工具和记忆都塞给模型，会让上下文拥挤且陈旧。按需读取更接近真实工作。

6. 20
   RAG 全流程：从一堆文档到 Agent 能用的知识库2026-06-04

   RAG 不只是向量检索。切分、元数据、召回、重排、引用和过期处理共同决定知识能不能被可靠使用。

7. 21
   检索优化：语义相似不等于任务相关2026-06-09

   用户问的是“我现在该改哪里”，检索却可能返回一堆“概念相似”的旧文章。任务、权限、时间和证据都要进入排序。

8. 22
   LLM 编译知识库：让零散经验变成可连接的系统2026-06-14

   知识库不是文件堆。把结论、来源、关系、版本和验证状态结构化，Agent 才能持续积累而不是重复聊天。

9. 23
   Agent 的记忆系统：文件派、数据库派和生命周期2026-06-19

   聊天记录、会话状态、项目记忆和用户偏好生命周期不同。先分层，再决定文件还是数据库。

10. 24
    记忆会坏：五种失效模式和工程解法2026-06-24

    记忆可能过时、冲突、过度泛化、被污染或无法追溯。可靠记忆需要年龄、来源、验证和删除机制。

第五章 · 规划与任务

1. 25
   规划与任务系统：从自然语言意图到可执行任务图2026-06-29

   “先给计划，不要执行”、进度清单和持久化任务图是三件不同的事，应该由不同状态和模块负责。

2. 26
   本地文件、图片附件与可回滚写入：让 Agent 改得起也退得回2026-07-04

   路径边界、图片临时注入、写前快照和冲突检测共同决定 Agent 改文件是否可控。

3. 27
   流式交互界面：事件驱动设计如何承接 Agent2026-07-09

   模型文本、工具进度、后台通知和输入状态会同时变化，界面应该消费语义事件，而不是直接监听内部函数。

第六章 · Multi-Agent

1. 28
   多 Agent 协作：上下文隔离、后台执行与通信2026-07-14

   多 Agent 不是简单复制线程。任务边界、上下文隔离、结果预览、通知和生命周期才是协作的难点。

2. 29
   多 Agent 编排模式：什么时候并行，什么时候串行2026-07-19

   并行能缩短等待，但会增加重复、合并和限流成本。编排应该由任务依赖和证据需求决定。

第六章 · Harness

1. 30
   Agent Harness：把模型能力变成可重复的工作系统2026-07-24

   真正稳定的 Agent 依赖的不只是模型，还包括配置、工具、状态、策略、事件、恢复和运行入口组成的 Harness。

2. 31
   如何验证一个 Agent：可观测性、测试与 Eval2026-07-27

   没有报错不代表完成任务。日志、轨迹、单元测试、集成测试和 Eval 要共同回答发生了什么、是否正确以及是否退化。

3. 32
   从本地 Agent 到可交付产品：可靠性、部署与降级2026-07-29

   部署后要面对网络、模型限流、上下文过长、外部服务不可用和进程崩溃。可靠性来自明确的降级和恢复协议。

收束

1. 33
   结课：从 10 行代码到 Agent 六大支柱2026-07-31

   把 33 篇内容重新串成一条判断路径：先看任务，再看上下文、工具、状态、协作和质量，而不是先问该用哪个框架。