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:
  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 reasoningEffort: "off", temperature: 0.3,
  maxTokens: min(2000, maxChars * 2 + 200), and the assembled system/user
  prompts.
• 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 to
  $DSH_HOME/dsh-bubble-explain.settings.json (values are clamped on write).

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