npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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 判断该版本 是否已存在(幂等),过发布闸门,自己打 tag dsh-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 的不变量一节。