收口:自检、分叉与下一卷
本合集目录
本章目录
单册说明:本文件是「AI Agent 完整教程」卷 0 的第 6 章,可独立阅读,也是卷 0 的出口。 前置:第 3、4、5 章(环境、三条链路、第一个 Agent)。没做完的话,这一章的清单会有很多空格——那也正常,空格会告诉你该回哪一章。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 0 · 学习地图(第 6 / 6 章) |
| 前置章节 | 第 3 章 + 第 4 章 + 第 5 章 |
| 本章产出 | 一份 12 项验收结果 + 一条明确的路径选择 |
| 对应代码 | 无(用第 3–5 章的三个脚本做自测) |
| 配图 | 图 0-11(12 项验收)、图 0-5(四条路径) |
| 读完的判定 | 12 项能全过;能说出下一卷读哪个、为什么不读别的 |
6.1 卷 0 验收清单
逐项打勾。做不到的项,就是你要回头补的节:

| # | 项目 | 对应节 | ☐ |
|---|---|---|---|
| 1 | 能用自己的话说清 Agent 与聊天机器人的区别 | 5.1 | ☐ |
| 2 | 能画出七层模型,并说出每层管什么 | 2.2 | ☐ |
| 3 | 能用七层定位一个具体故障 | 2.5 | ☐ |
| 4 | 实验目录已建好,路径不含中文、不含空格 | 3.7 | ☐ |
| 5 | 三个环境变量已设置,并验证生效 | 3.6 | ☐ |
| 6 | check_env.py 跑完没有 FAIL |
4.7 | ☐ |
| 7 | 链路① 网页能正常返回 | 4.2 | ☐ |
| 8 | 链路② 客户端能读写文件,且会请求确认 | 4.3 | ☐ |
| 9 | 链路③ hello_model.py 能打印回答和 token 用量 |
4.5 | ☐ |
| 10 | 能按错误码(401/404/429)说出该改哪个变量 | 4.6 | ☐ |
| 11 | first_agent.py --mock 能完整跑完,看懂了每步 |
5.6 | ☐ |
| 12 | 自己能说出四个终止条件和第五个隐形出口 | 5.5 / 5.8 | ☐ |
12 项全过:可以放心进下一卷。 11 项以下:不建议往下走。后面的内容全部建立在这 12 项之上,缺哪一项,后面都会以"报错"的形式回来找你。
6.2 三个不看文档的自测任务
合上文档,只靠终端完成:
任务一(定位):把 AI_MODEL 改成一个不存在的名字,跑 hello_model.py,记下错误码,说出是哪一层的问题,改回来。
任务二(安全):让 Agent 尝试把文件写到 ../../hacked.md,看它返回什么,并解释这段拒绝逻辑在哪一行。
任务三(编排):给它一个需要三步才能完成的任务(先列目录 → 再读其中一个文件 → 最后写摘要),观察它是不是真的走了三步,以及在哪一步可能出错。
三个都独立完成,本卷才算真的过。
| 任务 | 期望结果 | 如果你做不出来 |
|---|---|---|
| 一 | 404;第 1 层(模型层);改回 AI_MODEL 即恢复 |
回看 4.6 的诊断表 |
| 二 | 返回"已拒绝:路径越界",output/ 里没有该文件;逻辑在 safe_path() |
回看 5.3 |
| 三 | 三步各一次工具调用,上下文条数逐级增长 | 回看 5.5 和 5.6 |
6.3 六个"假跑通"症状
下面这些情况,看起来像成功了,其实没有:
| 症状 | 真相 |
|---|---|
| "它回答得很好,我觉得它能干这活" | 聊天答得好 ≠ 能动手。让它真的去写一个文件试试 |
| "演示时跑通了" | 演示用的是准备好的数据。换成你的真实数据、真实路径,再看一次 |
| "在我电脑上能用" | 换台机器、换个目录就跑不起来 → 卡在第 6 层(交付层) |
| "它说它做完了" | 必须去 output/ 里看文件到底在不在。模型会报告成功,但没真做 |
| "没报错就是对了" | 没报错只说明流程走完了,不说明结果正确。要抽查产物 |
| "我只花了很少的钱" | 那是一次任务。乘以每天的次数、再乘以 30 天,才是真实成本 |
这六条是给要带人的人准备的:别人报"我跑通了"的时候,你就按这张表逐条问一遍。能过六条,才算真跑通。
6.4 从这里分叉

