@ggboy123/dsh-paper-reader 0.6.2 → 1.1.0

package/README.md

@@ -1,11 +1,20 @@
 # dsh-paper-reader
 
+[![npm version](https://img.shields.io/npm/v/@ggboy123/dsh-paper-reader)](https://www.npmjs.com/package/@ggboy123/dsh-paper-reader)
+[![npm downloads](https://img.shields.io/npm/dm/@ggboy123/dsh-paper-reader)](https://www.npmjs.com/package/@ggboy123/dsh-paper-reader)
+[![license](https://img.shields.io/github/license/GGboya/dsh-paper-reader)](https://github.com/GGboya/dsh-paper-reader/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/GGboya/dsh-paper-reader?style=social)](https://github.com/GGboya/dsh-paper-reader/stargazers)
+
+**English**: [README_EN.md](README_EN.md)
+
 [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 插件：论文伴读工作台 —— PDF 转录 / 检索 + 原生对话伴读 + 内置阅读器。
 
 功能迁移自本地独立产品 pdfqa（Go 实现的论文伴读工具）。原则：agent 循环 / 模型层 / 会话持久化全部交给 dsh 框架，插件只做「转录 + 检索 + 阅读器 UI」的薄壳组合。
 
 **安装后不改动官方界面** —— 侧栏底部多一行「📚 论文伴读」开关，点击才进入伴读模式（左侧变为文献库树），再点即还原官方工作区列表：
 
+![演示：选中即问 → 回答带页码 → 点页码跳回 PDF 并高亮原文](docs/demo.gif)
+
 ![默认安装：官方侧栏原样，只多一行开关](https://raw.githubusercontent.com/GGboya/dsh-paper-reader/main/docs/screenshot-default.png)
 
 ![伴读模式：文献库 + PDF 阅读器 + 原生对话](https://raw.githubusercontent.com/GGboya/dsh-paper-reader/main/docs/screenshot-reading.png)
@@ -19,11 +28,25 @@
 - 📖 **PDF 阅读器居中**：中间是论文（PDF.js 缩放 / Retina 高清 / 文本层选择 / 适宽模式），最右是该论文的原生对话 —— 视觉换位实现，列宽拖拽/折叠仍是 dsh 原生行为，关掉 PDF 页签即还原官方布局
 - 💬 **选中即问**：阅读器里选中文字 → 弹出提问框 → 注入当前会话，原生对话区实时回答
 - 📍 **引用定位**：回答里的「第 N 页」可点击，平滑跳回 PDF 对应页并闪烁
-- 🀄 **中英切换**：顶栏「中」按钮原文 ↔ 纯中文切换；无译文时一键后台生成（babeldoc），生成需配置 `translate` 端点；**无需预装 Python**——首次生成时自动下载 uv + 托管 Python + babeldoc（macOS/Linux，约几分钟），全程落在用户目录
-- 🔍 **PDF 转录 + 检索**：本地提取（pdf.js，纯 Node 无需 Python），页眉页脚剔除 / 连字 / 断词愈合 / 段落重排，产出页码偏移表；兼容 pdfqa 的 `data/` 缓存布局（旧缓存读取时自动补建页码索引）
+- 🀄 **中英切换**：顶栏「中」按钮原文 ↔ 纯中文切换；无译文时一键后台生成（babeldoc），生成需配置 `translate` 端点；**无需预装 Python**——首次生成时自动下载 uv + 托管 Python + babeldoc（macOS / Linux / Windows，约几分钟），全程落在用户目录
+- 🔍 **PDF 转录 + 检索**：本地提取（pdf.js，纯 Node 无需 Python），页眉页脚剔除 / 连字 / 断词愈合 / 段落重排，产出页码偏移表；可选接入 TypeSafe/Jev 语义重排（设置面板填端点即启用，不配置时退回纯关键词排序）；兼容 pdfqa 的 `data/` 缓存布局（旧缓存读取时自动补建页码索引）
 
 ## 安装
 
+### 方式一：DSH Desktop（零环境，推荐普通用户）
+
+[DSH Desktop](https://github.com/anywhere-labs/dsh-desktop) 是社区的 DeepSeek Harness 桌面客户端（macOS / Windows，开箱即用，不需要装 Node.js）：
+
+1. 下载安装 DSH Desktop 并启动
+2. 托盘菜单 → **Open DSH Terminal**（终端里自带 `dsh`/`pnpm`，只对那个终端生效）
+3. 执行 `dsh plugin add @ggboy123/dsh-paper-reader@1.1.0`
+4. 退出并重开 DSH Desktop（插件变更要重启才进 Loader 组合）
+
+> 已在 DSH Desktop 2.0.13（内置 dsh 0.1.5-rc.2）上实测通过：侧栏文献库、PDF 阅读器、选中即问、页码跳转、原生对话伴读、翻译引擎自动安装（uv + Python + babeldoc 全程落在用户目录）全部可用。
+> 注意：Desktop 的 `desktop` profile 被 Electron 独占管理，外部 CLI 直接 `dsh plugin --profile desktop add` 会被拒（`managed exclusively by the Electron application`）——必须从 Desktop 自己的终端进。
+
+### 方式二：命令行 dsh（开发者）
+
 ```bash
 dsh plugin --profile web add @ggboy123/dsh-paper-reader
 ```
@@ -31,6 +54,23 @@ dsh plugin --profile web add @ggboy123/dsh-paper-reader
 > npm 包名走 `@ggboy123` 作用域：裸名 `dsh-paper-reader` 已被另一个插件占用（那是「输入文献、吐精读报告」的一次性分析工具，与本插件的「阅读器 + 会话伴读」定位不同）。
 > 不要用 `github:GGboya/dsh-paper-reader` 安装 —— dist 不入库，git 安装会导致 profile 起不来（构建产物只随 npm 包分发）。
 
+### 升级
+
+**已装过的用户升级必须带显式版本号**——不带版本的 `add` 对已存在的依赖是 no-op（pnpm 按首次安装时记录的版本范围解析，不会追新）：
+
+```bash
+dsh plugin --profile web add @ggboy123/dsh-paper-reader@1.1.0
+# 重启 dsh web 生效；浏览器 Cmd+Shift+R 强刷，避免旧阅读器页面缓存
+```
+
+确认当前装的是哪个版本：
+
+```bash
+grep '"version"' ~/.dsh/profiles/web/node_modules/@ggboy123/dsh-paper-reader/package.json
+```
+
+> pnpm 若开了供应链策略 `minimumReleaseAge`（发布 N 小时内的新包拒装）：要么等过窗口期，要么在 `~/.dsh/profiles/web/.npmrc` 加一行 `minimum-release-age-exclude[]=@ggboy123/dsh-paper-reader`（只豁免本插件，不动全局策略）。
+
 本地开发：
 
 ```bash
@@ -58,7 +98,7 @@ dsh --profile web                                  # 侧栏变为文献库树
 >
 > 翻译引擎**零预装**：找不到 babeldoc 时自动走 uv 链路安装——uv 独立二进制（GitHub Releases API 下载 + sha256 校验）→
 > uv 托管 Python 3.12 → `uv pip install babeldoc`，落在 `~/.dsh/.dsh-paper-reader/bin/` 与文献库同级 `.venv-pdf2zh/`，
-> 不碰系统 Python。已装有 uv / babeldoc（含 pdfqa 的 `.venv-pdf2zh`）则直接复用。Windows 暂不支持自动安装，需手动装 uv 后重试。
+> 不碰系统 Python。已装有 uv / babeldoc（含 pdfqa 的 `.venv-pdf2zh`）则直接复用。macOS / Linux / Windows 均支持自动安装（Windows 走 uv 的 zip 包 + 系统自带 tar 解包）。
 
 > 伴读模式是**按需开启**的：默认不注册 `sidebar.workspaces`（官方工作区/会话列表原样），侧栏底部「📚 论文伴读」开关点击才接管，再点还原；模式选择记在 localStorage。退出模式时已打开的 PDF 页签和伴读会话不受影响。
 
@@ -77,6 +117,8 @@ src/
   translate.ts  纯函数：babeldoc 调用（中文/中英对照 PDF 生成）
   babeldoc-install.ts 纯函数：无 Python 环境时自动安装 babeldoc（uv → 托管 Python → venv）
   translate-config.ts 纯函数：翻译端点配置读写（$DSH_HOME 下 0600）+ 保存前连接预检
+  rerank.ts     纯函数：search_paper 语义重排（TypeSafe/Jev，无凭据时退回关键词排序）
+  typesafe-config.ts 纯函数：TypeSafe 端点配置读写（与翻译配置同一套约定）
   preset.ts     纯函数：自带 agent preset 安装到 $DSH_HOME/.agent-presets/
 presets/paper-reader/  「论文伴读」agent preset（persona 完整提示词 + compaction）
 reader/index.html      阅读器页面（pdf.js，独立于 React 宿主，iframe 承载）

package/dist/babeldoc-install.js

@@ -3,20 +3,25 @@
 // 链路：uv 独立二进制（GitHub Releases，带 sha256 校验）
 //   → `uv venv`（uv 自动下载托管 Python，系统没有 Python 也能跑）
 //   → `uv pip install babeldoc`
-// 全部落在用户目录：uv 二进制在 <dshHome>/.dsh-paper-reader/bin/uv，
+// 全部落在用户目录：uv 二进制在 <dshHome>/.dsh-paper-reader/bin/uv（win32 为 uv.exe），
 // venv 在 文献库同级 .venv-pdf2zh（必须与 translate.ts findBabeldoc 的第一候选位一致），
-// 不碰系统 Python、不需要 sudo。win32 不在支持范围（tar 解 zip、exe 后缀都要分叉），直接给手动指引。
+// 不碰系统 Python、不需要 sudo。
+// win32 差异：uv 发 zip 而非 tar.gz（Win10 1803+ 自带 bsdtar 可解 zip，tar -xf 通吃两种格式）、
+// exe 后缀、venv 用 Scripts/ 而非 bin/、PATH 查找用 where 替代 which、不需要 chmod。
 import { execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { chmod, mkdir, rename, rm, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
+const isWin = process.platform === 'win32';
 /** uv 发布的 target triple；不支持的平台返回 null（给手动安装指引）。 */
 function uvTriple() {
     const { platform, arch } = process;
     if (platform === 'darwin')
         return arch === 'arm64' ? 'aarch64-apple-darwin' : 'x86_64-apple-darwin';
+    if (platform === 'win32')
+        return arch === 'arm64' ? 'aarch64-pc-windows-msvc' : 'x86_64-pc-windows-msvc';
     // musl 静态构建：不依赖系统 glibc 版本，最省心
     if (platform === 'linux') {
         if (arch === 'x64')
@@ -43,13 +48,14 @@ function run(cmd, args, opts = {}) {
     });
 }
 async function whichOk(cmd) {
+    // win32 没有 which，用 where（两者都找不到时都只是跳下一个候选，不算错误）
     return new Promise((res) => {
-        execFile('which', [cmd], (err, stdout) => res(!err && stdout.trim() !== ''));
+        execFile(isWin ? 'where' : 'which', [cmd], (err, stdout) => res(!err && stdout.trim() !== ''));
     });
 }
 /** 插件托管的 uv 位置（不落系统目录，删插件目录即清干净）。 */
 export function uvPath(home) {
-    return join(home, '.dsh-paper-reader', 'bin', 'uv');
+    return join(home, '.dsh-paper-reader', 'bin', isWin ? 'uv.exe' : 'uv');
 }
 /** 找 uv：插件托管 → PATH → 常见安装位。 */
 async function findUv(home) {
@@ -58,7 +64,10 @@ async function findUv(home) {
         return own;
     if (await whichOk('uv'))
         return 'uv';
-    for (const c of [join(homedir(), '.local', 'bin', 'uv'), join(homedir(), '.cargo', 'bin', 'uv')]) {
+    const candidates = isWin
+        ? [join(homedir(), '.local', 'bin', 'uv.exe')]
+        : [join(homedir(), '.local', 'bin', 'uv'), join(homedir(), '.cargo', 'bin', 'uv')];
+    for (const c of candidates) {
         if (existsSync(c))
             return c;
     }
@@ -75,7 +84,7 @@ async function downloadUv(home, onPhase) {
     if (!triple) {
         throw new Error(`当前平台（${process.platform}/${process.arch}）暂不支持自动安装：请手动安装 uv（https://docs.astral.sh/uv/）后重试`);
     }
-    const want = `uv-${triple}.tar.gz`;
+    const want = isWin ? `uv-${triple}.zip` : `uv-${triple}.tar.gz`;
     const tmp = join(home, '.dsh-paper-reader', 'bin', `.uv-install-${Date.now()}`);
     await mkdir(tmp, { recursive: true });
     try {
@@ -110,15 +119,18 @@ async function downloadUv(home, onPhase) {
         const actual = createHash('sha256').update(body).digest('hex');
         if (actual !== expect)
             throw new Error('uv 下载文件校验和不匹配，已丢弃（请重试）');
-        const tgzPath = join(tmp, 'uv.tar.gz');
-        await writeFile(tgzPath, body);
-        await run('tar', ['-xzf', tgzPath, '-C', tmp], { timeout: 60_000 });
-        const extracted = join(tmp, `uv-${triple}`, 'uv');
+        const pkgPath = join(tmp, isWin ? 'uv.zip' : 'uv.tar.gz');
+        await writeFile(pkgPath, body);
+        // 不带 -z：bsdtar（macOS 自带 / Win10 1803+ 的 tar.exe）和 GNU tar 解包时都自动探测格式，
+        // 同一条命令通吃 tar.gz 与 zip（win32 的 uv 只发 zip）
+        await run('tar', ['-xf', pkgPath, '-C', tmp], { timeout: 60_000 });
+        const extracted = join(tmp, `uv-${triple}`, isWin ? 'uv.exe' : 'uv');
         if (!existsSync(extracted))
             throw new Error('uv 解包结果不符合预期');
         const dst = uvPath(home);
         await rename(extracted, dst);
-        await chmod(dst, 0o755);
+        if (!isWin)
+            await chmod(dst, 0o755); // win32 无可执行位概念
         return dst;
     }
     finally {
@@ -130,10 +142,11 @@ async function installBabeldoc(uv, venvDir, onPhase) {
     onPhase('正在安装翻译引擎（2/3 安装 Python）…');
     // --python-preference only-managed：不碰用户系统里可能残缺/带 externally-managed 标记的 Python
     await run(uv, ['venv', venvDir, '--python', '3.12', '--python-preference', 'only-managed'], { timeout: 10 * 60_000 });
-    const py = join(venvDir, 'bin', 'python');
+    // win32 venv 用 Scripts/ 而非 bin/，可执行文件带 .exe
+    const py = isWin ? join(venvDir, 'Scripts', 'python.exe') : join(venvDir, 'bin', 'python');
     onPhase('正在安装翻译引擎（3/3 安装 babeldoc，首次约几分钟）…');
     await run(uv, ['pip', 'install', '--python', py, 'babeldoc'], { timeout: 20 * 60_000 });
-    const bin = join(venvDir, 'bin', 'babeldoc');
+    const bin = isWin ? join(venvDir, 'Scripts', 'babeldoc.exe') : join(venvDir, 'bin', 'babeldoc');
     if (!existsSync(bin))
         throw new Error('babeldoc 安装完成但未找到可执行文件');
     return bin;

package/dist/host.js

@@ -8,6 +8,7 @@ import { listPapers, listTopics, resolveDataDir, resolvePaper } from "./library.
 import { readTranscript, transcribePaper } from "./transcribe.js";
 import { pdfVariantPath, restartTranslation, startTranslation, zhStatus } from "./translate.js";
 import { clearTranslateConfig, maskApiKey, readTranslateConfig, resolveTranslateEndpoint, testTranslateEndpoint, writeTranslateConfig, } from "./translate-config.js";
+import { clearTypesafeConfig, readTypesafeConfig, resolveTypesafeConfig, testTypesafeEndpoint, writeTypesafeConfig, } from "./typesafe-config.js";
 import { installPaperPreset, PAPER_PRESET_ID } from "./preset.js";
 import { noteOrigin } from "./origin.js";
 function json(res, status, body) {
@@ -353,6 +354,50 @@ export function registerRoutes(ctx, config) {
             json(res, 200, { ok: true });
             return;
         }
+        // ── Jev/TypeSafe 端点配置（设置面板的读写口）─────────────────────────
+        // 与翻译配置同一套约定：GET 只回显掩码 key；POST 预检通过才落盘；DELETE 回落
+        if (sub === '/api/typesafe/config' && req.method === 'GET') {
+            const { cfg, source } = await resolveTypesafeConfig(config.typesafe);
+            json(res, 200, {
+                baseUrl: cfg.baseUrl ?? '',
+                model: cfg.model ?? '',
+                hasApiKey: Boolean(cfg.apiKey),
+                apiKeyHint: cfg.apiKey ? maskApiKey(cfg.apiKey) : '',
+                source,
+            });
+            return;
+        }
+        // POST：baseUrl/model 可空（SDK 有默认值）；key 留空 = 沿用已存的那把。
+        // 校验 → 预检 → 通了才落盘：重排失败会静默降级，key 填错很难察觉，这里先拦。
+        if (sub === '/api/typesafe/config' && req.method === 'POST') {
+            const body = (await readBody(req));
+            const baseUrl = body.baseUrl?.trim() ?? '';
+            const model = body.model?.trim() ?? '';
+            const prev = await readTypesafeConfig();
+            const apiKey = body.apiKey?.trim() || prev?.apiKey || '';
+            if (baseUrl && !/^https?:\/\//i.test(baseUrl)) {
+                json(res, 400, { error: '端点 URL 需要以 http:// 或 https:// 开头（留空用官方默认）' });
+                return;
+            }
+            if (!apiKey) {
+                json(res, 400, { error: 'API Key 不能为空' });
+                return;
+            }
+            const test = await testTypesafeEndpoint({ apiKey, ...(baseUrl ? { baseUrl } : {}), ...(model ? { model } : {}) });
+            if (!test.ok) {
+                json(res, 400, { error: `连接测试失败：${test.detail ?? '未知原因'}` });
+                return;
+            }
+            await writeTypesafeConfig({ apiKey, ...(baseUrl ? { baseUrl } : {}), ...(model ? { model } : {}) });
+            json(res, 200, { ok: true });
+            return;
+        }
+        // DELETE：清掉文件，回落到 profile 的 typesafe / 环境变量
+        if (sub === '/api/typesafe/config' && req.method === 'DELETE') {
+            await clearTypesafeConfig();
+            json(res, 200, { ok: true });
+            return;
+        }
         if (sub === '/api/transcribe' && req.method === 'POST') {
             const body = (await readBody(req));
             const ref = resolvePaper(dataDir, body);

package/dist/rerank.js

@@ -0,0 +1,85 @@
+// rerank.ts — 语义重排（Jev / TypeSafe System One,不依赖 Cordis)。
+//
+// 两段式检索的第二段:search.ts 的关键词打分是「快搜」——按词面捞回 shortlist;
+// 这里对 shortlist 里每个候选问一个 Noul(「这段能回答学生的问题吗」),
+// 按 noul 概率重排。快搜召回、Jev 定序,代码保留排序和截断。
+// 参考 https://docs.typesafe.ai/cookbooks/rerank_typesafe.md
+//
+// 凭据按「设置面板文件 > profile YAML > 环境变量」解析（typesafe-config.ts）,
+// 都配不出 apiKey 时 resolveRerankClient 返回 null,调用方退回纯关键词排序
+// ——重排是可迭增强,不是硬依赖。
+import { TypeSafeClient, noul } from '@typesafe-ai/sdk';
+import { patientFetch, resolveTypesafeConfig } from "./typesafe-config.js";
+/** 重排超预算（区别于网络/鉴权错误,方便上层区分日志）。 */
+export class RerankDeadlineError extends Error {
+    deadlineMs;
+    constructor(deadlineMs) {
+        super(`Jev 重排超过 ${deadlineMs}ms 预算,已放弃`);
+        this.deadlineMs = deadlineMs;
+        this.name = 'RerankDeadlineError';
+    }
+}
+export function resolveShortlistSize(config) {
+    const n = config?.shortlistSize ?? 15;
+    return Math.max(1, Math.min(Math.trunc(n), 30));
+}
+/**
+ * 有凭据则建客户端,否则返回 null(调用方走降级路径)。
+ * 每次检索都调用:设置面板保存后无需重启即生效(读的是个小 JSON,开销可忽略)。
+ */
+export async function resolveRerankClient(config) {
+    const { cfg } = await resolveTypesafeConfig(config);
+    if (!cfg.apiKey?.trim())
+        return null;
+    return new TypeSafeClient({
+        apiKey: cfg.apiKey,
+        ...(cfg.baseUrl ? { baseURL: cfg.baseUrl } : {}),
+        ...(cfg.model ? { defaultModel: cfg.model } : {}),
+        timeout: config?.timeoutMs ?? 60_000,
+        fetch: patientFetch,
+        logLevel: 'off',
+    });
+}
+/**
+ * 用 Jev 对 shortlist 重排,返回 top-k(按原文顺序)。
+ * 所有候选放进一份 state、一次请求并行问 N 个 Noul(同 state 的独立问题
+ * 官方建议同批发问);任何失败(网络/鉴权/超时)抛给调用方降级。
+ * deadlineMs > 0 时到点 abort 在飞请求并抛 RerankDeadlineError。
+ */
+export async function rerankHits(client, query, shortlist, k, deadlineMs = 1500) {
+    // state 与问题:候选按 c1..cN 编号,问题里用反引号路径引用对应候选。
+    const candidates = {};
+    const questions = {};
+    shortlist.forEach((h, i) => {
+        const key = `c${i + 1}`;
+        candidates[key] = h.chunk.text;
+        questions[key] = noul(`Could the passage at \`candidates.${key}\` help answer the student's question at \`question\`?`, {
+            true: 'The passage contains facts, reasoning, definitions, or data that directly help answer the question.',
+            false: 'The passage is only topically related or shares keywords, without content that actually helps answer the question.',
+        });
+    });
+    const ac = new AbortController();
+    const timer = deadlineMs > 0 ? setTimeout(() => ac.abort(new RerankDeadlineError(deadlineMs)), deadlineMs) : null;
+    let answers;
+    try {
+        ;
+        ({ answers } = await client.systemOne({ state: { question: query, candidates }, questions }, deadlineMs > 0 ? { signal: ac.signal } : {}));
+    }
+    catch (e) {
+        // abort 触发时 SDK 抛 APIUserAbortError,换成我们带预算信息的错误
+        if (ac.signal.aborted)
+            throw ac.signal.reason ?? e;
+        throw e;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+    return shortlist
+        .map((h, i) => ({ hit: h, noul: answers[`c${i + 1}`].noul }))
+        .sort((a, b) => b.noul - a.noul)
+        .slice(0, k)
+        // 重排后 score 改写为 noul(最终排序分),便于上层/调试脚本展示概率
+        .map((e) => ({ ...e.hit, score: Math.round(e.noul * 1000) / 1000 }))
+        .sort((a, b) => a.chunk.index - b.chunk.index); // 与 searchChunks 一致:按原文顺序返回
+}

package/dist/tools.js

@@ -3,6 +3,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools';
 import { listPapers, listTopics, resolveDataDir, resolvePaper } from "./library.js";
 import { transcribePaper, readTranscript } from "./transcribe.js";
 import { chunkText, searchChunks, formatHits } from "./search.js";
+import { resolveRerankClient, resolveShortlistSize, rerankHits } from "./rerank.js";
 import { completeStep, formatStudy, readStudy, recordQuiz, setPlan } from "./study.js";
 import { readerOrigin } from "./origin.js";
 const locateParams = {
@@ -60,6 +61,7 @@ const readerUrlSchema = {
 const readerUrlLine = (url) => (url ? `\n阅读器链接基址：${url}` : '');
 export function registerTools(ctx, config) {
     const dataDir = resolveDataDir(config.dataDir);
+    const shortlistSize = resolveShortlistSize(config.typesafe);
     ctx.tools.register(defineTool({
         name: 'list_papers',
         description: '列出文献库里的专题和文献。当用户提到某篇论文但你不知道它是否在库中、或用户问"我有哪些论文"时使用。',
@@ -164,6 +166,11 @@ export function registerTools(ctx, config) {
                     paper: { type: 'string', required: true },
                     query: { type: 'string', required: true },
                     totalChunks: { type: 'integer', required: true },
+                    reranked: {
+                        type: 'boolean',
+                        required: true,
+                        description: '返回片段是否经过语义重排（配置了 Jev/TypeSafe 凭据且候选充足时为 true）。',
+                    },
                     hits: {
                         type: 'array',
                         required: true,
@@ -207,12 +214,28 @@ export function registerTools(ctx, config) {
                 throw new Error('转录失败，无法检索');
             const chunks = chunkText(cached.text, 1500);
             const k = Math.max(1, Math.min(args.k ?? 5, 8));
-            const hits = searchChunks(chunks, cached.pages, args.query, k);
+            // 两段式检索:关键词快搜捞 shortlist(宽召回),Jev 按语义重排取 top-k。
+            // 凭据每次现查(设置面板保存即生效);无凭据或候选不超过 k 时跳过重排。
+            const rerankClient = await resolveRerankClient(config.typesafe);
+            let hits = searchChunks(chunks, cached.pages, args.query, rerankClient ? shortlistSize : k);
+            let reranked = false;
+            if (rerankClient && hits.length > k) {
+                try {
+                    hits = await rerankHits(rerankClient, args.query, hits, k, config.typesafe?.deadlineMs ?? 1500);
+                    reranked = true;
+                }
+                catch (e) {
+                    // 超预算/网络/鉴权任何失败都退回关键词 top-k(结果已算好,零成本降级)
+                    console.warn('[dsh-paper-reader] 检索重排失败，退回关键词排序:', e);
+                    hits = hits.slice(0, k);
+                }
+            }
             return {
                 paper: `${ref.topic}/${ref.name}`,
                 query: args.query,
                 totalChunks: chunks.length,
                 hits: hits.map((h) => ({ chunk: h.chunk.index, page: h.page, text: h.chunk.text })),
+                reranked,
                 readerUrl: readerUrl(ref),
             };
         },

package/dist/translate.js

@@ -4,9 +4,8 @@
 // babeldoc 只支持 OpenAI 兼容端点 → 端点/key/模型由插件配置提供。
 import { execFile } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { mkdir, rename, rm } from 'node:fs/promises';
-import { glob } from 'node:fs/promises';
-import { join, dirname, basename, extname } from 'node:path';
+import { mkdir, rename, rm, readdir } from 'node:fs/promises';
+import { join, dirname, basename, extname, isAbsolute } from 'node:path';
 import { dshHome } from "./library.js";
 import { ensureBabeldoc } from "./babeldoc-install.js";
 export function zhPdfPath(ref) {
@@ -30,22 +29,26 @@ export function zhStatus(ref) {
         ...(b && !b.error && b.phase ? { phase: b.phase } : {}),
     };
 }
-/** 找 babeldoc 可执行文件：pdfqa venv（文献库同级 .venv-pdf2zh）→ PATH → miniconda。 */
+/** 找 babeldoc 可执行文件：pdfqa venv（文献库同级 .venv-pdf2zh）→ PATH → miniconda（仅 macOS）。 */
 async function findBabeldoc(dataDir) {
+    const isWin = process.platform === 'win32';
     const candidates = [
-        join(dirname(dataDir), '.venv-pdf2zh', 'bin', 'babeldoc'),
+        // 与 babeldoc-install.ts installBabeldoc 的安装位严格一致（win32 venv 用 Scripts/）
+        isWin
+            ? join(dirname(dataDir), '.venv-pdf2zh', 'Scripts', 'babeldoc.exe')
+            : join(dirname(dataDir), '.venv-pdf2zh', 'bin', 'babeldoc'),
         'babeldoc',
-        '/opt/homebrew/Caskroom/miniconda/base/bin/babeldoc',
+        ...(process.platform === 'darwin' ? ['/opt/homebrew/Caskroom/miniconda/base/bin/babeldoc'] : []),
     ];
     for (const c of candidates) {
-        if (c.includes('/')) {
+        if (isAbsolute(c)) {
             if (existsSync(c))
                 return c;
             continue;
         }
-        // PATH 查找
+        // PATH 查找（win32 用 where）
         const found = await new Promise((res) => {
-            execFile('which', [c], (err, stdout) => res(!err && stdout.trim() !== ''));
+            execFile(isWin ? 'where' : 'which', [c], (err, stdout) => res(!err && stdout.trim() !== ''));
         });
         if (found)
             return c;
@@ -180,11 +183,13 @@ async function launch(ref, dataDir, endpoint, bin) {
             }
             // 产出从 scratch 挪回文献目录：<名>.zh-CN.mono.pdf → -zh.pdf，.dual.pdf → -dual.pdf
             try {
-                for await (const f of glob(join(tmpDir, `${stem}*.zh-CN.mono.pdf`))) {
-                    await rename(f, dstStem + '-zh.pdf');
-                }
-                for await (const f of glob(join(tmpDir, `${stem}*.zh-CN.dual.pdf`))) {
-                    await rename(f, dstStem + '-dual.pdf');
+                // 不用 glob：其 pattern 里反斜杠是转义符，win32 的 join 路径会踩雷；readdir + 前后缀匹配全平台稳
+                const files = await readdir(tmpDir);
+                for (const f of files) {
+                    if (f.startsWith(stem) && f.endsWith('.zh-CN.mono.pdf'))
+                        await rename(join(tmpDir, f), dstStem + '-zh.pdf');
+                    if (f.startsWith(stem) && f.endsWith('.zh-CN.dual.pdf'))
+                        await rename(join(tmpDir, f), dstStem + '-dual.pdf');
                 }
                 if (!existsSync(zhPdfPath(ref)) && !existsSync(dualPdfPath(ref))) {
                     busy.set(ref.pdfPath, { error: 'babeldoc 未产出译文 PDF' });

package/dist/typesafe-config.js

@@ -0,0 +1,105 @@
+// typesafe-config.ts — Jev/TypeSafe 端点配置的落盘与解析（纯函数，不依赖 Cordis）。
+//
+// 与 translate-config.ts 同一套约定：存 $DSH_HOME/.dsh-paper-reader/typesafe.json
+// （0600，不进 dataDir——密钥不跟文献库走）；密钥只落盘、只回显掩码。
+// 优先级：文件（设置面板填的）> profile 的 cordis.patch.yml config.typesafe
+// > 环境变量 TYPESAFE_API_KEY（部署方兜底）。
+import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { TypeSafeClient, noul } from '@typesafe-ai/sdk';
+import { Agent, fetch as undiciFetch } from 'undici';
+import { dshHome } from "./library.js";
+import { maskApiKey } from "./translate-config.js";
+export { maskApiKey };
+// 跨境/弱网链路 TCP 握手可能远超 undici 默认的 10s connect 超时(实测 30s+),
+// 单独放宽 connect;总耗时仍由客户端 timeout 控制。fetch 与 Agent 必须用同一个
+// undici 包(混用 npm undici 的 Agent + Node 内置 fetch 会因 dispatcher 内部
+// 接口版本不匹配而炸),per-call dispatcher,不动全局 dispatcher。
+const longConnectAgent = new Agent({ connect: { timeout: 60_000 } });
+export const patientFetch = (input, init) => 
+// 运行时同源;类型上 @types/node 的 undici-types 与 npm undici 不完全兼容,双断言绕过
+undiciFetch(input, { ...init, dispatcher: longConnectAgent });
+export function typesafeConfigPath(home = dshHome()) {
+    return join(home, '.dsh-paper-reader', 'typesafe.json');
+}
+/** 读配置；文件缺失/损坏/形状不对一律返回 null（与 translate-config 的读策略一致）。 */
+export async function readTypesafeConfig(home = dshHome()) {
+    try {
+        const data = JSON.parse(await readFile(typesafeConfigPath(home), 'utf8'));
+        if (typeof data !== 'object' || data === null)
+            return null;
+        const rec = data;
+        const out = {};
+        if (typeof rec['apiKey'] === 'string')
+            out.apiKey = rec['apiKey'];
+        if (typeof rec['baseUrl'] === 'string')
+            out.baseUrl = rec['baseUrl'];
+        if (typeof rec['model'] === 'string')
+            out.model = rec['model'];
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+/** 写配置。0600：文件含明文密钥，不靠 umask。 */
+export async function writeTypesafeConfig(cfg, home = dshHome()) {
+    const file = typesafeConfigPath(home);
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, JSON.stringify(cfg, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
+    await chmod(file, 0o600); // mode 只在新建时生效；已存在的文件要显式收紧
+}
+/** 删除配置（回落到 profile 的 typesafe / 环境变量）。文件不存在也算成功。 */
+export async function clearTypesafeConfig(home = dshHome()) {
+    await rm(typesafeConfigPath(home), { force: true });
+}
+/** 解析生效配置：按字段 file > profile > env（只 env 有 key 时 source=env）。 */
+export async function resolveTypesafeConfig(profile, home = dshHome()) {
+    const file = await readTypesafeConfig(home);
+    const envKey = process.env['TYPESAFE_API_KEY'];
+    const cfg = {};
+    const apiKey = file?.apiKey || profile?.apiKey || envKey;
+    const baseUrl = file?.baseUrl || profile?.baseUrl;
+    const model = file?.model || profile?.model;
+    if (apiKey)
+        cfg.apiKey = apiKey;
+    if (baseUrl)
+        cfg.baseUrl = baseUrl;
+    if (model)
+        cfg.model = model;
+    const source = file?.apiKey
+        ? 'file'
+        : profile?.apiKey
+            ? 'profile'
+            : envKey?.trim()
+                ? 'env'
+                : 'none';
+    return { cfg, source };
+}
+/**
+ * 连接预检：打一发极小的 systemOne（一个 Noul、几个 token），确认 key/端点/模型有效。
+ * 与翻译预检同理：重排失败会静默降级成关键词排序，key 填错用户很难察觉，落盘前先拦。
+ */
+export async function testTypesafeEndpoint(cfg) {
+    if (!cfg.apiKey?.trim())
+        return { ok: false, detail: 'API Key 不能为空' };
+    try {
+        const client = new TypeSafeClient({
+            apiKey: cfg.apiKey,
+            ...(cfg.baseUrl ? { baseURL: cfg.baseUrl } : {}),
+            ...(cfg.model ? { defaultModel: cfg.model } : {}),
+            timeout: 60_000, // 预检同样走慢链路,15s 容易误杀
+            fetch: patientFetch,
+            logLevel: 'off',
+        });
+        await client.systemOne({
+            state: 'ping',
+            questions: { ok: noul('Is this a connectivity check? Reply yes.') },
+        });
+        return { ok: true };
+    }
+    catch (err) {
+        const cause = err instanceof Error && err.cause instanceof Error ? `: ${err.cause.message}` : '';
+        return { ok: false, detail: (err instanceof Error ? err.message : String(err)) + cause };
+    }
+}

package/lib/client.js

@@ -33,6 +33,17 @@ window.__ModuleLoader__.load({
       history: '历史对话',
       sync: '对话还停在另一篇文献的会话里，点击切到当前文献',
       mode: '论文伴读', modeEnterTip: '进入论文伴读：左侧变为文献库树', modeExitTip: '退出论文伴读：恢复官方工作区列表',
+      settings: '论文伴读',
+      setRerankTitle: '检索重排（Jev）',
+      setRerankDesc: 'search_paper 检索的语义重排：关键词先捞候选，Jev 逐个判断「这段能否回答这个问题」再排序——大白话提问也能命中论文里的术语段落。不配则退回纯关键词排序。',
+      setTranslateTitle: '翻译端点',
+      setTranslateDesc: '「生成中文版」（babeldoc）用的 OpenAI 兼容端点，三项必填。保存前会先测连接。',
+      setBaseUrl: '端点 URL', setModel: '模型', setKey: 'API Key',
+      setSave: '测试并保存', setSaving: '测试连接中…', setClear: '清除自填配置',
+      setSaved: '已保存，立即生效', setCleared: '已清除，回落到部署方默认',
+      setKeyKeep: '留空沿用已保存的 ', setOptional: '可选',
+      setSourceFile: '当前来源：设置页', setSourceProfile: '当前来源：配置文件（部署方默认）',
+      setSourceEnv: '当前来源：环境变量', setSourceNone: '未配置',
     }
     const en = {
       library: 'Library',
@@ -41,6 +52,17 @@ window.__ModuleLoader__.load({
       history: 'Chat history',
       sync: 'Chat is still on another paper — click to switch to the current one',
       mode: 'Paper Reading', modeEnterTip: 'Enter paper-reading mode: sidebar becomes the library tree', modeExitTip: 'Exit paper-reading mode: restore the official workspace list',
+      settings: 'Paper Reader',
+      setRerankTitle: 'Search rerank (Jev)',
+      setRerankDesc: 'Semantic rerank for search_paper: keyword search shortlists candidates, Jev judges "can this passage answer the question" and reorders — plain-language questions hit terminology passages. Without it, plain keyword ranking is used.',
+      setTranslateTitle: 'Translate endpoint',
+      setTranslateDesc: 'OpenAI-compatible endpoint for "Generate Chinese version" (babeldoc). All three fields required. Connection is tested before saving.',
+      setBaseUrl: 'Endpoint URL', setModel: 'Model', setKey: 'API Key',
+      setSave: 'Test & save', setSaving: 'Testing…', setClear: 'Clear my config',
+      setSaved: 'Saved, effective immediately', setCleared: 'Cleared, falling back to deployment defaults',
+      setKeyKeep: 'Leave empty to keep saved ', setOptional: 'optional',
+      setSourceFile: 'Source: settings page', setSourceProfile: 'Source: config file (deployment default)',
+      setSourceEnv: 'Source: environment variable', setSourceNone: 'Not configured',
     }
 
     let t = (k) => k
@@ -744,6 +766,90 @@ window.__ModuleLoader__.load({
       }, wide ? h(React.Fragment, null, '📚', h('span', null, t('mode'))) : '📚')
     }
 
+    /* ---------- 设置面板：Jev 重排 + 翻译端点统一管理 ----------
+       settings.section 面板（与官方 通用设置/模型 同款缝）。两张端点卡片共用一套
+       读写口（GET 掩码回显 / POST 预检后落盘 / DELETE 回落默认），key 明文永不回传，
+       留空即沿用已保存的那把。保存即生效：宿主每次调用都现读配置文件。 */
+    const SET = {
+      card: { border: '1px solid var(--dsw-alias-border-l1, #30363d)', borderRadius: '10px', padding: '14px 16px', margin: '0 0 16px', background: 'var(--dsw-alias-bg-layer-1, #0d1117)' },
+      title: { fontSize: '14px', fontWeight: 600, color: 'var(--dsw-alias-label-primary, #24292f)', margin: '0 0 4px' },
+      desc: { fontSize: '12px', lineHeight: '1.6', color: 'var(--dsw-alias-label-secondary, #656d76)', margin: '0 0 12px' },
+      label: { display: 'block', fontSize: '12px', color: 'var(--dsw-alias-label-secondary, #656d76)', margin: '10px 0 4px' },
+      input: { width: '100%', boxSizing: 'border-box', fontSize: '13px', padding: '6px 8px', borderRadius: '6px', border: '1px solid var(--dsw-alias-border-l1, #30363d)', background: 'var(--dsw-alias-bg-layer-2, #161b22)', color: 'var(--dsw-alias-label-primary, #24292f)' },
+      row: { display: 'flex', alignItems: 'center', gap: '10px', marginTop: '12px' },
+      btn: { fontSize: '13px', padding: '6px 14px', borderRadius: '6px', border: 'none', cursor: 'pointer', background: 'var(--dsw-alias-button-primary-fill, #1f6feb)', color: 'var(--dsw-alias-label-primary-foreground, #fff)' },
+      btnGhost: { fontSize: '12px', padding: '6px 10px', borderRadius: '6px', cursor: 'pointer', background: 'none', border: '1px solid var(--dsw-alias-border-l1, #30363d)', color: 'var(--dsw-alias-label-secondary, #656d76)' },
+      ok: { fontSize: '12px', color: 'var(--dsw-alias-state-success-primary, #3fb950)' },
+      err: { fontSize: '12px', color: 'var(--dsw-alias-state-error-primary, #f85149)' },
+      meta: { fontSize: '12px', color: 'var(--dsw-alias-label-secondary, #656d76)' },
+    }
+
+    function EndpointCard(props) {
+      const [cfg, setCfg] = useState(null) // GET 结果（含 apiKeyHint/source）
+      const [form, setForm] = useState({ baseUrl: '', model: '', apiKey: '' })
+      const [busy, setBusy] = useState(false)
+      const [msg, setMsg] = useState(null) // { ok, text }
+      const load = useCallback(() => {
+        api(props.path).then((d) => {
+          setCfg(d)
+          setForm({ baseUrl: d.baseUrl || '', model: d.model || '', apiKey: '' })
+        }).catch((e) => setMsg({ ok: false, text: String(e.message || e) }))
+      }, [props.path])
+      useEffect(load, [load])
+      const sourceText = !cfg ? '' : { file: t('setSourceFile'), profile: t('setSourceProfile'), env: t('setSourceEnv'), none: t('setSourceNone') }[cfg.source] || ''
+      const save = async () => {
+        setBusy(true); setMsg(null)
+        try {
+          await api(props.path, {
+            method: 'POST', headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(form),
+          })
+          setMsg({ ok: true, text: t('setSaved') })
+          load()
+        } catch (e) { setMsg({ ok: false, text: String(e.message || e) }) } finally { setBusy(false) }
+      }
+      const clear = async () => {
+        setBusy(true); setMsg(null)
+        try {
+          await api(props.path, { method: 'DELETE' })
+          setMsg({ ok: true, text: t('setCleared') })
+          load()
+        } catch (e) { setMsg({ ok: false, text: String(e.message || e) }) } finally { setBusy(false) }
+      }
+      const field = (key, label, placeholder, type) => h('div', null,
+        h('label', { style: SET.label }, label, props.optional && key !== 'apiKey' ? `（${t('setOptional')}）` : ''),
+        h('input', {
+          style: SET.input, type: type || 'text', value: form[key], placeholder, disabled: busy,
+          onChange: (e) => setForm({ ...form, [key]: e.target.value }),
+        }),
+      )
+      return h('div', { style: SET.card, 'data-dsh-plugin': 'dsh-paper-reader', 'data-dsh-part': 'settings-card' },
+        h('h3', { style: SET.title }, props.title),
+        h('p', { style: SET.desc }, props.desc),
+        field('baseUrl', t('setBaseUrl'), props.baseUrlPlaceholder),
+        field('model', t('setModel'), props.modelPlaceholder),
+        field('apiKey', t('setKey'), cfg?.hasApiKey ? t('setKeyKeep') + cfg.apiKeyHint : props.keyPlaceholder, 'password'),
+        h('div', { style: SET.row },
+          h('button', { type: 'button', style: SET.btn, disabled: busy, onClick: save }, busy ? t('setSaving') : t('setSave')),
+          cfg?.source === 'file' ? h('button', { type: 'button', style: SET.btnGhost, disabled: busy, onClick: clear }, t('setClear')) : null,
+          msg ? h('span', { style: msg.ok ? SET.ok : SET.err }, msg.text) : h('span', { style: SET.meta }, sourceText),
+        ),
+      )
+    }
+
+    function SettingsPanel() {
+      return h('div', { style: { maxWidth: '560px' }, 'data-dsh-plugin': 'dsh-paper-reader', 'data-dsh-surface': 'settings-modal' },
+        h(EndpointCard, {
+          path: '/typesafe/config', title: t('setRerankTitle'), desc: t('setRerankDesc'), optional: true,
+          baseUrlPlaceholder: 'https://api.typesafe.ai', modelPlaceholder: 'jev-latest', keyPlaceholder: 'ts-...',
+        }),
+        h(EndpointCard, {
+          path: '/translate/config', title: t('setTranslateTitle'), desc: t('setTranslateDesc'),
+          baseUrlPlaceholder: 'https://api.deepseek.com/v1', modelPlaceholder: 'deepseek-chat', keyPlaceholder: 'sk-...',
+        }),
+      )
+    }
+
     return {
       inject: ['slots', 'locale', 'layout', 'uiWorkspace', 'sidebarRight', 'sidebarRightTabs'],
       apply(ctx) {
@@ -779,6 +885,12 @@ window.__ModuleLoader__.load({
             name: 'sidebar.right.pane.tab', key: 'dpr-reader', locale: NS,
           }, PdfTab))
 
+          // 设置面板（设置 → 论文伴读）：Jev 重排 + 翻译端点统一管理
+          ctx.slots.inject('settings.section', () => ctx.slots.register({
+            name: 'settings.section', id: 'dsh-paper-reader', order: 70,
+            label: () => bound('settings'), locale: NS,
+          }, SettingsPanel))
+
           clientApi = { slots: ctx.slots, layout: ctx.layout, uiWorkspace: ctx.uiWorkspace, sidebarRight: ctx.sidebarRight }
 
           // 阅读器跳转链接拦截（capture 阶段，一次绑定）：渲染器给 http(s) 链接加了

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggboy123/dsh-paper-reader",
-  "version": "0.6.2",
+  "version": "1.1.0",
   "description": "DeepSeek Harness 插件：论文伴读工作台 — PDF 转录 / 检索 / 原生对话伴读 + 内置阅读器页面。",
   "license": "MIT",
   "type": "module",
@@ -50,19 +50,31 @@
   "keywords": [
     "dsh-plugin",
     "deepseek-harness",
+    "deepseek",
     "pdf",
+    "pdf-reader",
     "paper",
-    "reader"
+    "paper-reading",
+    "research-paper",
+    "citation",
+    "reader",
+    "arxiv",
+    "ai-assistant",
+    "rag",
+    "translation"
   ],
   "dependencies": {
-    "@deepseek-ai/dsh-tools": "0.1.5-rc.2",
-    "pdfjs-dist": "^6.3.289"
+    "@typesafe-ai/sdk": "^0.6.0",
+    "pdfjs-dist": "^6.3.289",
+    "undici": "^8.10.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-tools": ">=0.1.5-rc.1 <0.2.0-0"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-tools": "0.1.5-rc.2",
     "@types/node": "^22.10.0",
     "typescript": "^5.6.0"
   }

package/reader/index.html

@@ -172,6 +172,7 @@ function esc(s) { return s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;
 
 let current = null;        // { topic, name }
 let zhState = { zh: false, dual: false, busy: false };
+let statusMeta = ''; // openPaper 的「name · N 页」基线，翻译阶段标签褪去后恢复它
 let zhVariant = null;      // null=原文 'dual'=中英对照 'zh'=纯中文
 // 每篇论文记住上次用的语言版本：伴读会话的跳转链接原地跳页不重载，
 // 加上这里的恢复，「中文界面跳中文」在同篇跳转/重开/跨论文三条路径上都成立
@@ -190,9 +191,10 @@ async function openPaper(topic, name, opts = {}) {
   $('status').textContent = '加载 PDF…';
   const q = `topic=${encodeURIComponent(topic)}&name=${encodeURIComponent(name)}`;
   const meta = await api('/paper?' + q);
-  $('status').textContent = meta.hasTranscript
+  statusMeta = meta.hasTranscript
     ? `${name} · ${meta.pageCount ?? '?'} 页`
     : `${name} · 未转录（提问时会自动转录）`;
+  $('status').textContent = statusMeta;
   await refreshZhState();
   // 恢复该论文上次的语言版本（译文已不存在时回落原文）
   const saved = localStorage.getItem(variantKey(topic, name));
@@ -213,8 +215,15 @@ async function refreshZhState() {
   btn.title = zhState.busy ? (zhState.phase || `翻译进行中${zhState.model ? `（${zhState.model}）` : ''}…`)
     : (zhState.zh || zhState.dual) ? '切换中文译文'
     : '还没有中文版，点击生成（babeldoc，需要几分钟）';
-  // 安装/准备阶段在状态栏持续可见（轮询每 5s 刷新一次）
-  if (zhState.busy && zhState.phase) $('status').textContent = zhState.phase;
+  // 安装/准备阶段在状态栏持续可见（轮询每 5s 刷新一次）；翻译结束后恢复论文基线信息
+  const statusEl = $('status');
+  if (zhState.busy && zhState.phase) {
+    statusEl.textContent = zhState.phase;
+    statusEl.dataset.phaseShown = '1';
+  } else if (!zhState.busy && statusEl.dataset.phaseShown) {
+    delete statusEl.dataset.phaseShown;
+    if (statusMeta) statusEl.textContent = statusMeta;
+  }
   // ↻ 只在「已有译文且空闲」时出现；状态变化时顺手拆掉两击确认的待确认态
   const regen = $('zh-regen');
   const canRegen = (zhState.zh || zhState.dual) && !zhState.busy;