yuezengwu/dsh-explain

dsh-explain is a learning-mode plugin for DeepSeek Harness. It turns useful concepts from completed work into structured explanations, schedules lightweight reviews, and lets you inspect or correct what it learns about you.

The primary agent stays untouched. Explain uses its own model calls, scheduler, context, and local SQLite database.

See the learning loop

The 28-second preview runs against real assembled DSH Web 0.1.2-rc.1 with deterministic, private fixture data. Watch the higher-quality MP4 or read the recording contract.

Capture	Review	Adapt
Turn a finalized answer or selected text into an editable /explain draft. Nothing submits automatically.	Revisit due concepts through recall, application, and distinction questions.	Inspect explanation preferences and topic familiarity, then correct or forget an inference.

Quick start

DSH 0.2.1-rc.5, 0.2.2-rc.1 and 0.2.2-alpha.3 support is available on main, preserving all twenty-eight previously verified hosts, including rc.4 and alpha.2. This is not a new Explain release: v0.3.1 still supports DSH through 0.1.6-alpha.2. See the compatibility contract for exact source revisions and evidence.

As checked on 2026-11-06, CLI npm latest=next=0.2.2-rc.1 and alpha=0.2.2-alpha.3. Pin the verified default explicitly (Node.js >=24.9):

npx @deepseek-ai/dsh@0.2.2-rc.1 plugin --profile web add github:yuezengwu/dsh-explain#main
npx @deepseek-ai/dsh@0.2.2-rc.1 --profile web

The verified default requires Node.js >=24.9. Keep rc.5 as a pinned fallback:

npx @deepseek-ai/dsh@0.2.1-rc.5 plugin --profile web add github:yuezengwu/dsh-explain#main
npx @deepseek-ai/dsh@0.2.1-rc.5 --profile web

The previously verified rc.2 and rc.4 remain supported; replace both CLI pins with the chosen exact version. For the existing tagged release, keep DSH 0.1.6-alpha.2 and install github:yuezengwu/dsh-explain#v0.3.1.

The verified alpha requires Node.js 24.9 or newer. Pin its version explicitly:

npx @deepseek-ai/dsh@0.2.2-alpha.3 plugin --profile web add github:yuezengwu/dsh-explain#main
npx @deepseek-ai/dsh@0.2.2-alpha.3 --profile web

Open Settings → Learning, choose an auxiliary provider and model, enable learning mode, and save. Explain observes only future completed top-level turns; it does not scan existing history.

Git-hosted plugins build during installation. If pnpm requests build approval, add the printed dsh-explain entry to the profile's pnpm-workspace.yaml, then repeat the install command. For automated runs that should not open a browser, start DSH with --no-open.

v0.3.1 adds DSH 0.1.6-alpha.2 support while retaining all eight previously verified hosts. It fixes source navigation and Explain shortcuts for the new Session API, with live plugin disable/re-enable coverage. Existing learning data remains compatible (SQLite schema 4, backup v3).

Start from the work itself

Entry point	What happens
/explain <request>	Requests an explanation using the current session as bounded source context.
Explain selected text	Creates an editable /explain --selection … draft from visible text.
Learn from this answer	Creates an editable draft tied to the exact finalized assistant turn.
Automatic evaluation	May add one useful explanation after an eligible turn, within your configured budget.
/review	Opens or resumes a local review round in the Learning tab.

Each explanation answers three practical questions: What is it? Why does it matter here? What is the common pitfall? Choose Got it to close the card, or Not yet for a different explanation.

Review, then correct the model

Concepts marked Got it enter a local spaced-review schedule. Learning → Today's review selects up to three due concepts. Each concept advances from recall to application to distinction after successful answers; an unsuccessful answer repeats that skill next time. The auxiliary model evaluates each answer as Mastered, Partial, or Forgotten and schedules the next review at a deterministic interval. Partial or forgotten concepts are treated as learning again and can receive a new explanation; an active explanation pauses that concept's quiz.

Learning → Learning overview exposes the current judgments about explanation length, structure, examples, terminology, and topic familiarity—with confidence and source links. You can correct an inference, forget it, or set an explicit preference. Precedence is fixed and visible: explicit preference → user correction → model inference.

One learning thread, many sessions

• Every $DSH_HOME owns exactly one Explain learning thread; resumes and forks never copy it.
• Every source session has at most one explanation awaiting feedback.
• One global scheduler serializes explanations, reviews, autonomous evaluation, rephrases, and compaction.
• Autonomous evaluation has a persistent rolling 24-hour budget, configurable in Settings.
• Rephrasing still works if a source session is later deleted because only a bounded source summary is retained.

