AI Agent 知识体系总览

What（本文讲什么）

这篇总览回答两个问题：

1. 这个方向到底在解决什么工程问题。
2. 这棵树应该怎么读，读完你能做出什么“可运行、可审计、可复盘”的 agent 系统。

这里的 AI agent 指的是一类“闭环系统”：它把大模型当作不可信的推理组件，用一个可控的 runtime 把推理、工具调用、状态持久化、错误处理、权限隔离、以及观测审计串成一条可验证的执行链。

Problem（这个方向解决的工程问题）

把 agent 当成“一次补全 + 一次工具调用”的脚本，会非常快撞上真实世界的硬边界：

1. 无状态: 模型本身不持久化，长任务需要外部状态机、检查点、恢复流程。
2. 有副作用: 工具调用会写文件、发请求、改数据库，重试会制造重复提交与不可逆破坏。
3. 上下文稀缺: 上下文窗口不是越大越好，长上下文会出现注意力退化与“中间信息更难被用到”的现象，需要动态装配与压缩策略。
4. 不可信输入: 模型输出是字符串，不等于“可信指令”；必须做 schema 校验、权限裁剪、速率限制、超时、幂等和审计。
5. 长时间运行: 超时、僵死、重试风暴、资源泄露、并发竞争、日志爆炸，都会在数小时尺度必然发生。
6. 多代理协作: 引入职责边界、状态同步、错误传播、工具污染、权限传递，以及最终的“谁为副作用负责”的归因问题。

这个方向的目标，是把 agent 拆成可理解、可实现、可调试、可验证的工程系统。读完这棵树后，你应该能回答更底层的问题：如果一个 agent 要在真实机器上连续工作数小时，它的控制回路、工具边界、状态恢复和安全隔离到底由哪些部件共同保证。

Usage（读完你能做什么）

你至少能实现一个“可上线骨架”，具备下列能力：

1. 统一的执行循环: observe -> plan -> act -> verify -> commit -> loop/stop。
2. 工具治理管线: 每次 tool call 都走校验、权限、超时、重试、幂等、审计。
3. 状态落盘与恢复: 任务状态、工具结果、以及关键决策点可重放，且不会重复制造副作用。
4. 动态上下文装配: 规则前缀稳定，现场信息优先，历史可压缩，检索可控。
5. 观测与复盘: trace/span、结构化日志、失败原因分布与回放链路。
6. 沙箱与隔离: 不可信代码执行时，把“事故半径”限制在可接受范围内。

为了让这件事不空洞，这棵树会不断把“抽象名词”落回到可落地的工程对象：

1. 一个可运行的 runtime（进程、线程、事件循环、调度器）。
2. 一套可验证的协议（schema、类型、工具接口、错误码、重试策略）。
3. 一条可审计的数据流（WAL、事件日志、trace、回放）。
4. 一组可隔离的执行环境（容器、用户态内核、最小权限、零信任）。

Principle（把 agent 拆成哪些组件）

可以用“控制回路 + 约束层”的视角理解 agent：

1. 控制回路: 让系统能持续运行并收敛到目标。
2. 约束层: 让每一步都可控、可追溯、可回滚（至少可停止），以及可被审计。

1) 控制回路（闭环）

一个最小闭环可以抽象成下面这条链：

观察(Observe) -> 推理(Think/Plan) -> 行动(Act) -> 校验(Verify) -> 提交(Commit) -> 继续/停止

关键点不是“循环”本身，而是你把副作用放在了哪里：

1. 观察只读: 读取文件、日志、网页、DB 查询结果，不能产生副作用。
2. 行动受限: 只允许 runtime 调工具，模型不直接接触系统能力。
3. 提交显式: 把“写文件/改数据库/发请求”作为显式提交点，配合幂等与审计。

2) 工具执行层（把字符串变成动作）

工具执行层负责把模型输出（字符串/JSON）变成真实动作，但它必须同时扮演“翻译器”和“守门人”：

1. 解析: 严格解析（JSON schema / typed tool）。
2. 校验: 参数白名单、路径约束、正则/AST 约束。
3. 授权: 作用域、最小权限、沙箱、网络访问策略。
4. 约束: 超时、并发、速率、资源配额。
5. 幂等: 幂等 key + 提交记录（WAL）防止重放副作用。

3) 记忆与持久化（让 agent 能“续命”）

持续运行必然中断。工程问题不是“如何不崩”，而是“崩了如何恢复”：

1. 短期记忆: 当前任务现场、打开的文件、最近对话。
2. 长期记忆: 可检索的事实库（文档、代码索引、工单、知识库）。
3. 任务状态: 进度、分支、已做动作的提交记录、下一步计划。
4. 恢复协议: 重启后从状态机恢复，不重复提交副作用。

4) 上下文投喂（让 token 花在刀刃上）

上下文投喂不是“把更多文本拼进去”，而是“把 token 当作可调度资源”：

