从零到上框架：AI Agent 开发完整学习路径（TypeScript）

一套面向初学者、从零手写 → 再上框架的 AI Agent 开发课程。 用 TypeScript 打通底层原理，再衔接主流框架，学完可直接用于求职（作品集 + 面试）与创业（demo → 产品）。

---

这套课程解决什么问题

市面上的 Agent 教程，要么只调 API 浅尝辄止，要么直接堆框架不讲原理——面试一问底层就露怯，创业一遇成本/幻觉就抓瞎。

本课程的取舍：

• 🧱 先手写，后框架：先纯手写 agent loop、工具调用、记忆、RAG、多智能体，理解每一行为什么存在；再引入 LangGraph.js / Vercel AI SDK，知其所以然。
• 🪜 三层学习路线：每章都分成「极简 → 进阶 → 真实实践」，先跑通最小闭环，再理解原理边界，最后映射到真实项目。
• ▶️ 每章可运行：npx tsx 直接跑，零编译、零环境折腾。
• 🗺️ 先看图，再看代码：每章都有可缩放的 图解学习地图 / Mermaid 图（默认就放到可读尺度，不必手动放大），并自动插入「抽象概念可视化」模块——每个概念按类型渲染专属的内联 SVG 动画场景（循环环 / 传送带 / 双路汇流 / 语义空间…）；本章概念图谱还会高亮本章焦点、按关系类型给连线配色。所有图片由代码内联绘制（零外部图片资源），用流程图、示意图、轻量动画、彩色加粗重点和外部阅读链接先建立心智模型，再进入原理讲解和代码走读。
• 🔌 厂商无关：统一的 getLLM() 抽象，换 Claude / OpenAI 只改一行 .env。
• 💼 能写进简历：毕业项目覆盖 29 个可演示作品集项目；附求职指南（简历模板 + 面试题）与创业指南（demo → 产品）。

适合：有基础 JS/TS、想入行或转行做 AI 应用 / Agent 工程的同学。

---

快速开始

git clone https://github.com/songuu/agent.git
cd agent
pnpm install

# 配置 key（至少一个厂商）
cp .env.example .env        # Windows: Copy-Item .env.example .env
#  → 编辑 .env 填入 ANTHROPIC_API_KEY 或 OPENAI_API_KEY

# 验证（不需要 key）
pnpm typecheck

# 跑第一个例子（需要 key）
npx tsx lessons/02-first-llm-call/index.ts

详细步骤见 第 00 章 · 环境搭建。

📖 用网页方式学习（课程站点）

整套课程内置了一个美观的网页站点（总览首页 + 全部课程 + 全文搜索 + 暗色模式 + Mermaid 图渲染）：

pnpm site:dev       # 本地开发：http://localhost:5173
pnpm site:build     # 构建静态站点到 .vitepress/dist
pnpm site:preview   # 预览构建产物

站点目录由 knowledge-graph/data/graph.ts 的 CHAPTERS 数据驱动——新增章节自动出现在侧边栏，无需改站点配置。

▶️ 在网页里直接运行 demo

开发时可以启动带本地运行器的站点，在课程页面的 demo 位置直接点「运行」，并在网页终端里实时查看 stdout/stderr 与 AI 流式输出：

pnpm site:live

它会同时启动：

• VitePress 课程站点：http://localhost:5173
• dev-only 本地运行器：http://127.0.0.1:5174

运行器只读取本机 .env 配置，支持现有 Anthropic/OpenAI 配置，也支持 LLM_PROVIDER=ollama 的本地 Ollama 模式。它不会把 key 明文返回给浏览器。

安全边界：这个运行器只能用于本地开发学习，默认只绑定 127.0.0.1，不要部署、反代或暴露到公网。普通 pnpm site:build 仍然生成可独立部署的静态站；没有启动 runner 时，页面只会显示友好的不可用提示。

---

全局导航

想直接跳到具体课程，走 全局课程导航。如果你想按 agent 类型、岗位目标或生产能力倒推学习路线，走 Agent 学习指南与分类地图。如果你要把 2026 年 agent 趋势落成工程边界，先读 Agent 趋势与五平面架构蓝图，再进入 Agent Engineering 20 周完整课程。它们一起整理了第 00–21 章、B1-B12 基础指南、Agent Engineering A1–A8、29 个毕业项目、RAG 架构蓝图、企业知识库 Agent 蓝图、企业知识库 Agent Capstone、RAG 系统实战项目和源码解析。

