dsh-proxy-routing

English | 中文

DeepSeek Harness 网络出口路由插件：按需接入环境中已经运行的 HTTP 或 SOCKS5 代理，按每次执行路由 shell 命令和 LLM provider 流量，不修改宿主进程环境。

本插件不提供网络代理功能，不创建代理服务，不管理节点、订阅或分流规则。使用前，运行环境中必须已经有可访问的 HTTP 或 SOCKS5 代理端点。

功能概览

• 接入本机已有的 HTTP（包括 CONNECT）或 SOCKS5 代理。
• 默认保持直连；NO_PROXY 默认排除回环地址和 api.deepseek.com。
• 覆盖 Bash/PowerShell 的前台、后台子进程，包括嵌套的 git、curl、npm、pnpm。
• 支持按 provider 路由 LLM 流，并隔离并发的直连流与代理流。
• 配置通过官方 proxy-routing settings namespace 持久化到 $DSH_HOME/settings.yaml，修改后无需重启 DSH 即可生效。
• Web 客户端可在现有 Settings → General → Network Proxy 行中编辑 namespace、测试端点并选择发现候选；诊断不会自动启用代理。
• Full Access Agent 会话可通过 net_proxy_discover 主动检查代理环境变量和有限的本机端口；受限会话会 fail closed，改为向用户询问 protocol/host/port。
• 启用或停用代理路由属于网络行为变更，需要人类审批（Full Access 权限等级除外）。

痛点与适用场景

典型案例

场景	直连时的痛点	本插件的作用
gh repo clone、git clone 拉 GitHub 仓库	Failed to connect to github.com port 443: Connection timed out	启用代理后，Agent 每次执行的 git/gh 子进程自动携带 HTTP(S)_PROXY，无需改 ~/.gitconfig 或 git config http.proxy
curl/wget 下载外网文件	下载卡死或中断（connect timed out）	由 DSH 启动的命令行子进程继承注入的代理环境，前台、后台执行都生效
Agent 用 npm/pnpm/cargo 装依赖	ETIMEDOUT、ESOCKETTIMEDOUT、依赖下载中断	依赖安装子进程自动走代理；已有镜像源时仍建议优先配置镜像
LLM provider API 域名受限或被限流	对话流中断、provider 不可达	按 provider 配置代理路由，其余直连流量不受影响
docker pull 拉镜像	dial tcp ... i/o timeout、net/http: TLS handshake timeout	不适用：镜像由 Docker daemon 拉取，不经本插件路由；需在 Docker Desktop / daemon 配置代理或 registry mirror

不适用场景

• Docker daemon 的镜像拉取与构建（docker pull、BuildKit 侧网络）。
• 浏览器、WinHTTP/WinINET 应用等不读环境变量代理的程序。
• 由插件自行搭建或提供代理服务：本插件只接入环境中已经运行的代理。

安装

版本 0.4.2 已发布到 npm，也可从 GitHub Release 获取预构建 tarball。请根据你的使用方式选择下面的安装路径。

通过 DSH 安装（推荐）

将插件安装到 web profile：

dsh plugin --profile web add [email protected]

如使用其他 profile，请将 web 替换为对应名称。该命令会更新 profile 的 package manifest 和 bundle 列表，使 DSH 能够加载插件。已经运行的 DSH 在安装后需要重启一次，才能重新组合 loader 并注册 net_proxy_* 工具。DSH 插件命令要求 PATH 中可用 pnpm。

通过 npm 安装

将已发布包安装到 npm 管理的项目中：

npm install [email protected]

这会把插件作为 Node 依赖安装。单独通过 npm 安装不会自动把插件加入 DSH profile 或 bundle 列表；普通 DSH 用户应使用上面的 DSH 安装命令。只有在宿主应用或自定义 profile 自行管理依赖时，才使用 npm 安装路径。

从本地 checkout 安装（仅开发）

将插件目录以绝对路径加入 profile 的 cordis.patch.yml：

- insert:
    - id: proxy-routing
      name: '/path/to/dsh-proxy-routing'

首次使用配置

安装时不会自动启用代理，这是有意设计：插件只接入已经运行的 HTTP 或 SOCKS5 代理，不启动代理服务，也不会静默猜测端点。

• Full Access Agent 会话可调用 net_proxy_discover。它检查代理环境变量和有限的常见本机端口，只返回探测成功的候选；启用前仍需确认候选用途。
• 受限 Agent 会话会拒绝主动扫描。请先向用户询问已经运行的代理 protocol、host、port，再调用 net_proxy_probe。
• Web 端使用 Settings → General → Network Proxy。发现本机代理 和 测试连接 都是只读诊断；选择或保存候选不会自动启用路由。
• 探测成功后，用同一端点请求 net_proxy_enable。Full Access 等级会直接生效，较低权限等级需要人类批准。
• 使用 net_proxy_status 检查当前生效路由；需要恢复直连时调用 net_proxy_disable。

也可以手动编辑下方的 proxy-routing YAML，写入代理端点和 profile 路由。Web 诊断通过官方 loopback Connection RPC 提供，不会向浏览器返回代理凭据。

重启与热更新边界

这里有四套不同机制：

