增加每章节 README 文件

2026-09-22 15:57:59 +08:00
parent 8e86665096
commit 9445061c76
49 changed files with 3815 additions and 6 deletions
@@ -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
+```
@@ -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
+```
@@ -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
+```
@@ -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
+```