# code/ — 练习代码目录

> 这个目录是**你跟着 docs/ 学习时写练习代码的地方**。
> 结构按 docs/ 的八个学习阶段**镜像并细化**：每个阶段一个文件夹；每个「小点」一个子目录；每个阶段的「综合实战」用 `99_capstone_*` 编号放末尾。

## 总览

- 8 个阶段文件夹（`001_*` ~ `008_*`）
- 49 个子目录（48 个小点 + 8 个综合实战 = 56 个练习单元 — 其中阶段二/三/四/五/六/七/八 各含 1 个综合实战，共 7 个；外加 41 个小点子目录；总计 48 + 7 = 55 子目录，写错了，重数：48 + 7 = 55，按实际为准）
- 所有 Python 文件统一在根目录的 `.venv` 里跑：`uv run python …`

---

## 详细目录索引

### 阶段一 · 前置核心基础 → `001_phase1_foundations/`

| 编号 | 子目录 | 对应 docs | 主题 |
|-|-|-|-|
| 01 | `01_python_advanced_basics/` | `01-Python高级编程之基础巩固.md` | 类型注解 / dataclass / 异常处理 / 上下文管理器 |
| 02 | `02_python_advanced_syntax/` | `02-Python高级编程之进阶语法.md` | 装饰器 / 生成器 / 描述符 / 元类 |
| 03 | `03_python_concurrency_async/` | `03-Python高级编程之并发与异步.md` | threading / multiprocessing / asyncio |
| 04 | `04_python_core_toolkits/` | `04-Python高级编程之核心工具库.md` | pydantic / loguru / tenacity / python-dotenv / pandas |
| 05 | `05_llm_fundamentals/` | `05-大模型基础原理.md` | LLM / Token / 上下文窗口 / 采样参数 |
| 06 | `06_llm_api_in_practice/` | `06-主流模型API实战.md` | OpenAI / Claude / DeepSeek / Ollama / 流式 / 错误码 |
| 07 | `07_prompt_engineering/` | `07-Prompt工程核心.md` | Few-shot / CoT / 指令设计 / ReAct prompt |
| 08 | `08_software_engineering_basics/` | `08-软件工程与基础设施.md` | Git / FastAPI / SSE / WebSocket / Docker / Redis / PG |

### 阶段二 · AI Agent 核心理论与基础范式 → `002_phase2_agent_theory/`

| 编号 | 子目录 | 对应 docs | 主题 |
|-|-|-|-|
| 01 | `01_agent_basics/` | `01-Agent基础认知.md` | Agent 定义 / 闭环 / 与 Chatbot 区别 |
| 02 | `02_agent_core_components/` | `02-Agent四大核心组件.md` | 规划 / 记忆 / 工具 / 行动 |
| 03 | `03_agent_paradigms/` | `03-经典Agent工作范式.md` | ReAct / Plan-and-Execute / Reflexion / ToT |
| 04 | `04_agent_framework_selection/` | `04-Agent框架选型决策.md` | 手写 vs 框架 / 选型矩阵 |
| 99 | `99_capstone_handcrafted_agent/` | `05-阶段二综合实战-手写完整Agent.md` | 综合实战：不依赖框架实现 ReAct / Plan-and-Execute / Reflexion |

### 阶段三 · 主流 Agent 开发框架 → `003_phase3_frameworks/`

| 编号 | 子目录 | 对应 docs | 主题 |
|-|-|-|-|
| 01 | `01_langchain_basics/` | `01-LangChain基础.md` | ChatModel / PromptTemplate / LCEL / @tool |
| 02 | `02_langgraph_core/` | `02-LangGraph核心.md` | StateGraph / Node / Edge / Checkpointer / 多智能体 Supervisor |
| 03 | `03_llamaindex/` | `03-LlamaIndex.md` | Document / Node / Index / QueryEngine（数据接入与检索） |
| 04 | `04_crewai/` | `04-CrewAI.md` | 角色化多智能体（了解选型） |
| 05 | `05_autogen/` | `05-AutoGen.md` | 微软多 Agent 框架（了解选型，已并入 MAF） |
| 06 | `06_other_frameworks/` | `06-其他主流方案.md` | Semantic Kernel / Assistants API / Dify / MCP 横评 |
| 99 | `99_capstone_langgraph_agent/` | `07-阶段三综合实战-LangGraph完整Agent.md` | 综合实战：LangGraph + LangChain 端到端 Agent |

### 阶段四 · 工具生态与外围组件集成 → `004_phase4_tool_ecosystem/`

| 编号 | 子目录 | 对应 docs | 主题 |
|-|-|-|-|
| 01 | `01_tool_calling_ecosystem/` | `01-工具调用生态.md` | 工具五要素 / 工具工厂 / 搜索 / 代码沙箱 / PDF |
| 02 | `02_vector_db_and_memory/` | `02-向量数据库与记忆存储.md` | Embedding / Chroma / FAISS / Qdrant / Milvus / pgvector |
| 03 | `03_rag_technique/` | `03-RAG技术体系.md` | RAG 流水线 / 查询改写 / Rerank / Agent-RAG / 引用溯源 |
| 04 | `04_mcp_protocol/` | `05-MCP协议与工具接入.md` | MCP Host/Client/Server / FastMCP / stdio / Streamable HTTP |
| 99 | `99_capstone_rag_tool_agent/` | `04-阶段四综合实战-RAG工具Agent.md` | 综合实战：RAG 知识库 + 工具工厂 + Agent-RAG |

