dsh-web-fetch-enhanced

2. 配置白名单

打开 DSH Web，进入：

插件 → dsh-web-fetch-enhanced

详情页直接显示白名单表单，在“允许的 CIDR”中每行填写一个网段。例如 Clash / Mihomo 的常见 Fake-IP 配置：

198.18.0.0/15

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

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

点击“保存”，页面显示“已保存”并保留输入框。无需重启 Profile，下一次 web_fetch 就会使用新规则。

下方“包含的组件”由 DSH 展示插件运行状态，配置白名单不需要进入组件。

3. 正常使用 web_fetch

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

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

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

常见配置场景

Clash / Mihomo Fake-IP

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

设置项	内容
允许的 CIDR	198.18.0.0/15
允许的域名	留空

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

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

设置项	内容
允许的 CIDR	198.18.0.0/15
允许的域名	api.example.com、*.docs.example.com

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

访问受信任的内网站点

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

| 设置项 | 内容 |
| --- | --- |
| 允许的 CIDR | `198.18.0.0/15` |
| 允许的域名 | `api.example.com`、`*.docs.example.com` |

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

## Profile 配置与旧版本迁移

从 DSH `0.1.7-rc.1` 起，本插件使用 Profile 拥有的 Cordis `Config`、`.volatile()` 和插件管理页的 `configForms` 表单，不再读取全局 `$DSH_HOME/settings.yaml`。

- 配置由 Schema 默认值与当前 Profile composition/patch 决定；Web 保存只修改选中的插件行。
- **清空输入并保存会显式写入 `[]`**，用于撤销继承的白名单。空数组具有安全意义，不再自动清理。
- **恢复继承与清空不同**：只有显式恢复操作才执行 `unset`，可能重新启用底层配置中的白名单。
- 升级前备份旧设置，将旧 `web-fetch-enhanced` 节中的授权规则逐项审查后迁入目标 Profile 的插件配置。插件不会自动将全局授权复制到所有 Profile。

详见 [0.1.7-rc.1 升级说明](https://github.com/Yurzi/dsh-web-fetch-enhanced/blob/d9d1bb42e0ccb7de58b3492056250535bc4425b8/docs/migration-0.1.7-rc.1.zh-CN.md)。

### 插件配置格式版本

插件配置支持独立的 `schemaVersion: 1`。已有无版本配置按 v0 在读取时自动迁移到 v1，无需手工补字段；非法版本和高于当前支持范围的版本会被拒绝，不静默降级。迁移只发生在内存中，不自动改写用户文件，也不改变白名单授权。详见[配置版本与迁移设计]()。

### 插件配置格式版本

插件配置支持独立的 `schemaVersion: 1`。已有无版本配置按 v0 在读取时自动迁移到 v1，无需手工补字段；非法版本和高于当前支持范围的版本会被拒绝，不静默降级。迁移只发生在内存中，不自动改写用户文件，也不改变白名单授权。详见[配置版本与迁移设计]()。

## 高级配置

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

| 字段 | 默认值 | 说明 |
| --- | --- | --- |
| `schemaVersion` | 缺失按 v0，运行时迁移至 `1` | 配置格式版本；独立于包版本，不在 Web 表单中编辑 |
| `providerId` | `http-enhanced` | 注册到 `ctx.web` 的 fetch provider ID |
| `allowCidrs` | `[]` | 允许作为非公网例外的 IPv4 / IPv6 CIDR |
| `allowHostnames` | `[]` | 可选的精确域名或最左侧通配规则 |
| `maxResponseBytes` | `5,000,000` | 响应正文最大读取字节数 |
| `maxBodyChars` | `100,000` | 解码后最大字符数 |
| `timeoutMs` | `30,000` | 单次抓取超时（毫秒） |
| `maxRedirects` | `5` | 同源重定向最大跳数；`0` 表示不跟随 |
| `userAgent` | `dsh-web-fetch-enhanced/0.1.0` | 每个请求使用的 User-Agent |

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

- [独立 provider 示例](https://github.com/Yurzi/dsh-web-fetch-enhanced/blob/d9d1bb42e0ccb7de58b3492056250535bc4425b8/examples/coexist.cordis.yml)
- [drop-in 替换示例](https://github.com/Yurzi/dsh-web-fetch-enhanced/blob/d9d1bb42e0ccb7de58b3492056250535bc4425b8/examples/drop-in.cordis.yml)
- [手动 composition patch](https://github.com/Yurzi/dsh-web-fetch-enhanced/blob/d9d1bb42e0ccb7de58b3492056250535bc4425b8/examples/manual.cordis.patch.yml)
- [架构与 provider 选择语义](https://github.com/Yurzi/dsh-web-fetch-enhanced/blob/d9d1bb42e0ccb7de58b3492056250535bc4425b8/docs/design.zh-CN.md)

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