dsh-proxy-switch
给 DeepSeek Harness(下称 DSH)用的代理开关:一条命令在「直连」和「走代理」之间切换,不用重启进程。
/proxy on 走代理(模型、搜索、抓取、子进程一起)
/proxy off 立刻回直连
它解决什么问题
DSH 的网页抓取工具(web_fetch)在发请求前会先解析域名,拿到非公网地址就直接拒绝:
URL hostname "nodejs.org" resolves to a non-public IP address
本机开着 TUN / fake-ip 的代理软件时(clash、sing-box 之类),DNS 会被劫持成 198.18.x.x 这类保留地址,于是所有抓取都失败——哪怕代理其实通得很好。DSH 不会把请求交给网络栈去试,它自己先判死刑。
翻 DSH 的抓取器源码可以看到那个逃生口:走代理的请求会跳过这项 IP 校验。所以解法是「需要抓外网时让 DSH 走代理」。
麻烦在于 DSH 的代理只在启动时读一次环境变量:@deepseek-ai/dsh-http-proxy 在 undici.setGlobalDispatcher() 里把进程的全局 dispatcher 换掉,之后改环境变量没用,必须重启。
这个插件把「重装 dispatcher」做成运行时可调:它在进程内直接调用同一个模块的 installProxyFromEnvironment(),切换对整条出站链路立即生效。
怎么工作
flowchart LR
A["/proxy on"] --> B{"探测核心端口"}
B -->|通| C["installProxyFromEnvironment()<br/>装代理 dispatcher"]
B -->|不通| D["保持直连<br/>状态标成降级"]
C --> E[("undici 全局 dispatcher")]
D --> E
E --> F["模型请求"]
E --> G["web_search"]
E --> H["web_fetch"]
E --> I["子进程"]
三个关键点:
- 共用同一个模块实例。插件必须解析到宿主加载的那一份
@deepseek-ai/dsh-http-proxy,因为proxyRouteFor()读的是该模块的模块级状态。解析走三级兜底,命中哪一级会写进日志(见排错)。 - 直连 ≠ 什么都不做。DSH 的代理模块对「没有代理配置」有专门分支,会装一个直连 Agent;插件照这个分支走,所以直连时和没装插件时行为一致,不会残留代理设置。
- 状态放文件里。
~/.dsh/proxy-switch.json是唯一真相:斜杠命令、命令行工具、手改文件三条路都写它,插件用fs.watch跟随,约一秒内生效。
安装
前置条件
- 已装 DSH,能挂 profile 插件(有
~/.dsh/profiles/<名字>/cordis.patch.yml)。 - 一个 HTTP 代理,默认按 clash 的混合端口
http://127.0.0.1:7890。不是这个端口的话装完改配置,或用/proxy url <地址>。 bash、node(DSH 自带)、python3(仅命令行工具和安装脚本用到)。
一条命令
git clone https://github.com/k-ying/dsh-proxy-switch.git
cd dsh-proxy-switch
./install.sh
不是 ~/.dsh/profiles/web 这个 profile 的话:
DSH_PROFILE_DIR=~/.dsh/profiles/other ./install.sh
装完重启一次 DSH(新插件要重新加载;已经装好之后在会话里切换则完全不用重启)。
它装了哪三样东西
| 位置 | 作用 |
|---|---|
~/.dsh/profiles/web/plugins/dsh-proxy-switch/ |
插件本体(index.js + package.json) |
~/.dsh/profiles/web/cordis.patch.yml |
末尾追加一段 - insert:,把插件挂进 profile;改动前自动备份成 cordis.patch.yml.bak.<时间戳> |
~/.local/bin/dsh-proxy |
命令行工具,DSH 没开也能切 |
验证
重启后在会话里打 /proxy status,或直接在终端:
dsh-proxy status
看到「配置 / 核心 / 文件」三行就对了。
使用
会话内
| 命令 | 作用 |
|---|---|
/proxy status |
看配置与实际生效状态(含降级原因) |
/proxy on |
走代理,先探核心端口,不通就不切 |
/proxy on force |
不探测,硬切 |
/proxy off |
立刻直连 |
/proxy toggle |
在两者之间切换 |
/proxy url <地址> |
改代理地址;正在走代理时会先验证新地址可用,不可用则拒绝且不动现有配置 |
/proxy test |
用当前路由真打一次 https://www.gstatic.com/generate_204,返回状态码和耗时 |
命令行
DSH 没开、或者想用快捷键/脚本切的时候用:
dsh-proxy # 同 status
dsh-proxy on # 走代理(探测端口)
dsh-proxy on! # 强制走代理
dsh-proxy off
dsh-proxy toggle
dsh-proxy url http://127.0.0.1:7890
它只写状态文件,DSH 开着的话会自己跟上;没开的话下次启动按文件生效。
典型场景
抓外网前开一下,抓完关掉
/proxy on
# ... 抓 https://nodejs.org、GitHub raw 之类 ...
/proxy off
一直是代理,只是偶尔要连内网:那就一直开着,NO_PROXY 默认已经把回环地址排除掉,本地服务不受影响。
换个代理端口:/proxy url http://127.0.0.1:7891,然后 /proxy on。
配置
在 cordis.patch.yml 里改:
- insert:
- id: proxy-switch
name: ./plugins/dsh-proxy-switch/index.js
config:
proxyURL: http://127.0.0.1:7890
| 字段 | 默认值 | 含义 |
|---|---|---|
proxyURL |
http://127.0.0.1:7890 |
代理核心地址,状态文件里没写 URL 时用它 |
statePath |
~/.dsh/proxy-switch.json |
状态文件位置 |
noProxy |
localhost,127.0.0.1,::1,[::1] |
走代理时的 NO_PROXY |
probeTimeoutMs |
800 |
端口探测超时 |
httpTimeoutMs |
10000 |
/proxy test 的超时 |
logPath |
~/.dsh/proxy-switch.log |
运行日志 |
modulePath |
空 | 手动指定 dsh-http-proxy 的入口文件;自动推导失败时才需要 |
状态文件长这样,手改同样生效:
{
"mode": "proxy",
"proxyURL": "http://127.0.0.1:7890"
}
行为约定
- 默认直连。没有状态文件时按直连启动,和没装插件时完全一样。
- 代理没开会降级,不会把 DSH 弄坏。
/proxy on先探 TCP 端口;clash 没启动就保持直连,状态里显示「配置:走代理 / 实际:直连」并给出原因,配置意图保留,等核心起来再/proxy on即可。 - 启动时同样降级。状态文件写着 proxy 但核心没起,自动直连,不覆盖状态文件。
- 切换失败会回滚。退回到上一个可用状态,不会停在半代理半直连。
- 直连不污染环境。直连模式不写任何
*_PROXY环境变量;代理模式会写(子进程因此也走代理),关闭时还原。 - 只影响本进程。不碰系统代理设置、不碰 clash 配置。
目录结构
dsh-proxy-switch/
├── index.js # 插件主体:状态、探测、切换、斜杠命令
├── bin/
│ └── dsh-proxy # 命令行工具,直接改状态文件
├── install.sh # 装配脚本:复制插件、挂 patch、装 CLI
├── package.json # 插件清单(dsh.plugin 标记 + bin 声明)
├── README.md
├── LICENSE
└── .gitignore
各文件职责:
| 文件 | 作用与关键点 |
|---|---|
index.js |
插件入口,export const name + export function apply(ctx, config)。负责:读写状态文件并 fs.watch 跟随、probeTcp() 探端口、proxyEnv() 把状态翻译成 installProxyFromEnvironment() 需要的 env 快照、load() 三级解析宿主模块、注册 /proxy 命令(ctx.inject(['commands'], ...))、dispose 时还原直连 |
bin/dsh-proxy |
纯 bash + python3,只读写 ~/.dsh/proxy-switch.json。用 /dev/tcp 探端口所以不依赖 nc;不需要 DSH 在跑 |
install.sh |
幂等。复制插件文件 → 检查 patch 里有没有 proxy-switch → 追加 - insert: 段(先备份)→ 机会性用 PyYAML 校验,失败则回滚 → 装 CLI |
package.json |
"type": "module" 和 dsh.plugin: true 让 DSH 认得它是插件;bin 声明给 npm 用 |
插件运行时产出两个文件(都不在仓库里):
| 文件 | 内容 |
|---|---|
~/.dsh/proxy-switch.json |
当前模式与代理地址 |
~/.dsh/proxy-switch.log |
模块加载层级、每次切换结果、降级原因 |
排错
/proxy 命令不存在 → 插件没加载。先看日志:
cat ~/.dsh/proxy-switch.log
- 有「代理模块加载成功(模块名 / pluginPackages / 安装目录)」→ 加载没问题,多半是没重启 DSH。
- 有「加载 @deepseek-ai/dsh-http-proxy 全部失败」→ 说明 DSH 的安装布局变了。设
modulePath指到<DSH 安装目录>/node_modules/@deepseek-ai/dsh-http-proxy/lib/index.js即可。 - 日志文件根本不存在 → 插件压根没被加载,检查
cordis.patch.yml末尾那段是否还在、路径对不对。
切换了但抓取仍失败 → /proxy test 看当前路由。如果显示「实际:直连」,说明降级了(核心没通)。
改完 patch 没反应 → 新增插件条目需要重启 DSH 才生效;插件已经加载之后,/proxy 的切换才是实时的。
卸载
rm -rf ~/.dsh/profiles/web/plugins/dsh-proxy-switch
再把 cordis.patch.yml 末尾那段 - insert:(id: proxy-switch)删掉,rm ~/.local/bin/dsh-proxy,重启 DSH。
开发
零第三方依赖,不需要构建:
node --check index.js
bash -n install.sh
想跑通全部子命令,最小做法是建个临时目录,把 node_modules/@deepseek-ai/dsh-http-proxy 软链到 DSH 安装目录里的同名包,再给插件一个假 ctx(只要能 inject(['commands']) 和 on() 就够)。
依赖与兼容性
插件直接调用 DSH 内部的 @deepseek-ai/dsh-http-proxy:installProxyFromEnvironment(env, report) 和 proxyRouteFor(url)。这是内部接口,DSH 大版本升级后如果签名变了,日志里的加载记录和 /proxy test 会第一时间暴露出来。
No comments yet. Be the first to write one.