@ggboy123/dsh-paper-reader 1.3.5 → 1.4.1

package/dist/host.js

@@ -1,14 +1,19 @@
 // host.ts — webServer 路由：阅读器页面 + PDF 文件 + 转录数据接口 + 选中即问。
 // 壳层代码：只做 HTTP ↔ 纯函数核心(library/transcribe)的转接。
-import { createReadStream, readFileSync } from 'node:fs';
+import { createReadStream, existsSync, readFileSync, realpathSync } from 'node:fs';
 import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
-import { basename, join } from 'node:path';
-import { deletePaper, deleteTopic, listPapers, listTopics, paperRefFor, renamePaper, renameTopic, resolveDataDir, resolvePaper, resolveUploadTopic, validateEntryBoundary, validateEntryName, } from "./library.js";
-import { readTranscript, transcribePaper } from "./transcribe.js";
+import { basename, join, resolve } from 'node:path';
+import { listPapers, listTopics, resolveDataDir, resolvePaper, resolveUploadTopic, validateEntryBoundary, validateEntryName, } from "./library.js";
+import { ManageError, assertInside, clearTopic, planTopicClear, deletePaper, deleteTopic, isManageError, planPaperDelete, planTopicDelete, realDataDir, renamePaper, renameTopic, resolveTopicDir, validateName, } from "./library-manage.js";
+import { readFormulaIndex } from "./formulas.js";
+import { MineruError, sanitizeDetail } from "./mineru.js";
+import { readTranscript, transcribePaper, ScannedPdfError, ShortTextError } 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 { clearEmbedConfig, maskApiKey as maskEmbedApiKey, readEmbedConfig, resolveEmbedConfig, testEmbedEndpoint, writeEmbedConfig, } from "./embed-config.js";
+import { clearMineruConfig, mergeMineruBody, precheckMineruConfig, resolveMineruConfig, testMineruCloud, testMineruLocal, writeMineruConfig, } from "./mineru-config.js";
 import { installPaperPreset, PAPER_PRESET_ID } from "./preset.js";
 import { noteOrigin } from "./origin.js";
 function json(res, status, body) {
@@ -34,12 +39,14 @@ async function readBody(req) {
     const raw = Buffer.concat(chunks).toString('utf8');
     if (!raw)
         return {};
+    // 畸形 JSON / 整包 null / 非对象 → {}：路由据此给**可读 400**（原来是 JSON.parse 抛错 →
+    // 外层兜底 500 internal，错误分类错误）。PR-1 的错误分类收口，rebase 时一并带入。
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
     catch {
-        return {}; // 畸形 JSON 与整包 null/非对象同待遇：路由据此给可读 400（不再 500）
+        return {};
     }
     return parsed !== null && typeof parsed === 'object' ? parsed : {};
 }
@@ -80,7 +87,14 @@ export function registerRoutes(ctx, config) {
             args.topic = topic;
         if (name)
             args.name = name;
-        return resolvePaper(dataDir, args);
+        try {
+            return resolvePaper(dataDir, args);
+        }
+        catch {
+            // 原先普通 Error 会冒泡成 500 且把「PDF 不存在: /abs/path」这类绝对路径写进响应体；
+            // 这里统一成 404 + 只含名称的文案（读路径也一样，语义更准且不泄露服务端路径）。
+            throw notFound(args.path ? '文献不存在（path 指向的文件不可用）' : `文献不存在：${args.topic ? `${args.topic}/` : ''}${args.name ?? ''}`);
+        }
     };
     /** 每篇文献的伴读会话 id（确定性，重启/刷新后可续）；n 支持同文献多会话（会话1/2/…）。 */
     const sessionPrefixFor = (ref) => `dpr-${Buffer.from(`${ref.topic}/${ref.name}`).toString('base64url')}`;
@@ -164,6 +178,153 @@ export function registerRoutes(ctx, config) {
         }
         return sessionController.create({ sessionId, cwd: join(dataDir, topic) });
     };
