# Lark Paper Reader Claude

> Claude Code 专用：将 arXiv/DOI/PDF 学术论文整理为论文翻译飞书文档，正文以原文逐段中文翻译为主体。

- Skill: `justcyl/lark-paper-reader-claude` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add justcyl/lark-paper-reader-claude`
- Raw SKILL.md: https://api.skillmd.com/api/skills/justcyl/lark-paper-reader-claude/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: justcyl (https://skillmd.com/u/justcyl)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/justcyl/lark-paper-reader-claude

---


# lark-paper-reader-claude

把一篇论文整理成可直接阅读的论文翻译飞书文档。唯一交付形态是：以原论文正文的中文逐段忠实翻译为主体，按原论文结构保留正文顺序，原位保留图、表、公式、算法和附录；必要的导读、作者思考路径、图表读法、公式直觉、术语边注、引用背景、代码映射等内容只作为辅助说明，不能替代翻译正文。默认直接使用 Claude Code 的 Agent 工具（subagent）并行生成候选，不逐次询问是否启用多智能体。若当前环境确无 Agent 工具可用（例如被权限策略禁用），才降级为主 agent 本体分批处理，并且降级记录只写入内部 checkpoint/QC，不写入正式文档。

## Claude Code Principles

- 使用当前工作区下的 `work/lark-paper-reader/<paper-id>/` 保存中间文件；只把最终可交付产物放入 `outputs/`。
- 需要读取配套细节时再打开 references：风格标准见 `references/style-standard.md`，飞书 XML 与公式规则见 `references/lark-doc-rules.md`，注释层规则见 `references/annotate.md`，质量检查见 `references/qc.md`。
- 执行本 skill 时必须默认使用 Agent 工具派生 `general-purpose` subagent 做并行工作；不要把"是否启用多智能体"作为需要用户确认的步骤。相互独立的 subagent 在同一条消息里并行发起。
- subagent 无法与用户交互，也看不到主对话上下文；给 subagent 的 prompt 必须自包含：论文工作目录绝对路径、分片范围、术语表路径、输出文件绝对路径和格式约定都要写清楚。
- 若当前环境确无 Agent 工具可用，或权限策略阻止调用，必须在 `annotations.json` 与 `qc-report.md` 说明"未启用子代理，已由主 agent 分批完成"及具体原因；不得把该说明写入正式 Markdown、飞书正文、callout、边注或导出的 PDF。
- 每一步都留下可恢复的 checkpoint：`metadata.json`、`glossary.md`、`translated.md`、`figures.json`、`annotations.json`、`qc-report.md`。
- 若发现已有同一论文的飞书文档，先向用户展示已有链接并暂停，除非用户明确要求重新创建。

## Multi-Agent Division Of Labor

subagent 用于加速和交叉审查论文翻译与注释候选，但主 agent 必须统一复核、合并和落盘，不能把候选内容未经检查直接写入正式文档。写飞书（`lark-cli` 创建/更新/插图/评论）统一由主 agent 执行，subagent 只产出候选文件。

- 翻译与覆盖：按章节或段落分片给多个 subagent 生成忠实中文翻译候选，每个 subagent 写入独立分片文件（如 `translated-part-01.md`）；主 agent 合并前检查是否遗漏摘要、方法、实验、相关工作、结论和附录。
- 术语与边注：subagent 提取核心术语、缩写、数学概念和高语义载荷段落，生成 comment 候选与唯一定位文本。
- 注释候选：subagent 为导读、作者思考路径、图表读法、公式直觉、方法具象化、引用背景、实现映射和读者疑问生成候选。
- 图表与公式审查：subagent 核对图片顺序、caption、表格、公式 LaTeX 和飞书 XML 渲染风险。
- QC 与视觉审查：subagent 检查重复图片/评论、占位符残留、裸 XML、未渲染公式、公共文档卫生；视觉审查时把导出的 PNG 页面路径交给 subagent 用 Read 工具逐页查看。

## Translation-First Contract

本 skill 的正式文档首先是一份论文原文翻译；注释内容只是放在翻译旁边的阅读辅助。执行时必须先完成可独立阅读的逐段翻译主体，再添加 callout/comment。

- 正文段落必须对应原文段落、列表、图注、表注、算法、公式说明和附录段落；不要用"本文主要讲了什么"的解读段落替代原文翻译。
- `translated.md` 只承载翻译主体和图表/公式占位；导读、作者思考路径、公式解读、图表读法、引用背景、代码映射和读者疑问不得写进正文段落。
- 允许对极难直译的长句做忠实中文化表达，但不能压缩论证链、合并多个原文段落、提前重排逻辑，或把细节改写成总结。
- 如果某些非正文材料只能做忠实转述而非逐字翻译，必须限于表格结构、伪代码、公式说明、PDF 抽取损坏片段等技术原因，并在 `qc-report.md` 记录。
- 注释内容必须锚定到已有翻译段落、公式、图、表、算法或引用之后；它是"在翻译旁补充说明"，不是另起一份讲义或总结。

## Public Document Hygiene

正式读者文档只承载论文内容和面向读者的注释层。`translated.md`、传给飞书的 Markdown/XML、飞书正文、callout、comment 和导出的 PDF/Markdown 中，严禁出现执行过程、工具限制、权限判断、代理使用状态或 checkpoint/QC 说明，例如：

- "本文档采用某某模式"
- "未启用子代理 / 未启用多代理 / 主 agent 分批完成 / subagent"
- `translation-plan.md`、`annotations.json`、`qc-report.md`、`lark-cli` 等内部产物或命令说明

这些信息只能出现在内部 checkpoint/QC 文件和最终给用户的交付说明中。若某个禁用词本身是论文原文、题名、引用或代码仓库内容，允许保留，但必须在 `qc-report.md` 标注为论文内容命中。

## Body Translation Contract

- `translated.md` 的正文层必须以原文结构为准：按章节、段落、列表、图注、表注、附录原序翻译，不主动压缩、不主动重排、不用总结替代原文。
- 注释内容不能改写或替代正文。导读、作者思考路径、图表读法、公式直觉、引用背景、实现映射和读者疑问必须进入 callout/comment，不混入原文翻译段落。
- 术语可以统一译名，但不要把术语表内容扩写进正文；正文只负责翻译原文，不负责讲解原文。

## Annotation Contract

注释内容的目标不是压缩论文，也不是另写一篇讲义，而是在完整原文翻译旁边补充理解线索。所有注释必须锚定到具体翻译段落、公式、图、表、算法或引用，帮助读者回到原文继续读；不得用摘要替代原文、删减关键限定、把辅助推断写成作者结论。

新增解释必须区分三类来源：

- **原文明确说的**：必须优先进入正文翻译或图注/表注翻译。
- **由原文和已有背景推出的阅读辅助**：必须写成 callout/comment，并使用"可以理解为""可能的直觉是"等限定语。
- **工具执行或工作流信息**：只能写入内部 checkpoint/QC，不进入正式文档。

## Single Deliverable

用户给出 arXiv ID、DOI、论文 PDF 或论文 URL 时，只产出一种文档：论文翻译飞书文档。不存在"只翻译不注释"的分支；但注释必须放在完整翻译旁边，不能把正文改造成纯解读稿。如果用户明确要求不要上传飞书或只要本地短答，再退出本 skill，改用普通回答或 `ph-paper-helper`。

## Quality Bars

- 主文正文必须逐段覆盖：摘要、引言、预备知识/背景、方法、实验、相关工作、结论。
- 原文中的图、表、算法、公式、脚注、图注、表注必须保留；大型表格可在飞书中用表格或等价 Markdown 表达，不能只写"见表"。
- 附录默认覆盖到同等层级；若因篇幅只翻译附录要点，必须在 `qc-report.md` 和最终回复中明确标为"非完整附录翻译"。
- 元信息与作者/机构/代码链接。
- 导读 callout：核心问题、本文答案、预备知识速查、阅读路径建议。
- 正文中文逐段翻译，保留原论文章节顺序和段落级论证链。
- 图、表、公式、算法原位插入，并补充中文图注/表注。
- 图表读法 callout：核心图表后必须解释图表元素、读图顺序、它支撑的论点、不能过度解读的边界，以及读完图表后应回到哪一节继续读。目标是让用户即使先看图表，也能被引导回论文正文。
- 公式直觉 callout：解释关键公式为什么这样设计、解决什么问题。
- 方法具象化 callout：把抽象机制映射到一个可理解例子。
- 作者思考路径 callout：在正式方法章节前，基于论文之前已有背景、失败模式、经验观察和相关工作，重建作者可能如何想到这个 idea。不得把论文自己的贡献、方法名、实验结果作为前提；必须标注为阅读辅助推断，而不是作者真实心理记录。
- 关键引用背景：展开 3 到 5 篇对理解论文最重要的一跳引用。
- 若有代码仓库，做代码映射：仓库结构、关键文件、论文模块到实现位置、必要代码片段。
- 实验读法：主结果、消融、扩展实验、局限和失败案例。
- 附录覆盖：实验细节、额外结果、案例研究、局限，不要只停在主文。

## Input Normalization

接受：

- `2604.14010`
- `arxiv://2604.14010`
- `https://arxiv.org/abs/2604.14010`
- `https://arxiv.org/pdf/2604.14010`
- `doi://10.48550/arXiv.2604.14010`

