awesome-agentic-ai-zh 学习地图:从 LLM 基础到多智能体系统的 10 站式技术路线
awesome-agentic-ai-zh 学习地图:从 LLM 基础到多智能体系统的 10 站式技术路线
导读
awesome-agentic-ai-zh 是一份以“看得懂、跑得起来”为目标的 Agentic AI 学习地图,用中英繁三种语言组织了一条从“什么是 LLM、Token 如何计数”一路延伸到“构建自己的多智能体系统”的完整路径。本文以该仓库首页(index.en.md)为骨架,结合 stages/、tracks/、examples/、resources/ 等目录的源码级细节,为你拆解 10 个学习停靠站、Track A/B 两条主线、角色化分支路线以及配套的可运行练习与自动化质量闸门,帮助你直接定位自己的起点并按步执行。
什么是 AI Agent:学习地图的起点定义
首页给出了整个学习地图最核心的一个定义:AI Agent 是一种能够自行决定下一步做什么、并朝着人的目标采取行动的人工智能系统。它不是一个“一次性问答”的聊天机器人,也不是一段固定脚本——在拿到一个目标后,Agent 会读取当前状况、在必要时调用工具,然后根据结果继续执行、纠正路线、停止,或者把控制权交回给人类。它可以在人的授权范围内自动工作,但必须遵守清晰的规则和权限边界。
在 README.en.md 中,这个定义被进一步落实为三个递进层次:
- 打基础:搞清 LLM(大语言模型)、prompt、API、token 这些最基本的概念;
- 动手构建:让模型调用工具、运行 agent loop、读取文档、记住信息;
- 让它可靠:加入权限控制、Eval 评测、人工审批、可观测性和故障恢复。
这也是整个仓库的设计逻辑:每一站先讲清楚一个概念,再给出可运行的练习,最后用资源目录补充深度。而仓库自身定位是“学习路线 + 精选资源 + 小型可运行示例”,遇到需要整章深度的内容,则指向官方文档或社区开源项目,而不是把百科内容重新抄一遍。
10 个学习停靠站:一张地图的完整结构
首页明确写道,这张地图包含 8 个主题 Stage + Stage 0 就绪检查 + Stage 7.5 进阶阅读站,共 10 个学习停靠站(learning stops)。所有学习者都先经过共用的 Stage 0–2 基础段,然后分头进入两条主线;如果你已经掌握 Python、Git 和 API,可以跳过 Stage 0。
共用基础段:Stage 0–2
| 停靠站 | 解决什么问题 | 完成后你能做什么 |
|---|---|---|
| Stage 0 · Foundations | 机器和工具是否就绪? | 用 Python 调用公开 API、读取 JSON、用 Git 保存版本 |
| Stage 1 · LLM 基础 | LLM、token、上下文窗口是什么,模型之间如何区别? | 完成第一次 API 调用,并能选择云上或本地模型 |
| Stage 2 · Prompt 设计 | 如何把目标、数据、规则、输出格式说清楚? | 对比 Zero-Shot、One-Shot、Few-Shot 与 CoT(思维链)的边界 |
Stage 0 的实操非常有代表性:它要求你创建 github_profile.py,用 Python 标准库 urllib 调用 GitHub 公开 API 获取用户资料,打印粉丝数并写入 result.txt,最后用 git init/commit 把结果保存下来——整个过程不需要账号、API token 或任何付费服务。这验证了“命令行 + Python + JSON + Git”四项基本功是否齐备。
Track A——CLI 高手线
Track A 的目标是“用现有 CLI Agent 把活儿干完”,适合不想自己写 Agent 程序、但想立刻用工具提效的人。首页给出的意图顺序是 A1 → A2 → Stage 5 → A3 → Stage 8:
| 顺序 | 停靠站 | 解决什么问题 | 完成后你能做什么 |
|---|---|---|---|
| A1 · 挑选一个 CLI Agent | OpenRouter、OpenCode、Pi、Ollama 都是什么? | 选定工具并完成一个小的可逆改动 | |
| A2 · 建立可重复的工作流程 | 如何把规则和步骤沉淀下来供下次复用? | 编写项目指令、Skill、可复用工作流 | |
| 5 · Claude Code 生态 | MCP、Skills、Plugins、Hooks、Subagents 有何区别? | 精读 5.1–5.4;按需选学 5.5–5.8 | |
| A3 · 接入真实工作 | 如何安全接入工具、CI 和团队流程? | 以最小权限、人工检查、留痕方式集成 | |
| 8 · Agent 接口 | Agent 如何驱动浏览器、屏幕、沙箱? | 判断任务该用 CLI、浏览器、Computer Use 还是 API |
A1 的第一课就示范了“先读后改”的安全闭环:在一个不含秘密的临时 demo 仓库中,先让工具只读文件、解释用途、找到测试命令并给出计划,等人工确认后才做一处可用 git diff 检查、可回退的小改动。A1 还给出了按“你已有什么”来选入口的表格——有 Anthropic 账号看 Claude Code,有 OpenAI 看 Codex CLI,有 Google 账号看 Gemini CLI,想切换供应商或用本地模型则看 OpenCode、goose、Aider、Pi,Router/本地运行时(OpenRouter、Ollama)必须与 Coding Agent 搭配使用。
Track B——Agent 建构者线
Track B 的目标是“从零写出自己的 Agent、工具循环、工作流和服务”,起点是 Stage 3。首页给出的意图顺序是 Stage 3 → 4 → 5 → 6 → 7 → 7.5 → 8:
| 顺序 | 停靠站 | 解决什么问题 | 完成后你能做什么 |
|---|---|---|---|
| 3 · Tool Use 与第一个 Agent Loop | 模型如何安全调用工具并继续推进? | 写出带轮次上限与参数校验的 Agent Loop | |
| 4 · Workflow Graphs 与 Agent 框架 | 如何把多个步骤画成一张图? | 在 workflow、agent、graph、framework 之间做选择 | |
| 5 · Claude Code 生态 | MCP、Skills、Plugins、Hooks、Subagents 如何协同? | 组合工具、规则与可复用能力 | |
| 6 · Memory 与 RAG | Agent 如何搜索、保存并取回重要信息? | 搭建最小 RAG、长期记忆与上下文检索流程 | |
| 7 · Agent 上线工程 | Agent 在生产环境中如何保持稳定? | 加入 Eval、可观测性、预算、HITL 审批与恢复 | |
| 7.5 · 进阶 Agentic 概念图 | 哪些进阶模式值得了解? | 从 PAR loop、agent-as-judge 等 12 个概念中按需挑选 | |
| 8 · Agent 接口 | Agent 如何突破 API 边界工作? | 选择 Computer Use、Browser Use 或代码沙箱 |
README 特别强调了一条学习顺序主线:Stage 2 Prompt → Stage 3 Agent Loop → Stage 4 Workflow Graph/框架 → Stage 5 工具与规则 → Stage 6 Context Engineering → Stage 7 上线工程。Prompt、Context、Harness、Loop、Graph 是协同工作的五个要素,而不是彼此替代的“五个代际产品”。
深入 Stage 3:第一个 Agent Loop 的技术细节
作为 Track B 的起点,Stage 3 是理解整个地图技术深度的最佳样本。它用一个核心流程贯穿始终:schema → call → execute → result → answer,也就是让模型填一张“工具工单”,由你的程序校验、执行并把结果送回模型。
先分清五个核心概念
- Tool Use:模型需要外部数据或动作时先发出工具请求,但模型本身不执行你的客户端工具——就像孩子请大人帮忙开高处的箱子,模型说出想做什么,由程序真正行动;
- Function Calling:模型按约定格式返回函数名与参数,各家 provider 的消息格式并不完全一致;
- Tool Schema:用 JSON Schema 描述工具的名字、用途、字段与数据类型,但 schema 只约束形状,程序仍必须校验取值、权限与业务规则;
- Tool Call:模型填好的“工单”,包含工具名、call ID 和参数,它是请求而不是执行结果,程序应先在 allowlist 中查找允许的函数;
- Tool Result:程序执行完后的返回数据,通过 call ID 与原始请求配对;外部结果不可信,绝不能当作最高优先级指令;
- Agent Loop:程序反复执行“问模型 → 执行工具 → 返回结果”直到得到答案或达到上限,完整回路是
model → tool call → execute → tool result → model; - ReAct:交替进行决策、行动、观察,本课的 loop 是 ReAct 启发的、可观测的,并不要求模型暴露私密思维链;
- Structured Output:模型返回固定形状的数据(如符合 schema 的 JSON),与 Function Calling 的区别是:前者要数据,后者要程序采取动作。
写第一个 Agent 前的五条护栏
Stage 3 明确列出了动手前必须遵守的安全规则:
- 只执行 allowlist 中的工具,绝不用模型生成的名称任意调用函数;
- 把工具参数当作不可信输入,先校验类型、取值范围与权限;
- 只给工具完成该任务所需的最小权限;
- 删除、支付、发邮件等高危动作必须先获得人工确认;
- 设置最大轮数、超时与成本上限,绝不让 Agent 无限循环。
一个可复制的本地示例(Path A,$0 API 成本)
Stage 3 的 Exercise 1 给出了完整可复制的 Ollama 版本:用 OpenAI Python SDK 连接 Ollama 的兼容 Chat Completions 端点(base_url="http://localhost:11434/v1"),数据不会发送到 OpenAI 云端。先执行 ollama pull qwen2.5:3b,然后定义 get_weather 工具的 JSON Schema(含 city、unit 字段,additionalProperties: false),让模型发起 Tool Call;程序读取 assistant.tool_calls 后先做白名单与参数双重校验,再把 role: "tool" 的结果按 tool_call_id 送回,最后让模型基于 Tool Result 作答。代码末尾还有两个断言(assert assistant.tool_calls[0].function.name == "get_weather" 与 assert any(message["role"] == "tool" ...)),保证回路确实走通。文档特别提醒:Ollama 与 OpenAI 的 strict-mode 保证并不一致,程序必须自己继续做校验;如果模型没调用工具,应在问题、模型、schema 不变的情况下连跑三次记录成功率,不能一次失败就下结论。
对应的可运行目录是 examples/stage-3/01-function-calling/README.en.md,同目录下有 starter.py、test.py、starter_anthropic.py、test_anthropic.py 分别覆盖本地与云上两条路径。
六个 Stage 的主题纵深
Stage 1:Token、上下文窗口与温度
Stage 1 从一条主线展开:Data → Pre-training → Base Model → Post-training → Instruct Model → Inference → Agent system。它区分了 SFT、DPO、RLHF、RL、GRPO、LoRA、PEFT 等训练/微调方法,并强调 Agent 不是训练流程中的下一个 checkpoint,而是把模型与 Prompt、RAG、Memory、Tools、Harness 连接起来的系统——这些部分通常工作在模型外部、不改变权重。它还会教你从响应的 usage 字段读取输入/输出 token 数来估算成本。
Stage 4:Workflow Graph 与框架选择
Stage 4 先讲清楚 Workflow Graph 的概念(把多个步骤、分支与人工核准画成一张图),再用 LangGraph、AutoGen、Agents SDK 等框架把它落地,回答“workflow、agent、graph、framework 该选哪个”的问题。
Stage 5:Claude Code 生态枢纽
Stage 5 是“工具与规则”的枢纽站:Track A 使用它、Track B 组合它。它系统区分 MCP(Model Context Protocol)、Skills、Plugins、Hooks、Subagents 各自的作用与协同方式。仓库还单独维护了 resources/mcp-skills-catalog.en.md 目录和 examples/stage-5/tool-calling-tutor/ 练习(含 evals/evals.json 与 references/ 下的调试流程图、schema 演进、SDK 差异对照)。
Stage 6:Memory 与 RAG 双车道
Stage 6 教授两条并行的 RAG 管道(检索增强生成),从 Embeddings、向量数据库、分块比较一路到完整 RAG 管道与长期记忆,目标是让 Agent“能找到证据、并保存真正需要保留的状态”。对应的练习目录覆盖 examples/stage-6/ 下的 01-embeddings 到 05-long-term-memory 五个子项目。
Stage 7:可测、可看、可停、可恢复
Stage 7 是“Agent 上线工程”的核心站,把 Stage 3 的 Agent Loop、Stage 4 的 Workflow Graph 与 Harness 整合起来,加入 Eval 评测、可观测性、预算上限、Human-in-the-loop 人工审批与恢复机制,让同样的工作图能在生产环境中稳定运行。Stage 7 练习目录(examples/stage-7/)包含多智能体辩论、Eval 核心、可观测性、SDK 进阶、部署(含 Dockerfile)与安全执行(safe-execution)六个子项目。
Stage 7.5 与 Stage 8:进阶阅读与接口选择
Stage 7.5 是一站刻意设计的“阅读站”:一次只挑一个进阶概念(如 PAR loop、agent-as-judge 等共 12 个),先判断你的系统是否需要它,而不是全盘照收。Stage 8 则是“接口枢纽”:Track A 负责委托、Track B 负责把接口构建进系统,需要判断任务到底该走 CLI、浏览器、Computer Use 还是 API,并配套可复制的安全练习。
角色化分支:按“你是谁”继续走
除了主线,仓库还为五类读者提供了角色化路线,首页用决策树图(branch decision tree)说明“按需选择,不必全走”:
| 分支 | 适合谁 | 主要处理内容 |
|---|---|---|
| 🔬 Researcher | 研究生、博士后、PI | 文献证据、可复现管道、多智能体评审 |
| 💻 Developer | 软件工程师 | CLI 委托、代码评审、测试与回滚 |
| 🎓 Teacher | 教师、讲师 | 备课、反馈、隐私、教学提示词 |
| 📊 Knowledge worker | 顾问、PM、分析师 | 邮件、会议、报告工作流 |
| 👥 Everyday user | 不写代码的 AI 用户 | 写作、学习、隐私与安全使用 |
每个分支的设计与定位统一记录在 branches/DESIGN.md,并有一整套 test_role_paths.py、test_role_map.py 等脚本保证分支与主线的路由一致。
如何学习不卡壳:starter.py 六步循环
examples/README.en.md 与 docs/HOW_TO_USE.md 共同定义了本仓库独特的学习方法:先跑起来,再改一件小事,最后用测试看差别。
每个练习目录里的 starter.py 是一份可以直接执行的最小系统,而不是空白作业纸。首次打开一个练习时只需:
cd examples/stage-3/03-react-from-scratch
python test.py
python starter.py
然后遵循六步循环:看 README 的“你会做出什么”与成功条件 → 复制第一组命令让原版测试通过 → 只改一个输入、规则、工具或停止条件 → 先猜结果 → 再跑测试看是否符合预期 → 用自己的话解释这一行为什么改变系统。推荐的改动都是最小且可逆的,例如把 max_iter 调小观察 Agent Loop 如何停止、暂时拿掉一个 schema 字段观察校验报错、换一个测试输入为未知值。
从地图到实践:克隆与配套资源入口
如果你想把地图克隆到本地,可以用:
git clone https://github.com/WenyuChiou/awesome-agentic-ai-zh.git
cd awesome-agentic-ai-zh
然后打开 stages/00-foundations.en.md 或直接跳到上面列出的第一个停靠站。以下是值得收藏的学习入口(星号为学习优先级,不是排名):
- Zero-to-setup guide:首次安装与首次运行(先帮读者在 Web、Desktop、IDE、CLI、API 之间做选择);
- How to use this material:第一次动手练习前必读;
- Core glossary:遇到 token、RAG、MCP 等生词时查阅;
- Runnable examples:离线测试与小案例;
- Hands-on cookbook:Skill、MCP、Office、Zotero、本地 LLM 的配方;
- Resource toolbox 与 RESOURCES.en.md:完整资源清单;
- CLI agent selection guide:Track A 起步或 CLI 工具对比;
- Progress tracker 与 Capstone project:Track A 走完 A3、Track B 走完 Stage 7 后的结业专题。
时间规划上(仅作为规划参考,不是截止日期):Track A 约 8–10 周,使用现有 CLI Agent 完成工作;Track B 主线约 16–22 周,按每周 5–8 小时通常是 5–7 个月。每个 Stage 的练习都给出分段的成本估算方式——例如 Claude Haiku 4.5 在 2026-08-27 检查时为输入/输出每百万 token $1 / $5,单次请求按 2,000 输入 + 1,000 输出 token 估算约 $0.007,而工具循环会发送多次请求,建议每次练习先预留 $0.05,五个完整章节实验设置 $1 的 provider 花费上限;Path A 的本地路径则是 $0 API 成本。
仓库的工程化维护:自动化检查与站点构建
这份地图本身也是工程化维护的产物。站点配置 mkdocs.yml 采用 Material 主题,内容直接从仓库根目录(stages/、tracks/、branches/、resources/ 与根级 *.md)经构建脚本暂存到 _build/docs/ 后再由 MkDocs 构建,并通过 i18n 插件输出繁中、简中、英文三种语言。nav 中可以看到首页(index.md)、项目说明、使用方法、进度、结业专题、路线图、共用基础、Track A/B、读者分流、实作、资源、贡献等完整的导航结构。
scripts/ 下有一套自动化质量闸门,例如:
check-links.py、check-locale-links.py、check-anchors.py:校验链接、语言切换器与锚点 slug 的三语一致性(锚点规则由test_anchor_slug_parity.py固定);check-hans-chars.py:检查简体中文用字;check-repository-freshness.py与check-2026-freshness.py:每周对仓库的存档状态、许可证、最后更新、重定向做新鲜度检查,并写入repository-freshness-snapshot.json;check-reader-ux.py:校验渐进式披露等阅读体验规则;check-mirror-parity.py/check-mirror-sync.py:检查镜像站点与主仓库的对等性;- 大量
test_*.py(如test_stage03_examples.py、test_stage06_rag_pipeline.py、test_stage07_content.py、test_role_paths.py、test_site_route_coherence.py)为各 Stage 的内容结构、练习可运行性和路由一致性把关。
ROADMAP.en.md 则用状态标记(🟢 active / 🟡 known gap / 🔵 idea / ✅ completed)透明地说明“现在能用什么、还缺什么”:主页地图、文案与测试共用同一条路线,任何顺序变更都必须三处同步更新。
结语
awesome-agentic-ai-zh 的价值在于它把“Agentic AI 该学什么”从一份链接清单变成了有顺序、有定义、有练习、有验收标准的可执行路线:先用 Stage 0–2 打平基础,再从 Track A(用 CLI Agent 干活)或 Track B(自己构建 Agent 系统)二选一深入,最后通过角色分支和 Capstone 结业专题把所学落到自己的真实场景。对照首页这张地图,你只需要回答一个问题:我现在的起点在哪里——然后走到下一站去。