dsh-client-masquerade

August 29, 2026 · View on GitHub

DeepSeek Harness 插件：让自定义模型伪装成 Claude Code / Codex 客户端 A DeepSeek Harness plugin: make a custom model masquerade as a Claude Code / Codex client.

一些网关（如 agentrouter、claude-code-router 类代理）按请求头识别客户端并据此路由或放行。本插件把伪造的客户端身份头写入你的 llm-pi-ai provider 配置，随每次请求真实发到上游网关——一键开启/关闭/切换，带中英文设置页。

安装 / Install

方式一：官方命令安装（推荐）

dsh plugin --profile web add github:ymh0000123/dsh-client-masquerade

这条命令会在 profile 目录里执行 pnpm add github:ymh0000123/dsh-client-masquerade，然后自动把包（其 dsh.bundle.patch 声明）并入该 profile 的插件层栈——不需要手动改任何配置文件。

然后应用补丁（必做）——否则伪装头里的 user-agent 会被 pi-ai 适配器的归属机制剥掉并覆盖为 deepseek-harness/...，按 User-Agent 识别客户端的网关（agentrouter、claude-code-router 类）会拒绝请求（401 UNAUTHENTICATED）。最省事的方式是在设置页点 User-Agent 补丁 → 应用（一次写入全部三个补丁），或用模型工具：

mask_client action=patch

也可以在你的 profile 目录（含 node_modules 的那个）逐个执行：

node node_modules/dsh-client-masquerade/patches/apply-pi-ai-useragent-patch.mjs   # user-agent
node node_modules/dsh-client-masquerade/patches/apply-pi-ai-body-patch.mjs        # 请求体（按请求体识别的网关需要）
node node_modules/dsh-client-masquerade/patches/apply-variant-retry-patch.mjs     # vision-toolkit 变体

注意：node_modules 是相对路径，请先在 profile 目录（含 node_modules 的那个）里执行。不记得目录或不在该目录时，直接用绝对路径调用脚本即可，脚本会自动定位本 profile 里安装的目标包：
node "C:\Users\你的用户名\.dsh\profiles\web\node_modules\dsh-client-masquerade\patches\apply-pi-ai-useragent-patch.mjs"

补丁幂等，可重复执行；pnpm install 或升级被打补丁的包后需重新应用一次。插件启动时也会自检：未打 UA 补丁会在日志打醒目的 [client-masquerade] dsh-llm-pi-ai is NOT user-agent patched 警告；若某条线路开了请求体伪装而请求体补丁没生效，也会单独警告——这个组合的失败表现和"网关繁忙"一模一样，不警告很难发现。

兼容旧版：若 dsh-llm-pi-ai 的补丁是旧版插件（<1.2.0）写入的（requestHeaders 块是另一种等价写法），还原 也能正确识别并还原为原始版本；应用 会把它升级为当前版本的补丁形态。不再出现 "neither the stock nor the patched requestHeaders block found"。

安装模式下也可以直接在网页设置页（Settings → Client Masquerade → 运行时补丁 → 全部应用）一键写入全部三个补丁，之后重启 dsh web 生效；动态模式无文件系统权限，设置页只显示补丁状态，仍需手动执行上面的命令。

之后重启：

dsh web

安装后：

Host 侧：mask_client 模型工具自动注册；设置写入逻辑挂载。
Web 侧：dsh.client 浏览器清单自动收录，Settings 里出现 Client Masquerade / 客户端伪装 设置页。

卸载：dsh plugin --profile web remove dsh-client-masquerade。插件可自由安装/卸载、重复安装无副作用；卸载后有两处残留需手动清理（见下）。

安装 / 卸载 / 清理速查

操作	命令 / 位置
安装	`dsh plugin --profile web add github:ymh0000123/dsh-client-masquerade`
卸载	`dsh plugin --profile web remove dsh-client-masquerade`
补丁应用（全部三个）	设置页运行时补丁 → 全部应用，或 `mask_client action=patch`（重启 `dsh web` 生效）
补丁还原（全部三个）	设置页运行时补丁 → 全部还原，或 `mask_client action=unpatch`（重启 `dsh web` 生效）
单独应用请求体补丁	`node node_modules/dsh-client-masquerade/patches/apply-pi-ai-body-patch.mjs`（`--revert` 还原）
清除伪装头	设置页点 Off，或 `mask_client action=off provider=<id>`（连同请求体伪装开关一并清除）

