@ggboy123/dsh-paper-reader 0.1.0

package/dist/preset.js

@@ -0,0 +1,31 @@
+// preset.ts — 把插件自带的「论文伴读」agent preset 安装到 dsh 用户预设根。
+// 纯函数模块，不依赖 Cordis。dsh 的 preset 发现是每次实时扫描
+// （$DSH_HOME/.agent-presets/<id>/，includeUserRoot 默认开），拷贝到位即生效，免重启。
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { dshHome } from "./library.js";
+export const PAPER_PRESET_ID = 'paper-reader';
+/**
+ * 把 presets/paper-reader/{preset.yml,agent.cordis.yml} 同步到
+ * <dshHome>/.agent-presets/paper-reader/。幂等：内容一致不写盘。
+ * 返回安装目录；写失败（权限等）返回 null，调用方回退到默认 preset。
+ */
+export async function installPaperPreset(packageRoot) {
+    const src = new URL('presets/paper-reader/', packageRoot);
+    const destDir = join(dshHome(), '.agent-presets', PAPER_PRESET_ID);
+    try {
+        await mkdir(destDir, { recursive: true });
+        for (const file of ['preset.yml', 'agent.cordis.yml']) {
+            const content = await readFile(new URL(file, src));
+            const dest = join(destDir, file);
+            const existing = await readFile(dest).catch(() => null);
+            if (existing === null || !existing.equals(content))
+                await writeFile(dest, content);
+        }
+        return destDir;
+    }
+    catch (err) {
+        console.warn('[dsh-paper-reader] agent preset 安装失败（回退默认 preset）:', err);
+        return null;
+    }
+}

package/dist/search.js

@@ -0,0 +1,98 @@
+// search.ts — 长文档分段检索（纯函数，不依赖 Cordis）。
+// 移植 pdfqa 的 chunkText + searchPaper，新增：片段 → 页码映射（经 pages.json 偏移表）。
+/** 按空行分段后打包成 ~size 字符的片段（忠实移植 pdfqa chunkText）。 */
+export function chunkText(text, size = 1500) {
+    const paras = text.split('\n\n');
+    const chunks = [];
+    let cur = '';
+    let curStart = 0;
+    // offset 追踪：每段在原文中的起点（paras 之间由 \n\n 连接）
+    let offset = 0;
+    const flush = (end) => {
+        if (cur.length > 0)
+            chunks.push({ index: chunks.length + 1, start: curStart, end, text: cur });
+        cur = '';
+    };
+    for (const raw of paras) {
+        const p = raw.trim();
+        const pStart = offset + (raw.length - raw.trimStart().length);
+        offset += raw.length + 2; // +2 为 \n\n
+        if (p === '')
+            continue;
+        if (cur.length > 0 && cur.length + p.length > size)
+            flush(pStart - 2);
+        // 单段超过 size 的硬切
+        let rest = p;
+        let restStart = pStart;
+        while (rest.length > size) {
+            if (cur.length > 0)
+                flush(restStart);
+            chunks.push({ index: chunks.length + 1, start: restStart, end: restStart + size, text: rest.slice(0, size) });
+            rest = rest.slice(size);
+            restStart += size;
+        }
+        if (rest !== '') {
+            if (cur.length > 0)
+                cur += '\n\n';
+            else
+                curStart = restStart;
+            cur += rest;
+        }
+    }
+    flush(text.length);
+    return chunks;
+}
+/** 字符位置 → 页码。无偏移表返回 null；跨页片段返回起始页。 */
+export function pageForOffset(pages, pos) {
+    if (!pages || pages.length === 0)
+        return null;
+    let best;
+    for (const span of pages) {
+        if (pos >= span.start && pos < span.end)
+            return span.page;
+        if (!best || span.start <= pos)
+            best = span;
+    }
+    return best?.page ?? null;
+}
+/** 关键词检索：按词项出现频次 × 词长打分，top-k 后按原文顺序返回（移植 pdfqa）。 */
+export function searchChunks(chunks, pages, query, k = 5) {
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    const hits = [];
+    for (const chunk of chunks) {
+        const lc = chunk.text.toLowerCase();
+        let score = 0;
+        for (const t of terms) {
+            score += countOccurrences(lc, t) * t.length; // 长词权重高
+        }
+        if (score > 0)
+            hits.push({ chunk, score, page: pageForOffset(pages, chunk.start) });
+    }
+    hits.sort((a, b) => b.score - a.score);
+    const top = hits.slice(0, k);
+    top.sort((a, b) => a.chunk.index - b.chunk.index); // 按原文顺序返回
+    return top;
+}
+function countOccurrences(haystack, needle) {
+    if (needle === '')
+        return 0;
+    let n = 0;
+    let i = haystack.indexOf(needle);
+    while (i !== -1) {
+        n++;
+        i = haystack.indexOf(needle, i + needle.length);
+    }
+    return n;
+}
+/** 格式化检索结果给模型消费（带页码 + 片段编号）。 */
+export function formatHits(hits, totalChunks, query) {
+    if (hits.length === 0) {
+        return `没有找到与 "${query}" 相关的片段，请换关键词（建议用英文术语或章节号）`;
+    }
+    const parts = [`共 ${totalChunks} 个片段，以下按原文顺序返回最相关的 ${hits.length} 个：\n`];
+    for (const h of hits) {
+        const where = h.page != null ? `（第 ${h.page} 页）` : '';
+        parts.push(`=== 片段 ${h.chunk.index}/${totalChunks}${where} ===\n${h.chunk.text}\n`);
+    }
+    return parts.join('\n');
+}

