HWP (한글)

OfficeCLI를 통한 HWP/HWPX 한국어 문서 생성, 읽기, 편집

기본 활성화: 예 바이너리 HWP: 실험적

빠른 참조

작업별 명령어 조회 표입니다. 각 행은 해당 작업의 지원 여부와 사용할 명령어를 보여줍니다.

"~해줘" 사용 예시

이 스킬을 트리거하는 자연스러운 한국어 프롬프트입니다. 필요한 것을 설명하기만 하면 됩니다.

편집 에스컬레이션 단계

주요 도구가 작업을 처리할 수 없을 때, 스킬은 4단계를 거쳐 에스컬레이션합니다. 낮은 단계가 우선이며, 높은 단계는 필요한 경우에만 사용됩니다.

에스컬레이션 시그널

• OfficeCLI가 사용자 정의 스타일을 추가할 수 없는 경우 → L2 (raw-set header.xml) + reference/header-xml-guide.md 참조
• 사용자 정의 템플릿 오버레이 → L3 (scripts/build_hwpx.py) + reference/style_id_maps.md 참조
• HWP 바이너리 입력 → 먼저 officecli hwp doctor --json 확인; rhwp 네이티브 준비 시 사용, 아니면 L3
• 다중 파일 패턴 매칭 (시험지, 규정) → L4
• 스타일 ID 조회 → 먼저 reference/style_id_maps.md 참조

핵심 워크플로우

생성 및 가져오기

# 빈 문서
officecli create doc.hwpx

# 마크다운에서 생성 (기본 JUSTIFY 정렬)
officecli create doc.hwpx --from-markdown input.md

# 왼쪽 정렬 마크다운 가져오기
officecli create doc.hwpx --from-markdown input.md --align left

# rhwp 브릿지를 통한 바이너리 HWP
officecli create file.hwp --json

# 데이터로 템플릿 병합
officecli merge template.hwpx out.hwpx --data '{"이름":"홍길동"}'
officecli merge template.hwpx out.hwpx --data data.json

# 템플릿 조합 (구조화된 문서에 권장)
python3 scripts/build_hwpx.py --template gonmun --output gonmun.hwpx

보기 모드

officecli view doc.hwpx text                    # 줄 번호가 있는 텍스트
officecli view doc.hwpx annotated               # 경로 + 스타일 상세
officecli view doc.hwpx outline                 # 제목만
officecli view doc.hwpx stats                   # 문서 통계
officecli view doc.hwpx html --browser          # A4 HTML 미리보기
officecli view doc.hwpx markdown                # GFM 마크다운 내보내기
officecli view doc.hwpx tables                  # 표 2D 그리드 + 레이블 맵
officecli view doc.hwpx forms --auto            # CLICK_HERE + 레이블-값 자동 감지
officecli view doc.hwpx forms --auto --json     # AI 파이프라인용 JSON
officecli view doc.hwpx objects                 # 그림/필드/책갈피/수식 목록
officecli view doc.hwpx objects --object-type field  # 유형별 필터
officecli view doc.hwpx styles                  # charPr/paraPr 스타일
officecli view doc.hwpx issues                  # 9단계 검증 문제

편집 작업

# 텍스트와 글꼴 크기로 문단 추가
officecli add doc.hwpx /section[1] --type paragraph --prop text="content" --prop fontsize=11

# 표 추가
officecli add doc.hwpx /section[1] --type table --prop rows=3 --prop cols=4

# 속성 설정 (굵게, 정렬)
officecli set doc.hwpx '/section[1]/p[1]' --prop bold=true --prop align=CENTER

# 텍스트 찾기 및 바꾸기
officecli set doc.hwpx / --prop find="old" --prop replace="new"

# 요소 제거
officecli remove doc.hwpx /section[1]/p[3]

# 두 요소 교환
officecli swap doc.hwpx '/p[1]' '/p[2]'

레이블 채우기 (표 자동 채우기)