一共三个补丁，都是改已安装的第三方包，都需要重启 dsh web 生效，都幂等：

补丁	目标文件	作用	不打会怎样
User-Agent	`@deepseek-ai/dsh-llm-pi-ai/lib/index.js`	让 profile 显式配置的 `user-agent` 原样上线	按 UA 识别的网关回 401
请求体	`@earendil-works/pi-ai/dist/api/anthropic-messages.js`	按需注入 Claude Code 的请求体指纹	按请求体识别的网关回 429/503（看起来像排队）
Vision-toolkit 变体	`@anionex/dsh-vision-toolkit/lib/image-input-variants.js`	`vision-toolkit-*` 包装路由继承上游重试策略	排队策略到不了 agent 实际走的路由

卸载后残留说明：① 三个补丁都是改在别的包的文件上，卸载插件不会自动还原——不用了就 mask_client action=unpatch（不动也基本无害：UA 补丁仅在 provider 显式配 user-agent 时生效，请求体补丁在没有开关头时完全惰性）；② 已写入 provider 的伪装 headers 会保留在设置文档里，需要逐个执行 off 或手动清除。

注：若之前用「动态插件」方式运行过同一份代码，请先停用/删除动态版本，避免设置页入口重复注册。

方式二：动态插件（无需重启、进程级）

创建动态插件（cordis_define），或直接在运行界面粘贴代码；
code.host ← 粘贴 host.body.js 全文（exports["./host.body"] 可编程读取）；
code.client ← 粘贴 client.body.js 全文；
运行插件并批准。

两种方式功能等价（伪装开关、mask_client、设置页、测试调用），区别：方式一随 profile 持久安装，方式二为进程级临时加载。安装模式下设置页走 webServer HTTP 路由（/dsh-client-masquerade/api），动态模式下走包私有 RPC。

动态模式同样需要 pi-ai 补丁：在 profile 目录执行 node node_modules/dsh-client-masquerade/patches/apply-pi-ai-useragent-patch.mjs（或手动应用 patches/ 里的改动）并重启，否则 user-agent 伪装无法上线。

前提：先在 Settings → Models 配置好你的自定义 provider（llm-pi-ai 路由），插件才能列出并写入。

它能做什么 / What it does

为任意已配置的 llm-pi-ai provider 一键应用/清除/切换伪装：Claude Code、Codex、或自定义请求头。
伪装头写入 provider 配置的 headers 字段（settings.yaml 中 llm-pi-ai.providers.<id>.headers），由 pi-ai 适配器在每次请求（Anthropic Messages 与 OpenAI 兼容协议均覆盖）原样发送。
请求体伪装：按需给 Anthropic 协议的请求体注入 Claude Code 的指纹（metadata.user_id、身份 system 块、哨兵工具定义），过 anyrouter 系网关的客户端校验——这是仅靠请求头过不去的那一关。
三个入口：设置页（Settings → Client Masquerade，卡片式面板：顶部四格状态摘要 + 身份伪装 / 请求体伪装 / 排队适配 / 运行时补丁 / 当前请求头）、模型工具 mask_client（list / on / off / test / body / queue）、动态模式下另有 Run 卡片面板。
界面中英双语，跟随 Harness 语言设置实时切换。
test 动作会真实发起一次最小流式调用，报告网关实际收到的请求头与模型回复/报错，并按该路线的伪装状态给出可执行的判断。

工作原理 / How it works

pi-ai 适配器（dsh-llm-pi-ai）的 provider 配置原生支持 headers 字典，并会在线路上发送它们。归属标头 user-agent 默认保留为 deepseek-harness/...，但配合适配器补丁（见 patches/）后，profile 里显式配置的 user-agent 会原样发到线上；未配置时仍回落到归属 User-Agent。预设因此同时写入网关真正识别的身份头与 User-Agent：

