1261 lines
67 KiB
Python
1261 lines
67 KiB
Python
"""
|
||
generate_readmes.py
|
||
|
||
为 code/ 下的每个学习子目录生成 README.md：
|
||
- 占位文件，让 git 能跟踪空目录（跨设备同步时结构不丢）
|
||
- 写清楚每个章节的学习目的 / 要求 / 主要内容 / 对应 docs / 建议练习
|
||
|
||
运行：
|
||
uv run python code/_tools/generate_readmes.py
|
||
"""
|
||
from __future__ import annotations
|
||
|
||
from pathlib import Path
|
||
|
||
CODE_ROOT = Path(__file__).resolve().parent.parent
|
||
DOCS_ROOT = CODE_ROOT.parent / "docs"
|
||
|
||
|
||
# ---------------------------------------------------------------------------
|
||
# 元数据：每个 phase 的标题 + 阶段目标 + 子目录列表
|
||
# ---------------------------------------------------------------------------
|
||
|
||
PHASES: list[dict] = [
|
||
{
|
||
"code_dir": "001_phase1_foundations",
|
||
"phase_title": "阶段一 · 前置核心基础",
|
||
"phase_doc_dir": "01-阶段一-前置核心基础",
|
||
"phase_goal": (
|
||
"把 Python 高级语法 / 大模型基础与 Prompt 工程 / 软件工程基础设施打牢，"
|
||
"为后续 Agent 开发提供语言、工具与工程地基。"
|
||
),
|
||
"topics": [
|
||
{
|
||
"code": "01_python_advanced_basics",
|
||
"title": "Python 高级编程之基础巩固",
|
||
"purpose": "巩固 Python 类型注解、dataclass、异常处理、上下文管理器等基础功底，是后续所有阶段的语言基座。",
|
||
"prerequisites": "已完成 Python 入门语法（变量 / 函数 / 类），能独立写 100 行左右的脚本。",
|
||
"content": [
|
||
"类型注解：`typing` / `TypeAlias` / `NewType` / `Optional` / `Union`",
|
||
"`dataclass` 数据类（含 `field`、`frozen`、`post_init`）",
|
||
"异常处理：`try/except/else/finally` + 异常链 `raise from` + 自定义异常层级",
|
||
"上下文管理器：`with` 协议 / `@contextmanager` / `contextlib`",
|
||
"模块与包：`__init__.py` 的语义 / 相对导入 / 命名空间包",
|
||
],
|
||
"exercises": [
|
||
"写一个支持嵌套的 `dataclass` 配置加载器（含默认值校验）",
|
||
"实现可复用的计时 / 临时目录上下文管理器",
|
||
"构造「连接池用完即抛」的自定义异常链路",
|
||
],
|
||
"done": [
|
||
"能熟练使用类型注解与 dataclass 定义数据结构",
|
||
"能用上下文管理器封装任意资源的获取与释放",
|
||
"能写出层级清晰的自定义异常体系",
|
||
],
|
||
},
|
||
{
|
||
"code": "02_python_advanced_syntax",
|
||
"title": "Python 高级编程之进阶语法",
|
||
"purpose": "掌握装饰器、生成器、描述符、元类等进阶特性，能写出「抽象可复用」而非「复制粘贴」的代码。",
|
||
"prerequisites": "已完成「01_python_advanced_basics」。",
|
||
"content": [
|
||
"装饰器：函数装饰器 / 类装饰器 / 带参装饰器 / `functools.wraps`",
|
||
"生成器与 `yield` / `yield from` / `async for`",
|
||
"描述符协议：`__get__` / `__set__` / `__delete__`（理解 `@property` 底层）",
|
||
"迭代器协议：`__iter__` / `__next__` / `itertools`",
|
||
"元类基础：`type` / `__init_subclass__` / `ABCMeta`",
|
||
],
|
||
"exercises": [
|
||
"实现一个带超时与缓存的函数装饰器",
|
||
"写一个分批读取大文件的生成器",
|
||
"用描述符实现一个类型校验的字段系统（类 `pydantic.Field`）",
|
||
],
|
||
"done": [
|
||
"能写任意结构的装饰器并理解闭包变量捕获",
|
||
"能用生成器改造长列表为流式处理",
|
||
"能解释描述符与 property 的关系",
|
||
],
|
||
},
|
||
{
|
||
"code": "03_python_concurrency_async",
|
||
"title": "Python 高级编程之并发与异步",
|
||
"purpose": "理解多线程 / 多进程 / 协程三种并发模型，能为 IO 密集 vs CPU 密集任务选对工具。",
|
||
"prerequisites": "已完成「01_python_advanced_basics」与「02_python_advanced_syntax」。",
|
||
"content": [
|
||
"GIL 的影响与绕过（多进程 vs C 扩展）",
|
||
"`threading` 线程池 / `concurrent.futures`",
|
||
"`multiprocessing` 进程池与共享状态",
|
||
"`asyncio`：事件循环 / `async/await` / Task / gather",
|
||
"异步上下文与同步代码互操作：`asyncio.to_thread` / `run_in_executor`",
|
||
],
|
||
"exercises": [
|
||
"用线程池并发抓取 10 个 URL 的标题并计时",
|
||
"用 `asyncio.gather` 并发调用 5 个模拟 LLM 接口",
|
||
"对比多线程 / 多进程 / 协程在 IO 密集任务上的耗时差异",
|
||
],
|
||
"done": [
|
||
"能说清 IO 密集用 asyncio，CPU 密集用 multiprocessing",
|
||
"能写正确的 `async/await` 代码并处理并发异常",
|
||
"能将同步阻塞调用丢进线程池不阻塞事件循环",
|
||
],
|
||
},
|
||
{
|
||
"code": "04_python_core_toolkits",
|
||
"title": "Python 高级编程之核心工具库",
|
||
"purpose": "掌握 pydantic / loguru / tenacity / python-dotenv / pandas 这五个几乎每个 Agent 项目都用得到的库。",
|
||
"prerequisites": "已完成「01_python_advanced_basics」。",
|
||
"content": [
|
||
"`pydantic v2`：`BaseModel` / `model_validate` / `model_json_schema` / 脏 JSON 兜底",
|
||
"`loguru`：结构化日志 / `logger.exception` / 日志分级",
|
||
"`tenacity`：重试三要素（何时停 / 等多久 / 重试什么）+ 指数退避",
|
||
"`python-dotenv`：`.env` 加载 / 环境变量管理 / `.gitignore`",
|
||
"`pandas` / `numpy`：选列 / 过滤 / groupby 聚合 / 只喂摘要控 token",
|
||
],
|
||
"exercises": [
|
||
"用 pydantic 校验并恢复模型输出的脏 JSON（```json 包裹 / 注释 / 截断）",
|
||
"用 loguru 给「LLM 调用 → 工具执行」全链路打 INFO 日志",
|
||
"写一个带指数退避的 tenacity 重试装饰器，只重试网络异常",
|
||
],
|
||
"done": [
|
||
"能用 pydantic 校验模型 JSON 输出 + 失败兜底",
|
||
"能用 tenacity 重试网络异常，参数错误 fail-fast",
|
||
"能搭好分层项目骨架 + pytest + ruff + mypy 质量门禁",
|
||
],
|
||
},
|
||
{
|
||
"code": "05_llm_fundamentals",
|
||
"title": "大模型基础原理",
|
||
"purpose": "建立对 LLM 的应用层认知：能看懂模型能力边界、合理设置采样参数、理解上下文窗口限制。",
|
||
"prerequisites": "无（概念为主），可与「06_llm_api_in_practice」并行。",
|
||
"content": [
|
||
"LLM / Token / 上下文窗口与计费",
|
||
"采样参数：`temperature` / `top_p` / `top_k` 与工具调用场景推荐 0~0.3",
|
||
"Embedding：把文本映射成向量，语义相近则向量距离近",
|
||
"Function Calling：模型按 tools Schema 输出「调用哪个工具、传什么参数」",
|
||
"幻觉与 RAG 抑制思路",
|
||
],
|
||
"exercises": [
|
||
"用同一 prompt 在不同 temperature 下生成 3 次，对比随机性",
|
||
"用 sentence-transformers 把 5 条相似语料烤成 embedding 并算两两余弦相似度",
|
||
"画一张「输入 → 上下文窗口 → 输出」的 token 流转图",
|
||
],
|
||
"done": [
|
||
"能说清 Token / 上下文窗口 / 采样的语义",
|
||
"能给工具调用场景合理设置 temperature",
|
||
"能区分 Embedding 与 Function Calling 的用途",
|
||
],
|
||
},
|
||
{
|
||
"code": "06_llm_api_in_practice",
|
||
"title": "主流模型 API 实战",
|
||
"purpose": "能用一套代码对接 OpenAI / Claude / DeepSeek / Ollama 等多家模型，并掌握流式调用与错误码处理。",
|
||
"prerequisites": "已完成「05_llm_fundamentals」。",
|
||
"content": [
|
||
"OpenAI 兼容生态：换 base_url 即换模型（DeepSeek / Ollama / vLLM）",
|
||
"Claude 原生 SDK 与 OpenAI 格式的三处差异（system 位置 / content blocks / tool_calls）",
|
||
"流式调用：`stream=True` / `chunk.choices[0].delta.content` 过滤",
|
||
"错误码处理：429 / 401 / 404 / 5xx 的语义与处置",
|
||
"本地部署：Ollama 调试 / vLLM 生产推理",
|
||
],
|
||
"exercises": [
|
||
"用 OpenAI SDK 对接 DeepSeek（仅改 base_url）",
|
||
"实现一个流式接口：逐 chunk 拼接并打印",
|
||
"写一个分类处置 429/401/404/5xx 的重试函数",
|
||
],
|
||
"done": [
|
||
"能用同一套代码切换不同模型（含流式）",
|
||
"能用 Ollama 本地部署并完成一次工具调用全流程",
|
||
"能为 429/5xx 写退避重试，对 401/404 直接 fail-fast",
|
||
],
|
||
},
|
||
{
|
||
"code": "07_prompt_engineering",
|
||
"title": "Prompt 工程核心",
|
||
"purpose": "掌握让模型稳定输出符合要求结果的提示设计技巧。",
|
||
"prerequisites": "已完成「05_llm_fundamentals」。",
|
||
"content": [
|
||
"指令设计：角色 + 任务 + 约束 + 输出格式",
|
||
"Few-shot：放若干「输入→输出」示例让模型模仿",
|
||
"CoT（思维链）：引导模型先逐步推理再给答案",
|
||
"结构化输出：要求 JSON / YAML 输出 + pydantic 兜底",
|
||
"ReAct Prompt：思考 → 行动 → 观察 三段式",
|
||
],
|
||
"exercises": [
|
||
"用 Few-shot 写一个稳定的「意图分类器」prompt",
|
||
"写一个 CoT prompt，让模型拆解数学题步骤",
|
||
"设计一个 ReAct prompt，约束模型按 思考/工具/观察 三段回答",
|
||
],
|
||
"done": [
|
||
"能用 Few-shot / CoT 显著提升模型输出稳定性",
|
||
"能让模型稳定按 JSON / 表格等结构化格式输出",
|
||
"能写出清晰的 ReAct 风格 prompt",
|
||
],
|
||
},
|
||
{
|
||
"code": "08_software_engineering_basics",
|
||
"title": "软件工程与基础设施",
|
||
"purpose": "补上 Git、FastAPI、Docker、PostgreSQL、Redis 这四根工程地基，让 Agent 能从「跑通」变成「可维护」。",
|
||
"prerequisites": "已完成阶段一前 7 个小点中的任意 4 个。",
|
||
"content": [
|
||
"Git 进阶：rebase vs merge / 分支流 / cherry-pick",
|
||
"FastAPI：路由 / Pydantic 模型 / SSE 流式 / Depends 依赖注入",
|
||
"容器化：Dockerfile 分层 / docker-compose 一键拉起",
|
||
"数据库：PostgreSQL 事务 / Redis TTL / SQLAlchemy 2.x",
|
||
],
|
||
"exercises": [
|
||
"实现一个带 SSE 流式的 FastAPI 接口并 curl 测试",
|
||
"写一个多阶段 Dockerfile，按「先拷依赖再拷源码」分层",
|
||
"用 SQLAlchemy 写一段「写任务 + 写明细」的事务代码",
|
||
],
|
||
"done": [
|
||
"能用 FastAPI 实现 SSE 流式接口并跑通",
|
||
"能编写多阶段 Dockerfile 并 compose 拉起应用 + Redis",
|
||
"会用 Redis TTL 与 PostgreSQL 事务",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
{
|
||
"code_dir": "002_phase2_agent_theory",
|
||
"phase_title": "阶段二 · AI Agent 核心理论与基础范式",
|
||
"phase_doc_dir": "02-阶段二-AI-Agent核心理论与基础范式",
|
||
"phase_goal": (
|
||
"先理解 Agent 是什么、为什么需要它，以及 ReAct / Plan-and-Execute / Reflexion 三大经典范式；"
|
||
"在不依赖框架的前提下，手写一个完整的 Agent。"
|
||
),
|
||
"topics": [
|
||
{
|
||
"code": "01_agent_basics",
|
||
"title": "Agent 基础认知",
|
||
"purpose": "建立 Agent 的基础认知：什么是 Agent、与 Chatbot 的本质区别、能干什么不能干什么。",
|
||
"prerequisites": "无。",
|
||
"content": [
|
||
"Agent 的「感知 → 规划 → 调用工具 → 反馈迭代」闭环",
|
||
"Agent vs Chatbot：被动应答 vs 主动完成任务",
|
||
"Agent 的能力边界：能调什么工具、能跑多长",
|
||
"Bad-case：效果差的输入样本的归类",
|
||
],
|
||
"exercises": [
|
||
"用一段话向完全不懂的人解释「Agent 是什么」",
|
||
"列出 5 个 Agent 能落地的真实场景，并标注每场景的核心工具",
|
||
],
|
||
"done": [
|
||
"能一句话定义 Agent 并与 Chatbot 区分",
|
||
"能给出 Agent 的能力边界判断标准",
|
||
],
|
||
},
|
||
{
|
||
"code": "02_agent_core_components",
|
||
"title": "Agent 四大核心组件",
|
||
"purpose": "拆解 Agent 的四大核心组件：规划、记忆、工具、行动。",
|
||
"prerequisites": "已完成「01_agent_basics」。",
|
||
"content": [
|
||
"规划（Planning）：目标拆解 / 子任务依赖图",
|
||
"记忆（Memory）：短期 / 工作 / 长期 三层",
|
||
"工具（Tools）：函数调用的「声明 / 调用 / 结果回传」三段",
|
||
"行动（Action）：执行单元 + 异常处理 + 超时",
|
||
],
|
||
"exercises": [
|
||
"把「帮我订明天去上海的机票」拆成规划 + 工具调用序列",
|
||
"为一个 Agent 画一张四大组件的协作图",
|
||
],
|
||
"done": [
|
||
"能拆出任意 Agent 的四大组件对应到代码模块",
|
||
"能解释「记忆」为什么必须分层",
|
||
],
|
||
},
|
||
{
|
||
"code": "03_agent_paradigms",
|
||
"title": "经典 Agent 工作范式",
|
||
"purpose": "掌握 ReAct / Plan-and-Execute / Reflexion 三大基础范式的实现思路。",
|
||
"prerequisites": "已完成「02_agent_core_components」。",
|
||
"content": [
|
||
"ReAct：思考 → 行动 → 观察 循环",
|
||
"Plan-and-Execute：先生成完整计划再逐步执行",
|
||
"Reflexion：失败后反思错误再重试",
|
||
"ToT / GoT / MAS：思维树 / 思维图 / 多智能体（了解即可）",
|
||
],
|
||
"exercises": [
|
||
"用伪代码写一个 ReAct 主循环（带最大轮次限制）",
|
||
"用 Plan-and-Execute 写「查天气 → 算温差 → 建议穿衣」流程",
|
||
"在 ReAct 基础上加一层反思：「失败时让模型先总结原因」",
|
||
],
|
||
"done": [
|
||
"能用伪代码写出三大范式的主循环",
|
||
"能区分何时用 ReAct、何时用 Plan-and-Execute",
|
||
],
|
||
},
|
||
{
|
||
"code": "04_agent_framework_selection",
|
||
"title": "Agent 框架选型决策",
|
||
"purpose": "理解手写 vs 框架的权衡，掌握选型矩阵，能根据场景决定要不要引入 LangGraph 等框架。",
|
||
"prerequisites": "已完成「03_agent_paradigms」。",
|
||
"content": [
|
||
"手写 Agent 的好处：可控 / 轻量 / 学习价值高",
|
||
"框架的好处：状态管理 / 持久化 / 可视化 / 生态",
|
||
"选型矩阵：场景 × 团队规模 × 维护周期",
|
||
"何时不要上框架：极简单任务 / 一次性脚本",
|
||
],
|
||
"exercises": [
|
||
"为三个真实场景分别给出「手写 / LangGraph / 其他」的选型建议",
|
||
"画一张「场景复杂度 × 维护周期」的选型决策图",
|
||
],
|
||
"done": [
|
||
"能根据场景复杂度判断是否需要引入框架",
|
||
"能说清 LangGraph 比手写的具体收益",
|
||
],
|
||
},
|
||
{
|
||
"code": "99_capstone_handcrafted_agent",
|
||
"title": "阶段二综合实战 · 手写完整 Agent",
|
||
"purpose": "不依赖任何 Agent 框架，从零实现一个支持 ReAct / Plan-and-Execute / Reflexion 的完整 Agent。",
|
||
"prerequisites": "已完成阶段二前 4 个小点。",
|
||
"content": [
|
||
"MockLLM：用脚本模型替代真实 API，方便离线调试",
|
||
"ReAct 主循环 + 工具调用 + tool_call_id 配对",
|
||
"Plan-and-Execute：先生成 todo list 再逐步执行",
|
||
"Reflexion：失败后让模型反思错误再重试",
|
||
"最大轮次 + Token 限流防失控",
|
||
],
|
||
"exercises": [
|
||
"实现一个支持两个工具（如搜索 + 计算）的 ReAct Agent",
|
||
"为同一个 Agent 增加 Plan-and-Execute 模式开关",
|
||
"实现 Reflexion：失败时让模型先总结原因，再重试一次",
|
||
],
|
||
"done": [
|
||
"能在不依赖框架的前提下跑通 ReAct / Plan-and-Execute / Reflexion",
|
||
"能解释每一段代码对应框架/Agent 的哪一层",
|
||
"能识别手写 Agent 的能力边界与失控点",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
{
|
||
"code_dir": "003_phase3_frameworks",
|
||
"phase_title": "阶段三 · 主流 Agent 开发框架",
|
||
"phase_doc_dir": "03-阶段三-主流Agent开发框架",
|
||
"phase_goal": (
|
||
"以 LangGraph 为核心，掌握生产级 Agent 框架的使用；"
|
||
"LlamaIndex 用于 RAG 数据接入；CrewAI / AutoGen / 其他方案了解选型。"
|
||
),
|
||
"topics": [
|
||
{
|
||
"code": "01_langchain_basics",
|
||
"title": "LangChain 基础",
|
||
"purpose": "掌握 LangChain 的 ChatModel / PromptTemplate / LCEL / @tool 四件套。",
|
||
"prerequisites": "已完成阶段一「06_llm_api_in_practice」。",
|
||
"content": [
|
||
"ChatModel：ChatOpenAI / ChatDeepSeek / ChatOllama 切换仅改 import",
|
||
"PromptTemplate / ChatPromptTemplate + Few-shot",
|
||
"LCEL：`prompt | llm | parser` 表达式语言",
|
||
"@tool 装饰器：自动生成 JSON Schema / `bind_tools` / `AIMessage.tool_calls`",
|
||
],
|
||
"exercises": [
|
||
"用 LCEL 拼一条 `prompt | llm | parser` 管道",
|
||
"写一个 @tool 函数并解释 docstring 对模型调用决策的影响",
|
||
"实现 RunnableParallel：检索 + 问题改写两路并发",
|
||
],
|
||
"done": [
|
||
"能用 ChatPromptTemplate + LCEL 组装管道",
|
||
"能用 @tool 定义工具并解释 bind_tools 的作用",
|
||
"能说清为什么 Chain 做不了 Agent、必须上 LangGraph",
|
||
],
|
||
},
|
||
{
|
||
"code": "02_langgraph_core",
|
||
"title": "LangGraph 核心（生产级事实标准）",
|
||
"purpose": "用 LangGraph 把 Agent 画成一张图，掌握 State / Node / Edge / ConditionalEdge / Checkpointer。",
|
||
"prerequisites": "已完成「01_langchain_basics」+ 阶段二所有小点。",
|
||
"content": [
|
||
"StateGraph：State 是全局背包，Node 是一次动作，Edge 决定下一步",
|
||
"`add_messages` reducer：消息追加而非覆盖",
|
||
"ToolNode：预置的工具执行节点",
|
||
"Checkpointer / thread_id：状态持久化与中断恢复",
|
||
"interrupt：人在环路审批",
|
||
],
|
||
"exercises": [
|
||
"用 StateGraph 搭一个最小 ReAct 循环（含条件边）",
|
||
"加 Checkpointer，实现「对话中断后从上次继续」",
|
||
"实现 Supervisor 多智能体主管模式",
|
||
],
|
||
"done": [
|
||
"能用 StateGraph 搭建任意结构的 Agent",
|
||
"能用 Checkpointer 持久化与恢复会话状态",
|
||
"能解释为什么生产首选 LangGraph 而非 LCEL",
|
||
],
|
||
},
|
||
{
|
||
"code": "03_llamaindex",
|
||
"title": "LlamaIndex（RAG 数据接入与检索）",
|
||
"purpose": "掌握 LlamaIndex 的 Document / Node / Index / QueryEngine 四件套，专门做 RAG 数据接入与检索。",
|
||
"prerequisites": "已完成「01_langchain_basics」+ 阶段四「02_vector_db_and_memory」（如顺序学习可先看）。",
|
||
"content": [
|
||
"Document / Node：文档加载与切块",
|
||
"Index：VectorStoreIndex / SummaryIndex / KeywordTableIndex",
|
||
"QueryEngine：检索入口，可与 Agent 工具融合",
|
||
"LlamaIndex 与 LangGraph 组合：检索 vs 编排分工",
|
||
],
|
||
"exercises": [
|
||
"用 LlamaIndex 加载一份 PDF 并做问答",
|
||
"把 QueryEngine 包成 LangGraph 的工具节点",
|
||
"对比 LlamaIndex 与 Chroma 原生 API 的异同",
|
||
],
|
||
"done": [
|
||
"能用 LlamaIndex 完成文档接入 → 索引 → 检索",
|
||
"能把 QueryEngine 与 LangGraph 配合使用",
|
||
"能解释 LlamaIndex 与 LangGraph 的分工",
|
||
],
|
||
},
|
||
{
|
||
"code": "04_crewai",
|
||
"title": "CrewAI（角色化多智能体，了解选型）",
|
||
"purpose": "了解 CrewAI 的角色化多智能体模式，能判断什么场景适合用它。",
|
||
"prerequisites": "已完成「02_langgraph_core」（先掌握 Supervisor 多智能体）。",
|
||
"content": [
|
||
"Agent / Task / Process 三个核心抽象",
|
||
"角色化分工：每个 Agent 一个明确角色",
|
||
"CrewAI 与 LangGraph 多智能体的对比",
|
||
],
|
||
"exercises": [
|
||
"用 CrewAI 搭一个「策划 + 写作 + 评审」三人组",
|
||
"对比 CrewAI 与 LangGraph Supervisor 模式的代码差异",
|
||
],
|
||
"done": [
|
||
"能用 CrewAI 跑通一个最小多 Agent 示例",
|
||
"能说清何时选 CrewAI、何时选 LangGraph",
|
||
],
|
||
},
|
||
{
|
||
"code": "05_autogen",
|
||
"title": "AutoGen（微软多 Agent，了解选型）",
|
||
"purpose": "了解 AutoGen 的自然语言对话协作模式，知道它的现状（已并入 MAF 进入维护模式）。",
|
||
"prerequisites": "已完成「02_langgraph_core」。",
|
||
"content": [
|
||
"AutoGen 的 Agent 间自然语言对话协作",
|
||
"现状：已并入 Microsoft Agent Framework（MAF）",
|
||
"何时考虑 AutoGen、何时直接上 LangGraph",
|
||
],
|
||
"exercises": [
|
||
"用 AutoGen 跑通一个最小多 Agent 对话",
|
||
"查阅 MAF 官方文档，对比 AutoGen 与 LangGraph 现状",
|
||
],
|
||
"done": [
|
||
"能说清 AutoGen 的定位与现状",
|
||
"能判断新项目是否还要选 AutoGen",
|
||
],
|
||
},
|
||
{
|
||
"code": "06_other_frameworks",
|
||
"title": "其他主流方案",
|
||
"purpose": "横向了解 Semantic Kernel / Assistants API / Dify 等方案，建立选型视野。",
|
||
"prerequisites": "已完成「01_langchain_basics」~「05_autogen」。",
|
||
"content": [
|
||
"Semantic Kernel：微软插件化框架（适合 Python/.NET 混合团队，已并入 MAF）",
|
||
"OpenAI Assistants API：托管式 Agent（快速原型，逻辑黑盒）",
|
||
"Dify：低代码 Agent 平台（业务验证）",
|
||
"选型矩阵：自研 vs LangGraph vs Assistants API vs Dify",
|
||
],
|
||
"exercises": [
|
||
"用 Assistants API 跑通一个最小 Agent",
|
||
"用 Dify 搭建一个零代码知识库问答",
|
||
],
|
||
"done": [
|
||
"能横向对比四大方案的优劣",
|
||
"能根据场景选择最合适的方案",
|
||
],
|
||
},
|
||
{
|
||
"code": "99_capstone_langgraph_agent",
|
||
"title": "阶段三综合实战 · LangGraph + LangChain 完整 Agent",
|
||
"purpose": "用 LangGraph + LangChain 搭建一个生产级 Agent，覆盖工具调用、状态持久化、消息流式。",
|
||
"prerequisites": "已完成阶段三前 6 个小点。",
|
||
"content": [
|
||
"StateGraph 完整搭建：LLM 节点 + ToolNode + 条件边",
|
||
"Checkpointer：thread_id 持久化与会话恢复",
|
||
"Stream：消息按 token 流式输出",
|
||
"错误重试：tenacity 装饰器 + 异常包装",
|
||
],
|
||
"exercises": [
|
||
"实现一个支持多工具、多轮对话的 LangGraph Agent",
|
||
"加入 Checkpointer 并验证中断恢复",
|
||
"用 FastAPI 暴露 SSE 流式接口",
|
||
],
|
||
"done": [
|
||
"能用 LangGraph 搭建任意结构的 Agent",
|
||
"能解释 StateGraph / ToolNode / Checkpointer 的协作",
|
||
"能将 Agent 暴露成 SSE 流式 API",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
{
|
||
"code_dir": "004_phase4_tool_ecosystem",
|
||
"phase_title": "阶段四 · 工具生态与外围组件集成",
|
||
"phase_doc_dir": "04-阶段四-工具生态与外围组件集成",
|
||
"phase_goal": (
|
||
"掌握 Agent 工具调用生态、向量数据库、RAG 全流程、MCP 协议；"
|
||
"把知识库封装成 Agent 工具，让 Agent 既「检索」又「做事」。"
|
||
),
|
||
"topics": [
|
||
{
|
||
"code": "01_tool_calling_ecosystem",
|
||
"title": "工具调用生态（工具工厂五要素）",
|
||
"purpose": "掌握工具开发五要素（校验 / 超时 / 权限 / 异常包装 / 结果精简）和工具工厂模式。",
|
||
"prerequisites": "已完成阶段三「01_langchain_basics」+ 阶段一「04_python_core_toolkits」。",
|
||
"content": [
|
||
"工具五要素：pydantic 校验 / 超时 / 权限白名单 / 异常包装 / 结果精简",
|
||
"工具工厂模式：业务只写纯函数，五要素自动继承",
|
||
"搜索工具：Tavily / SerpAPI / DuckDuckGo",
|
||
"代码执行沙箱：本地 / Docker 容器 / E2B 云沙箱三档位",
|
||
"文件处理：PDF（PyMuPDF）/ Excel（openpyxl）/ OCR",
|
||
],
|
||
"exercises": [
|
||
"实现一个带工具工厂的搜索工具（含超时与白名单）",
|
||
"用 Docker 跑一段用户生成的 Python 代码（断网 + 限内存）",
|
||
"用 PyMuPDF 解析一份 PDF 并截断返回前 2000 字",
|
||
],
|
||
"done": [
|
||
"能说清工具五要素并落地一个带工厂的工具",
|
||
"能区分代码执行的三档位适用场景",
|
||
"能写出带重试 + 降级的搜索/外部接口封装",
|
||
],
|
||
},
|
||
{
|
||
"code": "02_vector_db_and_memory",
|
||
"title": "向量数据库与记忆存储",
|
||
"purpose": "掌握向量基础、主流向量库选型、混合检索与 Rerank，能搭一个生产级记忆存储组合。",
|
||
"prerequisites": "已完成阶段一「05_llm_fundamentals」。",
|
||
"content": [
|
||
"Embedding：把文本映射成高维向量 / 余弦相似度",
|
||
"轻量方案：Chroma / FAISS",
|
||
"生产方案：Qdrant / Milvus / Pinecone / pgvector",
|
||
"检索进阶：元数据过滤 / 稠密+稀疏双路召回 / Rerank 精排",
|
||
"生产记忆组合：会话缓存 Redis + 语义库 Qdrant + 结构化 PG",
|
||
],
|
||
"exercises": [
|
||
"用 Chroma 完成增删改查 + 元数据过滤",
|
||
"用 Qdrant 实现混合检索 + Rerank",
|
||
"画一张「Redis + Qdrant + PG」三件套的记忆架构图",
|
||
],
|
||
"done": [
|
||
"能区分轻量 vs 生产向量库的取舍",
|
||
"能用 Chroma / Qdrant 实现混合检索 + Rerank",
|
||
"能讲清「稠密 BM25 + RRF + Rerank」的完整链路",
|
||
],
|
||
},
|
||
{
|
||
"code": "03_rag_technique",
|
||
"title": "RAG 技术体系",
|
||
"purpose": "掌握 RAG 流水线、chunking 选型、查询改写 / Rerank / 引用溯源等高级技术，能把 RAG 封装成 Agent 工具。",
|
||
"prerequisites": "已完成「02_vector_db_and_memory」+ 阶段三「02_langgraph_core」。",
|
||
"content": [
|
||
"RAG 七环节：加载 → 清洗 → 分块 → 向量化 → 检索 → 生成",
|
||
"chunking 策略：固定长度 / 递归字符 / 标题感知 / 语义 / 父子",
|
||
"高级 RAG 四件套：查询改写 / 多轮迭代 / Rerank / 引用溯源",
|
||
"Agent-RAG：把知识库封装成 kb_search 工具",
|
||
"LlamaIndex 检索 + LangGraph 编排的黄金组合",
|
||
],
|
||
"exercises": [
|
||
"用 RAG 完整流程做一份知识库问答",
|
||
"对比固定长度 / 递归字符 / 父子分块的 recall@5",
|
||
"把 QueryEngine 包成 @tool 并接入 LangGraph Agent",
|
||
],
|
||
"done": [
|
||
"能说清 RAG 七环节及每个环节的常见故障",
|
||
"能实现带查询改写 + 缓存 + 溯源的知识库检索工具",
|
||
"能区分普通 RAG 与 Agent-RAG 的适用场景",
|
||
],
|
||
},
|
||
{
|
||
"code": "04_mcp_protocol",
|
||
"title": "MCP 协议与工具接入",
|
||
"purpose": "理解 MCP 协议定位、最小实战把工具暴露成 MCP Server，以及 Agent 接入 MCP 客户端。",
|
||
"prerequisites": "已完成「01_tool_calling_ecosystem」+ 阶段三「02_langgraph_core」。",
|
||
"content": [
|
||
"为什么需要 MCP：N×M 集成爆炸 → 一套标准协议",
|
||
"核心概念：Host / Client / Server 与三大原语（tools / resources / prompts）",
|
||
"传输与部署：stdio（本地） / Streamable HTTP（远程）",
|
||
"最小实战：用 FastMCP 把工具工厂的工具暴露成 MCP Server",
|
||
"Agent 接入 MCP：LangChain / OpenAI Agents SDK",
|
||
],
|
||
"exercises": [
|
||
"用 FastMCP 把一个搜索工具暴露成 MCP Server",
|
||
"用 LangChain MCP 客户端接入并调用",
|
||
"对比 MCP 与工具工厂的分工",
|
||
],
|
||
"done": [
|
||
"能用 FastMCP 暴露一个最小 MCP Server",
|
||
"能解释 MCP 三大原语与安全边界",
|
||
"能判断什么场景该上 MCP、什么场景继续用工具工厂",
|
||
],
|
||
},
|
||
{
|
||
"code": "99_capstone_rag_tool_agent",
|
||
"title": "阶段四综合实战 · RAG 工具 Agent",
|
||
"purpose": "综合阶段四所有知识，搭一个支持知识库检索 + 工具调用的完整 Agent。",
|
||
"prerequisites": "已完成阶段四前 4 个小点。",
|
||
"content": [
|
||
"工具工厂 + @tool：所有外部能力统一封装",
|
||
"向量库 + RAG：把公司文档接入 Agent",
|
||
"kb_search + 改写 + 缓存 + 引用溯源",
|
||
"LangGraph 编排：模型自主决定何时检索",
|
||
],
|
||
"exercises": [
|
||
"实现一个支持「kb_search + 计算 + 联网」三件套的 Agent",
|
||
"为 kb_search 加查询改写 + 缓存 + 引用溯源",
|
||
"用 LangGraph 编排「思考 → 检索 → 汇总」完整链路",
|
||
],
|
||
"done": [
|
||
"能搭建一个企业内问应答的最小可用 Agent",
|
||
"能解释 RAG 与工具调用的边界与协作",
|
||
"能给出 Bad-case 的归因与修法",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
{
|
||
"code_dir": "005_phase5_advanced",
|
||
"phase_title": "阶段五 · 进阶技术",
|
||
"phase_doc_dir": "05-阶段五-进阶技术",
|
||
"phase_goal": (
|
||
"掌握多智能体协作、规划能力增强、记忆系统优化、Agent 评估与安全对齐，"
|
||
"让 Agent 从「能用」变成「可靠」。"
|
||
),
|
||
"topics": [
|
||
{
|
||
"code": "01_multi_agent_systems",
|
||
"title": "多智能体系统进阶",
|
||
"purpose": "掌握多智能体系统的四种模式（流水线 / 分层管控 / 辩论校验 / 黑板），能选型。",
|
||
"prerequisites": "已完成阶段三「02_langgraph_core」。",
|
||
"content": [
|
||
"流水线模式：每步一个 Agent，按顺序接力",
|
||
"分层管控：Supervisor 主管分发任务",
|
||
"辩论校验：两个 Agent 互相审核",
|
||
"黑板模式：共享状态空间，多 Agent 协同写入",
|
||
],
|
||
"exercises": [
|
||
"实现一个 Supervisor 主管 + 三个 Worker 的分层架构",
|
||
"实现一个「写 → 审 → 改」的辩论校验流水线",
|
||
"对比四种模式的代码复杂度与适用场景",
|
||
],
|
||
"done": [
|
||
"能区分四种多智能体模式的优劣",
|
||
"能用 LangGraph 实现 Supervisor 模式",
|
||
"能判断什么场景适合多智能体、什么场景单 Agent 就够",
|
||
],
|
||
},
|
||
{
|
||
"code": "02_planning_capability",
|
||
"title": "规划能力增强",
|
||
"purpose": "掌握子目标分解、任务图、Plan-and-Execute 进阶，让 Agent 能处理长周期任务。",
|
||
"prerequisites": "已完成阶段二「03_agent_paradigms」+ 阶段三「02_langgraph_core」。",
|
||
"content": [
|
||
"子目标分解：把复杂任务拆成可独立完成的子任务",
|
||
"任务图：子任务之间的依赖关系建模",
|
||
"Plan-and-Execute 进阶：先生成完整计划 + 每步验证 + 失败重规划",
|
||
"任务进度持久化：Checkpointer 与任务进度回溯",
|
||
],
|
||
"exercises": [
|
||
"实现一个「订机票 + 订酒店 + 排行程」的多步规划 Agent",
|
||
"为任务图加失败重规划（某步失败时让模型重新拆解）",
|
||
"用 Checkpointer 持久化任务进度，支持中断后续跑",
|
||
],
|
||
"done": [
|
||
"能实现子目标分解 + 任务图建模",
|
||
"能让 Agent 在长周期任务中失败重规划",
|
||
"能用 Checkpointer 持久化任务进度",
|
||
],
|
||
},
|
||
{
|
||
"code": "03_memory_system",
|
||
"title": "记忆系统优化",
|
||
"purpose": "掌握短期 / 工作 / 长期三层记忆的存储组合与读写策略。",
|
||
"prerequisites": "已完成阶段四「02_vector_db_and_memory」。",
|
||
"content": [
|
||
"短期记忆：当前会话上下文（Redis + TTL）",
|
||
"工作记忆：当前任务的中间态（Checkpointer）",
|
||
"长期记忆：跨会话持久化（向量库 + PG）",
|
||
"记忆读写策略：摘要压缩 / 重要度评分 / 自动归档",
|
||
],
|
||
"exercises": [
|
||
"实现一个三层记忆读写结合的 Agent",
|
||
"state_dict + Redis + 向量库的协同处理。",
|
||
"用重要度评分自动规划长期记忆的保留与剔除",
|
||
],
|
||
"done": [
|
||
"能区分三层记忆的职责与存储后端",
|
||
"能让 Agent 跨会话记住用户特征",
|
||
"能避免记忆爆炸（会期过期 / 重要度评分）",
|
||
],
|
||
},
|
||
{
|
||
"code": "04_agent_evaluation",
|
||
"title": "Agent 评估与评测",
|
||
"purpose": "掌握五大核心指标、LLM-as-judge、Ragas、LangSmith/Langfuse，构建回归测试闭环。",
|
||
"prerequisites": "已完成阶段三任意 Agent 综合实战。",
|
||
"content": [
|
||
"五大指标：任务成功率 / 工具调用准确率 / 步骤数 / 幻觉率 / 平均耗时",
|
||
"自建评测集：输入 + 期望要点（工具名 / 关键词 / 来源）",
|
||
"LLM-as-judge 三原则：裁判强 / 标准固定 / 抽人复核",
|
||
"Ragas：faithfulness / answer_relevancy / context_precision / context_recall",
|
||
"Bad-case 闭环：归类 → 修法 → 重跑 → 指标回升",
|
||
],
|
||
"exercises": [
|
||
"造一个 5 条用例的评测集并跑出五大指标",
|
||
"用 Ragas 评估一个 RAG Agent 的检索质量",
|
||
"接入 LangSmith 或 Langfuse 查看 trace 全链路",
|
||
],
|
||
"done": [
|
||
"能造评测集并跑出五大指标",
|
||
"能用 Ragas 拆解「检索 vs 生成」的锅",
|
||
"能用 Bad-case 闭环驱动迭代",
|
||
],
|
||
},
|
||
{
|
||
"code": "05_safety_and_alignment",
|
||
"title": "安全与对齐",
|
||
"purpose": "掌握 Agent 的注入防护、工具权限、输出审计、Human-in-the-loop 高危节点审批。",
|
||
"prerequisites": "已完成阶段四「01_tool_calling_ecosystem」。",
|
||
"content": [
|
||
"提示词注入：间接诱导 / 越权指令 / 身份混淆",
|
||
"工具权限：白名单 + 角色 + 代码层拦截",
|
||
"输出审计：危险动作必须可追溯、可回滚",
|
||
"Human-in-the-loop：高危节点 interrupt 审批",
|
||
],
|
||
"exercises": [
|
||
"为一个 Agent 写一个注入测试集（10 个 bad prompt）",
|
||
"为「转账」类工具加 Human-in-the-loop 审批",
|
||
"实现一个工具调用审计日志模块",
|
||
],
|
||
"done": [
|
||
"能识别主流的提示词注入攻击并防护",
|
||
"能设计高危工具的审批闸门",
|
||
"能写出可追溯的工具调用审计日志",
|
||
],
|
||
},
|
||
{
|
||
"code": "99_capstone_multi_agent_workflow",
|
||
"title": "阶段五综合实战 · 多智能体工作流 Agent",
|
||
"purpose": "综合阶段五所有能力，搭建一个多智能体工作流 Agent，覆盖分工协作 / 断点恢复 / 记忆 / 评估 / 注入检测。",
|
||
"prerequisites": "已完成阶段五前 5 个小点。",
|
||
"content": [
|
||
"Supervisor 主管 + 多 Worker 分工",
|
||
"Checkpointer 持久化 + 断点恢复",
|
||
"三层记忆协同（Redis + Qdrant + PG）",
|
||
"Ragas 评估 + Bad-case 闭环",
|
||
"注入检测 + Human-in-the-loop 审批",
|
||
],
|
||
"exercises": [
|
||
"实现一个「调研 → 写作 → 评审 → 发布」的四 Agent 流水线",
|
||
"为流水线加入注入检测与人手审批闸门",
|
||
"为流水线接 Ragas 评估 + LangSmith 追踪",
|
||
],
|
||
"done": [
|
||
"能搭建多智能体工作流并验证分工",
|
||
"能接入评估与安全防护",
|
||
"能说清多智能体 vs 单 Agent 的取舍",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
{
|
||
"code_dir": "006_phase6_vertical_apps",
|
||
"phase_title": "阶段六 · 垂直领域 Agent 落地实践",
|
||
"phase_doc_dir": "06-阶段六-垂直领域Agent落地实践",
|
||
"phase_goal": (
|
||
"把 Agent 落到真实垂直领域：代码开发、数据分析、内容创作、智能客服、办公自动化，"
|
||
"每领域都有独立的能力栈与陷阱。"
|
||
),
|
||
"topics": [
|
||
{
|
||
"code": "01_coding_agent",
|
||
"title": "代码开发 Agent",
|
||
"purpose": "掌握仓库级检索 / AST 分块 / 多文件读写 / 沙箱执行，能在真实代码库里改代码。",
|
||
"prerequisites": "已完成阶段四「03_rag_technique」+ 阶段三「02_langgraph_core」。",
|
||
"content": [
|
||
"仓库级检索：全库建索引（按函数 / 类切块）",
|
||
"AST 分块：`ast` 模块按函数 / 类边界切",
|
||
"多文件读写：diff 预览 + 限根目录",
|
||
"长上下文管理：符号表常驻 + 按需拉取",
|
||
"沙箱执行：Docker 隔离跑生成代码",
|
||
],
|
||
"exercises": [
|
||
"用 AST 把一个 Python 文件按函数切块",
|
||
"实现一个仓库符号表（函数名 → 文件/行号）",
|
||
"实现「定位 → 改 → 跑测试」三步 Agent",
|
||
],
|
||
"done": [
|
||
"能用 AST 分块实现仓库级检索",
|
||
"能管理多文件 diff 与根目录限制",
|
||
"能在沙箱中安全执行 Agent 生成的代码",
|
||
],
|
||
},
|
||
{
|
||
"code": "02_data_analysis_agent",
|
||
"title": "数据分析 Agent",
|
||
"purpose": "掌握 Text-to-SQL / Schema Prompt / 五道防线，能把自然语言问题翻译成 SQL 并出图。",
|
||
"prerequisites": "已完成阶段四「03_rag_technique」+ 阶段一「04_python_core_toolkits」（pandas）。",
|
||
"content": [
|
||
"Text-to-SQL：Schema Prompt 是第一杠杆",
|
||
"五道防线：只读账号 / SQL 白名单 / 参数化 / 结果校验 / 报错自修正",
|
||
"语义层：业务口径沉淀到中间表 / 视图",
|
||
"图表工具：把查询结果转可视化",
|
||
],
|
||
"exercises": [
|
||
"写一份高质量的 Schema Prompt",
|
||
"实现五道防线的 SQL 安全验证",
|
||
"让 Agent 自动选择图表类型（柱 / 折线 / 饼）",
|
||
],
|
||
"done": [
|
||
"能用 Schema Prompt 显著提高 SQL 准确率",
|
||
"能落地五道防线防止 SQL 注入与越权",
|
||
"能让 Agent 把查询结果转成可视化",
|
||
],
|
||
},
|
||
{
|
||
"code": "03_content_creation_agent",
|
||
"title": "内容创作 Agent",
|
||
"purpose": "掌握多 Agent 写作流水线、风格控制、人工反馈机制。",
|
||
"prerequisites": "已完成阶段三「02_langgraph_core」+ 阶段五「01_multi_agent_systems」。",
|
||
"content": [
|
||
"流水线：策划 → 写作 → 评审 → 校对",
|
||
"风格控制：Few-shot + System Prompt 约束",
|
||
"人工反馈：Human-in-the-loop 评审 + 编辑",
|
||
"多模态扩展：图片 / 表格 / 引用自动配齐",
|
||
],
|
||
"exercises": [
|
||
"搭一个「策划 + 写作 + 评审」三人组",
|
||
"加入风格 Few-shot 让 Agent 稳定产出某种文风",
|
||
"接入 Human-in-the-loop 审批闸门",
|
||
],
|
||
"done": [
|
||
"能搭多 Agent 内容流水线",
|
||
"能用风格控制稳定输出",
|
||
"能接入人工反馈闭环",
|
||
],
|
||
},
|
||
{
|
||
"code": "04_customer_service_agent",
|
||
"title": "智能客服与运维 Agent",
|
||
"purpose": "掌握工单 / 知识库 / 多轮上下文 / 升级人工的全链路。",
|
||
"prerequisites": "已完成阶段四「03_rag_technique」+ 阶段三「02_langgraph_core」。",
|
||
"content": [
|
||
"工单系统集成：开单 / 关单 / 升级流转",
|
||
"知识库检索：常见问题自动答",
|
||
"多轮上下文：会话状态持久化",
|
||
"升级人工：识别兜不住的问题并转人工",
|
||
"SLA 与响应时效监控",
|
||
],
|
||
"exercises": [
|
||
"实现一个支持多轮对话 + 知识库的客服 Agent",
|
||
"为 Agent 加工单开/关工具",
|
||
"实现「识别兜不住 → 升级人工」逻辑",
|
||
],
|
||
"done": [
|
||
"能搭多轮对话 + 知识库的客服 Agent",
|
||
"能集成工单系统",
|
||
"能识别兜不住的问题并升级人工",
|
||
],
|
||
},
|
||
{
|
||
"code": "05_office_automation_agent",
|
||
"title": "办公自动化 Agent（Agent + RPA）",
|
||
"purpose": "掌握 Agent + RPA 协作、流程编排、审批中断、幂等防重发。",
|
||
"prerequisites": "已完成阶段三「02_langgraph_core」+ 阶段五「05_safety_and_alignment」。",
|
||
"content": [
|
||
"Agent 动脑 vs RPA 动手的分工",
|
||
"流程编排：串行 + 审批 + 分支",
|
||
"审批中断：LangGraph interrupt",
|
||
"幂等防重发：不幂等操作必须用幂等键",
|
||
],
|
||
"exercises": [
|
||
"实现一个「报销邮件 → 提取要素 → 校验 → 审批 → 回执」流水线",
|
||
"为金额超限分支加 Human-in-the-loop 审批",
|
||
"为不幂等操作（发券）设计防重发机制",
|
||
],
|
||
"done": [
|
||
"能搭 Agent + RPA 协作的办公自动化流水线",
|
||
"能用 interrupt 实现审批中断",
|
||
"能为不幂等操作设计幂等键",
|
||
],
|
||
},
|
||
{
|
||
"code": "99_capstone_data_analysis_agent",
|
||
"title": "阶段六综合实战 · 数据分析 Agent",
|
||
"purpose": "搭建一个支持自然语言查询 + 自动出图 + 报告输出的数据分析 Agent。",
|
||
"prerequisites": "已完成阶段六前 5 个小点。",
|
||
"content": [
|
||
"Schema 元数据自动接入",
|
||
"五道防线保障 SQL 安全",
|
||
"自动出图（柱 / 折线 / 饼）",
|
||
"自动写报告（结论 + 数据 + 引用）",
|
||
],
|
||
"exercises": [
|
||
"为「上季度北京区域销售」自动生成 SQL + 柱状图",
|
||
"为 Agent 加自动报告生成（结论 + 数据）",
|
||
"用 Ragas 评估 Agent 的查询准确率",
|
||
],
|
||
"done": [
|
||
"能搭支持自然语言查询 + 自动出图的数据分析 Agent",
|
||
"能解释五道防线的关键作用",
|
||
"能评估 Agent 的查询质量",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
{
|
||
"code_dir": "007_phase7_engineering",
|
||
"phase_title": "阶段七 · 工程化部署与运维",
|
||
"phase_doc_dir": "07-阶段七-工程化部署与运维",
|
||
"phase_goal": (
|
||
"把 Agent 从「我本机能跑」扩展到「生产可扩、长期可观测」，"
|
||
"覆盖四层架构、状态持久化、容错降级、Docker / K8s 部署、监控告警与上线迭代闭环。"
|
||
),
|
||
"topics": [
|
||
{
|
||
"code": "01_agent_engineering_best_practices",
|
||
"title": "Agent 工程化最佳实践",
|
||
"purpose": "掌握四层架构（接入 / 编排 / 工具 / 存储）、状态持久化、重试·降级·熔断、成本优化。",
|
||
"prerequisites": "已完成阶段三「02_langgraph_core」+ 阶段一「08_software_engineering_basics」。",
|
||
"content": [
|
||
"四层架构：API 接入层 / Agent 编排层 / 工具服务层 / 存储层",
|
||
"插件化工具注册中心：新增工具零改动核心代码",
|
||
"状态持久化：临时 vs 持久 / Checkpointer 选 PG",
|
||
"三大保护：重试（救抖动）/ 降级（兜底）/ 熔断（防雪崩）",
|
||
"成本优化：Token 统计 / 语义缓存 / 步骤限流",
|
||
],
|
||
"exercises": [
|
||
"按四层架构搭一个最小 Agent 服务",
|
||
"为外呼工具加重试 + 降级 + 熔断三件套",
|
||
"实现 Token 统计 + 语义缓存 + 步骤限流",
|
||
],
|
||
"done": [
|
||
"能说清四层架构与各自职责",
|
||
"能实现熔断 + 降级 + Token 统计 + 步骤限流的工程化骨架",
|
||
"能判断一个状态该不该持久化",
|
||
],
|
||
},
|
||
{
|
||
"code": "02_deployment_and_scaling",
|
||
"title": "部署与伸缩（Docker / Compose / K8s）",
|
||
"purpose": "掌握容器化、Compose 一键全家桶、K8s 部署、HPA、任务队列、优雅停机。",
|
||
"prerequisites": "已完成「01_agent_engineering_best_practices」+ 阶段一「08_software_engineering_basics」。",
|
||
"content": [
|
||
"Dockerfile 多阶段构建 / 镜像分层缓存",
|
||
"docker-compose：app + worker + Redis + PG + Qdrant 全家桶",
|
||
"K8s：Deployment + Service + HPA",
|
||
"任务队列：API 入队即返回 / worker 消费（arq）",
|
||
"优雅停机：SIGTERM → 停接新请求 → 等存量 → 落盘 → 退出",
|
||
],
|
||
"exercises": [
|
||
"用 docker-compose 拉起 app + worker + Redis + PG + Qdrant",
|
||
"为长任务 Agent 接 arq 任务队列",
|
||
"实现优雅停机（preStop hook + 状态持久化）",
|
||
],
|
||
"done": [
|
||
"能用 docker-compose 拉起 Agent 全栈",
|
||
"能用 K8s 部署并配置 HPA",
|
||
"能实现优雅停机",
|
||
],
|
||
},
|
||
{
|
||
"code": "03_observability_and_ops",
|
||
"title": "监控与运维",
|
||
"purpose": "掌握三大监控支柱（Logs / Metrics / Traces）、黄金四指标、告警分级、上线迭代闭环。",
|
||
"prerequisites": "已完成「01_agent_engineering_best_practices」。",
|
||
"content": [
|
||
"三大支柱：Logs（明细） / Metrics（聚合数值） / Traces（跨节点路径）",
|
||
"黄金四指标：P95 延迟 / QPS / LLM 调用失败率 / token 消耗速率",
|
||
"Agent 特有的第五维度：成本指标",
|
||
"告警分级：P0 / P1 / P2 + SLO 反推阈值",
|
||
"上线迭代闭环：Bad-case 收集 → 归类 → 修复 → 回归",
|
||
],
|
||
"exercises": [
|
||
"用 loguru + OpenTelemetry 打全链路 trace_id",
|
||
"为 Agent 服务暴露 Prometheus 指标",
|
||
"搭一个 Bad-case 队列并跑通归类 → 修复 → 回归闭环",
|
||
],
|
||
"done": [
|
||
"能搭起 Logs / Metrics / Traces 三大支柱",
|
||
"能用 P95 / QPS / 失败率 / token 消耗四项指标定告警阈值",
|
||
"能跑通 Bad-case 闭环",
|
||
],
|
||
},
|
||
{
|
||
"code": "99_capstone_monitoring_agent",
|
||
"title": "阶段七综合实战 · 监控与运维 Agent",
|
||
"purpose": "搭一个覆盖三大支柱、黄金四指标、告警分级、Bad-case 闭环的完整监控 Agent。",
|
||
"prerequisites": "已完成阶段七前 3 个小点。",
|
||
"content": [
|
||
"三大支柱：loguru + Prometheus + OpenTelemetry",
|
||
"黄金四指标 + 成本指标",
|
||
"告警分级：SLO 反推阈值 + 分级响应",
|
||
"Bad-case 队列：从告警到归类到修复到回归",
|
||
],
|
||
"exercises": [
|
||
"为已有 Agent 服务接入三大支柱",
|
||
"为 P95 延迟 / 失败率 / token 消耗设分级告警",
|
||
"搭一个 Bad-case 队列并跑通归类 → 修复 → 回归",
|
||
],
|
||
"done": [
|
||
"能搭建生产级 Agent 监控体系",
|
||
"能用 SLO 反推告警阈值",
|
||
"能用 Bad-case 闭环驱动长期迭代",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
{
|
||
"code_dir": "008_phase8_projects",
|
||
"phase_title": "阶段八 · 实战项目路线（Level 1~5）",
|
||
"phase_doc_dir": "08-阶段八-实战项目路线",
|
||
"phase_goal": (
|
||
"通过 Level 1~5 五级递进项目，把前面所有阶段的能力串成完整的、可上线的端到端 Agent 系统。"
|
||
),
|
||
"topics": [
|
||
{
|
||
"code": "01_level1_react_qa_agent",
|
||
"title": "Level 1 · ReAct 智能问答 Agent",
|
||
"purpose": "最小可行 Agent：单智能体 + 1~2 个工具，能跑通 ReAct 主循环。",
|
||
"prerequisites": "已完成阶段二 + 阶段三「01_langchain_basics」。",
|
||
"content": [
|
||
"单智能体 + ReAct 主循环",
|
||
"1~2 个工具（如搜索 + 计算）",
|
||
"FastAPI 暴露 + Streamlit 前端",
|
||
"Mock LLM 演示，不需要真实 API Key",
|
||
],
|
||
"exercises": [
|
||
"搭一个支持「查 + 算」二语工具的 ReAct Agent",
|
||
"用 FastAPI + SSE 暴露为 Web 服务",
|
||
"用 Streamlit 做一个简单聊天前端",
|
||
],
|
||
"done": [
|
||
"能用 ReAct 跑通最小 Agent",
|
||
"能用 FastAPI + Streamlit 暴露为 Web",
|
||
"能解释主循环的每一步",
|
||
],
|
||
},
|
||
{
|
||
"code": "02_level2_rag_knowledge_agent",
|
||
"title": "Level 2 · 知识库 RAG Agent",
|
||
"purpose": "在 Level 1 基础上加知识库检索能力，能基于 RAG 做企业内问答。",
|
||
"prerequisites": "已完成 Level 1 + 阶段四「03_rag_technique」。",
|
||
"content": [
|
||
"向量库接入（Chroma / Qdrant）",
|
||
"文档加载 → 清洗 → 分块 → 向量化",
|
||
"RAG 检索 + 引用溯源",
|
||
"Agent-RAG：把 kb_search 接入主循环",
|
||
],
|
||
"exercises": [
|
||
"为 Agent 接入一份公司制度文档知识库",
|
||
"实现带引用溯源的 RAG 问答",
|
||
"对比普通 RAG vs Agent-RAG 的差异",
|
||
],
|
||
"done": [
|
||
"能搭一个支持 RAG 的 Agent",
|
||
"能解释 RAG 七环节 + 每环节的故障排查",
|
||
"能区分普通 RAG vs Agent-RAG",
|
||
],
|
||
},
|
||
{
|
||
"code": "03_level3_multi_role_creator",
|
||
"title": "Level 3 · 多角色内容创作团队",
|
||
"purpose": "在 Level 2 基础上做多 Agent 协作，覆盖内容创作全流程。",
|
||
"prerequisites": "已完成 Level 2 + 阶段五「01_multi_agent_systems」。",
|
||
"content": [
|
||
"角色化分工：策划 / 写作 / 评审 / 校对",
|
||
"多智能体协作（流水线 / 分层管控）",
|
||
"风格控制 + Few-shot",
|
||
"内容追踪 / 反馈 / 迭代",
|
||
],
|
||
"exercises": [
|
||
"搭一个「策划 + 写作 + 评审」三人组",
|
||
"为流水线加入风格 Few-shot",
|
||
"用 Ragas 评估内容质量",
|
||
],
|
||
"done": [
|
||
"能搭多角色内容创作流水线",
|
||
"能用风格控制稳定输出",
|
||
"能用评估闭环迭代内容质量",
|
||
],
|
||
},
|
||
{
|
||
"code": "04_level4_data_analysis_agent",
|
||
"title": "Level 4 · 数据分析 Agent",
|
||
"purpose": "在 Level 3 基础上加 Text-to-SQL，让 Agent 能基于数据库做交互式查询。",
|
||
"prerequisites": "已完成 Level 3 + 阶段六「02_data_analysis_agent」。",
|
||
"content": [
|
||
"Schema Prompt 自动生成",
|
||
"五道防线保障 SQL 安全",
|
||
"查询结果自动可视化（柱 / 折线 / 饼）",
|
||
"自动写报告（结论 + 数据 + 引用）",
|
||
],
|
||
"exercises": [
|
||
"为一份示例数据库写 Schema Prompt",
|
||
"实现五道防线的 SQL 安全验证",
|
||
"让 Agent 自动选择图表并出报告",
|
||
],
|
||
"done": [
|
||
"能搭一个支持自然语言查询的数据分析 Agent",
|
||
"能落地五道防线",
|
||
"能让 Agent 自动出图与报告",
|
||
],
|
||
},
|
||
{
|
||
"code": "05_level5_enterprise_cs_agent",
|
||
"title": "Level 5 · 企业智能客服 Agent",
|
||
"purpose": "完整的企业级客服系统，覆盖多租户 / 工单 / 知识库 / 升级人工的全链路。",
|
||
"prerequisites": "已完成 Level 4 + 阶段六「04_customer_service_agent」+ 阶段七前 3 个小点。",
|
||
"content": [
|
||
"多租户隔离：tenant_id 索引 / 检索过滤",
|
||
"工单系统集成：开 / 关 / 升级流转",
|
||
"知识库 + RAG + 多轮上下文",
|
||
"升级人工 + Human-in-the-loop 审批",
|
||
"全链路可观测（LangSmith / Langfuse）",
|
||
],
|
||
"exercises": [
|
||
"搭一个支持多租户的客服 Agent",
|
||
"为 Agent 接入工单系统",
|
||
"为 Agent 接入 LangSmith / Langfuse",
|
||
"为 Agent 加 SLA 与响应时效监控",
|
||
],
|
||
"done": [
|
||
"能搭企业级智能客服系统",
|
||
"能落地多租户 + 工单 + 升级人工",
|
||
"能用全链路可观测驱动迭代",
|
||
],
|
||
},
|
||
{
|
||
"code": "99_capstone_project_roadmap",
|
||
"title": "阶段八综合实战 · 五级项目路线导航",
|
||
"purpose": "用代码 / CLI 把 Level 1~5 五级项目的递进关系、能力覆盖、进度跟踪、排期映射串起来。",
|
||
"prerequisites": "已完成阶段八前 5 个 Level。",
|
||
"content": [
|
||
"五级项目递进关系图",
|
||
"能力覆盖矩阵（每级覆盖了哪些阶段能力）",
|
||
"进度跟踪：每级的「自检」与「达成标准」",
|
||
"排期映射：每级与 16 周学习计划的对应",
|
||
],
|
||
"exercises": [
|
||
"用 Python 写一个项目路线导航器（CLI / Web）",
|
||
"为导航器加进度跟踪（哪些 Level 已完成）",
|
||
"为导航器加排期映射（剩余多少周）",
|
||
],
|
||
"done": [
|
||
"能用代码呈现五级项目的递进关系",
|
||
"能用工具跟踪学习进度",
|
||
"能用工具评估学习投入产出",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
]
|
||
|
||
|
||
# ---------------------------------------------------------------------------
|
||
# 渲染单个 README
|
||
# ---------------------------------------------------------------------------
|
||
|
||
def render_readme(phase: dict, topic: dict) -> str:
|
||
"""根据 phase + topic 渲染一个 README.md 的内容。"""
|
||
phase_title = phase["phase_title"]
|
||
phase_doc_dir = phase["phase_doc_dir"]
|
||
title = topic["title"]
|
||
purpose = topic["purpose"]
|
||
prereq = topic["prerequisites"]
|
||
content = topic["content"]
|
||
exercises = topic["exercises"]
|
||
done = topic["done"]
|
||
code = topic["code"]
|
||
|
||
# 推断 doc 文件名（去掉中文序号）
|
||
# 比如 "01-LangChain基础.md" 会映射到一个 md 文件
|
||
# 由于 docs 实际文件名包含中文，这里直接给出相对路径让用户自查
|
||
# 用「同目录 + 第 N 篇」的语义提示
|
||
md_link = f"[`docs/{phase_doc_dir}/`](../../docs/{phase_doc_dir}/)（按目录名里的 `第 X 篇` 对应）"
|
||
|
||
lines: list[str] = []
|
||
lines.append(f"# {title}")
|
||
lines.append("")
|
||
lines.append(f"> 所属：{phase_title}")
|
||
lines.append(f"> 目标：{purpose}")
|
||
lines.append("")
|
||
lines.append("---")
|
||
lines.append("")
|
||
lines.append("## 📌 学习目的")
|
||
lines.append("")
|
||
lines.append(purpose)
|
||
lines.append("")
|
||
lines.append("## ✅ 学习要求（前置条件）")
|
||
lines.append("")
|
||
lines.append(prereq)
|
||
lines.append("")
|
||
lines.append("## 📚 主要学习内容")
|
||
lines.append("")
|
||
for item in content:
|
||
lines.append(f"- {item}")
|
||
lines.append("")
|
||
lines.append("## 📖 对应 docs")
|
||
lines.append("")
|
||
lines.append(f"- 目录：{md_link}")
|
||
lines.append("- 在 docs 目录里找到对应的小点 markdown 文件阅读详细理论。")
|
||
lines.append("")
|
||
lines.append("## 🛠️ 建议练习")
|
||
lines.append("")
|
||
for ex in exercises:
|
||
lines.append(f"- [ ] {ex}")
|
||
lines.append("")
|
||
lines.append("## 🏁 完成后达成标准")
|
||
lines.append("")
|
||
for d in done:
|
||
lines.append(f"- [ ] {d}")
|
||
lines.append("")
|
||
lines.append("---")
|
||
lines.append("")
|
||
lines.append("## 🚀 运行提示")
|
||
lines.append("")
|
||
lines.append("```bash")
|
||
lines.append(f"# 激活根目录的虚拟环境")
|
||
lines.append(f"cd /Users/jack/source/Demo/py/demo_python_agent")
|
||
lines.append(f"source .venv/bin/activate # 或直接用 uv run ...")
|
||
lines.append("")
|
||
lines.append(f"# 进入本章目录")
|
||
lines.append(f"cd code/{phase['code_dir']}/{code}")
|
||
lines.append("")
|
||
lines.append(f"# 跑你的练习文件")
|
||
lines.append(f"uv run python your_exercise.py")
|
||
lines.append("```")
|
||
lines.append("")
|
||
return "\n".join(lines)
|
||
|
||
|
||
# ---------------------------------------------------------------------------
|
||
# 主流程
|
||
# ---------------------------------------------------------------------------
|
||
|
||
def main() -> None:
|
||
created = 0
|
||
skipped = 0
|
||
for phase in PHASES:
|
||
phase_dir = CODE_ROOT / phase["code_dir"]
|
||
if not phase_dir.is_dir():
|
||
print(f"[skip] phase dir missing: {phase_dir}")
|
||
continue
|
||
for topic in phase["topics"]:
|
||
topic_dir = phase_dir / topic["code"]
|
||
if not topic_dir.is_dir():
|
||
print(f"[skip] topic dir missing: {topic_dir}")
|
||
continue
|
||
readme = topic_dir / "README.md"
|
||
if readme.exists() and readme.stat().st_size > 0:
|
||
skipped += 1
|
||
continue
|
||
readme.write_text(render_readme(phase, topic), encoding="utf-8")
|
||
created += 1
|
||
print(f"[ok] {readme.relative_to(CODE_ROOT.parent)}")
|
||
print()
|
||
print(f"created={created}, skipped={skipped}")
|
||
|
||
|
||
if __name__ == "__main__":
|
||
main() |