---

学习路径

每章都按「三层学习路线」设计，保证不是只看懂概念，而是一路走到能用在真实项目里：

每一层都建议按这个顺序学：

1. 先读可缩放的 图解学习地图 和「抽象概念可视化」，把流程、数据流、控制流装进脑子；彩色加粗的「核心判断 / 易错边界」先记住，外部理解链接用于课后补背景。
2. 再读 原理展开，理解为什么这样设计，以及它解决了 LLM 的哪个边界。
3. 最后看 代码走读 并运行 npx tsx lessons/NN-xxx/index.ts，把图里的每个节点对应到真实代码。

第00章 环境搭建
   │
   ▼
第一部分 · 基础概念 ───────► 第二部分 · 从零手写核心
 01 什么是 Agent             04 手写 Agent 循环 (ReAct)
 02 第一次 LLM 调用          05 工具调用基础
 03 提示工程                 06 从零构建工具系统
 B 基础概念扩展专题          07 短期记忆与上下文
   │                                │
   ▼                                ▼
第三部分 · 知识与检索        第四部分 · 进阶模式
 08 Embedding 与向量检索     10 推理范式 (ReAct/Plan/Reflect)
 09 从零实现 RAG             11 多智能体编排
   │                                │
   ▼                                ▼
第五部分 · 工程化与框架       第六部分 · 生产化
 12 上框架 (LangGraph/AI SDK) 15 评估与测试
 13 结构化输出与校验          16 可观测性与成本
 14 流式输出与 UX            17 安全与护栏
                            18 部署：变成服务
   │
   ▼
第七部分 · 前沿与生态
 19 Agent 前沿发展与生态拆解
 20 Agent 前沿文章库
   │
   ▼
第 21 章 · 源码解析（LangChain/LangGraph/LlamaIndex）
   │
   ▼
🎓 毕业项目 · Deep Research Agent（综合实战）
   │
   ▼
🔬 进阶 RAG 专题 · rag-advanced（分块/混合/精排/改写/评估/生产化）
   │
   ▼
🧭 RAG 完整架构蓝图（写入/查询/eval/治理/部署）
   │
   ▼
🏢 企业知识库 Agent 蓝图（记忆/RAG/事件/任务/部署纵向闭环）
   │
   ▼
🎓 毕业项目 · 企业知识库 Agent（纵向全栈实战）
   │
   ▼
📚 进阶项目 · songuu/rag-system（生产级 RAG 系统）
   │
   ▼
💼 求职指南   🚀 创业指南

完整大纲见 docs/curriculum.md。

🗺️ 想看概念之间怎么串联？全局知识图谱（每章末尾也有各自的概念图谱与延伸阅读，交互版见 knowledge-graph/output/index.html）。

---

章节一览

---

仓库结构

