Hwp Batch Convert

Use this skill for Windows 기반 한글(HWP/HWPX) 문서 일괄 변환.

Current scope:

• 폴더 단위 일괄 변환
• 파일 여러 개 일괄 변환
• HWP/HWPX → PDF 기본 변환
• HWP/HWPX → HWPX/DOCX/ODT/HTML/RTF/TXT/PNG/JPG/BMP/GIF 변환
• 동일 형식 자동 건너뜀
• 출력 파일명 충돌 시 자동 번호 부여
• 작업 계획만 확인하는 --plan-only
• OpenClaw 상위 레이어 연동용 --json, --report-json
• 한글 보안 확인 팝업 자동 허용용 --auto-allow-dialogs
• 로컬 UI 검증용 --self-test-dialog-handler
• 테스트용 --mode mock

Source basis

This skill reuses the design of the local/source repo:

• tmp/HwpMate
• upstream: https://github.com/twbeatles/HwpMate

Main logic origin:

• hwpmate/services/hwp_converter.py
• hwpmate/services/task_planner.py
• hwpmate/constants.py
• hwpmate/path_utils.py

If you need the mapping details or reuse rationale, read:

• references/hwpmate-reuse-notes.md

If you need the popup whitelist / safety details, read:

• references/auto-allow-dialogs.md

Quick start

같은 폴더에 PDF 출력:

python skills/hwp-batch-convert/scripts/hwp_batch_convert.py "C:\docs\contracts" --format PDF --same-location

별도 출력 폴더로 변환:

python skills/hwp-batch-convert/scripts/hwp_batch_convert.py "C:\docs\hwp" --format PDF --output-dir "C:\docs\pdf" --auto-allow-dialogs

여러 파일 한 번에 변환:

python skills/hwp-batch-convert/scripts/hwp_batch_convert.py "C:\docs\a.hwp" "C:\docs\b.hwpx" --format DOCX --output-dir "C:\docs\docx"

실제 변환 없이 계획만 확인:

python skills/hwp-batch-convert/scripts/hwp_batch_convert.py "C:\docs\hwp" --format PDF --output-dir "C:\docs\pdf" --plan-only --json

테스트용 모의 변환:

python skills/hwp-batch-convert/scripts/hwp_batch_convert.py "C:\docs\sample" --format PDF --output-dir "C:\docs\out" --mode mock --json

Main script

scripts/hwp_batch_convert.py

Parameters:

• sources...: 입력 파일/폴더 경로 하나 이상
• --format: 출력 형식 (PDF, HWPX, DOCX, ODT, HTML, RTF, TXT, PNG, JPG, BMP, GIF, HWP)
• --same-location: 원본과 같은 폴더에 출력
• --output-dir: 출력 루트 폴더
• --include-sub: 하위 폴더 포함(기본값)
• --no-include-sub: 하위 폴더 제외
• --overwrite: 같은 이름 출력 허용
• --plan-only: 실제 변환 없이 작업 계획만 생성
• --mode real|mock: 실변환 또는 모의 변환
• --auto-allow-dialogs: 제목 한글, 본문에 접근하려는 시도, 버튼 모두 허용/허용 조건을 모두 만족하는 보안 팝업만 자동 클릭
• --json: stdout JSON 출력
• --report-json: 결과 JSON 파일 저장
• --self-test-dialog-handler: 로컬 테스트용 샘플 한글 창을 띄워 자동 클릭 로직만 검증

Recommended workflow

1. 사용자 요청이 폴더/여러 파일 기반 HWP/HWPX 변환인지 확인한다.
2. 출력 형식이 명시되지 않았으면 보통 PDF를 기본 제안으로 사용한다.
3. 먼저 --plan-only --json 으로 대상/건너뜀/출력 경로를 확인한다.
4. 환경이 Windows + 한글 설치 + pywin32 가능하면 --mode real 로 실행한다.
5. 환경 검증이 먼저 필요하면 --mode mock 으로 경로/출력 구조만 검증한다.
6. 필요하면 --report-json 으로 결과 파일을 남긴다.

Operational notes

• 이 스킬은 사실상 Windows 전용이다.
• 실변환(--mode real)은 한컴 한글 설치와 pywin32가 필요하다.
• --auto-allow-dialogs 는 화이트리스트 방식이다. 제목이 한글 이고, 본문에 접근하려는 시도 가 있으며, 버튼이 모두 허용 또는 허용 인 경우에만 클릭한다.
• 위 조건에 맞지 않는 다른 팝업은 자동으로 건드리지 않는다. 감지되더라도 클릭 없이 이벤트만 남기거나 무시한다.
• 자동 허용 기록은 stdout JSON/--report-json 의 auto_dialog_* 필드와 auto_dialog_events 배열에서 확인한다.
• 한글 COM 자동화가 실패하면 --mode mock 으로 스킬/경로 로직만 먼저 검증하고, 이후 환경 문제를 분리 진단한다.
• 여러 폴더를 동시에 입력하면서 --output-dir 를 쓰면, 파일명 충돌 가능성이 있으니 결과 경로를 확인한다.
• 기본 입력 확장자는 .hwp, .hwpx 만 대상으로 한다.
• 사용자 요청이 DOCX/PDF 일반 문서 처리 중심이고 HWP가 핵심이 아니면 다른 문서 스킬/도구를 우선 고려한다.