cookbook-audit

# Cookbook 审计

## 指令

使用 `style_guide.md` 中的指南和评分标准审查请求的 Cookbook notebook。根据评分指南提供评分，并给出改进 cookbook 的建议。

样式指南提供了详细的模板和示例，涵盖：
- 以问题为导向的引言，包含最终学习目标（TLOs）和促成学习目标（ELOs）
- 前置条件和设置模式
- 核心内容结构
- 呼应学习目标的结论

**重要**：在进行审计之前，请务必先阅读 `style_guide.md`。样式指南包含可参考的标准模板以及好/坏示例。

## 工作流程

按照以下步骤进行全面审计：

1. **阅读样式指南**：首先查看 `style_guide.md` 以了解当前的最佳实践
2. **确定 notebook**：如果未提供，请询问用户路径
3. **运行自动检查**：使用 `python3 validate_notebook.py <path>` 捕捉技术问题并生成 markdown
   - 该脚本会自动运行 detect-secrets 以扫描硬编码的 API 密钥和凭据
   - 使用 `scripts/detect-secrets/plugins.py` 中定义的自定义模式
   - 对照 `scripts/detect-secrets/.secrets.baseline` 中的基线进行检查
4. **审查 markdown 输出**：该脚本会在 `tmp/` 文件夹中生成一个 markdown 文件以便于审查（与原始 .ipynb 相比节省上下文）
   - tmp/ 文件夹已被 gitignore，以避免提交审查产物
   - Markdown 包含代码单元格，但排除了输出内容，以便更清晰地审查
5. **手动审查**：通读 markdown 版本，对照样式指南和评分标准进行评估
6. **对每个维度评分**：客观地应用评分指南
7. **生成报告**：遵循下方的审计报告格式
8. **提供具体示例**：使用样式指南模板展示具体的改进建议，并注明行号引用

## 审计报告格式

请使用以下结构展示你的审计结果：

### 执行摘要
- **总体得分**：X/20
- **主要优势**（2-3 个要点）
- **关键问题**（2-3 个要点）

### 详细评分

#### 1. 叙述质量：X/5
[简要理由及具体示例]

#### 2. 代码质量：X/5
[简要理由及具体示例]

#### 3. 技术准确性：X/5
[简要理由及具体示例]

#### 4. 可操作性与理解度：X/5
[简要理由及具体示例]

### 具体建议

[优先级排序的、可操作的改进列表，并引用特定章节]

### 示例与建议

[展示 notebook 的具体摘录，并提出具体的改进建议]

## 快速参考检查清单

使用此清单确保全面覆盖：

**引言**（参见 style_guide.md 第 1 节）
- [ ] 以要解决的问题作为引子（1-2 句话）
- [ ] 解释为什么重要（1-2 句话）
- [ ] 以要点形式列出学习目标（2-4 个 TLOs/ELOs）
- [ ] 侧重于交付的价值，而非构建的机制
- [ ] 可选：提及更广泛的应用（1 句话）

**前置条件与设置**（参见 style_guide.md 第 2 节）
- [ ] 清晰列出所需知识
- [ ] 列出所需工具（Python 版本、API 密钥）
- [ ] 如适用，提及推荐的背景知识
- [ ] 使用 %%capture 抑制 pip install 的输出
- [ ] 使用 dotenv.load_dotenv() 而非 os.environ
- [ ] 在顶部定义 MODEL 常量
- [ ] 将相关的安装项合并在一个命令中

**结构与组织**
- [ ] 具有逻辑清晰的章节递进
- [ ] 每个章节通过演示进行教学
- [ ] 代码块之前有解释性文字
- [ ] 代码块之后包含我们学到了什么
- [ ] 使用标题分隔章节

**结论**（参见 style_guide.md 第 4 节）
- [ ] 呼应学习目标
- [ ] 总结完成的工作
- [ ] 建议将学到的知识应用到用户场景的方法
- [ ] 指出后续步骤或相关资源

