cookbook-audit

Cookbook 审计

说明

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

该风格指南提供了详细的模板和示例，涵盖以下内容：

• 以问题为导向的引言，包含终端学习目标（TLO）和支持性学习目标（ELO）
• 前置条件和设置模式
• 核心内容结构
• 与学习目标相呼应的结论

重要：进行审计前，务必先阅读 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 个 TLO/ELO）
• 聚焦于所带来的价值，而非构建的机制
• 可选：提及更广泛的应用场景（1 句话）

先决条件与设置（参见 style_guide.md 第 2 节）

• 清楚列出所需知识
• 列出所需工具（Python 版本、API 密钥）
• 如适用，提及建议具备的背景知识
• 使用 %%capture 抑制 pip install 的输出
• 使用 dotenv.load_dotenv()，而非 os.environ
• 在顶部定义 MODEL 常量
• 将相关安装项合并到一条命令中

结构与组织

• 按照合理的顺序安排章节
• 每个章节都通过演示来讲解
• 在代码块前提供说明文字
• 在代码块后总结所学内容
• 使用标题划分章节

结论（参见 style_guide.md 第 4 节）

• 将内容与学习目标对应起来
• 总结已完成的工作
• 建议如何将所学应用到用户自己的场景中
• 指出后续步骤或相关资源

代码质量

• 所有代码块前都有说明文字
• 不含硬编码的 API 密钥（由 detect-secrets 自动检查）
• 变量命名清晰易懂
• 注释解释“为什么”，而非“是什么”
• 遵循语言最佳实践
• 在笔记本顶部将模型名称定义为常量

输出管理

• 使用 %%capture 抑制 pip install 日志
• 不输出冗长的调试信息
• 展示相关的 API 响应
• 仅在演示错误处理时显示堆栈跟踪

内容质量

• 解释所采用的方法为何有效
• 说明何时适合使用此方法
• 提及其局限性和注意事项
• 提供可迁移的知识
• 选择合适的模型

技术要求

• 无需修改即可运行（API 密钥除外）
• 使用未弃用的 API 模式
• 使用各系列中的最新模型（claude-opus-5-5、claude-sonnet-5-5、claude-fable-5-1、claude-haiku-4-5）；已被取代但仍提供服务的 ID（例如 claude-opus-5、claude-sonnet-5）会被视为警告，除非是有意固定使用；已停用的 ID（例如 claude-3-*）则会阻止通过
• 使用非日期型模型别名（绝不使用 claude-sonnet-4-5-20250929 这类带日期的 ID）
• 在笔记本顶部将模型名称定义为常量
• 包含依赖项说明
• 归入主要类别
• 添加相关标签

内容理念：行动 + 理解

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 句话）

❌ 避免：以机械流程开头（“我们将构建一个研究 Agent……”） ✅ 应该：以问题/价值开头（“你的团队花费大量时间对 CI 失败进行分诊……”）

2. 前置条件与设置（必需）

必须包含：

• 所需知识：所需的技术技能
• 所需工具：Python 版本、带链接的 API 密钥
• 推荐：有帮助的可选背景知识
• 设置：带解释的分步操作
  • 对 pip install 使用 %%capture
  • 使用 dotenv.load_dotenv() 而不是 os.environ
  • 在顶部定义 MODEL 常量

3. 主要内容（必需）

按逻辑步骤或阶段组织，每个步骤包含：

• 清晰的章节标题
• 代码块前的说明性文字（我们即将做什么）
• 代码示例
• 代码块后的说明性文字（我们学到了什么）
• 预期输出（在相关处）
• 可选：理解提示框（为什么有效、何时使用、局限性）

4. 结论（推荐）

必须包含：

• 回顾：映射回学习目标
• 完成了什么：关键要点总结
• 应用指导：如何将所学应用到用户的场景中
• 后续步骤：可继续探索的相关资源或想法

❌ 避免：泛泛的总结（“我们已经展示了 SDK 如何实现……”） ✅ 应该：可操作的指导（“考虑将此应用到 X……接下来，尝试 Y……”）

可选章节

• 工作原理：简要说明底层机制
• 何时使用：适用场景与上下文
• 限制与注意事项：注意事项、失效模式、约束条件
• 故障排查：常见问题与解决方案
• 变体：替代方法或扩展
• 性能说明：优化方面的考量
• 延伸阅读：相关文档、论文或更深入讲解的链接

需要标记的常见反模式

详细的正例/反例请参阅 style_guide.md。注意以下问题：

引言反模式

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

环境搭建反模式

❌ 没有使用 %%capture，导致 pip install 输出杂乱 ❌ 使用多条独立的 pip install 命令 ❌ 使用 os.environ["API_KEY"] = "your_key" 而不是 dotenv ❌ 在各处硬编码模型名称，而不是使用 MODEL 常量 ✅ 使用分组安装、dotenv 和常量的简洁环境搭建

代码展示反模式

❌ 代码块前没有说明文字 ❌ 运行代码后没有解释我们学到了什么 ❌ 注释解释代码“做了什么”（代码应当自解释） ❌ 对显而易见的代码过度解释 ✅ 代码前有背景说明，代码后有要点总结，注释解释“为什么”

结论反模式

❌ 泛泛的总结：“我们已经展示了 SDK 如何实现……” ❌ 只是复述 notebook 做了什么，而没有给出指导 ❌ 没有映射回所述的学习目标 ✅ 就如何将所学应用到用户的具体场景提供可操作的指导