DeepSeek Harness Plugin

zhaoyuntao-wl/dsh-plugin-thread

Stars ★ 2 Category Memory Added 2026-08-24

Decision-and-goal memory with lineage: explicit commands and a model tool record decisions deterministically, a status card re-anchors them across compaction, a lossless event stream with BM25+jieba retrieval backs it, and a scenario-level fidelity regression suite gates releases.

Install

# from GitHub (first run asks for allowBuilds approval — follow the hint, retry)

dsh plugin --profile web add github:zhaoyuntao-wl/dsh-plugin-thread

Any plugin you install runs third-party code with your own permissions — it can read your files, use your credentials, and reach the network, and tool approvals don’t sandbox it. GitHub-sourced plugins also run build scripts at install time — pnpm blocks those until you allow them, so an install can stop with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED or ERR_PNPM_IGNORED_BUILDS; dsh prints the exact key to add under allowBuilds in your profile’s pnpm-workspace.yaml, and the install works on the next run. Allowing a build is a trust decision: only install sources you trust, and pin a commit (github:owner/repo#sha).

README

CI

Thread's deep-integration plugin for DeepSeek Harness — session memory with lineage for coding agents, using the base's native channels end to end.

What it does

  • Lossless capture — subscribes to session/event; the full event stream lands in dual SQLite databases with stable origins (idempotent append).
  • Structural delivery, three triggers — a first-turn anchor (project identity
    • behavior contract + status card), a re-anchor after every compaction, and a cross-agent state delta at every turn boundary. No per-turn card noise. The design follows the deterministic-log line of memory research (e.g. arXiv:2605.21997 “The Log is the Agent”); the compaction re-anchor targets the “Compaction Cliff” failure mode (arXiv:2608.22752).
  • Native query tool — query_session_memory registered through ctx.tools.register into the model's tool schema, with filesystem-style navigation ls / cd / cat / grep. The embedded MCP server remains as a fallback channel. Retrieval is deterministic BM25 over the lossless stream (jieba word segmentation for Chinese) with citation pull-back — no embedding dependency by default; a hybrid layer can be added at the integration boundary (evaluated against the BM25 baseline on the eval suite, not bundled).
  • Behavior-contract skill — a thread skill is registered into the base's skill catalog ("need details → call the tool") and injected at anchors, so the model does not rely on memory to know it has memory.
  • Output recognition — write/edit tools on markdown documents register knowledge_assets with lineage edges on write; /thread-reg ast covers explicit registration.
  • Explicit decision & preference channels — decisions are recorded through /thread-reg dec (user, --supersedes <id> for chain evolution) or the model's record_decision tool (the behavior contract instructs the model to call it when the user settles a decision or it commits to one). Preferences and lessons are recorded through /thread-reg fdb (auto-classified as correction when phrased as "don't"). Natural-language extraction of decisions/preferences is off — zero text-heuristic false positives; the lossless event stream remains the backstop for anything unrecorded. (Goal detection from short imperative messages and completion detection stay on, guarded against pasted/multi-line text.)
  • Read-only panel — what the model believes, on demand — /thread-panel (and the thread_panel MCP tool) renders goals, the decision chain with supersession, open items, handoffs, the last injection receipt, acceptance evidence and recent events. Scope is the session merged with its project: decisions and goals registered by other sessions in the same project show up too, so a brand-new session is not blind to what the project already decided (it reads the same merge the status card uses). The receipt line answers “what exactly was fed to the model this round”; the panel resolves the session's project bucket from disk, so it works from a command context that never saw the agent object.
  • Evidence gate — “done” must be proven — decisions and completions carry evidence instead of claims: verify runs each acceptance criterion, records command + exit code + env fingerprint + commit in the evidence table, and returns passed / failed / missing-env (a criterion with no command is missing environment, never a pass). Completing a goal whose criteria are unproven is refused, and the refusal names the missing criteria. On close the registered criteria are re-run automatically, so the handoff carries fresh evidence rather than the previous round's verdict.
  • Blocking questions are captured — ask_user_question calls land in open_questions with their call_id; a real answer settles the row, a timeout (recognized by the base's documented pendingNotice text, not keyword guessing) is recorded as timed_out so “the agent decided for you” stays visible instead of being smoothed into “answered”.
  • Closing sediment + inbox — closing words sediment in-progress goals into todos; /thread-cfm is the single pending-work inbox: todos (t#id) and candidates (c#id) in one view — do completes/promotes (candidates accept a corrected text), cnl discards, cnl all clears both. The status card surfaces the top candidates so they cannot pile up silently.
  • Behavior notes (1.0, stated plainly) — candidates are not produced automatically: natural-language extraction of decisions/preferences is off, so c# entries only ever hold pre-existing rows until the post-release extraction layer arrives; todos are produced actively (closing sediment + goal-completion self-healing). Decisions never expire on their own — close out time-bound ones with --supersedes. Goal completion detection is conservative (≥4 non-ASCII / ≥8 pure-ASCII overlap; short English goals are missed rather than mis-judged — abandon them with /thread-rev gol). See the Thread README "Honest boundaries" section for the full list.
  • Resource cleanup — /thread-rev <ast|dec|fdb|gol> <ids|all> revokes registrations: decisions/preferences/assets are deleted (the event stream keeps the text), goals are abandoned through the state machine with their todos self-healed. Every structured row carries a visible #id on the status card, so memory stays human-editable end to end.
  • Session isolation — /thread-iso / /thread-uniso, and /thread-pub <ast|dec|fdb|gol> <ids|all> shares rows produced while isolated.
  • Optional active compaction — with THREAD_AUTO_COMPACT=1 the plugin monitors token pressure at turn boundaries and triggers compactNow silently; state re-anchors after every compaction either way.
  • Dev probe, inert by default — the package ships a batch0-probe module used for contract smoke-testing during development; it is inert unless THREAD_B0_PROBE=1 is set, so normal sessions are unaffected.

Full user guide: English · 中文.

Supported dsh versions

  • Local-first, no daemon — everything runs in-process: embedded SQLite stores, no background service, no cloud dependency. Headless and web profiles of the same machine share the same store, and offline sessions behave identically.

  • Verified: dsh 0.2.2-rc.1 (current; the CLI and its SDK sub-packages ship version-locked). 0.1.x is no longer declared — dsh 0.2.0 replaced the shared plugin message source with per-producer MessageSourceMap kinds, which this plugin now declares; 0.1.x users should stay on dsh-thread@1.2.x.

  • The plugin pins its SDK peers to ^0.2.2-rc.1 (dsh-tools/dsh-agent/dsh-session/dsh-user-questions) and @deepseek-ai/cordis to ^4.1.0 (dsh 0.2.2-rc.1 pins cordis at ~4.1.0); every upgrade is verified by an isolated contract probe (type-level compile against the released SDK plus a live headless profile run) and the CI compat matrix (.github/workflows/ci.yml) before this table is updated.

  • No promise is made beyond the verified entry; each new dsh release is evaluated and the matrix extended before support is claimed.

Install

dsh plugin add dsh-thread
dsh plugin add dsh-thread@latest   # 升级:同命令重装最新版(core 经 ^1.0.0 依赖自动跟随)

The plugin pulls its kernel (@thread-memory/core) through a ^1.0.0 range, so new installs and re-adds pick up the latest core automatically. The runtime logs the resolved core version at startup ([dsh-thread] thread core vX.Y.Z) and the embedded MCP server reports it in its handshake.

All dsh plugins must be referenced in a profile's bundles to take effect. In ~/.dsh/profiles/<your-profile>/package.json:

{
  "name": "dsh-profile-my",
  "private": true,
  "dependencies": {},
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-headless",
        "dsh-thread"
      ]
    }
  }
}

