looeton/dsh-plugin-proxy-env

dsh-plugin-proxy-env

DSH 插件：启动时自动注入代理环境变量，并自检整条代理链路。
一个 DeepSeek Harness 插件，在启动时注入代理环境变量，并自检整条代理链路。

CI
License: MIT
Node
dsh plugin

中文 · English

中文

这是什么

一个 DSH 插件，做两件事：

1. 启动时注入代理变量——把 HTTP_PROXY / HTTPS_PROXY / NODE_USE_ENV_PROXY / NO_PROXY 写进 harness 主进程的环境，之后所有子进程（shell、git、npm、python）自动继承，不用再 setx + 重启。
2. 自检——从本地端口一路查到端到端请求，把结论写进日志和报告文件；同时注册一个 proxy_env_check 工具，随时能再查一次。

为什么这样能生效

DSH 在派生子进程时从 process.env 构造子环境（dsh-subprocess 的 scrubbedParentEnv()，它只剔除名字含 KEY/PASSWORD/SECRET/TOKEN 的和 DSH_ 的变量，代理变量是刻意保留的）。所以插件在加载阶段写一次 process.env，后面每一次 spawn 都带着它——比手工 setx 更即时，也不依赖启动方式。

注入哪些变量

| 变量 | 值 | 作用 |
|---|---|---|
| HTTP_PROXY / HTTPS_PROXY | 解析到的代理地址 | curl / git / python / Go 等自动读取 |
| NODE_USE_ENV_PROXY | 1 | 子 Node 进程启动时即让内置 fetch 读取上面的变量 |
| NO_PROXY | 默认 localhost,127.0.0.1,::1,api.deepseek.com | 回环必须排除，否则本地 GUI 请求会被塞进代理；模型 API 排除后，代理挂掉也不影响对话 |

已存在的同名变量默认不覆盖（override: true 可强制）。

自检做什么

按「由近到远」的顺序，先报最上游的断点：

1. 代理端口是否监听
2. 端口是否应答 CONNECT（手工建隧道，不依赖 undici）
3. DNS 是否返回真实地址（识别 198.18.0.0/15 与 fdfe:dcba:9876::/64 的 fake-ip）
4. 直连探针 + 走代理探针（TLS 隧道）
5. 汇总结论：PASS / WARN / FAIL + 一条修复建议

结果写入 $DSH_HOME/proxy-env/report.json，agent 可以直接读取，不必调用工具。

安装

方式一：DSH Desktop 插件管理器（推荐）

设置 → 插件 → 安装，填入 dsh-plugin-proxy-env（发布到 npm 后可用）。

方式二：手动（从本仓库安装）

1) 进入当前 profile 目录
cd "$env:DSH_HOME\profiles\desktop"

2) 安装（本地路径、git 或 npm 均可）
pnpm add file:D:/path/to/dsh-plugin-proxy-env
或 pnpm add github:looeton/dsh-plugin-proxy-env

3) 把包名加进 package.json 的 dsh.profile.bundles
"dsh": { "profile": { "bundles": [ ..., "dsh-plugin-proxy-env" ] } }

4) 重启 DSH Desktop

方式三：先本地验证，不装进 profile

node src/cli.mjs            # 独立自检，跟插件走同一套代码
node --test tests/.test.mjs   # 52 个单元测试

配置项

通过 patch 行或 profile 的 cordis.patch.yml 传入：

- id: proxy-env
config:
proxyUrl: http://127.0.0.1:7897   # 留空则自动探测
noProxy: localhost,127.0.0.1,::1,api.deepseek.com
selfCheck: true
tool: true

| 键 | 默认 | 说明 |
|---|---|---|
| enable | true | 总开关 |
| proxyUrl | 自动 | 完整代理地址；留空则按 port → Windows 系统代理 → 已导出的环境变量顺序解析 |
| host | 127.0.0.1 | 本地代理主机 |
| port | 0 | 直接指定端口 |
| noProxy | 见上 | NO_PROXY 内容 |
| override | false | 是否覆盖已存在的同名变量 |
| patchGlobalDispatcher | true | 动态 import undici，把全局 dispatcher 换成 EnvHttpProxyAgent，让运行时的 Node 请求也走代理 |
| selfCheck | true | 启动时自检 |
| writeReport | true | 写 $DSH_HOME/proxy-env/report.json |
| tool | true | 注册 proxy_env_check 工具 |
| probeUrl | https://www.google.com | 只有走代理才通的探针 |
| directProbeUrl | https://example.com | 直连探针 |
| dnsHost | example.com | fake-ip 检测域名 |
| timeoutMs | 15000 | 单个探针超时 |

提供的工具

| 工具 | 参数 | 返回 |
|---|---|---|
| proxy_env_check | probe_url、skip_network | 一行结论 + 完整链路文本 |

局限

- 它管的是进程环境，不是 web_fetch。DSH 的 web_fetch 用固定 IP 的自定义 undici Agent（防 SSRF / DNS rebinding），刻意绕过全局 dispatcher，所以即使代理正常它也不会走代理——这是设计，不是本插件的缺陷。被墙站点请用能走云端的抓取工具，或让 agent 用 shell 里的 node / python 抓。
- 注册表读取依赖 reg.exe，且用文件重定向而非管道（受限令牌沙箱里管道会 EPERM）。读不到时自动回退到已导出的 HTTPS_PROXY / HTTP_PROXY。
- 非 Windows 只走配置和环境变量，不读系统代理。
- patchGlobalDispatcher 是运行时切换：它需要能解析到 undici，且版本要有 EnvHttpProxyAgent（唯一会遵守 NO_PROXY 的实现）；不满足时跳过并在日志里说明。

相关项目

