@ggboy123/dsh-paper-reader 0.1.0

package/README.md

@@ -0,0 +1,73 @@
+# dsh-paper-reader
+
+[DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 插件：论文伴读工作台 —— PDF 转录 / 检索 + 原生对话伴读 + 内置阅读器。
+
+功能迁移自本地独立产品 pdfqa（Go 实现的论文伴读工具）。原则：agent 循环 / 模型层 / 会话持久化全部交给 dsh 框架，插件只做「转录 + 检索 + 阅读器 UI」的薄壳组合。
+
+## 功能
+
+- 📚 **侧栏文献库树**：接管工作区侧栏，专题 → 论文两级；支持新建专题、上传 PDF
+- 💬 **原生对话伴读**：点击论文即在右侧打开它的 dsh 原生会话（流式 / 工具卡 / 用量条全是官方 UI）；默认只呈现当前对话，对话列头部的 🕐 下拉回看**历史对话**（真实标题+日期，点哪条进哪条），＋ 新建对话
+- 🔗 **会话绑定论文**：会话 id 编码文献身份，工具调用自动定位当前论文——直接在输入框提问无需点名论文，回答必带页码
+- 🤖 **专用 agent preset「论文伴读」**：paper 会话自动使用专用 preset —— 像老师一样带读：制定分步阅读计划（每步带页码和思考题）→ 逐节指导、点评 → 出题检验、逐题批改 → 成绩与薄弱点记入 `<文献>.study.json` 学习档案，跨会话累积；快速问答（选中即问）则直接回答，不上课
+- 📖 **PDF 阅读器居中**：中间是论文（PDF.js 缩放 / Retina 高清 / 文本层选择 / 适宽模式），最右是该论文的原生对话 —— 视觉换位实现，列宽拖拽/折叠仍是 dsh 原生行为，关掉 PDF 页签即还原官方布局
+- 💬 **选中即问**：阅读器里选中文字 → 弹出提问框 → 注入当前会话，原生对话区实时回答
+- 📍 **引用定位**：回答里的「第 N 页」可点击，平滑跳回 PDF 对应页并闪烁
+- 🀄 **中英切换**：顶栏「中」按钮原文 ↔ 纯中文切换；无译文时一键后台生成（babeldoc），生成需配置 `translate` 端点
+- 🔍 **PDF 转录 + 检索**：本地提取（python3 + PyMuPDF），页眉页脚剔除 / 连字 / 断词愈合 / 段落重排，产出页码偏移表；兼容 pdfqa 的 `data/` 缓存布局（旧缓存读取时自动补建页码索引）
+
+## 安装（待发布）
+
+```bash
+dsh plugin --profile web add github:GGboya/dsh-paper-reader
+```
+
+本地开发：
+
+```bash
+pnpm install && pnpm run build
+dsh plugin --profile web add ./dsh-paper-reader   # 从父目录执行
+dsh --profile web                                  # 侧栏变为文献库树
+```
+
+文献库目录默认 `~/.dsh-paper-reader/data`；在 profile 的 `cordis.patch.yml` 里可改：
+
+```yaml
+- id: dsh-paper-reader
+  config:
+    dataDir: /path/to/pdfqa/data   # 直接指向 pdfqa 文献库即可复用全部缓存
+    # translate:                    # 可选：生成中文版（babeldoc）用的 OpenAI 兼容端点。
+    #   baseUrl: https://api.deepseek.com/v1   # 一般不用写在这里——阅读器里点「中」
+    #   apiKey: sk-...                          # 或右上角 ⚙ 可直接填，存到
+    #   model: deepseek-chat                    # ~/.dsh/.dsh-paper-reader/translate.json（0600）
+```
+
+> 中文版端点：**优先在阅读器 UI 里填**（点「中」→ 没配会自动弹表单，或点 ⚙）——填完会先测连接再落盘，不用重启。
+> 上面的 `translate` 配置退为**部署方默认值**，仅当 UI 未配置时生效。babeldoc 只支持 OpenAI 协议端点，
+> Anthropic 协议的端点（如 `api.kimi.com/coding/`）不能直连。
+
+⚠️ 本插件按「论文伴读专用 profile」设计：侧栏的 `sidebar.workspaces` 被文献库树接管，官方工作区/会话列表在该 profile 侧栏不可见（从 `cordis.patch.yml` 删掉本插件即恢复）。
+
+## 架构
+
+```
+src/
+  index.ts      Cordis 壳：inject tools；webServer 等服务就绪后挂路由
+  tools.ts      5 个 agent 工具：list_papers / transcribe_pdf / search_paper / study_progress / study_update
+  host.ts       webServer 路由（/paper-reader/*），connection.requestRejection 鉴权；
+                sessionController.create/prompt（agentPreset=paper-reader）+ follow SSE 桥
+  library.ts    纯函数：文献库目录约定与解析
+  transcribe.ts 纯函数：PyMuPDF 提取 + 页码偏移表（视觉兜底后置）
+  search.ts     纯函数：分段 + 关键词打分 + 页码映射
+  study.ts      纯函数：学习档案（计划 + 检验成绩）读写
+  translate.ts  纯函数：babeldoc 调用（中文/中英对照 PDF 生成）
+  translate-config.ts 纯函数：翻译端点配置读写（$DSH_HOME 下 0600）+ 保存前连接预检
+  preset.ts     纯函数：自带 agent preset 安装到 $DSH_HOME/.agent-presets/
+presets/paper-reader/  「论文伴读」agent preset（persona 完整提示词 + compaction）
+reader/index.html      阅读器页面（pdf.js，独立于 React 宿主，iframe 承载）
+lib/client.js          浏览器半边：文献库树(sidebar.workspaces 接管) + PDF 页签 + 主面板
+```
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# dsh-paper-reader bundle layer — applied when a profile lists this bundle.
+# `name` is a PACKAGE NAME (resolved through the profile's node_modules or the
+# installation fallback $DSH_HOME/profiles/node_modules), NOT a relative path.
+# id 是配置定位用的短 slug（README 里 - id: dsh-paper-reader 的示例靠它命中），
+# 与 npm 包名解耦 —— npm 上 dsh-paper-reader 已被占用，包名走 @ggboy123 作用域。
+# YAML 里 @ 开头的字符串必须加引号。
+- insert:
+    - id: dsh-paper-reader
+      name: '@ggboy123/dsh-paper-reader'

package/dist/host.js

@@ -0,0 +1,451 @@
+// host.ts — webServer 路由：阅读器页面 + PDF 文件 + 转录数据接口 + 选中即问。
+// 壳层代码：只做 HTTP ↔ 纯函数核心(library/transcribe)的转接。
+import { createReadStream } from 'node:fs';
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { listPapers, listTopics, resolveDataDir, resolvePaper } from "./library.js";
+import { readTranscript, transcribePaper } from "./transcribe.js";
+import { pdfVariantPath, startTranslation, zhStatus } from "./translate.js";
+import { clearTranslateConfig, maskApiKey, readTranslateConfig, resolveTranslateEndpoint, testTranslateEndpoint, writeTranslateConfig, } from "./translate-config.js";
+import { installPaperPreset, PAPER_PRESET_ID } from "./preset.js";
+function json(res, status, body) {
+    const buf = Buffer.from(JSON.stringify(body), 'utf8');
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'content-length': buf.length });
+    res.end(buf);
+}
+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) : {};
+}
+/** header 元数据解码：客户端 encodeURIComponent 过（HTTP header 值不允许非 Latin-1，如中文文件名）；非字符串/未编码原样返回。 */
+function decodeHdr(v) {
+    if (typeof v !== 'string')
+        return v;
+    try {
+        return decodeURIComponent(v);
+    }
+    catch {
+        return v;
+    }
+}
+export function registerRoutes(ctx, config) {
+    const ws = ctx.webServer;
+    const connection = ctx.connection;
+    const sessionController = ctx.sessionController;
+    const workspaceController = ctx.workspaceController;
+    const workspaceRegistry = ctx.workspaceRegistry;
+    const dataDir = resolveDataDir(config.dataDir);
+    // dist/host.js → 包根/reader/index.html
+    const readerHtml = new URL('../reader/index.html', import.meta.url);
+    // 自带「论文伴读」agent preset → $DSH_HOME/.agent-presets/（实时扫描，免重启）；
+    // 失败（旧版 dsh/无权限）则回退默认 preset，功能不受影响。
+    const presetDir = installPaperPreset(new URL('../', import.meta.url));
+    const locate = (url) => {
+        const path = url.searchParams.get('path') ?? undefined;
+        const topic = url.searchParams.get('topic') ?? undefined;
+        const name = url.searchParams.get('name') ?? undefined;
+        const args = {};
+        if (path)
+            args.path = path;
+        if (topic)
+            args.topic = topic;
+        if (name)
+            args.name = name;
+        return resolvePaper(dataDir, args);
+    };
+    /** 每篇文献的伴读会话 id（确定性，重启/刷新后可续）；n 支持同文献多会话（会话1/2/…）。 */
+    const sessionPrefixFor = (ref) => `dpr-${Buffer.from(`${ref.topic}/${ref.name}`).toString('base64url')}`;
+    /** 扫描某文献的全部伴读会话（不过滤）：按 dsh 会话列表过滤 id 前缀；兼容 v1 无后缀旧会话=会话1。
+     *  n 的分配必须基于这份全量扫描（含归档/空白）——用过滤后的列表算 maxN 会跟
+     *  磁盘上已存在（可能还被别的进程 flock 着）的会话目录撞号，create 直接失败（实测）。 */
+    const scanPaperSessions = async (ref) => {
+        const prefix = sessionPrefixFor(ref);
+        const all = await sessionController.list({}, AbortSignal.timeout(15_000));
+        const out = [];
+        for (const s of all.items) {
+            if (s.sessionId === prefix) {
+                out.push({ n: 1, sessionId: s.sessionId, running: s.running, blank: s.blank, updatedAt: s.updatedAt }); // 旧格式 → 会话1
+                continue;
+            }
+            if (s.sessionId.startsWith(prefix + '-')) {
+                const n = +s.sessionId.slice(prefix.length + 1) || 0;
+                if (n > 0)
+                    out.push({ n, sessionId: s.sessionId, running: s.running, blank: s.blank, updatedAt: s.updatedAt });
+            }
+        }
+        // 同 n 去重（旧格式与新格式并存时旧格式让位）；按 n 排序
+        const byN = new Map();
+        for (const s of out)
+            byN.set(s.n, s);
+        return [...byN.values()].sort((a, b) => a.n - b.n);
+    };
+    /** 列表视图：过滤归档集；空白会话（从未提问）只保留最新一个——更早的空会话是被遗弃的
+     *  「新建对话」，顺手真归档（官方语义：日志保留、所有列表隐藏），不只是从树上消失。 */
+    const listPaperSessions = async (ref) => {
+        const archived = new Set(workspaceRegistry?.archivedSessionIds ?? []);
+        const sorted = await scanPaperSessions(ref);
+        const visible = sorted.filter((s) => !archived.has(s.sessionId));
+        const newestBlank = [...visible].reverse().find((s) => s.blank);
+        // 非最新的空白会话 = 被遗弃的草稿：后台归档（幂等；最新空白是活跃草稿，留给复用/显式归档）
+        for (const s of visible) {
+            if (s.blank && s !== newestBlank && !s.running) {
+                workspaceRegistry?.archiveSession(s.sessionId).catch(() => { });
+            }
+        }
+        return visible.filter((s) => !s.blank || s === newestBlank);
+    };
+    /** n → 实际 sessionId：旧格式存在时优先（历史不丢），否则新格式。全量扫描（含归档）。 */
+    const sessionIdFor = async (ref, n) => {
+        const sessions = await scanPaperSessions(ref);
+        const hit = sessions.find((s) => s.n === n);
+        return hit?.sessionId ?? `${sessionPrefixFor(ref)}-${n}`;
+    };
+    /** 专题目录 → dsh 工作区（幂等，进程内缓存）。会话挂到工作区后原生 composer 才可用。 */
+    const workspaceCache = new Map();
+    const ensureTopicWorkspace = async (topic) => {
+        const dir = join(dataDir, topic);
+        const cached = workspaceCache.get(dir);
+        if (cached)
+            return cached;
+        try {
+            const { workspace } = await workspaceController.create({ path: dir });
+            workspaceCache.set(dir, workspace.workspaceId);
+            return workspace.workspaceId;
+        }
+        catch (err) {
+            console.warn('[dsh-paper-reader] workspace 注册失败(回退 cwd 模式):', err);
+            return undefined;
+        }
+    };
+    /** 创建/复用会话：优先挂工作区 + 论文伴读 preset；失败（preset 缺失或旧会话 preset 冲突）逐级回退。 */
+    const createPaperSession = async (sessionId, topic) => {
+        const workspaceId = await ensureTopicWorkspace(topic);
+        const usePreset = (await presetDir) !== null;
+        if (workspaceId) {
+            if (usePreset) {
+                try {
+                    return await sessionController.create({ sessionId, workspaceId, agentPreset: PAPER_PRESET_ID });
+                }
+                catch { /* preset 未注册或旧会话属另一 preset → 去掉 preset 重试 */ }
+            }
+            try {
+                return await sessionController.create({ sessionId, workspaceId });
+            }
+            catch { /* 工作区挂载失败则回退 */ }
+        }
+        return sessionController.create({ sessionId, cwd: join(dataDir, topic) });
+    };
+    const dispatch = async (req, res, url) => {
+        const sub = url.pathname.slice('/paper-reader'.length); // '' | '/' | '/api/...'
+        if ((sub === '' || sub === '/') && req.method === 'GET') {
+            const html = await readFile(readerHtml);
+            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'content-length': html.length });
+            res.end(html);
+            return;
+        }
+        if (sub === '/api/library' && req.method === 'GET') {
+            json(res, 200, { dataDir, topics: listTopics(dataDir), papers: listPapers(dataDir) });
+            return;
+        }
+        // 新建专题（目录）
+        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: '专题名不能为空，且不能包含 / \\ ..' });
+                return;
+            }
+            await mkdir(join(dataDir, name), { recursive: true });
+            json(res, 200, { ok: true, topic: name });
+            return;
+        }
+        // 上传 PDF 到专题（raw body；文件名/专题走 header，避免 multipart 解析。
+        // header 值不允许非 Latin-1 字符，中文一律 encodeURIComponent 编码传输，这里解码）
+        if (sub === '/api/library/upload' && req.method === 'POST') {
+            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 头' });
+                return;
+            }
+            if (!filename.toLowerCase().endsWith('.pdf')) {
+                json(res, 400, { error: '只支持 PDF 文件' });
+                return;
+            }
+            const safeName = filename.replaceAll('/', '_').replaceAll('\\', '_');
+            const chunks = [];
+            for await (const c of req)
+                chunks.push(c);
+            const buf = Buffer.concat(chunks);
+            if (buf.length < 100) {
+                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);
+            json(res, 200, { ok: true, topic: topic.trim(), name: safeName.slice(0, -4), bytes: buf.length });
+            return;
+        }
+        // 新建伴读会话（会话N+1）。最新可见会话还是空白草稿时直接复用它——
+        // 连点「新建」不再堆积空会话（毫无意义的点击什么都不存）。
+        // n 用全量扫描分配（含归档/空白），绝不与磁盘上已有目录撞号。
+        if (sub === '/api/sessions/new' && req.method === 'POST') {
+            const body = (await readBody(req));
+            const ref = resolvePaper(dataDir, body);
+            const visible = await listPaperSessions(ref);
+            const newest = visible[visible.length - 1];
+            if (newest && newest.blank && !newest.running) {
+                json(res, 200, { ok: true, n: newest.n, sessionId: newest.sessionId, reused: true });
+                return;
+            }
+            const all = await scanPaperSessions(ref);
+            const n = all.length ? all[all.length - 1].n + 1 : 1;
+            const sessionId = `${sessionPrefixFor(ref)}-${n}`;
+            await createPaperSession(sessionId, ref.topic);
+            json(res, 200, { ok: true, n, sessionId });
+            return;
+        }
+        // 归档空白草稿（切换会话时客户端后台调用）：只接受该文献的空白会话，内容会话绝不归档
+        if (sub === '/api/sessions/archive' && req.method === 'POST') {
+            const body = (await readBody(req));
+            const sessionId = body.sessionId ?? '';
+            const ref = resolvePaper(dataDir, body);
+            if (!sessionId.startsWith(sessionPrefixFor(ref) + '-') && sessionId !== sessionPrefixFor(ref)) {
+                json(res, 400, { error: '会话不属于该文献' });
+                return;
+            }
+            if (!workspaceRegistry) {
+                json(res, 503, { error: 'workspaceRegistry 服务不可用' });
+                return;
+            }
+            const sessions = await listPaperSessions(ref);
+            const target = sessions.find((s) => s.sessionId === sessionId);
+            if (!target || !target.blank || target.running) {
+                json(res, 409, { error: '只允许归档无内容的空白会话' });
+                return;
+            }
+            await workspaceRegistry.archiveSession(sessionId);
+            json(res, 200, { ok: true });
+            return;
+        }
+        if (sub === '/api/paper' && req.method === 'GET') {
+            const ref = locate(url);
+            const t = await readTranscript(ref);
+            const st = await stat(ref.pdfPath);
+            json(res, 200, {
+                topic: ref.topic,
+                name: ref.name,
+                pdfBytes: st.size,
+                hasTranscript: t !== null,
+                chars: t?.text.length ?? 0,
+                hasPageIndex: (t?.pages?.length ?? 0) > 0,
+                pageCount: t?.pages?.length ?? null,
+            });
+            return;
+        }
+        if (sub === '/api/pdf' && req.method === 'GET') {
+            const ref = locate(url);
+            const pdfPath = pdfVariantPath(ref, url.searchParams.get('variant'));
+            const st = await stat(pdfPath); // 变体不存在时 404/500 由外层兜底
+            res.writeHead(200, {
+                'content-type': 'application/pdf',
+                'content-length': st.size,
+                'cache-control': 'no-cache', // 切换文献/重新生成后必须拿到新的
+            });
+            createReadStream(pdfPath).pipe(res);
+            return;
+        }
+        // 中文版状态：zh=纯中文 dual=中英对照 busy=翻译中
+        if (sub === '/api/zh' && req.method === 'GET') {
+            json(res, 200, zhStatus(locate(url)));
+            return;
+        }
+        // 启动后台翻译（幂等）。端点：UI 里填的 > profile 的 translate
+        if (sub === '/api/zh/generate' && req.method === 'POST') {
+            const body = (await readBody(req));
+            const ref = resolvePaper(dataDir, body);
+            const { endpoint } = await resolveTranslateEndpoint(config.translate);
+            const r = await startTranslation(ref, dataDir, endpoint);
+            json(res, r.started ? 200 : 409, r);
+            return;
+        }
+        // ── 翻译端点配置（阅读器浮层的读写口）─────────────────────────────
+        // GET 只回显掩码 key：明文永不离开服务端
+        if (sub === '/api/translate/config' && req.method === 'GET') {
+            const { endpoint, source } = await resolveTranslateEndpoint(config.translate);
+            json(res, 200, {
+                baseUrl: endpoint.baseUrl ?? '',
+                model: endpoint.model ?? '',
+                hasApiKey: Boolean(endpoint.apiKey),
+                apiKeyHint: endpoint.apiKey ? maskApiKey(endpoint.apiKey) : '',
+                source,
+            });
+            return;
+        }
+        // POST：校验 → 预检 → 通了才落盘。key 填错在这里就拦下，
+        // 不让它拖到 babeldoc 跑几分钟后才异步失败。
+        if (sub === '/api/translate/config' && req.method === 'POST') {
+            const body = (await readBody(req));
+            const baseUrl = body.baseUrl?.trim() ?? '';
+            const model = body.model?.trim() ?? '';
+            // key 留空 = 沿用已存的那把（明文不回传，前端无法预填）
+            const prev = await readTranslateConfig();
+            const apiKey = body.apiKey?.trim() || prev?.apiKey || '';
+            if (!/^https?:\/\//i.test(baseUrl)) {
+                json(res, 400, { error: '端点 URL 需要以 http:// 或 https:// 开头' });
+                return;
+            }
+            if (!model) {
+                json(res, 400, { error: '模型名不能为空（如 deepseek-chat）' });
+                return;
+            }
+            if (!apiKey) {
+                json(res, 400, { error: 'API Key 不能为空' });
+                return;
+            }
+            const test = await testTranslateEndpoint({ baseUrl, apiKey, model });
+            if (!test.ok) {
+                json(res, 400, { error: `连接测试失败：${test.detail ?? '未知原因'}` });
+                return;
+            }
+            await writeTranslateConfig({ baseUrl, apiKey, model });
+            json(res, 200, { ok: true });
+            return;
+        }
+        // DELETE：清掉文件，回落到 profile 的 translate
+        if (sub === '/api/translate/config' && req.method === 'DELETE') {
+            await clearTranslateConfig();
+            json(res, 200, { ok: true });
+            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 });
+            return;
+        }
+        // 文献的伴读会话列表（多会话：会话1/会话2/…）
+        if (sub === '/api/sessions' && req.method === 'GET') {
+            const ref = locate(url);
+            const sessions = await listPaperSessions(ref);
+            json(res, 200, { sessions, latest: sessions.length ? sessions[sessions.length - 1].n : 1 });
+            return;
+        }
+        // 实时会话流（SSE）：桥接官方 sessionController.follow —— 阅读器右侧就是真正的 dsh 会话
+        if (sub === '/api/session/follow' && req.method === 'GET') {
+            const ref = locate(url);
+            const sessions = await listPaperSessions(ref);
+            const nParam = +(url.searchParams.get('n') ?? 0) || 0;
+            // 未指定时进最新会话；全新文献进会话1
+            const n = nParam > 0 ? nParam : sessions.length ? sessions[sessions.length - 1].n : 1;
+            const sessionId = await sessionIdFor(ref, n);
+            try {
+                await createPaperSession(sessionId, ref.topic);
+            }
+            catch { /* 已存在则复用；失败由 follow 报错 */ }
+            res.writeHead(200, {
+                'content-type': 'text/event-stream; charset=utf-8',
+                'cache-control': 'no-cache',
+                connection: 'keep-alive',
+            });
+            res.write(': connected\n\n');
+            res.write(`event: meta\ndata: ${JSON.stringify({ n, sessionId })}\n\n`);
+            const ac = new AbortController();
+            req.on('close', () => ac.abort());
+            try {
+                const frames = sessionController.follow({ address: { kind: 'session', sessionId }, maxMessages: 200, assistantStream: true }, ac.signal);
+                for await (const frame of frames) {
+                    if (ac.signal.aborted)
+                        break;
+                    res.write(`data: ${JSON.stringify(frame)}\n\n`);
+                }
+            }
+            catch (err) {
+                if (!ac.signal.aborted) {
+                    res.write(`event: error\ndata: ${JSON.stringify({ error: String(err instanceof Error ? err.message : err) })}\n\n`);
+                }
+            }
+            if (!res.writableEnded)
+                res.end();
+            return;
+        }
+        if (sub === '/api/ask' && req.method === 'POST') {
+            const body = (await readBody(req));
+            if (!body.question?.trim()) {
+                json(res, 400, { error: 'question 不能为空' });
+                return;
+            }
+            const sc = sessionController;
+            if (!sc) {
+                json(res, 503, { error: '当前 profile 没有 sessionController 服务，无法注入会话（headless?）' });
+                return;
+            }
+            const ref = resolvePaper(dataDir, body);
+            const existing = await listPaperSessions(ref);
+            let n;
+            if (body.fresh) {
+                // 全量扫描分配（含归档/空白），避免与磁盘上已有会话目录撞号
+                const all = await scanPaperSessions(ref);
+                n = all.length ? all[all.length - 1].n + 1 : 1;
+            }
+            else if (body.n && body.n > 0)
+                n = body.n;
+            else
+                n = existing.length ? existing[existing.length - 1].n : 1;
+            const sessionId = await sessionIdFor(ref, n);
+            try {
+                await createPaperSession(sessionId, ref.topic);
+            }
+            catch { /* 已存在则复用 */ }
+            const hasQuote = typeof body.selectedText === 'string' && body.selectedText.trim() !== '';
+            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(`用户的问题：${body.question}`);
+            const prompt = lines.join('\n');
+            await sc.prompt({
+                sessionId,
+                content: [{ type: 'text', text: prompt }],
+                requestId: randomUUID(),
+            }, AbortSignal.timeout(30_000));
+            json(res, 200, { ok: true, sessionId, n });
+            return;
+        }
+        json(res, 404, { error: 'not found: ' + url.pathname });
+    };
+    ctx.effect(() => {
+        const dispose = ws.register({
+            kind: 'prefix',
+            path: '/paper-reader',
+            handler: (req, res) => {
+                // 认证+Host 围栏（与宿主 /api 通道同一套校验）：插件路由不在宿主 index
+                // 鉴权路径上，必须自己校验。本路由暴露 PDF 读取和会话注入，不能裸奔。
+                const rejection = connection.requestRejection(req);
+                if (rejection !== undefined) {
+                    json(res, rejection, { error: rejection === 401 ? 'unauthorized' : 'forbidden' });
+                    return;
+                }
+                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) });
+                    else
+                        res.end();
+                });
+            },
+        });
+        console.log('[dsh-paper-reader] routes registered under /paper-reader');
+        return dispose;
+    });
+}

