链路体检 yangjinbin2006/dsh-doctor

dsh-doctor

一个给 DeepSeek Harness 做链路检查的小工具，专治挂了本地桥之后的各种不通。

dsh 本身可以接任何 OpenAI 兼容端点。前面加一层桥之后，大部分故障在聊天窗口里长得一样：
一个 400、一坨 JSON、一个错误码。错误码是唯一线索，但它基本不指向真正出问题的地方。

这个工具把链路按顺序走一遍，遇到第一处断点就停下：配置文件、TCP、/v1/models、一次真实对话请求。输出会告诉你是哪一跳失败，以及可以改什么。

只用 Python 标准库，3.8 以上，Windows、macOS、Linux 都能跑。

python dsh_doctor.py

链路正常时：

dsh-doctor 1.0.0
[ OK ] dsh-home found dsh home
[ OK ] patch-layer using ~/.dsh/profiles/desktop/cordis.patch.yml
[ OK ] provider local-bridge -> http://127.0.0.1:8080/v1, 3 model(s) [supportsDeveloperRole=false, thinkingFormat=openai]
chat-model, long-context-model, vision-model
[ OK ] tcp 127.0.0.1:8080 reachable (11ms)
[WARN] auth-source env BRIDGE_API_KEY is NOT set in this process
fix:
- Set the environment variable, then fully restart dsh so
it inherits it.
[ OK ] models 3 model(s) served
[ OK ] chat round-trip OK via 'chat-model'

6 ok, 1 warning(s), 0 failure(s)

真出问题时，返回体被替换成看得懂的说明：

[FAIL] chat POST /v1/chat/completions -> 400 [11128]
The upstream gateway rejected the request because the client does not
look like an approved channel. That is a request-fingerprint check.
The API key is usually fine.
fix:
- 把桥升级到会改写客户端身份（提示词前缀、User-Agent）的版本。
- 有些客户端会发 developer 角色，上游不接受。在 provider 的 compat 里设 supportsDeveloperRole: false。
- 用 curl 直接打同一个端点复测。curl 通而客户端不通，就是指纹问题。

为什么从配置文件查起

dsh 的 provider 配置放在 ~/.dsh/profiles/<profile>/cordis.patch.yml。它不是普通配置
文件，而是 YAML 数组形式的 loader patch，出错时不会报错：providers: 下面缩进错一格， provider 就直接从模型列表里消失，没有任何提示。

同时这个文件也是大家贴 API Key 的地方，所以它既制造"跑不起来"，也制造"key 泄露"。

dsh-doctor 直接解析这个结构，因此能指出客户端只会笼统报 400 的那些问题。

检查项

| 检查项 | 输出内容 |
| dsh-home | dsh 的状态目录在哪里，识别 DSH_HOME |
| patch-layer | 当前生效的补丁文件，以及还存在哪些 |
| provider | llm-pi-ai 下每个 provider 的 baseURL、模型数量、compat 标志 |
| secret | YAML 里明文的 apiKey:，带行号 |
| tcp | baseURL 里的 host 和 port 能不能连上，耗时多少 |
| auth-source | apiKeyEnv 指定的变量在当前进程里存不存在 |
| models | GET /v1/models 结果，以及声明了但端点没提供的 id |
| chat | 用默认模型发一次 max_tokens=16 的请求 |

错误码对照

| 编码或特征 | 含义 |
| 11128 Illegal API invocation from an unapproved channel | 请求指纹被拒，不是鉴权问题。一般是桥版本旧，或者带了 developer 角色消息。 |
| 11140 | 账号对这个模型没有权限。换出口重试只是白烧额度。 |
| no usable account | 桥在跑，但该路由下账号池为空。 |
| 429 / rate limit | 被限流。退避、加账号，或者开跨出口回退。 |
| 401 / invalid api key | dsh 进程没继承到这个环境变量，或者 key 过期了。 |
| model not found | 声明的 id 和端点实际提供的不一致，大小写敏感。 |
| developer ... not supported | 设 supportsDeveloperRole: false。 |
| context length | contextWindow 写得比上游允许的大。 |

更详细的排查记录在 docs/error-codes.md。

参数

--profile NAME 只检查这个 profile --json 机器可读输出 --timeout SECONDS 网络超时，默认 30 --skip-network 只查配置，不发请求 --proxy 走系统代理，默认关闭 --no-color 关闭 ANSI 颜色

--proxy 默认关闭是有原因的。企业代理和沙箱代理经常让一个正常运行的本地桥返回 502，所以工具默认直连。

退出码

0 表示全部通过或只有警告，1 表示至少一处失败。可以直接放进 CI，不用再解析输出。

说明

- 对话探测只发 16 个 token，--skip-network 则一个请求都不发。
- 不会完整打印密钥，最多显示成 sk-02****abcd。
- 只读，不写任何文件。
- 完整样例在 examples/report-sample.txt。

相关项目

- dsh-config-gen：生成并校验本工具检查的补丁层。

许可

MIT