- clash-verge-system-proxy —— 手工版完整指南（关 TUN、开系统代理、写变量、排错手册）
- proxy-doctor —— 独立的 PowerShell 诊断工具，不装插件也能用

English

这是什么

一个 DSH 插件，做两件事：

1. 启动时注入代理变量 —— 把 HTTP_PROXY / HTTPS_PROXY / NODE_USE_ENV_PROXY / NO_PROXY 写入 harness 宿主进程，这样每个子进程（shell、git、npm、python）都会继承它们。无需 setx，无需重启折腾。
2. 自检整条链路 —— 从本地端口一路走到真实请求，记录结论，写一份报告文件，并注册一个 proxy_env_check 工具用于按需重跑。

为什么这样可行

DSH 在生成每个子进程环境时，会从 process.env 构建（dsh-subprocess 里的 scrubbedParentEnv() 会剥掉凭据形状的变量名和 DSH_，但有意保留代理变量）。因此，在插件加载时写一次 process.env，就能覆盖之后每一次 spawn —— 立即生效，且与 app 的启动方式无关。

它注入了什么

| 变量 | 值 | 用途 |
|---|---|---|
| HTTP_PROXY / HTTPS_PROXY | 解析出的代理 URL | 被 curl、git、python、Go 等读取 |
| NODE_USE_ENV_PROXY | 1 | 让子 Node 进程从 bootstrap 起就遵守上面两个变量 |
| NO_PROXY | localhost,127.0.0.1,::1,api.deepseek.com | 回环地址必须排除，否则本地 GUI 请求会走代理；模型 API 也排除，这样代理挂了也不会断聊天 |

已有值不会被改动，除非 override: true。

自检做了什么

由近及远，这样报告总能指出最早断掉的那一环：

1. 代理端口是否在监听
2. 它是否响应 CONNECT（手搓隧道，不需要 undici）
3. DNS 是否返回真实地址（检测 198.18.0.0/15 和 fdfe:dcba:9876::/64 fake-ip）
4. 直连探针 + 走代理探针（TLS 隧道）
5. 一个结论 —— PASS / WARN / FAIL —— 外加一条修复建议

报告落在 $DSH_HOME/proxy-env/report.json，agent 无需工具调用即可读取。

安装
选项 1 — DSH Desktop 插件管理器（推荐）：Settings → Plugins → Install，然后安装 dsh-plugin-proxy-env（发布到 npm 后即可使用）。

选项 2 — 手动方式，从本仓库安装

cd "$env:DSH_HOME\profiles\desktop"
pnpm add file:D:/path/to/dsh-plugin-proxy-env   # 或 github:looeton/dsh-plugin-proxy-env
将 "dsh-plugin-proxy-env" 添加到 package.json 中的 dsh.profile.bundles
重启 DSH Desktop

选项 3 — 本地验证，无需安装

node src/cli.mjs            # 独立自检，与运行时相同的代码路径
node --test tests/.test.mjs   # 52 个单元测试

配置

- id: proxy-env
config:
proxyUrl: http://127.0.0.1:7897   # 留空 = 自动检测
noProxy: localhost,127.0.0.1,::1,api.deepseek.com
selfCheck: true
tool: true

| 键 | 默认值 | 用途 |
|---|---|---|
| enable | true | 总开关 |
| proxyUrl | 自动 | 完整的代理 URL；留空时顺序为 port → Windows 系统代理 → 已导出的环境变量 |
| host | 127.0.0.1 | 本地代理主机 |
| port | 0 | 显式端口 |
| noProxy | 见上 | NO_PROXY 内容 |
| override | false | 覆盖已存在的变量 |
| patchGlobalDispatcher | true | 动态导入 undici 并将全局 dispatcher 切换为 EnvHttpProxyAgent，使运行时 Node 请求也走代理 |
| selfCheck | true | 启动时运行检查 |
| writeReport | true | 写入 $DSH_HOME/proxy-env/report.json |
| tool | true | 注册 proxy_env_check 工具 |
| probeUrl | https://www.google.com | 仅能通过代理访问 |
| directProbeUrl | https://example.com | 可直接访问 |
| dnsHost | example.com | 用于 fake-ip 检查的主机 |
| timeoutMs | 15000 | 每个探测的超时时间 |

它注册的工具

| 工具 | 参数 | 返回 |
|---|---|---|
| proxy_env_check | probe_url、skip_network | 一行结论加上完整链路报告 |

局限性

- 它覆盖的是进程环境，而不是 web_fetch。 DSH 的 web_fetch 使用自定义 undici Agent 固定连接（SSRF / DNS 重绑定防御），并按设计绕过全局 dispatcher，因此即使其他一切都走代理，它也不会使用代理。对于被屏蔽的站点，请使用基于云端的页面读取器，或让 agent 从 shell 中用 node / python 抓取。
- 读取注册表会调用 reg.exe，并将 stdout 重定向到临时文件而非管道（在受限令牌沙箱中管道会因 EPERM 失败）。无法读取时，回退到已导出的 HTTPS_PROXY / HTTP_PROXY。
- 非 Windows 主机仅使用配置和环境变量。
- patchGlobalDispatcher 是一个运行时开关：它需要 undici 能够解析，并且版本需包含 EnvHttpProxyAgent（唯一遵循 NO_PROXY 的变体）。否则会跳过并记录日志。

相关项目
- clash-verge-system-proxy — 手动配套指南（关闭 TUN，开启系统代理，变量，故障排除）
- proxy-doctor — 独立的 PowerShell 诊断，无需插件

开发

node --check src/.mjs      # 或：npm run check
npm test                    # 或：node --test tests/.test.mjs
node src/cli.mjs            # 针对当前机器进行自检

许可证

MIT