Contributing to dsh-webbridge

August 14, 2026 · View on GitHub

Focused fixes, tests, and documentation changes are welcome. By participating, you agree to follow the Code of Conduct.

Before you start

  1. Read README.md — install, usage, and troubleshooting.
  2. Search existing issues and pull requests before opening duplicate work.
  3. Open an issue before changing the tool surface (which webbridge_* tools are exposed, the session contract) or the bundle manifest (cordis.patch.yml — the row id webbridge deliberately matches the DSH built-in).
  4. Keep each change narrowly scoped. Do not mix a feature or fix with unrelated refactoring or generated-output churn.

Architecture and scope

dsh-webbridge is an out-of-tree DeepSeek Harness host plugin. Contributions must preserve these responsibilities:

  • The plugin is a standard DSH bundle (host-only: dsh.bundle + cordis.patch.yml) that registers webbridge_* model tools on the tools service. It ships no browser-driving code of its own — every action goes through the separately installed Kimi WebBridge daemon and browser extension.
  • Tools must fail loud with a daemon_unreachable error when the daemon is not running, and browser state must stay in the user's browser — never copy it into model requests (no KV-cache burden).
  • The row id webbridge deliberately matches the built-in plugin; a later bundle layer replaces an earlier row of the same id, so the override behavior must be preserved.
  • The session contract is upstream (Kimi WebBridge): one task = one session = one tab group, and closing is always user-initiated. Do not change tool semantics without coordinating upstream.

Development

pnpm install
DSH_CHECKOUT=/path/to/dsh pnpm run build   # tsc -> lib/types, tsdown -> lib/index.js (committed)

Peer dependencies and the toolchain come from DSH: set DSH_CHECKOUT to a source checkout, or have dsh on PATH and run it once. Unit tests (tests/client.spec.ts) run against a mock HTTP daemon, so no real Kimi install is required; run them in a vitest-equipped environment (e.g. the DSH checkout) and set KIMI_WEBBRIDGE_IT=1 to run integration tests against a live daemon.

Keep the bilingual README in sync (edit both README.md and README.zh.md, then node scripts/verify-i18n.mjs --write).

Commit and release

  • Bump the version and update CHANGELOG.md (Keep a Changelog format) in the same change that ships a user-visible difference.
  • Tag releases with a semantic version (v0.0.3) and push tags with the release.