# 레이블로 채우기 (fill: 접두사)
officecli set doc.hwpx / --prop 'fill:대표자=홍길동' --prop 'fill:연락처=010-1234'

# 방향 채우기: right (기본), down, left, up
officecli set doc.hwpx / --prop 'fill:주소>down=서울시'

# 약식 (fill: 접두사 생략 가능, /table/fill 경로 사용 시)
officecli set doc.hwpx /table/fill --prop '이름=김서준'

쿼리 (확장 구문)

officecli query doc.hwpx 'p'                          # 모든 문단
officecli query doc.hwpx 'tc[text~=홍길동]'           # 셀 텍스트 검색
officecli query doc.hwpx 'run[bold=true]'              # 굵은 텍스트 런
officecli query doc.hwpx 'p:has(tbl)'                  # 표를 포함하는 문단
officecli query doc.hwpx 'tbl > tr > tc[colSpan!=1]'   # 병합된 셀
officecli query doc.hwpx 'run[fontsize>=20]'           # 20pt 이상 글꼴
officecli query doc.hwpx 'p[heading=1]'                # 제목 1

연산자: =, !=, ~= (포함), >=, <=
의사 선택자: :empty, :contains(text), :has(child), :first, :last
가상 속성: text, bold, italic, fontsize, colSpan, rowSpan, heading

상주 모드 (실시간 연결)

officecli open doc.hwpx          # 즉시 반환; 데몬이 백그라운드에서 실행
officecli view text               # 다시 열지 않고 보기
officecli set '/p[1]' --prop bold=true
officecli close                   # 세션 닫기

배치 모드

officecli batch doc.hwpx <<'EOF'
view text
view stats
view forms --auto
EOF

비교

officecli compare a.hwpx b.hwpx                    # 텍스트 차이점 (기본)
officecli compare a.hwpx b.hwpx --mode outline      # 제목 차이점
officecli compare a.hwpx b.hwpx --mode table --json  # 표 차이점 JSON

LCS DP 정렬을 사용합니다 (1000만 셀 초과 시 탐욕 알고리즘으로 대체). 표 유사도: 차원 가중치 0.3 + 내용 가중치 0.7. 페이지 범위 필터링: --pages "1-3,5".

이미지 및 워터마크

# 인라인 이미지
officecli add doc.hwpx /section[1] --type picture --prop path=/path/to/image.png

# 페이지 중앙 떠다니는 이미지
officecli add doc.hwpx /section[1] --type picture \
  --prop path=/path/to/image.png \
  --prop anchor=page --prop halign=center --prop valign=middle

# 워터마크 (불투명 RGB PNG 권장)
officecli add doc.hwpx /section[1] --type watermark \
  --prop src=/path/to/watermark.png --prop bright=0 --prop contrast=0

감시 및 HTML 미리보기

officecli watch doc.hwpx           # 파일 변경 시 HTML 자동 새로고침
officecli unwatch doc.hwpx         # 중지
officecli view doc.hwpx html --browser  # 단발성 A4 미리보기

템플릿 조합 시스템

HWP는 고유한 기본 + 오버레이 템플릿 시스템을 사용합니다. 공문/보고서/회의록/제안서의 대부분의 HWPX 생성은 officecli create 빈 문서 대신 이 시스템을 사용해야 합니다.

사용 가능한 템플릿

방법 1: build_hwpx.py (권장)

python3 scripts/build_hwpx.py --template report --output Q4Report.hwpx

# 그런 다음 officecli로 내용 편집
officecli open Q4Report.hwpx
officecli set Q4Report.hwpx /table/fill --prop '제목=2026 Q4 보고'
# ... 계속 편집 ...
officecli close Q4Report.hwpx

방법 2: 수동 오버레이 (커스터마이징용)

# 1. 기본 골격 복사
cp -r templates/base/ work/

