前言¶

在 DSH 中处理 DeepSeek 工具调用时，有些失败看起来像“模型抽风”，但根源可能在请求和响应的拼接上：工具结果已经传回，请求仍可能报错；流式输出看起来正常，最后拼出的参数却不是合法 JSON；同一段 history 在打开或关闭 thinking 后表现不同。

DeepSeek Protocol Doctor 是一个第三方 DSH 插件，用于离线检查 DeepSeek 请求、工具循环、reasoning_content 和 SSE / JSONL 流。它只检查给定的请求内容或录制流，不调用模型，也不判断回答质量。

这是什么¶

DeepSeek Protocol Doctor 由 Whning0513 维护，采用 MIT 许可。它为 DSH 增加两个检查工具：

• deepseek_protocol_check：检查请求和消息历史。
• deepseek_stream_check：检查保存下来的 SSE / JSONL 流。

它也可以作为 Agent Skill 使用。仓库提供 skills/deepseek-protocol-doctor 目录，DSH 可从 .agents/skills/、.dsh/skills/ 以及用户目录下的对应位置自动发现。Skill 只负责把排查步骤组织好，实际协议检查仍调用同一套 dsv4-doctor。

能检查哪些问题¶

下面列出的检查项来自当前已核实能力。工具主要面向工具调用协议、流式响应拼接和常见配置项。

• tool_call_id 缺失。
• 同一轮 tool call 未收齐就进入下一轮。
• reasoning_content 被客户端丢掉。
• function.arguments 未拼完就被当成 JSON 解析。
• 多个流式 tool call 的 delta 交错到达，客户端按到达顺序直接追加。
• strict schema 缺少 required 或 additionalProperties: false。
• max_tokens、thinking mode 和 /beta 路由中的相关配置。

每条问题会有固定 code，方便在 CI 中处理。输出支持 text、JSON 和 SARIF。退出码可用于区分 error 或 warning；warning 默认不拦 CI，需要更严格时加 --fail-on-warning。

安装到 DSH¶

插件需要 Python 3.10+。如果 Python 安装在别处，可以设置 DSV4_DOCTOR_PYTHON。

下面命令用于把插件安装到 DSH 的某个 profile。命令中的 demo 是 profile 示例，需要替换为实际 profile：

dsh plugin --profile demo add github:Whning0513/deepseek-protocol-doctor

安装完成后，DSH 中会新增两个工具。可以直接这样调用：

用 deepseek_protocol_check 看看这个请求里的工具调用哪里不对：{ ... }

作为 Agent Skill 使用¶

仓库中的 skills/deepseek-protocol-doctor 是 DSH 可自动发现的 Skill 目录。DSH 会从 .agents/skills/、.dsh/skills/ 以及用户目录下的对应位置发现它。

如果想把 Skill 放到当前项目的共享目录，可以先执行：

mkdir -p .agents/skills
cp -R /path/to/deepseek-protocol-doctor/skills/deepseek-protocol-doctor .agents/skills/

这里把 /path/to/deepseek-protocol-doctor 替换为仓库在本机的实际路径即可。复制后，DSH 仍会通过同一套 dsv4-doctor 执行检查。

命令行用法¶

在仓库目录里可以先创建虚拟环境并安装：

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .

安装后可以运行示例数据：

dsv4-doctor check fixtures/valid_tool_loop.json
dsv4-doctor check fixtures/invalid_tool_loop.json
dsv4-doctor stream fixtures/stream_interleaved.jsonl

如果不安装，也可以直接通过 Python 模块运行：

PYTHONPATH=src python -m dsv4doctor check fixtures/valid_tool_loop.json

check 接受完整的 OpenAI-compatible 请求，也接受单独的 messages 数组；stream 接受 SSE 和 JSONL。

如果需要机器可读结果，可以输出 JSON 或 SARIF：

dsv4-doctor check request.json --format json
dsv4-doctor check request.json --format sarif > result.sarif

适用场景与注意事项¶

这个插件适合 DSH / 智能体开发者在排障或 CI 中检查请求结构、工具循环和流式拼接。它不是 benchmark，也不会判断回答质量。

使用时需要注意：

• 这是第三方项目，不是 DeepSeek 官方组件。
• 它没有内置 tokenizer，只做静态的 max_tokens 检查，不给出假装精确的 token 数。
• OpenRouter、vLLM、SGLang 和其他兼容接口可能有自己的行为，目前还没有完整覆盖。
• DSH 还在 developer preview；如果上游插件接口变化，这里的包装也需要跟着改。
• 工具不会替你补一段假的 reasoning_content。这个字段应该保存模型原始返回值。
• 插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。

GitHub 仓库：Whning0513/deepseek-protocol-doctor