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