预设	写入的请求头
`claude-code`	`user-agent: claude-cli/2.1.241 (external, cli)`、`anthropic-client: claude-code/2.1.241`、`anthropic-version`、`anthropic-beta`（含 `context-1m-2025-08-07` 等完整列表）、`anthropic-dangerous-direct-browser-access`、`x-app: cli`、`x-stainless-*` 系列
`codex`	`user-agent: codex-tui/0.145.0 (...)`、`openai-client: codex/0.48.0`、`x-stainless-*` 系列
`custom`	任意（通过 `headersJson` 传入）

claude-code 预设的取值来自实测抓包：用本地反代把真实 claude-cli 2.1.241 的请求拦下来，逐个头比对后写入。网关普遍按 claude-cli 版本号放行，所以升级插件后建议重新点一次 Claude Code 让预设刷新（设置页会把旧预设标为「预设已过期」）。按设计不伪装 x-claude-code-session-id：它是每会话随机 UUID，写成固定值反而是更糟的指纹。

为什么需要补丁：原生 dsh-llm-pi-ai 会把 profile 的 user-agent 剥离并强制覆盖为 deepseek-harness/...，导致按 User-Agent 识别客户端的网关（如 agentrouter）拒绝请求（401 UNAUTHENTICATED）。patches/apply-pi-ai-useragent-patch.mjs 会把安装目录里 @deepseek-ai/dsh-llm-pi-ai/lib/index.js 的 requestHeaders 改为：显式配置的 profile user-agent 优先上线，未配置时回落归属 User-Agent。重装/升级 dsh-llm-pi-ai 后需重新应用。

排错：分清「伪装没生效」和「网关自己不行」

这是本插件最容易被误判的一点，而且误判的方向和直觉相反。

中转网关（new-api / one-api 系，anyrouter、agentrouter 等）在拒绝请求时，很多情况下只回一个裸的 429/503 Service Unavailable。这一个状态码同时对应两种完全不同的原因：

上游渠道真的全忙 —— 等一等就好，重试有意义；
网关的 Claude Code 校验拒绝了你的请求体 —— 重试一万次也不会好。

两者在状态码和响应体上完全一样。早期版本把它一律判成「排队」，于是建议「配 15 次重试、等 7-8 分钟」——对第 2 种情况，这只是把失败拖长。

mask_client action=test 现在按该路线自身的状态来区分，给出 classification 与 disguiseImplicated：

classification	触发条件	含义与处置
`auth` (401/403)	—	凭证或客户端身份被拒：检查 Key；确认 pi-ai user-agent 补丁已应用并重启
`policy-gate` (400 + `请启用 1m 上下文`)	—	缺 beta 声明头：重新应用新版 `claude-code` 预设（已内置完整 `anthropic-beta`）
`body-fingerprint` (429/503)	未开请求体伪装	网关可能在按请求体识别客户端——仅靠请求头满足不了。开启请求体伪装（见下节）后再判断
`body-fingerprint` (429/503)	已开伪装但补丁未生效	开关写进了设置，但执行注入的补丁没加载，请求体仍是 DSH 的形状。`mask_client action=patch` 后重启
`queued` (429/503)	伪装已生效仍失败	此时才是渠道池真忙（真实 Claude Code CLI 同样会被拒）。开启排队适配让 agent 等得起

交叉验证的可靠办法：把同一个 Key 填进 Claude Code（ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN）跑一次。注意这个验证只能证伪不能证实：Claude Code 能用、DSH 不能用，恰恰是请求体指纹校验的典型表现（真实 CLI 的请求体天然合格），并不说明 Key 有问题。

请求体指纹：anyrouter 系网关真正在校验什么

anyrouter 这类网关不看请求头，看请求体。下面每一条都是拿真实 claude-cli 2.1.241 的原始请求做消融实验测出来的——先逐字节重放拿到 200，再逐项删改：

改动	结果
逐字节重放真实请求	200
删掉 `metadata`	503
`metadata.user_id` 改成普通字符串（非 JSON）	503
`session_id` 为空 / 非 UUID 格式（`dsh-session-…`、无连字符的 32hex）	503
删掉 system 里的客户端身份块	503
把哨兵工具改名	429
27 个自造工具、体量拉到 104KB	429
16 个冷门真实工具（不含 Glob/Grep/Read）	429
只留 Glob + Grep + Read	200
在此基础上追加 DSH 自己的工具 / 改工具顺序 / 缩短 messages / 追加 system 文本	200

