前言¶
在 DeepSeek Harness（DSH）里，模型经常通过 web_fetch、GitHub 工具或可选的纯搜索去拉取公网资源。若你希望只有部分域名走公司或本机 HTTP 代理，其余请求仍直连，又不想动模型请求、全局 fetch 或父进程的代理环境，全局接管类插件（例如 dsh-plugin-proxy / dsh-proxy-pro）往往过重。dsh-rule-proxy 由社区维护者 xiaoyi728 提供，用 hostname 规则为网页工具提供隔离传输：命中规则走你配置的上游，未命中或上游不可用时走独立直连，两条路径都不改写模型侧网络。
这是什么¶
dsh-rule-proxy 是 DSH 生态下的联网工具类插件（当前 GitHub 星标为 1）。一句话定位：按 hostname 规则为 DSH web 工具提供隔离的 HTTP(S) 代理通道，上游不可达时自动回退直连。插件未发布到 npm，源码与说明见 GitHub 仓库，社区目录页为 skillhub.cn/plugins/xiaoyi728/dsh-rule-proxy。DSH 采用「一切皆插件」的 Cordis 装配方式；skillhub 等目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
与全局代理插件的差异¶
下面几条是 README 中强调的设计边界，便于选型：
- 按规则分流，而非全局接管：通过
registerFetchProvider自持独立传输（每请求新建 Agent/ProxyAgent、公网 IP/DNS 钉选、NAT64 检查），不修改模型 provider、全局 fetch、全局 Undici dispatcher 或父进程代理环境。 - 上游不可用自动回退直连：命中规则优先走上游；上游未配置或连接失败时改走直连，不向工具报错，只有直连也失败才返回工具错误。
- 域名匹配策略：
domain类型按精确域名及子域匹配（github.com匹配api.github.com，不匹配notgithub.com）；regex类型用 RE2-WASM 线性时间匹配 hostname。 - 规则引擎内存安全：re2-wasm 编译实例无法释放（固定 16 MiB 堆），pattern 编译一次终身复用，配置快照按值比较，避免 OOM。
- 对话头部一键开关：每会话头部胶囊按钮（绿 = ON / 红 = OFF），与设置页共享同一状态 store。
- 干净卸载：仅释放本插件资源，不残留全局状态。
许可为 MIT；运行环境要求 Node >=22.19.0，DSH >=0.2.0-rc.2 <0.3.0（以 package.json 为准）。
核心功能¶
接管的请求范围¶
只接管命中规则的网页工具请求（web_fetch / GitHub 工具 / 可选的 SearXNG 纯搜索）。这些请求通过设置里的上游代理发出；未命中规则、或上游不可用时的回退请求，走插件自持的直连传输。模型请求、全局 fetch、全局 Undici dispatcher 和父进程代理环境均不被修改。插件不发送遥测；规则、代理地址和 proxyToken 只存在于 profile 配置文件中，proxyToken 永不通过接口回传。
普通 bash/git/gh、第三方 SDK 和 SSH 不自动代理。GitHub 工具不提供私有仓库凭据、clone、fetch、push。
模型侧工具¶
| 工具 | 说明 |
|---|---|
rule_proxy_diagnose({url, source}) |
不联网，返回路由与命中原因；source=model 表示不受插件管理 |
github_api_get({path}) |
匿名 GitHub API GET |
github_git_refs({repository}) |
公共 owner/repository 的 HTTPS Git 引用查询 |
设置与排障¶
「设置 → 工具规则代理」提供规则 JSON 编辑与导入（保存、导入前校验）、路由诊断（输入 URL 预览命中，不联网）。关闭「工具代理开关」后规则仍可匹配，但网页工具改为直连；这与 Cordis 的 disabled（整插件卸载）不同。
安装与启用¶
插件以当前 dsh 进程权限运行，安装前应自行检查源码与 MIT 许可证，并按 profile 权限保护配置文件（含 proxyToken）。
从 GitHub 安装（推荐）¶
dsh plugin --profile web add github:xiaoyi728/dsh-rule-proxy
GUI 中可在 插件 → 添加插件 粘贴仓库地址，例如：
https://github.com/xiaoyi728/dsh-rule-proxy
等价写法还包括 github:xiaoyi728/dsh-rule-proxy、https://github.com/xiaoyi728/dsh-rule-proxy.git 等。本插件没有 prepare / build 脚本，源码安装不会触发 pnpm 的 allowBuilds 构建授权。add dsh-rule-proxy（npm 名）目前不可用。
本地开发可在添加插件时填写仓库绝对路径。
挂接 web 的 fetchProvider¶
装完后需把 web 服务的 fetchProvider 指向 rule-proxy。DSH 原生 profile 使用 cordis.patch.yml，应将以下 patch 合并进 profile 现有 patch 数组（不要覆盖其他条目）：
- insert:
- id: rule-proxy
name: dsh-rule-proxy
- id: rule-proxy
config:
enabled: true
proxyUrl: http://127.0.0.1:7890
- id: web
config:
fetchProvider: rule-proxy
其中 web 须换成该 profile 实际 WebRuntime 的 entry id；proxyUrl 按你的上游修改。profile 需已有 web 服务，使用标准工具还需启用原生 tool-web。安装完成后启动 dsh web。
启用纯搜索时，在 @deepseek-ai/dsh-web 中另设 searchProvider: rule-proxy-searxng，并配置可选字段 searxEndpoint。
典型用法¶
会话头部开关¶
对话头部右侧「● 代理 ON/OFF」：绿点表示工具代理生效，红点表示关闭；一点切换总开关，悬停可看活动规则数与上游地址。
上游与认证¶
「上游 HTTP(S) 代理」须为 origin（不含路径、查询串、内嵌凭据）；暂不支持 SOCKS。需要认证时在 secret 字段 proxyToken 配置完整 Proxy-Authorization 值，接口永不返回该字段。
规则示例¶
规则为 JSON 数组，每项包含 include、type、title、pattern、active，只支持 include/regex 或 include/domain：
[
{ "include": "include", "type": "domain", "title": "GitHub domain", "pattern": "github.com", "active": true },
{ "include": "include", "type": "regex", "title": "OpenAI hosts", "pattern": "(^|\\.)openai\\.com$", "active": true }
]
规则只匹配规范化 hostname（小写、去尾点）。最多 256 项，pattern 最多 512 字符；宿主使用 RE2，不支持反向引用与先行断言，设置页会拒绝非法构造。默认规则随包 rules.json 提供。
本地路由诊断 CLI¶
不启动 GUI 时，可用包内脚本验证路由：
npm run diagnose -- https://github.com web-fetch rules.json
npm run diagnose -- https://api.openai.com model rules.json
配置字段摘要¶
配置由 Cordis profile 持久化，经设置页与 schema 暴露：
| 字段 | 默认 | 说明 |
|---|---|---|
enabled |
true |
总开关；false 时规则仍匹配但网页工具改直连 |
proxyUrl |
'' |
上游 HTTP(S) 代理 origin；为空或连接失败时自动直连 |
proxyToken |
'' |
secret：完整 Proxy-Authorization 值 |
rules |
随包 rules.json |
分流规则数组 |
searxEndpoint |
'' |
可选 SearXNG 纯搜索端点 |
maxResponseBytes |
5000000 |
响应字节上限 |
maxBodyChars |
100000 |
正文转文本字符上限 |
timeoutMs |
30000 |
请求超时 |
maxRedirects |
5 |
重定向上限（同源限制） |
若同时保留 http 与 rule-proxy provider，必须在 web 配置中显式选择 fetchProvider，否则 web 服务会报告 provider 歧义。
适用场景与注意¶
适合：需要让模型网页工具访问特定域名（如 GitHub、指定 API 主机）时走固定 HTTP 代理，其余工具流量直连；希望上游偶发失败时自动回退，而不是直接把错误抛给工具；需要在设置页或 rule_proxy_diagnose 里离线核对 hostname 命中。
不适合或有限制：诊断不验证 DNS、上游认证或 TLS；日志不输出请求正文与凭据。完整 Git clone/fetch/push 尚未实现。规则匹配与工具传输隔离不等于模型服务或远端搜索服务内部网络可控。README 指出公网 HTTPS 上游与真实 GitHub 流程需在隔离 profile 自备上游后验收，本地单测使用假目标，不能据此认定生产环境已通。
卸载时先将 web 的 fetchProvider 改回 http、searchProvider 改回原值，再移除 rule-proxy 插件条目。
结尾¶
dsh-rule-proxy 把「网页工具走代理」收敛到 hostname 规则与独立传输层，与全局网络改写解耦，并在上游不可用时回退直连。若要安装或阅读设计细节，可打开 社区目录页 与 GitHub 仓库；踩坑与设计决策见仓库内 docs/LESSONS.md，测试说明见 TEST_REPORT.md。
