<div align="center">

Kimi WebBridge for DeepSeek Harness

Give your DeepSeek Harness agents the user's real browser — with their login sessions.

!English 

     

*A third-party plugin bundle for DeepSeek Harness (dsh). It turns the local Kimi WebBridge daemon into 16 native kimi_webbridge_* tools — the agent can open pages, read them, click, type, screenshot, run JS, inspect network traffic, upload files, save PDFs, and check daemon/extension health in your real browser, logged in as you.*

</div>

---

🚀 What's new in 0.2.0

This is the actively maintained 0.2.0 line. Compared with the original 0.1.0 plugin, it adds:

---

✨ What it does

🛠️ What the model gets — 16 tools

✅ Requirements & versions

> Compatibility is pinned to what was actually verified. Run node tests/smoke.mjs after installing to check your environment.

📦 Installation

Option A — from GitHub (recommended):

dsh plugin --profile demo add github:Bernardxu123/dsh-kimi-webbridge
dsh --profile demo web

Option B — from a local checkout:

dsh plugin --profile demo add ./dsh-Kimi-WebBridge
dsh --profile demo web

Option C — no install, one-off overlay (kimi-webbridge.overlay.yml):

- insert:
    - id: kimi-webbridge
      name: '/absolute/path/to/dsh-Kimi-WebBridge/index.js'
      config:
        session: dsh

dsh web --patch ./kimi-webbridge.overlay.yml

Option D — permanent merge: copy the insert block from cordis.patch.yml into $DSH_HOME/profiles/<name>/cordis.patch.yml (or $DSH_HOME/cordis.patch.yml for all profiles).

Uninstall:

dsh plugin --profile demo remove dsh-kimi-webbridge

The CLI removes the dependency and reconciles the profile's layer list; the 16 tools unregister. Verify the row is gone:

dsh --profile demo --dump-config    # the kimi-webbridge row must not appear