三个条件缺一不可：

metadata.user_id 是 JSON 字符串，device_id 非空（值不校验）、session_id 必须是 UUID 格式；
system 含客户端身份块；
tools 含 Glob / Grep / Read 这三个工具名。

工具描述不参与校验（换成等长填充仍返回 200），所以 Claude Code 改文案不会让伪装失效；只有它改名或删掉这三个工具才需要重新抓取指纹。指纹数据在 patches/claude-code-fingerprint.js。

开启请求体伪装

mask_client action=body provider=anyrouter state=on     # 开启
mask_client action=patch                                # 应用补丁（含请求体补丁）
# 重启 dsh web
mask_client action=body provider=anyrouter state=off    # 关闭

设置页也有 请求体伪装 开关。开关写入 provider 的 x-dsh-body-masquerade: claude-code:<deviceId> 头——这是内部标记，打了补丁的 pi-ai 会在发送前把它剥掉，不会上线。deviceId 在开启时生成一次并存进设置，让网关看到一个稳定的设备。

代价：三个哨兵工具会告知模型但 DSH 并未实现。少于三个过不了校验，换成冷门工具（CronCreate 之类）同样过不了，所以这是最小可行集。

注入时它们的描述会被替换成「不可用，请勿调用」——因为实测网关只校验工具名字，描述可以自由改写。这一点很关键：若按抓包原样注入描述，模型会把它们当成真能力去调用，而 DSH 没有实现、返回不了结果，于是模型明明已经回复完、界面却一直显示「工作中」。改写描述后模型不再调用（已实测对照），网关照样放行。

若某天网关开始校验描述，test/body-fingerprint-probe.mjs 会报出来：它的 “sentinel descriptions wiped” 那一项会从 200 变成 429。

补丁本身是惰性的：只有配了开关头的 provider 才会被注入，其余路线完全不受影响。

排队适配（渠道真的忙时）

确认请求体伪装已生效、仍然 429/503，才轮到排队适配。这类网关不直接拒绝，而是排队：上游渠道全忙时对每个请求都回 429/503，真实 Claude Code 靠带退避重试数分钟挺过去。

DSH 侧已内置 dsh-llm-retry 插件：它在 agent 请求失败时按 provider 的 retryPolicy 决定是否重试。默认策略只重试 5 次、退避到 10s（总窗口约 30s），远不够排一个长队。本插件新增 queue 动作，把 provider 的 retryPolicy 改成排队策略：

mask_client action=queue provider=anyrouter state=on            # 开启排队适配
mask_client action=queue provider=anyrouter state=on retries=15 maxdelay=60000   # 自定义
mask_client action=queue provider=anyrouter state=off           # 关闭，回落到默认策略

默认策略：maxRetries=10、退避 1s→30s（指数 + 抖动）、可重试码覆盖 RATE_LIMIT（429）与 SERVER（5xx）等，累计等待约 2-3 分钟——足以排过典型的长队，又不至于让真正死掉的线路挂住不报错。
list 会显示每个 provider 的排队状态（queue: true/false + 策略摘要）以及 registrationRetryPolicy——这是 agent 循环实际执行的策略（llm 注册表里捕获、经 prepareCall 交给 agent/request-error 由 dsh-llm-retry 消费）。它跟着 settings 变更实时更新（pi-ai 在 onChange 时重新注册路由），所以看到 registrationRetryPolicy.maxRetries == 10 / maxDelayMs == 30000 即证明排队机制已生效，无需猜测。
设置页也有 排队适配 开关。
test 动作同样会带退避骑队列（最多约 2-3 分钟，可被调用方中断），而不是试两三次就报失败；最终仍失败时，若该路线的请求体伪装已生效，返回 classification: queued、disguiseImplicated: false；否则返回 classification: body-fingerprint，提示先去过请求体那一关。

