@ggboy123/dsh-paper-reader 1.3.3 → 1.3.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GGboya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -11,6 +11,8 @@
 
 > **👉 普通用户直接看「安装 → 方式一」**：装 DeepSeek 官方桌面端，添加插件即可，不需要任何开发环境。本仓库面向的是想自己装插件、或想改代码的用户。
 
+> 💬 **QQ 交流群：1127244508** —— 安装/使用问题、功能建议、bug 反馈都欢迎来聊。
+
 功能迁移自本地独立产品 pdfqa（Go 实现的论文伴读工具）。原则：agent 循环 / 模型层 / 会话持久化全部交给 dsh 框架，插件只做「转录 + 检索 + 阅读器 UI」的薄壳组合。
 
 **安装后不改动官方界面** —— 侧栏底部多一行「📚 论文伴读」开关，点击才进入伴读模式（左侧变为文献库树），再点即还原官方工作区列表：
@@ -37,14 +39,14 @@
 
 ## 安装
 
-### 方式一：官方桌面端装插件（推荐）
+### 普通用户：桌面端装好即用（推荐）
+
+**两步**：装 DeepSeek 官方桌面端 → 里面直接装插件。
 
-**DeepSeek 官方桌面端**（[deepseek.com/download](https://www.deepseek.com/download/) 下载，即 DeepSeek Harness 桌面版）：
+1. 下载安装 [DeepSeek 官方桌面端](https://www.deepseek.com/download/)（即 DeepSeek Harness 桌面版），登录 DeepSeek 账号
+2. 侧栏 → **插件** → **添加插件**，输入 `@ggboy123/dsh-paper-reader@latest`，装完点进插件详情打开「启用」开关，**重启桌面端**
 
-1. 安装并启动，登录 DeepSeek 账号
-2. 侧栏 → **插件** → **添加插件**，输入 `@ggboy123/dsh-paper-reader@1.3.3` 安装
-3. 装完默认**停用**：点进插件详情，打开「启用」开关
-4. **重启桌面端**（热启用状态下打开论文的链路会静默失效，重启进开机组合才正常，实测）
+完成。侧栏底部点「📚 论文伴读」进入文献库，上传 PDF 开始用。
 
 完整流程演示（添加插件 → 启用 → 重启 → 打开论文直接提问）：
 
@@ -53,23 +55,28 @@
 > 已在官方桌面端 V0.2.0-rc.2（内置 dsh 0.2.0-rc.2，macOS arm64）实测通过：侧栏文献库、新建专题、上传 PDF、PDF 阅读器、原生对话伴读、历史/新建对话按钮全部可用。
 > 需要 ≥1.2.0：更早版本会被 0.2.x 运行时的 peer 兼容校验拒载（插件列表里显示异常）。
 
-> 曾经的 PaperReader 桌面版（基于社区 DSH Desktop 的预装打包）**已不再维护**——统一收敛到官方桌面端 + 插件的形式，老用户请迁移到本方式。
+> 想直接在客户端里逛插件市场（4000+ 插件、分类、评论、一键安装），可另装社区插件 [`dshmarket`](https://github.com/dsh-market/dsh-market)，本插件已在其目录中。
+
+**排坑（都是实测踩过的）**：
 
-### 方式二：命令行 dsh（开发者）
+- **升级后插件开关会回到停用**：侧栏 → 插件 → 打开「启用」→ 重启。症状有迷惑性——文献树还在但点论文没反应（浏览器侧缓存活着、宿主侧已下线），其实是没启用
+- **添加时务必带 `@latest`**：不带版本号对已装过的插件是 no-op（dsh 的插件管理器按首次记录的版本处理，不会追新）
+- 旧版 PaperReader 桌面版（社区 DSH Desktop 预装打包）**已停止维护**，请迁移到本方式
+
+### 开发者：命令行 dsh
 
 ```bash
-dsh plugin --profile web add @ggboy123/dsh-paper-reader
+dsh plugin --profile web add @ggboy123/dsh-paper-reader@latest
 ```
 
 > npm 包名走 `@ggboy123` 作用域：裸名 `dsh-paper-reader` 已被另一个插件占用（那是「输入文献、吐精读报告」的一次性分析工具，与本插件的「阅读器 + 会话伴读」定位不同）。
 > 不要用 `github:GGboya/dsh-paper-reader` 安装 —— dist 不入库，git 安装会导致 profile 起不来（构建产物只随 npm 包分发）。
 
-### 升级
-
-**已装过的用户升级必须带显式版本号**——不带版本的 `add` 对已存在的依赖是 no-op（pnpm 按首次安装时记录的版本范围解析，不会追新）：
+**升级**：用 `@latest`（或显式版本号）——不带任何版本/tag 的 `add` 对已装过的依赖是 no-op（实测）：
 
 ```bash
-dsh plugin --profile web add @ggboy123/dsh-paper-reader@1.3.3
+dsh plugin --profile web add @ggboy123/dsh-paper-reader@latest   # 永远装最新
+# dsh plugin --profile web add @ggboy123/dsh-paper-reader@1.3.4  # 或钉住具体版本
 # 重启 dsh web 生效；浏览器 Cmd+Shift+R 强刷，避免旧阅读器页面缓存
 ```
 
@@ -79,7 +86,7 @@ dsh plugin --profile web add @ggboy123/dsh-paper-reader@1.3.3
 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`（只豁免本插件，不动全局策略）。
+> pnpm 若开了供应链策略 `minimumReleaseAge`（发布 N 小时内的新包拒装，桌面端默认开）：要么等过窗口期，要么在 `~/.dsh/profiles/web/.npmrc` 加一行 `minimum-release-age-exclude[]=@ggboy123/dsh-paper-reader`（只豁免本插件，不动全局策略）。桌面端的豁免清单在 `~/.dsh/profiles/desktop/pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude`。
 
 ### 参与开发（本地调试）
 

package/dist/host.js

@@ -4,7 +4,7 @@ import { createReadStream, readFileSync } 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, } from "./library.js";
+import { deletePaper, deleteTopic, listPapers, listTopics, paperRefFor, renamePaper, renameTopic, resolveDataDir, resolvePaper, resolveUploadTopic, validateEntryBoundary, validateEntryName, } from "./library.js";
 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";
@@ -16,12 +16,32 @@ function json(res, status, body) {
     res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'content-length': buf.length });
     res.end(buf);
 }
+/**
+ * 错误文案判别：带 `.code` 的 Node errno 系统错误 → 固定中文文案（不回显原始错误，
+ * 避免把 dataDir/目标绝对路径带进响应体）；不带 `.code` 的是我们自己抛的中文业务 Error
+ * （专题不存在/已存在同名/名字不能包含… 等）→ 保留 `e.message`，用户仍能定位问题。
+ */
+function readableError(err) {
+    const code = err?.code;
+    if (typeof code === 'string' && code)
+        return '系统错误，请稍后重试';
+    return err instanceof Error ? err.message : String(err);
+}
 async function readBody(req) {
     const chunks = [];
     for await (const c of req)
         chunks.push(c);
     const raw = Buffer.concat(chunks).toString('utf8');
-    return raw ? JSON.parse(raw) : {};
+    if (!raw)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {}; // 畸形 JSON 与整包 null/非对象同待遇：路由据此给可读 400（不再 500）
+    }
+    return parsed !== null && typeof parsed === 'object' ? parsed : {};
 }
 /** header 元数据解码：客户端 encodeURIComponent 过（HTTP header 值不允许非 Latin-1，如中文文件名）；非字符串/未编码原样返回。 */
 function decodeHdr(v) {
@@ -122,7 +142,7 @@ export function registerRoutes(ctx, config) {
             return workspace.workspaceId;
         }
         catch (err) {
-            console.warn('[dsh-paper-reader] workspace 注册失败(回退 cwd 模式):', err);
+            console.warn('[dsh-paper-reader] workspace 注册失败(回退 cwd 模式):', readableError(err));
             return undefined;
         }
     };
@@ -182,14 +202,20 @@ export function registerRoutes(ctx, config) {
             json(res, 200, { dataDir, topics: listTopics(dataDir), papers });
             return;
         }
-        // 新建专题（目录）
+        // 新建专题（目录）。校验与 rename 的 to 侧一致（validateEntryName：边界 + 命名规范），
+        // 保证「能创建的必然能删除/改名」（R12：创建/删除对称）。
         if (sub === '/api/library/topic' && req.method === 'POST') {
             const body = (await readBody(req));
-            const name = body.name?.trim();
-            if (!name || /[/\\]|\.\./.test(name)) {
-                json(res, 400, { error: '专题名不能为空，且不能包含 / \\ ..' });
+            if (typeof body.name !== 'string' || !body.name.trim()) {
+                json(res, 400, { error: '专题名不能为空' });
+                return;
+            }
+            const err = validateEntryName(body.name);
+            if (err) {
+                json(res, 400, { error: err });
                 return;
             }
+            const name = body.name.trim();
             await mkdir(join(dataDir, name), { recursive: true });
             json(res, 200, { ok: true, topic: name });
             return;
@@ -203,11 +229,24 @@ export function registerRoutes(ctx, config) {
                 json(res, 400, { error: '缺少 x-dpr-topic / x-dpr-name 头' });
                 return;
             }
+            // 词法层：与其余 CRUD 同强度（../ / \ 隐藏名 控制字符 超长 空串）
+            const errName = validateEntryName(topic);
+            if (errName) {
+                json(res, 400, { error: errName });
+                return;
+            }
             if (!filename.toLowerCase().endsWith('.pdf')) {
                 json(res, 400, { error: '只支持 PDF 文件' });
                 return;
             }
             const safeName = filename.replaceAll('/', '_').replaceAll('\\', '_');
+            // 文件名也做边界类校验（空/分隔符/../NUL），与删除侧对称：upload 能创建的必须能被删
+            const stem = safeName.slice(0, -4); // 去掉 .pdf
+            const errStem = validateEntryBoundary(stem);
+            if (errStem) {
+                json(res, 400, { error: errStem });
+                return;
+            }
             const chunks = [];
             for await (const c of req)
                 chunks.push(c);
@@ -216,10 +255,24 @@ export function registerRoutes(ctx, config) {
                 json(res, 400, { error: '文件内容为空' });
                 return;
             }
-            const dir = join(dataDir, topic.trim());
-            await mkdir(dir, { recursive: true });
-            const target = join(dir, safeName);
-            await writeFile(target, buf);
+            // realpath 子路径层：拒绝「data/<topic> → 库外」符号链接逃逸写（与 CRUD 同一套 primitive）
+            let dir;
+            try {
+                dir = resolveUploadTopic(dataDir, topic.trim());
+            }
+            catch (err) {
+                json(res, 400, { error: readableError(err) });
+                return;
+            }
+            try {
+                await mkdir(dir, { recursive: true });
+                const target = join(dir, safeName);
+                await writeFile(target, buf);
+            }
+            catch (err) {
+                json(res, 400, { error: readableError(err) });
+                return;
+            }
             json(res, 200, { ok: true, topic: topic.trim(), name: safeName.slice(0, -4), bytes: buf.length });
             return;
         }
@@ -236,15 +289,37 @@ export function registerRoutes(ctx, config) {
                 json(res2, 409, { error: '文件被占用（可能正在阅读器或其他程序中打开），关闭后重试' });
             }
             else {
-                json(res2, 400, { error: e instanceof Error ? e.message : String(err) });
+                json(res2, 400, { error: readableError(err) });
             }
         };
+        /** 非法/越界名字 → 400 可读文案（词法层；realpath 子路径层在 library primitive 内兜底）。
+         *  放在 busyPapersInTopic / resolvePaper 之前，越界输入不会碰任何文件系统。返回 true 表示已响应。 */
+        const badEntry = (res, raw) => {
+            const err = typeof raw === 'string' ? validateEntryName(raw) : '名字不能为空';
+            if (!err)
+                return false;
+            json(res, 400, { error: err });
+            return true;
+        };
+        /** 删除/改名-from 用：只做边界类校验（安全），不做命名规范类（长度/前导点）。
+         *  删除是对已存在文件的操作——upload 能创建的名字（前导点、超长、\x01 等）必须能删。 */
+        const badEntryBoundary = (res, raw) => {
+            const err = typeof raw === 'string' ? validateEntryBoundary(raw) : '名字不能为空';
+            if (!err)
+                return false;
+            json(res, 400, { error: err });
+            return true;
+        };
         if (sub === '/api/library/rename-topic' && req.method === 'POST') {
             const body = (await readBody(req));
-            if (!body.topic?.trim()) {
+            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('、')}` });
@@ -263,10 +338,12 @@ export function registerRoutes(ctx, config) {
         }
         if (sub === '/api/library/delete-topic' && req.method === 'POST') {
             const body = (await readBody(req));
-            if (!body.topic?.trim()) {
+            if (typeof body.topic !== 'string' || !body.topic.trim()) {
                 json(res, 400, { error: '缺少 topic' });
                 return;
             }
+            if (badEntry(res, body.topic))
+                return;
             const busy = busyPapersInTopic(body.topic.trim());
             if (busy.length) {
                 json(res, 409, { error: `以下文献正在翻译，稍后再试：${busy.join('、')}` });
@@ -284,10 +361,16 @@ export function registerRoutes(ctx, config) {
         }
         if (sub === '/api/library/rename-paper' && req.method === 'POST') {
             const body = (await readBody(req));
-            if (!body.topic?.trim() || !body.name?.trim()) {
+            if (typeof body.topic !== 'string' || !body.topic.trim() || typeof body.name !== 'string' || !body.name.trim()) {
                 json(res, 400, { error: '缺少 topic / name' });
                 return;
             }
+            if (badEntry(res, body.topic))
+                return;
+            if (badEntryBoundary(res, body.name))
+                return;
+            if (badEntry(res, body.to ?? ''))
+                return;
             let ref;
             try {
                 ref = resolvePaper(dataDir, { topic: body.topic.trim(), name: body.name.trim() });
@@ -313,10 +396,14 @@ export function registerRoutes(ctx, config) {
         }
         if (sub === '/api/library/delete-paper' && req.method === 'POST') {
             const body = (await readBody(req));
-            if (!body.topic?.trim() || !body.name?.trim()) {
+            if (typeof body.topic !== 'string' || !body.topic.trim() || typeof body.name !== 'string' || !body.name.trim()) {
                 json(res, 400, { error: '缺少 topic / name' });
                 return;
             }
+            if (badEntry(res, body.topic))
+                return;
+            if (badEntryBoundary(res, body.name))
+                return;
             let ref;
             try {
                 ref = resolvePaper(dataDir, { topic: body.topic.trim(), name: body.name.trim() });
@@ -650,7 +737,7 @@ export function registerRoutes(ctx, config) {
                 const url = new URL(req.url ?? '/', 'http://x');
                 dispatch(req, res, url).catch((err) => {
                     if (!res.headersSent)
-                        json(res, 500, { error: String(err instanceof Error ? err.message : err) });
+                        json(res, 500, { error: readableError(err) });
                     else
                         res.end();
                 });

package/dist/library.js

@@ -6,8 +6,8 @@
 //   <dataDir>/<专题>/<文献>.pages.json   页码偏移表（转录时生成，检索映射页码用）
 // pdf2zh 的产物（-en / -zh / -dual）不算用户文献。
 // （问答不落盘存档——会话持久化交给 dsh 自己；pdfqa 时代的 -qa/ 目录不再读写。）
-import { readdirSync, existsSync, mkdirSync, statSync, renameSync, rmSync } from 'node:fs';
-import { join, resolve, extname, basename } from 'node:path';
+import { readdirSync, existsSync, mkdirSync, statSync, renameSync, rmSync, realpathSync, lstatSync } from 'node:fs';
+import { join, resolve, extname, basename, sep } from 'node:path';
 import { homedir } from 'node:os';
 const PDF2ZH_SUFFIXES = ['-en', '-zh', '-dual'];
 /** 判定是否为用户文献：排除 pdf2zh 的中间/产出文件。 */
@@ -111,10 +111,103 @@ export function validateEntryName(raw) {
         return '名字过长（最多 120 个字符）';
     if (/[\\/]|\.\./.test(name))
         return '名字不能包含 / \\ 或 ..';
+    if (/[\u0000-\u001f\u007f]/.test(name))
+        return '名字不能包含控制字符';
     if (name.startsWith('.'))
         return '名字不能以 . 开头';
     return null;
 }
+/**
+ * 边界类名字校验（删除/改名-from 用）：只挡安全边界——空、分隔符/..、NUL。
+ * 与 validateEntryName 的分工：命名规范类（长度上限、前导点、非 NUL 控制字符）只在创建/改名时
+ * 强制（那是用户在起名字）；删除是对已存在文件的操作——upload 能创建的名字（前导点、超长、
+ * \x01 等控制字符）必须能删，否则会成为无法清理的孤儿。NUL 必须挡：它会让 Node fs 抛
+ * ERR_INVALID_ARG_VALUE 并把绝对路径带进错误文案（错误回显卫生）。
+ */
+export function validateEntryBoundary(raw) {
+    const name = raw.trim();
+    if (!name)
+        return '名字不能为空';
+    if (/[\\/]|\.\./.test(name))
+        return '名字不能包含 / \\ 或 ..';
+    if (name.includes('\u0000'))
+        return '名字不能包含控制字符';
+    return null;
+}
+// ================= 路径穿越防护（词法 + realpath 子路径双层） =================
+// 这些 CRUD 原语以前只对 `to` 做过校验，`topic`/`name`/`from` 直接 `join(dataDir, x)`：
+// `../sentinel` 这类输入会让 rmSync/renameSync 作用于 dataDir 之外的目录（可递归强制删除）。
+// 这里补两层结构性防护：① 词法层（validateEntryName 拒绝 / \ .. 与隐藏名）；② realpath
+// 层（目标目录的 real 路径必须落在 dataDir 的 real 路径之内，挡住 `..` 之外的符号链接逃逸）。
+/** dataDir 的 real 绝对路径（resolve + realpath，去符号链接与 `..`）。目录缺失时给无路径文案。 */
+function realDataDir(dataDir) {
+    const abs = resolve(dataDir);
+    if (!existsSync(abs))
+        throw new Error('文献库数据目录不存在');
+    return realpathSync(abs);
+}
+/** target 必须落在 root 之内（严格子路径，不含 root 本身），否则视为越界。 */
+function assertInside(root, target) {
+    const r = root.endsWith(sep) ? root : root + sep;
+    if (target !== root && !target.startsWith(r))
+        throw new Error('路径越界，已拒绝');
+}
+/**
+ * 安全解析专题目录：词法校验 + realpath 严格子路径包含。
+ * 返回可直接 rename/delete 的目录路径（join 后的路径，非 realpath——顶层符号链接对
+ * rmSync/renameSync 只操作链接本身，不跟随，语义保持不变）。任何调用方（不只路由）
+ * 传入越界 topic 都会被拒：`..`、绝对路径、`a/../b`、指向库外的符号链接等。
+ */
+function resolveSafeTopic(dataDir, topic) {
+    const err = validateEntryName(topic);
+    if (err)
+        throw new Error(err);
+    const root = realDataDir(dataDir);
+    const dir = join(root, topic.trim());
+    if (!existsSync(dir))
+        throw new Error(`专题不存在: ${topic.trim()}`);
+    let real;
+    try {
+        real = realpathSync(dir);
+    }
+    catch {
+        throw new Error(`专题不存在: ${topic.trim()}`);
+    }
+    assertInside(root, real);
+    return dir;
+}
+/**
+ * 安全解析「待创建」的专题目录（upload 用）：词法校验 + realpath 严格子路径包含。
+ * 与 resolveSafeTopic 不同：专题可以尚不存在（upload 会 mkdir 创建），但已存在的条目
+ * （目录/文件/符号链接）仍必须 realpath 落在 dataDir 之内——挡住「data/evil → 库外」这类
+ * 符号链接逃逸写。返回可直接 mkdir/writeFile 的目录路径（join 后的路径，非 realpath）。
+ */
+export function resolveUploadTopic(dataDir, topic) {
+    const err = validateEntryName(topic);
+    if (err)
+        throw new Error(err);
+    const root = realDataDir(dataDir);
+    const dir = join(root, topic.trim());
+    let exists = false;
+    try {
+        lstatSync(dir); // lstat 不跟随符号链接：悬空链接也算「已存在」，交给 realpath 兜底
+        exists = true;
+    }
+    catch {
+        exists = false;
+    }
+    if (!exists)
+        return dir; // 尚不存在：mkdir(recursive) 会创建真实目录（词法层已保证无分隔符/../隐藏名）
+    let real;
+    try {
+        real = realpathSync(dir);
+    }
+    catch {
+        throw new Error(`专题不存在: ${topic.trim()}`);
+    }
+    assertInside(root, real);
+    return dir;
+}
 /** 构造文献引用（不做存在性校验；给只按路径判定的调用方用，如翻译 busy 检查）。 */
 export function paperRefFor(dataDir, topic, name) {
     const pdfPath = join(dataDir, topic, name + '.pdf');
@@ -129,53 +222,59 @@ export function derivedFilesFor(pdfPath) {
     const stem = pdfPath.slice(0, -'.pdf'.length);
     return PAPER_SIDECARS.map((s) => stem + s);
 }
-/** 改名专题（目录 rename）。from 不存在 / to 已存在 / 名字非法 → throw 中文 Error。
+/** 改名专题（目录 rename）。from/to 非法（含越界）→ throw；from 不存在 / to 已存在 → throw 中文 Error。
  *  已知局限：大小写不敏感文件系统（macOS/Windows）上纯大小写改名会被「目标已存在」
  *  拒绝——不做临时名两跳绕过，保持简单。 */
 export function renameTopic(dataDir, from, to) {
     const err = validateEntryName(to);
     if (err)
         throw new Error(err);
-    if (to.trim() === from)
+    if (to.trim() === from.trim())
         return;
-    const src = join(dataDir, from);
-    if (!existsSync(src))
-        throw new Error(`专题不存在: ${from}`);
-    const dst = join(dataDir, to.trim());
+    const src = resolveSafeTopic(dataDir, from); // 词法 + realpath 子路径校验 from
+    const dst = join(realDataDir(dataDir), to.trim());
     if (existsSync(dst))
         throw new Error(`已存在同名专题: ${to.trim()}`);
     renameSync(src, dst);
 }
 /** 改名文献：连带派生文件（转录/页码索引/译文/学习档案）逐个跟随，不存在的跳过。
- *  返回实际改名的文件名清单（含 .pdf 本体）。 */
+ *  返回实际改名的文件名清单（含 .pdf 本体）。topic/from/to 非法（含越界）→ throw。 */
 export function renamePaper(dataDir, topic, from, to) {
-    const err = validateEntryName(to);
-    if (err)
-        throw new Error(err);
-    to = to.trim();
-    if (to === from)
+    const errTo = validateEntryName(to);
+    if (errTo)
+        throw new Error(errTo);
+    const errFrom = validateEntryBoundary(from);
+    if (errFrom)
+        throw new Error(errFrom);
+    const toTrim = to.trim();
+    const fromTrim = from.trim();
+    if (toTrim === fromTrim)
         return [];
-    const dir = join(dataDir, topic);
-    if (!existsSync(join(dir, from + '.pdf')))
-        throw new Error(`文献不存在: ${topic}/${from}`);
-    if (existsSync(join(dir, to + '.pdf')))
-        throw new Error(`已存在同名文献: ${to}`);
+    const dir = resolveSafeTopic(dataDir, topic); // 词法 + realpath 子路径校验 topic
+    if (!existsSync(join(dir, fromTrim + '.pdf')))
+        throw new Error(`文献不存在: ${topic.trim()}/${fromTrim}`);
+    if (existsSync(join(dir, toTrim + '.pdf')))
+        throw new Error(`已存在同名文献: ${toTrim}`);
     const renamed = [];
     for (const suf of PAPER_SIDECARS) {
-        const src = join(dir, from + suf);
+        const src = join(dir, fromTrim + suf);
         if (!existsSync(src))
             continue;
-        renameSync(src, join(dir, to + suf));
-        renamed.push(from + suf);
+        renameSync(src, join(dir, toTrim + suf));
+        renamed.push(fromTrim + suf);
     }
     return renamed;
 }
-/** 删除文献及其全部派生文件。返回实际删除的文件名清单。 */
+/** 删除文献及其全部派生文件。返回实际删除的文件名清单。topic/name 非法（含越界）→ throw。 */
 export function deletePaper(dataDir, topic, name) {
-    const dir = join(dataDir, topic);
-    const pdfPath = join(dir, name + '.pdf');
+    const errName = validateEntryBoundary(name);
+    if (errName)
+        throw new Error(errName);
+    const dir = resolveSafeTopic(dataDir, topic); // 词法 + realpath 子路径校验 topic
+    const nameTrim = name.trim();
+    const pdfPath = join(dir, nameTrim + '.pdf');
     if (!existsSync(pdfPath))
-        throw new Error(`文献不存在: ${topic}/${name}`);
+        throw new Error(`文献不存在: ${topic.trim()}/${nameTrim}`);
     const deleted = [];
     for (const f of derivedFilesFor(pdfPath)) {
         if (!existsSync(f))
@@ -185,10 +284,8 @@ export function deletePaper(dataDir, topic, name) {
     }
     return deleted;
 }
-/** 删除专题（递归，含其下全部文献与派生文件）。 */
+/** 删除专题（递归，含其下全部文献与派生文件）。topic 非法（含越界）→ throw（不触碰库外）。 */
 export function deleteTopic(dataDir, topic) {
-    const dir = join(dataDir, topic);
-    if (!existsSync(dir))
-        throw new Error(`专题不存在: ${topic}`);
+    const dir = resolveSafeTopic(dataDir, topic);
     rmSync(dir, { recursive: true, force: true });
 }

package/lib/client.js

@@ -631,12 +631,17 @@ window.__ModuleLoader__.load({
 
       // 激活会话：客户端会话目录（catalog）感知到新会话有时延，轮询到「已列出」再
       // openSession，并以 current === sessionId 为成功标准（否则原生对话区不切换）。
+      // ⚠️ 仅凭 catalog 的 current 判断不够（用户实测「点插件页后再点论文没反应」）：
+      // 插件页等非对话视图占着主视图时，目录里 cur 仍是目标会话，但视图并不在对话——
+      // 提前返回会让主视图永远停在插件页、PDF 锚点不回来。补一个可见事实作成功标准：
+      // PDF 页签锚点回来（对话视图已恢复）；没回来就持续 openSession 往回推。
       const activateSession = useCallback((sessionId) => {
         let tries = 20
         const tick = () => {
           try {
             const snap = uiWorkspace.sessions?.list?.getSnapshot?.()
-            if (currentSessionOf(snap) === sessionId) return // 已是当前会话
+            const anchorBack = !!document.querySelector('[data-dsh-surface="rightbar-tab-anchor"]')
+            if (currentSessionOf(snap) === sessionId && anchorBack) return // 会话已切 + 视图已回
             const listed = !!(snap && (snap.byId?.[sessionId] || snap.ids?.includes(sessionId)))
             if (listed) uiWorkspace.openSession(sessionId)
             if (--tries > 0) setTimeout(tick, 300)
@@ -660,7 +665,14 @@ window.__ModuleLoader__.load({
             if (listed) {
               // 对目录里早已存在的会话这步能真正预开（store 已 adopt）；
               // 对刚创建的会话恒 no-op —— 靠切换护栏兜底（见 beginSwitchGuard）。
-              sidebarRight.openTabIn(sessionId, 'dpr-reader', { revealIfOpened: true })
+              // ⚠️ openTabIn 失败不能堵住 done()（用户实测「点插件页后再点论文没反应」）：
+              // 插件页等非对话视图占着主视图时，目标会话在右栏没有 seat，openTabIn 每次都抛——
+              // 若当可重试错误轮询，done() 永远不执行 → activateSession（openSession 切回对话
+              // 视图）不被调用 → 主视图停在插件页、PDF 锚点永不回来。预开只是优化，失败就
+              // 直接放行，切换护栏 + openPdfTab 轮询兜底。
+              try {
+                sidebarRight.openTabIn(sessionId, 'dpr-reader', { revealIfOpened: true })
+              } catch { /* 无 seat（插件页/会话未收编）——切换后由 openPdfTab 补开 */ }
               done?.()
               return
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggboy123/dsh-paper-reader",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "description": "DeepSeek Harness 插件：论文伴读工作台 — PDF 转录 / 检索 / 原生对话伴读 + 内置阅读器页面。",
   "license": "MIT",
   "type": "module",
@@ -45,6 +45,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "pretest": "npm run build",
+    "test": "node --test \"test/*.test.mjs\"",
     "smoke:engine": "node scripts/engine-smoke.mjs",
     "prepublishOnly": "tsc -p tsconfig.json"
   },