| name | deepseek-api |
| description | 调用 DeepSeek API（/chat/completions）的强制查阅规范，覆盖思考模式（reasoning_content / thinking / reasoning_effort）与多轮对话上下文拼接。**任何**涉及 DeepSeek API 的代码编写、修改、排错前必须先调用本 skill。触发词：DeepSeek、deepseek、deepseek-v4-pro、reasoning_content、思考模式、thinking mode、reasoning_effort、deepseek 多轮、deepseek chat completions、api.deepseek.com。 |
DeepSeek API 使用规范
强制要求
每次涉及 DeepSeek API 的编码/修改/排错前，必须先阅读本目录下的两份原文档：
禁止凭记忆/训练数据回答 DeepSeek API 相关问题：模型名、参数名、reasoning_content 回传规则、思考开关参数格式都必须以本目录文档为准。文档可能随上游更新，每次都要重读。
关键红线（先看这一段，再去读原文）
- base_url：
https://api.deepseek.com，使用 OpenAI SDK 调用。
- 思考模式开关：OpenAI 格式下通过
extra_body={"thinking": {"type": "enabled/disabled"}} 传入，不要写成顶层 thinking=。默认开启。
- 思考强度
reasoning_effort："high" | "max"；low/medium 会被映射为 high，xhigh 映射为 max。
- 思考模式禁用参数：
temperature、top_p、presence_penalty、frequency_penalty 传了不会报错但不会生效——不要依赖它们。
- 多轮对话是无状态的：每轮必须自行拼接完整
messages 历史回传给 API，服务端不保存上下文。
reasoning_content 回传规则（最容易踩坑）：
- 两个 user 之间没有工具调用 → 中间 assistant 的
reasoning_content 无需回传，回传也会被忽略。
- 两个 user 之间有工具调用 → 该轮所有 assistant 的
reasoning_content 必须完整回传，否则 API 返回 400。
- 安全做法：直接
messages.append(response.choices[0].message)，整条 message 对象（含 content / reasoning_content / tool_calls）一起塞回去；流式则手动重建为 {"role":"assistant","reasoning_content":..., "content":..., "tool_calls":...}。
- 工具调用循环：一个 user turn 内模型可能进行多次思考+工具调用子轮次，需用
while True 循环直到 tool_calls is None 才算该 turn 结束。
自检清单（提交 DeepSeek 相关代码前过一遍）
排错顺序
DeepSeek API 返回异常时按以下顺序排查（与 CLAUDE.md 中第三方 API 集成规范一致）：
- 重读 thinking_mode.md / multi_round_chat.md 对照参数
- 打印发送给 API 的完整
messages 与请求体，看真实响应
- 最后才读内部封装实现
400 报错最常见原因：含工具调用的历史轮次漏传 reasoning_content。
文档来源
如发现本目录文档与上述 URL 不一致，以 URL 为准，并用 local-webfetch 重新抓取覆盖本目录文件。