Zero configuration beyond that: @thread-memory/core + better-sqlite3 resolve as dependencies; capture and injection start as soon as the plugin is activated.

Note (native module): if the plugin fails to start with "Could not locate the bindings file", pnpm 10 ignored the better-sqlite3 build script during install. Fix with one command in the profile directory:

cd ~/.dsh/profiles/<your-profile>
pnpm rebuild better-sqlite3

This is a pnpm 10 onlyBuiltDependencies policy, not a plugin bug.

Configuration

Config Default Meaning
budgetLines 200 Status card line budget
feedbackRows 50 Feedback rows consulted by the tool guard
busyRetries / busyRetryDelayMs 20 / 100 SQLITE_BUSY retry policy
compactPressureTokens 0 Active-compaction token threshold (0 = off; requires THREAD_AUTO_COMPACT=1 to pull the compaction service)

Commands

Registered as real dsh commands — visible in the command palette, /-completable, and executed directly (no model round-trip). The same lines also work as plain messages where no command UI exists. One grammar, six commands:

Command Effect
/thread-reg <ast|dec|fdb|gol> List that resource's rows (ids for rev/supersede)
/thread-reg <ast|dec|fdb|gol> <text> Register: ast = path (directories expand recursively, cap 50) · dec = decision (active immediately; --supersedes <id> evolves the chain) · fdb = preference/lesson (auto-classified by "don't" phrasing) · gol = goal
/thread-rev <ast|dec|fdb|gol> List that resource's rows
/thread-rev <ast|dec|fdb|gol> <ids|all> Revoke: dec/fdb/ast are deleted (event stream keeps the text) · gol is abandoned (state machine + todos self-heal)
/thread-cfm Pending-work inbox: todos (t#id) + candidates (c#id)
/thread-cfm do <id> [text] t# complete a todo · c# promote a candidate to an active decision (optional corrected text)
/thread-cfm cnl <id> / cnl all Discard one item / clear the inbox
/thread-iso / /thread-uniso Silence / restore a session
/thread-pub List isolated rows (all resources, ids for sharing)
/thread-pub <ast|dec|fdb|gol> <ids|all> Share isolated rows
/thread-handoff [target] Produce a handoff from this session's state (optional target role; no target = project-addressed)
/thread-panel Read-only panel: goals · decision chain (with supersession) · open items · last injection receipt · acceptance evidence · handoffs · recent events

Evidence gate

Acceptance is evidence, not assertion:

// record + run criteria (omit `criteria` to re-run what was registered before)
await mcp.callTool({ name: "verify", arguments: { criteria: [
  { key: "unit-tests", command: "pnpm test" },
  { key: "lint",       command: "pnpm lint" },
] } });
// → 验收 1/2 已证(缺:lint)  + per-criterion { status, exit, output, evidenceId }
  • Each run stores command, exit code, environment fingerprint and commit in evidence; the panel shows the latest row per criterion.
  • checkCompletionGate refuses to mark a goal complete while any registered criterion lacks a passing row, and the refusal is surfaced to the model ([Thread 证据门] 目标未标完成:#3 缺 lint), not swallowed.
  • Criteria with no command are missing-env — they block completion but are never counted as proof.
  • Handoff briefs gain one line: 验收:验收 1/2 已证(缺:lint).

Visibility and receipts

The status card is injected as base instructions, so it is not a chat bubble. To keep “what was injected” auditable, every injection writes a receipt (kind: anchor | status-card | handoff, timestamp + summary) that the panel renders as 「本轮注入」. Cards are rebuilt from the store at injection time — they are never cached — and refreshed after decision confirmation, structural commands, closing sediment and compaction, plus once per turn in agent/pre-step.

Handoffs (for orchestrators)

Thread carries state across sessions: a finishing session leaves a compact brief — goal, up to three active decisions, open items, next steps, artifact pointers — and the receiving session starts with it instead of rediscovering it.

Thread does not schedule, launch, or retry anything. It is the state base your orchestrator sits on, not another orchestrator.

// start a worker with two extra fields
env: { THREAD_TASK_ID: taskId, THREAD_ROLE: "dev" }

// claim the handoff addressed to that task/role (atomic; marks it delivered)
const { content } = await mcp.callTool({ name: "handoff_next", arguments: { task_id: taskId, role: "dev" } });
// → { id, status, brief: { goal, decisions[], open[], next[], artifacts[], conditions[] } }

// acknowledge once consumed
await mcp.callTool({ name: "handoff_ack", arguments: { id } });

Guarantees: claiming is a single UPDATE … RETURNING (two workers never get the same row), producing is idempotent per goal, ack is idempotent, lookups are project-scoped, and any handoff failure fails open so the agent path never blocks. The brief carries pointers only — documents stay the artifact layer.

Measured (2026-11-13, three arms × 5 runs, empty workspace, same memory):

handoff pushed memory only no Thread
recalls the earlier decision 5/5 5/5 1/5
follows the producer's chosen next step 5/5 0/5 0/5
lookups by the receiving agent 1.0 6.8 4.2
mean wall time 7s 15s 12s

Details: Thread docs — handoff.

MCP fallback

The package ships an embedded MCP server (bin: dsh-thread) exposing the same query_session_memory contract over MCP for bases and setups where native tool registration is unavailable, plus thread_panel, verify, handoff_next and handoff_ack. See the Thread Memory Protocol.

Repository relationship

This repository hosts the dsh deep-integration plugin. The base-agnostic kernel (@thread-memory/core) and the Qoder adapter live in the main Thread repository.

License

MIT

Content from the project README on GitHub ↗

Links

More in this category

View the whole category →

Community comments

Comments are public GitHub Discussions. Loading them connects to GitHub and Giscus; a GitHub account is required to post.