hwpx_new

한글(HWPX) 서식 파일 하나만 주면, AI 가 그 서식이 어떤 문서인지 스스로 파악하고 — 원하는 목적에 맞게 새로 써서 — 같은 서식의 HWPX 와 PDF 두 파일로 만들어 줍니다.

"이 계획서를 결과보고서로 바꿔줘" · "작년 안내문을 올해로 고쳐줘" · "이 양식으로 새 보고서 만들어줘"

Claude · ChatGPT(Codex) · Gemini · Grok · Cursor · Antigravity 등 어떤 AI 에서도 같은 결과가 나오도록 만든 스킬 + MCP + 명령줄 도구입니다.

표지 띠, 소제목 바, 표 색·테두리, 강조 박스, ● 글머리, 쪽 번호까지 원본 서식 그대로 복제됩니다.

한눈에 보는 작동 방식

서식.hwpx ─▶ ① 분석 ─▶ ② 뼈대 파악 ─▶ ③ AI 가 내용 작성 ─▶ ④ 서식 복제 조립 ─▶ ⑤ PDF 변환
             (표지·소제목·표·박스·         (계획서? 공문?      (Markdown 으로         (원본 서식 그대로     (한글 → 없으면
              글머리 자동 분류)             어떤 절 구성?)      내용만 씀)             HWPX 생성)           LibreOffice → 내장)
                                                                                          │
                              HWPX + PDF ◀─ ⑧ 미리보기 확인 ◀─ ⑦ 자동 보정(쪽 나눔·간격) ◀─ ⑥ 조판 자동 점검

• ⑥ 조판 자동 점검: 빈 쪽, 소제목만 쪽 끝에 홀로 남음, 표가 쪽 사이에서 잘림, 마지막 쪽에 몇 줄만 남음을 PDF 에서 찾아냅니다.

• ⑦ 자동 보정: 쪽 나눔을 넣고 간격을 줄여 스스로 고친 뒤 다시 확인합니다(최대 6회).

• 날짜와 요일이 안 맞으면(예: 2026. 9. 16.(화)) 경고합니다.

Related MCP server: report-mcp

설치 (5분)

1. Python 3.9 이상 설치 (Windows 는 설치 화면에서 Add python.exe to PATH 체크)

2. 이 저장소를 내려받아 설치 프로그램 실행

   • Windows: install.bat 더블클릭

   • macOS/Linux: bash install.sh

   • 또는 한 줄: pip install git+https://github.com/ZZombie04/hwpx_new.git

3. 설치 확인

   hwpx-new doctor

   한글(Hancom Office)이 설치된 Windows 에서는 실제 한글로 PDF 를 만들어 쪽 배치가 가장 정확합니다. 한글이 없으면 Chrome/Edge 기반 내장 렌더러가 근사 PDF 를 만듭니다(HWPX 자체는 동일).

AI 에 연결하기 (가장 쉬운 방법부터)

A. 명령줄 AI (Claude Code · Codex · Gemini CLI · Grok · Antigravity …)

이 폴더를 열고 그냥 말하면 됩니다. 저장소 루트의 AGENTS.md(= CLAUDE.md, GEMINI.md)에 작업 절차 전체가 들어 있어 AI 가 스스로 읽고 분석 → 작성 → 변환 → 확인 → 보정까지 수행합니다.

서식.hwpx 를 분석해서 결과보고서로 만들어줘. 연수는 9/16, 9/22 두 번 했고 각각 11명, 13명 이수했어.

B. MCP (Claude Desktop · Claude Code · Cursor · Windsurf · Codex · Gemini …)

hwpx-new mcp-config        # 내 컴퓨터에 맞는 설정을 프로그램별로 출력합니다

출력된 JSON 을 각 프로그램의 MCP 설정에 붙여 넣으면 hwpx_analyze, hwpx_build, hwpx_preview 등 도구가 생깁니다. Claude Code 는 한 줄이면 됩니다.

claude mcp add hwpx_new -- python -m hwpx_new.mcp_server

자세한 프로그램별 설정은 docs/clients.md.

C. Claude 스킬로 설치

