跳至內文
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),若數量相同則取較新者。
  • 複製並修補。 基準版本的原始碼會以寫入時複製(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/ 下的殘留檔案,系統會在乾淨的資料夾中重試一次。若修改後的文件無法編譯,錯誤訊息會作為新的一輪回饋傳回給代理程式。若基準版本無法編譯,系統會忽略錯誤強制編譯到底;若仍失敗,該輪審閱將僅顯示原始碼變更。

增量編譯與排版審閱管線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):以兩邊皆唯一出現的連續八詞片段作為錨點固定對齊,保留這些錨點的最長遞增鏈,再對錨點之間的區段進行差異比對。移動位置的連續至少 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 相比:

變更項目資料夾內執行 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。