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)

Field	Limit
text	non-empty, ≤ 4000 chars
parent.text / parent.explanation	≤ 10000 chars each
depth	0–6
maxChars	50–1000

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

<video src="docs/promo/dsh-bubble-explain-promo.mp4" poster="docs/promo/poster.png" controls width="720"></video>

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):

…