1. 稳定前缀: 规则/工具定义尽量固定，利于缓存与稳定行为。
2. 现场优先: 当前文件、错误日志、调用栈、单测失败信息。
3. 历史压缩: 把旧对话压成结构化事实与决策点。
4. 检索可控: RAG 不是多多益善，需要可解释的检索与去噪。

5) 隔离与可观测（强能力必须配强约束）

agent 的能力越强，事故半径越大。两个横切层必须从一开始就设计进去：

1. 隔离: 进程权限、文件系统只读/白名单、网络 egress 控制、容器/用户态内核。
2. 可观测: 结构化日志、trace/span、审计日志、回放与复盘工具。

当前知识树的学习顺序（目录即依赖图）

content/zh/06-ai-agent 按“先定义边界，再建立闭环，再给闭环装上工具与约束”的顺序组织：

这个顺序的理由是：先把“边界与闭环”讲清楚，再把“工具与外接感官”接进来，最后补齐“长期运行的约束与运维”。很多失败的 agent 项目，都是反过来走：先做一个能跑的 demo，然后才补幂等/权限/观测，结果越补越返工。

概览文章和深度文章的分工

这篇 00-ai-agent-overview.md 只负责“地图与边界”，不替代任何单篇深文。后续每个一级目录会出现两类文章：

1. 父节点概览文章: 解释模块内部边界、路线、对比、前置依赖。
2. 叶子深度文章: 聚焦一个机制，讲清 What/Problem/Usage/Principle/Source/Design/Pitfalls/Debug。

父节点讲地图，叶子讲机制。地图不讲细节，细节不重复画地图，这是为了让整个知识库可维护，不会在全局到处复制同一段定义。

本方向的验收标准（不是“更长”就算赢）

验收不看“字数”，看能否支撑真实工程：

1. 体系层: 目录顺序是否体现真实前置依赖（否则会反复返工）。
2. 文章层: 单篇是否把一个机制讲透（机制、实现路径、失败模式、防错设计）。
3. 工程层: 能否防止真实事故（超时、重试、幂等、权限、隔离、观测、审计）。

因此，这个方向的重构会先稳住最前置的基础文章（定义、边界、行动范式、循环理论），再向后推进模型路由、记忆、工具调用、MCP、多代理、安全隔离与运维调试。

资料入口（便于追踪版本与证据）

本方向的每篇文章在重写前都会生成一份 research dossier，存放在：

.agents/runs/06-ai-agent/research/articles/<article>.md

它的作用不是“堆链接”，而是把关键事实与一手来源固定下来，避免正文出现编造机制或随口给结论的情况。

最小落地清单（把这棵树变成代码）

如果你要从零开始做一个能跑的 agent runtime，可以用下面这份清单对照自检。它刻意不提具体框架名字，只描述“你必须实现的对象与边界”。

1) 任务与状态机

1. Task（任务）: 目标、输入、约束、截止时间、预算。
2. Step（步骤）: 可重放的动作单元，拥有明确的输入输出。
3. TaskState（状态）: 当前步骤、已完成步骤、下一步候选、失败次数。
4. Checkpoint（检查点）: 在副作用前后落盘，支持恢复与回放。

2) 工具与治理

1. Tool（工具接口）: name、schema、执行函数、超时、权限域。
2. ToolResult（工具结果）: 结构化数据 + 原始输出 + 截断信息。
3. Gate（治理管线）: parse -> validate -> authorize -> execute -> record。
4. WAL（提交记录）: 每次副作用写入一条不可变记录（谁、何时、对哪个资源、做了什么、结果如何）。

3) 上下文与记忆

1. ContextAssembler（装配器）: 把规则、现场、历史、检索片段拼装成可控输入。
2. MemoryStore（记忆库）: 文档/代码索引、检索接口、去噪策略。
3. Compressor（压缩器）: 把历史折叠成结构化事实与决策点。

4) 观测与审计

1. Trace（链路）: 一次任务 -> 多次调用 -> 多个工具步骤。
2. Span（跨度）: 每次模型调用、每次工具调用都是一个 span。
3. AuditLog（审计日志）: 用于事后回答“到底发生了什么”。

5) 隔离与权限

1. 文件系统: 只读挂载、白名单路径、禁止写出工作区。
2. 网络: 默认拒绝，按域名/端口/目的地白名单放行。
3. 进程: 资源配额（CPU/内存）、超时与强制回收。

常见误区（这些坑会让你反复返工）

1. 先做 demo，后补治理: 你会发现所有“补丁”都要改接口，返工巨大。
2. 把模型当执行者: 让模型直接拼 shell 命令并执行，等同把不可信输入直连系统调用。
3. 只记录文本日志: 不能复盘，也无法做统计；必须有结构化字段与 trace id。
4. 认为“加大上下文就行”: 上下文管理是结构问题，不是容量问题。
5. 把多代理当成并发: 多代理带来的不是“更快”，而是“更复杂的归因与同步”。

这也是为什么本方向会把“边界、闭环、治理、持久化、上下文、隔离、观测”作为主线，而不是把某个热门框架当主线。

下一步阅读建议：先把 01-认知与启蒙 四篇打透，再回到这里对照“最小落地清单”逐项落地实现。