**代码质量**
- [ ] 所有代码块之前都有解释性文字
- [ ] 没有硬编码的 API 密钥（由 detect-secrets 自动检查）
- [ ] 有意义的变量名
- [ ] 注释解释“为什么”而非“是什么”
- [ ] 遵循语言最佳实践
- [ ] 在 notebook 顶部将模型名称定义为常量

**输出管理**
- [ ] 使用 %%capture 抑制 pip install 日志
- [ ] 没有冗长的调试输出
- [ ] 显示相关的 API 响应
- [ ] 仅在演示错误处理时显示堆栈跟踪

**内容质量**
- [ ] 解释方法为何有效
- [ ] 讨论何时使用此方法
- [ ] 提及局限性/注意事项
- [ ] 提供可迁移的知识
- [ ] 选择合适的模型

**技术要求**
- [ ] 无需修改即可执行（API 密钥除外）
- [ ] 使用未弃用的 API 模式
- [ ] 使用有效的模型名称（claude-sonnet-4-5、claude-haiku-4-5、claude-opus-4-5）
- [ ] 在 notebook 顶部将模型名称定义为常量
- [ ] 包含依赖项规范
- [ ] 已分配到主类别
- [ ] 具有相关标签

### 内容理念：行动 + 理解

Cookbook 主要以行动为导向，但策略性地融入了理解内容，并受 Diataxis 框架指导。

**核心原则：**
- **实用导向**：向用户展示如何使用可运行的代码完成特定任务
- **问题优先**：以要解决的问题和交付的价值开头，而非机制
- **构建者视角**：从用户的角度出发，解决实际问题
- **培养能力**：帮助用户理解方法为何有效，而不仅仅是如何操作
- **可迁移的知识**：传授适用于特定示例之外的规律和原则
- **批判性思维**：鼓励用户质疑输出，认识局限性，做出明智选择
- **学习契约**：首先陈述学习目标，然后在结论中呼应它们

### 什么样的 Cookbook 是好的

一个好的 Cookbook 不仅帮助用户解决当下的问题，还能帮助他们理解解决方案背后的基本原则，鼓励他们识别何时以及如何调整方法。用户将能够对 AI 系统设计做出更明智的决策，培养对模型输出的判断力，并建立可迁移到未来 AI 系统的技能。

### Cookbook 不是什么

Cookbook 不是纯教程：我们假设用户具备基本的技术技能和对 API 的熟悉度。我们在 cookbook 中明确说明前置条件，并引导用户前往 Academy 学习更多主题。
它们不是全面的解释：我们不教 Transformer 架构或概率论。我们需要理解，用户遵循我们的 cookbook 是为了解决他们今天面临的问题。他们很忙，正处于学习或构建的过程中，并希望能够运用所学来解决当前的需求。
Cookbook 不是参考文档：我们不会详尽地记录每个参数，我们会根据需要链接到文档中的适当资源。
Cookbook 不是简单的技巧和窍门：我们不教授仅适用于当前模型代际的“黑客技巧”。我们不过度承诺而交付不足。
Cookbook 不是生产就绪的代码：它们展示用例和能力，而非生产模式。不需要过度的错误处理。

### 样式指南

#### 语气与语调
- 教育性和培养能力
- 专业但平易近人
- 尊重用户的智力和时间
- 使用第二人称（“你”）或第一人称复数（“我们”）——在 notebook 内保持一致

#### 写作质量
- 清晰、简洁的解释
- 优先使用主动语态
- 短段落（3-5 句话）
- 避免未定义的术语
- 使用标题分隔章节

#### 代码呈现
- **始终先解释再展示**：每个代码块之前应有解释性文字
- **运行后解释**：在代码块执行后包含我们学到了什么
- **注释解释为什么，而不是什么**：使用有意义的变量名
- **使用常量**：在顶部将 MODEL 定义为常量
- **良好习惯**：使用 `dotenv.load_dotenv()` 而非 `os.environ`

