dsh-web-fetch-enhanced

中文 · English

为 DeepSeek Harness 提供安全、可控的增强型网页抓取：解决 Clash / Mihomo Fake-IP 与受信任内网目标被原生公网地址检查拦截的问题，同时保持模型侧 web_fetch 用法不变。

它解决什么问题？

DeepSeek Harness 原生 HTTP provider 默认拒绝所有非公网地址，这是重要的 SSRF 安全边界。但在以下场景中，目标明明可信，也可能被提前拦截：

• Clash、Mihomo 等透明代理的 Fake-IP 模式把公网域名解析到 198.18.0.0/15；
• Agent 需要读取企业内网文档站、自建知识库或其他受信任的私有网络服务；
• 本地代理在接管连接前，需要先通过 Harness 的地址检查。

本插件允许管理员显式配置两层例外：

1. CIDR 白名单：哪些非公网 IPv4 / IPv6 网段可以访问；
2. 域名白名单（可选）：哪些域名可以使用上述 CIDR 例外。

没有配置任何 CIDR 时，行为与原生 provider 的“仅公网”默认值一致。

主要特性

• 与原生工具完全兼容：不增加新模型工具，Agent 继续调用 web_fetch；
• 网页端即时配置：在 DSH Web 设置中编辑白名单，保存后下一次抓取立即生效；
• 默认拒绝非公网目标：只有明确命中的 CIDR 例外才会放行；
• 可选域名第二因子：将可访问网段进一步限制到精确域名或 *.example.com；
• DNS 全答案校验与连接固定：所有解析结果都必须合规，连接只使用已验证的地址；
• 重定向逐跳复核：仅跟随同源重定向，并在每一跳重新解析、校验和固定地址；
• 受限匿名请求：只发送无 Cookie、无 Authorization、无 URL 凭据的 GET 请求；
• 完整资源上限：限制 URL、响应字节、解码字符、重定向次数和超时时间；
• IPv4 / IPv6 防护：覆盖 IPv4-mapped IPv6 与活动 DNS64 / NAT64 目标检查；
• 全局出站代理协同：无缝对接 DSH 全局 HTTP 代理路由（HTTP_PROXY / HTTPS_PROXY / ALL_PROXY / NO_PROXY），同时严格禁止非公网 IP 字面量越权走代理，杜绝内网 SSRF 风险；
• 动态系统提示词协同：当管理员配置了非公网白名单时，自动向模型系统提示词注入显式授权声明，消除模型因默认安全准则而产生“无法访问内网”的拒答幻觉。

版本兼容性与支持策略

• 最低支持的 DSH 版本：0.1.5-rc.2
• 版本支持策略：本插件仅对 DeepSeek Harness 的 RC（Release Candidate）候选发布版本及后续稳定正式版提供支持。由于 Alpha 或开发快照版本更迭频繁且缺乏稳定的 API 保证，本插件不再对 Alpha 等非 RC 阶段版本进行维护与适配。

快速开始

1. 安装到 Web Profile

推荐使用 DSH 的插件管理命令。安装包会把随包发布的 cordis.patch.yml 作为 Profile patch 层应用：

dsh plugin --profile web add dsh-web-fetch-enhanced

如果 Web Profile 已经在运行，请按你的部署方式重启对应的 Host 进程，使新插件和 Client face 完成装载。

本地源码开发时可以使用绝对路径：

dsh plugin --profile web add link:/absolute/path/to/dsh-web-fetch-enhanced

2. 配置白名单

打开 DSH Web，进入：

设置 → 插件 → 可配置插件 → Web Fetch Enhanced

展开卡片，在“允许的 CIDR”中每行填写一个网段。例如 Clash / Mihomo 的常见 Fake-IP 配置：

198.18.0.0/15

如果希望只有指定网站可以使用这个例外，再填写“允许的域名”：

api.example.com
*.docs.example.com

点击“保存”。无需重启 Profile，下一次 web_fetch 就会使用新规则。

3. 正常使用 web_fetch

插件不会改变 Agent 的使用方式。你仍然可以直接用自然语言提出请求，例如：

