hwpx

name hwpx description HWP/HWPX 문서(.hwp, .hwpx) 변환·생성·읽기·편집, HTML 활동지→편집 가능한 HWPX 변환 스킬. 'HWP 변환', 'hwp를 hwpx로', '한글 문서', 'hwpx', 'HWPX', '한글파일', '.hwpx 만들어줘', '보고서', '공문', '기안문', '한글로 작성', '회의록', '제안서', '이미지 포함 문서', 'HTML을 HWPX로', 'K-Teacher 스타일', '컬러 활동지' 등의 요청 시 사용한다. Windows에서는 설치된 한컴오피스 Automation COM 엔진으로 HWP를 HWPX로 빠르게 변환한 뒤 읽기·편집을 이어가며, 사용할 수 없으면 내장 rhwp WASM 변환기로 폴백한다. allowed-tools Bash(python3 *), Bash(powershell.exe *), Bash(pwsh *), Read, Write, Glob, Grep HWPX 통합 문서 스킬 HWPX는 한컴오피스 한글의 개방형 문서 포맷이다. ZIP 패키지 + XML 파트 구조. 스킬 디렉토리 ${CLAUDE_SKILL_DIR}/ ├── SKILL.md ├── scripts/ │ ├── hwpx_helpers.py # ★ 헬퍼 라이브러리 (배너/섹션바/이미지/빌드 함수) │ ├── convert_hwp.py # ★ HWP→HWPX 변환 (Workflow H) │ ├── convert_hwp_hancom.ps1 # ★ Windows 한컴 COM 고속·일괄 변환 (Workflow H 우선) │ ├── build_hwpx.py # 템플릿+XML → .hwpx 조립 │ ├── fix_namespaces.py # ★ 필수: 네임스페이스 후처리 │ ├── validate.py # HWPX 구조 검증 │ ├── finalize_hwpx.py # line cache removal, layout QA, Hancom open test │ ├── analyze_template.py # HWPX 심층 분석 │ ├── clone_form.py # ★ 양식 복제 (Workflow F) │ ├── fill_hwpx.py # ★★ 양식 필드 채우기 + 머리말/꼬리말/쪽번호/표구조/수식 in-place (Workflow J) │ ├── secure_fill.py # ★ 개인정보(PII) 비경유 양식 채우기 │ ├── verify_hwpx.py # ★ 서브에이전트 검수 도구 │ ├── text_extract.py # 텍스트 추출 │ ├── build_problem_answer_sheet.py # 문제지 1장 + 답안지 1장 생성 │ ├── md2hwpx.py # 마크다운→HWPX 자동 변환 │ ├── gonmun.py # ★ 행정안전부 표준 기안문(별지 제1호서식) 생성기 (Workflow G) │ ├── gonmun_lint.py # ★ 공문서 작성법 자동 검수기 (2025 편람) │ ├── yoyak.py # ★ 요약보고(결재선 달린 1~3쪽 약식 보고) 생성기 — 마크다운 입력 (Workflow Y) │ ├── geomto.py # ★ 기본계획·검토보고(로마숫자 장 배너, 표지 선택) 생성기 — 마크다운 입력 (Workflow Y) │ ├── munche_lint.py # ★ 개조식 보고서 원고 문체 검문기 (서술형 종결·수사적 대조·길이·표기) (Workflow Y) │ ├── bodojaryo.py # ★ 정부 표준 보도자료 생성기 (레퍼런스 복제 방식) │ ├── gyehoek.py # ★ 공공기관 계획서 생성기 (행안부 업무계획 복제, 제목/목차 토글) │ ├── gyehoek_hook.py # ★ PreToolUse 훅 — 계획서 생성 전 제목/목차 포함 여부 강제 질문 │ ├── report_placeholder_hook.py # ★ PreToolUse 훅 — 기관명 미입력 보고서 전달 차단 │ └── office/{unpack,pack}.py ├── templates/ │ ├── base/ # 베이스 Skeleton │ ├── report/ # 보고서 │ ├── gonmun/ # 공문(간이형) │ ├── gonmun2025/ # ★ 행정안전부 표준 기안문 별지 제1호서식 (맑은 고딕 11.5pt) │ ├── yoyak/ # ★ 요약보고 스타일(header.xml) — 실측값에서 파생, 원본 흔적 없음 │ ├── geomto/ # ★ 기본계획·검토보고 스타일(header.xml = yoyak + 장 배너·표지) │ ├── minutes/ # 회의록 │ ├── proposal/ # 제안서 ├── assets/ │ ├── report-template.hwpx │ ├── gyehoek-reference.hwpx # ★ 공공기관 계획서 기본양식(행안부 2025 업무계획) — gyehoek.py가 복제 │ ├── bodojaryo-reference.hwpx # ★ 정부 표준 보도자료 양식(고정) — bodojaryo.py가 복제 │ └── problem-answer-reference.hwpx └── references/ ├── xml-structure.md # XML 구조, 이미지 삽입, 표지/섹션 바 패턴 ├── template-styles.md # 템플릿별 스타일 ID 맵 ├── troubleshooting.md # 트러블슈팅 ├── report-style.md # 보고서 양식 상세 ├── official-doc-style.md # 공문서 양식 상세 ├── gonmunseo-2025-writing-rules.md # ★ 2025 개정 공문서 작성법 ├── yoyak-bogo-style.md # ★ 요약보고 서식 실측·파생 (Workflow Y) ├── geomto-bogo-style.md # ★ 기본계획·검토보고 서식 실측·파생 (Workflow Y) ├── bogo-munche.md # ★ 개조식 보고서 문체 — 실측 15건 통계·규칙·검문표 (Workflow Y) ├── kordoc-integration.md # kordoc 장점 채택/보류 기준 └── xml-internals.md # 저수준 XML 구조 환경 설정 pip install python-hwpx lxml --break-system-packages # HWP→HWPX 변환 (Workflow H) # Windows: 한컴오피스 한글 + HwpAutomation 파일 경로 보안 모듈 권장(추가 Python 의존성 없음) # 그 외/폴백: Node.js 18+, rhwp WASM 런타임은 scripts/vendor/rhwp에 고정·포함 Mandatory Finalization And QA Run this finalization sequence for every generated or edited .hwpx before delivering it to a user: python3 " ${CLAUDE_SKILL_DIR} /scripts/fix_namespaces.py" output.hwpx python3 " ${CLAUDE_SKILL_DIR} /scripts/finalize_hwpx.py" output.hwpx --strip-linesegarray --layout python3 " ${CLAUDE_SKILL_DIR} /scripts/validate.py" output.hwpx --layout On Windows with Hancom Office installed, add a real open test: python3 " ${CLAUDE_SKILL_DIR} /scripts/validate.py" output.hwpx --hancom Rules: After any XML-level text replacement, remove hp:linesegarray . These are Hancom line-layout caches; stale caches can make Hancom show a damaged-file restore warning even when ZIP/XML validation passes. Treat validate.py as structural validation only unless --layout or --hancom is used. XML validity does not prove that Hancom can open the file or that long text fits the template. For template forms, preserve the template structure. If content is too long, split the content into multiple paragraphs/list items and increase row heights. Do not change the template just to fit existing prose. For subcategory body text, create real new paragraphs with the template body style or visible list/indent markers. Do not put several long sentences into one <hp:t> and rely on visual wrapping. For table rows with increased cell heights, update every cell in that row and keep the table-level hp:sz/@height consistent with the row heights. ★ 워크플로우 선택 (Decision Tree) 반드시 아래 판단을 따른다. 사용자 요청 ├─ ".hwp 파일 → 변환/읽기/편집" → 워크플로우 H로 별도 HWPX 생성 후 해당 워크플로우 계속 ★★ ├─ "마크다운/텍스트/URL → HWPX" → 워크플로우 A (콘텐츠→HWPX) ├─ "양식의 빈칸/필드 채워줘" (라벨-값, 체크박스, 괄호 빈칸) → 워크플로우 J (필드 채우기) ★★★ ├─ "양식에 내용 채워줘" ({{플레이스홀더}} 템플릿) → 워크플로우 B (템플릿 치환) ├─ "HWPX 수정해줘" → 워크플로우 C (기존 문서 편집) ├─ "이 HWPX 양식으로 만들어줘" → 워크플로우 D (레퍼런스 기반) ├─ "이 양식 복제해서 내용 바꿔줘" → 워크플로우 F (양식 복제) ★ ├─ "공문 작성해줘/공문서 검수해줘" → 워크플로우 G (공문서 작성법 준수) ★ ├─ "요약보고/약식보고/단장님·부시장님 보고용 한 장" (결재선 + □❍- 개조식) → 워크플로우 Y (yoyak) ★ ├─ "기본계획/검토보고/검토서 만들어줘" (Ⅰ Ⅱ Ⅲ 장 배너, 표지·결재란 선택) → 워크플로우 Y (geomto) ★ ├─ "문제지 한장 답안지 한장", "문제지+답안지", "정답지 포함 활동지" → 워크플로우 I ★ ├─ "HTML 디자인을 HWPX로", "K-Teacher 스타일", "컬러 활동지" → 워크플로우 K ★ └─ "HWPX 읽어줘" → 워크플로우 E (읽기/추출) ⚠️ 원본 형식 보존 규칙 (사용자가 .hwp 파일을 제공한 경우) HWP 바이너리는 직접 수정하지 않는다. 읽기·편집 등 작업에 HWP 내용이 필요하면 원본을 그대로 보존하고 별도 .hwpx 를 자동 생성한 뒤 후속 워크플로우를 계속한다. 입력 파일 확인 ├─ .hwp 파일 │ ├─ "HWPX로 변환해줘" → 워크플로우 H (원본 유지, 별도 .hwpx 출력) │ ├─ "읽어줘/텍스트 추출" → 워크플로우 H → E │ └─ "수정해줘/채워줘" → 워크플로우 H → C/J/F (별도 HWPX 결과) └─ .hwpx 파일 → 기존 워크플로우 판별 (아래) 변환으로 생긴 HWPX는 반드시 검증한 뒤 사용한다. 사용자가 결과 형식을 HWP로 유지하라고 명시했거나 변환을 금지한 경우에는 자동 변환하지 말고 제한을 안내한다. ⚠️ 자동 판별 규칙 (사용자가 양식 파일을 제공한 경우) 사용자가 .hwpx 파일을 주고 "이걸로 테스트", "내용 바꿔줘", "이 양식으로" 등을 요청하면 먼저 clone_form.py --analyze 로 구조를 확인한다. 양식 분석 결과 ├─ 빈 값 셀/체크박스/괄호 빈칸이 있는 신청서·서식 → 워크플로우 J (필드 채우기) ★★★ ├─ 테이블 ≥ 1개 또는 이미지 ≥ 1개, 기존 문구를 새 문구로 교체 → 워크플로우 F (양식 복제) ★★★ ├─ 테이블 0개, 이미지 0개, 단순 텍스트 → 워크플로우 C 또는 D 가능 └─ 판단 불가 → `fill_hwpx.py analyze` 먼저 실행 — 타겟이 있으면 J, 없으면 F 절대 하지 말 것: <hp:t> 노드를 순차적으로 새 텍스트로 덮어쓰기 — 런(run) 소실, 서식 파괴 lxml로 텍스트 노드를 직접 조작 — 네임스페이스/속성 손실 위험 새 section0.xml을 처음부터 작성 (Workflow A/D) — 구조 97.5% 손실 반드시 할 것: clone_form.py 의 clone() 함수 또는 ZIP-level 문자열 치환 사용 치환은 str.replace() 기반으로 XML 구조를 건드리지 않음 워크플로우 I: 문제지 1장 + 답안지 1장 생성 학생용 문제지와 교사용 답안지를 한 파일 안에 2쪽 구조로 만든다. 1쪽은 문제지 , 2쪽은 답안지 이며, 전체를 표 기반으로 구성한다. 입력 JSON { "title" : "수업 제목" , "unit" : "영상 수업" , "subtitle" : "핵심 내용과 실천 목표" , "subject" : "국어" , "main_actor" : "학생" , "scenes" : [ { "title" : "도입" , "summary" : "핵심 내용을 한 문장으로 정리한다." } , { "title" : "전개" , "summary" : "중요 장면과 근거를 정리한다." } , { "title" : "정리" , "summary" : "배운 점과 실천 목표를 쓴다." } ] , "change" : "변화나 배운 점 예시 답안" , "theme" : "핵심 주제 예시 답안" } 생성 명령 python3 " ${CLAUDE_SKILL_DIR} /scripts/build_problem_answer_sheet.py" \ --input-json lesson.json \ --output lesson-sheet.hwpx python3 " ${CLAUDE_SKILL_DIR} /scripts/validate.py" lesson-sheet.hwpx 품질 기준 assets/problem-answer-reference.hwpx 에서 header/secPr/style을 가져온다. 문제지와 답안지 사이에는 pageBreak="1" 이 정확히 1개 있어야 한다. 구조 검증은 validate.py 로 통과해야 한다. 최종 HWPX의 Contents/section0.xml 에는 문제지 , 답안지 , 첫 번째 활동 , 두 번째 활동 , 세 번째 활동 , 정답 , 예시 답안 텍스트가 있어야 한다. JSON 입력에 \\n 이 들어와도 실제 줄바꿈으로 정규화한다. 워크플로우 K: K-Teacher 학생 활동지 HTML → HWPX K-Teacher가 실제 생성하는 학생 활동지 HTML을 편집 가능한 HWPX 표·문단·네이티브 둥근 도형으로 변환한다. 임의의 브라우저 CSS를 복제하는 범용 변환기가 아니라 .doc-header , section.block , student_task , source_card , answer_box , exit_ticket , 자료표와 쪽 나누기를 결정론적으로 매핑한다. 디자인 기준은 저장소 루트 DESIGN.md 를 따른다. python3 " ${CLAUDE_SKILL_DIR} /scripts/html2hwpx.py" input.html output.hwpx \ --keep-xml build/html2hwpx 변환 단계와 지원 HTML은 references/html-to-hwpx.md 를 따른다. 결과는 스크립트 내부에서 fix_namespaces.py , finalize_hwpx.py --strip-linesegarray --layout , validate.py --layout 까지 통과해야 한다. 워크플로우 A: 콘텐츠 → HWPX (가장 중요!) 마크다운·텍스트·URL → 구조화된 HWPX 문서. 이 워크플로우가 핵심. 마크다운 한 편을 그대로 문서로 만들 때는 md2hwpx.py 가 가장 빠르다. 표지·배너처럼 문단을 직접 조립해야 하는 구조가 필요하면 hwpx_helpers.py 를 import 해 아래 흐름을 따른다. 전체 흐름 [1] 소스 자료 읽기 [2] 구조 파싱 (제목, 섹션, 본문, 이미지) [3] 템플릿 선택 → 해당 템플릿의 스타일 ID만 사용 (references/template-styles.md) ⚠️ 템플릿 간 ID는 호환되지 않음! report charPr를 base에 쓰면 깨짐 [4] hwpx_helpers.py를 import하여 Python 빌드 스크립트 작성 [5] build_hwpx.py로 .hwpx 조립 [6] 이미지가 있으면 add_images_to_hwpx() + update_content_hpf() [7] fix_namespaces.py 후처리 (필수!) [8] validate.py 검증 사용 예: from hwpx_helpers import * → make_first_para() → make_body_para() → make_image_para() section0.xml 핵심 규칙 첫 문단 첫 run에 secPr + colPr 필수 — 없으면 문서가 안 열림 모든 문단 id는 고유 정수 XML 특수문자 <>&" 반드시 이스케이프 표지→본문 사이 pageBreak="1" 문단 삽입 XML 구조 상세: references/xml-structure.md 빌드 명령 # 1. section0.xml을 임시 파일로 작성 (Python 스크립트로 생성) # 2. 빌드 (예: report 템플릿) python3 " ${CLAUDE_SKILL_DIR} /scripts/build_hwpx.py" \ --template report \ --section /tmp/section0.xml \ --title "문서 제목" \ --output result.hwpx # 3. 네임스페이스 후처리 (필수!) python3 " ${CLAUDE_SKILL_DIR} /scripts/fix_namespaces.py" result.hwpx # 4. 검증 python3 " ${CLAUDE_SKILL_DIR} /scripts/validate.py" result.hwpx Python 빌드 스크립트 패턴 scripts/hwpx_helpers.py 를 import하여 검증된 함수를 재사용한다. import subprocess, sys from pathlib import Path sys.path.insert( 0 , str (Path( "${CLAUDE_SKILL_DIR}/scripts" ))) from hwpx_helpers import * SKILL_DIR = Path( "${CLAUDE_SKILL_DIR}" ) REF_HWPX = SKILL_DIR / "assets" / "gyehoek-reference.hwpx" OUTPUT = Path( "output.hwpx" ) # 1. secPr 추출 secpr, colpr = extract_secpr_and_colpr(REF_HWPX) # 2. section0.xml 조립 parts = [] parts.append( f'<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>' ) parts.append( f'<hs:sec {NS_DECL} >' ) parts.append(make_first_para(secpr, colpr)) parts.append(make_text_para( "문서 제목" , charpr= "7" , parapr= "20" )) parts.append(make_empty_line()) parts.append(make_body_para( "가." , "본문 내용" )) parts.append( f'</hs:sec>' ) section_xml = "\n" .join(parts) # 3. 빌드 Path( "/tmp/section0.xml" ).write_text(section_xml, encoding= "utf-8" ) subprocess.run([ "python3" , str (SKILL_DIR/ "scripts/build_hwpx.py" ), "--template" , "report" , "--section" , "/tmp/section0.xml" , "--output" , str (OUTPUT)], check= True ) # 4. (이미지 있으면) add_images_to_hwpx() + update_content_hpf() # 5. 후처리 + 검증 subprocess.run([ "python3" , str (SKILL_DIR/ "scripts/fix_namespaces.py" ), str (OUTPUT)], check= True ) subprocess.run([ "python3" , str (SKILL_DIR/ "scripts/validate.py" ), str (OUTPUT)]) hwpx_helpers.py 제공 함수 함수 설명 next_id() 고유 ID 생성 xml_escape(text) XML 특수문자 이스케이프 extract_secpr_and_colpr(hwpx) HWPX에서 secPr+colPr 추출 make_first_para(secpr, colpr) 첫 문단 (secPr 포함) make_empty_line() 빈 줄 make_page_break() 페이지 넘김 make_text_para(text, charpr, parapr) 텍스트 문단 make_body_para(marker, text) 본문 (마커+내용) make_image_para(binary_item_id, w, h) 이미지 (전체 hp:pic 구조) add_images_to_hwpx(path, images) ZIP에 이미지 추가 update_content_hpf(path, images) content.hpf에 이미지 등록