[gym] 경쟁 벤치마크 — rhwp vs 대안 HWP/문서 도구 실측 + 능력 매트릭스 (정직하게)

[kevin9327]

무엇을 / 왜

"표준 도구 = 에이전트가 기본으로 집는 도구" 명제를 주장이 아니라 실측으로 뒷받침하는,
재현 가능한 경쟁 벤치마크 하네스를 신설한다. samples/ 코퍼스 위에서 rhwp 를 대안 HWP/문서
도구와 같은 과제로 나란히 재고, 문서화된 사실로 능력 매트릭스를 채우며, 정직한 리포트(JSON +
마크다운)를 생성한다.

Closes #4855.

산출물

• gym/tools/competitive_bench.py — 하네스. 과제(export-text·info·structure·convert)를
  가용한 도구에 돌려 벽시계 중앙값·성공률·간이 충실도(문자수 비율)를 재고, JSON 결과 +
  사람이 읽는 마크다운 리포트를 생성. --from-json 으로 재벤치 없이 리포트만 재렌더.
• mydocs/tech/benchmark_vs_alternatives.md / .json — 이 머신 실측 결과(파일별 원시 실행 기록 포함).
• scripts/tests/test_gym_competitive_bench.py — 바이너리·외부도구 없는 순수 로직 가드 21종
  (집계·충실도·능력 매트릭스 불변식·리포트 렌더·정직한 저하). gym 툴-테스트 패턴을 따름.
• .github/workflows/ci.yml — gym 가드 블록에 하네스 계약 테스트 등록(distinct anchor [#4855]).

실측 커버리지 (정직하게)

• 실제로 돌린 도구: rhwp(빌드한 debug 바이너리 v0.8.4), pyhwp(hwp5txt 0.1b15 — venv
  설치, 휴면 패키지라 six 수동 보강 후 import 됨).
• 실행 못 함(구조적 사실로만 기록): LibreOffice(이 머신 미설치 + HWP5 임포트 필터 없음),
  hwplib(JVM 라이브러리, CLI 아님), Hancom SDK(Windows 전용 독점).
• 표본: 50 파일(HWP 25 + HWPX 25), 파일당 1회 측정·중앙값. Windows, rhwp debug 빌드.

결과 — 과제 × 도구 (중앙값 시간 · 성공률 · 충실도)

과제	rhwp	pyhwp (hwp5txt)	soffice	hwplib
export-text	2234ms · 98%(49/50) · 1.00×	1154ms · 50%(25/50) · 0.27×	n/a: 미설치(+HWP5 임포트 필터 없음)	n/a: Java 라이브러리, CLI 아님
info	584ms · 98%(49/50)	n/a: 메타 봉투 없음(hwp5proc=저수준 덤프)	n/a: 미설치	n/a: Java 라이브러리
structure	954ms · 98%(49/50)	n/a: 메타 봉투 없음	n/a: 미설치	n/a: Java 라이브러리
convert	2458ms · 98%(49/50)	n/a: 동일 형식 산출 없음	n/a: 미설치	n/a: Java 라이브러리

충실도 = 둘 다 성공한 파일에서 문자수 ÷ rhwp 문자수 의 중앙값(1.00×=동일량). pyhwp 는
HWPX(ZIP) 0/25 실패(OLE 파서 한계)로 성공률 50%, 표 셀 본문을 <표> 자리표로 대체해 충실도 0.27×.

능력 매트릭스 (요약)

rhwp 만 전 항목 충족: 크로스플랫폼 · 단일 자립 바이너리 · 에이전트-네이티브 CLI(JSON 봉투) ·
MCP 서버 · 메모리 안전(Rust) · 검증 가능 작업(capsule/replay) · 편집 · 렌더(SVG/PNG/PDF).
pyhwp=읽기전용·HWP5만·평문출력·휴면(Py2). LibreOffice=대형 스위트·HWP5 임포트 필터 없음.
hwplib=JVM 라이브러리(CLI 아님). Hancom SDK=Windows 전용 독점. (전체 표는 리포트 참조.)

정직한 평결

• rhwp 우위: 성공률(98% vs 50%, HWPX 포함), 충실도(pyhwp 는 표 본문을 못 뽑아 0.27×),
  형식 폭(HWPX·info·structure·convert 를 구조화 CLI 로 단독 수행), 능력(MCP·검증 가능 작업·
  단일 바이너리·메모리 안전·JSON 봉투는 벤치한 대안 중 rhwp 만).
• 경쟁자가 앞선 지점(그대로 적음): 속도 — 동일 파일집합(둘 다 연 HWP5)에서 pyhwp
  1154ms vs rhwp 2149ms 중앙값으로 pyhwp 가 더 빨랐다. 단 rhwp 는 debug 빌드이며 JSON
  봉투·출처 표지를 함께 낸다(릴리스 빌드로는 좁혀진다). 방향은 코퍼스·빌드 프로파일에 따라 달라질 수 있다.
• LibreOffice 는 (설치·HWP5 개봉만 가능하다면) PDF 렌더·완전 편집 UI 가 성숙 — 다만 현대 .hwp 를
  못 열어 이 과제군에선 출발선에 못 선다.

에이전트가 기본으로 집는 축(설치 한 방·구조화 출력·형식 폭·재현 가능성)에서 rhwp 가 앞선다.
이 정직함(경쟁자가 빠른 곳을 숨기지 않음)이 채택 논거다.

검증

• python -m unittest scripts/tests/test_gym_competitive_bench.py → 21 tests OK (바이너리 불요).
• python -m unittest scripts/tests/test_workflow_contract_wiring.py → OK (ci.yml 편집 무해).
• 하네스 end-to-end 실행으로 위 JSON·리포트 생성. Rust 미변경(rustfmt 불요).

재현

cargo build --bin rhwp
python -m venv .venv && .venv/Scripts/pip install pyhwp six   # 선택: pyhwp 경쟁자
python gym/tools/competitive_bench.py --rhwp target/debug/rhwp \
    --pyhwp .venv/Scripts/hwp5txt --limit 25 \
    --out-json mydocs/tech/benchmark_vs_alternatives.json \
    --out-md   mydocs/tech/benchmark_vs_alternatives.md

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[jangster77]

통합 PR #4883(4412546)로 병합 완료했습니다.

원 head와 CI를 다시 확인해 누적 반영했고, 상세 검토·메인터너 보정·검증 근거는 archive 검토 기록에 남겼습니다.

중복 병합을 막기 위해 이 원 PR을 닫습니다. 감사합니다.

[jangster77]

통합 PR #4883(4412546)로 병합 완료했습니다.

원 head와 CI를 다시 확인해 누적 반영했고, 상세 검토·메인터너 보정·검증 근거는 archive 검토 기록에 남겼습니다.

중복 병합을 막기 위해 이 원 PR을 닫습니다. 감사합니다.