⚠️ 先过请求体校验，再谈排队。 若网关是按请求体识别客户端的（anyrouter 系），没开请求体伪装时无论配多少次重试都不会成功——重试只会把失败拖长。判断顺序：test 的 classification 说 body-fingerprint 就先开请求体伪装，说 queued 才是该调排队策略。

验证"排队机制是否真的在跑"：

mask_client action=list provider=anyrouter → 确认 queue: true 且 registrationRetryPolicy 与 retryPolicy 一致（maxRetries=10、maxDelayMs=30000）。一致即代表 agent 循环会用排队策略。

mask_client action=test provider=anyrouter → 观察 attempts（会到 10）与 classification: queued，说明测试在带退避骑队列。

用 anyrouter 作为模型发一条真实消息：失败时会看到 agent 带退避重试约 2-3 分钟（会话里会出现 llm/retry 事件，policyKey 含 maxRetries=10 / maxDelayMs=30000），而不是 30 秒就放弃。

若第 1 步显示 registrationRetryPolicy 与 settings 不一致（例如仍是 maxRetries=5 / maxDelayMs=10000 的默认值），说明运行中的进程还没完成注册更新——重启 dsh web 后必然一致（策略写入 settings 后实时传播；插件代码升级本身也需要重启加载）。

注意：策略写入的是设置文档，pi-ai 适配器每次请求都会重新读取 profile，因此无需重启即可对下一次 agent 请求生效（插件本体升级仍需重启 dsh web）。

⚠️ 重要：agent 实际用的路由可能是 vision-toolkit 变体

排查"还是只重试 5 次"时发现一个隐蔽坑：你的 agent 默认模型（settings.yaml 的 agent-default-model）可能指向 vision-toolkit-anyrouter 而不是 anyrouter。@anionex/dsh-vision-toolkit 会给每个纯文本上游路由注册一个 vision-toolkit-<上游> 包装变体（为了支持粘贴图片），你的消息走的是这个包装路由。

而 vision-toolkit 的包装适配器没有实现 providerRetryPolicy（它自己的注释说"上游路由拥有重试"，但漏了转发），所以 vision-toolkit-anyrouter 的注册策略永远是默认 5 次——无论上游 anyrouter 配了什么排队策略，都到不了它头上。

本插件 1.5.0 解决了这个问题：

转发补丁（patches/）：给已安装的 dsh-vision-toolkit/lib/image-input-variants.js 加上 providerRetryPolicy() 转发方法，让包装路由继承上游的排队策略。用 mask_client action=patch（或设置页的补丁按钮）一并写入，也可手动执行：
```
node node_modules/dsh-client-masquerade/patches/apply-variant-retry-patch.mjs
```
然后重启 dsh web。补丁状态在插件启动时自检，并显示在设置页与 list 输出里。
queue 动作支持变体路由：mask_client action=queue provider=vision-toolkit-anyrouter state=on 会自动映射到上游 anyrouter 写策略（返回里带 upstream 字段）。
list 输出 registeredRoutes：列出所有已注册路由（含 vision-toolkit-* 变体）及其 registrationRetryPolicy——一眼就能确认 vision-toolkit-anyrouter 是否已继承排队策略（应显示 maxRetries=10 / maxDelayMs=30000）。

诊断时用 mask_client action=list 看 registeredRoutes 里 vision-toolkit-anyrouter 的策略；若仍是 maxRetries=5，说明转发补丁还没生效（重启后生效）。

使用 / Usage

设置页：顶部「路由」下拉选 provider，四格摘要（身份伪装 / 请求体 / 排队 / 补丁）先给出该路由的当前全貌；下面每张卡片各管一件事——身份伪装用分段控件在 Claude Code / Codex / 关闭之间切换，右上角 测试调用 验证是否真的生效；请求体伪装 与 排队适配 各一个开关，并展示哨兵工具、生效中的重试策略字段（含「agent 循环已生效」判定）；运行时补丁 一行一个补丁及其状态，安装模式可全部应用 / 全部还原；当前请求头默认折叠。

模型工具 mask_client：

