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 做了什么，没有指导 ❌ 未呼应陈述的学习目标 ✅ 关于将学到的知识应用到用户具体场景的可操作指导