| name | rhwp-fidelity-compare |
| description | 한컴이 내보낸 공식 PDF와 rhwp export-svg를 쪽별로 대조합니다. tools/fidelity_compare의 페이지 시트·픽셀 diff% 랭킹(최악 쪽 우선)·text-report.tsv 문자 멀티셋(소실/과잉/치환)을 후보 검출로 읽고, --font-style·로컬 face 별칭·두부 오염·RHWP_FONT_PATH_DIR·provenance를 닫습니다. 트리거 — 사용자가 "한컴 PDF와 비교", "공식 출력 기준 대조", "fidelity_compare 돌려줘", "한컴이 뽑은 PDF랑 rhwp가 같은지"를 요청할 때. 독립 한컴 PDF가 있을 때만. 자기 일관성 render-diff나 버그 헌팅 여정과는 다른 축이다. |
rhwp-fidelity-compare — 한컴 기준 PDF 대조 Skill
에이전트가 한컴이 내보낸 공식 PDF 와 rhwp export-svg 를 쪽별로
대조할 때 쓰는 규약이다. 코어는 이미 있는
tools/fidelity_compare/fidelity_compare.py 와 rhwp export-svg 뿐이다.
이 스킬은 실 에이전트 경로다. gym 이 아니고, 새 CLI 명령을 발명하지
않는다. rhwp-visual-regression(자기 일관성 render-diff) 과
bug-hunter(여정 방법론) 를 이 폴더에서 재작성하지 않는다.
픽셀 diff% 와 문자 멀티셋은 후보 검출이지 절대 판정이 아니다.
최종 시각 판정은 유지자/작업지시자가
visual_verification_governance.md
를 따라 내린다.
상세는 references/ 를 단계별로 연다. SKILL.md 는 인덱스와 정지 규칙만 담는다.
정본:
언제 쓰는가 / 언제 쓰지 않는가
| 손에 있는 것 | 정직한 도구 | 이 스킬 |
|---|
| 한컴 도구·버전·경로가 기록된 독립 공식 PDF + 원본 HWP/HWPX | tools/fidelity_compare | 여기 |
| 편집/변환 전후 두 HWP, 공식 PDF 없음 | rhwp render-diff | 쓰지 않음 → rhwp-visual-regression |
| 같은 파일을 두 번 렌더해 결정성만 본다 | render-diff A A | 쓰지 않음 |
| 원인 미확정 실사용 결함을 여정으로 좁힌다 | bug-hunter playbook | 후보 검출만 넘긴다 |
| gym pack / 채점 / 리더보드 | gym 도구 | 금지 |
독립 한컴 PDF 가 없으면 이 하네스는 정직하지 않다. 샘플 옆의 동반 PDF 는
도구·버전·출처를 확인하기 전에는 최종 기준으로 승격하지 않는다.
바이너리·venv
새 fidelity-* 하위명령은 없다. 비교는 저장소 로컬 venv 의 Python 이
기존 하네스를 호출한다.
python3.12 -m venv venv
venv/bin/python -m pip install pypdf pypdfium2 pillow
py -3.12 -m venv venv
venv\Scripts\python.exe -m pip install pypdf pypdfium2 pillow
- POSIX:
venv/bin/python
- Windows:
venv\Scripts\python.exe
- Chrome/Chromium 은
--text-only 가 아닐 때 필수
--text-only 는 pypdf 만 있으면 되고 Chrome·pypdfium2 를 요구하지 않는다- 하네스 SVG 는 기본
--font-style (로컬 face 별칭, embed 아님)
실행 파일 자동 탐색: rhwp 는 target/release-test → target/release →
PATH. Chrome 은 플랫폼 기본 경로. 안 맞으면 RHWP_BIN / CHROME_BIN.
수정 직후 비교 전 최신 바이너리:
cargo build --profile release-test --target-dir target/pr-review
RHWP_BIN=target/pr-review/release-test/rhwp \
venv/bin/python tools/fidelity_compare/fidelity_compare.py plan 0 9 \
--out-dir /tmp/rhwp-fidelity-plan
이 cargo build 는 시각 대조용 컴파일 전용 이다. Rust 테스트를 대신하지
않는다.
사다리 (강제 순회 아님)
독립 한컴 PDF 가 있는가
│
├─ 없음 ──▶ rhwp-visual-regression (render-diff). 여기서 멈추지 말고 스킬을 갈아탄다 (F01)
│
├─ 있음, 텍스트 후보만 먼저 ──▶ --text-only [--export-all-svg] [--layout-ledger] (F02)
│ text-report.tsv 소실/과잉/치환
│ page-count-ledger.tsv 쪽수 불일치는 후보
│
├─ 픽셀 시트 ──▶ (기본 모드) cmp-pNNN.png + report.tsv 최악 쪽 우선 (F03)
│ Chrome 필수. 없으면 --text-only 로 내려가거나 정지 (F10)
│
├─ 글꼴 두부 의심 ──▶ --font-style · RHWP_FONT_PATH_DIR · svg-glyph-risk-report.tsv (F04)
│
└─ 사람/유지자 시트 감사 ──▶ 실질 결함만 이슈 승격 (F05)
자동 diff% 통과는 최종 판정이 아니다
질문이 이미 답이면 다음 단으로 내려가지 않는다. 정지 조건은
27_exception_catalog.md 와 아래 표.
요청 → 명령
| 사용자 요청 | 명령 | 레퍼런스 |
|---|
| 한컴 PDF 랑 같은지 | 등록키 또는 --source+--reference-pdf+--label | 01_when_to_use.md |
| 일단 글자만 | --text-only --export-all-svg | 06_text_report.md |
| 최악 쪽부터 보자 | 기본 모드 → report.tsv 내림차순 | 05_pixel_ranking.md |
| 글자가 □ 로 나온다 | --font-style 기본인지, RHWP_FONT_PATH_DIR | 07·09·17 |
| 윈도에서 돌려 | venv\Scripts\python.exe, break-system-packages 금지 | 03_windows.md |
| 임의 HWP+PDF 쌍 | --source --reference-pdf --label --reference-grade | 19_direct_pair.md |
| Chrome 없다 | --text-only 또는 정지 F10 | 13_missing_chrome.md |
| 암호화 PDF | 정지 F13. 암호 우회 CLI 발명 금지 | 16_encrypted_pdf.md |
등록 키: plan manual bunjang korexam math eng.
키는 ASCII 글롭이다. 한글 argv 는 배경 셸에서 cp949 로 깨질 수 있다.
venv/bin/python tools/fidelity_compare/fidelity_compare.py plan 0 34 \
--out-dir /tmp/rhwp-fidelity-plan
RHWP_BIN=target/release-test/rhwp \
venv/bin/python tools/fidelity_compare/fidelity_compare.py 0 214 \
--source 'samples/입력.hwp' \
--reference-pdf 'pdf/한컴-기준.pdf' \
--label issue-3738-hwp \
--reference-grade '한컴 2020 기준 PDF' \
--text-only --export-all-svg --layout-ledger \
--out-dir /tmp/rhwp-fidelity-issue-3738
Windows:
venv\Scripts\python.exe tools\fidelity_compare\fidelity_compare.py plan 0 9 `
--out-dir $env:TEMP\rhwp-fidelity-plan
--out-dir 은 지정한 디렉터리 자체를 산출 루트로 쓴다. 생략하면
output/fidelity/<키>/. worktree 를 깨끗이 두려면 저장소 밖 경로를 쓴다.
산출물 (읽는 법)
| 파일 | 의미 | 판정 권위 |
|---|
cmp-pNNN.png | 기준 PDF ‖ rhwp 렌더 쪽별 비교 시트 | 사람 눈 |
report.tsv | page, diff%, note — 최악 쪽 우선 정렬 | 후보 순위 |
text-report.tsv | 쪽별 문자 멀티셋. reference_only=소실, svg_only=과잉, 둘 다=치환 | 후보 |
provenance.tsv | 원본·기준 PDF 경로와 기준 등급 | 재현 기록 |
run-state.tsv | requested/completed/missing. 누락이면 종료 코드 ≠ 0 | 실행 완전성 |
page-count-ledger.tsv | PDF / SVG / render-tree 쪽수 | 후보. 전역 page-break 수정 근거 아님 |
svg-glyph-risk-report.tsv | SVG raw PUA / U+FFFD | 두부 후보 (PDF 추출과 독립) |
그 외 owner-shift · table-fragment · layout-candidates 는
20_outputs.md. 모두 candidate 다.
text-report.tsv 헤더:
page reference_only svg_only reference_only_chars svg_only_chars note
공백·순서를 무시하고 NFC 멀티셋을 비교한다. PDF 텍스트층에 없는 path
글리프, 숨김 텍스트, 추출기 매핑 차이는 최종 시각 판정을 대신하지 않는다.
글꼴·두부
하네스는 rhwp export-svg --font-style 을 기본으로 쓴다. 원 문서 legacy
face 와 설치된 family/full name 이 달라도 @font-face src: local(...)
별칭을 Chrome 이 쓰게 해서, 한양중고딕·휴먼명조가 설치돼 있는데도 비교 PNG 가
□ 로 채워지는 하네스 오염 을 막는다.
- 글꼴 바이너리를 SVG 에 embed 하지 않는다 (기본 모드)
RHWP_FONT_PATH_DIR 로 라이선스 있는 로컬 글꼴 디렉터리를 넘긴다- 휴먼명조/휴먼고딕의 HMKMM/HMKMG 처럼 EBDT local face 가 Chrome 에서
.notdef 를 그리는 경우, 고정 좌표를 유지한 채 outline 명조·고딕을 먼저
고른다. HY신명조는 원 face 우선순위를 보존한다
- 시트가 온통 두부면 문서 결함이 아니라 하네스 오염 (F14). 글꼴을 고치고
다시 돌린 뒤에야 후보를 읽는다
provenance (필수 기록)
한컴 출력은 도구·버전·출력 경로·폰트에 따라 달라진다. 재현 기록에 남긴다.
| 필드 | 예 |
|---|
| 한컴 도구 | 한글 2022 / 2024 / 한컴오피스 |
| 버전 | 12.0.0.xxxx |
| 내보내기 경로 | 파일→PDF로 저장 / 인쇄→PDF / pdf/ 보존본 |
| 글꼴 | 설치 목록 또는 RHWP_FONT_PATH_DIR |
| 원본 경로 | samples/....hwp |
| 오라클 PDF 경로 | pdf/....-2022.pdf |
| 기준 등급 | 한컴 2022 기준 PDF / 참고 PDF (미확인) |
provenance.tsv 는 role, path, grade 세 열이다. --reference-grade 는
direct pair 에서만 쓴다. bunjang 동반 PDF 는 등급이 "참고" 이며 별도 확인
전에는 최종 기준으로 쓰지 않는다.
정지 규칙
| ID | 언제 | 행동 |
|---|
| F01 | 독립 한컴 PDF 없음 | rhwp-visual-regression 으로 인계. 가짜 기준 PDF 를 만들지 않음 |
| F02 | --text-only 로 후보만 모음 | 시트 없이 원장만. 결함 확정 금지 |
| F03 | report.tsv 상위 쪽 | 최악부터 시트를 눈으로 감사. diff% 절대값으로 merge 하지 않음 |
| F04 | PUA / U+FFFD / □ | 글꼴 별칭·경로를 먼저. 문서 결함으로 바로 승격 금지 |
| F05 | 시트 감사 끝 | 실질 결함만 이슈. 최종 판정은 유지자 |
| F06 | gym / 새 CLI 요청 | 거절. 이 스킬은 기존 하네스만 |
| F07 | visual-regression 스킬을 여기서 고침 | 거절. 이웃 스킬 재작성 금지 |
| F08 | bug-hunter 여정을 여기서 다시 씀 | 거절. 후보만 넘긴다 |
| F09 | venv 없음 / 시스템 pip | 정지. --break-system-packages 금지 (F15) |
| F10 | Chrome 없음, --text-only 아님 | --text-only 로 내리거나 정지. Chrome 설치를 강제 스크립트하지 않음 |
| F11 | 쪽수 불일치 | page-count-ledger.tsv 를 후보로 기록. 전역 page-break 패치 금지 |
| F12 | run-state incomplete | 누락 쪽을 먼저. 부분 랭킹을 전수로 포장하지 않음 |
| F13 | 암호화 PDF | 정지. 암호 제거 CLI / 우회 발명 금지 |
| F14 | 시트가 두부 가득 | 하네스 오염. 글꼴을 고치고 재실행 |
| F15 | --break-system-packages | 거절. 저장소 venv/ 만 |
| F16 | 질문이 이미 답 | 다음 단 금지 |
| F17 | samples/ 동반 PDF 를 공식 기준으로 승격 | 도구·버전 확인 전 금지 |
| F18 | 원본 HWP 를 비교 중 덮어씀 | 금지. --out-dir 만 기록 |
금지 기본값
- 새 비교 CLI (
fidelity-diff, pdf-compare, hangul-diff) 발명
- gym pack / gym 과제 / 채점기 작성
rhwp-visual-regression / bug-hunter 스킬 재작성- DocumentCore / 렌더러 구현을 이 PR 에서 고침
- 시스템 Python 에 pip install,
--break-system-packages
- 암호화 PDF 암호 우회
- diff% 0 을 "한컴과 동일" 으로 발표
- 두부 시트를 문서 회귀로 오진
- 원본을 비교 과정에서 덮어쓰기
인계
- 공식 PDF 없이 전후 레이아웃만 →
rhwp-visual-regression
- 원인 미확정 실사용 여정 →
bug-hunter (이 하네스 원장을 입력으로)
- 미지 문서 파악만 →
rhwp-doc-triage (비교하지 않음)
- 편집 자체 →
rhwp-safe-edit / rhwp-form-fill (끝난 뒤 공식 PDF 가 있으면 여기로)
- CLI 일반 →
rhwp-cli (export-svg 단건)
상세: 26_handoff.md
예외 경로 (짧게)
| 예외 | 증상 | 처방 |
|---|
| Chrome 없음 | Chrome/Chromium을 찾을 수 없습니다 exit 2 | CHROME_BIN 또는 --text-only (F10) |
| venv 없음 | pypdf/pypdfium2 ImportError exit 2 | 저장소 venv 재생성 (F09) |
| 쪽수 불일치 | ledger 의 PDF≠SVG | 후보. 전역 패치 금지 (F11) |
| 암호화 PDF | pypdf/pypdfium2 암호 예외 | 정지 (F13) |
| 두부 하네스 | 비교 PNG 가 □ 투성이 | RHWP_FONT_PATH_DIR + --font-style 재실행 (F14) |
레퍼런스 목차
- 00_tree.md — 판단 트리
- 01_when_to_use.md — 독립 PDF 가 있을 때만
- 02_setup_venv.md — venv · pypdf · pillow
- 03_windows.md —
venv\Scripts\python.exe
- 04_page_sheets.md —
cmp-pNNN.png
- 05_pixel_ranking.md — 최악 쪽 우선
- 06_text_report.md — 소실/과잉/치환
- 07_font_style.md —
--font-style
- 08_local_face_aliases.md — local() 별칭
- 09_tofu.md — PUA · U+FFFD · □
- 10_font_path_dir.md —
RHWP_FONT_PATH_DIR
- 11_provenance.md — 도구·버전·경로·글꼴
- 12_visual_verdict.md — 유지자 판정
- 13_missing_chrome.md — Chrome 부재
- 14_missing_venv.md — venv 부재
- 15_page_count_mismatch.md — 쪽수
- 16_encrypted_pdf.md — 암호화 PDF
예제: examples/. 기계 가독 픽스처: fixtures/.
처리 결과: mydocs/working/agent_fidelity_compare.md
권위