mask_client action=list
mask_client action=on provider=agen-openai preset=codex
mask_client action=on provider=agen-openai preset=custom headersJson={"originator":"codex-tui"}
mask_client action=off provider=agen-openai
mask_client action=test provider=agen-openai
mask_client action=body provider=anyrouter state=on
mask_client action=body provider=anyrouter state=off
mask_client action=queue provider=anyrouter state=on
mask_client action=queue provider=anyrouter state=off

on 采用合并语义：保留你原有的其他请求头，仅覆盖预设拥有的键；headersJson 可追加/覆盖任意头。切换预设不会关掉请求体伪装。
off 删除预设拥有的键和请求体伪装开关（"这条线路不再伪装"），你手工配置的头会保留。
test 通过 ctx.llm.stream 真实调用该路由（默认用 provider 的第一个模型，可用 model= 指定），返回 effectiveWireHeaders（线上实际收到的头）、bodyMasquerade / bodyMasqueradeLive、模型首段输出或网关报错；会带退避重试以骑过排队窗口，并附上 classification / disguiseImplicated（见上文）。
body 写/删 provider 的请求体伪装开关（state=on|off）。
queue 写/删 provider 的 retryPolicy（state=on|off，可选 retries=、maxdelay= 覆盖）。

诊断某个网关是否按请求体识别客户端（换网关、或怀疑指纹过期时）：

node test/body-fingerprint-probe.mjs --host anyrouter.top --key-env ANYROUTER_API_KEY [--proxy 127.0.0.1:7890]

它手工构造请求、逐项消融、轮转发送，并在首尾各发一次对照请求——对照结果不一致就判定本轮不可信并要求重跑，而不是把网关的状态漂移当成结论。输出会直接告诉你该网关卡在哪一项，以及当前指纹还能不能通过。

仓库结构 / Repository layout

文件	用途
`index.js`	安装模式 Host 插件（cordis 主入口：`name` + `apply`）
`client.js`	安装模式 Web 客户端 bundle（`__ModuleLoader__` 格式，设置页）
`cordis.patch.yml`	bundle patch：`dsh plugin add` 后自动挂载的插件行
`host.body.js` / `client.body.js`	动态插件模式的 paste-ready 代码体
`plugin.js`	动态代码体编程加载器（剥离注释头）
`patches/patch-lib.js`	三个补丁的文本与 apply/revert 逻辑（Host 插件与 CLI 共用，避免漂移）
`patches/claude-code-fingerprint.js`	抓包得到的 Claude Code 请求体指纹（身份 system 块 + 哨兵工具定义）
`patches/apply-*.mjs`	三个补丁各自的手动 CLI（均支持 `--revert` / `--target`）
`test/body-fingerprint-probe.mjs`	消融诊断：判断某网关是否按请求体识别客户端、当前指纹是否还有效
`test/*.test.js`	单元测试（`npm test`）

限制 / Limitations

仅作用于 llm-pi-ai 自定义 provider；内置 deepseek-official 适配器没有请求头钩子，无法用此方式伪装。
预设现在包含 user-agent；未打 patches/ 补丁时，user-agent 仍会被归属机制覆盖（其余身份头不受影响）。此时 test 会额外返回 warning，明确告知伪装 UA 实际没有上线。
伪装头会真实写入设置文档并持久化；停用插件不会自动撤销，需要执行 off 或清除 provider 的 headers 字段。
请求体伪装的哨兵工具是"告知但未实现"的：模型看得到 Glob/Grep/Read，DSH 执行不了。它们都是只读工具，误调只会让那一步失败，但这确实是真实代价——只在需要它的线路上开。
请求体伪装只针对 Anthropic 协议（api: anthropic-messages）。补丁改的是 pi-ai 构造 Anthropic 请求体的地方，OpenAI 兼容协议的路线不受影响，也不需要。
指纹会过期。当前指纹认的是工具名 Glob/Grep/Read（描述不参与校验）。Claude Code 若给这几个工具改名，伪装会失效，且失败表现和"网关繁忙"一模一样——用 test/body-fingerprint-probe.mjs 判断是哪种。
排队不等于失败：上游渠道耗尽时的 429/503 对真实 Claude Code 同样返回。但反过来不成立——先确认请求体伪装已生效，再把 429/503 当成排队。

License

MIT