统一转成 `ph` 可接受的 URI，例如 `arxiv://2604.14010` 或 `doi://...`。为文件路径生成安全 ID 时，将 `/`、`:`、`.` 等替换成 `_`。

## Workflow

1. **Preflight**
   - 运行 `lark-cli auth status` 确认飞书登录。
   - 运行 `uv run --project "$HOME/project/ph2" ph --version` 确认 `ph` 可用。
   - 建立工作目录：`work/lark-paper-reader/<safe-paper-id>/`。

2. **Duplicate Check**
   - 用论文 ID 搜索飞书：`lark-cli docs +search --query "$ARXIV_ID" --as user`。
   - 搜索结果在 `data.results` 中，不是 `items`。
   - 若标题或摘要命中同一 ID，向用户展示文档标题和 URL，并停止等待确认。

3. **Fetch Paper Source**
   - `ph import --input <paper-uri>` 只用于入库和元信息补全。
   - 对 arXiv 论文，默认下载 arXiv PDF 与 e-print LaTeX source：`https://arxiv.org/pdf/<id>` 与 `https://arxiv.org/e-print/<id>`。
   - 解包 source，优先从 `.tex`、`.bbl/.bib`、`figures/`、`00README.json` 构建正文、图片、公式、表格和引用清单；原始 PDF 只用于核对分页/文本和视觉导出。
   - 只有当 arXiv source 不可用、不是 LaTeX、缺关键图片/表格，或用户提供的是非 arXiv PDF/DOI 时，才 fallback 到 MinerU：`ph fetch --paper-id <paper-uri> --force --include-content`。
   - fallback 到 MinerU 时，从返回的 `full_text_path` 推导 `PAPER_DIR`，不要手拼 ph 缓存路径；并在 `metadata.json`、`translation-plan.md`、`qc-report.md` 记录触发原因。

