k-gov-skill(1) hwpx-mouseco: 공공기관 HWPX 보고서 자동화

먼저 결론

이 글은 k-gov-skill(1) hwpx-mouseco: 공공기관 HWPX 보고서 자동화를 실무에서 바로 판단하고 적용할 수 있도록 정리한 보물창고 글입니다. 핵심은 정보를 많이 담는 것이 아니라, 반복 가능한 절차와 확인 기준을 남기는 것입니다. 기존 설명의 핵심은 "hwpx-mouseco 는 공공기관 한글 보고서 양식을 .hwpx 상태로 분석하고, 보고서 JSON을 넣어 원페이퍼·다중페이퍼·장문 보고서를 생성·검증할 때 쓰는 스킬입니다."로 요약할 수 있습니다.

hwpx-mouseco는 공공기관 한글 보고서 양식을 .hwpx 상태로 분석하고, 보고서 JSON을 넣어 원페이퍼·다중페이퍼·장문 보고서를 생성·검증할 때 쓰는 스킬입니다.

이 기능의 목표는 새 문서를 예쁘게 만드는 것이 아닙니다.

기존 HWPX 양식의 구조와 스타일을 보존한 채 내용을 안전하게 채우는 것입니다.

목차

• 해결하는 문제
• 이 기능으로 할 수 있는 일
• 먼저 알아둘 점
• 입력과 출력
• 기본 흐름
• 사용 예시
• 결과 확인 포인트
• 실패 모드
• 관련 파일
• 저장소

해결하는 문제

공공기관 문서 작업에서는 최종 산출물이 HWPX 양식에 들어가야 하는 경우가 많습니다. 그런데 HWPX는 단순 텍스트 파일이 아닙니다. ZIP 패키지 안에 XML, 스타일, 표, 첨부 에셋, 미리보기 텍스트가 함께 들어 있습니다.

본문만 바꿨다고 끝나는 것이 아닙니다. 표 구조, 스타일 참조, 미리보기 텍스트, 첨부 이미지, manifest 참조까지 함께 맞아야 최종 파일을 신뢰할 수 있습니다.

이 기능으로 할 수 있는 일

• .hwpx 파일을 ZIP/XML 구조로 열어 문단, 표, 스타일, 에셋 확인
• 공개 배포용 프로파일 선택
• 보고서 JSON을 HWPX로 변환
• 원페이퍼, 다중페이퍼, 장문 보고서 생성
• 템플릿의 제목, 작성정보, 본문 위계, 표 구조 보존
• validate-only로 패키지, XML, 스타일 참조, 한글 깨짐 점검
• 빈 글머리, 남은 ** 마크다운 표시, 오래된 Preview 텍스트 확인

먼저 알아둘 점

• 이 스킬은 .hwp 바이너리 직접 편집용이 아닙니다. 기본 대상은 .hwpx입니다.
• 단순 텍스트 치환만 하면 문서 구조가 깨질 수 있습니다.
• 템플릿의 문단, 표, 셀, 글상자, 스타일 참조를 최대한 보존해야 합니다.
• 실제 기관 내부 양식, 직인, 서명, 개인정보가 들어간 HWPX는 공개 저장소에 넣지 않습니다.

입력과 출력

입력은 보고서 JSON, 사용할 프로파일 또는 템플릿 경로, 제목, 작성정보, 본문 섹션, 표, 참고 문단입니다. 필요하면 slot map 검토 결과도 함께 씁니다.

출력은 최종 .hwpx 파일, 템플릿 inspection 결과, validate-only 검증 결과, 남은 레이아웃 위험 또는 수동 확인 필요사항입니다.

기본 흐름

HWPX 템플릿 ZIP/XML 구조 확인
-> 프로파일 또는 템플릿 선택
-> report JSON 작성 또는 입력
-> HWPX 생성
-> validate-only 재검증
-> 내부 XML과 Preview/PrvText.txt 확인
-> 실제 HWPX 뷰어에서 최종 확인

사용 예시

$env:PYTHONUTF8='1'; $env:PYTHONIOENCODING='utf-8'; chcp 65001 > $null
python skills\hwpx-mouseco\scripts\create_hwpx_report.py `
  --input skills\hwpx-mouseco\examples\public_ai_adoption_report.json `
  --template "skills\hwpx-mouseco\templates\붙임1 보고서 양식_배포용_원페이퍼.hwpx" `
  --output output\report.hwpx

python skills\hwpx-mouseco\scripts\create_hwpx_report.py --validate-only output\report.hwpx

결과 확인 포인트

• 생성된 .hwpx가 다시 열리는가
• content.hpf manifest와 spine 참조가 맞는가
• header.xml과 section XML 참조가 깨지지 않았는가
• 핵심 본문 텍스트가 실제 XML 안에 들어갔는가
• 템플릿의 표, 글머리, 작성정보 위치가 유지됐는가
• ** 마크다운 표시나 깨진 한글이 남지 않았는가
• Preview/PrvText.txt가 오래된 내용을 보여주지 않는가

실패 모드

• .hwp 바이너리를 직접 편집하려 함
• BinData, manifest, spine, style 참조를 누락함
• 템플릿의 문단 위계를 무시하고 텍스트만 치환함
• inspect 단계에서 Preview/PrvText.txt may not match section text 경고가 나왔는데 확인하지 않음
• 공개 배포용이 아닌 실제 기관 양식을 템플릿으로 넣음

관련 파일

skills/hwpx-mouseco/SKILL.md
skills/hwpx-mouseco/profiles/*.profile.json
skills/hwpx-mouseco/templates/*.hwpx
skills/hwpx-mouseco/scripts/*.py
skills/hwpx-mouseco/references/*.md
skills/hwpx-mouseco/schemas/slot_map.schema.json

저장소

https://github.com/mouseco/k-gov-skills/tree/main/skills/hwpx-mouseco

자주 묻는 질문

이 글은 언제 쓰면 좋나요?

반복 업무를 매번 새로 설명하지 않고, 절차와 검증 기준을 고정하고 싶을 때 적용합니다.

그대로 따라 해도 되나요?

출발점으로는 그대로 써도 됩니다. 다만 실제 업무에서는 목표, 입력 자료, 제약 조건, 검수 기준을 자신의 상황에 맞게 바꾸는 편이 안전합니다.

결과가 기대와 다르면 무엇을 먼저 확인해야 하나요?

먼저 입력이 충분한지, 출력 형식이 명확한지, 하지 말아야 할 조건이 빠지지 않았는지 확인합니다. 문제가 반복되면 실패 사례를 다음 요청에 포함해 기준을 좁힙니다.

정리

k-gov-skill(1) hwpx-mouseco: 공공기관 HWPX 보고서 자동화의 핵심은 이해보다 재사용입니다. 스킬은 읽는 문서보다 실행 절차에 가깝습니다. 한 번 사용한 뒤 막힌 지점을 체크리스트에 반영해야 다음 실행 품질이 올라갑니다.