@li-canghai/dsh-paper
v0.8.1
Published
PDF transcription with stable block ids, folder scanning up to two sub-levels, and session-scoped paper context with drag-select batch injection and removal for DSH.
Readme
dsh-paper
概览
把 PDF 变成可检索、可引用、可对照阅读的本地语料。
选文件或文件夹 → 解析(已有的直接复用)→ 连同结果收进插件存储,库自此自包含;
读的时候有章节目录、块级续读、划线、AI 边注、逐块中英对照、原页拖选提问,
引用标记悬停即见该条参考文献原文([41] 与 (Zhang et al., 2020) 都认),
还能把同一篇并排开两格(左英文右译文、滚动联动);
写完有书目补全、BibTeX / RIS / CSL-JSON 互通与 GB/T 7714 等引用样式。
另有两条不进库的旁路:把结果存一份到论文文件夹,或直接把一篇 PDF 解成 md + images。
目录
使用
什么时候选它
想把一批 PDF 变成可检索、可引用、可对照阅读的语料时。它不做 Zotero 那样的多端同步与写作软件集成 (差距见 zotero-gaps.md),换来的是一条自包含的本地流水线: 入库即复制、解析可复用、引用能按 GB/T 7714 出。
只要读一篇 PDF 的一段文字,用右栏「解析」Tab 就够 —— 那条路不建库、不写 item.json。
最小配置
| 项 | 值 |
| --- | --- |
| MinerU Key | 插件详情页录入,存 $DSH_HOME/runtime/dsh-paper/mineru.json(页面只回显打码值)|
| 启动器 | uvx(页面图、PDF 元数据、MinerU 解析三条链共用;缺失时详情页自检卡给安装命令)|
| 解析语言 | ch(中英);扫描件可开 parseOcr |
| 自动翻译 | 开,范围「前 20 页」,模型跟随宿主默认 |
完整配置项表见 SPEC.md 的配置项。
部署
node deploy-plugin.mjs dsh-paper # 仓库根脚本,同步到 profile 副本并注册
npm run deploy:check # 退出 0 才算副本齐、profile 注册完整内容更新由 hmr 热换代;只有升级/删除已加载依赖或宿主升版才需要重启宿主。 从零安装与依赖清单见 install.md。
实现
宿主半按四层分,依赖单向向下:纯逻辑(tool-identity / slicing / reading-order / item-ops /
library-model / blocks,不碰 IO)→ 模型侧工具(四个 *-tool.js,只做 schema 与整形)→
工具执行侧(tool-host.js 的 createToolHost(deps))→ 路由与装配(index.js)。
HTTP 分发只做三件事:repositoryReady、同源检查、按阶段转发;路由体按阶段 × 领域分组,
只读路由必须在解析请求体之前。同一件事只有一份实现:条目改写、切片、阅读顺序、导出各只有一个所有者。
解析链:入库先把 PDF 复制进 runtime(同哈希幂等)→ 复用已有记录 → 才调 MinerU(VLM 优先,
失败补一次 pipeline)→ 整批提交(正文、目录、块列表、图片一起 stage 再逐个 rename,失败反序回滚)。
解析完成后按文章名自动改名,那是 9 个文件搬家而不是改一个文件。
翻译链:触发点是「打开一篇文献」而不是解析完成;范围三档、协议三种、并发由全局闸门限住 (许可挂在每一次模型请求上,重试也算数)。「翻译」恒定增量,「整篇重译」才全量。
关键不变量:🔴 路径只有一个所有者且主名用入库时冻结的 pdfName · 🔴 入库不写用户目录 ·
🔴 一个任务的执行权只有一个拥有者 · 🔴 「记录里没有这个键 = 显式清空」的写入必须用搬动前读到的那份记录 ·
🔴 回滚按字节不按记录对象重写 · 🔴 section 走阅读顺序、blocks 走块数组顺序 ·
🔴 注入默认关闭且单条消息区块整块保留或整块丢弃。
源码映射:
| 关注点 | 入口 |
| --- | --- |
| 宿主装配、HTTP 分发 | lib/index.js |
| 路径规则(唯一所有者)|lib/store-paths.js |
| 解析队列与闸门 | lib/resolver.js · lib/mineru-sdk.js · lib/result-archive.js |
| 阅读顺序与章节 | lib/reading-order.js · lib/outline.js · lib/slicing.js |
| 翻译 | lib/translate.js · lib/translate-prompts.js · lib/concurrency-gate.js |
| 跨篇检索 | lib/search-index.js · lib/search-database.js · lib/search-terms.js |
| arXiv 源码层 | lib/tex-*.js · lib/pdf-text.js |
| 客户端(源 / 产物)|lib/client-parts/*.js → lib/client.js |
完整机制见 ARCHITECTURE.md。
延伸阅读
- docs/ARCHITECTURE.md — 代码分层、磁盘身份与写入边界、解析与翻译两条主链、检索与注入、关键不变量
- docs/SPEC.md — 四个工具的动作表、配置项、HTTP 路由、存储布局、状态码与退出码
- docs/PITFALLS.md — 九十多条「现象 → 根因 → 规避」,含实测数字与反向验证过的回归
- docs/DECISIONS.md — 45 条方向性选择,每条带背景、决定、后果与重审条件
- docs/install.md — 从零安装的依赖清单、步骤与验收清单
- docs/arXiv 源码计划 — 源码优先层的判据与实测交付记录
- docs/阅读器设计 — 空块折叠、阅读位置、划线与中英对齐的实现判据
- docs/书目补全 — Crossref / arXiv 两路补全的判据与冲突处理
- docs/书目互通 — BibTeX / RIS / CSL-JSON 导入导出与引用样式
- docs/Zotero 差距 — 排除多端同步后的其余能力差距
- docs/界面规划 — 三栏文献库与右栏阅读器的界面规划稿(历史,非权威)
已知限制
- 不自动补造空节正文,也不跨章节搬移浮动图表;图内文字需通过原页核对。 正文与目录以现有解析产物为输入,漏字、错字和图片内文字由解析流程负责。
- arXiv 源码增强默认关闭(
texSourceEnabled):打开后只对 arXiv 来源生效,任一环不成立就整篇退回 MinerU。 - 书目补全依赖公开登记的覆盖:未登记或不适用的卷期页码保持空白,版本冲突不自动合并。
- 笔记导出的可选块 id 与源文件夹自动改名暂未提供;源目录搬迁会影响用户既有分类工作流。
- 两个系统窗口(选择 PDF / 选择文件夹)只支持 Windows:非 win32 回 501,企业机被 ConstrainedLanguage 策略挡住时同样只报错一行(此时路径粘贴与其余功能照常可用)。
- 模型工具面不提供永久删除:
Paper_library只到回收站。 - 检索未承诺恒定查询耗时:首页仍需全库内容校验;中文按子串匹配、引号内按连续词组匹配。
开发笔记
非权威内容:工作假设与待排查方向,随时可能被推翻。
- 新增设置项要同时改三处:默认值、白名单、校验。默认值只能存在一处。
- 改
lib/client-parts/之后必须跑node scripts/sync-client-parts.mjs;lib/client.js标记块之间是产物。npm run check会跑--check,源与产物不同步直接失败。 - 只测闸门/渲染器这类「类本身」不够:实测摘掉
index.js的gate: translationGate一行, 全仓 745 个测试一个都不红。新接线要有穿透真实接线的用例。 - 断言要打在被观察的那一层:选区提问那个缺陷之所以溜过去,是因为用例断言了请求体里的字段, 而客户端本来就发对了 —— 要断言的是投递出去的那条消息。
- 改
sourceHashOf的口径时记得:哈希若仍按原串算,已经存下来的坏译文会被一直跳过、永远修不回来。 - 部署面只剩
desktop;npm audit必须显式给--registry=https://registry.npmjs.org(本机默认镜像不实现审计端点);package-lock.json只能在干净目录生成。 - 测试 CI:
dsh-paper-ci.yml随插件改动自动运行、也可手动触发。 Windows 跑npm run check全量测试(额外安装与宿主镜像同版的测试工具包),Ubuntu 24.04 跑 PDF/选区跨平台回归, 并用真正的 PDFium + Chromium 逐字测坐标、逐像素检查同一行蓝色选区不留白、核对真实鼠标拖选; 截图作为 Actions artifact 保存 7 天。两者都跑npm run smoke。测试 CI 不发布 npm 包。 - 发版见 .agents/skills/dsh-paper-npm-release:
改
package.json的 version 并推到 main 就发版,其余提交不触发。dsh-paper-release.yml盯着Plugins/dsh-paper/package.json这条路,先查 npm 判断该版本 是否已存在(幂等),过发布闸门,自己打 tagdsh-paper-v<版本>,再用 OIDC 发布 —— tag 是产物不是输入,所以它恒等于实际发出去的版本,也不存在「忘了打 tag 就静默不发」。 一键等效操作:node scripts/release.mjs <版本号>(过闸门 → 改版本号与 lockfile → 提交 → 推 HEAD)。 任何 npm 写操作都要显式--registry=https://registry.npmjs.org—— 本机全局是镜像, 而npm publish、npm trust都不读 scope 级 registry 配置。 - 宿主接口一有变化,先看 PITFALLS.md 里有没有对应的旧坑, 再去改 ARCHITECTURE.md 的不变量一节。