package/dist/index.js

@@ -0,0 +1,17 @@
+// dsh-paper-reader — Cordis 插件壳。
+// 壳保持薄：agent 循环/模型层交给 dsh 框架，本插件只注册工具和 HTTP 路由。
+// 核心逻辑（转录/检索）是 src/ 下不依赖 Cordis 的纯函数模块，方便日后迁移。
+import { registerTools } from "./tools.js";
+import { registerRoutes } from "./host.js";
+export const name = 'dsh-paper-reader';
+// 等宿主的工具注册服务（ctx.tools）就绪后再运行。
+export const inject = ['tools'];
+export function apply(ctx, config = {}) {
+    registerTools(ctx, config);
+    console.log(`[dsh-paper-reader] registered tools: list_papers, transcribe_pdf, search_paper, study_progress, study_update`);
+    // webServer 是可选服务（web profile 有，headless 没有）：出现时再挂路由。
+    // connection/sessionController/workspaceController/workspaceRegistry 同属 web profile（cordis 要求访问前先声明 inject）。
+    ctx.inject(['webServer', 'connection', 'sessionController', 'workspaceController', 'workspaceRegistry'], (rctx) => {
+        registerRoutes(rctx, config);
+    });
+}

package/dist/library.js

@@ -0,0 +1,103 @@
+// library.ts — 文献库目录约定（纯函数，不依赖 Cordis）。
+//
+// 布局兼容 pdfqa 的 data/ 思路：
+//   <dataDir>/<专题>/<文献>.pdf          原始 PDF
+//   <dataDir>/<专题>/<文献>.txt          转录缓存（清洗后的全文文本）
+//   <dataDir>/<专题>/<文献>.pages.json   页码偏移表（转录时生成，检索映射页码用）
+// pdf2zh 的产物（-en / -zh / -dual）不算用户文献。
+// （问答不落盘存档——会话持久化交给 dsh 自己；pdfqa 时代的 -qa/ 目录不再读写。）
+import { readdirSync, existsSync, mkdirSync, statSync } from 'node:fs';
+import { join, resolve, extname, basename } from 'node:path';
+import { homedir } from 'node:os';
+const PDF2ZH_SUFFIXES = ['-en', '-zh', '-dual'];
+/** 判定是否为用户文献：排除 pdf2zh 的中间/产出文件。 */
+export function isPaperPDF(filename) {
+    if (!filename.toLowerCase().endsWith('.pdf'))
+        return false;
+    const stem = filename.slice(0, -extname(filename).length);
+    return !PDF2ZH_SUFFIXES.some((s) => stem.endsWith(s));
+}
+/** dsh home：$DSH_HOME > ~/.dsh（与 dsh-home-paths 的解析顺序一致）。 */
+export function dshHome(env = process.env) {
+    const fromEnv = env.DSH_HOME?.trim();
+    return fromEnv || join(homedir(), '.dsh');
+}
+/** 解析数据目录：显式配置 > 环境变量 > 默认 ~/.dsh-paper-reader/data */
+export function resolveDataDir(configured) {
+    const dir = configured ?? process.env['DSH_PAPER_READER_DATA'] ?? join(homedir(), '.dsh-paper-reader', 'data');
+    const abs = resolve(dir);
+    mkdirSync(abs, { recursive: true });
+    return abs;
+}
+/** 列出专题（一级子目录，跳过隐藏目录）。 */
+export function listTopics(dataDir) {
+    if (!existsSync(dataDir))
+        return [];
+    return readdirSync(dataDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+        .map((e) => e.name)
+        .sort();
+}
+/** 列出某专题下的文献名（不含后缀）；topic 省略时跨全部专题。 */
+export function listPapers(dataDir, topic) {
+    const topics = topic ? [topic] : listTopics(dataDir);
+    const out = [];
+    for (const t of topics) {
+        const dir = join(dataDir, t);
+        if (!existsSync(dir))
+            continue;
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+            if (e.isFile() && isPaperPDF(e.name)) {
+                out.push({ topic: t, name: e.name.slice(0, -4) });
+            }
+        }
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+function refFor(topic, name, pdfPath) {
+    const base = pdfPath.slice(0, -extname(pdfPath).length);
+    return {
+        topic,
+        name,
+        pdfPath,
+        txtPath: base + '.txt',
+        pagesPath: base + '.pages.json',
+    };
+}
+/**
+ * 解析文献：三种方式
+ *  1. path 绝对/相对路径直指 PDF
+ *  2. topic + name 在专题目录里找 <name>.pdf
+ *  3. 只有 name 时跨专题找，同名多篇报歧义
+ */
+export function resolvePaper(dataDir, args) {
+    if (args.path) {
+        const abs = resolve(args.path);
+        if (!existsSync(abs))
+            throw new Error(`PDF 不存在: ${abs}`);
+        const name = basename(abs, extname(abs));
+        return refFor(basename(join(abs, '..')), name, abs);
+    }
+    if (!args.name)
+        throw new Error('需要 path 或 name 参数定位文献');
+    const name = args.name.replace(/\.pdf$/i, '');
+    const candidates = listPapers(dataDir, args.topic).filter((p) => p.name === name);
+    if (candidates.length === 0) {
+        const hint = listPapers(dataDir).map((p) => `${p.topic}/${p.name}`).join(', ');
+        throw new Error(`文献库中找不到 "${name}"。现有文献: ${hint || '(空)'}`);
+    }
+    if (candidates.length > 1) {
+        throw new Error(`"${name}" 命中多篇: ${candidates.map((c) => c.topic).join(', ')}，请用 topic 参数限定`);
+    }
+    const hit = candidates[0];
+    return refFor(hit.topic, hit.name, join(dataDir, hit.topic, hit.name + '.pdf'));
+}
+/** 转录缓存是否可用（存在且非空）。 */
+export function transcriptCached(ref) {
+    try {
+        return statSync(ref.txtPath).size > 1000;
+    }
+    catch {
+        return false;
+    }
+}