dsh-fakeip-compat
FakeIP 兼容层：让 DeepSeek Harness 的 web_fetch 接受 FakeIP 网段的 DNS 答案，可选通过 DNS-over-HTTPS 验证真实地址，并提供 General-settings 设置项。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:bemarkt/dsh-fakeip-compat#884adbf4323b0322adac75df7792c5e54d8fca65Fakeip Compat 以 dsh-fakeip-compat 发布，当前版本为 1.0.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
中文 | English
Version 1.0.0 · verified against DeepSeek Harness
0.2.1-rc.5on both Desktop and CLI profiles.
A FakeIP-compatibility layer for web_fetch in DeepSeek Harness, with a General-settings row for its own configuration.
When a local DNS answers with placeholder addresses from a FakeIP range, the harness refuses the fetch before a single byte is sent:
Error: URL hostname "raw.githubusercontent.com" resolves to a non-public IP address
This plugin re-registers the http fetch provider with one extra rule ahead of that judgement, and can optionally re-check the real destination through DNS-over-HTTPS. Connection pinning, same-origin redirects, byte and character caps, and charset decoding stay exactly as the harness already does them.
The compat suffix is the point: nothing else changes. The provider id, the row id and the composition are the ones DeepSeek Harness already ships, so this drops into a profile that selects fetchProvider: http without touching anything else.
@deepseek-ai/dsh-web-fetch-http resolves a hostname once and requires every answer to be a globally reachable unicast address (internally ipaddr.js's range() === 'unicast'). A FakeIP resolver answers with addresses from reserved or unique-local blocks, so every request is refused:
| Answer | ipaddr.js range | Outcome |
|---|---|---|
198.18.0.0/15 | reserved | treated as non-public, rejected |
fc00::/18 | uniqueLocal | treated as non-public, rejected |
Any hostname resolving into such a range cannot be fetched by the agent at all.
One rule is inserted ahead of the stock judgement:
destination inside fakeipRanges -> allow
allowNonPublic === true -> allow (the check is skipped entirely)
anything else -> the unchanged public-unicast check
Private networks, loopback and the 169.254.169.254 metadata address stay blocked by default.
Design choices worth knowing about:
lib/ip.js. A profile-installed bundle can only resolve its own node_modules, so the plugin must not need one.HttpFetchProvider, so pinning, redirects, caps and decoding are the shipped implementation rather than a copy.node:http/node:https transport takes over: pinning and caps still apply, the harness proxy router does not. runtime.implementation reports which one is live.web-fetch-http only because two providers cannot share the id http.A FakeIP answer says nothing about the real destination: the resolver hands out a placeholder and the proxy resolves the name afterwards. A hostname pointed at a private network therefore arrives looking exactly like any other placeholder.
Turning on verification asks an independent JSON DoH endpoint for the real answer before the connection is made:
verifyRealAddress | Behaviour |
|---|---|
off (default) | no query at all, zero added latency |
warn | query, log a non-public real answer, then allow the fetch |
enforce | query, refuse the fetch when the real answer is non-public |
dohFailurePolicy decides what an unverifiable destination means while verification is on: allow (default) or deny. Only queries that produced no usable answer count as unverifiable; a query that answered with public addresses is a pass.
Why it is off by default. Verification is not free, and the honest tradeoffs are worth stating:
enforce mode that disagreement becomes a failed fetch, so enforce suits a home network whose only split is the proxy, not a policy-heavy deployment.web_fetch, which is why the failure policy is separate and defaults to allow.So verification closes one specific gap — a name whose real answer is a private address — and pays for it in availability, latency and privacy. Off by default; turn it on when that gap is the thing you care about.
| Item | Value |
|---|---|
| DeepSeek Harness | 0.2.1-rc.5 (verified), Desktop and CLI profiles alike |
| Node.js | 20 or newer |
| Composition | must mount web; the settings row additionally needs webServer and configEditor |
Without webServer or configEditor (for example a pure TUI profile) the fetch provider still works; the settings row reports that the configuration route is unavailable, and the row config is written by hand.
plugin_manager { action: "install_bundle", target: "<absolute path to this repository>" }
Reinstalling over an existing copy is refused (already-installed); remove first, then install:
plugin_manager { action: "remove_bundle", target: "dsh-fakeip-compat" }
plugin_manager { action: "install_bundle", target: "<absolute path to this repository>" }
The bundle patch does two things:
- id: web-fetch-http # disabled only to avoid a duplicate "http" provider id
disabled: true
- insert:
- id: fakeip-compat
name: 'dsh-fakeip-compat'
config:
fakeipRanges: ['198.18.0.0/15']
allowNonPublic: false
verifyRealAddress: 'off'
A tarball install from GitHub works too: package.json records the canonical sources under dsh.install (tarball preferred), so the URL never has to be guessed.
application: applied. A saved config reconciles the row through the Loader, so no restart is needed.client.js, needs a restart before the row appears.Settings → General → scroll to the bottom → FakeIP fetch compatibility:
× removes one. An empty list means every non-public destination stays blocked.allowNonPublic checkbox.off / warn / enforce, plus the DoH endpoint and the failure policy.cordis.patch.yml; the Loader reconciles the row and the provider reloads with the new settings.Write path:
browser → GET|POST /ext/fakeip-compat/config
→ configEditor.edit(entry, …)
→ ~/.dsh/profiles/<profile>/cordis.patch.yml
→ Loader reconciles the row
→ provider reloads with the new config
| Field | Default | Meaning |
|---|---|---|
fakeipRanges | ['198.18.0.0/15'] | CIDR blocks accepted as destinations. Multiple entries, IPv4 and IPv6 mixed. |
allowNonPublic | false | Drop the destination check entirely, private and loopback addresses included. |
verifyRealAddress | 'off' | off / warn / enforce, as described above. |
dohEndpoint | 'https://dns.google/resolve' | JSON DoH endpoint used while verification is on. HTTPS only. |
dohTimeoutMs | 4000 | Per-query deadline for the DoH lookup. |
dohFailurePolicy | 'allow' | What an unverifiable destination means while verification is on. |
maxResponseBytes | 5000000 | Response body byte cap. |
maxBodyChars | 100000 | Decoded character cap. |
timeoutMs | 30000 | Fetch timeout. |
maxRedirects | 5 | Same-origin redirect hop cap. |
userAgent | deepseek-harness/… | Request User-Agent. |
- id: fakeip-compat
name: 'dsh-fakeip-compat'
config:
fakeipRanges:
- '198.18.0.0/15'
- 'fc00::/18'
allowNonPublic: false
verifyRealAddress: 'warn'
dohEndpoint: 'https://dns.google/resolve'
dohFailurePolicy: 'allow'
1. Configuration route. Replace the port with the one the running GUI uses:
Invoke-WebRequest -Uri 'http://127.0.0.1:<PORT>/ext/fakeip-compat/config' -UseBasicParsing | Select-Object -ExpandProperty Content
Expect HTTP 200, rowId: fakeip-compat, the resolved config, and a runtime block:
{
"rowId": "fakeip-compat",
"config": { "fakeipRanges": ["198.18.0.0/15"], "allowNonPublic": false, "verifyRealAddress": "off" },
"runtime": {
"desktop": true,
"electron": "44.7.0",
"node": "24.21.0",
"dshVersion": "0.2.1-rc.5",
"implementation": "shipped-http",
"verifyRealAddress": "off",
"shippedPath": "…/dsh-web-fetch-http/lib/index.js",
"resolvedFrom": "…/dsh/package.json"
}
}
runtime is diagnostic only; it is deliberately not rendered in the settings row.
2. Settings row.
cordis_inspect_query { platform: "client", provider: "Slots", method: "listSubTree", input: { root: "settings.general.item" } }
occupants should contain { "id": "fakeip-compat", "order": 101, "active": true }.
3. Fetch. A URL that used to fail now returns a body:
web_fetch { url: "https://raw.githubusercontent.com/nodejs/node/main/README.md" }
4. Offline self-test. No DNS, no network:
node scripts/selftest.mjs
Covers CIDR boundaries (198.18.0.0 and 198.19.255.254), fc00::/18 inside and outside, ::ffff: mapping, private/loopback/metadata still refused, malformed CIDR rejected, config validation of every verification field, and URL policy.
Desktop is an Electron application, which changes three things for a profile-installed bundle:
| Item | Value |
|---|---|
| Harness tree | <...>/resources/app/dsh/ (inside app.asar for some distributions) |
| Profile directory | ~/.dsh/profiles/<profile> |
| Web GUI | http://127.0.0.1:<random port> — the port changes on every restart |
| Client bundle hot reload | none; editing client.js needs a restart |
The shipped provider is located by probing, in order:
import('@deepseek-ai/dsh-web-fetch-http')process.resourcesPath/app/dsh/package.json (the Desktop main path)process.resourcesPath/app/package.json (packaged asar layout)process.argv[1] (CLI entry)dirname(process.execPath)/resources/app/dsh/package.jsonprocess.cwd()/package.json$DSH_PROFILE_DIR/package.jsonIf none resolves, the Node-native fallback takes over: fetching still works and the caps still apply, but the harness proxy router is bypassed. runtime.implementation tells the two apart.
| Symptom | Cause | Fix |
|---|---|---|
WEB_DUPLICATE_PROVIDER | the web-fetch-http row was not disabled | check - id: web-fetch-http / disabled: true in the patch |
still WEB_BLOCKED_URL | the range is not in fakeipRanges | the error names the address; add that block to the list |
WEB_BLOCKED_URL mentioning verifyRealAddress is 'enforce' | the real answer is non-public and mode is enforce | switch to warn, or drop that host from scope |
| every fetch fails once verification is on | the DoH endpoint is unreachable and dohFailurePolicy is deny | fix the endpoint, or set the policy to allow |
row says the configuration route is unavailable, (HTTP 404) | /ext/fakeip-compat/config was never registered: no webServer, or this row activated before it | the plugin waits for webServer via ctx.inject; if it persists, restart DSH |
… (HTTP 503) | no configEditor in the composition | a TUI-only profile has no settings row; write cordis.patch.yml by hand |
… row is not present in this profile | the row id is not fakeip-compat | restore the default id |
save reports is overridden by a home patch or command-line overlay | a higher-priority patch pins that row's config | edit the $DSH_HOME layer or the --patch overlay instead |
| the row never appears in Settings | the client half never entered the module graph | confirm every dsh.client.inject package exists in this version, then restart DSH |
runtime.implementation is node-native | the shipped HttpFetchProvider was not resolved | extend the probe list above; fetching works, proxy routing does not |
dsh-fakeip-compat/
├── .github/workflows/ # CI: syntax check, offline self-test, manifest validation
├── package.json # name, version, main, exports, dsh.bundle + dsh.client
├── cordis.patch.yml # bundle patch: disable the shipped row, insert this one
├── client.js # Client half: window.__ModuleLoader__.load + settings.general.item
├── lib/
│ ├── index.js # Host half: provider, resolution probing, config route, runtime facts
│ ├── ip.js # IPv4/IPv6 parsing, CIDR matching, block table, classifier
│ ├── resolver.js # one resolve, per-answer verdict, optional verification, abort racing
│ ├── doh.js # optional JSON DoH verification of the real destination
│ ├── provider.js # node:http/https fallback transport
│ ├── config.js # DEFAULTS / normalizeConfig / ROW_ID
│ └── config-route.js # GET/POST /ext/fakeip-compat/config
├── locale/{en,zh}.json # Plugin Manager title and description
├── icon.svg # Plugin icon
├── scripts/selftest.mjs # Offline self-test
├── CHANGELOG.md # Release history
└── LICENSE
plugin_manager { action: "remove_bundle", target: "dsh-fakeip-compat" }
Removing the bundle drops the web-fetch-http override with it, so the shipped behaviour returns and FakeIP destinations are refused again.