# 2. 도메인별 스타일 오버레이
cp -r templates/gonmun/* work/Contents/

# 3. 필요에 따라 header.xml과 section0.xml 편집
#    참조: reference/header-xml-guide.md, reference/section0-xml-guide.md
#    스타일 ID: reference/style_id_maps.md

# 4. HWPX로 재압축 (ZIP + 정리 + 최소화)
python3 scripts/ooxml/pack.py work/ out.hwpx

# 5. 검증
officecli validate out.hwpx

참조 기반 편집

사용자가 "X.hwpx처럼 서식 맞춰줘", "공문 양식처럼", "기존 보고서 스타일", 또는 소스 파일을 제공하는 경우 — 소스에서 시작하되 처음부터 다시 만들지 마세요.

워크플로우

1. 소스 복사: cp source.hwpx target.hwpx — header.xml (스타일), section0.xml (구조), META-INF를 상속합니다
2. 열기: officecli open target.hwpx — 데몬이 즉시 반환합니다 (백그라운드로 실행하지 마세요)
3. 본문 문단만 제거 — header.xml (charPr/paraPr/borderFill), META-INF, settings를 유지합니다
4. 새 내용 추가 — 기존 styleidref 값을 사용하면 자동으로 적용됩니다

템플릿 우선순위

1. 사용자 제공 소스 파일 — 최우선 템플릿
2. tests/fixtures/agentic/*.hwpx — 실제와 유사한 샘플 (공문, 보고서, 표가 있는 회의록)
3. templates/{base,gonmun,minutes,proposal,report}/ — 템플릿 조합 시스템
4. officecli create 빈 문서 — 다른 것이 해당되지 않을 때만 사용

양식 인식 및 채우기

4단계 인식 전략

3단계 채우기 파이프라인

1. 셀 내 패턴: 체크박스 ☐ → ☑, 괄호 빈칸 채우기, 주석 채우기
2. 표 레이블-값: 정확 일치 + 접두사 60% 매칭, 4방향 (right/down/left/up)
3. 인라인 문단: 표 외부의 "label: value"에 대한 정규식 후방 탐색

AI 양식 채우기 워크플로우

# 1단계: 모든 필드 인식
officecli view form.hwpx forms --auto --json > fields.json

# 2단계: AI가 레이블 -> 값 매핑 (사용자 로직)

# 3단계: 매칭된 필드 채우기
officecli set form.hwpx /table/fill --prop '성 명=홍길동'

바이너리 HWP 지원 (실험적)

네이티브 바이너리 .hwp 작업은 rhwp 브릿지로 구동됩니다. 모든 작업은 기능 게이트가 적용되어 있으므로 — 지원을 가정하기 전에 항상 준비 상태를 확인하세요.

검색 명령어

# 항상 먼저 실행
officecli hwp doctor --json       # 런타임 준비 상태 확인
officecli capabilities --json     # 전체 기능 매트릭스
officecli hwp --json              # 현재 레시피 및 정책

지원되는 작업 (준비 시)

# 생성
officecli create file.hwp --json

# 보기 / 내보내기
officecli view file.hwp text --json
officecli view file.hwp svg --page 1 --json
officecli view file.hwp png --page 1 --out /tmp/hwp-png --json
officecli view file.hwp pdf --page 1 --out out.pdf --json
officecli view file.hwp markdown --json
officecli view file.hwp thumbnail --out thumb.png --json
officecli view file.hwp info --json
officecli view file.hwp tables --section 0 --json

# 필드 편집
officecli set file.hwp /field --prop name=회사명 --prop value=리지 --prop output=out.hwp --json

# 텍스트 편집
officecli set file.hwp /text --prop find=마케팅 --prop value=브릿지 --prop output=out.hwp --json

# 텍스트 삽입
officecli add file.hwp /text --type paragraph --prop value=새본문 --prop output=out.hwp --json

# 표 셀 편집
officecli set file.hwp /table/cell --prop section=0 --prop parent-para=3 \
  --prop control=0 --prop cell=0 --prop value=오피스셀 --prop output=out.hwp --json

# 네이티브 작업 (이스케이프 해치)
officecli view file.hwp native --op get-style-list --json
officecli set file.hwp /native-op --prop op=split-paragraph --prop output=out.hwp --json

# HWPX에서 HWP로 내보내기
officecli set input.hwpx /save-as-hwp --prop output=out.hwp --json

수식 처리 (수식)

HWPX 수식은 한컴의 독자적 스크립트 언어를 사용합니다. MathML도, LaTeX도, OMML도 아닙니다.

# 수식 생성
officecli add doc.hwpx /section --type equation --prop 'script=x^2 + y^2 = r^2'

# 모든 수식 보기
officecli view doc.hwpx objects --object-type equation

한국어 문서 디자인 원칙

정부 양식 미감 (한국 공공양식 미감)

• 표가 뼈대입니다: 한국 양식은 표 중심입니다. 모든 레이블-값 쌍이 정밀하게 병합된 셀 그리드에 위치합니다. 그리드 구조를 정확히 유지하세요.
• 제목 계층: 제1조 (조) > 제1항 (항) > 제1호 (호). 개요 수준에는 styleidref를 사용하세요.
• 고정 여백: 정부 양식은 표준 A4 여백을 사용합니다 (상/하 ~15mm, 좌/우 ~20mm). 기존 문서의 여백을 변경하지 마세요.
• 정렬: 본문 텍스트는 기본적으로 JUSTIFY (양쪽 정렬)입니다. 제목은 CENTER일 수 있습니다. 공식 문서에서 본문 텍스트에 LEFT를 사용하지 마세요.

균등분할 감지 (균등분할)

한국 양식에서는 셀 내 이름에 균등 문자 간격을 자주 사용합니다: "홍 길 동" (각 글자 사이에 공백). 이것은 표시 관례이지 데이터가 아닙니다.

• 읽기: 균등 공백을 제거하여 실제 값을 얻습니다 ("홍길동")
• 쓰기: 템플릿 셀이 균등 간격을 사용하는 경우, 이에 맞게 공백을 삽입합니다 (2자: "이 준", 3자: "홍 길 동", 4자: "남궁민수")
• 감지 정규식: ^(\S)\s(\S)\s(\S)$ 등 (1개 공백으로 구분된 단일 문자 그룹)

문서 유형 분류

필수 검증

# 1. 구조 검증 (반드시 통과해야 함)
officecli validate output.hwpx

# 2. PDF 시각 검증 (반드시 확인해야 함)
soffice --headless --convert-to pdf --outdir /tmp output.hwpx
# 확인: 표 위치, 안내 텍스트 제거 여부, 체크박스 정확성,
#         병합 셀 텍스트가 올바른 행에 있는지, 숫자 손상 여부

# 3. 서브에이전트를 통한 시각적 QA (reference/visual_qa_prompt.md 사용)
python3 scripts/contact_sheet.py /tmp/output.pdf sheet.png

# 4. 한컴오피스가 있으면, .hwpx를 직접 열어서도 확인

납품 전 체크리스트

• officecli validate 통과 (오류 0개)
• soffice --headless --convert-to pdf → 시각 확인
• 표 셀이 올바른 위치에 있는지 (cellAddr 매핑)
• 안내 텍스트 (※, 예시) 완전 제거
• 체크박스 ☐/■가 의도된 셀에만 있는지
• 병합 셀 텍스트가 올바른 행에 있는지
• 한컴오피스가 있으면 .hwpx를 직접 열어서 확인

보안

참조 자료 및 스크립트

참조 문서 (reference/)

Python 스크립트 (scripts/)

패턴 매칭 편집 (L4 대체)

officecli set/find-replace로 처리할 수 없는 복잡한 양식 편집 — 수능 시험지, 다중 섹션 규정, 단편화된 텍스트 노드 등에 사용합니다.

핵심 흐름

# HWPX 압축 해제
python3 scripts/hwpx_cli.py open input.hwpx

# work/Contents/의 XML 파일 편집
# (lineseg는 hwpx_cli.py에 의해 자동 제거됨)

# 재압축
python3 scripts/hwpx_cli.py save output.hwpx

주요 패턴

Lineseg 제거 (중요)

HWPX XML을 직접 편집할 때 (officecli나 scripts/hwpx_cli.py를 통하지 않고), 반드시 모든 <hp:linesegarray> 요소를 제거해야 합니다. 오래된 레이아웃 캐시로 인해 문자가 한 줄에 겹쳐 표시됩니다.

import re
xml = re.sub(r'<(?:hp:)?linesegarray[^>]*>.*?</(?:hp:)?linesegarray>', '', xml, flags=re.DOTALL)
xml = re.sub(r'<(?:hp:)?linesegarray[^/]*/>', '', xml)  # self-closing