| 路径 | 适合 | 章节序列 | 终点 |
|---|---|---|---|
| A 零基础非程序员 | 只想把活干完,不写代码 | 卷 1 精简章 → 卷 3 客户端 → 卷 5 场景 | 能搭出自己的流水线 |
| B 会编程 | 想真做出来 | 卷 1 全 → 卷 2 → 卷 4 → 卷 6 | 能开发并部署 |
| C 产品与研究者 | 做选型与可行性判断 | 卷 1 关键章 → 卷 3.1 → 卷 5.14 → 卷 6 | 能判断值不值得做 |
| D 要做培训 | 带人、写教程 | 卷 0 → 卷 7 顺序全读 | 能对外授课 |
唯一不要做的:从卷 3 的框架开始。没手写过循环的人学框架,只会变成配置工——遇到框架没覆盖的场景就卡住。
一个反直觉的顺序:卷 4(从零手写)排在卷 3(框架)之前。先会手写,再看框架,你才看得懂框架替你做了什么、以及它在哪一步偷了懒。
怎么在 30 秒内确定自己走哪条:
| 问题 | 回答 | 路径 |
|---|---|---|
| 你愿意写 Python 吗? | 不愿意 / 只能照着改 | A |
| 愿意,而且想自己设计 | B | |
| 你主要是在评估"要不要上一个 Agent 项目"吗? | 是 | C |
| 你要给别人讲这套东西吗? | 是 | D |
6.5 卷 0 速查卡
命令
python check_env.py # 全身检查
python check_env.py --no-network # 跳过网络
python hello_model.py # 真调用
python hello_model.py --mock # 只看请求体
python first_agent.py "你的任务" --setup --mock --yes # 零成本演示
python first_agent.py "你的任务" # 真跑
环境变量
| 变量 | 作用 | 默认 |
|---|---|---|
AI_API_KEY |
密钥 | 无(必填) |
AI_BASE_URL |
服务地址 | https://api.openai.com/v1 |
AI_MODEL |
模型名 | gpt-4o-mini |
AI_LAB |
实验目录 | ~/ai-agent-lab |
错误码速记
| 码 | 一句话 | 改哪里 |
|---|---|---|
| 401 | 密钥不对 | AI_API_KEY |
| 403 | 没权限 | 账号/模型开通 |
| 404 | 找不到 | AI_BASE_URL 或 AI_MODEL |
| 429 | 限流/没钱 | 额度、频率 |
| 5xx | 服务端问题 | 等、换节点 |
本卷文件清单
AI-Agent教程/卷0/
├── 卷0-00-导读.md 导航、目录、阅读约定
├── 卷0-01-这一卷要解决什么.md 第 1 章
├── 卷0-02-全景地图-七层模型.md 第 2 章
├── 卷0-03-环境准备-机器与终端.md 第 3 章
├── 卷0-04-环境准备-三条链路.md 第 4 章
├── 卷0-05-第一个Agent.md 第 5 章
├── 卷0-06-收口-自检与分叉.md 第 6 章(你正在读的这份)
├── images/ 13 张配图
└── code/
├── check_env.py 环境体检(零依赖)
├── hello_model.py 链路③ 最小示例(零依赖)
├── first_agent.py 第一个 Agent(零依赖)
└── requirements.txt 说明:无需安装任何包
6.6 本卷回顾:你现在拥有什么
读完这一卷,你实际上已经完成了三件很多人卡了半年都没完成的事:
- 你有了地图——遇到问题,你知道该查七层里的哪一层,而不是到处试工具;
- 你有了环境——三条链路全通,后面任何教程的"第一步"你都能直接跳过;
- 你有了一个真的 Agent——它不完美,但它有工具、有循环、有边界、有出口。后面所有内容,都是在这个骨架上长肉。
下一卷(卷 1 基础理论)会回答一个问题:为什么这个骨架会这样反应? ——模型的 token 机制、上下文窗口、提示词为什么有效、RAG 为什么能治幻觉。带着你现在这个能跑的 Agent 去读,那些概念会立刻有落点,而不是悬在空中。
6.7 卷 0 到此为止
卷 0 完。本卷自成单元,读到这里即可独立使用;后续各卷按 6.4 的路径选择进入。