python-hwpx 프로젝트가 직접 유지보수하는 first-party HWPX 에이전트 스킬
문서 편집은 순수 Python으로 수행하며, 최종 시각 검증은 필요할 때 한컴 오라클을 사용합니다.
Note
현재 공개 트레인은 python-hwpx 6.0.2 · python-hwpx-automation 7.0.1 ·
hwpx-plugin 2.0.0입니다 (released 2026-08-04 — 엔진 완전성 트레인, 계약
34a91560759dc47a).
HWPX를 잘 몰라도 됩니다. 스킬을 설치하면 Claude Code·Codex·Cursor 같은
에이전트에게 자연어로 말하는 것만으로 한글 문서를 다룰 수 있습니다. 에이전트는
SKILL.md의 의사결정 트리를 따라 알맞은 스크립트와 MCP 도구를 스스로 고르고,
문서 처리는 코어 python-hwpx가 순수
파이썬으로 수행합니다.
| 저장소 | 역할 | |
|---|---|---|
| 📦 | python-hwpx |
HWPX 문서를 읽고·고치고·만드는 순수 파이썬 엔진 |
| 🔌 | python-hwpx-automation |
저작·양식 채움 워크플로, hwpx CLI, 선택형 MCP 서버 |
| 🎯 | hwpx-plugins |
에이전트가 알맞은 도구를 고르도록 돕는 플러그인/스킬 번들 |
응용 저장소는 python-hwpx-automation으로 이름을 바꿨습니다 — 정식 배포·
import·콘솔은 각각 python-hwpx-automation · hwpx_automation ·
hwpx-automation-mcp이고, 기존 hwpx-mcp-server 표면은 6.x 동안 그대로
동작합니다.
호스트의 플러그인 명령으로 스킬과 MCP 서버를 함께 설치합니다. 설치·재설치 후에는 새 에이전트 세션을 시작해야 새 skill과 MCP 도구가 로드됩니다.
# Claude Code
claude plugin marketplace add airmang/hwpx-plugins
claude plugin install hwpx-plugin@hwpx
# Codex CLI
codex plugin marketplace add airmang/hwpx-plugins
codex plugin add hwpx-plugin@hwpxCursor는 canonical skill 파일을 .cursor/skills/hwpx/(또는 글로벌 ~/.cursor/skills/hwpx/)에 복사하고
.cursor/rules/hwpx.mdc 트리거 룰을 둡니다. OpenClaw·Hermes는 각 호스트 번들(plugins/openclaw/hwpx-plugin,
plugins/hermes/hwpx)에 MCP 배선 안내가 함께 들어 있습니다. 저장소 이름 hwpx-plugins와 설치되는
skill 이름 hwpx를 혼동하지 마세요.
설치 후 사용자가 직접 파이썬을 칠 일은 거의 없습니다. 에이전트에게 자연어로 말하면 스킬이 트리거됩니다.
| 이렇게 말하면 | 에이전트가 하는 일 |
|---|---|
| "이 hwpx 텍스트 전부 뽑아줘" | 표 안 문단·각주 포함 텍스트 추출 |
| "이 양식은 그대로 두고 내용만 채워줘" | 바이트 보존 양식 form-fit (셀 채움·행/열 조정·한컴 검증) |
| "머리글·쪽번호 들어간 계획서 새로 만들어줘" | 문서 빌더(document plan)로 레이아웃 민감 문서 조립 |
| "한컴에서 안 열리는 hwpx인데 복구해줘" | repair/recover 복구 복사본 생성 |
예시 — 사용자: "첨부한 가정통신문 양식에서 학교명이랑 날짜만 우리 학교 걸로 바꿔서 새 파일로 줘." 에이전트가 원본을 보존한 채 form-fit으로 값을 채우고, 패키지·스키마 검증을 거친 새 파일을 돌려줍니다.
- 에이전트 온보딩 스킬 —
SKILL.md의사결정 트리로 요청 성격에 맞는 스크립트·MCP 도구를 스스로 선택 - 문서 능력 한 벌 — 읽기·양식 채움·생성·편집·공문서·신구대조표·mail merge
- MCP 서버 동봉 배선 — 호스트별 MCP 설정과 런처가 포함되어 스킬과 도구가 한 번에 로드
- 호스트별 번들 — Claude Code·Codex·Cursor·OpenClaw·Hermes 진입점을 한 canonical 소스에서 빌드
- 신뢰 루프 —
render_preview페이지 PNG 자기검증·package/schema/text 검증·시각 검토 evidence
자세한 내용: SKILL.md · references/
| 구분 | 의미 | 현재 값 |
|---|---|---|
| 완전한 공개 트레인 | 현재 공개 릴리스 — plugin 설치까지 함께 검증한 조합 (released 2026-08-04, 엔진 완전성 트레인) | python-hwpx 6.0.2 · python-hwpx-automation 7.0.1 · hwpx-plugin 2.0.0 |
| 최소 호환 버전 | 2.0 스킬 계약이 지원하는 가장 낮은 조합 | python-hwpx >= 6.0.2 · python-hwpx-automation >= 7.0.1 · skill >= 2.0.0 |
| 플러그인 설치 핀 | 번들이 고정한 정확 버전 | python-hwpx[preview]==6.0.2 · python-hwpx-automation[mcp,oracle]==7.0.1 |
- 코어 성숙도:
Development Status :: 3 - Alpha. Python 기준은 3.10 이상입니다. - MCP 서버·플러그인 성숙도: 미선언. 버전 숫자를 성숙도 주장으로 해석하지 않습니다.
산출물이 실제 한컴오피스에서 열리는지는 코어가 동결 코퍼스 전수로 측정해 그대로 공개합니다 — 실측 코퍼스 메트릭.
- 대상 포맷은 Open XML 기반
.hwpx입니다. 레거시 바이너리.hwp직접 편집은 범위 밖입니다. visual_review_required=true는 package/schema/text 검사는 통과했지만 열린 문서의 페이지 나눔·표 맞춤은 아직 미확인이라는 뜻입니다. 최종 제출을 말하려면 viewer에서 열어observed_passevidence를 남깁니다.- 예제·문서에는 이름·전화번호·이메일·주소 등 PII를 redaction 없이 넣지 않습니다.
Discussions · 이슈 · CONTRIBUTING · CHANGELOG
canonical SKILL.md·references/·examples/·scripts/를 편집한 뒤
python3 scripts/build_hwpx_plugins.py로 호스트 번들을 재빌드하고
python3 scripts/validate_hwpx_plugin.py로 검증합니다.
python-hwpx · python-hwpx-automation 위에서 동작하며, 아래 공개 표준·프로젝트에 빚지고 있습니다.
- OWPML — 개방형 워드프로세서 마크업 언어 (KS X 6101) — HWPX가 기반하는 한국 산업 표준
- hancom-io/hwpx-owpml-model — OWPML 요소 구조 참조 모델 · neolord0/hwpxlib — 오라클 샘플 코퍼스
- edwardkim/rhwp — 멱등성·검증 게이트 설계 영감
Apache-2.0 (LICENSE · NOTICE) — Kohkyuhyun @airmang · kokyuhyun@hotmail.com