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 的术语和高语义载荷段落。该清单处理完一个标记一个，不得凭感觉少量添加。

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。