本地跑通第一个示例
这页的目标很简单：不要一上来就试图理解全部示例，而是先建立一条稳定的本地运行路径。只要你能把一个例子反复跑通、改动、验证，后面很多示例都会变得容易得多。
第一步：准备一个安全的本地环境
基础要求
- Python 3.11+
uv可用- 可用的
ANTHROPIC_API_KEY - 一份可重复的小样本数据
最常见的初始化命令
uv sync --all-extras
cp .env.example .env然后在 .env 中填入：
ANTHROPIC_API_KEY=your-api-key第二步：先做结构检查，再做真实执行
快速结构检查
make test-notebooks这一步更适合排查明显问题，例如结构错误、环境不齐、基础约束不满足。
只跑一个目标示例
make test-notebooks NOTEBOOK=tool_use/calculator_tool.ipynb先把注意力放在一个例子上，比一开始全量执行更高效。
需要真实执行时再跑
make test-notebooks-exec只有当你已经确认示例方向正确、并且准备验证真实模型表现时，再进入这一步。
第三步：按问题选示例，而不是按好奇心乱跳
- 需要文档问答、检索和知识增强：看 RAG 与检索增强
- 需要工具调用或自动化：看 工具调用
- 需要多步流程与任务编排：看 Agent 模式
- 需要图像、截图或文档理解：看 多模态
- 需要格式控制、缓存或结构化输出：看 输出控制
- 需要回归验证和质量基线：看 评测与测试
第四步：改造时一次只改一层
建议按这个顺序改：
- 先换输入数据
- 再换提示词或系统约束
- 再接自己的工具或外部系统
- 最后再调模型、并发和成本策略
这样更容易定位“到底是哪一层改变了结果”。
常见坑
一开始就跑大样本
这通常只会把调试成本、接口成本和排障复杂度一起放大。
一次改太多
如果你同时改提示词、工具、数据和模型，就很难判断问题来自哪里。
没有准备最小验证集
示例改成自己的功能后，如果没有一个固定的小样本，你很难判断质量是在变好还是变差。
直接用真实业务数据试错
先脱敏、先缩小样本、先在测试环境里验证。示例阶段最怕的不是“不够真实”，而是“真实到出了风险”。
最后一条建议
真正高效的做法，不是“把更多示例读完”，而是“先把一个示例改成自己真正会继续维护的东西”。只要这一步完成，Cookbook 对你的价值就已经开始显现。