흔한 실수

안티패턴 (반드시 피해야 함)

1. 수학 시험에 수식이 없으면 출력이 깨집니다 — 수능 문서에는 <hp:equation> 요소가 필요합니다
2. 보호 장치 없는 HWP 바이너리 덮어쓰기 금지 — --prop output=...을 우선 사용; safeInPlace.ready=true일 때만 안전한 제자리 수정 사용
3. rhwp에 네이티브 프리미티브가 있을 때 가짜 HWPX 대체 금지 — OfficeCLI에 해당 경로가 없으면 격차를 보고하고 승인을 위해 중단
4. lineseg 제거 없이 XML 편집 금지 — 오래된 캐시로 텍스트가 겹칩니다
5. 고정 레이아웃 시험에 보이는 QA 마커 금지 — 대신 스크린샷이나 부속 증거를 사용하세요
6. 교차 포맷 스킬 로딩 금지 — 이 스킬은 .hwp/.hwpx 전용입니다
7. 템플릿에 존재하는 스타일 재생성 금지 — 먼저 cp하고 reference/style_id_maps.md를 참조하세요
8. 참조 자료 무시 금지 — header-xml-guide.md, section0-xml-guide.md, style_id_maps.md는 사용자 정의 XML 작업에 필수입니다

의존성

