lacemou/dsh-session-ref

Cross-session reference (mention) plugin for DeepSeek Harness.

Paste @[label](dsh-session:<id>) into any session — including one in a different workspace/folder — and the host resolves the referenced session and injects its content snapshot for the model to read. Cross-folder tasks and conversations can be referenced directly; no more paraphrasing by hand.

Full design notes: SPEC.md (Chinese).

Version support (0.2.x)

Plugin	DSH host	Notes
0.2.x (current)	0.1.2-rc.1 and same-cohort releases	Targets the newest cohort; the client half is shape-compatible with older cohorts
0.1.x	0.1.0-rc.6 – 0.1.1-rc.2	Legacy-cohort release line (see .agents/MIGRATION-0.1.2.md)

The 0.1.2 cohort removed @deepseek-ai/dsh-client-runtime (which the 0.1.x client depended on), so 0.2.0's client half carries zero value imports from host packages: the bundle only requires react, dsh.client.inject is empty, and all types point at the 0.1.2-rc.1 domain packages (cordis, dsh-api-session-controller, dsh-session). The same artifact no longer falls out of the boot graph on 0.1.2+ hosts due to a phantom dependency (DSH-0.1.2-A1-25).

Features (MVP)

• Host half: an agent/pre-step listener parses @[label](dsh-session:…) and bare dsh-session:<id> mentions, calls the native sessionReferenceResolver.prepare() to inject the snapshot (rendered as a distinct Session recall row), and rewrites the mention into a readable @label. The sessionReferenceResolver service is registered by the plugin when the deployment does not mount it (as in rc.6 profiles).
• Client half: a 复制引用 / Copy reference button in the composer tool row copies the current session's mention (@[title](dsh-session:<id>)) to the clipboard in one click.
• Everything cross-session reuses the native @deepseek-ai/dsh-session-reference pipeline: parallel source reads, deduplication, budget bounds (≤3 sources / ≤64 KB), self-reference rejection, and the untrusted-context warning.

Important limitations

1. Community plugin: not an official DSH component; maintained by the community. Relies on host-internal contracts that may break on upgrades.
2. Snapshot semantics: references are capture-time snapshots, not live sessions; subsequent source changes do not propagate to the target.
3. Context budget: at most 3 sources per message and 64 KB per source snapshot; over-budget references are truncated or rejected outright.
4. Self-reference rejection: referencing the current session is rejected natively to prevent cycles.
5. Internal dependencies: depends on host-internal interfaces (agent/pre-step, sessionReferenceResolver) and session-log formats; may break after host upgrades.
6. Capability boundary: not infinite context (injected snapshots occupy target context until compaction) and not automatic collaboration (one-way reference; no messaging or task handoff).

Install

# Option 1: npm (recommended)
dsh plugin --profile web add dsh-session-ref

# Option 2: git checkout (lib/ is committed — no build step)
git clone https://github.com/lacemou/dsh-session-ref
cd dsh-session-ref
dsh plugin --profile web add /path/to/dsh-session-ref

# Option 3: local development
cd dsh-session-ref
npm install
npm run build
dsh plugin --profile web add /path/to/dsh-session-ref

Then restart the web process (Ctrl-C, then dsh web again) so the new bundle is picked up.

Published as a git/npm bundle, lib/ is committed — no build step is needed on the installing side.

Usage

1. In session A, click 复制引用 / Copy reference in the composer tool row.
2. The clipboard now holds @[titleA](dsh-session:…).
3. In session B (which can be in another workspace), paste and send.
4. The transcript shows a distinct Session recall row (source title plus retained/omitted stats), and the model sees the ## Referenced sessions snapshot alongside the readable @titleA.

You can also write mentions by hand: @[any label](dsh-session:<id>) or a bare dsh-session:<id>.

Self-references (referencing the current session) are rejected natively, as are messages exceeding 3 distinct sources or the snapshot byte budget — the message is passed through untouched in those cases.

Development

npm run typecheck   # tsc --noEmit
npm run test        # vitest run (21 tests: host injection, URI encoding parity, client copy)
npm run build       # tsc --noEmit + tsdown → lib/index.js (host) + lib/client.js (browser)

Known limitations

• No @ autocomplete yet (see M2 in the roadmap below; the MVP closes the loop via copy-reference → paste).
• Text-only projection: non-text blocks (images, tool results) do not cross sessions.
• Reading sessions written by other DSH versions may fail (native limitation); on failure the message degrades to its raw form.
• Cross-process references to sessions the current host has never loaded go through the persistence path, which some deployments (e.g. headless profiles) may not serve; referencing live sessions always works.

Roadmap

Milestone	Scope
M2	@ autocomplete in the composer: typing @ lists session candidates (from the native listCandidates, ranked by workspace affinity); keyboard selection inserts @[title](dsh-session:…) — upgrading copy-paste to a one-step mention
M3	Cross-workspace directory browsing + reference granularity (whole session / user nodes / ranges)
M4	Integration with dsh-crosstalk: reference + handoff
M5	Contribute "copy session ID / copy reference" back to the upstream core UI

Full design notes: SPEC.md (Chinese).

License

MIT