@yfwu2020/dsh-selection-explain 0.1.2 → 0.1.3

package/README.md

@@ -2,7 +2,8 @@
 
 > 在 [DSH](https://github.com/deepseek-ai) Web 界面里**选中任意文字**，就地得到**专业翻译** + **这段文字在当前上下文里到底是什么意思**，还能接着追问、或一键升格成正式会话。
 
-[![version](https://img.shields.io/badge/version-0.1.0-blue)](https://github.com/yfwu2020/dsh-selection-explain/releases)
+[![release](https://img.shields.io/github/v/release/yfwu2020/dsh-selection-explain?label=release)](https://github.com/yfwu2020/dsh-selection-explain/releases)
+[![npm](https://img.shields.io/npm/v/@yfwu2020/dsh-selection-explain?label=npm)](https://www.npmjs.com/package/@yfwu2020/dsh-selection-explain)
 [![license](https://img.shields.io/badge/license-MIT-green)](./package.json)
 [![DSH plugin](https://img.shields.io/badge/DSH-plugin-8b5cf6)](https://github.com/yfwu2020/dsh-selection-explain)
 
@@ -24,6 +25,8 @@
 
 点开面板**先只出翻译**（上下文窗口收窄到 8 条消息，首字最快）；翻译出来后才出现 **`↓ 展开详解`**，点了才用完整会话背景（24 条消息）做深度解读。想要快就停在第一段，想要透就展开——**不强迫你为深度等首字**。
 
+<img src="assets/stage1.png" alt="首轮：只有翻译一节 + 展开详解按钮" width="540">
+
 ### 翻译：按选中内容的语言和形态自适应
 
 不是无脑翻译，而是先判断这段文字是什么，只给对应的那一种：
@@ -49,6 +52,8 @@
 
 如果选中的是代码（在 `<pre>/<code>` 里，或文本特征像代码），首轮标题变成「**注释**」：整个回答是一个代码块，里面是**注释 + 原代码交替**的批注清单——每条语句**前面**一行该语言的注释符号（`//`、`#`、`--`、`<!--`…），原代码逐字不变。注释行弱化显示，一眼分得清哪行是代码、哪行是批注。缩进按原行起始列对齐，折行也不会跑到注释左边。
 
+<img src="assets/code.png" alt="选中代码：注释与原代码交替的批注清单" width="540">
+
 ### 临时对话小窗
 
 翻译一出来就能直接追问，不必先展开详解：
@@ -59,6 +64,30 @@
 - 生成中可以点**停止**打断；没有可用结果时给「重新生成」。
 - 关掉面板**不会丢**：点右下角胶囊原样回来，不重新请求。
 
+<img src="assets/stage2.png" alt="展开详解后：翻译与详解两节卡片，下方可继续追问" width="540">
+
+### 输出偏好：Markdown ↔ 网页
+
+输入区左下角那个两格开关（`M↓` = Markdown / `▭` = 网页）决定**追问的回答用什么形式**。默认是 **Markdown**，选择记在浏览器本地，下次打开还是它。
+
+| 档位 | 行为 |
+| --- | --- |
+| **Markdown**（默认） | 普通文字 / Markdown 回答——标题、列表、表格、代码块都可以。**并不禁止 HTML**：如果某个问题用一页网页明显讲得更清楚，照样会给网页；只是不会为了"好看"把简单问题做成页面 |
+| **网页** | **网页优先**（不是"一律网页"）：需要对比、流程、层级、图表，或文字答案会长到不好读 → 直接给**完整的单文件 HTML**，页面本身就是答案；一两段话能说清的简单问题**仍然用文字回答** |
+
+<img src="assets/web.png" alt="网页模式：回答里嵌一张可交互的页面，带「预览 / 源码」切换" width="540">
+
+**网页输出的优点**（也是它值得单独一档的原因）：
+
+- **复杂信息能"看"而不是"读"**：三种方案的取舍做成对照表 + 条形图，一眼看出差别；文字版要读三段才建立同样的印象。
+- **页面就是答案，不是附件**：生成的是**完整单文件 HTML**（样式与脚本全内联），小窗当场渲染成可交互页面——能悬停、能点、能滚，不用保存成文件再打开。
+- **两个视图随时切**：回答上方有 `预览 / 源码` 两个页签，切到源码就能把 HTML 拿走。
+- **默认就整页展示**：预览高度**由页面内容决定**（内部不滚动），所以一页对比表能完整看下来；想收起来点右侧 **`⤡ 还原`**，回到固定高度（320px、内部滚动）。
+- **有设计规范兜底**：开网页模式时，插件会把自己带的 `skills/web-design/SKILL.md` 注入提示词——按小窗**约 500px 宽的窄容器**写的单列布局规范，避免生成那种"三栏卡片 + 渐变大标题"的通用 AI 模板感。（该文件读不到时有一份内置兜底，不会因此失败。）
+- **回答仍然可追问**：网页结果会作为前情带回下一轮，可以继续说"把第二列改成时间线"。
+
+**什么时候别用网页**：只想要一段解释、或要的是可以直接复制的文本时，Markdown 更快也更省 token——网页要生成一整份 HTML，等待时间和输出长度都更大。
+
 ### 「最近聊过的」历史
 
 面板头部 `🕘 最近` 打开独立浮层列表（贴面板侧边，空间不够自动翻到另一侧）。重划同一个词**直接回放上次的对话，一次模型都不调**。默认保留最近 20 个划词条目（每个条目含它自己的全部追问），LRU 淘汰，**升格过的条目不会被淘汰**。
@@ -77,6 +106,15 @@
 
 面板自带 Markdown 渲染器（段落、多级列表、小标题、表格、引用、代码块）和**语法高亮 tokenizer**（自研，零依赖）：注释 / 字符串 / 数字 / 关键字 / 函数名 / 类型 / 标签 / 属性 / 变量 / 运算符分色，按围栏语言标记选规则。配色跟随**面板实际底色**判定，不是看系统偏好——所以 App 深色 + 系统浅色也不会出现深底配深字。文字对比度实测全部 ≥ WCAG AA 4.5。
 
+<!--
+  上面几张演示图的来源（要换图看这里）：
+  · 图由 scripts/build-demo-pages.mjs 生成演示页 —— 样式直接从 lib/client.js 抽取真实 CSS，
+    DOM 结构与文案照 src/client/index.js 的渲染器写，所以和真实面板一致（非手绘示意图）。
+  · 截图：Chrome 无头（--headless --screenshot --force-device-scale-factor=2）
+  · 裁边：node scripts/crop-png.mjs <in.png> assets/<name>.png 24
+  · 想换成真实环境截图，直接用同名文件覆盖 assets/ 下的图片即可。
+-->
+
 ---
 
 ## 安装
@@ -93,21 +131,26 @@ dsh plugin --profile web add @yfwu2020/dsh-selection-explain
 
 ### 方式二：从 Release 安装
 
-每个 Release 都附了**构建好的 `.tgz`**（含 `lib/` 产物，装完即可用，无需 clone 源码）：
+每个 Release 都附了**构建好的 `.tgz`**（含 `lib/` 产物，装完即可用，无需 clone 源码）。
+用 `latest` 路径可以不写版本号、永远取最新：
 
 ```bash
-# 下载最新 release 的安装包
-curl -LO https://github.com/yfwu2020/dsh-selection-explain/releases/download/v0.1.0/yfwu2020-dsh-selection-explain-0.1.0.tgz
+# 下载最新 release 的安装包（无需知道版本号）
+VER=$(curl -sI https://github.com/yfwu2020/dsh-selection-explain/releases/latest | grep -i '^location:' | sed 's|.*/tag/v||' | tr -d '\r\n')
+curl -LO "https://github.com/yfwu2020/dsh-selection-explain/releases/download/v$VER/yfwu2020-dsh-selection-explain-$VER.tgz"
 
 # 解包到插件目录
 mkdir -p ~/.dsh/plugins/dsh-selection-explain
-tar -xzf yfwu2020-dsh-selection-explain-0.1.0.tgz \
+tar -xzf "yfwu2020-dsh-selection-explain-$VER.tgz" \
   -C ~/.dsh/plugins/dsh-selection-explain --strip-components=1
 
 # 装配到 profile（重启后由官方接管）
 dsh plugin --profile web add ~/.dsh/plugins/dsh-selection-explain
 ```
 
+> 也可以直接下某个固定版本，把上面的 `$VER` 换成版本号即可，例如
+> `.../releases/download/v0.1.2/yfwu2020-dsh-selection-explain-0.1.2.tgz`。
+
 ### 方式三：从源码安装
 
 ```bash
@@ -277,13 +320,14 @@ curl -s http://127.0.0.1:3080/selection-explain/api/ping
 
 ```bash
 npm run build       # 构建（= bash scripts/build.sh）
-npm test            # 463 条断言（filters / client / transcript / guard）
+npm test            # 489 条断言（filters / prompt / client / transcript / guard）
 npm run typecheck   # tsc --noEmit
 ```
 
 | 脚本 | 用途 |
 | --- | --- |
-| `scripts/test-client.mjs` | 无浏览器集成测试：真实 host 路由 + 最小 DOM 桩，覆盖槽注册 → 划词浮标 → 点击 → SSE 流式渲染 → 两节内容 → 清理 |
+| `scripts/test-client.mjs` | 无浏览器集成测试：真实 host 路由 + 最小 DOM 桩，覆盖槽注册 → 划词浮标 → 点击 → SSE 流式渲染 → 两节内容 → 清理（host 不在跑时自动跳过在线断言） |
+| `scripts/test-prompt.mjs` | **提示词契约测试**：把两节结构标题、结论条格式、音标规则、详解来源判断、追问网页模式要求等关键约束固化成断言，误删即 CI 红 |
 | `scripts/test-filters.mjs` | host 侧流式过滤器单测（思考泄漏、工具调用残渣等） |
 | `scripts/test-transcript.mjs` | 会话背景窗口的离线测试（锚点 / 条数 / 不截断 / 噪音剔除 / 退化路径） |
 | `scripts/test-guard.mjs` | 文件工具读取边界的路径校验 |
@@ -305,7 +349,7 @@ node scripts/dump-prompt.mjs --no-session "<选中文字>"   # 不带会话背
 git tag v0.2.0 && git push origin v0.2.0
 ```
 
-`.github/workflows/publish.yml` 会自动：校验 tag 与 `version` 一致 → `npm install` → 构建 → 跑 463 条测试 → 类型检查 → `npm publish --provenance`（附 provenance 签名）。
+`.github/workflows/publish.yml` 会自动：校验 tag 与 `version` 一致 → `npm install` → 构建 → 跑 489 条测试 → 类型检查 → `npm publish --provenance`（附 provenance 签名）。
 
 npm 侧只需配一次：包设置 → **Trusted Publisher** → GitHub Actions，填 `yfwu2020` / `dsh-selection-explain` / `publish.yml`，并勾选允许 **`npm publish`**（默认只允许 `npm stage publish`）。
 
@@ -316,10 +360,12 @@ npm 侧只需配一次：包设置 → **Trusted Publisher** → GitHub Actions
 ## 目录
 
 ```
-src/index.ts            host 半：SSE 路由 / 模型调用 / 提示词 / 会话背景 / 历史落盘 / 过滤器
+src/index.ts            host 半：SSE 路由 / 模型调用 / 会话背景 / 历史落盘 / 过滤器
+src/prompts.ts          提示词与写作规则（纯字符串常量，无逻辑）
 src/client/index.js     client 半：划词浮标 + 面板 + 渲染器（手写 ModuleLoader bundle，无打包器）
-scripts/                build.sh + 4 个测试 + dump-prompt
+scripts/                build.sh + 5 个测试 + dump-prompt + 演示图生成
 skills/web-design/      网页模式注入的设计规范（运行时读取）
+assets/                 README 的演示图（由 scripts/build-demo-pages.mjs 生成）
 cordis.patch.yml        官方装配用的 bundle patch
 lib/                    构建产物（已 gitignore，克隆后需 npm run build）
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yfwu2020/dsh-selection-explain",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "DSH 划词解读：选中文字浮出按钮，点击弹窗流式显示专业中英翻译 + 该文字在当前上下文中的含义详解",
   "type": "module",
   "main": "./lib/index.js",
@@ -11,6 +11,7 @@
     "scripts",
     "cordis.patch.yml",
     "skills",
+    "assets",
     "README.md"
   ],
   "license": "MIT",

package/scripts/build-demo-pages.mjs

@@ -0,0 +1,296 @@
+/**
+ * 生成 README 用的小窗演示页（docs/demo/*.html）。
+ *
+ * 目的：README 里的功能截图必须**和真实面板长得一样**，所以样式不能手抄 ——
+ * 这里直接从 lib/client.js 里把模块级 `CSS` 常量抽出来注入演示页，
+ * 类名 / 结构 / 文案也照 src/client/index.js 的渲染器与真实输出写。
+ *
+ * 用法：node scripts/build-demo-pages.mjs
+ * 产物：docs/demo/stage1.html / stage2.html / code.html（再交给 Chrome 截图）
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const ROOT = resolve(HERE, '..')
+
+/** 从客户端 bundle 里取出模块级 CSS 常量（不手抄，保证与线上一致）。 */
+function extractCss() {
+  const src = readFileSync(resolve(ROOT, 'lib', 'client.js'), 'utf8')
+  const m = src.match(/var CSS = \[([\s\S]*?)\]\s*\.join\(''\)/) || src.match(/var CSS = \[([\s\S]*?)\]\.join\('\\n'\)/)
+  if (!m) throw new Error('未能在 lib/client.js 里找到 CSS 常量')
+  // 元素是 '...' 单引号字符串字面量
+  const parts = []
+  const re = /'((?:[^'\\]|\\.)*)'/g
+  let e
+  while ((e = re.exec(m[1])) !== null) parts.push(e[1].replace(/\\'/g, "'").replace(/\\n/g, '\n'))
+  return parts.join('\n')
+}
+
+/** DSH 主题变量：用浅色主题的实际取值，让截图看起来像真的嵌在 DSH 里。 */
+const THEME_VARS = `
+  --dsw-alias-bg-layer-1: #ffffff;
+  --dsw-alias-label-primary: #1a1a1a;
+  --dsw-alias-label-secondary: #6b7280;
+  --dsw-alias-label-primary-foreground: #ffffff;
+  --dsw-alias-interactive-bg-hover: rgba(140,140,140,.11);
+  --dsw-alias-border-l3: rgba(140,140,140,.35);
+  --dsw-alias-border-l4: rgba(140,140,140,.22);
+  --dsw-alias-button-primary-fill: #3b6ef5;
+  --sel-a1: #0d9488;
+  --sel-a2: #0f766e;
+`
+
+const PAGE = (title, css, body) => `<!doctype html>
+<html lang="zh-CN"><head><meta charset="utf-8"><title>${title}</title>
+<style>
+  /* 只渲染小窗本体：纯白底、无外边距，宽度固定 540 —— 截图后统一裁切 */
+  html,body{margin:0;padding:0;background:#ffffff;font-family:-apple-system,"PingFang SC","Helvetica Neue",Arial,sans-serif}
+  body{display:block;width:540px}
+  ${THEME_VARS}
+${css}
+  /* 演示页专用：把浮层定位改成静态排版、并显示面板（真实面板默认 display:none，由 JS 打开） */
+  .dsh-sel-layer{position:static !important;pointer-events:auto}
+  /* 截图只要"小窗本体"：去掉投影、边框、圆角 —— 否则裁切后会在上下边缘留下一圈灰线
+     （真实面板的投影是给浮层用的，单独截图时只会变成灰边） */
+  .dsh-sel-panel{position:static !important;display:flex !important;max-height:none !important;width:540px !important;
+    box-shadow:none !important;border:0 !important;border-radius:0 !important}
+  /* 首轮：真实行为是「翻译一出来输入框就出现」（askRow.style.display = wide || translationReady），
+     所以演示页也照实显示，不再隐藏 */
+  .dsh-sel-ask{display:flex !important;border:0 !important}
+</style></head>
+<body>${body}</body></html>
+`
+
+const panel = (stage, inner) => `<div class="dsh-sel-layer">
+  <div class="dsh-sel-panel" data-stage="${stage}" data-theme="light" role="dialog" aria-label="划词解读">
+    <div class="dsh-sel-head">
+      <span class="dsh-sel-mark"></span>
+      <span class="dsh-sel-title">划词解读</span>
+      <span class="dsh-sel-headspace"></span>
+      <button class="dsh-sel-action">🕘 最近</button>
+      <button class="dsh-sel-action">↗ 升格</button>
+      <button class="dsh-sel-icon" title="关闭">✕</button>
+    </div>
+    <div class="dsh-sel-body">
+${inner}
+    </div>
+  </div>
+</div>`
+
+const quote = (text) => `      <div class="dsh-sel-quote">${text}</div>`
+
+const section = (key, title, content) => `      <div class="dsh-sel-sec" data-sec="${key}">
+        <div class="dsh-sel-sh"><i></i><span>${title}</span><span class="dsh-sel-hint"></span></div>
+        <div class="dsh-sel-c">
+${content}
+        </div>
+      </div>`
+
+const p = (html) => `          <p>${html}</p>`
+const list = (level, items) => `          <div class="dsh-sel-list" data-level="${level}">
+${items.map((it) => `            <div class="dsh-sel-item"${it.num ? ' data-num="1"' : ''}><span class="dsh-sel-bullet">${it.bullet || '•'}</span><span>${it.text}</span></div>`).join('\n')}
+          </div>`
+const callout = (tag, text) => `          <div class="dsh-sel-callout"><span class="dsh-sel-callout-tag">${tag}</span>${text}</div>`
+
+const expand = `      <button class="dsh-sel-expand"><span>↓ 展开详解</span></button>`
+
+/** 真实图标（照 src/client/index.js 的 markdownIcon / windowIcon / sendIcon）。 */
+const mdIcon = `<svg viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3.5 17.5V7.5l4.4 5 4.4-5v10"></path><path d="M17.4 7v9.6M14.3 13.6l3.1 3.1 3.1-3.1"></path></svg>`
+const webIcon = `<svg viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="4.5" width="18" height="15" rx="3"></rect><path d="M3 9.6h18"></path></svg>`
+const sendIcon = `<svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M8 13.2V3.4"></path><path d="M3.9 7.5 8 3.4l4.1 4.1"></path></svg>`
+
+/**
+ * 输入区（结构照 src/client/index.js 的真实构建顺序）：
+ *   .dsh-sel-ask > textarea.dsh-sel-askbox + .dsh-sel-asktools
+ *   asktools = 输出偏好(文字 + 分段开关 + 滑动药丸) + askspace(撑开) + 模型胶囊 + 发送键
+ */
+const askRow = (webOn, model = 'deepseek-v4.1-flash', tier = '高') => `      <div class="dsh-sel-ask">
+        <textarea class="dsh-sel-askbox" rows="1" placeholder="就这段文字继续追问…（Enter 发送，Shift+Enter 换行）"></textarea>
+        <div class="dsh-sel-asktools">
+          <span class="dsh-sel-pref" data-on="${webOn ? '1' : '0'}">
+            <span class="dsh-sel-preftext">输出偏好</span>
+            <span class="dsh-sel-seg" role="radiogroup" aria-label="输出偏好">
+              <span class="dsh-sel-segpill"></span>
+              <button class="dsh-sel-segcell" role="radio" aria-label="Markdown：普通段落，最省时间"${webOn ? '' : ' data-on="1"'}>${mdIcon}</button>
+              <button class="dsh-sel-segcell" role="radio" aria-label="网页：复杂问题生成一个 HTML 页面"${webOn ? ' data-on="1"' : ''}>${webIcon}</button>
+            </span>
+          </span>
+          <span class="dsh-sel-askspace"></span>
+          <button class="dsh-sel-picker" type="button" aria-haspopup="menu" aria-expanded="false">
+            <span class="dsh-sel-picker-name">${model}</span>
+            <span class="dsh-sel-picker-tier">· ${tier}</span>
+            <span class="dsh-sel-picker-caret">▼</span>
+          </button>
+          <button class="dsh-sel-iconbtn dsh-sel-asksend" type="button" aria-label="发送">${sendIcon}</button>
+        </div>
+      </div>`
+
+const chatBubble = (role, html) =>
+  `        <div class="dsh-sel-bubble ${role === 'user' ? 'dsh-sel-bubble-user' : 'dsh-sel-bubble-bot'}">${html}</div>`
+
+// ───────────────────────── 状态一：首轮只出翻译 ─────────────────────────
+const stage1 = panel(
+  'translation',
+  [
+    quote('the migration ran long'),
+    section(
+      'translation',
+      '翻译',
+      [
+        p('这句话里需要翻译的是 <b>the migration ran long</b>：'),
+        list(0, [{ text: '<b>migration</b> /maɪˈɡreɪʃn/ —— 迁移（把数据/服务从一处搬到另一处）' }]),
+        list(0, [{ text: '<b>ran long</b> —— 跑得比预期久（ran = run 的过去式，long 指耗时超出预期）' }]),
+        p('合起来：<b>迁移跑得比预期久</b>。'),
+        callout('在本句中', '迁移作业耗时超出了原计划——这是在陈述进度延迟的事实，不含"失败了"的意思。'),
+      ].join('\n'),
+    ),
+    expand,
+    askRow(false),
+  ].join('\n'),
+)
+
+// ───────────────────────── 状态二：展开详解 + 追问 ─────────────────────────
+const stage2 = panel(
+  'detail',
+  [
+    quote('the migration ran long'),
+    section(
+      'translation',
+      '翻译',
+      [
+        p('这句话里需要翻译的是 <b>the migration ran long</b>：'),
+        list(0, [{ text: '<b>migration</b> /maɪˈɡreɪʃn/ —— 迁移（把数据/服务从一处搬到另一处）' }]),
+        list(0, [{ text: '<b>ran long</b> —— 跑得比预期久（ran = run 的过去式，long 指耗时超出预期）' }]),
+        callout('在本句中', '迁移作业耗时超出了原计划——这是在陈述进度延迟的事实，不含"失败了"的意思。'),
+      ].join('\n'),
+    ),
+    section(
+      'detail',
+      '详解',
+      [
+        p('这句话出自一句对话，是开发者在向 PM 说明<b>进度为什么需要重新安排</b>——它不是报错，而是在为后面的决定做铺垫。'),
+        p('两个关键说法各指什么：'),
+        list(0, [
+          { text: '<b>migration</b>（迁移）：把数据或服务从旧结构搬到新结构的一次作业。在数据库语境里通常指改表结构、搬数据这类"不能中途停"的操作。' },
+          { text: '<b>ran long</b>（跑久了）：完成时态，说的是这次已经发生的执行<b>耗时超过预期</b>，而不是"即将变慢"。' },
+        ]),
+        p('承接关系：既然迁移比预期久，后面的 <b>freeze features</b>（冻结功能开发）就不是随口一说，而是把人力腾出来的实际动作。'),
+        callout('小结', '在说"迁移耗时超预期"，用来解释接下来的功能冻结——重点在<b>排期</b>，不在迁移本身的对错。'),
+      ].join('\n'),
+    ),
+    `      <div class="dsh-sel-chatlog" style="display:flex">`,
+    chatBubble('user', '那 freeze features 是指完全停止开发吗？'),
+    chatBubble('assistant', '不是完全停止，而是<b>暂停新功能合入</b>：已有功能的修 bug 与收尾照常，只是不再往主干加新特性，好让迁移期间的分支收敛。'),
+    '      </div>',
+    askRow(false),
+  ].join('\n'),
+)
+
+/** 代码块：真实渲染器逐行输出 `.dsh-sel-pre-line`，注释行带 data-wrap（可折行），代码行不折。 */
+const codeBlock = (lines) => `          <pre class="dsh-sel-pre" data-hl="light">${lines
+  .map((l) => `<div class="dsh-sel-pre-line"${l.wrap ? ' data-wrap="1"' : ''}>${l.wrap ? `<span class="dsh-sel-pre-cmt">${l.text}</span>` : l.text}</div>`)
+  .join('')}</pre>`
+
+// ───────────────────────── 状态三：选中代码 → 出注释 ─────────────────────────
+const codeDemo = panel(
+  'translation',
+  [
+    quote('function debounce(fn, wait) { … }'),
+    section(
+      'translation',
+      '注释',
+      [
+        codeBlock([
+          { wrap: true, text: '// 防抖：把连续触发压成「最后一次之后 wait 毫秒才真正执行」' },
+          { text: 'function debounce(fn, wait) {' },
+          { wrap: true, text: '  // 闭包变量：保存上一次的定时器，用来取消它' },
+          { text: '  let timer = null' },
+          { wrap: true, text: '  // 每次触发都先清掉上一个定时器，再重新计时' },
+          { text: '  return function (...args) {' },
+          { text: '    clearTimeout(timer)' },
+          { wrap: true, text: '    // wait 毫秒内没有新触发，才执行原函数' },
+          { text: '    timer = setTimeout(() =&gt; fn.apply(this, args), wait)' },
+          { text: '  }' },
+          { text: '}' },
+        ]),
+        callout('小结', '把高频触发收敛成一次执行——常用于搜索输入、窗口 resize 这类"只要最终结果"的场景。'),
+      ].join('\n'),
+    ),
+  ].join('\n'),
+)
+
+/** 网页模式：回答里嵌一张可交互的 HTML 页面（.dsh-sel-preview 结构照渲染器）。 */
+const previewBlock = (srcdoc) => `      <div class="dsh-sel-preview" data-view="preview" data-full="1">
+        <div class="dsh-sel-previewbar">
+          <div class="dsh-sel-previewtabs">
+            <button class="dsh-sel-previewtab" data-on="1">预览</button>
+            <button class="dsh-sel-previewtab" data-on="0">源码</button>
+          </div>
+          <button class="dsh-sel-previewzoom">⤡ 还原</button>
+        </div>
+        <div class="dsh-sel-previewbody">
+          <iframe class="dsh-sel-previewframe" srcdoc="${srcdoc.replace(/"/g, '&quot;')}"></iframe>
+        </div>
+      </div>`
+
+const DEMO_HTML = `<!doctype html><html><head><meta charset="utf-8"><style>
+body{margin:0;padding:14px 16px;font:13px/1.6 -apple-system,"PingFang SC",sans-serif;color:#1a1a1a;background:#fff}
+h3{margin:0 0 4px;font-size:14px}
+p.sub{margin:0 0 12px;color:#6b7280;font-size:12px}
+table{border-collapse:collapse;width:100%;font-size:12.5px}
+th,td{border-bottom:1px solid #e6e8eb;padding:7px 8px;text-align:left}
+th{background:#f6f8f9;font-weight:600;color:#374151}
+td.y{color:#0f766e;font-weight:600}
+td.n{color:#b45309}
+.bars{display:flex;align-items:flex-end;gap:10px;height:74px;margin:14px 0 4px}
+.bar{flex:1;border-radius:5px 5px 0 0;background:#0d9488;position:relative}
+.bar span{position:absolute;bottom:-19px;left:0;right:0;text-align:center;font-size:11px;color:#6b7280}
+.b1{height:34px;background:#99f6e4}.b2{height:58px}.b3{height:74px;background:#0f766e}
+</style></head><body>
+<h3>三种缓存策略的取舍</h3>
+<p class="sub">按"命中率 / 一致性风险 / 实现成本"三个维度对比</p>
+<table>
+  <tr><th>策略</th><th>命中率</th><th>一致性风险</th><th>实现成本</th></tr>
+  <tr><td>不缓存</td><td class="n">—</td><td class="y">无</td><td class="y">最低</td></tr>
+  <tr><td>进程内 LRU</td><td class="y">高</td><td class="n">中（多实例不一致）</td><td class="y">低</td></tr>
+  <tr><td>共享缓存 + TTL</td><td class="y">最高</td><td class="y">低（可配 TTL）</td><td class="n">中</td></tr>
+</table>
+<div class="bars"><div class="bar b1"><span>不缓存</span></div><div class="bar b2"><span>LRU</span></div><div class="bar b3"><span>共享缓存</span></div></div>
+</body></html>`
+
+// ───────────────────────── 状态四：网页模式（输出偏好拨到「网页」）─────────────────────────
+// 场景要能体现"为什么该用网页"：需要对比 + 图示的问题 → 直接给一页 HTML。
+const webDemo = panel(
+  'detail',
+  [
+    quote('缓存策略'),
+    section(
+      'detail',
+      '详解',
+      [
+        p('三种做法的差别是并列的，画成一页更好看：'),
+        previewBlock(DEMO_HTML),
+      ].join('\n'),
+    ),
+    `      <div class="dsh-sel-chatlog" style="display:flex">`,
+    chatBubble('user', '把三种缓存策略的差别画成一页对比'),
+    '      </div>',
+    askRow(true, 'deepseek-v4.1-flash', '高'),
+  ].join('\n'),
+)
+
+const css = extractCss()
+mkdirSync(resolve(ROOT, 'docs', 'demo'), { recursive: true })
+const out = {
+  'stage1.html': PAGE('划词解读 · 首轮翻译', css, stage1),
+  'stage2.html': PAGE('划词解读 · 详解与追问', css, stage2),
+  'code.html': PAGE('划词解读 · 代码注释', css, codeDemo),
+  'web.html': PAGE('划词解读 · 网页模式', css, webDemo),
+}
+for (const [name, html] of Object.entries(out)) {
+  writeFileSync(resolve(ROOT, 'docs', 'demo', name), html, 'utf8')
+  console.log(`✓ docs/demo/${name}  ${(html.length / 1024).toFixed(1)} kB`)
+}
+console.log(`\nCSS 来源：lib/client.js（${css.length} 字符，未手抄）`)

package/scripts/crop-png.mjs

@@ -0,0 +1,142 @@
+/**
+ * 裁掉截图四周的空白（仅用 Node 内置 zlib 解码/编码 PNG，不依赖 imagemagick）。
+ *
+ * 用途：README 的演示图需要紧凑。Chrome `--screenshot` 只能给固定窗口尺寸，
+ * 面板比窗口矮时底部会留下大片背景色 —— 这里把纯背景的边缘裁掉。
+ *
+ * 用法：node scripts/crop-png.mjs <in.png> <out.png> [边距px]
+ */
+import { readFileSync, writeFileSync } from 'node:fs'
+import { inflateSync, deflateSync } from 'node:zlib'
+
+const [, , inPath, outPath, padArg, tolArg] = process.argv
+if (!inPath || !outPath) {
+  console.error('用法: node scripts/crop-png.mjs <in.png> <out.png> [边距px] [背景容差]')
+  process.exit(1)
+}
+const PAD = Number(padArg ?? 0)
+// 容差要能吃掉面板投影造成的渐变（实测同一张图背景在 247~255 之间浮动）
+const TOL = Number(tolArg ?? 8)
+
+// ── 读 PNG（假定 Chrome 输出的 8bit RGB/RGBA 非隔行）──
+const buf = readFileSync(inPath)
+if (buf.readUInt32BE(0) !== 0x89504e47) throw new Error('不是 PNG')
+let pos = 8
+let width = 0
+let height = 0
+let bitDepth = 0
+let colorType = 0
+const idat = []
+while (pos < buf.length) {
+  const len = buf.readUInt32BE(pos)
+  const type = buf.toString('ascii', pos + 4, pos + 8)
+  const data = buf.subarray(pos + 8, pos + 8 + len)
+  if (type === 'IHDR') {
+    width = data.readUInt32BE(0)
+    height = data.readUInt32BE(4)
+    bitDepth = data[8]
+    colorType = data[9]
+    if (data[12] !== 0) throw new Error('不支持隔行 PNG')
+  } else if (type === 'IDAT') idat.push(data)
+  else if (type === 'IEND') break
+  pos += 12 + len
+}
+if (bitDepth !== 8 || (colorType !== 2 && colorType !== 6)) {
+  throw new Error(`不支持的 PNG 格式：bitDepth=${bitDepth} colorType=${colorType}`)
+}
+const bpp = colorType === 6 ? 4 : 3
+const raw = inflateSync(Buffer.concat(idat))
+
+// ── 反滤波 ──
+const stride = width * bpp
+const img = Buffer.alloc(height * stride)
+for (let y = 0; y < height; y++) {
+  const filter = raw[y * (stride + 1)]
+  const line = raw.subarray(y * (stride + 1) + 1, y * (stride + 1) + 1 + stride)
+  const prev = y > 0 ? img.subarray((y - 1) * stride, y * stride) : null
+  const cur = img.subarray(y * stride, (y + 1) * stride)
+  for (let x = 0; x < stride; x++) {
+    const a = x >= bpp ? cur[x - bpp] : 0
+    const b = prev ? prev[x] : 0
+    const c = prev && x >= bpp ? prev[x - bpp] : 0
+    let v = line[x]
+    if (filter === 1) v += a
+    else if (filter === 2) v += b
+    else if (filter === 3) v += (a + b) >> 1
+    else if (filter === 4) {
+      const p = a + b - c
+      const pa = Math.abs(p - a)
+      const pb = Math.abs(p - b)
+      const pc = Math.abs(p - c)
+      v += pa <= pb && pa <= pc ? a : pb <= pc ? b : c
+    }
+    cur[x] = v & 0xff
+  }
+}
+
+// ── 找内容边界：以左上角像素为背景色 ──
+const bg = [img[0], img[1], img[2]]
+const isBg = (x, y) => {
+  const o = y * stride + x * bpp
+  return (
+    Math.abs(img[o] - bg[0]) <= TOL && Math.abs(img[o + 1] - bg[1]) <= TOL && Math.abs(img[o + 2] - bg[2]) <= TOL
+  )
+}
+let top = 0
+let bottom = height - 1
+let left = 0
+let right = width - 1
+outer: for (; top < height; top++) for (let x = 0; x < width; x++) if (!isBg(x, top)) break outer
+outer2: for (; bottom > top; bottom--) for (let x = 0; x < width; x++) if (!isBg(x, bottom)) break outer2
+outer3: for (; left < width; left++) for (let y = top; y <= bottom; y++) if (!isBg(left, y)) break outer3
+outer4: for (; right > left; right--) for (let y = top; y <= bottom; y++) if (!isBg(right, y)) break outer4
+
+top = Math.max(0, top - PAD)
+left = Math.max(0, left - PAD)
+bottom = Math.min(height - 1, bottom + PAD)
+right = Math.min(width - 1, right + PAD)
+const w = right - left + 1
+const h = bottom - top + 1
+
+// ── 重新编码（每行用 filter 0）──
+const outStride = w * bpp
+const rawOut = Buffer.alloc(h * (outStride + 1))
+for (let y = 0; y < h; y++) {
+  rawOut[y * (outStride + 1)] = 0
+  img.copy(rawOut, y * (outStride + 1) + 1, (top + y) * stride + left * bpp, (top + y) * stride + left * bpp + outStride)
+}
+const chunk = (type, data) => {
+  const len = Buffer.alloc(4)
+  len.writeUInt32BE(data.length)
+  const body = Buffer.concat([Buffer.from(type, 'ascii'), data])
+  const crc = Buffer.alloc(4)
+  crc.writeUInt32BE(crc32(body) >>> 0)
+  return Buffer.concat([len, body, crc])
+}
+let table = null
+function crc32(b) {
+  if (!table) {
+    table = new Int32Array(256)
+    for (let n = 0; n < 256; n++) {
+      let c = n
+      for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+      table[n] = c
+    }
+  }
+  let c = 0xffffffff
+  for (let i = 0; i < b.length; i++) c = table[(c ^ b[i]) & 0xff] ^ (c >>> 8)
+  return c ^ 0xffffffff
+}
+const ihdr = Buffer.alloc(13)
+ihdr.writeUInt32BE(w, 0)
+ihdr.writeUInt32BE(h, 4)
+ihdr[8] = 8
+ihdr[9] = colorType
+const png = Buffer.concat([
+  Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+  chunk('IHDR', ihdr),
+  chunk('IDAT', deflateSync(rawOut, { level: 9 })),
+  chunk('IEND', Buffer.alloc(0)),
+])
+writeFileSync(outPath, png)
+console.log(`✓ ${outPath}  ${width}x${height} → ${w}x${h}`)