dsh-web-fetch-proxy

为 DSH ctx.web 增加一个代理出网的 web_fetch provider(id http-proxy): 所有请求经一个显式配置的 HTTP(S) 代理(undici ProxyAgent)发出,由代理负责 域名解析与出网。用于本机代理采用 fake-ip/TUN DNS 的环境——内置本地 provider 在连接前校验「公网单播 IP」,而 fake-ip 会把所有域名解析为 198.18.0.0/15 保留段,导致任意网页都报 resolves to a non-public IP address。本插件不改 DSH 核心,纯注册表扩展。

安装

npx --yes github:shaomingbo/dsh-web-fetch-proxy#v0.1.2

无参数等同 install,默认 profile 为 web;另提供幂等的 install、只读 status、uninstall 与 --profile <name>、--source link:<本地路径>、--help。 安装器要求 PATH 中存在 dsh 0.1.2-alpha.3 或 0.1.5-rc.1(仅接受这两个 精确版本,dsh --version 逐字核验,不兼容即失败并给出定位办法)与 pnpm, 所有依赖操作经官方 dsh plugin --profile <name> add ... --ignore-scripts 完成, 不手改 manifest、不回退;安装器不管理 DSH 进程生命周期——Bundle 集合变化后 手动重启对应 profile,Web 端强刷新现有 GUI。安装器兼容范围:上列两个精确 CLI 版本,各自经一次性 DSH_HOME 中的真实 launcher 走完官方 absent→install→ reinstall→status→uninstall→repeated-uninstall 闭环(见 test/installer.test.mjs);其他宿主版本未知,安装器会拒绝。

本地开发可用 --source link:<checkout>;link: 验收不能替代正式 tag 的 安装闭环。换装边界:本插件无 HMR 承诺,候选变更需重启并强刷新。

发布固定 tag 之前,可先用 lab 候选 tgz 经官方 CLI 安装(见 CHANGELOG)。

配置与接线(仅 profile patch 层,零核心改动)

# 1) 插件条目(其 cordis.patch.yml 已 insert;这里补 config)
- id: web-fetch-proxy
  config:
    proxyUrl: http://127.0.0.1:7890
    # 可选,与内置 provider 同默认值:
    # maxResponseBytes: 5000000
    # maxBodyChars: 100000
    # timeoutMs: 30000
    # maxRedirects: 5
    # userAgent: deepseek-harness/0.0.1 (+https://github.com/deepseek-ai)

# 2) 把 web seam 的 fetch provider 指到本插件
#    注意:entry patch 的 config 是整项替换,必须保留原有字段。
- id: web
  config:
    searchProvider: deepseek-official
    fetchProvider: http-proxy

proxyUrl 必填且在加载时校验(仅 http/https、不得内嵌凭据),配置缺失或非法 fail loud;不做隐藏 env 兜底。回退:删除上面两段 patch 即恢复内置 provider。

安全语义(与内置 provider 的差异,需明读)

• 出网与 SSRF 边界:内置 provider 解析域名并要求全部地址为公网单播,再把 连接钉死到已验证地址;本 provider 不做本地 DNS 校验,解析完全交给所配置 的可信代理。代理即信任边界:给什么代理地址,就信任该代理的解析与路由。
• 匿名性保留:不带 cookie、不带环境凭据、URL 不得内嵌凭据(与内置一致); User-Agent 为显式产品标识,不伪装浏览器。
• 重定向:仅跟随同源重定向(与内置一致,预算内);跨源重定向拒绝并提示直接 请求目标 URL。
• 限额:与内置 provider 相同的默认值——5 MiB 字节上限(超限截断, Content-Length 超限直接拒绝)、100k 字符截断、30s 超时、5 跳重定向。

错误码

普通 ProxyFetchError(带 code),词表与 ctx.web seam 一致: WEB_INVALID_URL、WEB_BLOCKED_URL、WEB_REDIRECT_BLOCKED、 WEB_UNSUPPORTED_CONTENT_TYPE、WEB_FETCH_TOO_LARGE、WEB_FETCH_TIMEOUT、 WEB_ABORTED、WEB_PROVIDER_ERROR。工具端以 isError 结果呈现,不中断会话。

验证矩阵(本候选,lab 实测)

• 单测:node --test test/(本地 fixture:URL 校验、限额、content-type、 charset、同源/跨源重定向、hop 上限、超时、插件注册与 agent 释放)。
• 真实出网:develop dsh-web-fetch-proxy smoke:proxy — 经 127.0.0.1:7890 抓取 registry.npmjs.org 与 example.com,并验证死代理 fail-closed。
• 组合与启动:lab install test → dump test(组合含 fetchProvider: http-proxy)→ serve test 真实加载。
• 0.1.5-rc.1 适配:工具入口 pipeline 测试直接只读加载隔离 0.1.5-rc.1 前缀的 公开包——真实 ToolRuntime/WebRuntime、发布版 web_fetch、默认 http provider 与本插件并存,错选/漏配 fetchProvider 走默认 provider 的 真实网络边界(loopback 拒绝)与 seam 的歧义拒绝;安装器对 0.1.5-rc.1 launcher 跑同样的官方 CLI 闭环。

已知限制

• 代理本身必须可信:代理可观察并篡改全部请求与响应,本插件不做端到端校验。
• dump-config/启动 smoke 与 GUI 验证过的宿主组合:CLI 0.1.2-alpha.3, Web/Base 0.1.2-rc.1,Node 24.18.0。0.1.5-rc.1 上未做 dump-config/启动 smoke/GUI 验收,已验证范围限于安装器官方 CLI 闭环与工具入口 pipeline 测试; 其他宿主版本未验证,未知。
• 未承诺 HMR;更换候选后需重启对应 profile 并强刷新 GUI。