yuezengwu/dsh-explain

English | 简体中文

dsh-explain — Learning mode for DSH

✅ Status: M6 is implemented entirely in Explain and passes its DSH 0.1.0-rc.6 acceptance gates. No other plugin requires a patch or runtime dependency. See the product requirements and technical architecture for the full design. The detailed design documents are currently written in Chinese.

dsh-explain turns useful material from multiple DeepSeek Harness work sessions into one private, local-first learning thread. It keeps at most one active explanation per source session and continuously adapts explanations to the user's knowledge, preferences, and learning progress.

Core behavior

• A $DSH_HOME contains exactly one local learning thread. Work sessions, resumes, and forks do not copy its state.
• Each top-level source session may have one explanation awaiting feedback, or none. While one remains open, that source cannot generate another; other sources may continue independently.
• Enter /explain <learning request> in the composer of an established or empty session to request an explanation. /explain on, /explain off, and /explain status manage the feature.
• Select visible text and use Explain's composer-row shortcut, or use the Explain action on any finalized assistant answer. Both create an editable command draft and never submit it automatically.
• Manual explanations, autonomous explanations, rephrases, and compaction share one global scheduler. At most one auxiliary model request runs at a time.
• Autonomous evaluation defaults to 50 requests per rolling 24-hour window. Usage survives restarts; failures and retries count, while manual explanations, rephrases, and compaction do not.
• A private global ExplainContext summarizes conversation preferences, knowledge level, and learning progress. It is sent only to the auxiliary model and is never injected into the primary agent.
• Auxiliary history is compacted after new structured observations or closed explanations remain untouched for 30 minutes, or before a request would exceed 50% of the selected model's context window. User-visible history is never deleted.
• The primary model does not know that Explain exists. Explain does not write to the primary session log, modify the primary model context, or block the primary turn.
• Learning history, active-source state, compaction checkpoints, and ExplainContext are stored in $DSH_HOME/dsh-explain/v1/thread.sqlite. Enablement and model settings use $DSH_HOME/settings.yaml.
• The first entry of an explanation stores a restricted source summary of up to 2,000 characters for later rephrasing. Rephrasing still works after the source session is deleted, and the summary is not exposed through the learning-view API.
• The learning thread appears in the first-party conversation.view slot as a Learning tab. Configuration and diagnostics use the first-party settings.section; no external UI host is required.
• The Learning tab is session-scoped, but every tab reads the same global client store and typed Remote. All work sessions therefore display the same learning thread.
• The settings page controls the auxiliary model, enablement, and rolling autonomous-request budget, and reports routing, budget recovery, context pressure, and the latest compaction.
• If a source still exists in the current session inventory, its explanation can open it directly. Deleted sources remain readable and are marked unavailable.
• P0 never switches views automatically. Empty Hero sessions do not display view tabs, and the work-session composer remains available while the Learning view is open.
• P0 has no external UI dependency and does not bundle or require better-sidebar.

Why

• DSH can complete complex work, but a result alone may not teach the concepts, tradeoffs, or common pitfalls involved.
• Explain turns ordinary work sessions into learning material without requiring users to know what to ask in advance.
• Learning state needs to remain coherent across work sessions, so all material enters one global thread while source-specific active explanations preserve local continuity.

Progress

• Product overlap review: no direct duplicate was found; related plugins provide implementation references only.
• P0 PRD: one global thread, per-source active explanations, an autonomous-call budget, two compaction triggers, global ExplainContext, and automatable acceptance criteria.
• Architecture v11: Explain owns both shortcut adapters on first-party DSH slots; optional plugins remain unmodified and unobserved.
• UI path: first-party conversation.view registration following the ui-trajectory view-ring pattern, with no external UI dependency.
• M1 infrastructure: standalone plugin build, local SQLite schema, entity-level CAS, pagination, long polling, and generated typed Remotes.
• M2 implementation: source observation, single-flight auxiliary scheduling, durable budgets, rephrasing, dual-trigger compaction, ExplainContext, and the Learning view.
• M2 real DSH Web/model flow and GIF acceptance evidence.
• M3 release gates: P0 acceptance matrix, keyless assembled-Web snapshot, and installation/composition smoke tests.
• M4 configuration and diagnostics: settings UI without YAML editing, concurrent-setting convergence, source navigation and missing-source fallback, shared diagnostics store, and expanded assembled-Web snapshot.
• M5 manual learning command: /explain <learning request>, explicit-request scheduling, source labels, durable rephrase summaries, and stable failure results.
• M6.1 Explain Host protocol: --selection and --answer <turn> source resolution, origin persistence, rephrase propagation, legacy --suggested input compatibility, and stable failures.
• M6 P1 implementation: selected text, exact assistant answers, and explicitly selected visible Advisor suggestions enter the same learning loop through Explain-owned editable drafts.

