""" 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()