awesome-agentic-ai-zh:从 LLM 基础到多智能体系统的 10 站 AI Agent 学习地图
awesome-agentic-ai-zh:从 LLM 基础到多智能体系统的 10 站 AI Agent 学习地图
awesome-agentic-ai-zh 是一张面向中文读者的三语(繁体中文 / 简体中文 / English)Agentic AI 学习地图,用 10 个学习站把“LLM 是什么、token 怎么算”一路串到“自己打造多 agent 系统”。本文以 项目首页 为核心骨架,结合 主 README、路线图、站点配置 与 可执行范例,完整拆解这张地图的路线设计、每个学习站的入口与出口、角色分流、动手练习体系,以及支撑整站三语发布与链接校验的工程机制。
先懂一件事:AI Agent 是什么?
项目首页给出了一个直白的定义:
AI Agent(AI 智能体)是能为了人的目标,自己判断下一步并采取行动的 AI 系统。人给它目标后,它会读取当前情况、需要时使用工具,再根据结果继续、修正、停止,或把控制权交还给人;它可以自动替人完成工作,但只能在规则和权限内行动。
这个定义有两点值得注意,也是整张地图反复强调的边界:
- 不是聊天机器人:只回答一次的聊天机器人,或每一步都预先固定好的脚本,不一定是 Agent。Agent 的关键在于“自己判断下一步”与“采取行动”之间的闭环。
- 不是无限自由:Agent 只能在人给的规则和权限内行动。这一边界在 Stage 3 的“写第一个 Agent 前的五条底线”中被落实为 allowlist 工具派发、参数验证、最小权限、人工确认与
MAX_STEPS上限,并在 Stage 7 升级为 Eval、观测、预算、Human-in-the-loop 与恢复。
首页据此设计了三条递进的学习目标(见 README.zh-Hans.md):
- 先懂基础:LLM、Prompt、API 与 Token 是什么;
- 再做出东西:让模型调用工具、跑 Agent Loop、读文件与记住事情;
- 最后做得可靠:加入权限、Eval、人工批准、观测与失败恢复。
选一条学习路线:Track A 与 Track B
首页提供了两条平行路线,对应两类不同目标的读者(完整选择表见 README.zh-Hans.md):
| 你现在想做什么? | 建议路线 | 路线入口 |
|---|---|---|
| 用 Claude Code、Codex、OpenCode 等 CLI Agent 完成工作 | Track A — CLI Power User | A1:选一个 CLI Agent |
| 自己写 Agent、工具循环、Workflow 与服务 | Track B — Agent Builder | Stage 3:第一个 Agent Loop |
| 只想在日常生活安全使用 AI,暂时不写程序 | 日常用户路线 | 日常用户指南 |
- Track A — CLI 高手:把 Claude Code 这类 CLI agent 用到极致,覆盖工作流与 production 化。正式顺序是
A1 → A2 → Stage 5 → A3 → Stage 8(见 README.zh-Hans.md)。 - Track B — Agent 建构者:从工具调用一路写到多 agent 协作、写自己的 MCP server。正式顺序是
Stage 3 → Stage 4 → Stage 5 → Stage 6 → Stage 7 → Stage 7.5 → Stage 8。
两条路线共享 Stage 0–2 的共用基础;已经会 Python、Git 与 API 的人可以直接跳过 Stage 0。Stage 5(Claude Code 生态)和 Stage 8(Agent 界面)是两条路的交汇 Hub:Track A 侧重“怎么用/怎么委派”,Track B 侧重“怎么组合/怎么接进自己的 Agent”。
从 Stage 0 到 Stage 8:10 个学习站全景
首页把整张地图组织为 8 个主题 Stage + Stage 0 准备关 + Stage 7.5 进阶阅读站 = 10 个学习站。每一站解决一个明确问题,并给出“完成后你能做什么”的出口能力(出口能力表详见 README.zh-Hans.md)。
共用基础:Stage 0–2
| Stage | 这一步解决什么? | 完成后你能做什么? |
|---|---|---|
| 0 · 基础准备 | 电脑与基本工具准备好了吗? | 用 Python 调用公开 API、读 JSON,并用 Git 保存成果 |
| 1 · LLM 基础 | LLM、Token、Context 与模型差在哪里? | 调用一个 LLM,并依需求选云端或本机模型 |
| 2 · Prompt 设计 | 怎么把目标、数据、规则与输出说清楚? | 用固定案例比较 Zero-Shot、One-Shot、Few-Shot 与 CoT 的边界 |
Stage 0 是一道“自检关”:四项能力(Python 调 API 读 JSON、Git 的 clone/branch/commit/push、命令行操作、看懂 YAML/JSON)都会就可以直接跳到 Stage 1;不确定就完成主练习“GitHub 数据小工具”(stages/00-foundations.zh-Hans.md)——不需要账号、API token 或付费服务。
Stage 1 建立三个核心词:Token(模型读写与 API 计价的计算单位)、Context Window(一次请求可用的 token 空间,需同时查模型最大输出上限)、Temperature(控制采样变化程度,低值利于分类、高值利于构思但更不稳定)。同时给出“模型如何走到 Agent”的主线:
数据 → Pre-training → Base Model → Post-training → Instruct Model → Inference → Agent 系统
Agent 不是训练流程中的下一个模型检查点,而是把模型、Prompt、RAG、Memory、Tools 和 Harness 连接起来的系统,这些部分通常在模型外部工作、不改变模型权重(stages/01-llm-basics.zh-Hans.md)。
Track A:使用 CLI Agent 把工作做完
| 顺序 | 这一步解决什么? | 完成后你能做什么? |
|---|---|---|
| A1 · 选一个 CLI Agent | OpenRouter、OpenCode、Pi、Ollama 分别是什么? | 选对工具并完成第一个小任务 |
| A2 · 建立可重复流程 | 怎么把规则与步骤留给下一次使用? | 写 Project Instructions、Skill 与可重用工作流程 |
| 5 · Claude Code 生态 | MCP、Skills、Plugins、Hooks 与 Subagents 怎么分? | 先读核心 5.1–5.4;5.5–5.8 依工作需要选读 |
| A3 · 接进真实工作 | 怎么安全连接外部工具、CI 与团队流程? | 用最小权限、人工检查与记录完成集成 |
| 8 · Agent 操作界面 | Agent 怎么操作浏览器、画面与 Sandbox? | 判断任务该用 CLI、Browser、Computer Use 还是 API |
Track B:从零打造 Agent
| 顺序 | 这一步解决什么? | 完成后你能做什么? |
|---|---|---|
| 3 · 工具使用与第一个 Agent Loop | 模型怎么安全调用工具并重复下一步? | 做出有最大轮数、会验证参数的 Agent Loop |
| 4 · Workflow Graph 与 Agent 框架 | 怎么把多个步骤画成工作地图? | 选择 Workflow、Agent、Graph 与 Framework |
| 5 · Claude Code 生态 | MCP、Skills、Plugins、Hooks 与 Subagents 怎么合作? | 组合工具、规则与可重用能力 |
| 6 · Memory · RAG | Agent 怎么查文件、保存与取回重要信息? | 建立最小 RAG、long-term memory 与 contextual retrieval 流程 |
| 7 · Agent 上线工程 | Agent 怎么在真实环境稳定运作? | 加入 Eval、观测、预算、Human-in-the-loop 与恢复 |
| 7.5 · 进阶 Agentic 概念地图 | 还有哪些进阶 Pattern 值得认得? | 从 12 个概念选读 PAR loop、agent-as-judge 等需要的主题 |
| 8 · Agent 操作界面 | Agent 怎么操作 API 以外的真实环境? | 选择 Computer Use、Browser Use 或 Code Sandbox |
两个关键 Hub:Stage 5 与 Stage 8
- **Stage 5(Claude Code 生态)**是工具与规则 Hub:MCP、Skills、Plugins、Hooks、Subagents 的分工与合作都在这里讲清,Track A 看“怎么用”,Track B 看“怎么组合”。仓库还附带一个完整的 Skill 包范例 examples/stage-5/tool-calling-tutor/,内含
SKILL.md、references、translations 与三语 README。 - **Stage 8(Agent 界面)**是操作界面 Hub:Computer Use、Browser Use、Sandbox 的选择与安全检查,Track A 看“怎么委派”,Track B 看“怎么接进自己的 Agent”。
学习顺序的底层逻辑
首页与 README 反复强调一条贯穿主线(README.zh-Hans.md):
Stage 2 Prompt → Stage 3 Agent Loop → Stage 4 Workflow Graph/Framework → Stage 5 工具与规则 → Stage 6 Context Engineering → Stage 7 production。
Prompt、Context、Harness、Loop、Graph 会一起工作;它们不是五层,也不是互相取代的产品世代。完成 A3 或 Stage 7 后可以开始 Capstone 项目,并用 PROGRESS.zh-Hans.md 记录进度。
依你的身份继续走:五条角色路径
地图在两条主线之外,还准备了五条按读者身份分流的路径(完整说明见 README.zh-Hans.md):
| 路线 | 适合谁 | 你会处理什么? |
|---|---|---|
| 🔬 研究人员 | 研究生、博后、PI | 文献证据、可重现流程、Multi-Agent Review |
| 💻 开发者 | 软件工程师 | CLI Delegation、Code Review、测试与回滚 |
| 🎓 教师 | 老师、讲师 | 备课、反馈、隐私与教学 Prompt |
| 📊 知识工作者 | 顾问、PM、分析师 | Email、会议与报告工作流程 |
| 👥 日常用户 | 不一定写程序的 AI 用户 | 写作、学习、隐私与安全使用 |
这五条路径的设计理念是“按需选读,不必全部走完”:每条路径都把“今天先做什么”留在页面第一屏,完整项目表、替代方案与疑难排解默认收合(ROADMAP.zh-Hans.md)。路线设计说明见 branches/DESIGN.md。
三语对照与站点工程:同一个内容、三套镜像
首页顶部提供繁中 / 简中 / 英文三套语言的切换入口,仓库中每个核心文档都维护 .md(繁中默认)、.en.md、.zh-Hans.md 三个镜像文件。支撑这套三语站点的工程机制体现在 mkdocs.yml:
- 站点元信息:
site_name: awesome-agentic-ai-zh,描述为 "A trilingual 10-stop learning roadmap for agentic AI";内容直接托管在仓库根目录的stages/、tracks/、branches/、resources/与根级*.md,构建前由脚本把白名单内容暂存到_build/docs/(mkdocs.yml)。 - i18n 插件:配置
zh-TW(默认)、en、zh-Hans三个 locale,并为简体中文做了 Material 主题语言映射(zh-Hans → zh)(mkdocs.yml)。 - 锚点一致性:
toc的 slugify 规则与scripts/check-anchors.py、scripts/test_anchor_slug_parity.py对齐,确保带中文标题的跳转链接在 GitHub 与渲染后的站点上都能命中(mkdocs.yml)。 - 构建钩子:
scripts/mkdocs_hooks.py会在构建时剥离 README 中只在 GitHub 生效的行内语言切换器,避免渲染站点上出现 404 链接(mkdocs.yml)。
这套机制与 ROADMAP.zh-Hans.md 中“首页学习地图、文字和测试现在使用同一条路线;以后调整顺序时,三者要一起更新”的维护约定互相印证——同一张地图,在首页、章节文档与自动化测试之间保持单一事实来源。
动手练习体系:先跑起来,再改一件小事
首页标注“每阶段附动手练习”。这套练习的核心方法论在 docs/HOW_TO_USE.md 中讲得很清楚:先跑起来,再改一件小事,最后用测试看差别。仓库的 examples/ 目录按 Stage 组织可运行范例(Stage 1 有 2 个、Stage 3 有 6 个、Stage 4 有 5 个、Stage 6 有 5 个、Stage 7 有 6 个,详见 examples/README.zh-Hans.md)。
每个练习文件夹的典型结构是:
starter.py # 可直接运行的起点,不是空白作业纸
starter_anthropic.py # 云端路径(Path B)的起始程序
test.py / test_anthropic.py # 不连接真实模型的离线测试(Mock)
README.md / README.en.md / README.zh-Hans.md # 三语说明
requirements.txt # 依赖清单
三条运行路径(examples/README.zh-Hans.md):
| 路径 | 谁真的生成答案 | 先做什么 | 适合什么时候 |
|---|---|---|---|
| Path C:Mock | 固定的假答案 | python test.py |
第一步;先找程序错误 |
| Path A:Ollama | 你电脑上的模型 | 安装 Ollama、pull 题目指定的模型 | 练习真实模型行为,不产生供应商模型 API 账单 |
| Path B:Anthropic | Anthropic 云端模型 | 设置 ANTHROPIC_API_KEY |
想用同一道题比较云端质量时 |
例如第一次运行 examples/stage-3/01-function-calling/ 只需三行命令:
cd examples/stage-3/01-function-calling
python -m pip install -r requirements.txt
python test.py
“Mock 通过”只证明程序的固定逻辑能工作,还没有证明任何模型一定会答对;真实模型行为要用固定 eval 核对。本地模型默认 tag 与下载大小(2026-08-31 UTC 查核)为:Stage 1–2 用 gemma4:e4b(9.6 GB)、Stage 3–6 用 qwen2.5:3b(1.9 GB)、Stage 7 用 qwen3.5:4b(3.4 GB)(examples/README.zh-Hans.md)。
Stage 3 的六步练习路线
Stage 3 是 Track B 的第一站,六个练习把“工具使用与第一个 Agent Loop”拆成可独立完成的台阶:
- Function Calling(一个工具、一次调用):模型生成
get_weatherTool Call,程序验证参数后执行,再把 Tool Result 送回模型。练习提供 Ollama 主路径(API 费用 $0)与 Anthropic 对照路径两个完整可复制程序。 - 多工具选择:模型在
calculator与get_weather之间选择,程序只派发 allowlist 内的名称;明确禁止globals()[model_name]()或eval()派发。 - 从零实现 ReAct(不用 framework):核心是一个有
MAX_STEPS上限的 13 行 loop——ask_model → read_tool_calls → validate_call → execute → make_tool_result,没有 tool call 就返回最终答案,超过步数就报错。 - 多步骤推理任务:观察模型是否会接着使用前一个工具的结果(先查天气、再换算华氏)。
- 错误处理:把“可以让模型修正的工具错误”送回模型,对 transport、解析或超上限错误明确停止;Anthropic 失败结果用
"is_error": true。 - Function schema 设计:用同一组题目比较坏 schema 与好 schema,练习工具命名、description、enum 与
additionalProperties: false的五条设计规则。
这一章的完整双路径实现分别位于 examples/stage-3/03-react-from-scratch/、examples/stage-3/05-error-handling/ 与 examples/stage-3/06-schema-design/,schema 速查表在 resources/schema-design-cheatsheet.zh-Hans.md。
写第一个 Agent 前的五条底线
无论走哪条路线,Stage 3 都要求在写代码前先立下五条安全底线:
- 只执行 allowlist 里的工具,不用模型输出的名称做任意函数调用;
- 把工具参数当成不可信输入;先检查类型、范围和权限;
- 工具只拿完成任务需要的最小权限;
- 删除、付款、发邮件等高风险动作,执行前要让人确认;
- 设置最大轮数、timeout 和费用上限,不能让 Agent 无限绕圈。
这五条底线会在后续 Stage 中逐步工程化:Stage 7 的 Eval、观测与恢复,以及 examples/stage-7/06-safe-execution/ 用本机 JSON 假动作教 approval、checkpoint、resume 与 idempotency(不调用模型)。
怎么学才不容易卡住?
首页与 docs/HOW_TO_USE.md 给出了同一条学习方法论:
- 一次只走一个 Stage:先回答这一章的核心问题;
- 核心词与必读先看:它们会直接用在后面的练习;
- 直接复制第一个命令:先跑不连网的测试,不必抄一份空白文件;
- 一次只改一件事:改完立刻再跑测试,才知道是哪个改动造成结果;
- 做到完成条件再往下走:看懂不等于做得到。
每道题做完后问自己三句话(docs/HOW_TO_USE.md):为什么这样写?(例如 Agent Loop 为什么要把 tool result 放回 messages)、拿掉它会怎样?(例如没有 max_iter、schema 或 approval gate 会发生什么)、真实环境还缺什么?(通常要再补 auth、eval、observability、retry 或人工核准)。
时间安排参考(README.zh-Hans.md):Track A 约 8–10 周;Track B 主干约 16–22 周,每周投入 5–8 小时时通常需要 5–7 个月。时程只是安排参考,先完成眼前的一步即可。
先收藏的学习入口
README 按用途给出了最常用入口的优先级清单(完整清单在 RESOURCES.zh-Hans.md):
- 开始:零基础设置指南(⭐⭐⭐⭐⭐)、如何使用这份教材(⭐⭐⭐⭐⭐)、学习进度表(⭐⭐⭐⭐);
- 学习:核心名词表(⭐⭐⭐⭐⭐)、可执行范例入口(⭐⭐⭐⭐⭐)、实作 Cookbook(⭐⭐⭐⭐);
- 查资料:资源工具柜(⭐⭐⭐⭐⭐)、完整资源清单(⭐⭐⭐⭐)、CLI Agent 选择指南(⭐⭐⭐⭐)、课程与认证地图(⭐⭐⭐⭐)。
星号表示学习优先顺序,不是项目排行榜——这一约定贯穿整个仓库:⭐⭐⭐⭐⭐ 代表“没有它就会卡住”,补充资源诚实使用 ⭐⭐⭐⭐(强烈推荐)或 ⭐⭐⭐(扎实参考),不用假五星(stages/00-foundations.zh-Hans.md)。
现在就开始
- 完全没写过程序:从 Stage 0:基础准备 开始,API 或 CLI Agent 不熟时搭配 零基础设置指南;
- 已经会 Python、Git 与 API:从 Stage 1:LLM 基础 开始;
- 还不确定要走哪条路:先看上面的 Track A/Track B 选择表。
下载到本机阅读时:
git clone https://github.com/WenyuChiou/awesome-agentic-ai-zh.git
cd awesome-agentic-ai-zh
下载后先打开 stages/00-foundations.zh-Hans.md,或直接前往适合你的第一站。仓库是只读的,阅读与运行练习都不会要求你修改仓库内容——练习文件复制到自己新建的文件夹即可。