Papilotが組版済みレビューを構築する仕組み
ワークツリーのスナップショット、ウォームなLaTeXビルド、ドキュメント全体の単語アライメント、SyncTeXによる切り抜き、採否判断ジャーナルまで、コードで辿る1回のレビューラウンド。


この記事では、エージェントによる最後のファイル書き込みから紙面での採否判断まで、Papilotのコード内で1回のレビューラウンドがどのように処理されるかを追います。パスはリポジトリを指し、数値はXeLaTeX、BibTeX、mintedを使用し、\includeで章を分割した240 MBの学位論文で計測したdocs/performance.mdに基づいています。
ワークツリーとスナップショット
各タスクは、未コミットの編集も含めた原稿のスナップショットから作成されるデタッチ状態のGitワークツリーです(engine/src/core/tasks.ts)。エージェントは、そのワークツリーを作業ディレクトリおよびサンドボックスとして実行されます。
ラウンドは、ワークツリーをGitツリーとして記録することから始まります。ラウンドごとに学位論文全体をハッシュ化すると遅いため、スナップショットはワークツリーのGitディレクトリ内にある専用インデックスファイルpapilot/snapshot-indexを経由します(原稿側にも専用の.git/papilot/working-indexがあります)。このインデックスは前回のスナップショットまたはリポジトリのインデックスを初期値とするため、Gitはサイズまたは更新日時が変わったファイルのみを再ハッシュ化します。各スナップショットは2回取得して比較されるため、保存途中のファイルによってディスク上に一度も存在しなかったツリーが生成されることはありません。この学位論文では、スナップショットの所要時間が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パス、BibTeX実行2回)から25.8 s(1パス)に短縮されました。
ターン終了前の先行処理。 エージェントがファイルを書き込むたびに投機的ビルドと比較が開始され、次の書き込みがあるとキャンセルされます(engine/src/core/publish.ts)。そのため、エージェントが停止した時点ではラウンドのレンダリングがすでに完了していることが多くなります。
1台のマシンで2つのTeX実行。 原稿のプレビュー、各タスクのラウンド、および投機的ビルドは、全プロセス間で2つのTeXスロットを共有します。優先度の高い実行が待機している場合、優先度の低い実行はSIGSTOPで一時停止され、後で再開されます(engine/src/core/pool.ts)。
ビルド失敗時の処理。 エラーがbuild/配下の残存ファイルを指しているビルドは、クリーンなフォルダから1回再試行されます。改訂版のドキュメントがコンパイルできない場合、エラーは次のターンとしてエージェントに返されます。ベースラインがコンパイルできない場合はエラーを無視してコンパイルを続行し、それでも失敗した場合はソースの変更のみを表示します。
紙面上の各変更箇所の特定
ソース内の単位。 差分処理では、本文を単語単位(CJKテキストでは文字単位)に分割します。コメント、インライン数式とディスプレイ数式、波括弧グループ、引数付きコマンド、およびequation、align、tabular、verbatim、minted、tikzpictureなどの環境は、単一のトークンとして扱われます。空白や句読点のみで隔てられた編集は結合され、結果として得られる各編集が正確なソース範囲を持つ1つの採否判断単位になります。画像やその他のバイナリファイルはファイル全体で1単位となり、同じ.bibエントリに触れる変更ブロックも1単位にまとめられます。
ドキュメント間の相違箇所。 ワーカープロセスがMuPDFで両方のPDFからテキストを抽出し、2つのドキュメントを単語単位でアライメントします(engine/src/render/effects.ts)。固有の8単語の連続をアンカーとして対応付け、それらのアンカーの最長増加列を保持し、アンカー間のギャップの差分を取ります。20文字以上の英数字の連続が移動した場合は、移動として報告されます。ドキュメント全体を比較することで、再定義されたマクロのすべての使用箇所、番号が振り直された数式、新しい参考文献エントリなど、編集箇所から離れた場所に生じた変更も検出できます。
各編集の位置特定。 WebAssemblyにコンパイルされビルドごとに1回インデックス化されるSyncTeXが、各編集の旧行を旧PDFに、新行を新PDFにマッピングし、ページの切り抜き領域を生成します。切り抜きは両方のドキュメントで共通する行で区切られます。その後、各編集はテキストの変更、レイアウトの変更(2×でのピクセル比較)、移動、組版結果同一、またはマッピング不可に分類されます。インクのみの変更(フォント、色、上付きや下付きなどの位置変化)とベクター描画は個別に比較されます。印字された同じ行を共有する切り抜きは1つの領域に統合されますが、各編集は個別のAcceptとRejectを保持します。画面上のストリップはベクター形式のSVGです。
組版結果が同一になる空白のみの編集は、同じ段落内の最も近い実質的な編集に紐付けられます(空行、\par、セクション見出しをまたぐことはありません)が、採否判断としては独立したままになります。
編集箇所から離れた変更(オプション)。 Track indirect changesをオンにすると、各編集の切り抜き領域外にある差異は、バリアントをコンパイルすることで原因が追跡されます。まずマクロ定義など単体では視覚的変化を持たない編集を試し、次に編集セットを半分ずつ試します。原因の和集合が検証され、各編集の下に最大3箇所まで描画され、残りはオンデマンドで読み込まれます。
ジャーナルとしての採否判断
採否判断が作業フォルダを直接書き換えることはありません。各判断は、すべての書き込みの期待バイト列と対象バイト列とともにSQLiteジャーナルに記録され、ディスクと照合され、いずれかのステップが失敗した場合はロールバックされます(engine/src/core/review.ts)。
- Acceptは、変更をプライベートコミット
refs/papilot/<task>/acceptedに記録します。 - Rejectは、3ウェイマージによってワークツリー内の変更を取り消すため、それ以降に編集された箇所はそのまま保たれます。エージェントが作業中の場合、却下処理はそのターンが終わるまで待機します。
- Undoは、直前の判断を取り消します。
- Applyは、承認された変更を再び3ウェイマージで作業ファイルに統合します。Commitは、ブランチが移動していないことを確認した上で、
index.lockを保持しながらgit commit-treeでタスクの変更のみをHEADに書き込み、すでにステージングされていた他の変更はそのまま維持します。
その間に原稿の同じ箇所が変更されていた場合でも、上書きされることはありません。提案内容は現在の原稿に対してリベースされ、同じタスク内の新しいレビューとして戻されます。
分離に伴うコスト
同じフォルダのコピー内で実行したlatexmkとの比較は以下の通りです。
| 変更内容 | フォルダ内のlatexmk | Papilot |
|---|---|---|
| 1つの章を編集 | 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の準備が完了しました。