> ⚠️ Known harness caveat (dsh 0.1.0-rc.7, discussion #913): on rare transient pnpm failures the entry can remain in dsh.profile.bundles, and the profile then fails to boot with cannot resolve profile bundle "dsh-kimi-webbridge" — dsh plugin install does not fix it (community analysis: #917). Recovery: edit the profile's package.json and delete "dsh-kimi-webbridge" from dsh.profile.bundles, then boot again.

> Only runtime files (index.js, cordis.patch.yml, READMEs, LICENSE) are installed; docs/ and tests/ stay in this repository. Verified with npm pack.

🚀 Quick start

1. Install the bundle and start dsh web --profile demo. 2. Wait for the kimi_webbridge_* tools in the catalog. 3. Ask: "Open example.com in the browser, tell me what's on the page, and screenshot it." 4. The agent opens a tab group (named in your language), reads the page via snapshot, saves the screenshot, and shows you the file.

⚙️ Configuration

All keys optional; override the kimi-webbridge row from a later patch layer, restating every key you need:

- id: kimi-webbridge
  name: dsh-kimi-webbridge
  config:
    baseUrl: 'http://127.0.0.1:10086'   # daemon endpoint
    session: dsh                        # daemon-side tab-group name (one per profile)
    requestTimeoutMs: 120000            # per-request timeout
    startDaemonTool: true               # expose kimi_webbridge_start_daemon
    daemonBin: null                     # override the auto-detected daemon binary
    maxRenderText: 50000                # cap on rendered result text
    disabledTools: []                   # optional tool names to hide, e.g. ['kimi_webbridge_cdp', 'kimi_webbridge_evaluate']

✅ Done / ⚠️ Not done

Done and verified

• All 16 tools end-to-end tested through the real harness + real browser (dsh 0.1.0-rc.7, daemon v1.11.6): navigation, clicking through to real sites, form fill + value verification, file upload + files.length verification, network capture, CDP layout metrics, screenshots, PDFs, tab management, daemon self-start, status/health checks.
• Automatic retry for capture tools (a fresh tab's first screenshot can stall while the page settles — a retry returns instantly).
• Graceful daemon-unreachable errors with a self-heal path (kimi_webbridge_start_daemon), tested against a dead port via --patch.
• Per-tool enable/disable via disabledTools (hide cdp/evaluate for untrusted policies).
• Schema strictness verified against the real @deepseek-ai/dsh-tools compile + raw-JSON-schema boundary checks (tests/smoke.mjs).

Not done / known limits

• fill/click are ignored by sites that strictly check event.isTrusted (banking portals, captchas) — those need manual interaction. Trusted input is possible at the protocol level via cdp, but that is advanced.
• Cross-origin iframes are out of scope: snapshot/click/fill/evaluate operate on the top frame only.
• session is per-profile, not per-agent: subagents share the same tab group. Per-agent session isolation is a future idea (see below).
• macOS/Linux code paths exist but were not verified on real machines.
• CDP is limited to what the extension exposes (browser-level domains such as Browser.* are not available).

🗺️ Roadmap — routes that work and routes that don't

Viable routes

• ✅ Direct HTTP to the daemon (this plugin) — the only interface WebBridge exposes today.
• ✅ Per-profile session naming; config-driven tool toggles (startDaemonTool).
• ✅ Health/status tool over GET /status.
• ✅ Per-tool enable/disable via disabledTools.
• 🔜 Per-agent session mapping.
• 🔜 Publishing to npm once the harness API is stable.

Dead ends (don't go here)

• ❌ Mounting via @deepseek-ai/dsh-mcp-client — WebBridge has no MCP endpoint (/mcp and /sse return 404; only /command and /status exist). The MCP route used by e.g. Exa does not apply.
• ❌ OAuth login flows (mcp.exa.ai?login-style) — not supported by the daemon bridge; API keys are not a WebBridge concept either.
• ❌ Daemon lifecycle beyond start — the plugin never runs stop/restart/uninstall; that is always the user's call.
• ❌ Headless / VM automation — the model acts as you, in your browser; this is not a scraping or CI tool.

🔐 Security

• The daemon listens on 127.0.0.1 only; the model operates your browser as you. Review what your harness is allowed to ask for.
• The plugin stores and sends no credentials, has no filesystem access, and never modifies the deepseek-harness installation.
• kimi_webbridge_cdp and kimi_webbridge_evaluate are powerful; disable them for untrusted model policies with disabledTools: ['kimi_webbridge_cdp', 'kimi_webbridge_evaluate'].

🧪 Verifying your install

node tests/smoke.mjs

Offline registration + schema-boundary checks always run; live daemon round-trips (navigate → snapshot → evaluate → screenshot → close) run when the daemon is reachable. Set SKIP_LIVE=1 to force offline-only mode (used by CI).

🙏 Credits & thanks

• DeepSeek — for the DeepSeek Harness agent runtime and its plugin architecture (dsh, Cordis, dsh-tools).
• Moonshot AI — for Kimi WebBridge, the local browser bridge this plugin drives.
• The Koishi/Cordis ecosystem — for the plugin framework (cordis, schemastery) that DeepSeek Harness is built on, and whose conventions this plugin follows.

📌 Version & compatibility

• Plugin: 0.2.0
• Tested with: dsh 0.1.0-rc.7 · Node 24 (≥18 required) · Kimi WebBridge daemon v1.11.6 / extension 1.11.5 · Windows
• Dependencies: none declared — @deepseek-ai/dsh-tools resolves at runtime from the harness installation (no registry copies are installed)

📚 More docs

• [Engineering documentation](docs/engineering.md) · [Glossary](docs/glossary.md) · [API reference](docs/api-reference.md) · [Solutions & pitfalls](docs/solutions.md)

📄 License

[MIT](LICENSE). Not an official DeepSeek or Moonshot product. WebBridge is a product of Moonshot AI.