从零到一：Hello-Agents 综合案例完整开发指南
本系列文档是为 零 Python 基础 的学习者编写的实战教程。目标是带你从"完全不懂"到"独立跑通并理解" Datawhale Hello-Agents 教程第四部分（综合案例进阶）的全部三个项目：
- 智能旅行助手（第十三章）—— 多智能体协作 + MCP 工具 + Web 应用
- 自动化深度研究智能体（第十四章）—— TODO 驱动研究 + 流式输出
- 赛博小镇（第十五章）—— 游戏引擎 + 记忆系统 + 好感度系统
原教程内容采用 CC BY-NC-SA 4.0 协议开源，本系列文档基于其项目架构重新编写讲解，配套官方代码仓库：
datawhalechina/hello-agents的code/chapter13~15目录。学习时请以官方仓库代码为准，本文档负责"讲懂它"。
配套基础篇:本系列聚焦原书第四、五部分的综合案例与工程化。原书第 1~12 章(智能体原理、LLM 基础、三大范式、框架、记忆与 RAG、上下文工程、通信协议、Agentic-RL、评估)的逐章精讲与手敲教程见 docs/1 系列。如果你是纯零基础,推荐先读 docs/1 的第 1~4 章打地基。
一、这套文档适合谁
- 没有 Python 基础，但想完整做出一个 AI Agent 项目的人
- 看官方教程觉得"步子太大跟不上"的人
- 想系统了解 Agent 开发全链路（环境 → 框架 → 后端 → 前端 → 部署）的人
二、文档目录与学习路线
请严格按顺序学习，每一篇都是下一篇的地基：
| 序号 | 文档 | 内容 | 预计耗时 |
|---|---|---|---|
| 01 | Python 基础速成 | 变量、函数、类、异步、类型注解——只讲本项目用到的 | 2~3 天 |
| 02 | 环境搭建：uv 与开发工具链 | uv、Node.js、Git、API Key 申请、编辑器 | 半天 |
| 03 | Agent 原理与 HelloAgents 框架精讲 | LLM、Agent、工具调用、MCP、记忆系统、框架裁剪 | 2 天 |
| 04 | Web 开发基础 | FastAPI、Pydantic、SSE、CORS、Vue 前端是怎么回事 | 1~2 天 |
| 05 | 项目一：智能旅行助手从 0 到 1 | 四 Agent 协作 + 高德地图 MCP + Vue 前端 | 3~5 天 |
| 06 | 项目二：深度研究智能体从 0 到 1 | TODO 规划 → 搜索 → 总结 → 报告，SSE 流式推送 | 3~4 天 |
| 07 | 项目三：赛博小镇从 0 到 1 | Godot 游戏 + NPC 记忆 + 好感度系统 | 3~5 天 |
| 08 | Docker 与部署实战 | Dockerfile、docker compose、Nginx、上云 | 1~2 天 |
| 09 | 常见问题与排错手册 | 报错速查表、调试方法论 | 随用随查 |
| 10 | 进阶知识补全与面试指南 | QPS与高并发、RAG、ReAct、Function Calling、安全、评估、高频面试题 | 2~3 天 |
| 11 | 实战手敲一:从零手敲一个完整Agent | 不用框架手写:工具调用循环、双层记忆、SSE流式、聊天界面 | 1~2 天 |
| 12 | 实战手敲二:多智能体旅行规划系统 | 多Agent并行、结构化输出、Pydantic校验+自修复循环 | 2~3 天 |
| 13 | 实战手敲三:深度研究智能体 | Plan-and-Execute、联网搜索与降级、SSE进度推送 | 2~3 天 |
| 14 | 实战手敲四:记忆小镇(多NPC) | NPC人设、LLM情感裁判、记忆持久化、NPC间八卦传播 | 1~2 天 |
| 15 | 模型微调与私有化部署 | LoRA/QLoRA、LLaMA-Factory、Ollama、vLLM、显存估算 | 2~3 天 |
| 16 | Agent专家踩坑手册与成长路线 | 16个真实踩坑与解法、专家成长路线图 | 上线/面试前必读 |
| 17 | 面试冲刺:盲区补全与高频追问实战 | LLM底层原理、RAG进阶追问、Agent测试、会话扩容、前沿动态、系统设计题、连环追问模拟 | 面试前3天精读 |
| 18 | 终极手敲:构建你自己的Agent框架 | 原书第七章从0到1:多提供商LLM、五种范式Agent、工具注册表、打包成可pip安装的框架 | 3~5 天 |
| 19 | 实战手敲五:企业级文档问答系统 | PDF版式与表格解析、BM25+向量混合检索+RRF+精排、评测集与CI质量闸门、鉴权限流缓存追踪、Docker交付 | 5~7 天 |
| 20 | 实战手敲六:用 LangGraph 重写研究智能体 | 状态机建模(节点/边/reducer)、Postgres checkpointer与断点续跑、interrupt()人在环中、时间旅行与分叉重跑、给状态机写测试 |
3~4 天 |
总时长约 6~8 周（每天 2~4 小时）。不要跳过 01~04：三个项目 80% 的"看不懂"，根源都在基础篇。
两条腿走路:跑通官方项目 + 手敲自研项目
- 05~07 篇(跑通路线):官方三个项目有几十个文件(Vue 前端、Godot 游戏),正确练法是"克隆 → 跑通 → 精读 → 改造",不是逐行抄写
- 11~14 篇(手敲路线):每种项目原型给你一个每行代码都完整给出的同架构自研版(5~8 个文件),从空目录敲到整体运行,四个项目分别对应:工具 Agent、多 Agent 结构化输出(项目一的魂)、Plan-and-Execute(项目二的魂)、多 NPC 记忆(项目三的魂)
- 顺序建议:05~07 每跑通一个官方项目,就手敲对应的自研版(05→12、06→13、07→14),"跑通别人的 + 写出自己的"缺一不可
- 18 篇是手敲路线的终点:前面手敲的都是"应用",18 篇造的是"框架本身"(对应原书第七章《构建你的智能体框架》),五种范式 Agent + 可 pip 安装,建议完成 11~14 后再挑战
- 19 篇是工程化路线的起点:11~14、18 篇练的是"功能能跑",19 篇练的是"能上线"——真实 PDF 语料、可量化的检索指标、CI 质量闸门、鉴权限流缓存追踪、容器交付。这一篇的每个指标和每段输出都是实测的,面试里最能讲的项目通常是这一类
- 19 与 20 是刻意配对的一组:19 篇做的是数据平面(材料怎么找对、怎么不胡说),20 篇做的是控制平面(流程怎么停得住、崩了怎么续、人怎么插手)。20 篇把 13 篇那个能跑的研究智能体用 LangGraph 重写,补上断点续跑、人在环中、时间旅行,并且给状态机配了 27 个测控制流而不是测模型输出的测试。两篇的工程纪律完全一致(fail closed、限流、
--workers 1、只 mock LLM、Docker + CI),区别只在业务问题
三、三个项目分别练什么
项目一 旅行助手 项目二 深度研究 项目三 赛博小镇
───────────── ───────────── ─────────────
多Agent顺序协作 TODO驱动的规划执行 Agent + 游戏引擎
MCP协议接外部API SSE流式实时推送 记忆系统(短期+长期)
Pydantic数据建模 搜索引擎工具集成 好感度状态机
Vue前端表单/地图 Markdown报告生成 Godot/GDScript入门
三个项目共用同一套底座：HelloAgents 框架（SimpleAgent）+ FastAPI 后端 + 一个独立前端。学完项目一之后，项目二、三的后端部分你会发现"套路是一样的"。
四、学习方法建议
- 先跑通，再看懂，最后改造。 每个项目文档都分为"里程碑"，每个里程碑结束都有一个可运行的checkpoint。跑不起来就不要往下走。
- 手敲代码。 复制粘贴学不会编程。基础篇的代码必须手敲；项目篇可以对照官方仓库，但关键文件建议自己重写一遍。
- 善用报错信息。 排错手册（09 篇）教你读懂 Traceback。90% 的报错，答案就写在最后一行。
- 控制成本。 全程使用 DeepSeek / 智谱 / ModelScope 等国内低价或免费 API，完整学完三个项目的 LLM 花费通常在 20 元人民币以内。
五、最终你将得到什么
跑通的(官方项目):
- 一个能根据"城市 + 天数 + 偏好 + 预算"自动生成完整旅行计划（含地图、天气、酒店、预算、导出 PDF）的 Web 应用
- 一个输入任意研究主题、自动拆解子任务、搜索全网并生成带引用报告的研究助手
- 一个可以用 WASD 走动、按 E 与"有记忆、有性格、有好感度"的 AI NPC 对话的像素小镇游戏
亲手敲出来的(每一行都是你写的,11~14、18~20 篇):
- 一个带工具调用循环、双层记忆、SSE 流式和聊天界面的完整 Agent 服务
- 一个多智能体并行协作、结构化输出带自修复的旅行规划系统
- 一个 Plan-and-Execute 架构、能联网搜索并生成报告的研究智能体
- 一个多 NPC、有好感度和持久化记忆、信息能在 NPC 间传播的记忆小镇
- 一个自己的 Agent 框架:多提供商 LLM、五种范式、可 pip 安装(18 篇)
- 一个能上线的企业文档问答系统:混合检索 + 精排、带引用与拒答、检索指标接 CI 闸门、鉴权限流缓存追踪、Docker 交付(19 篇)
- 一个有状态可恢复的研究智能体工作流:LangGraph 状态机、Postgres checkpointer 断点续跑、人在环中审批、时间旅行分叉重跑、27 个控制流测试(20 篇)
工程与专家能力:
- 用 uv 管理 Python 项目、用 Docker 打包部署任意服务
- 用 LoRA/QLoRA 微调开源模型,用 Ollama/vLLM 私有化部署并接入自己的 Agent（15 篇）
- 16 类真实线上踩坑的识别与解法、从初级到专家的成长路线图（16 篇）
准备好了就从 01-Python基础速成 开始吧。