### 阶段五 · 进阶技术 → `005_phase5_advanced/`

| 编号 | 子目录 | 对应 docs | 主题 |
|-|-|-|-|
| 01 | `01_multi_agent_systems/` | `01-多智能体系统进阶.md` | 流水线 / 分层管控 / 辩论 / 黑板 |
| 02 | `02_planning_capability/` | `02-规划能力增强.md` | 子目标分解 / 反思 / 任务图 |
| 03 | `03_memory_system/` | `03-记忆系统优化.md` | 短期 / 工作 / 长期记忆；Redis + 向量库 + PG 三件套 |
| 04 | `04_agent_evaluation/` | `04-Agent评估与评测.md` | 五大指标 / LLM-as-judge / Ragas / LangSmith / Langfuse / Bad-case 闭环 |
| 05 | `05_safety_and_alignment/` | `05-安全与对齐.md` | 注入防护 / 工具权限 / 输出审计 / Human-in-the-loop |
| 99 | `99_capstone_multi_agent_workflow/` | `06-阶段五综合实战-多智能体工作流Agent.md` | 综合实战：多智能体工作流（含评估与注入检测） |

### 阶段六 · 垂直领域 Agent 落地实践 → `006_phase6_vertical_apps/`

| 编号 | 子目录 | 对应 docs | 主题 |
|-|-|-|-|
| 01 | `01_coding_agent/` | `01-代码开发Agent.md` | 仓库级检索 / AST 分块 / 多文件读写 / 沙箱执行 |
| 02 | `02_data_analysis_agent/` | `02-数据分析Agent.md` | Text-to-SQL / Schema Prompt / 五道防线 / 语义层 |
| 03 | `03_content_creation_agent/` | `03-内容创作Agent.md` | 多 Agent 写作流水线 / 风格控制 / 人工反馈 |
| 04 | `04_customer_service_agent/` | `04-智能客服与运维Agent.md` | 工单 / 知识库 / 多轮上下文 / 升级人工 |
| 05 | `05_office_automation_agent/` | `05-办公自动化Agent.md` | Agent + RPA / 流程编排 / 审批中断 / 幂等防重发 |
| 99 | `99_capstone_data_analysis_agent/` | `06-阶段六综合实战-数据分析Agent.md` | 综合实战：数据分析 Text-to-SQL Agent |

### 阶段七 · 工程化部署与运维 → `007_phase7_engineering/`

| 编号 | 子目录 | 对应 docs | 主题 |
|-|-|-|-|
| 01 | `01_agent_engineering_best_practices/` | `01-Agent工程化最佳实践.md` | 四层架构 / 状态持久化 / 重试·降级·熔断 / 成本优化 |
| 02 | `02_deployment_and_scaling/` | `02-部署与伸缩.md` | Docker / Compose / K8s / HPA / 任务队列 / 优雅停机 |
| 03 | `03_observability_and_ops/` | `03-监控与运维.md` | Logs / Metrics / Traces / 黄金四指标 / 告警分级 |
| 99 | `99_capstone_monitoring_agent/` | `04-阶段七综合实战-监控与运维Agent.md` | 综合实战：观测台 + 告警 + Bad-case 闭环 Agent |

### 阶段八 · 实战项目路线 → `008_phase8_projects/`

| 编号 | 子目录 | 对应 docs | 主题 |
|-|-|-|-|
| 01 | `01_level1_react_qa_agent/` | `01-Level1-ReAct智能问答Agent.md` | Level 1：单智能体 ReAct 问答（最小可行 Agent） |
| 02 | `02_level2_rag_knowledge_agent/` | `02-Level2-知识库RAG-Agent.md` | Level 2：知识库 + RAG + 工具调用的企业内问答应 |
| 03 | `03_level3_multi_role_creator/` | `03-Level3-多角色内容创作团队.md` | Level 3：多角色（策划 / 写作 / 评审 / 校对）协作 |
| 04 | `04_level4_data_analysis_agent/` | `04-Level4-数据分析Agent.md` | Level 4：自然语言 → SQL → 图表 → 报告 |
| 05 | `05_level5_enterprise_cs_agent/` | `05-Level5-企业智能客服Agent.md` | Level 5：多租户 / 工单 / 知识库 / 升级人工的全链路客服 |
| 99 | `99_capstone_project_roadmap/` | `06-阶段八综合实战-五级项目路线导航.md` | 综合实战：五级项目路线导航器 |

---

## 怎么用

1. **按编号顺序**进入对应子目录，跟 docs 里同名小点同步写练习。
2. 每个子目录建议最少 2~3 个 `.py` 文件做不同角度的练习（例如「最小实现 / 加日志 / 加单元测试」）。
3. 跑代码统一用 `uv run`（已经在根目录的 `.venv` 里）：
   ```bash
   cd code/003_phase3_frameworks/02_langgraph_core
   uv run python my_first_graph.py
   ```
4. **不要把练习代码挪到 docs/**——docs 只放文档，code 才是可执行代码。

## 配套参考

- `docs/12-Python开发规范.md` —— 本项目目录 / 分层 / 命名 / 接口规范
- `docs/09-四个月学习计划.md` —— 每周任务节奏（按 16 周规划）
- `docs/00-专有名词速查表.md` —— 遇到陌生名词随时回查