dsh-plugin-bridge

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.

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, ptc still offered after the PTC runtime rename, keyless preview fails closed; the SDK change is additive and lib/ is byte-identical to 0.3.5. Model-backed migration was not re-run; see smoke report
0.1.6-alpha.2	Yes (Bridge 0.3.7+)	Yes (Bridge 0.3.7+)	Official npm host: Bridge 0.3.6 migrates, but its Open target session button fails with ctx.sessions.open is not a function; Bridge 0.3.7 opens the target through uiWorkspace.openSession on alpha.2 and alpha.1, keeps the paused goal, and survives live disable and enable from the Plugins page; see acceptance report

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

• Design, safety, image policy, cost, and evidence
• Chinese install, configuration, rollback, and FAQ
• Release acceptance report
• Vision migration report
• Native WebUI repeat acceptance
• DSH 0.1.2-alpha.2 compatibility acceptance
• DSH 0.1.5-rc.1 compatibility acceptance
• Summary worker tier comparison on DSH 0.1.5-rc.1
• DSH 0.1.6-alpha.1 compatibility smoke
• DSH 0.1.6-alpha.2 compatibility acceptance
• Historical compression benchmark

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