00b 全景：一个循环推出整个系列

每篇单独看都能懂，合起来却串不成一张图，原因是系列按专题切开，每篇自成一体，没讲清楚”为什么学完这篇就会冒出下一篇的问题”。

这一篇只做一件事：给出一条主线，让 16 篇都能挂上去。 不讲新知识。

读法：先读完这篇，之后每读一篇，回来看它挂在哪一层、拧的是哪个旋钮。

一、主干：一句话

Agent 就是一个循环：把上下文发给模型 → 模型要么直接回答，要么要求调用工具 → 程序执行工具，把结果塞回上下文 → 再来一轮，直到模型不再调用工具，或者程序叫停。

flowchart LR
    CTX[上下文<br/>系统提示词 + 历史 + 工具结果] --> M[模型]
    M -->|直接回答| END[结束]
    M -->|要调工具| T[执行工具]
    T -->|结果塞回去| CTX
    STOP[程序叫停<br/>步数上限 / 卡住 / 预算用完] -.-> END

后面 16 篇讲的都是这个循环本身，或者它跑起来以后遇到的问题。

二、问题链：循环跑起来之后，一个个冒出来的问题

把循环真跑起来，问题是按顺序冒出来的。按冒出来的先后分成四层，再加一层输出：

flowchart TB
    L1["<b>第一层 让循环转起来</b><br/>01 模型 → 02 调用 → 03 提示词 → 04 工具 → 05 循环"]
    L2["<b>第二层 让循环转得久、转得稳</b><br/>06 上下文 · 07 状态恢复 · 08 RAG"]
    L3["<b>第三层 确认它转得对、不闯祸</b><br/>09 评测 · 10 可观测 · 11 安全"]
    L4["<b>第四层 把循环放进真实系统</b><br/>12 框架与协议 · 13 多 Agent · 14 后端"]
    L5["<b>输出</b><br/>15 系统设计题 · 16 项目怎么讲"]
    L1 --> L2 --> L3 --> L4 --> L5

每一篇对应的问题，一句话说清：

记住左边四层的名字和各层的问题，右边的篇目自然能对上。忘了某篇讲什么时，先想”循环跑到哪一步会出这个问题”。

三、四个旋钮：每篇都在做同样的取舍

问题链是纵向的主线。还有一条横向的线：几乎每个”该怎么选”，都是在下面四个旋钮之间取舍。

各篇里的典型取舍：

面试官问”为什么这么做""为什么不用 X”，回答基本都能落到这四个旋钮上：我在这里更看重哪个，放弃了哪个，有没有数据支撑。

四、一次请求从头走到尾

拿 CrossBuild Agent 的一次真实请求走一遍：“把 libpng 交叉编译到 aarch64”。每一步标出对应篇目。

sequenceDiagram
    participant U as 浏览器
    participant S as 后端 server/app.py
    participant L as 循环 build_agent.py
    participant M as 模型 DeepSeek
    participant T as 工具 tools.py
    U->>S: GET /api/build（14）
    S->>L: 加锁，同一时间只跑一个构建（14）
    loop 最多 40 步（05）
        L->>M: 系统提示词 + 历史 + 工具结果（03、06）
        M-->>L: tool_calls：run_command（02、04）
        L->>T: 白名单 + 路径检查（11）
        T-->>L: 执行结果，过长就截断（06）
        L->>L: 记一条调用记录到 runs.db（10）
        L-->>U: SSE 推一条事件（14）
        Note over L,M: 构建失败时模型调 search_knowledge 查经验库（08）
    end
    L->>L: 卡住或到上限 → 验收：扫产物是不是 aarch64（05）
    L-->>U: 推送最终结果

同一条路径，用文字再过一遍：

1. 浏览器请求 /api/build，后端用 StreamingResponse 推 SSE，并用一把锁保证同时只跑一个构建 —— 14
2. 进入循环，MAX_STEPS 默认 40 —— 05
3. 每轮把系统提示词、历史消息、上一轮工具结果拼成 messages —— 03、06
4. 用 OpenAI 兼容的 SDK 调 DeepSeek，SDK 自带重试 —— 01、02
5. 模型返回 tool_calls，比如要执行 cmake .. —— 04
6. run_command 先查命令在不在白名单，再查参数有没有指到工作目录外 —— 11
7. 执行命令，输出太长就截断并把全文存到文件 —— 06
8. 构建失败时，系统提示词要求先调 search_knowledge 查经验库 —— 08
9. 每次工具调用都写进 runs.db —— 10
10. 同样的调用反复出现就判定卡住，到步数上限也停；停下后不信模型说的”成功了”，自己跑一遍构建、扫产物架构 —— 05
11. LangGraph 版本（graph_agent.py）把同样的循环画成图，每个节点结束存检查点，kill 掉能续跑 —— 07、12
12. 事后评测：另选 5 个 Agent 没见过的项目当留出集，不开知识库、BM25、混合检索三种配置各跑 3 轮，结果都是 15/15，加知识库没有带来可测量的收益 —— 09

这个项目没有用多 Agent（13），被问到时可以直说：单个循环的上下文够用，拆开只会多花钱。

五、自测

合上文章，拿白纸做下面三件事。卡住的地方，就是还没接上的地方，回到对应篇补。

1. 写出主干那句话，画出循环图。

2. 默写四层问题链，每层至少说出两个问题和对应篇号。

3. 从浏览器发请求开始，把第四节那条路径讲一遍，每一步说出属于哪篇、拧的是哪个旋钮。

下一篇：01 大模型基础——循环里最核心的零件：模型本身。