• 安装或移除插件：dsh plugin ... add/remove 修改的是 profile 文件。已经运行的进程不会重新扫描这些文件，也不会重建 Cordis loader tree，所以首次注册或移除后必须重启。
• 插件 Host 代码：官方 Cordis module HMR 支持卸载旧 fiber、清理 effects/registrations、重新导入并执行插件。它要求启用 HMR service、root 覆盖源码、timer 和 loader internals 可用，并由带必要 Node internals 的开发宿主运行。普通 Web profile 当前明确将共享 HMR 行设为 disabled: true，原因是 Web reload lifecycle 仍标记为未测试；这是 Web composition 的部署决定，不是插件一般不能 HMR。
• 插件 Client 代码：Web profile 仍挂载 @deepseek-ai/dsh-client-hmr。从同一 DSH checkout 运行 pnpm run dev:web 时，本插件 lib/client.js 的变更可以通过 browser module graph 热更新而无需刷新页面；没有 watcher 时仍需重建 client artifact 并刷新。
• settings YAML：官方 settings-file provider 会监听 $DSH_HOME/settings.yaml。插件成功加载后，修改 proxy-routing section 可以在运行时应用，不需要重启 DSH。

配置

默认状态

全新的 v2 settings namespace 会解析为默认配置结构，能够在不配置代理时直接以直连方式工作：

• Agent 默认路由为直连：bindings.agent.kind = "direct"。
• default profile 默认包含 noProxy 和 timeout 配置，但不包含实际代理端点。
• noProxy 默认排除 127.0.0.1、localhost、::1 和 api.deepseek.com。
• timeout 默认是 60000 毫秒。
• 网络代理的 protocol、host、port 必须由用户提供，并指向环境中已经运行的代理服务。
• 已存在的 proxy-agent.json 会被忽略。本版本不会自动迁移旧的私有文件格式；如需保留配置，请手动复制到 YAML namespace。

因此，插件安装后即可开箱使用直连能力；只有需要代理出口时，才需要用户配置代理端点。

配置 Schema

官方 DSH settings provider 会将这一 namespace 保存在 $DSH_HOME/settings.yaml 中（未设置 DSH_HOME 时回退到 ~/.dsh/settings.yaml），并保留同一文档中的其他 settings namespace。下面是 v2 canonical YAML 结构：

proxy-routing:
  version: 2
  profiles:
    - id: default
      protocol: http
      host: 127.0.0.1
      port: 7897
      username: ""
      password: ""
      noProxy: [127.0.0.1, localhost, ::1, api.deepseek.com]
      timeout: 60000
  bindings:
    agent:
      kind: direct
      # 使用 profile 时还需：profileId: default
    providers: []
    gateway: null
    gatewayPurposes: []
  gateway:
    enabled: false
    port: 17890
    dedicatedPurposePorts: false
    purposes: []

其中 protocol、host、port 必须指向环境中已经运行的代理服务。插件通过 ctx.settings 注册 namespace；YAML 解析、原子写入、锁和热更新由官方 settings-file provider 负责。插件不会读取、写入、监听或迁移 proxy-agent.json。

端点未配置时的固定指引：

代理端点未配置：Full Access 会话请运行 net_proxy_discover 查找已运行代理；受限会话请向用户询问 protocol/host/port 后运行 net_proxy_probe，再请求 net_proxy_enable。

Agent 安装指南

Agent 只负责发现并请求使用已经存在的代理，不负责启动代理服务。推荐流程：

1. Full Access 会话先调用 net_proxy_discover；它只检查代理环境变量和有限的本机候选端口。受限会话不要主动扫描，先向用户询问 protocol、host、port。
2. 外部请求、抓取或下载失败时，调用 net_proxy_status，确认 default 是否已配置。
3. 调用 net_proxy_probe 测试当前或临时端点；未配置端点时不要猜测地址。
4. 使用端点信息请求 net_proxy_enable；Full Access 等级下直接生效，其他等级等待人类批准后再重试失败操作。
5. 需要恢复直连时，请求 net_proxy_disable。显式 provider 覆盖不会被清除。

权限分级

权限等级	net_proxy_enable / net_proxy_disable 行为
Full Access（danger-full-access）	无需询问用户，直接生效
其他等级（read-only / workspace-write 等）	需要人类批准后生效

只读工具 net_proxy_status / net_proxy_probe / net_proxy_discover 在任何等级下都无需审批。

可用工具：

工具	审批	用途
net_proxy_status	只读	查看配置修订号、端点是否已配置、Agent 生效路由、provider 覆盖、fetch 归属和持久 shell 代际；可用 verify 探测连通性。
net_proxy_probe	只读	使用当前或临时端点测试链路，不修改配置。
net_proxy_discover	仅 Full Access	检查代理环境变量和有限的本机候选端口，只返回探测成功候选，不启用或持久化路由。
net_proxy_enable	需要审批（Full Access 除外）	将 Agent 路由指向 default；可更新端点字段并持久化。
net_proxy_disable	需要审批（Full Access 除外）	将 Agent 路由恢复直连；provider 覆盖和端点配置保留。

开发与测试

pnpm install
pnpm test
pnpm run build:client
pnpm run probe

pnpm run build:client 会生成 Web module-loader 使用的 lib/client.js。开发 client HMR 时，从同一 DSH checkout 运行 pnpm run dev:web；没有 watcher 时，重建 client artifact 后刷新注入 DSH Web 页面。

测试覆盖 HTTP/CONNECT/SOCKS5、超时、背压、NO_PROXY、重定向、探测与有限发现、审批门禁、settings schema 校验与 YAML 热更新、loopback RPC 校验、补偿事务、fetch/LLM/shell 隔离、HMR/dispose 幂等和真实子进程继承。

参考

• 传输层参考：mafeis/dsh-net-proxy（MIT）。
• 配置命名参考：@cordisjs/plugin-proxy-agent。

许可证

MIT