跳到正文
Papilot

Papilot 如何构建排版级审阅

深入代码追踪一轮审阅:工作树快照、热缓存 LaTeX 编译、全文按词对齐、SyncTeX 裁切与审阅决定日志。

Papilot 团队6 分钟阅读
Papilot 产品示意图:展示论文页面原位的修改前后排版对比,以及接受、拒绝、评论与源码切换按钮。Papilot 产品示意图:展示论文页面原位的修改前后排版对比,以及接受、拒绝、评论与源码切换按钮。
一轮审阅:每处修改在排版前后的对比,支持 Accept、Reject 与 Comment。

本文追踪一次审阅轮次在 Papilot 代码中的完整流程:从智能体最后一次写入文件,到你在页面上做出决定。文中的路径对应 代码仓库;性能数据取自 docs/performance.md,测量对象是一篇 240 MB 的学位论文(使用 XeLaTeX、BibTeX、minted,并通过 \include 拆分章节)。

工作树与快照

每个任务都是一个分离的 Git 工作树(worktree),由手稿的快照创建,其中包含未提交的修改(engine/src/core/tasks.ts)。智能体将该工作树作为工作目录和沙箱运行。

每一轮审阅开始时,首先将工作树记录为 Git 树对象。如果每轮都对整篇论文重新计算哈希会非常慢,因此快照通过工作树 Git 目录下的私有索引文件 papilot/snapshot-index 生成(手稿本身也有独立的 .git/papilot/working-index)。该索引以上一轮快照或仓库索引为初始状态,因此 Git 只会对文件大小或修改时间发生变化的文件重新计算哈希。每次快照都会取两次并比对,防止文件保存一半时产生磁盘上从未真实存在过的树状态。在这篇学位论文上,生成快照的耗时从 2.1 s 降至 0.1 s。

双侧同时编译

每次编译都在各自的目录中运行,目录名由所编译的内容决定,从而保证 SyncTeX 始终指向屏幕上 PDF 对应的确切源码。如果每次都从空目录开始,就会丢弃 latexmk 的缓存状态,因此新目录会基于最接近的已有编译目录创建(engine/src/core/build.ts):

  • 选择基准目录。 在最近 16 次章节相同、编译器设置和编译器版本一致的无错编译中,选出其树对象与新树对象差异文件数最少(git diff-tree)的那一次;若数量相同则取较新的一次。
  • 克隆并修补。 基准目录的源文件通过写时复制克隆(APFS 上使用 cp -c -R)。删除不在新树中的文件,保留 Git 对象和大小均相同的文件,其余文件通过单次 git cat-file --batch 流式写入。LaTeX 的输出文件通过 COPYFILE_FICLONE 克隆。导出整篇论文耗时 0.76 s;复制 LaTeX 状态耗时 0.06 s。
  • 保留 latexmk 状态。 .aux、.bbl、.fdb_latexmk、minted 缓存及其余辅助文件(除 .fls 外)全部保留。这些文件内部记录的路径包含目录的 32 字符缓存键。由于所有缓存键长度相同,直接按字节替换旧键即可保持 SyncTeX 数据中的偏移量有效(对 .synctex.gz 先解压再重新压缩)。随后 latexmk 会像在你的本地目录中一样,自行判断需要运行哪些步骤。

按章编译轮次。 当主文件通过 \include 引入章节且所有变更文件都属于这些章节时,修改前后两侧均只对变更章节执行单次 \includeonly 编译。未变更章节的 .aux 文件取自任务基准版本的完整编译结果,从而保证公式编号、交叉引用和文献引用准确无误。两侧同时编译,并使用相同的 SOURCE_DATE_EPOCH(当前轮次日期的 UTC 正午,配合 FORCE_SOURCE_DATE=1),使 \today 不会产生额外差异。学位论文的单章编译耗时从 68.7–88.5 s(3 次编译遍历、2 次 BibTeX 运行)降至 25.8 s(1 次编译遍历)。

在回合结束前预编译。 智能体每写入一个文件,就会启动一次投机编译与比对;若智能体继续写入下一个文件,则取消当前投机任务(engine/src/core/publish.ts)。因此当智能体停止运行时,当前轮次的排版结果往往已经就绪。

单机双 TeX 并发槽位。 手稿预览、所有任务的审阅轮次以及投机编译在所有进程间共享两个 TeX 执行槽位。当优先级更高的编译任务等待时,系统会通过 SIGSTOP 暂停优先级较低的任务,稍后再恢复执行(engine/src/core/pool.ts)。

故障处理。 如果编译报错指向 build/ 下的残留文件,系统会在全新目录中重试一次。如果修改后的文档无法通过编译,错误信息会作为新回合发回给智能体。如果基准文档无法通过编译,系统会强制跳过错误继续编译;若仍然失败,该轮审阅将仅展示源码差异。

