结论先说：学 Agent 不该按文件顺序学，而该按“系统约束顺序”学 #

前面 01-09 篇，我们已经把 SecurityClaw 的框架骨架拆开了。到这里，问题变了：

如果我不是只想“看懂这个项目”，而是想真正建立 Agent 开发的知识框架，我应该按什么顺序理解这些概念？

我的答案不是：

先学 prompt
再学 tools
再学 RAG

而是这条顺序：

执行循环：系统到底怎么一步步推进
工具调用运行时：模型提出动作以后，谁来验证和执行
状态与记忆：哪些信息属于当前状态，哪些属于可恢复上下文
RAG 与上下文工程：什么知识应该被检索进当前决策
评估、恢复与停止条件：失败后怎么办，什么时候必须停
安全护栏与权限：哪些边界不该交给模型自己判断
可观测性与评测：你怎么证明 Agent 没在乱来
架构取舍：什么时候该上工作流、单 Agent、多 Agent

这篇的作用，就是把后面 11-18 篇连成一条真正可学的主线。

一、为什么不能按“功能模块”学 Agent #

很多人学 Agent 的方式是：

今天看 Tools
明天看 RAG
后天看 Memory

这种学法的问题是：你会把每个模块当成孤立功能，而不是一个互相约束的系统。

但真实 Agent 的关键不在于“模块有几个”，而在于它们的依赖关系：

flowchart TD
    Loop[执行循环] --> Tools[工具调用运行时]
    Loop --> State[状态与记忆]
    Tools --> Guardrails[权限/预算/护栏]
    State --> Checkpoint[checkpoint / 会话恢复]
    State --> RAG[RAG / 上下文注入]
    Loop --> Evaluation[评估与恢复]
    Evaluation --> Observability[trace / metrics / eval]
    Guardrails --> Architecture[单Agent / 多Agent / 工作流取舍]

这张图说明了一件很重要的事：

你不先理解循环和状态，就很难真正理解工具调用、RAG 和恢复。

二、第一优先级：执行循环 #

Agent 不是“一次模型调用”，而是：

decide -> execute -> evaluate -> continue / recover / stop

这是你必须最先掌握的东西。因为后面所有模块，都是围绕这条外循环服务的。

为什么它排第一 #

因为不搞清循环：

你不知道 state 在哪里更新
你不知道失败该回到哪一步
你不知道 RAG 注入应该发生在规划前还是恢复后
你不知道停止条件属于哪个层面

后面 11-15 篇，其实都是在给这条循环加约束。

三、第二优先级：工具调用运行时 #

很多人以为 Agent 的重点是“模型能不能学会挑工具”。其实真正危险的点不是挑，而是执行。

正确的理解应该是：

# 伪代码：模型只提议，运行时执行
action = llm.plan(state)
validated = runtime.validate(action)
result = runtime.execute(validated)
observation = runtime.record(result)

这一层回答的问题 #

工具名是否合法
参数是否符合 schema
是否有权限
预算是否允许
结果如何结构化回流

你如果不先理解这层，后面谈 Guardrails 和 Evaluation 都会悬空。

四、第三优先级：状态与记忆 #

State 和 Memory 是 Agent 系统里最容易混的概念。

4.1 state #

当前这轮运行里，节点之间传递的结构化字段

4.2 working memory #

在多步内保留当前焦点和中间发现

4.3 checkpoint #

为了恢复而保存的、足够小的结构状态

4.4 RAG #

外部长期知识层，不是运行中的 state

这四样如果混在一起，Agent 迟早会出现：

prompt 膨胀
恢复缓慢
失败路径解释不清
检索结果污染当前状态

所以我把“状态与记忆”排在 RAG 前面。因为你必须先知道“当前系统内部已经记住了什么”，才知道还需要从外部检索什么。

五、第四优先级：RAG 不是默认参与者，而是条件参与者 #

这是很多人入门 Agent 时最容易误解的一点。

RAG 不是“只要有知识库就应该参与”。

它只应该在这种时刻介入：

当前 state 不足以支撑判断
外部证据可能改变决策
检索收益大于上下文成本

这就是为什么我把 RAG 放在 state / memory 之后。

你先要知道系统内部的状态边界，才能判断哪些知识值得被拉进当前回合。

六、第五优先级：评估、恢复和停止条件 #

Agent 的可靠性，不看它能不能“继续”，而看它：

什么时候承认证据足够
什么时候进入恢复路径
什么时候强制停下

这是“系统是否诚实”的核心。

为什么这一步排在后面 #

因为恢复和停止，是在执行循环、运行时、状态系统都成立之后，才能正确定义的。

如果你连：

state 怎么更新
result 怎么结构化
permission 怎么检查

都没搞清楚，就谈恢复路径，只会变成空话。

七、第六优先级：安全护栏不是最后补丁，而是执行前的边界系统 #

很多教程把 Guardrails 当成最后加的安全模块。这会误导你。

更准确的理解是：

Guardrails 不是“后处理”，而是执行前置条件系统。

它至少包括：

权限
人工确认
幂等性
预算
注入防护

这一步排在恢复之后，不是因为它不重要，而是因为你要先理解系统“会怎么跑”，才能理解“为什么这些边界必须在这里拦”。

八、第七优先级：可观测性和评测 #

很多 Agent 项目最后失败，不是因为能力不够，而是因为你根本不知道它为什么失败。

可观测性层至少要回答：

这次计划是什么
执行了哪些工具
每一步花了多久
哪一步失败了
为什么进入恢复
为什么最终停止

而评测层再往上走一步：

最终答案是否正确
证据链是否足够
恢复路径是否合理
空结果是否被正确区分

这一步被我放在后面，是因为它是前面所有层都成立后的“系统证明层”。

九、第八优先级：架构取舍 #

到了最后，你才真正有资格回答这些问题：

单 Agent 够不够
多 Agent 什么时候必要
工作流是不是比 Agent 更合适
有些任务是不是根本不该上 Agent

这一步排最后，不是因为它最不重要，而是因为它最依赖前面所有认知。

没有前 1-7 步，你谈架构，只会落进“多 Agent 看起来更高级”的幻觉里。

十、这一篇真正要带走的学习顺序 #

如果你想建立 Agent 开发知识框架，按这个顺序学：

基础骨架层 #

执行循环
工具调用运行时
状态与记忆

知识与恢复层 #

RAG 与上下文工程
评估、恢复与停止条件

控制与证明层 #

安全护栏与权限
可观测性与 Agent 评测
架构取舍

这就是后面 11-18 篇真正的阅读地图。

十一、验证命令 #

# 这一篇本身是路线图，不对应单个测试
# 建议后续按章节逐篇跑：
pytest tests/ -k "runtime or memory or rag or recover or permissions or eval" -v