Local-first by design

Data	Behavior
Learning thread	Stored in $DSH_HOME/dsh-explain/v1/thread.sqlite.
Enablement and model settings	DSH 0.1.7 stores live fields in the active profile patch; older hosts use $DSH_HOME/settings.yaml. Explain imports its own legacy section once per profile, preserves explicit profile overrides and the original file, and leaves storage paths unchanged.
Source material	Reduced to bounded capsules; rephrasing retains at most a 2,000-character restricted summary.
Global learning context	Sent with bounded source text to the configured auxiliary provider. Local storage does not imply offline model inference.
Export	A versioned local backup excludes private source summaries and filters common credential/path formats in public text. Arbitrary private prose may remain; review before sharing.
Clear	A typed CLEAR confirmation atomically removes learned content while preserving runtime settings and the active budget window.

Explain uses first-party DSH conversation, composer, assistant-action, and settings extension points. It does not require patches to DSH or other plugins.

Compatibility and verification

Check	Current result
DSH compatibility	0.2.1-rc.5 / 0.2.2-rc.1 published packages; 0.1.2-rc.1, 0.1.3-alpha.1, 0.1.3-alpha.2, 0.1.5-alpha.1, 0.1.5-alpha.2, 0.1.5-rc.1, 0.1.5-rc.2, 0.1.5-rc.3, 0.1.6-alpha.1, 0.1.6-alpha.2, 0.1.7-alpha.1, 0.1.7-alpha.2, 0.1.7-rc.1, 0.1.7-rc.2, 0.2.0-rc.1, 0.2.0-rc.2, 0.2.1-alpha.1, 0.2.1-alpha.2, 0.2.1-alpha.3, 0.2.1-alpha.4, 0.2.1-alpha.5, 0.2.1-rc.1, 0.2.1-rc.2, 0.2.1-rc.3, 0.2.1-rc.4, 0.2.1-rc.5, 0.2.2-alpha.2, 0.2.2-alpha.3, 0.2.2-rc.1 assembled source
Unit and integration	108 tests on each of the twenty-nine source versions
Assembled DSH Web	7 shared scenarios; 0.1.7, 0.2.0, and 0.2.1 add legacy-settings migration and restart coverage
Explain-owned shortcuts	3 M6 scenarios for unload/remove/reinstall; live disable/re-enable additionally runs on 0.1.6-alpha.2
Production package	Frozen install, build and pack
Real auxiliary model	DSH 0.1.6-alpha.1 + deepseek-flash: explanation, rephrase, corrected preference, correct/incorrect review, exact-answer command, export and clear

See the acceptance matrix for coverage and the 2026-09-15 real-model acceptance for the current model route, sample, screenshots, and test limits. DSH remains a developer preview; Explain follows its current public API line instead of retaining compatibility layers for private-preview packages.

Local development

The default development install uses published 0.2.2-rc.1 API packages, with a version-scoped repair for their missing store runtime dependencies. Assembled-Web tests accept a built DSH checkout for any of the twenty-nine versions above. The existing demo recording remains on 0.1.2-rc.1:

pnpm install
DSH_SOURCE_DIR=/absolute/path/to/dsh pnpm dsh:link
DSH_SOURCE_DIR=/absolute/path/to/dsh pnpm dsh:link:check
pnpm typecheck
pnpm test
DSH_SOURCE_DIR=/absolute/path/to/dsh pnpm test:web
DSH_SOURCE_DIR=/absolute/path/to/dsh pnpm test:m6
pnpm build

Install this checkout directly for manual development:

dsh plugin --profile web add /absolute/path/to/dsh-explain
dsh --profile web --dump-config
dsh --profile web

Documentation

Document	Purpose
Demo production	Storyboard, privacy contract, commands, assets, and artwork provenance.
Product requirements	User model, scope, policies, and acceptance criteria.
Architecture	Persistence, scheduling, RPC, UI integration, and failure behavior.
Architecture audit and improvements	Code evidence, verification boundaries, and prioritized follow-up work (Chinese).
Queue scale validation	Synthetic before/after measurements and queue lifecycle invariants (Chinese).
Acceptance matrix	Automated and real-flow evidence.
Iteration plan	Completed milestones and follow-up sequencing.

License

MIT