Communitygithub.com

kangdacool/hwpx-editing-skill

LLM 에이전트(Claude Code·Codex 등)가 한글 .hwpx 파일을 안 깨고 편집할 수 있게 해주는 검증된 규칙 및 파이썬 도구 스킬입니다. 포터블 Agent Skill로, Claude Code, Codex 등 다양한 LLM 에이전트가 HWPX (한글 .hwpx) 파일을 손상 없이 편집하도록 가르칩니다.

hwpx-editing-skill란 무엇인가요?

이 스킬은 LLM 에이전트(Claude Code, Codex 등)가 한글 문서(.hwpx)를 편집할 때 발생하는 주요 문제인 파일 손상을 방지하도록 설계되었습니다. HWPX는 XML을 압축한 ZIP 파일 구조로, 일반적인 ZIP 도구로 다시 압축하면 한글에서 인식하지 못하는 깨짐 현상이 발생합니다. 이 스킬은 원본 압축 상태를 보존하는 `repack_preserve` 함수와 함께, lxml 기반 XML 편집, ID 중복 방지, `linesegarray` 제거 등의 필수 가이드라인을 제공합니다. 또한 `inspect_hwpx.py`로 숨은 페이지/단 나누기를 검사하고, `verify.py`로 편집 결과를 검증하는 파이프라인을 포함하여, '편집해도 열리는' 결과를 보장합니다. 지원 플랫폼은 Claude Code, Codex 등 모든 명령행 기반 LLM 에이전트이며, Python 3.10+ 환경에서 lxml 라이브러리만 있으면 사용할 수 있습니다.

지원 대상✓Claude Code✓Codex CLI~Cursor
npx skills add kangdacool/hwpx-editing-skill

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

HWPX 편집

HWPX는 XML(HWPML)의 ZIP 압축 파일입니다. 파일이 손상되는 함정은 외부에서 명확히 드러나지 않으므로, 편집 전에 반드시 references/hwpx-guide.md의 해당 섹션을 읽고, scripts/의 스크립트를 실행하여 재압축 및 검증하세요 — 직접 ZIP을 만들거나 눈으로 확인하지 마세요.

HWPX 전용입니다. 이 스킬은 .hwpx (ZIP + XML)만 다룹니다. 레거시 .hwp (OLE 바이너리, 시그니처 D0CF11E0)는 먼저 한글에서 다른 이름으로 저장 → HWPX(.hwpx) 로 변환해야 합니다. 스크립트가 .hwp를 감지하면 안내 메시지를 출력합니다.

가장 중요한 규칙 하나

절대 일반 ZIP 작성기로 HWPX를 다시 압축하지 마세요. 한글은 변경되지 않은 항목이 재압축된 파일을 거부합니다. 원시 보존 리패커(scripts/hwpxlib.py:repack_preserve)를 사용하세요: 이 함수는 건드리지 않은 모든 항목을 바이트 단위로 복사하고 변경한 항목만 다시 압축하므로, 아무것도 변경하지 않은 리패킹 결과는 원본과 바이트 단위로 동일합니다. 즉, "원본이 한글에서 열리면, 당신의 편집본도 열립니다."

작업 흐름

  1. 먼저 검사하세요. python scripts/inspect_hwpx.py FILE.hwpx --breaks — 섹션별 개수(문단, 표, pic, 수식, 필드)와, 중요한 것은 어떤 문단에 숨은 pageBreak/columnBreak가 있는지 보여줍니다. 제목이 내용과 분리되거나 페이지/단이 비어 있다면, 먼저 그 나누기를 찾으세요 (§6-A) — keepWithNext를 사용하지 마세요. 본문 문단 나누기는 보통 남아있는 쓰레기입니다.
  2. references/hwpx-guide.md의 해당 가이드 섹션을 읽으세요 (아래 매핑 참조). XML id/참조(charPrIDRef, paraPrIDRef, borderFillIDRef, …)는 파일마다 다릅니다 — 항상 실제 파일에서 읽어오고, 추측하지 마세요.
  3. lxml로 XML을 편집하되, 다음 불변 규칙을 따르세요:
    • 문단을 편집하거나 생성한 후에는 <hp:linesegarray>를 제거하세요 (캐시된 줄 레이아웃이 오래되어 간격이 깨집니다). 구조적 편집 후에는 전체 섹션에서 linesegarray를 제거하여 한글이 완전히 재배치하도록 하세요. hwpxlib.strip_linesegarray를 사용하세요.
    • 노드(각주, 미주, 표, 수식, 이미지)를 복제할 때, 원본의 id/instId를 그대로 물려받아 중복 → 불안정이 발생합니다. hwpxlib.make_uid로 새 ID를 할당하세요. 중첩된 subList>p/tbl/tc/p ID도 포함합니다.
    • 기존 charPr/paraPr 정의를 재사용하고 새로 추가하지 마세요. 꼭 추가해야 한다면 itemCnt를 업데이트하지 않으면 한글이 파일을 거부합니다.
  4. hwpxlib.repack_preserve(src, changed, out, added)로 리패킹하세요: changed = 편집된 항목 (상단에 XML 선언 유지), added = BinData/imageN.png 또는 새 sectionN.xml과 같은 새 항목 (이것들도 content.hpf에 등록하세요).
  5. 모든 빌드 검증: python scripts/verify.py EDITED.hwpx --orig ORIG.hwpx. 모든 하드 검사가 통과해야 합니다 (바이트 정체성 자체 검사, content.hpf 포함 well-formed XML, 중복 ID 없음, ZIP 무결성 + mimetype 첫 번째/STORED). 또한 최소 변경 diff를 출력하여 의도한 변경만 있는지 확인할 수 있습니다.
  6. 한글에서 왕복 테스트. LibreOffice는 HWPX를 렌더링할 수 없으므로, 렌더링 의존적 판단 (제목 고아 문제, 간격이 올바른지 등)은 사용자가 한글에서 파일을 열어 확인해야 하며, 수식/목차의 경우 도구→차례 새로 고침 또는 더블클릭→닫기로 최종 확정해야 합니다. 그렇게 안내하세요.