사전 요구 사항 확인

# OfficeCLI (필수)
which officecli >/dev/null 2>&1 || echo "WARN: OfficeCLI not installed"

# LibreOffice (권장, 필요 시 자동 설치)
which soffice >/dev/null 2>&1 || echo "INFO: LibreOffice not installed"

# Python 패키지 (L3/L4에 선택 사항)
python3 -c "import lxml; import pyhwp" 2>/dev/null || echo "OPTIONAL: pip install lxml pyhwp"

# Java (HWP 변환 전용)
echo "JAVA_HOME=$JAVA_HOME"

도구 검색

추측하기 전에 항상 도움말에서 구문을 확인하세요.

officecli --help
officecli hwp --json
officecli hwp doctor --json
officecli capabilities --json
officecli view --help
officecli set --help
python3 scripts/hwpx_cli.py --help
python3 scripts/build_hwpx.py --help

시험 XML 구조 패턴

수능 스타일의 시험지는 고정 레이아웃 제약으로 인해 특별한 처리가 필요합니다.

HWP → HWPX 변환

포맷 감지

file doc.hwpx   # "Zip archive" -> HWPX (ZIP + OWPML XML)
file doc.hwp    # "HWP Document" -> HWP 5.0 바이너리

구조적 차이

변환 파일 편집 전략

1. 제목: 런 인식 교체 — set_run_text(p0, 'old', 'new') (페이지 번호 런 건너뛰기)
2. 본문: 직렬화된 XML에 대한 원시 문자열 교체 — sec0.replace(old, new)
3. 다중 <t> 셀: ReplaceTextInCell() 사용 — 모든 <t>를 연결 → 매칭 → 재분배