读取 https://docs.example.com/guide，并总结部署步骤。

Agent 会照常调用 web_fetch；地址解析、白名单判断和安全传输由本插件在底层完成。

常见配置场景

Clash / Mihomo Fake-IP

如果整个 Fake-IP 网段都由可信代理接管：

留空域名白名单表示：任意域名只要解析到已放行 CIDR，就可以使用该 CIDR 例外。公网地址仍照常访问。

只允许少量域名使用 Fake-IP

这是更严格的配置，适合代理规则不完全受你控制的环境。

访问受信任的内网站点

# 允许的 CIDR
10.20.0.0/16

# 允许的域名
wiki.corp.example
*.docs.corp.example

请只放行实际需要的最小网段，不要为了方便加入整个 RFC1918 地址空间。

白名单规则

CIDR

• 每行一个标准 IPv4 或 IPv6 CIDR；
• IPv4 必须使用四段十进制网络地址，例如 192.168.1.0/24；
• IPv6 不接受 %eth0 之类的 Zone ID；
• 必须填写网络基址，不能用带主机位的地址代替网段；
• 空白行会被忽略，重复条目会在设置页中提示并阻止保存。

域名

• 精确规则：api.example.com；
• 最左侧通配规则：*.example.com；
• *.example.com 匹配其子域名，但不匹配 example.com 本身；
• 不要填写协议、路径或端口，例如 https://example.com、example.com/path、example.com:8080 都不是合法规则；
• 域名白名单只约束“非公网 CIDR 例外”，不会限制原本就允许访问的公网地址。

两层规则如何组合？

设置页按钮说明

• 保存：把当前草稿写入用户设置层；
• 放弃修改：丢弃尚未保存的编辑，恢复当前生效值；
• 重置为 Profile 配置：把“删除 allowCidrs 和 allowHostnames 用户覆盖、重新继承 Profile composition”的操作加入草稿；仍需点击“保存”才会生效；
• 只读状态：当前连接没有持久化 Host Profile 设置的权限。通常应从 Host 本机的 loopback 地址打开 Web GUI。

“保存空列表”和“重置为 Profile 配置”含义不同：前者显式覆盖为空，后者恢复继承。

安全提示

白名单会扩大 Agent 可发起 HTTP 请求的网络范围。只放行你理解并信任的最小目标。

请勿加入以下宽泛或敏感目标：

• 0.0.0.0/0 或 ::/0；
• 云元数据地址，例如 169.254.169.254/32；
• 不必要的整个 10.0.0.0/8、172.16.0.0/12 或 192.168.0.0/16；
• 由不可信代理、DNS 或租户共同控制的网段。

即使配置了白名单，Host 仍会重新执行完整的 CIDR、域名、DNS 和 provider 身份校验；浏览器端校验不是安全边界。详细威胁模型见 安全设计。

高级配置

通常只需要在 Web GUI 中维护两项白名单。其他参数应由 Profile composition 管理：

默认安装（通过 bundle cordis.patch.yml）采用独立的 http-enhanced provider ID，并显式禁用原生的 web-fetch-http，以避免后续其他 Web 插件（如 search 插件）覆盖 id: web 的 config 时因 fetchProvider 变成未指定而触发 WEB_PROVIDER_AMBIGUOUS。需要自定义组合或 drop-in 替换时，参考：

• 独立 provider 示例
• drop-in 替换示例
• 手动 composition patch
• 架构与 provider 选择语义

不要让原生 provider 和本插件同时注册同一个 ID，否则 Host 会以 WEB_DUPLICATE_PROVIDER 拒绝启动，而不是执行 last-wins 覆盖。

常见问题

开发与贡献

需要二次开发时：

pnpm install
pnpm run check

pnpm run check 会执行类型检查、lint、构建、测试与发布包校验。Host bundle 输出到 lib/index.js，浏览器 Client bundle 输出到 lib/client.js。

许可证与来源

本项目采用 MIT License。网络安全模型与部分实现基于 DeepSeek Harness 的 @deepseek-ai/dsh-web-fetch-http，详见 NOTICE。本项目不是 DeepSeek 官方包，除非发布者另有明确说明。