增量编译与排版审阅流水线Papilot 如何在 Git 工作树中为任务创建快照、基于热缓存 LaTeX 状态编译两个版本、比对排版后的文档并记录每项决定。增量编译与排版审阅流水线01 / Git 工作树隔离任务修改私有 Git 增量快照索引。02 / 种子增量构建克隆并编译热缓存状态,双侧同时编译。03 / 差异归属引擎生成版面对比正文偏移与原子公式保护。04 / 可撤销日志逐条拍板决定点击应用前绝不改动原稿。点击应用或提交前,主工作目录保持原样。 增量编译与排版审阅流水线Papilot 如何在 Git 工作树中为任务创建快照、基于热缓存 LaTeX 状态编译两个版本、比对排版后的文档并记录每项决定。增量编译与排版审阅流水线01 / Git 工作树隔离任务修改私有 Git 增量快照索引。02 / 种子增量构建克隆并编译热缓存状态,双侧同时编译。03 / 差异归属引擎生成版面对比正文偏移与原子公式保护。04 / 可撤销日志逐条拍板决定点击应用前绝不改动原稿。点击应用或提交前,主工作目录保持原样。
一轮审阅:快照、编译、比对、决定。

在页面上定位每一处修改

源码中的比对单元。 差异比对将正文拆分为单词(中日韩文本拆分为字符)。以下结构保持为单个词元(token):注释、行内与行间数学公式、花括号组、带参数的命令,以及 equation、align、tabular、verbatim、minted 和 tikzpicture 等环境。仅被空格或标点隔开的修改会合并为一处,最终每处修改对应一个带有精确源码范围的审阅决定。图片等二进制文件以整个文件为单元,涉及同一个 .bib 条目的多处修改也会合并为一个单元。

定位文档差异。 工作进程使用 MuPDF 提取两侧 PDF 的文本,并按词对齐两份文档(engine/src/render/effects.ts):以文档中唯一出现的连续 8 个词作为锚点将两侧锁定,保留这些锚点构成的最长递增链,再对锚点之间的区间进行差异比对。至少包含 20 个字母或数字的连续文本若发生位置移动,会被识别为移动(move)。通过全文比对,可以找出修改位置之外引发的连锁变化:重定义宏的每一处调用、重新编号的公式,以及新增的参考文献条目。

定位每处修改的版面位置。 编译为 WebAssembly 的 SyncTeX 在每次构建后建立一次索引,将每处修改的旧行号映射到旧 PDF、新行号映射到新 PDF,从而生成页面裁切区域(crop);裁切边界取在两份文档共有的文本行处。随后,每处修改会被归类为:文本变更、版面变更(2× 分辨率像素比对)、位置移动、排版结果完全相同,或未映射。仅涉及油墨外观的变化(字体、颜色、文本上标或下移)以及矢量图形会单独比对。共享同一印刷行的多个裁切区域会合并为一个展示区域,但每处修改仍保留各自独立的 Accept 和 Reject 操作。屏幕上展示的对比条均为矢量 SVG。

如果一处仅涉及空白符的修改在排版后毫无差异,它会附着到同一段落内最近的实质修改上(绝不跨越空行、\par 或章节标题),同时依然作为一项独立的审阅决定。

修改位置之外的间接变更(可选)。 开启 Track indirect changes 后,对于落在所有修改裁切区域之外的版面差异,系统会通过编译不同变体来追踪其成因:首先测试自身无直接可见效果的修改(例如宏定义),然后采用二分法测试修改集合的各个子集。验证所有成因的并集后,每处修改下方最多直接绘制三处关联变化,其余部分按需加载。

将决定记录为日志

你的任何审阅决定都不会直接改写工作目录。每项决定都会记录到 SQLite 日志中,保存每次写入的预期字节与目标字节,写入前与磁盘内容核对,若任一步骤失败则完整回滚(engine/src/core/review.ts):

  • Accept 将该处修改记录到私有提交 refs/papilot/<task>/accepted 中。
  • Reject 通过三方合并在工作树中撤销该处修改,从而保留此后在同一区域做出的其他编辑。当智能体正在运行时,拒绝操作会等待当前回合结束后再执行。
  • Undo 撤回最近一次审阅决定。
  • Apply 同样通过三方合并,将已接受的修改合并到你的工作文件中。Commit 在持有 index.lock 并确认分支未发生移动后,使用 git commit-tree 仅将该任务的修改写入 HEAD,同时保留你在暂存区(stage)中的任何其他内容。

如果在此期间手稿的相同段落发生了改动,任何内容都不会被覆盖:系统会将修改提议变基(rebase)到当前手稿上,并在同一任务中生成新一轮审阅。

隔离机制的开销

与在相同目录副本中直接运行 latexmk 对比:

变更操作目录内直接运行 latexmkPapilot
修改一个章节69.2 s,1 遍71.2 s,1 遍
修改 TeX 不读取的文件0.2 s,无需操作1.9 s,不运行 TeX
打开论文项目0.2 s,无需操作71.3 s,1 遍

从智能体完成编辑到审阅轮次就绪耗时 23.1–47.2 s。在长达 150 s 的人工审阅过程中,系统会预先编译下一版手稿,因此提交后仅需 0.8 s 即可生成最终 PDF。