Paper Reader

这是一个 SKILL 分发包，不是全局 CLI 工具。

它通过 npx 把 paper-reader skill 安装到指定 agent 的 skills 目录里。安装完成后，agent 会读取 skill 里的 SKILL.md、模板和脚本。

安装

使用 npx 安装到指定 AGENT：

npx @rongyan/paper-reader install --target codex

npx @rongyan/paper-reader install --target claude-code

npx @rongyan/paper-reader install --target opencode

也支持直接省略 install：

npx @rongyan/paper-reader --target codex

默认安装位置：

• codex -> ${CODEX_HOME:-~/.codex}/skills/paper-reader
• claude-code -> ~/.claude/skills/paper-reader
• opencode -> ~/.config/opencode/skills/paper-reader

需要覆盖已有安装时，可加 --force：

npx @rongyan/paper-reader install --target claude-code --force

如果只想预览写入位置，可加 --dry-run：

npx @rongyan/paper-reader install --target opencode --dry-run

不存在全局安装。不要使用 npm install -g @rongyan/paper-reader。

安装内容

安装到目标 agent 后，skill 目录里只包含 skill 真正需要的内容：

• SKILL.md
• references/
• scripts/

不会把 npm 包自己的 bin/、src/、test/、README.md 安装进目标 skill 目录。

Skill 能力

这个 skill 面向 本地 TeX source 论文精读，核心能力包括：

• 只读本地 TeX source，不回退到 PDF 或联网来源
• 用 scripts/flatten_tex.js 判定主文件并展开 \input{} / \include{}
• 按 abstract / first-pass / main body / appendix / references 组织内容
• 自动推导 sources/<paper-id> -> result/<paper-id> 的输出目录
• 为 overview 图生成安全的复制目标和 Markdown 相对引用路径
• 用 scripts/prepare_markdown_assets.js 检查最终 Markdown 里的图片、链接和 HTML 资源；如果引用的是 PDF 等非图片资源，会自动转成真正的 images/*.png 并重写引用，images/ 目录里未直接引用的 PDF 也会转成同名 PNG；如果 Markdown 里有 Mermaid 代码块，会优先用全局 mmdpc 转成 images/*.png，再 fallback 到 npx --yes @rongyan/mermaid-plus-cli，两者都失败时保留原代码块
• Mermaid 转图会检查节点标签是否完整；如果渲染结果把有标签的节点退化成裸 B / C 这类 ID，会保留原 Mermaid 代码块，避免输出缺内容的图片
• 用 scripts/write_summary_json.js 从最终 Markdown 生成 paper-reader-summary.json：标题取 frontmatter 的 title，摘要取正文开头到第一个章节标题之间的内容，并通过 JSON.stringify 自动转义双引号、反斜杠和换行

版本同步

package.json 和 SKILL.md 的版本号必须保持一致。

常用命令：

npm run check:version
npm run sync:version
npm version patch

npm version ... 会先更新 package.json，然后通过包内脚本把相同版本同步回 SKILL.md。