lark-paper-reader-codex

name	lark-paper-reader-codex
description	Codex 专用：将 arXiv/DOI/PDF 学术论文整理为论文翻译飞书文档，正文以原文逐段中文翻译为主体。
metadata	{"requires":{"bins":["lark-cli"],"skills":["lark","ph-paper-helper"]}}

lark-paper-reader-codex

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

Codex 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 时必须默认使用 Codex 当前可用的子代理/多代理工具；不要把“是否启用多智能体”作为需要用户确认的步骤。
• 若当前环境确无可调用子代理工具，或更高优先级工具规则阻止调用，必须在 annotations.json 与 qc-report.md 说明“未启用子代理，已由 Codex 本体分批完成”及具体原因；不得把该说明写入正式 Markdown、飞书正文、callout、边注或导出的 PDF。
• 每一步都留下可恢复的 checkpoint：metadata.json、glossary.md、translated.md、figures.json、annotations.json、qc-report.md。
• 若发现已有同一论文的飞书文档，先向用户展示已有链接并暂停，除非用户明确要求重新创建。

Multi-Agent Division Of Labor

多智能体/并行工作者用于加速和交叉审查论文翻译与注释候选，但主 agent 必须统一复核、合并和落盘，不能把候选内容未经检查直接写入正式文档。

• 翻译与覆盖：按章节或段落分片生成忠实中文翻译候选，检查是否遗漏摘要、方法、实验、相关工作、结论和附录。
• 术语与边注：提取核心术语、缩写、数学概念和高语义载荷段落，生成 comment 候选与唯一定位文本。
• 注释候选：为导读、作者思考路径、图表读法、公式直觉、方法具象化、引用背景、实现映射和读者疑问生成候选。
• 图表与公式审查：核对图片顺序、caption、表格、公式 LaTeX 和飞书 XML 渲染风险。
• QC 与视觉审查：检查重复图片/评论、占位符残留、裸 XML、未渲染公式、公共文档卫生和 PDF/PNG 视觉问题。

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 说明，例如：

• “本文档采用某某模式”
• “未启用子代理 / 未启用多代理 / Codex 本体分批完成”
• 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

   • 写 translated.md，默认执行逐段忠实翻译：保留章节层级、段落顺序、公式 LaTeX、表格、图表占位和附录。
   • 不要主动改写成总结、导读、解读、评论或讲义；补充说明后续只能进入 callout/comment。
   • 独立公式保留 $$...$$，行内公式保留 $...$；不要转成 Unicode 数学符号。
   • 在图所在位置写稳定占位符，如 [图1位置: <image-file>]，后续插图后删除。
   • 长文分批写入文件，但不要依赖某个特定 agent 的 write 工具说明。

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”“未启用子代理”“未启用多代理”“Codex 本体”“工具规则”“权限判断”“translation-plan.md”“annotations.json”“qc-report.md”“lark-cli”等元说明；若命中不是论文内容，必须删除后重新导出检查。
    • 导出 PDF 并转 PNG。若当前 Codex 环境有视觉查看能力，抽样或逐页检查公式、图片、callout 和排版；否则保留 PNG/PDF 路径并说明未做视觉模型审查。
    • 修复问题后重新跑 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。