skill/hwpx-new 폴더를 ~/.claude/skills/ 에 복사하면 "이 서식으로 ~ 만들어줘" 같은 요청에서 자동으로 켜집니다.

D. 도구 연결이 없는 채팅 AI (웹 ChatGPT · Gemini · Grok 등)

hwpx-new prompt 서식.hwpx "이 계획서를 결과보고서로 바꿔줘. 이수 24명"   # ← 출력 전체를 AI 채팅창에 붙여넣기
# AI 가 준 Markdown 을 content.md 로 저장한 뒤
hwpx-new build 서식.hwpx content.md -o 결과

이렇게 말하세요 (예시)

AI 는 마지막에 HWPX 경로, PDF 경로, (지어낸 내용이 있다면) 그 목록을 알려 줍니다. 사용자가 주지 않은 숫자·이름을 임의로 만들지 않는다는 규칙이 지침에 들어 있습니다.

명령어 모음

내용 작성 문법 (핵심)

# 문서 제목
@subtitle 작성 부서
## Ⅰ. 소제목
- 글머리 문단
  - 하위 단계
:::box 강조 박스 제목
박스 안 줄
:::
<!-- widths: 1.3, 3.5 -->
| 항목 | 내용 |
|:-:|:-:|
| 연수명 | 2026 ○○ 연수 |
<!-- pagebreak -->
@end

빈 줄·간격·번호 모양·표 테두리는 서식에서 배워서 자동 적용되므로 적지 않습니다. 병합 셀이 있는 표, 기안문의 여러 칸 제목 등은 JSON 블록으로 쓸 수 있습니다 → docs/content-format.md

어떻게 서식을 알아내나요

HWPX 는 ZIP 안의 XML 입니다. hwpx_new 는 문서의 각 블록을 살펴 역할을 붙입니다.

이렇게 배운 서식 요소를 복제해 글만 바꾸므로 글꼴·색·여백이 원본과 같습니다. 자세한 내용은 docs/how-it-works.md.

자주 묻는 질문

PDF 가 한글에서 연 것과 조금 달라요. 한글이 없는 환경에서는 내장 렌더러가 만든 근사 PDF 입니다. 한글이 설치된 Windows 에서는 한글 자신이 PDF 로 저장합니다.

한글 변환이 멈추거나 오래 걸려요. 한글은 외부 프로그램이 파일을 열려 하면 "파일 접근 허용" 보안 승인 창을 띄웁니다(화면 뒤에 숨어 있을 수 있음). 그 창에서 [허용]을 누르면 진행됩니다. 75초 안에 응답이 없으면 자동으로 다음 엔진(LibreOffice → 내장 렌더러)으로 넘어가 PDF 는 반드시 만들어지고, 이 도구가 띄운 한글 프로세스만 정리합니다(사용자가 열어 둔 한글 문서는 건드리지 않습니다). 승인 창이 매번 뜨는 것이 불편하면 한글 자동화 보안 모듈(FilePathChecker) 등록을 직접 검토하세요 — 보안 설정이라 이 도구가 대신 바꾸지 않습니다.

.hwp 파일은요? 옛 형식이라 직접 읽지 않습니다. hwpx-new convert 또는 한글에서 다른 이름으로 저장 → HWPX.

그림·사진이 있는 서식은요? 서식의 표·글은 복제하지만 본문 그림은 새 문서에 넣지 않습니다(붙임으로 따로 첨부).

표에 열이 너무 많으면? 7열 이상이면 경고합니다. 열을 줄이거나 표를 나눠 쓰세요.

한계

• 서식의 첫 번째 구역(섹션)만 사용합니다.

• 각주·수식·도형·그림은 복제하지 않습니다(표지 띠 같은 표 장식은 그대로 유지).

• 기안문처럼 특수한 구조는 clone 블록과 fields 로 칸을 채워야 할 수 있습니다.

개발 / 테스트

pip install -e .
python tests/test_e2e.py      # 서식 분석 → 조립 → PDF → 점검 전 과정
python tests/test_mcp.py      # MCP 서버 왕복

라이선스

MIT — LICENSE