+    /* ── 破坏性操作（删除/重命名）的共用出口 ──────────────────────────────────
+       契约：docs/reader-ux-requirements.md §2。错误文案一律不含服务端绝对路径；
+       结构性字段（trashDir/trashRel）只在必须给用户恢复线索时出现（见 O4 说明）。 */
+    const manageFail = (res, err) => {
+        if (!isManageError(err))
+            return false;
+        json(res, err.status, { error: err.message, code: err.code, ...err.extra });
+        return true;
+    };
+    /**
+     * errno 错误通道 —— **复用上游 #4 的 `fsError` 语义**：EBUSY/EPERM（文件被占用）→ 409 占用文案，
+     * 其余 errno → 400 + 固定中文文案（`readableError` 对带 `.code` 的错误不回显原始 message，
+     * 因此绝不泄露 dataDir/绝对路径）；不带 `.code` 的业务 Error 保留可读 message。
+     * 说明（t4 评审 O6 的旧裁定在此被上游必修 3 推翻）：上游要求的正是这条通道，现予恢复。
+     */
+    const fsError = (res2, err) => {
+        const e = err;
+        if (e?.code === 'EBUSY' || e?.code === 'EPERM') {
+            json(res2, 409, { error: '文件被占用（可能正在阅读器或其他程序中打开），关闭后重试', code: 'file-busy' });
+            return true;
+        }
+        json(res2, 400, { error: readableError(err) });
+        return true;
+    };
+    /** 破坏性路由的统一失败出口：我们的 ManageError 优先（status/code/extra），否则走 errno 通道。 */
+    const libFail = (res2, err) => {
+        if (isManageError(err))
+            return manageFail(res2, err);
+        return fsError(res2, err);
+    };
+    /**
+     * 某文献的伴读会话统计。**查不到就标 unknown**（不再吞成「0 个会话」）：
+     * R4-F3 指出 fail-open 会削弱 S7「有运行中会话就拒绝」——会话服务不可用时无法证明「没有运行中会话」，
+     * 破坏性操作据 unknown 走 fail-closed（见 requireSessionClear）。读路径不受影响（只有破坏性路由用它）。
+     */
+    /** 对外形状固定为 `{total, running}`（既有断言 deepEqual 它）；`unknown` 只在服务端内部用。 */
+    const toWire = (i) => ({ total: i.total, running: i.running });
+    const sessionInfo = async (ref) => {
+        if (typeof sessionController?.list !== 'function')
+            return { total: 0, running: 0, unknown: true };
+        try {
+            const s = await scanPaperSessions(ref);
+            return { total: s.length, running: s.filter((x) => x.running).length, unknown: false };
+        }
+        catch {
+            return { total: 0, running: 0, unknown: true };
+        }
+    };
+    /**
+     * 破坏性操作的会话准入（**fail-closed**）：查不到会话状态就**拒绝**，不冒险动手。
+     * 取向理由：删除会把产物搬进回收站、重命名会改会话工作区下的文件名；若此时真有会话在跑，
+     * 破坏的是用户当前正在用的工作目录。代价是「会话服务抖动时可能白拒一次」，用户重试即可——
+     * 可恢复性远好于误删。unknown 用 503 + code=session-unknown，running 用 409 + code=session-running。
+     */
+    const requireSessionClear = async (ref, res) => {
+        const info = await sessionInfo(ref);
+        if (info.unknown) {
+            json(res, 503, { error: '暂时无法确认该文献的伴读会话状态，为避免误删已取消本次操作；请稍后重试', code: 'session-unknown' });
+            return false;
+        }
+        if (info.running > 0) {
+            json(res, 409, { error: `该文献有 ${info.running} 个正在运行的伴读会话，请先结束后再操作`, code: 'session-running', sessions: toWire(info) });
+            return false;
+        }
+        return true;
+    };
+    /** 专题级会话准入：该专题内任一篇文献会话状态不明/在跑 → 拒绝。 */
+    const requireTopicSessionsClear = async (topic, res) => {
+        for (const p of listPapers(dataDir, topic)) {
+            if (!(await requireSessionClear(p, res)))
+                return false;
+        }
+        return true;
+    };
+    /**
+     * 契约 R5「并发互斥」的最小在途守卫（R4-F2）：
+     * 同一篇文献的删除/重命名在途时，第二个请求直接 409 `busy`（而不是让两个请求交错改同一批文件：
+     * 实测后果是第二个请求拿到 404/500 的中间态）。进程内 Set 足够——本插件是单进程 ws 路由。
+     * 机器码取 `busy` 而非契约 §5 R5 字面的 `in-progress`：两者语义完全一致（「有操作在途」），
+     * `busy` 更短且与既有 `translation-busy`/`session-running` 的短词风格一致；前端 errText 已按 `busy` 对齐。
+     */
+    const inflight = new Set();
+    const withInflight = async (key, res, fn) => {
+        if (inflight.has(key)) {
+            json(res, 409, { error: '同一篇文献的另一个删除/重命名操作正在进行，请稍后重试', code: 'busy' });
+            return;
+        }
+        inflight.add(key);
+        try {
+            await fn();
+        }
+        finally {
+            inflight.delete(key);
+        }
+    };
+    /** 「文献不存在」的统一出口：404 + 不含服务端绝对路径的文案（原先普通 Error 会冒泡成 500 并带路径）。 */
+    const notFound = (what) => new ManageError('not-found', 404, what);
+    /**
+     * **写路径**的文献定位（t3-O2：/api/transcribe 曾接受任意 `path` 并据此写盘）。
+     * 规则与删除同级：只认 topic+name；给了 `path` 时其 **realpath 必须落在 dataDir 内**
+     * （符号链接指向库外同样拒绝）。校验逻辑全部复用 library-manage 的既有实现，不另写一套。
+     */
+    const locateForWrite = (body, isUrlSearch = false) => {
+        void isUrlSearch;
+        if (body.path) {
+            const abs = resolve(String(body.path));
+            let real;
+            try {
+                real = realpathSync(abs);
+            }
+            catch {
+                throw notFound('文献不存在（path 指向的文件不可读）');
+            }
+            assertInside(realDataDir(dataDir), real); // 越界/符号链接逃逸 → 400 escape-rejected
+            return resolvePaper(dataDir, { path: abs });
+        }
+        // exactOptionalPropertyTypes: true —— 不能把 undefined 直接挂到可选属性上
+        const args = {};
+        if (body.topic !== undefined)
+            args.topic = body.topic;
+        if (body.name !== undefined)
+            args.name = body.name;
+        return resolvePaper(dataDir, args);
+    };
+    /** 破坏性路由用的文献定位：把 resolvePaper 的普通 Error 统一成 404（含符号链接 .pdf 的情况）。 */
+    const resolveLibraryPaper = (topic, name) => {
+        try {
+            return resolvePaper(dataDir, { topic, name });
+        }
+        catch {
+            throw notFound(`文献不存在：${name}`);
+        }
+    };
+    /**
+     * 外层兜底文案脱敏：把任何**绝对路径**替换成 `<path>`。
+     * 说明：这里没有采用「一律不回显 err.message」的极端做法——那会把 MinerU/转录等**可读的领域错误**
+     * 一起变成不可读（既有测试明确断言这些文案要含 `MinerU` 等关键词，不许放宽）。改为：领域错误保留可读文案、
+     * 但**先剥掉绝对路径**；未知内部错误则只给通用文案。两种情况都带机器可读 `code:'internal'`。
+     */
+    const stripAbsPaths = (msg) => msg.replace(/(?:[A-Za-z]:)?(?:[\\/][^\s'"“”（）()]+)+/g, '<path>');
+    /** 破坏性路由的统一前置检查：拒绝 path 参数（写路径只认 topic+name）。 */
+    const rejectWritePath = (body, res) => {
+        if (body.path === undefined || body.path === null || body.path === '')
+            return false;
+        json(res, 400, { error: '删除/重命名不接受 path 参数，请用 topic + name', code: 'escape-rejected' });
+        return true;
+    };
     const dispatch = async (req, res, url) => {
         const sub = url.pathname.slice('/paper-reader'.length); // '' | '/' | '/api/...'
         if ((sub === '' || sub === '/') && req.method === 'GET') {
@@ -202,22 +363,27 @@ export function registerRoutes(ctx, config) {
             json(res, 200, { dataDir, topics: listTopics(dataDir), papers });
             return;
         }
-        // 新建专题（目录）。校验与 rename 的 to 侧一致（validateEntryName：边界 + 命名规范），
-        // 保证「能创建的必然能删除/改名」（R12：创建/删除对称）。
+        // 新建专题（目录）。校验与 upload / rename 的 to 侧同一套（validateName：边界 + 命名规范），
+        // 保证「能创建的必然能删除/改名」（PR-1 的创建/删除对称原则；创建走 inline 正则时，
+        // `.hidden`/超长/含控制字符的名字都能被创建，却是删不掉的孤儿）。
         if (sub === '/api/library/topic' && req.method === 'POST') {
             const body = (await readBody(req));
-            if (typeof body.name !== 'string' || !body.name.trim()) {
-                json(res, 400, { error: '专题名不能为空' });
-                return;
+            try {
+                const name = validateName(body.name, 'topic');
+                const root = realDataDir(dataDir);
+                const dir = join(root, name);
+                // 已存在 → 必须是真目录且不是符号链接（与 upload 同一条链路）；不存在 → 词法层已保证不越界
+                if (existsSync(dir))
+                    resolveTopicDir(dataDir, name);
+                else
+                    assertInside(root, dir);
+                await mkdir(dir, { recursive: true });
+                json(res, 200, { ok: true, topic: name });
             }
-            const err = validateEntryName(body.name);
-            if (err) {
-                json(res, 400, { error: err });
-                return;
+            catch (err) {
+                if (!manageFail(res, err))
+                    throw err;
             }
-            const name = body.name.trim();
-            await mkdir(join(dataDir, name), { recursive: true });
-            json(res, 200, { ok: true, topic: name });
             return;
         }
         // 上传 PDF 到专题（raw body；文件名/专题走 header，避免 multipart 解析。
@@ -226,205 +392,389 @@ export function registerRoutes(ctx, config) {
             const topic = decodeHdr(req.headers['x-dpr-topic']);
             const filename = decodeHdr(req.headers['x-dpr-name']);
             if (typeof topic !== 'string' || typeof filename !== 'string' || !topic.trim() || !filename.trim()) {
-                json(res, 400, { error: '缺少 x-dpr-topic / x-dpr-name 头' });
+                json(res, 400, { error: '缺少 x-dpr-topic / x-dpr-name 头', code: 'bad-request' });
                 return;
             }
             // 词法层：与其余 CRUD 同强度（../ / \ 隐藏名 控制字符 超长 空串）
             const errName = validateEntryName(topic);
             if (errName) {
-                json(res, 400, { error: errName });
+                json(res, 400, { error: errName, code: 'bad-name' });
                 return;
             }
             if (!filename.toLowerCase().endsWith('.pdf')) {
-                json(res, 400, { error: '只支持 PDF 文件' });
+                json(res, 400, { error: '只支持 PDF 文件', code: 'bad-request' });
                 return;
             }
             const safeName = filename.replaceAll('/', '_').replaceAll('\\', '_');
-            // 文件名也做边界类校验（空/分隔符/../NUL），与删除侧对称：upload 能创建的必须能被删
-            const stem = safeName.slice(0, -4); // 去掉 .pdf
+            // 文件名走**边界类**（上游 #4 口径）：前导点 / 超长 / 非 NUL 控制字符都能上传，
+            // 与删除侧对称——upload 能落盘的名字必须能被删（library-symmetry R7/R14）。
+            const stem = safeName.slice(0, -4);
             const errStem = validateEntryBoundary(stem);
             if (errStem) {
-                json(res, 400, { error: errStem });
+                json(res, 400, { error: errStem, code: 'bad-name' });
                 return;
             }
-            const chunks = [];
-            for await (const c of req)
-                chunks.push(c);
-            const buf = Buffer.concat(chunks);
-            if (buf.length < 100) {
-                json(res, 400, { error: '文件内容为空' });
+            // realpath 子路径层（上游 #4 的 resolveUploadTopic）：`data/<topic> → 库外` 与**悬空**符号
+            // 链接都在这里被挡（悬空链接 lstat 算存在、realpath 失败 → 400 可读文案，而不是 mkdir 抛 ENOENT 的 500）。
+            // 顺序：目标目录的全部校验都在**读 body 之前**——越界目标不消费请求体、不碰盘。
+            let dir;
+            try {
+                dir = resolveUploadTopic(dataDir, topic);
+            }
+            catch (err) {
+                json(res, 400, { error: readableError(err), code: 'escape-rejected' });
                 return;
             }
-            // realpath 子路径层：拒绝「data/<topic> → 库外」符号链接逃逸写（与 CRUD 同一套 primitive）
-            let dir;
+            // 我们的加严：上游放行「real 落在库内」的符号链接专题，我们一律拒（评审 §B 点名表扬）。
             try {
-                dir = resolveUploadTopic(dataDir, topic.trim());
+                if (existsSync(dir))
+                    resolveTopicDir(dataDir, topic.trim());
+                else
+                    assertInside(realDataDir(dataDir), dir);
             }
             catch (err) {
-                json(res, 400, { error: readableError(err) });
+                if (libFail(res, err))
+                    return;
+                throw err;
+            }
+            const chunks = [];
+            for await (const c of req)
+                chunks.push(c);
+            const buf = Buffer.concat(chunks);
+            if (buf.length < 100) {
+                json(res, 400, { error: '文件内容为空', code: 'bad-request' });
                 return;
             }
             try {
                 await mkdir(dir, { recursive: true });
-                const target = join(dir, safeName);
-                await writeFile(target, buf);
+                await writeFile(join(dir, safeName), buf);
             }
             catch (err) {
-                json(res, 400, { error: readableError(err) });
+                fsError(res, err);
                 return;
             }
-            json(res, 200, { ok: true, topic: topic.trim(), name: safeName.slice(0, -4), bytes: buf.length });
+            json(res, 200, { ok: true, topic: topic.trim(), name: stem, bytes: buf.length });
             return;
         }
-        /* ---- 库管理：专题/文献 改名与删除。----
-         * 翻译进行中（busy）一律 409 拒绝——babeldoc 异步跑着会往旧路径写 -zh/-dual 产物，
-         * 改名/删除会让它写丢；busy 键控在旧路径上，动了就失联。
-         * Windows 下删除被阅读器 iframe 占用的文件可能 EBUSY/EPERM，转成可读文案。 */
-        const busyPapersInTopic = (topic) => listPapers(dataDir, topic)
-            .filter((p) => zhStatus(paperRefFor(dataDir, p.topic, p.name)).busy)
-            .map((p) => p.name);
-        const fsError = (res2, err) => {
-            const e = err;
-            if (e?.code === 'EBUSY' || e?.code === 'EPERM') {
-                json(res2, 409, { error: '文件被占用（可能正在阅读器或其他程序中打开），关闭后重试' });
-            }
-            else {
-                json(res2, 400, { error: readableError(err) });
-            }
-        };
-        /** 非法/越界名字 → 400 可读文案（词法层；realpath 子路径层在 library primitive 内兜底）。
-         *  放在 busyPapersInTopic / resolvePaper 之前，越界输入不会碰任何文件系统。返回 true 表示已响应。 */
+        /* ── 路由名兼容层 ─────────────────────────────────────────────────────
+           上游 v1.3.0（614b935）为文献库自建了 4 条 CRUD 路由
+           `/api/library/{delete,rename}-{topic,paper}` —— **对外规范路径**（上游 UI / 文档 / 上游用例
+           都走它们）。我们分支的 `/api/library/{topic,paper}/{delete,rename}` 保留为别名。
+           两族共用同一批 handler，底层永远是 library-manage 的加固实现（回收站可恢复 / 精确 stem /
+           realpath 三层穿越防护 / 会话·翻译·在途 409 / 删除计划）；上游那份带穿越洞的第二实现
+           （rmSync(recursive) 且 topic 未校验）已整段删除 —— 任何时刻只有一份实现。
+           body 键也做兼容：topic ?? name、newName ?? to。 */
+        /** 非法/越界名字 → 400 可读文案（词法层复用上游 #4 的 validateEntryName；realpath 层由 primitive 兜底）。
+         *  放在任何文件系统操作之前：越界输入不会碰到盘。返回 true 表示已响应。 */
         const badEntry = (res, raw) => {
             const err = typeof raw === 'string' ? validateEntryName(raw) : '名字不能为空';
             if (!err)
                 return false;
-            json(res, 400, { error: err });
+            json(res, 400, { error: err, code: 'bad-name' });
             return true;
         };
-        /** 删除/改名-from 用：只做边界类校验（安全），不做命名规范类（长度/前导点）。
-         *  删除是对已存在文件的操作——upload 能创建的名字（前导点、超长、\x01 等）必须能删。 */
+        /** 删除 / 改名-from 用（上游 #4 的分层）：只做边界类校验（空、分隔符、`..`、NUL），不卡命名规范。 */
         const badEntryBoundary = (res, raw) => {
             const err = typeof raw === 'string' ? validateEntryBoundary(raw) : '名字不能为空';
             if (!err)
                 return false;
-            json(res, 400, { error: err });
+            json(res, 400, { error: err, code: 'bad-name' });
             return true;
         };
-        if (sub === '/api/library/rename-topic' && req.method === 'POST') {
-            const body = (await readBody(req));
-            if (typeof body.topic !== 'string' || !body.topic.trim()) {
-                json(res, 400, { error: '缺少 topic' });
-                return;
-            }
-            if (badEntry(res, body.topic))
-                return;
-            if (badEntry(res, body.to ?? ''))
-                return;
-            const busy = busyPapersInTopic(body.topic.trim());
-            if (busy.length) {
-                json(res, 409, { error: `以下文献正在翻译，稍后再试：${busy.join('、')}` });
+        // 删除预览（dry-run）：确认弹窗的文件清单必须来自这里，不许前端自己拼
+        if (sub === '/api/library/paper/delete-plan' && req.method === 'GET') {
+            const topic = url.searchParams.get('topic') ?? '';
+            const name = url.searchParams.get('name') ?? '';
+            if (url.searchParams.get('path')) {
+                json(res, 400, { error: '不接受 path 参数，请用 topic + name', code: 'escape-rejected' });
                 return;
             }
             try {
-                renameTopic(dataDir, body.topic.trim(), body.to ?? '');
+                const plan = planPaperDelete(dataDir, topic, name);
+                const ref = resolveLibraryPaper(plan.topic, plan.name);
+                const sessions = await sessionInfo(ref);
+                const zh = zhStatus(ref);
+                json(res, 200, {
+                    topic: plan.topic,
+                    name: plan.name,
+                    files: plan.files,
+                    totalBytes: plan.totalBytes,
+                    trashRoot: plan.trashRoot,
+                    sessions: toWire(sessions),
+                    translation: { busy: zh.busy, hasZh: zh.zh, hasDual: zh.dual },
+                    notDeleted: plan.notDeleted,
+                });
             }
             catch (err) {
-                fsError(res, err);
-                return;
+                if (!libFail(res, err))
+                    throw err;
             }
-            workspaceCache.delete(join(dataDir, body.topic.trim())); // 旧目录的工作区记录失效（残留无害）
-            json(res, 200, { ok: true, topic: body.to?.trim() });
             return;
         }
-        if (sub === '/api/library/delete-topic' && req.method === 'POST') {
+        // 删除文献：产物移入 <dataDir>/.trash/（可恢复）。规范名 = 上游 /api/library/delete-paper，
+        // 别名 = /api/library/paper/delete。词法门走 badEntry(topic) + badEntryBoundary(name)。
+        if ((sub === '/api/library/delete-paper' || sub === '/api/library/paper/delete') && req.method === 'POST') {
             const body = (await readBody(req));
-            if (typeof body.topic !== 'string' || !body.topic.trim()) {
-                json(res, 400, { error: '缺少 topic' });
+            if (badEntry(res, body.topic) || badEntryBoundary(res, body.name))
                 return;
-            }
-            if (badEntry(res, body.topic))
+            if (rejectWritePath(body, res))
                 return;
-            const busy = busyPapersInTopic(body.topic.trim());
-            if (busy.length) {
-                json(res, 409, { error: `以下文献正在翻译，稍后再试：${busy.join('、')}` });
+            await withInflight(`${String(body.topic ?? '')}\u0000${String(body.name ?? '')}`, res, async () => {
+                try {
+                    const plan = planPaperDelete(dataDir, body.topic, body.name);
+                    const ref = resolveLibraryPaper(plan.topic, plan.name);
+                    const sessions = await sessionInfo(ref); // 全部前提先校验，再动手
+                    if (!(await requireSessionClear(ref, res)))
+                        return;
+                    if (zhStatus(ref).busy) {
+                        throw new ManageError('translation-busy', 409, '该文献正在生成译文，请等待完成后再删除', {});
+                    }
+                    const r = deletePaper(dataDir, plan.topic, plan.name);
+                    // `deleted` = 上游字段名（上游用例断言），`moved` = 我们的；同源同义
+                    json(res, 200, { ...r, deleted: r.moved, sessions: toWire(sessions) });
+                }
+                catch (err) {
+                    if (!libFail(res, err))
+                        throw err;
+                }
+            });
+            return;
+        }
+        // 重命名文献：全部同名产物一起改名（含译文变体），`.pdf` 最后移。
+        // 规范名 = /api/library/rename-paper（上游 UI 与用例），别名 = /api/library/paper/rename。
+        if ((sub === '/api/library/rename-paper' || sub === '/api/library/paper/rename') && req.method === 'POST') {
+            const body = (await readBody(req));
+            const rawTo = body.newName ?? body.to;
+            if (badEntry(res, body.topic) || badEntryBoundary(res, body.name) || badEntry(res, rawTo))
                 return;
-            }
-            try {
-                deleteTopic(dataDir, body.topic.trim());
-            }
-            catch (err) {
-                fsError(res, err);
+            if (rejectWritePath(body, res))
                 return;
-            }
-            json(res, 200, { ok: true });
+            await withInflight(`${String(body.topic ?? '')}\u0000${String(body.name ?? '')}`, res, async () => {
+                try {
+                    // 先校验名称/越界/存在（planPaperDelete 内部做全套检查）——不能先 resolvePaper：
+                    // 非法名会在那里抛出非 ManageError 的普通错误，被外层记成 500。
+                    const plan = planPaperDelete(dataDir, body.topic, body.name);
+                    const ref = resolveLibraryPaper(plan.topic, plan.name);
+                    const sessions = await sessionInfo(ref);
+                    if (!(await requireSessionClear(ref, res)))
+                        return;
+                    if (zhStatus(ref).busy) {
+                        throw new ManageError('translation-busy', 409, '该文献正在生成译文，请等待完成后再重命名', {});
+                    }
+                    const r = renamePaper(dataDir, ref.topic, ref.name, rawTo);
+                    // 会话 id 内嵌 topic/name → 改名后旧会话不再出现在该文献的列表里（不删除，如实回显）
+                    json(res, 200, { ...r, name: r.to, detachedSessions: sessions.total });
+                }
+                catch (err) {
+                    if (!libFail(res, err))
+                        throw err;
+                }
+            });
             return;
         }
-        if (sub === '/api/library/rename-paper' && req.method === 'POST') {
+        // 删除专题：仅空专题（非隐藏条目为 0），非递归语义；隐藏条目进回收站而不是销毁。
+        // 规范名 = /api/library/delete-topic；上游 UI 只发 {topic}（没有确认字段），我们的 UI 发
+        // {name, confirmName} 两段式确认。confirmName 语义（本文件）：
+        //   · 给了就必须与专题名完全一致（confirmName === topic|name，否则 400 confirm-mismatch）；
+        //   · 没给也照走全部前置——**空专题免确认**（上游契约，没有数据可毁），
+        //     非空专题一律 409 topic-not-empty（我们的加固，比上游「一点递归删光」保守）。
+        if ((sub === '/api/library/delete-topic' || sub === '/api/library/topic/delete') && req.method === 'POST') {
             const body = (await readBody(req));
-            if (typeof body.topic !== 'string' || !body.topic.trim() || typeof body.name !== 'string' || !body.name.trim()) {
-                json(res, 400, { error: '缺少 topic / name' });
+            const rawName = typeof body.topic === 'string' && body.topic ? body.topic : body.name;
+            if (typeof rawName !== 'string' || rawName.length === 0) {
+                badEntry(res, rawName);
                 return;
             }
-            if (badEntry(res, body.topic))
+            if (badEntryBoundary(res, rawName))
                 return;
-            if (badEntryBoundary(res, body.name))
+            // 词法门两段式（4 条路由都必须在文件系统操作之前过 badEntry，见 upstream V12 的结构性断言）：
+            // ① badEntry（上游 #4 的 validateEntryName）挡**类型 / 空值**——非字符串、空串在任何模式下都非法；
+            // ② 命名规范类（长度/前导点/非 NUL 控制字符）只对「创建 / 改名-to」强制；删除/改名-from
+            //    走 badEntryBoundary（分层理由见其定义：历史遗留的不规范名必须能清掉，否则是删不掉的孤儿）。
+            if (rejectWritePath(body, res))
                 return;
-            if (badEntry(res, body.to ?? ''))
+            await withInflight(`topic\u0000${String(rawName ?? '')}`, res, async () => {
+                try {
+                    const name = rawName;
+                    // confirmName 是**可选**栅栏：给了就必须一致（400 confirm-mismatch）；没给也照走全部前置——
+                    // 空专题免确认（上游 delete-topic {topic} 契约：没有数据可毁），非空专题一律
+                    // 409 topic-not-empty（我们的加固，比上游「一点递归删光」保守，见 docs/reader-ux-requirements.md）。
+                    if (body.confirmName !== undefined && body.confirmName !== name) {
+                        throw new ManageError('confirm-mismatch', 400, '需要 confirmName 与 name 完全一致才允许删除专题', {});
+                    }
+                    const plan = planTopicDelete(dataDir, name); // 全部前提先校验，再动手
+                    if (plan.entries.length > 0) {
+                        // clearEndpoint：非空专题的「下一步」——UI 据此进入**批量清空**中间态（上游评论第 10 条）
+                        throw new ManageError('topic-not-empty', 409, `专题内还有 ${plan.entries.length} 个条目（${plan.papers.length} 篇文献），请用批量清空或先逐篇删除`, {
+                            entries: plan.entries,
+                            papers: plan.papers,
+                            clearEndpoint: '/api/library/topic/clear',
+                            clearPlanEndpoint: '/api/library/topic/clear-plan',
+                        });
+                    }
+                    if (!(await requireTopicSessionsClear(plan.name, res)))
+                        return;
+                    let busy = 0;
+                    for (const p of listPapers(dataDir, plan.name)) {
+                        if (zhStatus(resolveLibraryPaper(p.topic, p.name)).busy)
+                            busy++;
+                    }
+                    if (busy > 0)
+                        throw new ManageError('translation-busy', 409, '该专题有正在生成译文的文献，请等待完成后再删除', {});
+                    const r = deleteTopic(dataDir, plan.name);
+                    workspaceCache.delete(join(dataDir, plan.name)); // 清掉指向已删目录的工作区缓存
+                    json(res, 200, { ...r, archivedSessionsNote: true });
+                }
+                catch (err) {
+                    if (!libFail(res, err))
+                        throw err;
+                }
+            });
+            return;
+        }
+        // 重命名专题：目录整体改名（历史会话不删除，但不再出现在该专题下）
+        if ((sub === '/api/library/rename-topic' || sub === '/api/library/topic/rename') && req.method === 'POST') {
+            const body = (await readBody(req));
+            const rawName = typeof body.topic === 'string' && body.topic ? body.topic : body.name;
+            const rawTo = body.newName ?? body.to;
+            if (typeof rawName !== 'string' || rawName.length === 0) {
+                badEntry(res, rawName);
                 return;
-            let ref;
-            try {
-                ref = resolvePaper(dataDir, { topic: body.topic.trim(), name: body.name.trim() });
             }
-            catch (err) {
-                fsError(res, err);
+            // from 侧同 delete-topic：badEntry 挡类型/空值，命名规范只在改名**目标**（badEntry(rawTo)）上强制
+            // ——这样「历史遗留的怪名专题 → 改成规范名」这条路不被自己的校验堵死。
+            if (badEntryBoundary(res, rawName) || badEntry(res, rawTo))
                 return;
-            }
-            if (zhStatus(ref).busy) {
-                json(res, 409, { error: '该文献正在翻译，稍后再试' });
+            if (rejectWritePath(body, res))
+                return;
+            await withInflight(`topic\u0000${String(rawName ?? '')}`, res, async () => {
+                try {
+                    const name = String(rawName ?? '');
+                    const plan = planTopicDelete(dataDir, name); // 复用同一个「存在且合法」校验
+                    if (!(await requireTopicSessionsClear(plan.name, res)))
+                        return;
+                    let busy = 0;
+                    let detached = 0;
+                    for (const p of listPapers(dataDir, plan.name)) {
+                        const ref = resolveLibraryPaper(p.topic, p.name);
+                        const s = await sessionInfo(ref);
+                        if (s.unknown) {
+                            json(res, 503, { error: '暂时无法确认该专题的伴读会话状态，为避免误删已取消本次操作；请稍后重试', code: 'session-unknown' });
+                            return;
+                        }
+                        detached += s.total;
+                        if (zhStatus(ref).busy)
+                            busy++;
+                    }
+                    if (busy > 0)
+                        throw new ManageError('translation-busy', 409, '该专题有正在生成译文的文献，请等待完成后再重命名', {});
+                    const r = renameTopic(dataDir, plan.name, rawTo);
+                    workspaceCache.delete(join(dataDir, plan.name));
+                    // 响应补 `topic`（上游 UI/文档读法）——我们的 RenameResult 用 from/to
+                    json(res, 200, { ...r, topic: r.to, detachedSessions: detached });
+                }
+                catch (err) {
+                    if (!libFail(res, err))
+                        throw err;
+                }
+            });
+            return;
+        }
+        // 清空预览（dry-run，只读）：非空专题删除的**中间态**清单（上游评论第 10 条）。
+        // 形状与 /api/library/paper/delete-plan 对齐（files/totalBytes/notDeleted），逐篇额外给
+        // sessions/translation，让 UI 在用户点确认**之前**就能提示「第 7 篇正在翻译」。
+        if (sub === '/api/library/topic/clear-plan' && req.method === 'GET') {
+            const topic = url.searchParams.get('topic') ?? '';
+            if (url.searchParams.get('path')) {
+                json(res, 400, { error: '不接受 path 参数，请用 topic', code: 'escape-rejected' });
                 return;
             }
-            let renamed;
             try {
-                renamed = renamePaper(dataDir, ref.topic, ref.name, body.to ?? '');
+                const plan = planTopicClear(dataDir, topic);
+                const papers = [];
+                for (const p of plan.papers) {
+                    const ref = resolveLibraryPaper(plan.topic, p.name);
+                    const sessions = await sessionInfo(ref);
+                    const zh = zhStatus(ref);
+                    papers.push({
+                        name: p.name,
+                        files: p.files,
+                        totalBytes: p.totalBytes,
+                        sessions: toWire(sessions),
+                        translation: { busy: zh.busy, hasZh: zh.zh, hasDual: zh.dual },
+                    });
+                }
+                json(res, 200, {
+                    topic: plan.topic,
+                    papers,
+                    papersCount: plan.papersCount,
+                    filesCount: plan.filesCount,
+                    totalBytes: plan.totalBytes,
+                    hidden: plan.hidden,
+                    trashRoot: plan.trashRoot,
+                    notDeleted: plan.notDeleted,
+                    clearEndpoint: '/api/library/topic/clear',
+                });
             }
             catch (err) {
-                fsError(res, err);
-                return;
+                if (!libFail(res, err))
+                    throw err;
             }
-            json(res, 200, { ok: true, topic: ref.topic, name: body.to?.trim(), renamed });
             return;
         }
-        if (sub === '/api/library/delete-paper' && req.method === 'POST') {
+        // 批量清空专题（一次确认、逐篇进回收站、失败即整体回滚）：`confirmName === topic` 是**必需**的
+        // （手输专题名确认保留在清空这一步，不放松）。
+        // 前置：全部校验完（存在性 / 非空 / 逐篇会话 / 逐篇翻译）才动一个字节；
+        // 执行：withInflight（同一专题并发只放一个）+ library-manage.clearTopic（非递归 rmdir）。
+        if (sub === '/api/library/topic/clear' && req.method === 'POST') {
             const body = (await readBody(req));
-            if (typeof body.topic !== 'string' || !body.topic.trim() || typeof body.name !== 'string' || !body.name.trim()) {
-                json(res, 400, { error: '缺少 topic / name' });
+            const rawTopic = typeof body.topic === 'string' && body.topic ? body.topic : body.name;
+            if (typeof rawTopic !== 'string' || rawTopic.length === 0) {
+                badEntry(res, rawTopic);
                 return;
             }
-            if (badEntry(res, body.topic))
+            if (badEntryBoundary(res, rawTopic))
                 return;
-            if (badEntryBoundary(res, body.name))
+            if (rejectWritePath(body, res))
                 return;
-            let ref;
-            try {
-                ref = resolvePaper(dataDir, { topic: body.topic.trim(), name: body.name.trim() });
-            }
-            catch (err) {
-                fsError(res, err);
+            if (body.confirmName !== rawTopic) {
+                json(res, 400, { error: '需要 confirmName 与专题名完全一致才允许清空', code: 'confirm-mismatch' });
                 return;
             }
-            if (zhStatus(ref).busy) {
-                json(res, 409, { error: '该文献正在翻译，稍后再试' });
-                return;
-            }
-            let deleted;
-            try {
-                deleted = deletePaper(dataDir, ref.topic, ref.name);
-            }
-            catch (err) {
-                fsError(res, err);
-                return;
-            }
-            json(res, 200, { ok: true, deleted });
+            await withInflight(`topic\u0000${rawTopic}`, res, async () => {
+                try {
+                    const plan = planTopicClear(dataDir, rawTopic); // 存在性 404 / 越界 400 / 符号链接专题 400
+                    if (plan.papersCount === 0) {
+                        throw new ManageError('bad-request', 400, '专题已为空，请用删除专题', { clearEndpoint: '/api/library/delete-topic' });
+                    }
+                    let detached = 0;
+                    const busyTrans = [];
+                    for (const p of plan.papers) {
+                        const ref = resolveLibraryPaper(plan.topic, p.name);
+                        if (!(await requireSessionClear(ref, res)))
+                            return; // unknown→503 / running→409（同一套 code）
+                        detached += (await sessionInfo(ref)).total;
+                        if (zhStatus(ref).busy)
+                            busyTrans.push(p.name);
+                    }
+                    if (busyTrans.length > 0) {
+                        throw new ManageError('translation-busy', 409, `以下文献正在生成译文，请等待完成后再清空：${busyTrans.join('、')}`, { papers: busyTrans });
+                    }
+                    const r = clearTopic(dataDir, plan.topic);
+                    workspaceCache.delete(join(dataDir, plan.topic)); // 清掉指向已清空目录的工作区缓存
+                    json(res, 200, { ...r, detachedSessions: detached, archivedSessionsNote: true });
+                }
+                catch (err) {
+                    if (!libFail(res, err))
+                        throw err;
+                }
+            });
+            return;
+        }
+        // 公式索引：MinerU content_list 的 equation 块（LaTeX + bbox），供阅读器画热区/列表面板
+        if (sub === '/api/formulas' && req.method === 'GET') {
+            const ref = locate(url); // 只读路径，沿用 path/topic/name 三种定位
+            json(res, 200, await readFormulaIndex(ref));
             return;
         }
         // 新建伴读会话（会话N+1）。最新可见会话还是空白草稿时直接复用它——
@@ -519,7 +869,16 @@ export function registerRoutes(ctx, config) {
         // 启动后台翻译（幂等；force=true 为重翻：先删已有译文再启动）。端点：UI 里填的 > profile 的 translate
         if (sub === '/api/zh/generate' && req.method === 'POST') {
             const body = (await readBody(req));
-            const ref = resolvePaper(dataDir, body);
+            let ref;
+            try {
+                // 同样写盘（<文献>-zh.pdf 落在 PDF 旁边）→ 与 transcribe 同一套 path 边界约束
+                ref = locateForWrite(body);
+            }
+            catch (err) {
+                if (manageFail(res, err))
+                    return;
+                throw err;
+            }
             const { endpoint } = await resolveTranslateEndpoint(config.translate);
             const r = body.force
                 ? await restartTranslation(ref, dataDir, endpoint)
@@ -620,11 +979,168 @@ export function registerRoutes(ctx, config) {
             json(res, 200, { ok: true });
             return;
         }
+        // ── 嵌入模型端点配置（设置面板第三张端点卡片）─────────────────────────
+        // 与 translate/typesafe 完全同一套约定：GET 只回掩码 key；POST 预检通过才落盘；DELETE 回落。
+        if (sub === '/api/embed/config' && req.method === 'GET') {
+            const { cfg, source, enabled } = await resolveEmbedConfig(config.embed);
+            json(res, 200, {
+                baseUrl: cfg.baseUrl ?? '',
+                model: cfg.model ?? '',
+                hasApiKey: Boolean(cfg.apiKey),
+                apiKeyHint: cfg.apiKey ? maskEmbedApiKey(cfg.apiKey) : '',
+                enabled,
+                source,
+            });
+            return;
+        }
+        // POST：baseUrl/model/key 三项齐全是启用条件；key 留空 = 沿用已存的那把。
+        // 校验 → 预检（真打一发 /embeddings）→ 通了才落盘：嵌入失败是静默降级，填错很难察觉。
+        if (sub === '/api/embed/config' && req.method === 'POST') {
+            const body = (await readBody(req));
+            const baseUrl = body.baseUrl?.trim() ?? '';
+            const model = body.model?.trim() ?? '';
+            const prev = await readEmbedConfig();
+            const apiKey = body.apiKey?.trim() || prev?.apiKey || '';
+            if (baseUrl && !/^https?:\/\//i.test(baseUrl)) {
+                json(res, 400, { error: '端点 URL 需要以 http:// 或 https:// 开头' });
+                return;
+            }
+            if (!model) {
+                json(res, 400, { error: '嵌入模型名不能为空' });
+                return;
+            }
+            if (!apiKey) {
+                json(res, 400, { error: 'API Key 不能为空' });
+                return;
+            }
+            const test = await testEmbedEndpoint({ baseUrl, apiKey, model });
+            if (!test.ok) {
+                json(res, 400, { error: `连接测试失败：${test.detail ?? '未知原因'}` });
+                return;
+            }
+            await writeEmbedConfig({ baseUrl, apiKey, model });
+            json(res, 200, { ok: true });
+            return;
+        }
+        // DELETE：清掉文件，回落到 profile 的 embed / 环境变量
+        if (sub === '/api/embed/config' && req.method === 'DELETE') {
+            await clearEmbedConfig();
+            json(res, 200, { ok: true });
+            return;
+        }
+        // ── MinerU 解析后端配置（设置面板第三张卡片的读写口）────────────────────
+        // 与 translate/typesafe 同一套约定：GET 只回显掩码 key；POST 预检通过才落盘；DELETE 回落。
+        const MINERU_SOURCES = new Set(['auto', 'pdfjs', 'mineru-local', 'mineru-cloud']);
+        if (sub === '/api/mineru/config' && req.method === 'GET') {
+            const { config: cfg, source } = await resolveMineruConfig(config.mineru);
+            json(res, 200, {
+                mode: cfg.mode,
+                source,
+                local: {
+                    baseUrl: cfg.local.baseUrl,
+                    backend: cfg.local.backend,
+                    effort: cfg.local.effort,
+                    parseMethod: cfg.local.parseMethod,
+                    langList: cfg.local.langList,
+                    hasApiKey: Boolean(cfg.local.apiKey),
+                    apiKeyHint: cfg.local.apiKey ? maskApiKey(cfg.local.apiKey) : '',
+                },
+                cloud: {
+                    baseUrl: cfg.cloud.baseUrl,
+                    modelVersion: cfg.cloud.modelVersion,
+                    hasApiKey: Boolean(cfg.cloud.apiKey),
+                    apiKeyHint: cfg.cloud.apiKey ? maskApiKey(cfg.cloud.apiKey) : '',
+                },
+            });
+            return;
+        }
+        // POST：校验 → 预检 → 通了才落盘。key 留空沿用已存值（明文不回传，前端无法预填）。
+        if (sub === '/api/mineru/config' && req.method === 'POST') {
+            const body = (await readBody(req));
+            if (body.mode !== undefined && body.mode !== 'off' && body.mode !== 'local' && body.mode !== 'cloud') {
+                json(res, 400, { error: 'mode 只能是 off/local/cloud' });
+                return;
+            }
+            const prev = await resolveMineruConfig(config.mineru);
+            const next = mergeMineruBody(prev.config, body);
+            const test = await precheckMineruConfig(next);
+            if (!test.ok) {
+                json(res, 400, { error: test.detail ?? '连接测试失败' });
+                return;
+            }
+            await writeMineruConfig(next);
+            json(res, 200, { ok: true });
+            return;
+        }
+        // DELETE：清掉文件，回落到 profile 的 mineru / 环境变量
+        if (sub === '/api/mineru/config' && req.method === 'DELETE') {
+            await clearMineruConfig();
+            json(res, 200, { ok: true });
+            return;
+        }
+        // 连通性预检（不落盘）：设置面板「测试连接」按钮用；HTTP 恒 200，便于 UI 展示。
+        if (sub === '/api/mineru/test' && req.method === 'POST') {
+            const body = (await readBody(req));
+            const prev = await resolveMineruConfig(config.mineru);
+            const next = mergeMineruBody(prev.config, body);
+            const test = await precheckMineruConfig(next);
+            if (test.ok)
+                json(res, 200, { reachable: true, mode: next.mode });
+            else
+                json(res, 200, { reachable: false, mode: next.mode, error: test.detail ?? '连接测试失败' });
+            return;
+        }
+        // 健康探针：GET /api/mineru/health（可选 ?mode=local|cloud，默认按生效 mode）
+        if (sub === '/api/mineru/health' && req.method === 'GET') {
+            const modeParam = url.searchParams.get('mode');
+            const mode = modeParam === 'local' || modeParam === 'cloud' ? modeParam : (await resolveMineruConfig(config.mineru)).config.mode;
+            if (mode === 'off') {
+                json(res, 200, { reachable: false, mode: 'off', error: 'MinerU 未启用（mode=off）' });
+                return;
+            }
+            if (mode === 'local') {
+                const { config: cfg } = await resolveMineruConfig(config.mineru);
+                const t = await testMineruLocal(cfg.local.baseUrl);
+                if (!t.ok) {
+                    json(res, 200, { reachable: false, mode: 'local', error: t.detail ?? '不可达' });
+                    return;
+                }
+                const h = t.health ?? {};
+                json(res, 200, {
+                    reachable: true,
+                    mode: 'local',
+                    status: h['status'] ?? 'healthy',
+                    version: t.version ?? '',
+                    protocolVersion: h['protocol_version'] ?? null,
+                    queuedTasks: h['queued_tasks'] ?? 0,
+                    processingTasks: h['processing_tasks'] ?? 0,
+                });
+                return;
+            }
+            const { config: cfg } = await resolveMineruConfig(config.mineru);
+            const t = await testMineruCloud(cfg.cloud.baseUrl, cfg.cloud.apiKey);
+            if (t.ok)
+                json(res, 200, { reachable: true, mode: 'cloud' });
+            else
+                json(res, 200, { reachable: false, mode: 'cloud', error: t.detail ?? '不可达' });
+            return;
+        }
         if (sub === '/api/transcribe' && req.method === 'POST') {
             const body = (await readBody(req));
-            const ref = resolvePaper(dataDir, body);
-            const t = await transcribePaper(ref);
-            json(res, 200, { chars: t.chars, pageCount: t.pageCount, hasPageIndex: t.pages.length > 0, source: t.source });
+            let ref;
+            try {
+                // t3-O2：这条路由会**写盘**（<文献>.txt 等落在 PDF 旁边），所以 path 必须受与删除同级的边界约束
+                ref = locateForWrite(body);
+            }
+            catch (err) {
+                if (manageFail(res, err))
+                    return;
+                throw err;
+            }
+            const mineru = await resolveMineruConfig(config.mineru);
+            const source = MINERU_SOURCES.has(body.source ?? 'auto') ? body.source : 'auto';
+            const t = await transcribePaper(ref, { force: body.force === true, source, mineru });
+            json(res, 200, { chars: t.chars, pageCount: t.pageCount, hasPageIndex: t.pages.length > 0, source: t.source, producer: t.producer, backend: t.backend });
             return;
         }
         // 文献的伴读会话列表（多会话：会话1/会话2/…）
@@ -701,12 +1217,17 @@ export function registerRoutes(ctx, config) {
             }
             catch { /* 已存在则复用 */ }
             const hasQuote = typeof body.selectedText === 'string' && body.selectedText.trim() !== '';
+            // 公式引用（kind='equation'）：引用内容来自 MinerU 的 LaTeX，不是文本层乱码（契约 §1.3）；
+            // 非公式路径的文案必须与改造前逐字一致（回归项 A11）。
+            const isEquation = body.kind === 'equation';
             const where = hasQuote && body.page ? `（选中于第 ${body.page} 页）` : '';
             const lines = [
                 `[论文伴读] 文献：${ref.topic}/${ref.name}（同目录下，search_paper 可直接检索；回答注明页码）`,
             ];
             if (hasQuote) {
-                lines.push(`用户在阅读器里选中了一段文字${where}：`, `"""${body.selectedText.trim()}"""`);
+                lines.push(isEquation
+                    ? `用户在阅读器里引用了${body.page ? `第 ${body.page} 页的` : ''}一个公式（LaTeX 源，来自 MinerU 版面解析）：`
+                    : `用户在阅读器里选中了一段文字${where}：`, `"""${body.selectedText.trim()}"""`);
             }
             lines.push(`用户的问题：${body.question}`);
             const prompt = lines.join('\n');
@@ -736,10 +1257,25 @@ export function registerRoutes(ctx, config) {
                 noteOrigin(req.headers.host);
                 const url = new URL(req.url ?? '/', 'http://x');
                 dispatch(req, res, url).catch((err) => {
-                    if (!res.headersSent)
-                        json(res, 500, { error: readableError(err) });
-                    else
+                    if (res.headersSent) {
                         res.end();
+                        return;
+                    }
+                    // ① 域内可识别错误（ManageError）：用它的状态码/机器码/结构化字段
+                    if (isManageError(err)) {
+                        json(res, err.status, { error: err.message, code: err.code, ...err.extra });
+                        return;
+                    }
+                    // ② MinerU / 转录的**领域错误**：保留可读文案（既有测试明确断言这些文案含 `MinerU` 等关键词，
+                    //    不许为了让文案变得「绝对安全」而把它们一起打哑），但先剥掉任何绝对路径。
+                    // ③ 其余未知内部错误：不回显 err.message（原生 fs 错误常带绝对路径），只给通用文案。
+                    //    两种情况都带 machine-readable code:'internal'。
+                    const known = err instanceof MineruError || err instanceof ShortTextError || err instanceof ScannedPdfError;
+                    const raw = err instanceof Error ? err.message : String(err);
+                    // R7-F2：兜底文案承诺「详见服务端日志」，这里必须真的落一条日志。双重脱敏：
+                    // stripAbsPaths 剥绝对路径、sanitizeDetail 剥凭据（Bearer / sk-* / ?token=），绝不把路径或密钥写进日志。
+                    console.error('[dsh-paper-reader] route error:', sanitizeDetail(stripAbsPaths(raw)));
+                    json(res, 500, { error: known ? stripAbsPaths(raw) : '内部错误（详见服务端日志）', code: 'internal' });
                 });
             },
         });