用途：在项目中首次正确接入 LLM 客户端，避免常见配置陷阱，并可用于审计已有集成。
主要能力与要点：
- 密钥从环境变量读取，绝不硬编码或提交；变量名写入 CLAUDE.md，值放 .env.local（gitignore）、CI secret 或密码管理器。若密钥曾被提交，需轮换，删除文件不会从 git 历史中移除。
- 客户端在 handler 内实例化，而非模块作用域。模块级初始化会在构建期（如 Vercel 的 page-data collection）运行，缺少环境变量时导致构建失败，且报错与原因不符；本地构建常通过而部署失败。
- 模型从环境变量固定并带注册表默认值：MODEL = os.environ.get("AI_MODEL", "<default from registry>")。
- 设置显式超时，默认客户端超时往往远长于实际可接受等待时间。
- 处理推理模型的参数差异。
陷阱：
- 推理模型输出为空（静默）：输出 token 预算同时覆盖推理 token 与可见输出，设得过低会耗尽预算返回空或截断消息且无报错。修复：推理模型给足预算，输出为空先提高 token 上限再调试提示词。
- max_tokens 与 max_completion_tokens（显式报错）：推理模型（gpt-5*、o*）拒绝 max_tokens，要求 max_completion_tokens。按模型 ID 前缀检测，而非维护列表。
- 带 provider 前缀的模型 ID 不是笔误：经 LiteLLM 路由的框架（如 CrewAI）使用 provider/model 格式，openai/gpt-5-mini 在此正确、在别处错误。可用 grep -iE "crewai|litellm" requirements.txt package.json 验证。
- Azure OpenAI 不等于 OpenAI：端点、API 版本参数、部署名而非模型名、独立密钥均不同；其模型可用性与定价可能滞后 OpenAI API，切换工作负载前需确认。
审计已有集成可用 grep 查找模型固定、硬编码密钥，并用 git ls-files --error-unmatch .env 与 git log 判断 .env 是否真被提交；未跟踪且被 gitignore 属正常，无需轮换。
限制：模型 ID 不在本文件，见 references/model-registry.md；具体模型可用性与价格需按注册表命令核实。