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 即可生效。
• 启用或停用代理路由属于网络行为变更，需要人类审批（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 应用等不读环境变量代理的程序。
• 由插件自行搭建或提供代理服务：本插件只接入环境中已经运行的代理。

安装

开发或本地使用时，将插件目录以绝对路径加入 profile 的 cordis.patch.yml：

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

发布后：

dsh plugin --profile web add github:<owner>/dsh-proxy-routing

安装后重启 DSH，使插件加载并注册 net_proxy_* 工具。

配置

默认状态

全新的 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。

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

代理端点未配置：请运行 net_proxy_enable 并提供 protocol/host/port，或在 Web 设置（Settings → Network Proxy）中配置代理地址。

Agent 安装指南

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

1. 确认运行环境已有可访问的 HTTP 或 SOCKS5 代理，并取得 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_status	只读	查看配置修订号、端点是否已配置、Agent 生效路由、provider 覆盖、fetch 归属和持久 shell 代际；可用 verify 探测连通性。
net_proxy_probe	只读	使用当前或临时端点测试链路，不修改配置。
net_proxy_enable	需要审批（Full Access 除外）	将 Agent 路由指向 default；可更新端点字段并持久化。
net_proxy_disable	需要审批（Full Access 除外）	将 Agent 路由恢复直连；provider 覆盖和端点配置保留。

开发与测试

pnpm install
pnpm test
pnpm run probe

测试覆盖 HTTP/CONNECT/SOCKS5、超时、背压、NO_PROXY、重定向、探测、审批门禁、配置迁移与校验、事务写入、fetch/LLM/shell 隔离、HMR/dispose 幂等和真实子进程继承。

参考

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

许可证

MIT