M1 established persistence and Host/Client RPC. M2 completed the learning loop. M3 added release gates. M4 made configuration, diagnostics, and source navigation available in the UI. M5 added user-initiated learning from the composer. M6 adds Explain-owned shortcuts without modifying optional plugins. See the acceptance matrix for automated evidence.

Current iteration

M6 registers an Explain selection action in conversation.input.left and an exact-answer action in conversation.chat.assistant-actions. Both use the public per-session input facade, recheck the live composer at click time, write only an editable draft, and remain independent of dsh-selection-chat, dsh-suggested-replies, and dsh-advisor. The scope and evidence are recorded in docs/NEXT.md.

Install

Explain currently targets DSH 0.1.0-rc.6. DSH is a developer preview, so older private-preview package lines are not supported.

npx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web add github:yuezengwu/dsh-explain
npx @deepseek-ai/dsh@0.1.0-rc.6 web

Git-hosted plugins build during installation. If pnpm asks for build approval, add the printed dsh-explain entry to the profile's pnpm-workspace.yaml and repeat the install command.

Local development

The default build uses the public DSH 0.1.0-rc.6 API packages. A built DSH source checkout is required for assembled-Web acceptance; link it explicitly after installing dependencies:

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

The source checkout must match the 0.1.0-rc.6 public API surface. Compatibility layers for earlier private-preview package lines are not retained.

test:web starts a real keyless DSH Web composition with a fresh temporary $DSH_HOME, a durable session fixture, and a pre-seeded Explain database. It compares the Learning and Settings ARIA output against golden snapshots and verifies native settings revisions, source navigation, and the missing-source fallback. To intentionally update the UI output, run DSH_SOURCE_DIR=/absolute/path/to/dsh pnpm run test:web:refresh and review the snapshot diff.

test:m6 installs only Explain into a fresh profile. It verifies that no consumer plugin is present, both shortcuts produce exact editable drafts without submitting, and removing then reinstalling Explain restores the complete layer once.

Install the development checkout directly rather than through npm:

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

Related design survey

The product goal has no direct duplicate. The following projects informed individual implementation choices but do not define this project's data model.

Project	Reused idea	Deliberately not reused
dsh-auto-blame	Background model calls after a turn and client feedback patterns	External custom session events and projections are not used for Explain persistence
dsh-advisor	Transcript deltas, isolated model calls, emission guards, and configuration gateways	Advisor injects suggestions into the primary agent; Explain never injects the primary model
dsh-memory	Repository naming covers the long-term-memory direction	The placeholder contains no reusable service or protocol
dsh-memory-evolve	Cross-session layered memory, low-frequency snapshots, and user-visible management	Its snapshots enter the primary agent; Explain neither depends on nor reads its private files
DSH compact-basic, token-meter, and LLM model info	Capacity thresholds, deterministic token estimates, and routed contextWindow values	Native compaction modifies one session surface; Explain needs its own global SQLite compactor
DSH third-party memory MCP example	Optional interoperability reference for cross-session persistence	Model-initiated tool calls and an external provider do not fit automatic P0 ExplainContext updates
DSH ui-trajectory	conversation.view registration, session-header tabs, and active-only rendering	Trajectory uses a session-event view model; learning facts remain in Explain SQLite and Remotes
DSH-better-sidebar	Side-workbench interaction reference	P0 does not require simultaneous work and learning views, so it adds no sidebar service or dependency tree
official-plugins-port claude/learning-output-style and claude/explanatory-output-style	Learning and explanation prompt references	A system prompt alone cannot provide isolated scheduling, durable history, or a feedback loop
dsh-edu	Possible future knowledge-artifact formats	P0 does not implement courses, quizzes, cards, or spaced review

License

MIT