agent/
├── README.md                  # 你在这里
├── .env.example               # 复制成 .env 填 key
├── docs/
│   ├── setup.md               # 第 00 章 · 环境搭建
│   ├── curriculum.md          # 完整教学大纲
│   ├── glossary.md            # 术语表
│   ├── career-guide.md        # 💼 求职指南
│   ├── startup-guide.md       # 🚀 创业指南
│   ├── agent-learning-guides.md # Agent 学习指南与分类地图
│   ├── agent-trends-architecture.md # 🧭 2026 Agent 趋势与五平面架构
│   ├── rag-architecture.md    # 🧭 RAG 完整架构蓝图
│   ├── enterprise-knowledge-base-agent.md # 🏢 企业知识库 Agent 蓝图
│   └── rag-system-project.md  # 📚 RAG 系统实战项目
├── source-analysis/           # 第 21 章 · 源码解析
├── src/shared/                # 跨课程共享的「标准库」（provider 无关）
│   ├── llm/                   #   统一 LLM 抽象 + Anthropic/OpenAI 实现 + embedding
│   ├── agent/                 #   工具系统 (tool) + 可复用 agent 循环 (loop)
│   ├── rag/                   #   内存向量库
│   └── util/                  #   env / logger / ui
├── lessons/                   # 20 章课程，每章 README + 可运行代码
│   ├── 01-what-is-an-agent/
│   └── ...
└── capstone/
    ├── README.md                        # 🎓 29 个毕业项目总览
    ├── project-catalog.mjs              # 新增 20 个实践项目的数据源
    ├── deep-research-agent/             # 🎓 Deep Research 综合实战
    ├── support-copilot/                 # 客服 Copilot
    ├── code-review-crew/                # 代码评审团
    ├── agent-eval-harness/              # Agent 评测与回归门
    ├── mini-agent-harness/              # MCP + Docker sandbox + checkpoint
    ├── incident-responder/              # 告警响应与复盘实战
    ├── feedback-intelligence/           # 用户反馈洞察实战
    ├── sales-lead-researcher/           # 销售线索研究实战
    ├── enterprise-knowledge-base-agent/ # 🏢 企业知识库 Agent Capstone
    └── privacy-dsr-automation/          # 新增实践项目之一，其余见 capstone/README.md

💡 设计说明：第二、三部分「从零手写」时，各章在自己目录里亲手实现核心逻辑以理解原理； 这些能力的「成熟版」沉淀在 src/shared/，供后续章节与毕业项目复用——这正是真实项目里 「先理解、再抽象、后复用」的工程演进路径。

---

学完之后

• 💼 求职指南：岗位画像、技能清单、用本项目写简历、高频面试题。
• 🚀 创业指南：机会判断、MVP 裁剪、成本控制、上线 checklist。
• Agent 学习指南与分类地图：按学习阶段、agent 类型、工程能力和岗位路线拆解全项目。
• 🧭 2026 Agent 趋势与五平面架构：把 harness、外置状态、隔离执行、协议互操作与 trajectory/outcome assurance 组织成可渐进落地的工程框架。
• 🛠️ Agent Engineering 20 周完整课程：沿 A1–A8 把 Run、Prompt、Context Runtime、Evidence RAG、Durable Memory、Cache/Multi-Agent 与 Trace/发布治理落成可执行、可验证、可回放的企业合同。
• 🧩 进阶 LangGraph · L6 Event streaming：用真实 multi-mode stream 建立 user/debug/audit 投影边界，避免前端直接绑定框架 chunk。
• 🔬 进阶 RAG 专题：分块策略、混合检索、重排、查询改写、评估、生产化六章，把第 08/09 章的最小 RAG 补成生产级，能力沉淀在 src/shared/rag/。
• 源码解析：先从热门库卡片或仓库矩阵解析器定位任意 GitHub 仓库的包/文件边界，再用源码对话检索 raw source 和行号引用，再切 CodeMap 对照职责层，再顺着官方源码入口读 LangChain、LangGraph、LlamaIndex，把“会用框架”推进到“能看懂和调试框架”。
• 🧭 RAG 完整架构蓝图：把 RAG demo 升级成可维护系统，覆盖写入路径、查询路径、数据模型、API 边界、安全治理、质量闭环和部署拓扑。
• 🏢 企业知识库 Agent 蓝图：把 RAG、记忆、工具、流式事件、定时任务和部署组织成一条企业级作品集路线。
• 🎓 企业知识库 Agent Capstone：把蓝图拆成产品边界、数据模型、API、事件流、测试门和 4 周实现路线。
• 📚 RAG 系统实战项目：连接到 songuu/rag-system，把第 08/09 章的最小 RAG 扩展成独立知识库系统。

---

常见问题

• 必须用 Claude 吗？ 不。.env 里把 LLM_PROVIDER 设成 openai 即可，课程代码一行不用改。
• 必须用 pnpm 吗？ 不。npm install / yarn 也行，把命令里的 pnpm 换掉即可。
• 要花多少钱？ 全程用便宜模型（如 gpt-4o-mini / claude-haiku）跑完成本很低；第 16 章专门讲成本控制。
• 没有 TS 基础能学吗？ 建议先掌握基础 JS/TS（异步、模块、类型），再开始第 01 章。

---

License

MIT © songuu