스크립트 (scripts/) — 실행하세요, 직접 만들지 마세요

스크립트목적
hwpxlib.py라이브러리: repack_preserve, own (실제 본문 텍스트, 각주·미주·메모 제외), make_uid, strip_linesegarray, find_duplicate_ids, structural_counts, §7 검증 도우미. import하여 사용하세요.
inspect_hwpx.py FILE [--text] [--breaks]구조 덤프; 숨은 페이지/단 나누기 찾기.
verify.py EDITED [--orig ORIG]§7 전체 체크리스트 실행; 실패 시 0이 아닌 종료 코드 반환 (CI 게이트 가능).
selftest.py실제 파일 없이 리패커가 무손실임을 증명.
tables_to_xlsx.py FILE [OUT]표를 Excel(.xlsx)로 내보내기, 병합 셀 유지 (openpyxl 필요). 이미지/수식만 있는 셀은 [그림]/[수식]으로 표시; 레거시 .hwp는 거부하고 안내.

스크립트는 lxml이 필요합니다 (pip install lxml); 표→Excel 내보내기는 openpyxl도 필요합니다. Python 3.10+.

가이드 (references/hwpx-guide.md)에서 읽을 위치

필요한 섹션만 로드하세요 — 가이드는 "흔한 실패 TOP" 으로 시작하니 먼저 훑어본 후 다음으로 이동하세요:

  • §1 구조 및 파싱 — 네임스페이스, own(), "모든 섹션 확인", 표 텍스트는 셀별로 (일괄 itertext 안 됨).
  • §2 리패킹 (원시 보존) — 핵심 리패커. hwpxlib와 동일.
  • §3 공통 규칙 — linesegarray 제거, 복제 후 ID 중복 제거.
  • §4 내용 편집 — 문단, 표 (셀 너비 합계는 표 너비와 같아야 하며, 그렇지 않으면 한글이 거부; 병합), 이미지 (orgSz=px×75, 크기 계산, 추출 순서가 아닌 내용으로 검증, matplotlib 가독성 "작은 그림, 큰 텍스트"), 서식, 각주/미주 (<hp:ctrl> 래핑 필수), 메모, 오타 검사 범위 (무차별 정규식 금지).
  • §5 단 · 목차 · 수식 — colPr, TABLEOFCONTENTS (개요 수준 문단에서), 한컴 수식 스크립트 (LaTeX 아님; 형식 표).
  • §6 페이지/단 관리 — 숨은 나누기 먼저, 고아 제목 방지 (keepWithNext, 제목 뒤 빈 문단 없음, 조건부 columnBreak), 빈 페이지 정리, 넓은 표 → 1단 영역 + secPr 블록을 섹션 경계 간 이동.
  • §7 검증 체크리스트 — verify.py가 자동화하는 내용과 왕복 테스트 주의사항.

가드레일

  • 이 스킬은 문서만 편집합니다. 사용자의 자격 증명이 필요 없으며, 원격 콘텐츠를 가져오거나 실행하지 않습니다. 복사본을 작업하고 원본을 보관하세요.
  • 작성자의 내용을 보존하세요: 사용자가 요청한 것만 변경하세요. verify.py의 최소 변경 diff가 증거입니다.

관련 스킬