python-hwpx 프로젝트가 직접 유지보수하는 first-party HWPX 에이전트 스킬

문서 편집은 순수 Python으로 수행하며, 최종 시각 검증은 필요할 때 한컴 오라클을 사용합니다.

HWPX를 잘 모르는 사용자도 스킬만 설치하면 Claude Code·Codex·Cursor 같은 에이전트에게 자연어로 말하는 것만으로 한글 문서를 다룰 수 있습니다. 에이전트는 SKILL.md의 의사결정 트리를 따라 알맞은 스크립트나 MCP 도구를 스스로 호출하고, 문서 처리는 코어 python-hwpx가 순수 파이썬으로 수행합니다.

호스트의 플러그인 명령으로 스킬과 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@hwpx

Cursor는 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를 혼동하지 마세요.

• 코어 성숙도: 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/

설치 후 사용자가 직접 파이썬을 칠 일은 거의 없습니다. 에이전트에게 자연어로 말하면 스킬이 트리거됩니다.

예시 — 사용자: "첨부한 가정통신문 양식에서 학교명이랑 날짜만 우리 학교 걸로 바꿔서 새 파일로 줘." 에이전트가 원본을 보존한 채 form-fit으로 값을 채우고, 패키지·스키마 검증을 거친 새 파일을 돌려줍니다.

이 번들의 문서 능력은 코어 python-hwpx와 hwpx-mcp-server가 수행합니다. 산출물이 실제 한컴오피스에서 열리는지는 코어가 동결 코퍼스 전수를 측정해 그대로 공개합니다 — 실측 코퍼스 메트릭. 스킬은 이 계약 위에서 도구 선택과 evidence 루프만 조율합니다.

• 대상 포맷은 Open XML 기반 .hwpx입니다. 레거시 바이너리 .hwp 직접 편집은 범위 밖입니다.
• visual_review_required=true는 package/schema/text 검사는 통과했지만 열린 문서의 페이지 나눔·표 맞춤은 아직 미확인이라는 뜻입니다. 최종 제출을 말하려면 viewer에서 열어 observed_pass evidence를 남깁니다.
• 예제·문서에는 이름·전화번호·이메일·주소 등 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 · kokyuhyun@hotmail.com