4. **Plan The Document**
   - arXiv source 路径：从主 `.tex` 提取标题、作者、年份、摘要、章节、图片引用、公式、表格、算法、参考文献和 GitHub URL；从 PDF 文本抽取核对章节顺序。
   - MinerU fallback 路径：从 `full.md` 提取标题、作者、年份、摘要、章节、图片引用、公式、参考文献和 GitHub URL。
   - 写 `metadata.json`、`figures.json` 和 `translation-plan.md`。
   - 在 `translation-plan.md` 首行写明 `Deliverable: 论文翻译飞书文档`，并列出正文翻译覆盖项与注释覆盖项。
   - 必须先读取 `references/style-standard.md`，并在 `translation-plan.md` 写入 `Style baseline: 面向大语言模型的离策略基于价值强化学习`。后续正文、callout、图表读法、公式直觉、术语表和 QC 都按该风格标准执行。
   - 建立 `glossary.md`：A 类使用中文共识译名，B 类首次出现写"中文（英文全称，缩写）"，C 类保留英文。
   - 必须写 `annotation-plan.json`：列出待加 callout 的作者思考路径、图表读法、公式/方法步骤/引用/疑问，以及待加 comment 的术语和高语义载荷段落。该清单处理完一个标记一个，不得凭感觉少量添加。

5. **Translate**
   - 按章节分片并行派生翻译 subagent；每个 subagent 的 prompt 必须包含：源文件绝对路径与分片范围、`glossary.md` 绝对路径、翻译契约要点（逐段忠实翻译、保留 `$...$`/`$$...$$`、图占位符格式 `[图N位置: <image-file>]`）、输出分片文件绝对路径。
   - 主 agent 逐片复核后合并为 `translated.md`：保留章节层级、段落顺序、公式 LaTeX、表格、图表占位和附录；检查分片接缝处无遗漏、无重复。
   - 不要主动改写成总结、导读、解读、评论或讲义；补充说明后续只能进入 callout/comment。
   - 独立公式保留 `$$...$$`，行内公式保留 `$...$`；不要转成 Unicode 数学符号。
   - 在图所在位置写稳定占位符，如 `[图1位置: <image-file>]`，后续插图后删除。
   - 长文分批用 Write/Edit 写入文件。

6. **Create Lark Doc**
   - 用 `lark-cli docs +create --api-version v2 --doc-format markdown --content @translated.md --parent-position my_library --as user` 创建文档。
   - 创建后用 `drive files patch` 修复内部标题和 Drive 文件名。
   - 在标题后插入论文元信息 callout：标题、作者、年份、arXiv/DOI、PDF 链接、创建时间。
   - Fetch XML 验证公式实际状态；如果公式仍是字面 `$...$` 或 `$$...$$`，按 `references/lark-doc-rules.md` 修复。

