增加每章节 README 文件
This commit is contained in:
@@ -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
|
||||
```
|
||||
@@ -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
|
||||
```
|
||||
@@ -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
|
||||
```
|
||||
@@ -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
|
||||
```
|
||||
@@ -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
|
||||
```
|
||||
@@ -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
|
||||
```
|
||||
@@ -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
|
||||
```
|
||||
@@ -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
|
||||
```
|
||||
Reference in New Issue
Block a user