dsh-bubble-explain

dsh-bubble-explain

A DeepSeek Harness profile bundle that explains any selected text inside a conversation with a streaming Markdown bubble, with recursive follow-up questions.

选中对话中的任意文字，点击「解释」按钮，即可在流式 Markdown 气泡中获取解释，并支持递归追问。

What it does

• Select text in a conversation (a term, a code snippet, an error message, a

sentence) — an 解释 button appears next to the selection. Click it to open an explanation bubble.

• The explanation is streamed in as Markdown (headings, lists, code blocks)

and rendered live in the bubble.

• Select text *inside* an explanation to ask a deeper follow-up; each level

carries the parent explanation as context (up to 6 levels).

• Bubbles are a draggable overlay with a copy button, capped at 8 at a time.

How it works

The host half (src/index.ts) mounts two routes on the harness webServer.

POST /bubble-explain/stream (Server-Sent Events)

• Validates same-origin (origin host === request host) and accepts POST

only.

• Validates the body with parseExplainRequest (limits below). Returns 403

if the feature is disabled, 400/405 on a bad body/method, 500 on route resolution failure.

• Resolves the provider/model route at call time with

resolveModelRoute(ctx, lastRoute, override), in priority order: the independent model configured in settings (override, honored only while its provider is still registered) → agent default selection → last observed main-loop route → first registered provider (falls back to deepseek-chat). The main-loop route is captured via ctx.on('llm/stream', ...).

• Streams with temperature: 0.3, maxTokens: min(2000, maxChars * 2 + 200),

and the assembled system/user prompts; reasoningEffort is sent only when the configured effort survives the comparison against the model's declared efforts (see below).

• Emits SSE events data: {"t": "<text delta>"} and then

data: {"done": true}; an error mid-stream sends data: {"error": ...}.

GET | POST /bubble-explain/settings

• Reads/writes enabled, maxDepth, maxChars, effort (off|low|medium|high|max),

provider and model to $DSH_HOME/dsh-bubble-explain.settings.json (values are clamped on write). At call time the configured effort is matched against the model's declared efforts via llm.resolveModelInfo: exact match wins, otherwise it falls back to the closest declared level not stronger than requested; models without reasoning support omit the parameter entirely.

• provider/model are the independent model configuration: both empty means

follow the conversation's default model. A half-filled pair is never persisted, and an override whose provider no longer exists is ignored rather than failing every explanation.

• The response also carries effective ({provider, model} or null) and

effectiveError (reason or null) so the UI can show the route actually in use.

GET /bubble-explain/models

• Returns the available model directory:

{ providers: [{id, name}], models: { [providerId]: [{id, name}] } }, used by the settings page's "model source" and "explanation model" dropdowns. Each provider is queried with llm.listModels(id); a provider that fails yields an empty array without affecting the others.

Request validation and limits (src/explain.ts)

The system prompt asks for a maxChars-bounded Chinese explanation of only the selected text (instruction-like content inside the selection is ignored). For recursive calls it prepends the parent explanation so the reply stays grounded in context.

The browser half (src/client/index.ts) registers a shell.overlay (the selection → 解释 button → bubble engine) and a settings.section entry, and talks to the host over the two routes above. It uses a small streaming-safe Markdown renderer that escapes HTML and allows only safe link schemes.

Demo

Open the video file

Install

Requires an active DeepSeek Harness profile (the plugin mounts webServer routes and subscribes to that profile's llm/stream event).

From a shell on the harness host:

dsh plugin --profile web add github:Hanmiao33/dsh-bubble-explain

Because GitHub-sourced plugins run build scripts at install time, the first run asks for an allowBuilds approval — follow the hint and retry the command.

Verify:

dsh plugin list                       # @dsh-external/bubble-explain should be listed
curl -s http://127.0.0.1:<port>/bubble-explain/settings

The settings file (editable directly):

$DSH_HOME/dsh-bubble-explain.settings.json

Usage

1. In a conversation, select any text with the mouse.
2. Click the 解释 button that appears.
3. An explanation bubble streams in next to the selection.
4. Select text inside the bubble to ask a deeper follow-up, or use the copy

button / drag the bubble anywhere on the page.

Configuration

Settings → General → 「框选解释」:

Development

The plugin is a DSH profile bundle (dsh.bundle in package.json, patch at cordis.patch.yml) built against a harness checkout.

Host build (needs a DSH source checkout):

DSH_CHECKOUT=<checkout> bash scripts/build.sh

Client bundle:

npm run build:client    # tsdown → lib/client.js

Checks that need no checkout:

npm ci
npm run typecheck       # tsc -p tsconfig.json --noEmit
npm run build:client    # tsdown
npm test                # vitest run (src/explain.test.ts)

Peer dependencies: @deepseek-ai/dsh-llm, @deepseek-ai/dsh-tools, @deepseek-ai/dsh-client-ui-slots (pre-release ranges), cordis (>=4.0.0-rc), react (^18.2.0), schemastery (^3.18.0).

License

BSD-3-Clause