dsh-plugin-bridge
dsh-plugin-bridge moves a locked session to a new preset through a previewable five-part handoff
English | 中文
Halfway through a task and need another tool preset? Switching the produced session in place would leave tool history that belongs to the old assembly. Bridge previews a bounded five-part handoff, opens a clean target, and leaves the original session untouched.
A real Bridge migration in the official DeepSeek Harness WebUI
Quick start · Why Bridge · Evidence · Decisions · Compatibility
Quick start
Install from npm:
dsh plugin --profile web add dsh-plugin-bridge
# restart dsh web once
Pinned GitHub fallback:
dsh plugin --profile web add github:Totoro-qaq/dsh-plugin-bridge#v0.3.7
Then type in the official WebUI:
/bridge list target presets
/bridge --doctor check the host contract after a DSH upgrade
/bridge code preview the handoff; change nothing
/bridge code --go migrate, restate, then wait
/bridge code --go --continue restate and start work in the same target request
On DSH rc.7 and later, the official WebUI renders /bridge as a native card. Text exposes the fixed five sections as ordinary fields and flat bullet or ordered-list rows while preserving their Markdown markers; Markdown preserves full source freedom; Preview renders Markdown or a complete JSON tree. Long content scrolls inside the card while the action bar stays reachable. Confirm migration opens the created target session.
UIs that implement the official conversation.chat.commandview slot receive the same card automatically. Other custom UIs retain the complete server result, summary-file workflow, and target title/session-ID fallback; UI authors can reuse the framework-free dsh-plugin-bridge/client-contract export instead of reimplementing the wire. On an older or non-slot client, correct the printed summary file and run:
/bridge code --go --file <path>
Preview edits are temporary until migration is confirmed. Restarting the client or system may discard them; the source session remains untouched, and you can regenerate the preview.
Uninstall with dsh plugin --profile web remove dsh-plugin-bridge, then restart dsh web.
Why Bridge
| Promise | What it means |
|---|
| Preview before execution | /bridge <preset> creates no target and changes no source session. Review or edit the five-section handoff first. |
| Move state, not tool traces | Decisions, paths, current state, and next steps move to a clean preset. Incompatible calls from the old tool assembly do not. |
| Fail closed | The target goal is paused before kickoff. If that cannot be guaranteed, Bridge clears/cancels the target and sends no model request. |
Installing Bridge adds zero prompt tokens to ordinary sessions. It is a host slash command, not a model tool or skill.
Evidence at a glance
The release gate is intentionally small and reproducible; these are regression results, not population guarantees.
| Gate | Result |
|---|
| Five-part summary facts | 30/30 |
| Target restatement / first useful work facts | 60/60 · 60/60 |
| Critical facts / obsolete-value resurrection | 90/90 · 0 |
| Existing image evidence / unresolved raw image | 5/5 · 5/5 |
Confirm / --continue target request shape | 2 · 1 to first useful work |
| Confirm extra, paired nominal median | +8.1% vs --continue |
| Summary worker share of clean acceptance components | 20.74% nominal |
| Native WebUI repeat gate (preview / target facts) | 3/3 · 3/3, five facts each |
| DSH 0.1.2 alpha.2 / alpha.3 / alpha.5 installed WebUI | 13/13 · ordered-list edit · PTC paused · image → text fallback |
| DSH 0.1.5-rc.1 installed WebUI, npm Bridge 0.3.4 | 13/13 · 3/3 migrations · edit reached target · PTC paused · raw image → vision target |
The token percentage varies widely with preset, response length, and cache state. The worker share is composition, not causal overhead versus no Bridge; the stable product claim is one additional confirmation request. Read the design and evidence boundaries, full release report, and vision report.
How it works
fold history -> five-part handoff -> preview/edit -> clean target session
-> pause stored goal -> inject -> restate -> wait or continue
image history -> verbatim assistant evidence; unresolved originals use the attachment gateway
The five sections are Goal, Current state, Key decisions and conventions, Key files, and Next step. The original session is never rewritten; archive the target and return to the source if the handoff is unsatisfactory.
Migration decisions
| Situation | Bridge behavior | Cost / fidelity effect |
|---|
Plugin installed, no /bridge call | No prompt injection or model tool | 0 Bridge prompt tokens |
/bridge code | One bounded summary worker; preview only | No target session is created |
Default --go | Target restates and waits | One explicit confirmation request before useful work |
--go --continue | Restate and work in one target request | Lower request count; no background goal round |
| Image already has assistant analysis | Copy that response verbatim | No raw image is resent by default |
| Image is unresolved and target accepts images | Copy the original attachment and preserve the source VLM | Vision pricing comes from the selected provider |
| Image is unresolved and target is text-only | Prompt admission rejects the image; Bridge sends a visible text fallback | No hidden local VLM and no silent claim of visual understanding |
Compatibility
| DSH baseline | Server handoff | Native card | Verification boundary |
|---|
| 0.1.0-rc.6 | Yes | No | Narrow RPC contract and text compatibility tests |
| 0.1.0-rc.7 / rc.8 | Yes | Contract-checked | Client-module/command-slot contract plus server fallback |
| 0.1.1-rc.2 | Yes | Yes | Installed official WebUI: doctor 13/13, edit/confirm/auto-open, three-run repeat gate |
| 0.1.2-alpha.2 / alpha.3 / alpha.5 | Yes | Yes | Official DSH npm hosts: typed controllers 13/13 and PTC auto-open; the alpha.5 gate installed the branch tarball, retained alpha.3 titles, edited ordered lists, fell back from unresolved image to text, and removed cleanly |
| 0.1.2-rc.1 → 0.1.3-alpha.2 | Yes (Bridge 0.3.3+) | Yes (Bridge 0.3.3+) | Real npm-host upgrade, preserved v2 history/title, exact edited payload, PTC paused goal, image fallback and clean removal; see acceptance report |
| 0.1.5-alpha.1 | Yes (Bridge 0.3.4+) | Yes (Bridge 0.3.4+) | Official npm host with session format V3: tarball install, served native-card bundle, doctor 13/13 and preset listing on a V3 session; SDK type diff and V3 fold fixtures. Model-backed preview, migration and image fallback were not re-run; see smoke report |
| 0.1.5-rc.1 | Yes (Bridge 0.3.4+) | Yes (Bridge 0.3.4+) | Official npm host with the published 0.3.4 unchanged: doctor 13/13, native card rendered, three model-backed migrations to PTC with an exact edited handoff and paused goal, and an unresolved image carried to the vision-capable default model; see acceptance report |
| 0.1.6-alpha.1 | Yes (Bridge 0.3.6+) | Yes (Bridge 0.3.6+) | Official npm host: doctor 13/13, native card rendered, still offered after the PTC runtime rename, keyless preview fails closed; the SDK change is additive and is byte-identical to 0.3.5. Model-backed migration was not re-run; see |
Use Bridge 0.3.4 or later for DSH 0.1.5-alpha.1: DSH published no 0.1.4, and a caret prerelease range such as ^0.1.3-alpha.2 never matches the next prerelease minor, so 0.3.4 adds ^0.1.5-alpha.1 and builds against that SDK with byte-identical lib/ output. Session format V3 records the system prompt as a system/message surface node; Bridge folds only user, assistant and tool events, so prompt text never enters a handoff. Use Bridge 0.3.3 or later for DSH 0.1.3-alpha.2; Bridge 0.3.2 does not include those compatibility changes. The typed adapter reads the default 240-message history window with one fresh inspect call instead of four; it does not cache running state. doctor checks method availability, not end-to-end compatibility. The same ^0.1.5-alpha.1 range also matches 0.1.5-rc.1 and the 0.1.5 final, so rc.1 needs no new Bridge release.
Since 0.3.5 the summary worker follows the conversation's model by default (modelTier: current). On DSH 0.1.5-rc.1 that is V4.1-Flash, which matched V4-Pro in the tier comparison at about half the summary time. DSH releases before 0.1.5-rc.1 have no V4.1-Flash, so set DSH_BRIDGE_TIER=pro or pass --tier pro there.
Use Bridge 0.3.6 or later for DSH 0.1.6-alpha.1. It adds the ^0.1.6-alpha.1 peer term: ^0.1.5-alpha.1 matches a future 0.1.6 but no 0.1.6 prerelease. Only the dependency ranges change; the shipped code is the same as 0.3.5.
DSH 0.1.6-alpha.2 removed the client sessions.open. Bridge 0.3.6 still migrates there, but its Open target session button fails with ctx.sessions.open is not a function. Use Bridge 0.3.7 or later: it opens targets through the WebUI navigation service uiWorkspace.openSession and falls back to sessions.open on older hosts.
CI covers Node.js 22 and 24. Run /bridge --doctor after every Harness upgrade; it names missing required gateway methods instead of failing vaguely.
Current limits:
- installing with the CLI (
dsh plugin --profile web add) may need one WebUI restart; on DSH 0.1.6-alpha.2 a first install from the WebUI Plugins page (add the package name dsh-plugin-bridge) applies live, while upgrading an existing install there needs a restart;
- the native card opens the created target through the WebUI navigation service (
uiWorkspace.openSession, with sessions.open as the fallback on older hosts); older clients still receive the title and session ID fallback;
- progress appears immediately while the worker runs; the current fixed three-run sample took 7.4–12.8 seconds of worker time, while
previewTimeoutMs remains the hard bound;
- text-only models cannot inspect unresolved images;
- the native-card repeat gate is still only three fixed runs, so it is release evidence rather than a statistical guarantee.
The server command stays the compatibility core. The same package now adds an optional official client half for rendered editing and navigation; if that prerelease client contract fails to load, /bridge still returns the complete server result. See the implementation boundary.
Documentation
Development
npm ci
npm run verify
verify builds and type-checks both plugin halves, runs 184 tests, checks generated lib/ and datasets, then packs, installs, and imports the actual npm tarball. Tests spend no model tokens. prepublishOnly runs the same gate; GitHub releases also require the tag to match package.json before trusted npm publishing.
Community listings: Awesome DSH Plugin · Awesome DeepSeek Harness
Ecosystem discovery: dsh-TUI. Bridge remains a standard DSH plugin; TUI/std conformance is tracked separately.
License
MIT
