跳到正文
AI Agent 教程 · 卷 0 · 学习地图

收口:自检、分叉与下一卷

本合集目录
本章目录

单册说明:本文件是「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 验收清单

逐项打勾。做不到的项,就是你要回头补的节:

12 项验收:能不能用,不看学没学完

# 项目 对应节 ☐
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 从这里分叉

读完卷 0,从这里分叉

路径 适合 章节序列 终点
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 本卷回顾:你现在拥有什么

读完这一卷,你实际上已经完成了三件很多人卡了半年都没完成的事:

  1. 你有了地图——遇到问题,你知道该查七层里的哪一层,而不是到处试工具;
  2. 你有了环境——三条链路全通,后面任何教程的"第一步"你都能直接跳过;
  3. 你有了一个真的 Agent——它不完美,但它有工具、有循环、有边界、有出口。后面所有内容,都是在这个骨架上长肉。

下一卷(卷 1 基础理论)会回答一个问题:为什么这个骨架会这样反应? ——模型的 token 机制、上下文窗口、提示词为什么有效、RAG 为什么能治幻觉。带着你现在这个能跑的 Agent 去读,那些概念会立刻有落点,而不是悬在空中。


6.7 卷 0 到此为止


卷 0 完。本卷自成单元,读到这里即可独立使用;后续各卷按 6.4 的路径选择进入。