package/dist/study.js

@@ -0,0 +1,100 @@
+// study.ts — 学习档案（纯函数，不依赖 Cordis）。
+// 每篇论文一个 <文献>.study.json，存在文献旁边：阅读计划（分步状态）+ 历次检验分数。
+// 这是结构化状态（教学进度），不是会话流水——dsh 的会话存储替代不了，agent 经工具读写。
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+export function studyPathFor(ref) {
+    return ref.pdfPath.slice(0, -4) + '.study.json';
+}
+/** 读学习档案；不存在或损坏返回 null。 */
+export async function readStudy(ref) {
+    try {
+        const raw = await readFile(studyPathFor(ref), 'utf8');
+        const data = JSON.parse(raw);
+        if (!Array.isArray(data.plan) || !Array.isArray(data.quizzes))
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeStudy(ref, record) {
+    const file = studyPathFor(ref);
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, JSON.stringify(record, null, 2) + '\n', 'utf8');
+    return file;
+}
+/** 制定/重置阅读计划：第一步置为 current，其余 pending。 */
+export async function setPlan(ref, steps) {
+    if (steps.length === 0)
+        throw new Error('计划不能为空');
+    const prev = await readStudy(ref);
+    const record = {
+        paper: `${ref.topic}/${ref.name}`,
+        plan: steps.map((title, i) => ({ id: i + 1, title, status: i === 0 ? 'current' : 'pending' })),
+        quizzes: prev?.quizzes ?? [], // 重新制定计划不清历史成绩
+    };
+    await writeStudy(ref, record);
+    return record;
+}
+/** 完成某一步（可附点评），并把下一步置为 current。 */
+export async function completeStep(ref, stepId, note) {
+    const record = await readStudy(ref);
+    if (!record)
+        throw new Error('还没有学习计划，先用 action=set_plan 制定');
+    const step = record.plan.find((s) => s.id === stepId);
+    if (!step)
+        throw new Error(`计划里没有第 ${stepId} 步（共 ${record.plan.length} 步）`);
+    step.status = 'done';
+    if (note)
+        step.note = note;
+    // 归一化：current 只能有一个（第一个未完成的步骤），其余一律 pending。
+    // 补记/乱序完成时否则会出现多个 current（先 complete 2 再 complete 1：1 曾滞留 current）。
+    let firstOpen = true;
+    for (const s of record.plan) {
+        if (s.status === 'done')
+            continue;
+        if (firstOpen) {
+            s.status = 'current';
+            firstOpen = false;
+        }
+        else
+            s.status = 'pending';
+    }
+    await writeStudy(ref, record);
+    return record;
+}
+/** 记录一次检验成绩。 */
+export async function recordQuiz(ref, score, total, summary) {
+    if (total <= 0 || score < 0 || score > total)
+        throw new Error(`分数不合法：${score}/${total}`);
+    const record = (await readStudy(ref)) ?? { paper: `${ref.topic}/${ref.name}`, plan: [], quizzes: [] };
+    record.quizzes.push({ time: new Date().toISOString(), score, total, ...(summary ? { summary } : {}) });
+    await writeStudy(ref, record);
+    return record;
+}
+/** 给老师/用户看的进度摘要。 */
+export function formatStudy(record) {
+    if (!record)
+        return '还没有学习记录。';
+    const lines = [];
+    if (record.plan.length) {
+        lines.push('阅读计划：');
+        for (const s of record.plan) {
+            const mark = s.status === 'done' ? '✅' : s.status === 'current' ? '▶️' : '⬜';
+            lines.push(`  ${mark} ${s.id}. ${s.title}${s.note ? `（${s.note}）` : ''}`);
+        }
+    }
+    else {
+        lines.push('（尚未制定阅读计划）');
+    }
+    if (record.quizzes.length) {
+        lines.push('检验记录：');
+        for (const q of record.quizzes) {
+            const pct = Math.round((q.score / q.total) * 100);
+            lines.push(`  · ${q.time.slice(0, 16).replace('T', ' ')} — ${q.score}/${q.total}（${pct} 分）${q.summary ? `：${q.summary}` : ''}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/tools.js

@@ -0,0 +1,307 @@
+// tools.ts — 工具注册（Cordis 壳；核心逻辑在 library/transcribe/search 纯函数里）。
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { listPapers, listTopics, resolveDataDir, resolvePaper } from "./library.js";
+import { transcribePaper, readTranscript } from "./transcribe.js";
+import { chunkText, searchChunks, formatHits } from "./search.js";
+import { completeStep, formatStudy, readStudy, recordQuiz, setPlan } from "./study.js";
+const locateParams = {
+    path: { type: 'string', description: 'PDF 绝对路径。与 topic+name 二选一。' },
+    topic: { type: 'string', description: '专题名（文献库一级目录）。' },
+    name: { type: 'string', description: '文献名（不带 .pdf 后缀）。省略时自动使用当前会话绑定的论文（伴读会话），只有查询别的论文才需要显式指定。' },
+};
+function locate(dataDir, args, exec) {
+    const refArgs = {};
+    if (args.path)
+        refArgs.path = args.path;
+    if (args.topic)
+        refArgs.topic = args.topic;
+    if (args.name)
+        refArgs.name = args.name;
+    // 未指定论文时回退到「当前会话绑定的论文」：伴读会话 id 形如 dpr-<base64url(topic/name)>-N，
+    // 工具执行上下文里的 agent.id 就是会话 id。直接在输入框提问（不经选中即问）时靠它定位。
+    if (!refArgs.path && !refArgs.name) {
+        const paper = paperFromSessionId(exec?.agent?.id);
+        if (paper)
+            return resolvePaper(dataDir, { topic: paper.topic, name: paper.name });
+    }
+    return resolvePaper(dataDir, refArgs);
+}
+/** 从伴读会话 id 反解论文（dpr-<base64url(topic/name)>[-N]）；非伴读会话返回 null。 */
+export function paperFromSessionId(sessionId) {
+    if (!sessionId?.startsWith('dpr-'))
+        return null;
+    try {
+        const body = sessionId.slice(4).replace(/-\d+$/, '');
+        const decoded = Buffer.from(body, 'base64url').toString('utf8');
+        const sep = decoded.indexOf('/');
+        if (sep <= 0 || sep === decoded.length - 1)
+            return null;
+        return { topic: decoded.slice(0, sep), name: decoded.slice(sep + 1) };
+    }
+    catch {
+        return null;
+    }
+}
+export function registerTools(ctx, config) {
+    const dataDir = resolveDataDir(config.dataDir);
+    ctx.tools.register(defineTool({
+        name: 'list_papers',
+        description: '列出文献库里的专题和文献。当用户提到某篇论文但你不知道它是否在库中、或用户问"我有哪些论文"时使用。',
+        parameters: {
+            topic: { type: 'string', description: '只看某个专题；省略则列出全部。' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    dataDir: { type: 'string', required: true, description: '文献库根目录。' },
+                    topics: {
+                        type: 'array',
+                        required: true,
+                        items: { type: 'string' },
+                        description: '专题列表。',
+                    },
+                    papers: {
+                        type: 'array',
+                        required: true,
+                        items: { type: 'string', description: '形如 专题/文献名' },
+                        description: '文献列表。',
+                    },
+                },
+                additionalProperties: false,
+            },
+            render: (_args, value) => [
+                {
+                    type: 'text',
+                    text: value.papers.length === 0
+                        ? `文献库为空（${value.dataDir}）。把 PDF 放进 <专题>/ 目录即可。`
+                        : `文献库（${value.dataDir}）：\n${value.papers.map((p) => `- ${p}`).join('\n')}`,
+                },
+            ],
+        },
+        execute: async (args, exec) => {
+            const papers = listPapers(dataDir, args.topic).map((p) => `${p.topic}/${p.name}`);
+            return { dataDir, topics: listTopics(dataDir), papers };
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'transcribe_pdf',
+        description: '把一篇 PDF 论文转录为纯文本（本地 PyMuPDF 提取，带页码索引），结果落盘缓存。' +
+            '读一篇新论文的第一步：先转录，再用 search_paper 检索。已有缓存时秒回。',
+        parameters: {
+            ...locateParams,
+            force: { type: 'boolean', description: '忽略缓存重新转录。' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    paper: { type: 'string', required: true },
+                    txtPath: { type: 'string', required: true, description: '转录文本路径。' },
+                    chars: { type: 'integer', required: true },
+                    pageCount: { type: 'integer', required: true },
+                    hasPageIndex: { type: 'boolean', required: true, description: '是否有页码索引（检索结果能否带页码）。' },
+                    source: { type: 'string', required: true, enum: ['cache', 'local'] },
+                },
+                additionalProperties: false,
+            },
+            render: (_args, value) => [
+                {
+                    type: 'text',
+                    text: `已转录《${value.paper}》：${value.chars} 字符，${value.pageCount} 页` +
+                        `（${value.source === 'cache' ? '缓存复用' : '本地提取'}${value.hasPageIndex ? '，含页码索引' : '，无页码索引'}）。` +
+                        `接下来可用 search_paper 检索具体内容。`,
+                },
+            ],
+        },
+        execute: async (args, exec) => {
+            const ref = locate(dataDir, args, exec);
+            const t = await transcribePaper(ref, { force: args.force === true });
+            return {
+                paper: `${ref.topic}/${ref.name}`,
+                txtPath: ref.txtPath,
+                chars: t.chars,
+                pageCount: t.pageCount,
+                hasPageIndex: t.pages.length > 0,
+                source: t.source,
+            };
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'search_paper',
+        description: '在论文全文中按关键词检索相关片段，返回带页码的原文片段。' +
+            '当需要论文的具体内容（定义、算法步骤、章节细节、数据）时使用，基于检索到的原文回答并注明页码。' +
+            '关键词建议：用论文中的英文术语、章节号（如 "Section 3.1"）或概念名，不要用完整长句；找不到时换同义词或更短的词重试。' +
+            '论文未转录时会自动先转录。',
+        parameters: {
+            query: { type: 'string', required: true, description: '检索关键词，如 "backup task" 或 "locality"。' },
+            k: { type: 'integer', description: '返回片段数量，默认 5，最多 8。' },
+            ...locateParams,
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    paper: { type: 'string', required: true },
+                    query: { type: 'string', required: true },
+                    totalChunks: { type: 'integer', required: true },
+                    hits: {
+                        type: 'array',
+                        required: true,
+                        items: {
+                            type: 'object',
+                            properties: {
+                                chunk: { type: 'integer', required: true },
+                                page: {
+                                    oneOf: [{ type: 'integer' }, { type: 'null' }],
+                                    required: true,
+                                    description: '片段起始页码；无页码索引时为 null。',
+                                },
+                                text: { type: 'string', required: true },
+                            },
+                            additionalProperties: false,
+                        },
+                    },
+                },
+                additionalProperties: false,
+            },
+            render: (_args, value) => [
+                {
+                    type: 'text',
+                    text: formatHits(value.hits.map((h) => ({
+                        chunk: { index: h.chunk, start: 0, end: 0, text: h.text },
+                        score: 0,
+                        page: h.page,
+                    })), value.totalChunks, value.query),
+                },
+            ],
+        },
+        execute: async (args, exec) => {
+            const ref = locate(dataDir, args, exec);
+            let cached = await readTranscript(ref);
+            if (!cached) {
+                await transcribePaper(ref);
+                cached = await readTranscript(ref);
+            }
+            if (!cached)
+                throw new Error('转录失败，无法检索');
+            const chunks = chunkText(cached.text, 1500);
+            const k = Math.max(1, Math.min(args.k ?? 5, 8));
+            const hits = searchChunks(chunks, cached.pages, args.query, k);
+            return {
+                paper: `${ref.topic}/${ref.name}`,
+                query: args.query,
+                totalChunks: chunks.length,
+                hits: hits.map((h) => ({ chunk: h.chunk.index, page: h.page, text: h.chunk.text })),
+            };
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'study_progress',
+        description: '读取一篇论文的学习档案：分步阅读计划（每步状态）和历次检验成绩。' +
+            '开始伴读、或用户想继续学习/查看进度时先调用；没有记录时返回空，此时应制定计划（study_update 的 set_plan）。',
+        parameters: { ...locateParams },
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    paper: { type: 'string', required: true },
+                    hasRecord: { type: 'boolean', required: true },
+                    plan: {
+                        type: 'array',
+                        required: true,
+                        items: {
+                            type: 'object',
+                            properties: {
+                                id: { type: 'integer', required: true },
+                                title: { type: 'string', required: true },
+                                status: { type: 'string', required: true, enum: ['pending', 'current', 'done'] },
+                                note: { type: 'string' },
+                            },
+                            additionalProperties: false,
+                        },
+                    },
+                    quizzes: {
+                        type: 'array',
+                        required: true,
+                        items: {
+                            type: 'object',
+                            properties: {
+                                time: { type: 'string', required: true },
+                                score: { type: 'integer', required: true },
+                                total: { type: 'integer', required: true },
+                                summary: { type: 'string' },
+                            },
+                            additionalProperties: false,
+                        },
+                    },
+                },
+                additionalProperties: false,
+            },
+            render: (_args, value) => [
+                {
+                    type: 'text',
+                    text: `《${value.paper}》学习档案：\n` + formatStudy(value.hasRecord ? { paper: value.paper, plan: value.plan, quizzes: value.quizzes } : null),
+                },
+            ],
+        },
+        execute: async (args, exec) => {
+            const ref = locate(dataDir, args, exec);
+            const record = await readStudy(ref);
+            return {
+                paper: `${ref.topic}/${ref.name}`,
+                hasRecord: record !== null,
+                plan: record?.plan ?? [],
+                quizzes: record?.quizzes ?? [],
+            };
+        },
+    }));
+    ctx.tools.register(defineTool({
+        name: 'study_update',
+        description: '更新一篇论文的学习档案（老师用）：' +
+            'set_plan=制定阅读计划（steps 为 3~6 个分步标题，会重置计划但保留历史成绩）；' +
+            'complete_step=学生完成某一步（step_id + 可选 note 点评，自动推进到下一步）；' +
+            'record_quiz=记录一次检验成绩（score/total + 可选 summary 薄弱点小结）。',
+        parameters: {
+            action: { type: 'string', required: true, enum: ['set_plan', 'complete_step', 'record_quiz'] },
+            steps: { type: 'array', items: { type: 'string' }, description: 'set_plan 用：分步标题列表，如 "读摘要与引言（第 1 页），说出论文要解决的问题"。' },
+            step_id: { type: 'integer', description: 'complete_step 用：完成的步骤号。' },
+            note: { type: 'string', description: 'complete_step 用：对学生这一步表现的点评。' },
+            score: { type: 'integer', description: 'record_quiz 用：得分。' },
+            total: { type: 'integer', description: 'record_quiz 用：满分。' },
+            summary: { type: 'string', description: 'record_quiz 用：本次检验小结（考点/薄弱点）。' },
+            ...locateParams,
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    paper: { type: 'string', required: true },
+                    summary: { type: 'string', required: true, description: '更新后的档案摘要。' },
+                },
+                additionalProperties: false,
+            },
+            render: (_args, value) => [{ type: 'text', text: `《${value.paper}》档案已更新：\n${value.summary}` }],
+        },
+        execute: async (args, exec) => {
+            const ref = locate(dataDir, args, exec);
+            let record;
+            if (args.action === 'set_plan') {
+                if (!args.steps?.length)
+                    throw new Error('set_plan 需要 steps');
+                record = await setPlan(ref, args.steps);
+            }
+            else if (args.action === 'complete_step') {
+                if (!args.step_id)
+                    throw new Error('complete_step 需要 step_id');
+                record = await completeStep(ref, args.step_id, args.note);
+            }
+            else {
+                if (args.score === undefined || args.total === undefined)
+                    throw new Error('record_quiz 需要 score 和 total');
+                record = await recordQuiz(ref, args.score, args.total, args.summary);
+            }
+            return { paper: `${ref.topic}/${ref.name}`, summary: formatStudy(record) };
+        },
+    }));
+}