본문으로 건너뛰기
Papilot

Papilot이 조판된 리뷰를 빌드하는 방법

코드로 따라가는 한 번의 리뷰 라운드: 워크트리 스냅샷, 웜 LaTeX 빌드, 전체 문서 단어 정렬, SyncTeX 크롭, 그리고 결정 저널.

Papilot 팀읽는 시간 5분
조판된 수정 전후 PDF 비교 화면과 수락, 거절, 코멘트, LaTeX 소스 보기 동작을 보여 주는 Papilot 제품 화면 예시.조판된 수정 전후 PDF 비교 화면과 수락, 거절, 코멘트, LaTeX 소스 보기 동작을 보여 주는 Papilot 제품 화면 예시.
리뷰 라운드: 각 편집의 전후 조판 결과와 Accept, Reject, Comment.

이 글에서는 에이전트가 마지막으로 파일을 기록한 시점부터 화면의 페이지에서 결정을 내리기까지, Papilot의 코드를 따라 한 번의 리뷰 라운드가 진행되는 과정을 살펴봅니다. 경로는 저장소를 가리키며, 수치는 XeLaTeX, BibTeX, minted를 사용하고 \include로 장을 나눈 240 MB 크기의 학위 논문에서 측정한 docs/performance.md에서 가져왔습니다.

워크트리와 스냅샷

각 태스크는 아직 커밋하지 않은 수정 사항을 포함한 원고의 스냅샷에서 생성된 분리된(detached) Git 워크트리입니다(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패스, BibTeX 2회 실행)에서 25.8 s(1패스)로 단축되었습니다.

턴이 끝나기 전에. 에이전트가 파일을 쓸 때마다 투기적(speculative) 빌드와 비교가 시작되며, 다음 파일 쓰기가 발생하면 이전 작업은 취소됩니다(engine/src/core/publish.ts). 따라서 에이전트가 멈출 때쯤이면 라운드 렌더링이 이미 끝나 있는 경우가 많습니다.

한 대의 머신, 두 개의 TeX 실행. 원고 미리보기, 모든 태스크의 라운드, 투기적 빌드는 모든 프로세스에 걸쳐 두 개의 TeX 슬롯을 공유합니다. 더 급한 실행이 대기 중이면 덜 급한 실행을 SIGSTOP으로 일시 중지했다가 나중에 재개합니다(engine/src/core/pool.ts).

실패 처리. 오류가 build/ 아래에 남은 파일을 가리키는 빌드는 깨끗한 폴더에서 한 번 재시도합니다. 수정된 문서가 컴파일되지 않으면 오류는 새 턴으로 에이전트에게 전달됩니다. 기준(baseline) 문서가 컴파일되지 않으면 오류를 넘기며 끝까지 컴파일하고, 그마저 실패하면 해당 라운드는 소스 변경 사항만 표시합니다.

증분 조판 검토 파이프라인Papilot이 Git 워크트리에 태스크 스냅샷을 찍고, 웜 LaTeX 상태에서 두 버전을 빌드하며, 조판된 문서를 비교하고 각 결정을 기록하는 과정.증분 조판 검토 파이프라인01 / Git 워크트리작업 수정 격리전용 Git 증분 스냅샷 인덱스.02 / 시드 빌드복제 및 컴파일웜 상태, 양쪽 동시 빌드.03 / 비교 엔진조판 전후 비교본문 오프셋과 수식 보존.04 / 검토 저널주석별 수락 결정적용 전까지 원본을 보호.적용·커밋 전까지 작업 폴더는 그대로 유지. 증분 조판 검토 파이프라인Papilot이 Git 워크트리에 태스크 스냅샷을 찍고, 웜 LaTeX 상태에서 두 버전을 빌드하며, 조판된 문서를 비교하고 각 결정을 기록하는 과정.증분 조판 검토 파이프라인01 / Git 워크트리작업 수정 격리전용 Git 증분 스냅샷 인덱스.02 / 시드 빌드복제 및 컴파일웜 상태, 양쪽 동시 빌드.03 / 비교 엔진조판 전후 비교본문 오프셋과 수식 보존.04 / 검토 저널주석별 수락 결정적용 전까지 원본을 보호.적용·커밋 전까지 작업 폴더는 그대로 유지.
한 번의 라운드: 스냅샷, 빌드, 비교, 결정.

페이지에서 각 변경 사항 찾기

소스의 단위. diff는 본문을 단어 단위(CJK 텍스트는 글자 단위)로 분할합니다. 주석, 인라인 및 디스플레이 수식, 중괄호 그룹, 인자를 포함한 명령어, 그리고 equation, align, tabular, verbatim, minted, tikzpicture 같은 환경은 단일 토큰으로 유지됩니다. 공백이나 문장 부호만 사이에 둔 편집은 하나로 합쳐지며, 이렇게 묶인 각 편집은 정확한 소스 범위를 가진 하나의 결정 단위가 됩니다. 이미지와 기타 바이너리 파일은 파일 전체가 한 단위이며, 같은 .bib 항목을 건드리는 변경 블록(hunk)들은 하나의 단위를 이룹니다.

문서가 달라진 위치. 워커 프로세스가 MuPDF로 두 PDF의 텍스트를 추출하고 단어 단위로 두 문서를 정렬합니다(engine/src/render/effects.ts). 고유한 8단어 연속 구간을 앵커로 삼아 두 문서를 고정하고, 이 앵커들의 최장 증가 체인을 유지한 뒤, 앵커 사이의 구간에 대해 diff를 구합니다. 영문자와 숫자가 최소 20자 이상 이어진 구간이 위치를 옮긴 경우 이동으로 보고합니다. 문서 전체를 비교하기 때문에 재정의된 매크로의 모든 사용처, 번호가 바뀐 수식, 새로 추가된 참고문헌 항목처럼 편집 위치에서 떨어진 곳의 변경 사항까지 찾아낼 수 있습니다.

각 편집의 위치. 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는 3방향 병합(three-way merge)으로 워크트리의 변경 사항을 되돌리므로, 그 이후에 편집된 구절은 그대로 유지됩니다. 에이전트가 작업하는 동안 발생한 거절은 에이전트의 턴이 끝날 때까지 대기합니다.
  • Undo는 가장 최근의 결정을 취소합니다.
  • Apply는 수락된 변경 사항을 다시 3방향 병합으로 작업 파일에 병합합니다. Commit은 브랜치가 이동하지 않았는지 확인한 후 index.lock을 유지한 채 git commit-tree로 태스크의 변경 사항만 HEAD에 기록하며, 이미 스테이징해 둔 다른 항목은 그대로 보존합니다.

그사이 원고의 동일한 구절이 변경되었다면 아무것도 덮어쓰지 않습니다. 제안된 변경 사항을 현재 원고 위로 리베이스하여 같은 태스크의 새 리뷰로 다시 가져옵니다.

격리에 드는 비용

동일한 폴더의 복사본에서 실행한 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가 준비되었습니다.