7. **Insert Figures**
   - 只插入正文实际引用的图片；arXiv source 路径以 `.tex` 的 `\includegraphics` 顺序为准，MinerU fallback 路径以 `full.md` 引用顺序为准。
   - 对 PDF/EPS/SVG 图先本地转换为 PNG，写入工作区 `images/`，再插入飞书。
   - `lark-cli docs +media-insert --file` 要求从图片目录执行，传相对文件名。
   - 用图片前后唯一中文文本定位；若歧义，改用更长的 `start...end` anchor。
   - 插入完成后 fetch XML 删除所有 `[图X位置...]` 占位符块。

8. **Add Annotation Layer**
   - 每次执行本 skill 都必须添加注释层。
   - 必须先读取 `references/annotate.md` 并执行其中的 5-PRE 扫描：fetch 文档 XML/with-ids，列出公式、方法步骤、重要引用、长段落、术语首次出现，写入 `annotation-plan.json`。
   - 额外解释（导读、作者思考路径、图表读法、公式直觉、具象化、引用背景、实现要点、读者疑问）必须作为飞书原生 XML `<callout>` 块插入到对应 block 后，不能写成正文 Markdown blockquote，也不能把解释混入翻译正文。
   - 图表读法必须插在对应图片/表格及其中文图注/表注之后；作者思考路径必须插在正式方法章节之前，通常位于引言/相关工作之后。
   - 边注必须用飞书 comment，锚定到具体术语或具体段落；优先 `--selection-with-ellipsis` 唯一定位，歧义时 fetch with-ids 后用 `--block-id`，不得用全文评论冒充边注。
   - 必须有足量边注：至少覆盖所有核心术语首次出现，并覆盖语义载荷高的关键段落；少于 8 条 comment 时必须在 `qc-report.md` 说明论文很短或定位失败原因。
   - 若论文有 GitHub 仓库，浅克隆到工作目录，先写架构地图，再把关键实现片段以内嵌代码块加入 `🔧` callout。

9. **References**
   - 只展开 3 到 5 篇高价值 1-hop 引用：理论基础、主要 baseline、被反复比较的工作。
   - 用 `ph search` 或 `ph fetch` 获取元信息和必要摘要，不要为了装饰性引用拉太多论文。

10. **Quality Check (QC) And Visual Gate**
    - QC 指 Quality Check / 质量检查，用来在交付前确认文档结构、公式、图表、注释层、飞书导出和正式文档卫生没有明显问题。
    - 按 `references/qc.md` 跑结构检查：重复图片、重复评论、占位符残留、裸 XML、公式字面残留、关键章节缺失。
    - 翻译主体检查：正文是否仍是按原论文结构逐段翻译，是否有用总结、导读、解读或讲义替代原文翻译的段落；发现后必须恢复为翻译正文。
    - 注释覆盖检查：是否包含导读、作者思考路径、图表读法、公式直觉、引用背景、实验读法、局限、代码映射（若有仓库）和附录覆盖；同时检查这些注释没有混入正文翻译段落。
    - 风格一致性检查：按 `references/style-standard.md` 对照标题层级、段落长度、callout 类型、图表/公式解读格式、术语表和最终汇报口径；若明显偏离，修复后重跑 QC。
    - 正式文档卫生检查：fetch/export 后搜索"本文档采用""Mode""未启用子代理""未启用多代理""主 agent 分批""subagent""工具规则""权限判断""translation-plan.md""annotations.json""qc-report.md""lark-cli"等元说明；若命中不是论文内容，必须删除后重新导出检查。
    - 导出 PDF 并转 PNG，用 Read 工具（或派生视觉审查 subagent）逐页或抽样检查公式、图片、callout 和排版；Claude Code 具备图片查看能力，视觉检查默认必须执行，不得以"无视觉能力"为由跳过。
    - 修复问题后重新跑 QC，最终给用户飞书链接、PDF/PNG 检查结果和残余风险。

## Lark Command Notes

- `--api-version v2` 只用于 `docs +create` 的 Markdown 建文档。fetch、update、block 操作使用默认版本。
- `docs +create --title` 可能只设置 Drive 文件名；创建后用 `drive files patch` 设置最终标题。
- `block_replace` 写 XML 时不要在 `<p>` 里包 `<text>` 子元素；对行内公式使用 `<latex>...</latex>`。
- callout 里的公式必须写成 `<latex>...</latex>`，不要写 Markdown `$...$`。
- 多行代码块用 `<pre lang="python"><code>...</code></pre>`，可以放在 `<callout>` 内。

## Deliverable

最终回复包含：

- 飞书文档标题和链接。
- 确认为论文翻译飞书文档。
- 是否发现重复文档，以及用户是否要求重建。
- 图片数量、评论数量、callout 覆盖简报，特别说明作者思考路径与图表读法是否覆盖。
- 质量检查（QC）结果和是否完成 PDF/PNG 视觉检查。
- 如果某一步因权限、导出或工具缺失失败，明确说明失败点和可恢复的本地 checkpoint。