HWPX(.hwpx/OWPML) 문서 처리 스킬 v3: python-hwpx 기반 열기/생성/편집, TextExtractor로 텍스트 추출, ObjectFinder로 구조 탐색, 대량 치환은 ZIP-level + 네임스페이스 정리(fix_namespaces).
.hwpx는 ZIP 기반 OWPML 문서다. 모든 작업은 hwpx-mcp-server의 MCP 도구를 1차 경로로 사용한다.
MCP가 없을 때의 local Python(python-hwpx >= 2.11.1) 대안과 번들 스크립트는 references 문서에만 있다.
MCP 서버가 연결되어 있으면 작업 전에 mcp_server_health()를 호출해
version, pythonHwpxVersion, toolSurface.status, toolSurface.missingKeyTools를 확인한다.
toolSurface.status != "ok"이거나 핵심 도구가 누락되면 플러그인 재설치
(codex plugin remove hwpx-plugin@hwpx 후 codex plugin add hwpx-plugin@hwpx)
또는 stale plugin venv/cache 제거 후 새 호스트 세션을 시작하라고 안내한다.
단위는 인간 단위다: 글자 크기 pt, 줄간격 %, 들여쓰기 mm, 문단 간격 pt, 용지/여백 mm.
| 사용자 요청 패턴 | 1차 경로 (MCP 도구) | 상세 참조 |
|---|---|---|
| 문서 구조·표·양식 필드·앵커를 한 번에 파악 | get_document_map |
workflows-editing |
| 텍스트·개요·표 내용 읽기 | get_document_text · get_document_outline · get_table_text |
api |
| Markdown/HTML/JSON 변환·추출 | hwpx_to_markdown · hwpx_to_html · hwpx_extract_json |
api |
| 텍스트 위치·라벨 옆 셀 찾기 | find_text · find_cell_by_label |
workflows-editing |
| 본문·표 편집 (기본 경로, 2건 이상이면 필수) | apply_edits (dry_run → 확정) |
workflows-editing |
| 단건 치환·문단·표 셀 편집 | search_and_replace · batch_replace · insert_paragraph · set_table_cell_text |
workflows-editing |
| 직전 편집 되돌리기 | undo_last_edit |
workflows-editing |
| 줄간격·정렬·들여쓰기·문단 간격 변경 | set_paragraph_format |
workflows-editing |
| 용지 크기·방향·여백·단 설정 | set_page_setup |
workflows-editing |
| 머리글/바닥글 추가·수정 | set_header_footer |
workflows-editing |
| 쪽번호 추가·수정 | set_page_number |
workflows-editing |
| 기존 문단을 불릿/번호 목록으로 | set_list_format |
workflows-editing |
| 그림 삽입 / 그림만 교체 | insert_picture · replace_picture |
workflows-editing |
| 굵게·색·글꼴 등 글자 서식, 사용자 스타일 | format_text · create_custom_style · list_styles |
workflows-editing |
| 표 병합·분할·머리행 표시 | merge_table_cells · split_table_cell · format_table |
workflows-editing |
| 검토 메모 추가·삭제 | add_memo · add_memo_by_anchor · remove_memo |
workflows-editing |
| 충실도 민감·대형 문서의 문단 텍스트 패치 | byte_preserving_patch |
workflows-editing |
| 생성/편집 후 레이아웃 확인 | render_preview self-check 루프 |
workflows-editing |
| 자연어 요청으로 새 문서 생성 | validate_document_plan → create_document_from_plan |
workflows-creation |
| 머리글·쪽번호·리치 런·병합 표 조립 생성 | hwpx.builder (local) |
workflows-creation |
| 정부보고서·공문형 보고서 (□/○/※ 불릿) | parse_government_report_text → compute_report_value → create_government_report_document |
workflows-creation |
| 운영 계획서 제출 후보 | document-plan + quality_profile="operating_plan" |
workflows-creation |
| 제안서·기획안 | create_proposal_document → inspect_document_quality |
workflows-creation |
| 공문서 작성규정 lint·결재란 | inspect_official_document_style |
workflows-creation, 규정 |
| 누름틀/FORM 필드 채움 | list_form_fields → fill_form_field / analyze_form_fill → apply_form_fill |
workflows-forms |
| 승인된 양식 보존 채움 (baseline) | analyze_template_formfit → apply_template_formfit |
workflows-forms |
| 양식 + 아이디어로 고품질 완성 | analyze_quality_generation → apply_quality_generation |
workflows-forms |
| 메일머지 N부 대량생산 (상장·수료증·안내장) | mail_merge |
workflows-bulk-compare |
| 표 합계·평균·소계 계산 | table_compute |
workflows-bulk-compare |
| 두 문서/문단 비교 (신구 diff) | doc_diff |
workflows-bulk-compare |
| 신구대조표 문서 생성 | create_comparison_table_document |
workflows-bulk-compare |
| 사진대지 생성 | build_image_grid → create_document_from_plan |
workflows-bulk-compare |
| 회의 명패 생성 | build_meeting_nameplates → create_document_from_plan |
workflows-bulk-compare |
| 조직도 생성 | build_organization_chart → create_document_from_plan |
workflows-bulk-compare |
| 참조 문서 서식 이식·템플릿 등록 | extract_style_profile · apply_style_profile_to_plan · register_template |
workflows-bulk-compare |
| 붙임·표/그림 번호 정합성 검사 | inspect_reference_consistency |
workflows-bulk-compare |
| 깨졌거나 한컴에서 안 열리는 파일 | repair_hwpx (복구 복사본 생성) |
api |
| 원본 보존용 사본 만들기 | copy_document |
api |
| MCP 없음: 텍스트 추출·표 포함 전역 치환 | scripts/text_extract.py · scripts/zip_replace_all.py |
api |
copy_document 사본 또는
별도 destination에서 작업한다. 양식 채움은 항상 원본과 다른 destination에만 적용한다.openSafety.ok == true
(또는 verification.openSafety.ok == true)를 확인한다. false인 파일은 handoff하지 않는다.dry_run=true로 semanticDiff를 먼저 확인한 뒤 확정 저장한다.visual_review_required=true이면
references/evidence-contract.md의 요건
(current.status == "observed_pass" + current.screenshot_path)을 충족하기 전에는
최종 제출 가능 상태라고 주장하지 않는다.repair_hwpx로 복구 복사본을 만든다.<, > 같은 XML 조각을 넣지 않는다. 태그가 아닌 텍스트 플레이스홀더만 치환한다.get_document_map(filename) — 개요·표·양식 필드·앵커와 document_revision을 확보한다.apply_edits(filename, operations, dry_run=true) — semanticDiff와 openSafety.ok를 확인한다.apply_edits(filename, operations, expected_revision=<1의 document_revision>)로 확정한다.ok, openSafety.ok, semanticDiff를 확인한다.
reason: "document revision mismatch"면 문서를 다시 읽고 새 revision으로 재시도한다.undo_last_edit(filename)로 직전 저장 전 상태로 되돌린다.idempotency_key를 부여해 중복 적용을 막는다.연산 스키마와 응답 키 상세는 references/workflows-editing.md를 본다.
references/workflows-editing.md — 트랜잭션 편집 루프, 서식 5종, 그림, byte patch, render_preview.references/workflows-creation.md — document-plan, builder, 정부보고서, 운영계획서, 제안서, 공문서 레시피.references/workflows-forms.md — 양식 3경로 결정표, 누름틀, form-fit, 품질 생성.references/workflows-bulk-compare.md — 메일머지, 표 계산, 신구대조, 생성기 3종, 스타일 프로파일/템플릿.references/evidence-contract.md — openSafety·visual-review v1·hard gates·제출 증거 계약.references/api.md — python-hwpx 시그니처, MCP 도구 표, repair/recover, 번들 스크립트.references/official-document-rules.md — 공문서 항목 표시·끝 표시·붙임·날짜/금액 규칙.python3 examples/01_create_and_save.py → python3 scripts/text_extract.py examples/out/01_created.hwpx.
