python-hwpx 프로젝트가 직접 유지보수하는 first-party HWPX 에이전트 스킬
문서 편집은 순수 Python으로 수행하며, 최종 시각 검증은 필요할 때 한컴 오라클을 사용합니다.
HWPX를 잘 모르는 사용자도 스킬만 설치하면 Claude Code·Codex·Cursor 같은 에이전트에게 자연어로
말하는 것만으로 한글 문서를 다룰 수 있습니다. 에이전트는 SKILL.md의 의사결정 트리를 따라
알맞은 스크립트나 MCP 도구를 스스로 호출하고, 문서 처리는 코어 python-hwpx가
순수 파이썬으로 수행합니다.
| 레포 | 역할 | |
|---|---|---|
| 📦 | python-hwpx |
순수 파이썬 HWPX 코어 |
| 🔌 | hwpx-mcp-server |
MCP 클라이언트에서 HWPX 조작 |
| 🎯 | hwpx-plugins |
에이전트용 플러그인·스킬 번들 (이 레포) |
호스트의 플러그인 명령으로 스킬과 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를 혼동하지 마세요.
| 구분 | 의미 | 현재 값 |
|---|---|---|
| 공개 릴리스 | 현재 공개된 구성요소 버전 | python-hwpx 4.1.1 · hwpx-mcp-server 5.0.0 · hwpx-plugin 0.7.1 |
| 최소 호환 버전 | 이 공개 스킬 계약이 지원하는 가장 낮은 조합 | python-hwpx >= 4.0.0 · hwpx-mcp-server >= 5.0.0 · skill >= 0.7.0 |
| 플러그인 설치 핀 | 재현 가능한 설치를 위해 고정한 정확 버전 | python-hwpx[visual,preview]==4.1.1 · hwpx-mcp-server==5.0.0 |
- 코어 성숙도:
Development Status :: 3 - Alpha. Python 기준은 3.10 이상입니다. - MCP 서버·플러그인 성숙도: 미선언. 버전 숫자를 성숙도 주장으로 해석하지 않습니다.
- 에이전트 온보딩 스킬 —
SKILL.md의사결정 트리로 에이전트가 요청 성격에 따라 알맞은 스크립트·MCP 도구를 스스로 고름 - 문서 능력 한 벌 — 읽기·양식 채움·생성·편집·공문서·신구대조표·mail merge를 자연어 요청만으로 (엔진은 python-hwpx)
- MCP 서버 동봉 배선 — 호스트별 MCP 설정과 런처가 포함되어 스킬과 도구가 한 번에 로드됨
- 호스트별 번들 — Claude Code·Codex·Cursor·OpenClaw·Hermes 진입점을 한 canonical 소스에서 빌드
- 신뢰 루프 —
render_preview페이지 PNG 자기검증·package/schema/text 검증·시각 검토 evidence 계약
자세한 내용: SKILL.md · references/
설치 후 사용자가 직접 파이썬을 칠 일은 거의 없습니다. 에이전트에게 자연어로 말하면 스킬이 트리거됩니다.
| 이렇게 말하면 | 에이전트가 하는 일 |
|---|---|
| "이 hwpx 텍스트 전부 뽑아줘" | 표 안 문단·각주 포함 텍스트 추출 |
| "이 양식은 그대로 두고 내용만 채워줘" | 바이트 보존 양식 form-fit (셀 채움·행/열 조정·한컴 검증) |
| "머리글·쪽번호 들어간 계획서 새로 만들어줘" | hwpx.builder로 레이아웃 민감 문서 조립 |
| "한컴에서 안 열리는 hwpx인데 복구해줘" | repair/recover 복구 복사본 생성 |
예시 — 사용자: "첨부한 가정통신문 양식에서 학교명이랑 날짜만 우리 학교 걸로 바꿔서 새 파일로 줘." 에이전트가 원본을 보존한 채 form-fit으로 값을 채우고, 패키지·스키마 검증을 거친 새 파일을 돌려줍니다.
이 번들의 문서 능력은 코어 python-hwpx와 hwpx-mcp-server가 수행합니다. 산출물이 실제 한컴오피스에서 열리는지는 코어가 동결 코퍼스 전수를 측정해 그대로 공개합니다 — 실측 코퍼스 메트릭. 스킬은 이 계약 위에서 도구 선택과 evidence 루프만 조율합니다.
- 대상 포맷은 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 · hwpx-mcp-server 위에서 동작하며, 아래 공개 표준·프로젝트에 빚지고 있습니다.
- OWPML — 개방형 워드프로세서 마크업 언어 (KS X 6101) — HWPX가 기반하는 한국 산업 표준
- hancom-io/hwpx-owpml-model — OWPML 요소 구조 참조 모델 · neolord0/hwpxlib — 오라클 샘플 코퍼스
- edwardkim/rhwp — 멱등성·검증 게이트 설계 영감
Apache-2.0 (LICENSE · NOTICE) — Kohkyuhyun @airmang · [email protected]