#### 输出处理
**使用 %%capture 移除多余输出**：
- pip install 日志（始终抑制这些）
- 冗长的调试语句
- 冗长的堆栈跟踪（除非演示错误处理）

**显示相关输出**：
- 演示功能的 API 响应
- 成功执行的示例

### 结构要求

**详细模板和示例请参见 style_guide.md**

#### 1. 引言（必需）
必须包含：
- **问题引子**（1-2 句话）：我们要解决什么问题？
- **为什么重要**（1-2 句话）：为什么这很重要？
- **学习目标**（2-4 个要点）：“在本 cookbook 结束时，你将能够……”
  - 使用行为动词（构建、实施、部署等）
  - 具体说明能力
  - 包含背景/约束条件
- **可选**：更广泛的应用（1 句话）

❌ **避免**：以机制开头（“我们将构建一个研究代理……”）
✅ **做法**：以问题/价值开头（“你的团队花费数小时对 CI 失败进行分类……”）

#### 2. 前置条件与设置（必需）
必须包含：
- **所需知识**：需要的技术技能
- **所需工具**：Python 版本、带链接的 API 密钥
- **推荐**：有帮助的可选背景知识
- **设置**：分步骤并附带解释
  - 对 pip install 使用 `%%capture`
  - 使用 `dotenv.load_dotenv()` 而非 `os.environ`
  - 在顶部定义 `MODEL` 常量

#### 3. 主要内容（必需）
按逻辑步骤或阶段组织，每个阶段包含：
- 清晰的章节标题
- **代码块之前的解释性文字**（我们要做什么）
- 代码示例
- **代码块之后的解释性文字**（我们学到了什么）
- 预期输出（如适用）
- 可选：理解提示（为什么有效、何时使用、局限性）

#### 4. 结论（推荐）
必须包含：
- **回顾**：呼应学习目标
- **完成的工作**：关键点总结
- **应用指导**：如何将学到的知识应用到用户场景
- **后续步骤**：相关资源或进一步探索的想法

❌ **避免**：通用总结（“我们演示了 SDK 如何实现……”）
✅ **做法**：可操作的指导（“考虑将其应用于 X……接下来，尝试 Y……”）

#### 可选章节
- **工作原理**：底层机制的简要解释
- **何时使用**：合适的用例和场景
- **局限性与注意事项**：警告、失败模式、约束条件
- **故障排除**：常见问题和解决方案
- **变体**：替代方法或扩展
- **性能说明**：优化考虑
- **延伸阅读**：相关文档、论文或更深入解释的链接

### 需要标记的常见反模式

详细的好/坏示例请参考 style_guide.md。注意以下问题：

#### 引言反模式
❌ 以机制开头：“我们将使用 Claude SDK 构建一个研究代理……”
❌ 功能堆砌：列出 SDK 方法或工具能力
❌ 模糊的学习目标：“了解代理”或“理解 API”
✅ 以问题为导向的框架，配合具体、可操作的学习目标

#### 设置反模式
❌ 未使用 `%%capture` 的嘈杂 pip install 输出
❌ 多个独立的 pip install 命令
❌ 使用 `os.environ["API_KEY"] = "your_key"` 而非 dotenv
❌ 全文硬编码模型名称，而非使用 MODEL 常量
✅ 干净的设置，合并安装项，使用 dotenv 和常量

#### 代码呈现反模式
❌ 代码块之前没有解释性文字
❌ 运行代码后没有解释我们学到了什么
❌ 注释解释代码做“什么”（代码应自文档化）
❌ 过度解释显而易见的代码
✅ 代码前有背景，代码后有见解，注释解释“为什么”

#### 结论反模式
❌ 通用总结：“我们演示了 SDK 如何实现……”
❌ 仅重述 notebook 做了什么，没有指导
❌ 未呼应陈述的学习目标
✅ 关于将学到的知识应用到用户具体场景的可操作指导

---