Papilot 如何建置排版審閱
深入程式碼剖析一輪審閱流程:工作樹快照、預熱 LaTeX 建置、全文逐詞對齊、SyncTeX 裁切與決定日誌。


本文追蹤 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),若數量相同則取較新者。 - 複製並修補。 基準版本的原始碼會以寫入時複製(copy-on-write,在 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/ 下的殘留檔案,系統會在乾淨的資料夾中重試一次。若修改後的文件無法編譯,錯誤訊息會作為新的一輪回饋傳回給代理程式。若基準版本無法編譯,系統會忽略錯誤強制編譯到底;若仍失敗,該輪審閱將僅顯示原始碼變更。
在頁面上找出每一處變更
原始碼中的單位。 差異比對會將內文拆分為單詞(中日韓文字則拆分為字元)。某些結構會保持為單一標記(token):註解、行內與獨立顯示的數學式、大括號群組、附帶參數的指令,以及諸如 equation、align、tabular、verbatim、minted 與 tikzpicture 等環境。僅由空白或標點符號分隔的編輯會被合併,合併後的每項編輯都成為一個具備精確原始碼範圍的獨立決定。圖片與其他二進位檔案以整個檔案為單位,而觸及同一個 .bib 條目的變更區塊也會合成單一單位。
文件差異所在。 工作行程會使用 MuPDF 擷取兩份 PDF 的文字,並逐詞對齊兩份文件(engine/src/render/effects.ts):以兩邊皆唯一出現的連續八詞片段作為錨點固定對齊,保留這些錨點的最長遞增鏈,再對錨點之間的區段進行差異比對。移動位置的連續至少 20 個字母與數字片段會被標記為搬移。比對整份文件能找出遠離編輯處的變動:重新定義巨集的每一處引用、重新編號的公式、新增的參考文獻條目。
每項編輯的位置。 編譯為 WebAssembly 並在每次建置時建立一次索引的 SyncTeX,會將每項編輯的舊行號映射到舊 PDF、新行號映射到新 PDF,進而產生頁面裁切區域;裁切邊界會落在兩份文件共用的行上。接著,每項編輯會被分類為文字變更、版面變更(以 2× 解析度進行像素比對)、搬移、排版結果相同,或無法映射。僅涉及筆跡的變更(字型、顏色、上標或下標文字)與向量繪圖會分開比對。共用同一印刷行的裁切區域會合併為一個區塊,但每項編輯仍保有各自的 Accept 與 Reject。畫面上顯示的區塊皆為向量 SVG。
排版結果完全相同的純空白編輯,會附加到同一段落中最近的實質編輯上(絕不跨越空白行、\par 或章節標題),並維持為獨立的決定。
遠離編輯處的變更(選用)。 開啟 Track indirect changes 時,落在所有編輯裁切區域外的差異,會透過編譯不同變體來追蹤成因:首先編譯本身無可見效果的編輯(例如巨集定義),接著對編輯集合進行二分編譯。系統會驗證所有成因的聯集,在每項編輯下方最多繪製三處關聯變更,其餘則依需求載入。
以日誌記錄決定
任何決定都不會直接寫入你的資料夾。每項決定都會記錄在 SQLite 日誌中,包含每次寫入的預期位元組與目標位元組,並與磁碟內容核對;若任何步驟失敗便會回滾(engine/src/core/review.ts):
- Accept 會將變更記錄於私有提交
refs/papilot/<task>/accepted中。 - Reject 會在工作樹中透過三方合併(three-way merge)還原該處變更,因此後續曾修改過的段落不會受到影響。當代理程式仍在執行時,退回操作會等到該回合結束後才生效。
- Undo 會撤銷最新的一項決定。
- Apply 會再次透過三方合併,將已接受的變更合併至你的工作檔案中。Commit 則會在持有
index.lock的情況下,確認分支未發生移動後,以git commit-tree僅將該任務的變更寫入HEAD,同時保留你原本已暫存(staged)的任何其他內容。
若在此期間手稿的相同段落發生了變動,任何內容都不會被覆寫:提案會重新變基(rebase)至目前的手稿上,並在同一個任務中作為新一輪審閱返回。
隔離機制的成本
與在相同資料夾副本中直接執行 latexmk 相比:
| 變更項目 | 資料夾內執行 latexmk | Papilot |
|---|---|---|
| 編輯單一章節 | 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。