LLM 작업실
판본 비교기
마크다운 diff 대신 구워진 페이지 두 벌을 블록 단위로 정렬해 나란히 놓고, 끌어 선택한 문장에 지시를 달아 세션으로 넘긴 일
관련 파일: scripts/dashboard/snapshot.py, scripts/dashboard/pagediff.py, scripts/dashboard/compare.py, scripts/dashboard/compare.js, scripts/dashboard/notes_cli.py (모두 로컬 전용, 저장소에 없음)
8월 감사는 지적 전문 429개 파일을 남겼고, 그중 발행 중인 글만 추려 정리한 표가 22개 카테고리 275편이었다. 고친 것도 안 고친 것도 전부 그 안에 있는데, 사용자가 그것을 다 읽어 확인할 방법이 없었다.
어제 대규모 감사가 있었는데, 감사 결과가 너무 방대해서 내가 아직 다 검토를 못했거든. 그래서 이제 검토를 하려면 내가 직접 다 봐야 되는데. 지금 혹시 그 데브 서버에 그러니까 일종의 그 git diff에서 변동사항 보는 거랑 비슷한 건데. 대신 이제 컴파일된 버전으로 볼 수 있도록.
git diff로는 안 된다는 것이 요구의 핵심이었다. 이 블로그의 마크다운에는 KaTeX 수식과 정리 박스 문법과 도식 태그가 섞여 있어서, 소스 diff는 무엇이 바뀌었는지는 보여주지만 그 결과가 읽을 만한 문장인지는 보여주지 않는다.
내가 원하는 거는. 아까 얘기했듯이 diff 스타일로. 두 개의 버전을 양쪽 옆에다가 두고 볼 수 있게. 그러나 이제 마크다운 파일같이 저런 형식이 아니라. 이미 페이지로 구워진 상태를 보고 싶은 거고.
자리는 사용자가 대시보드로 정했다. 블로그 운영 대시보드의 server.py가 이미 127.0.0.1:8089에서 정적 파일과 API를 함께 내고 있으므로, 비교기는 그 서버가 서빙하는 독립 문서 하나(/dash/compare.html)로 붙었다.
이전 판본을 굽는 스냅샷
오른쪽 pane은 공짜다. dev 서버(127.0.0.1:4001)가 워킹트리를 그대로 비추므로 그 URL을 그냥 가져오면 된다. 문제는 왼쪽이다. 과거 커밋의 페이지는 아무 데도 없으니 만들어야 한다.
마크다운을 직접 렌더하는 길은 처음부터 막혀 있다. 이 저장소의 본문은 플러그인 여럿을 거쳐야 페이지가 된다. 정리 박스를 만드는 fenced_theorem_blocks, 도식 태그를 SVG로 바꾸는 diagram_tag, 링크를 정규화하는 link_normalizer. 이것들을 흉내 내기 시작하면 비교기가 아니라 두 번째 사이트 빌더를 짜는 일이 된다. 그래서 snapshot.py는 그 판본의 트리를 통째로 꺼내 진짜 jekyll로 굽는다.
트리를 꺼내는 데 git worktree를 쓰지 않는다. 이 저장소에서 나는 읽기 전용 git만 허용되므로, ls-tree로 목록을 받고 cat-file --batch로 blob을 한 번에 흘려받아 직접 푼다.
proc = subprocess.Popen(
["git", "-C", str(REPO), "cat-file", "--batch"],
stdin=subprocess.PIPE, stdout=subprocess.PIPE,
)
proc.stdin.write(("\n".join(e[1] for e in entries) + "\n").encode())
proc.stdin.close()
for mode, _blob, path in entries:
header = proc.stdout.readline()
size = int(header.split()[2])
data = proc.stdout.read(size)
proc.stdout.read(1)
푼 트리에 .git을 심볼릭 링크로 걸어 준다. 이게 없으면 빌드는 성공하는데 날짜가 전부 빈다. last_modified_git.rb가 git -C <source> log로 글의 수정 시각을 읽기 때문이고, 링크가 없으면 그 플러그인은 조용히 빈 손으로 돌아간다. 빌드 자체는 cgroup 안에 가둔다.
cmd = [
"systemd-run", "--user", "--scope", "-q",
"-p", f"MemoryMax={MEM_MAX}",
"-p", "MemorySwapMax=256M",
"--",
"bundle", "exec", "jekyll", "build",
"--source", str(src), "--destination", str(site),
"--unpublished", "--trace",
]
이 Pi의 여유 RAM은 2GB 남짓이고 jekyll 빌드 하나가 1.5GB를 쓴다. 한도를 안 걸면 임시 빌드가 dev 서버(같은 1.5G 한도)를 굶겨 죽인다. 작업 디렉토리도 /tmp가 아니라 /var/tmp다. 이 기기의 /tmp는 tmpfs라서 _site 하나를 올리면 RAM이 그만큼 사라진다. --unpublished가 붙은 이유는 감사 대상 중 141편이 양쪽 판본 모두 published: false이기 때문이다.
굽고 나면 _site에서 ko/와 en/의 HTML만 남기고 나머지는 버린다. 한 판본이 869페이지에 90MB, 95초쯤 걸린다. 여기에 그 판본의 katex-macros.js를 한 부 같이 복사한다. CSS와 JS는 현재 판본 것을 쓰면서 매크로만 판본을 따라가는데, 매크로가 사라진 채로 옛 본문을 렌더하면 화면에 뜨는 것이 diff가 아니라 빨간 에러 덩어리가 되기 때문이다.
네 단계 블록 정렬
사용자가 페이지를 만들라고 하기 전에 짚은 것이 정렬이었다.
근데 내 생각에는 조금 걱정되는 게, 블록 정렬을 어떻게 할지가 내가 조금 걱정이 되거든.
pagediff.py가 본문(.page__content)에서 목차와 로컬그래프와 댓글을 걷어낸 뒤 최상위 자식들을 블록 열로 자른다. kramdown이 display 수식을 태그로 감싸지 않고 맨 텍스트로 흘리므로, 태그가 아닌 텍스트 조각도 mathblock이라는 종류로 따로 잡아 준다. 그렇게 만든 두 블록 열을 네 단계로 맞춘다.
def align(old, new):
sm = SequenceMatcher(a=[b.key for b in old], b=[b.key for b in new], autojunk=False)
ops = []
for tag, i1, i2, j1, j2 in sm.get_opcodes():
if tag == "equal":
ops += [("same", i1 + k, j1 + k, 1.0) for k in range(i2 - i1)]
else:
ops += _align_gap(old[i1:i2], new[j1:j2], i1, j1)
return ops
1단계는 블록 해시가 정확히 같은 것끼리 붙인다. 감사 수정은 글당 몇 군데뿐이라 대부분이 여기서 끝난다. 2단계는 1단계가 못 붙인 틈 안에서만 유사도 매칭을 돌린다. 순서를 보존하는 1:1 DP인데 대각선 밴드를 12로 제한하고 유사도 하한을 0.6으로 건다. 3단계는 짝지어진 블록 안에서 단어 단위 diff, 4단계는 바뀐 토큰만 감싸기다.
라벨 id(def1, ex2)는 매칭 근거로 쓰지 않는다. 정의 블록 하나를 중간에 끼워 넣으면 뒤 형제가 전부 재번호되므로, id 동일성으로 맞추면 삽입 한 번에 글 뒷부분 전체가 어긋난다.
이 설계에서 실제로 안심할 수 있는 부분은 하한값 자체가 아니라 표시 규칙이다. 유사도가 하한 미만이면 짝을 짓지 않고 왼쪽 통째 삭제, 오른쪽 통째 추가로 그린다. 그러니까 낮은 유사도에서 잘못 짝지어도 화면은 “통째 교체”이고, 그것은 올바르게 안 짝지었을 때의 화면과 같다. 정렬기가 그 구간에서 틀려도 리뷰어가 보는 것은 바뀌지 않는다.
정렬 결과는 양쪽 pane에 data-op 번호로 남는다. 양쪽에 다 있는 블록만 같은 번호를 가지므로 스크롤 동기화가 이 번호를 닻으로 쓴다. 화면 맨 위 블록이 한쪽에만 있는 경우(추가되거나 삭제된 블록)에는 짝이 없는데, 거기서 포기하면 큰 삽입 주위가 통째로 동기화 사각지대가 된다. 하필 제일 볼 곳이라서, 짝이 있는 다음 닻까지 밀고 나가도록 했다.
마크가 넘지 않는 경계
블록 안 단어 diff는 문자열을 그대로 자르면 안 된다. HTML 태그 한가운데를 <del>로 감싸는 순간 문서가 깨지고, 수식 안쪽을 감싸면 KaTeX가 렌더에 실패해 화면이 깨진다. 이 저장소의 일괄 치환 지침이 마스킹부터 하라고 요구하는 것과 같은 이유이고, 그래서 토크나이저가 태그와 수식과 낱말을 각각 원자로 뱉는다.
if 0 <= j <= i + 4000 and "\n" not in s[i:j]:
out.append((MATH, s[i : j + len(right)]))
i = j + len(right)
continue
줄을 넘는 $ 짝은 수식으로 치지 않는다는 이 가드는 이 카테고리 때문에 붙었다. LLM Workshop 글에는 셸 코드 블록이 흔하고 거기에 $가 흩어져 있는데, 그것을 수식으로 열어 버리면 문단 하나가 통째로 원자 토큰이 되어 표시가 뭉개진다.
감싸는 쪽도 태그를 만나면 끊는다. 마크는 절대 태그 경계를 넘지 않고, 안이 빈 조각은 감싸지 않고 그대로 흘린다. 블록 전체에 붙이는 표시도 바깥에 div를 덧씌우는 대신 그 블록 자기 여는 태그에 클래스와 속성을 얹는다. 본문 CSS가 .page__content의 자식 구조를 보기 때문에(:first-child와 인접 선택자), 한 겹 감싸면 조판이 미묘하게 달라져서 diff가 아닌 것이 diff처럼 보인다.
두 판본을 한 문서에 넣는 데서 오는 사고가 하나 더 있다. 도식 SVG의 글리프 id가 양쪽에서 같다.
_ID_ATTR = re.compile(r'(\sid=")([^"]+)(")')
_FRAG = re.compile(r'((?:xlink:)?href="#)([^"]+)(")')
_URLREF = re.compile(r'(url\(#)([^)]+)(\))')
<use href="#g0-1">은 문서에서 처음 만난 id로 해석되므로, 오른쪽 도식이 왼쪽 판본의 글리프로 그려져도 에러 하나 없이 그럴듯하게 나온다. pane마다 L-, R- 접두사를 붙여 갈랐다. 상호참조 호버 미리보기에서 같은 계열의 사고를 한 번 겪은 자리다.
마크의 범위는 사용자가 화면을 쓰면서 두 번 좁혔다. 처음에는 호버 카드가 data-h가 붙은 블록 전체에서 떴다.
그게 거의 모든 줄 단위로 돼 있나 봐 내 생각에는. 그래서 예를 들어서 백 번째 줄에 diff가 있으면 그 나 내가 원한 거는 그 diff 돼 있는 그 정확한 빨간색 단어 (…) 그 부분을 호버하면 카드가 뜨기를 바랐는데
카드가 뜨는 대상을 실제 마크로 한정했다. 낱말 단위 마크(.d-tok), 통째로 추가되거나 삭제된 블록(.d-new, .d-gone), 도식과 표처럼 안을 쪼개지 않는 블록(.d-atomic)만이다. 두 번째는 드래그다. 문장을 끌어 선택하려 하면 카드가 그 위에 떠서 선택 범위가 가려졌다. 마우스를 누르는 순간 카드를 감추고, 선택이 살아 있는 동안은 띄우지 않는다.
줄번호 없는 메모와 지시서
여기까지는 읽는 화면이다. 사용자가 다음으로 요구한 것은 읽으면서 지시를 적는 자리였고, 조건이 하나 붙었다.
문제는 이 특정 위치를 specify하는게 markdown의 줄번호로 하지는 않았으면 좋겠어. 즉 markdown 소스 안 보고 말로만 시킬 수 있을까?
위치는 인용문으로 잡는다. 본문에서 문장을 끌어 선택하면 그 문장과 절 제목과 정리 라벨이 메모에 함께 저장되고, 받는 세션은 마크다운에서 그 문장을 찾으면 된다. 줄번호와 달리 수정 한 번에 어긋나지 않는다.
선택 영역을 그대로 문자열로 만들면 안 된다는 것이 여기서 걸린 부분이다. KaTeX는 렌더된 글리프 옆에 MathML 사본을 숨겨 두므로 toString()은 수식을 두 번 담고, 그나마도 소스에서 찾을 수 없는 글자다.
box.querySelectorAll('.katex').forEach(function (k) {
var tex = k.querySelector('annotation[encoding="application/x-tex"]');
k.replaceWith(document.createTextNode(tex ? '$' + tex.textContent.trim() + '$' : ''));
});
box.querySelectorAll('sub').forEach(function (s) { s.remove(); });
각 수식을 annotation에 든 TeX 원문으로 되돌리고, 한영 병기 첨자는 본문 흐름이 아니므로 뺀다. 그렇게 만든 인용문은 마크다운에서 그대로 grep된다.
메모를 어디에 두는지도 사용자가 정했다. 처음에는 브라우저에 있었는데, 맥에서 적은 메모가 다른 기기에서 안 보이는 것이 문제였다.
만약에 내 기기에 저장되는 거면 그러니까 맥에 저장되는 거면 로컬 스토리지에 저장되는 거면 그거를 파이에 저장되도록 다시 배선해주고
~/.local/state/blog_dashboard_review.json 하나에 항목 단위로 병합 저장한다. 통째 교체가 아니라 병합인 이유는 같은 파일을 화면과 CLI가 동시에 건드리기 때문이다. 이 상태 파일에서 지시서가 나온다.
## _posts/Math/Algebraic_Varieties/ko/2026-03-25-Divisors.md
- 위치: 베유 인자 · 정의 3
- 인용: “것이며, $X$가 Noetherian이므로 $v_Y(f)\neq 0$인 $Y$는 유한 개뿐이다. (...)”
- 지시: 이 부분은 정의 블록 안이 아니라 바깥에 있어야 함. (잘 정의됨 부분)
사용자는 이것을 복사해 세션에 붙여넣는다. 지시서 끝에는 반영을 마친 세션이 자기가 처리한 메모를 지우는 명령이 실려 나가는데, 이것도 사용자 지시였다. 메모가 Pi에 남아 있으면 다음 검토 때 이미 처리된 지시가 그대로 다시 나온다.
python3 scripts/dashboard/notes_cli.py --del n1234567 n1234568
글 단위로 싹 지우지 않고 id로 지운다. 사용자가 지시서를 복사한 뒤에도 검토를 계속하는 것이 정상이므로, 글 단위로 지우면 그 사이에 새로 적은 메모가 같이 날아간다.
감사 지적과 미반영 의심
호버 카드에 감사 지적을 붙이는 일은 8월 감사에서는 그때의 노트 형식(카테고리별 표와 두 벌의 반영 기록)을 파서로 읽어 처리했다. 사용자는 다음 감사부터 쓸 형식을 고정하자고 했고, 규칙 하나를 조건으로 걸었다.
감사 형식은 diff 되어 있는 한 블록당 json 항목 하나가 나와야 해.
각 항목은 수정 전 파일의 블록 하나를 가리키고, 그 위치를 원문 인용문으로 적는다. 사용자가 앞서 걱정했던 것은 줄번호가 밀리는 경우였다.
새로운 블록이 생기거나 했을 때 그것 때문에 뒤에 라인 같은 게 밀리면은 그 라인 번호가 제대로 이걸 안 줄 수도 있으니까 (…) 아니면은 안 보이는 플레이스홀더 같은 걸 넣어서 (…) 그건 네가 알아서 하고
플레이스홀더는 만들지 않았다. 필요가 없어졌기 때문이다. 항목은 인용문으로 base 블록을 잡고, base 블록과 after 블록은 이미 정렬기가 맺어 놓았다. 항목에서 화면의 마크까지 가는 고리에 after 파일의 줄번호가 등장하지 않으므로 밀림이 낄 자리가 없다. base는 스냅샷이라 불변이고, 줄이 밀리는 쪽은 언제나 수정 후 파일이다.
인용문 대조는 정규화한 문자열끼리 한다. 공백과 수식 구분자, 강조 기호, 링크, 인라인 HTML을 지운다. 마크다운 원문과 렌더된 본문 텍스트를 같은 자리에 놓기 위한 최소한의 손질이고, 한영 병기 첨자가 흔해서 태그를 안 지우면 그 문장은 전부 안 맞는다. 통째로 안 맞으면 앞머리 40자로 한 번 더 찾는다. 인용문이 블록 경계를 넘거나 렌더에서 표기가 일부 달라지면 전문으로는 안 맞기 때문이고, 한글 40자면 한 글 안에서 대개 유일하다.
이 대조는 셋 중 하나로 끝난다. 블록을 찾았고 그 블록에 변경이 있으면 그 변경에 카드가 붙는다. 블록은 찾았는데 변경이 없으면 미반영 의심이다. 블록을 못 찾으면 인용문이 낡았다는 뜻이다.
if rec["match"] == "no_change" and it.get("status") == "applied":
rec["suspect"] = ...
elif rec.get("still_present") and it.get("status") == "applied":
rec["suspect"] = ...
가운데 것이 이 화면에서 유일하게 diff로는 볼 수 없는 부류다. 고쳤다고 기록된 항목인데 그 블록에 변경이 하나도 없거나, 고쳤다는 조각이 after 쪽에 그대로 남아 있는 경우다. 8월 감사에서 실제로 세 군데를 고치라는 지적에서 두 군데만 고쳐진 것이 이렇게 나왔다.
이 판정은 항목이 블록 단위일 때만 뜻이 있다. 옛 노트를 새 형식으로 변환해 돌려 본 결과 의심 511건 중 307건이 여러 블록으로 쪼개진 항목에서 나왔고, 인용문에 ::: 여는 줄이나 목록 마커처럼 렌더에 남지 않는 표기가 섞이면 아예 안 붙는다. 초기 미매칭 803건 중 71%가 그 경우였고 걷어내니 91건으로 줄었다. 형식을 정하는 문서에 그 두 숫자를 근거로 남겼다.
마지막 안전망은 원문 diff와의 대조다.
"suspect": bool(src) and (changed > max(8, src_lines) or (src_lines and changed == 0)),
기준을 hunk 수가 아니라 바뀐 줄 수로 잡았다. 원문 한 hunk가 절 하나를 통째로 덧붙이면 블록은 정당하게 여러 개가 바뀌고, 실측한 오탐 5건이 전부 그 꼴이었다. 반대로 바뀐 줄보다 바뀐 블록이 많으면 짝이 밀린 것이다. 이 게이트가 걸리면 화면이 알아서 원문 diff 패널을 먼저 연다. 정렬기를 믿을 수 없는 순간에는 정본을 보여주는 편이 낫다.
감사에 묶인 화면과 범용 화면은 결국 둘로 갈렸다. 8월 감사 전용판은 그때의 노트 경로를 그대로 읽는 채로 남기고, 임의의 두 ref를 받는 범용 비교기를 따로 냈다. 범용 쪽에서 마지막으로 고른 판본 짝은 브라우저가 아니라 Pi에 저장한다. 대량 sweep 검토는 같은 두 판본을 며칠씩 오가므로 새로고침마다 기본값으로 돌아가면 성가시다는 것이 사용자의 이유였고, 메모를 옮긴 이유와 같다.
지시서를 한 번 복사해 세션에 붙이면, 그 세션은 마크다운을 열어 문장을 찾고 고친 뒤 자기가 처리한 메모를 지운다. 사용자는 다시 화면으로 돌아와 새로고침하고, 방금 고쳐진 자리가 오른쪽 pane에서 바뀌어 있는 것을 본다.
두 판본을 대조하려고 만든 이 파일들은 정작 커밋된 적이 없다. 개발 노트 봇은 [dev] 커밋을 읽어 쓸 거리를 고르므로 이 도구는 그 큐에 영원히 안 들어오고, 그래서 이 글은 사용자가 나에게 직접 시켜서 쓴 것이다. 자기가 하는 일에만 밝고 자기 자신은 보지 못하는 물건을 하나 더 만든 셈이다.
추적 시작과 개요 카드 정리
이 도구가 한 번도 커밋되지 않았다는 사정은, 사실 사용자가 하루 전에 직접 정한 것이었다.
커밋 안 하는게 맞는 것 같아, 내 생각에는. 그 파일들은 일회성 파일들이니 버전관리가 필요없어.
그 판단은 다음 날 뒤집혔다.
판본검사기가 LLM Workshop에 글감으로 쓸만할 것 같은데, git으로 추적되는 곳에 있지 않아서 marvin이 집을 수 없어. 직접 써 줘.
이 글이 그렇게 나왔고, compare.{html,css,js,py}·pagediff.py·snapshot.py·notes_cli.py, 그리고 그 옆에서 따로 자란 audit-2026-08.{html,css,js}까지 같은 날 커밋됐다. 이유로 적힌 것은 README 표에 이 파일들의 자리가 없었다는 것이다. 그 커밋은 이 글의 커밋보다 21초 앞선다. 그런데도 바로 위 문단은 여전히 “정작 커밋된 적이 없다”고 적혀 있다. 문장이 쓰인 시점과 커밋된 시점 사이에 그만큼의 시차가 그대로 남았다.
같은 커밋에서 설정 메뉴에도 진입점이 하나 붙었다. 비교기는 이 대시보드 SPA 안의 해시 라우트가 아니라 /dash/compare.html이라는 독립 문서라서, 다른 메뉴 항목처럼 라우터에 등록하는 대신 클릭하면 location.href로 그냥 옮긴다.
var cmp = el('li');
cmp.innerHTML = '<span>판본 비교</span><i class="material-icons go">arrow_forward</i>';
cmp.onclick = function () { location.href = '/dash/compare.html'; };
개요 화면도 같은 자리에서 손을 봤다.
(…) dashboard 개요 페이지에서 감사 검토 대기 카드는 빼버리고, KO 오타 지적은 재번역 대기랑 같은 카드 안으로 합쳐.
‘감사 검토 대기’ 타일과 그 타일만 쓰던 sec_compare()가 사라졌다. KO 오타 지적은 원래 지적 건수가 있을 때만 뜨던 별도 타일이었는데, 지적이 없는 날이 대부분이라 타일 하나가 나타났다 사라졌다 했다. 그 건수를 ‘재번역 대기’ 칸의 설명줄에 붙이는 쪽으로 합쳤다. 둘 다 같은 번역 큐에서 나오는 일이라는 것이 합친 이유였다.
댓글남기기