HWP (한글)

HWP/HWPX Korean document create, read, edit via OfficeCLI

Default Active: Yes Binary HWP: Experimental

Quick Reference

Complete task-to-command lookup. Each row shows whether the operation is supported and which command to use.

"~해줌" Usage Examples

Natural Korean prompts that trigger this skill. Just describe what you need.

Editing Escalation Ladder

When the primary tool cannot handle the job, the skill escalates through four levels. Lower levels are preferred; higher levels are used only when necessary.

Escalation Signals

• OfficeCLI cannot add custom style → L2 (raw-set header.xml) + read reference/header-xml-guide.md
• Custom template overlay → L3 (scripts/build_hwpx.py) + read reference/style_id_maps.md
• HWP binary input → check officecli hwp doctor --json first; native rhwp when ready, else L3
• Multi-file pattern match (exams, regulations) → L4
• Style ID lookup → read reference/style_id_maps.md first

Core Workflows

Create & Import

# Empty document
officecli create doc.hwpx

# From Markdown (JUSTIFY alignment by default)
officecli create doc.hwpx --from-markdown input.md

# Left-aligned Markdown import
officecli create doc.hwpx --from-markdown input.md --align left

# Binary HWP via rhwp bridge
officecli create file.hwp --json

# Template merge with data
officecli merge template.hwpx out.hwpx --data '{"이름":"홍길동"}'
officecli merge template.hwpx out.hwpx --data data.json

# Template assembly (recommended for structured docs)
python3 scripts/build_hwpx.py --template gonmun --output gonmun.hwpx

View Modes

officecli view doc.hwpx text                    # line-numbered text
officecli view doc.hwpx annotated               # path + style detail
officecli view doc.hwpx outline                 # headings only
officecli view doc.hwpx stats                   # document statistics
officecli view doc.hwpx html --browser          # A4 HTML preview
officecli view doc.hwpx markdown                # GFM markdown export
officecli view doc.hwpx tables                  # table 2D grid + label map
officecli view doc.hwpx forms --auto            # CLICK_HERE + label-value auto-detect
officecli view doc.hwpx forms --auto --json     # JSON for AI pipeline
officecli view doc.hwpx objects                 # picture/field/bookmark/equation list
officecli view doc.hwpx objects --object-type field  # filter by type
officecli view doc.hwpx styles                  # charPr/paraPr styles
officecli view doc.hwpx issues                  # 9-level validation issues

Edit Operations

# Add paragraph with text and font size
officecli add doc.hwpx /section[1] --type paragraph --prop text="content" --prop fontsize=11

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

# Set properties (bold, alignment)
officecli set doc.hwpx '/section[1]/p[1]' --prop bold=true --prop align=CENTER

# Find and replace text
officecli set doc.hwpx / --prop find="old" --prop replace="new"

# Remove element
officecli remove doc.hwpx /section[1]/p[3]

# Swap two elements
officecli swap doc.hwpx '/p[1]' '/p[2]'

Label Fill (Table Auto-Fill)

# Fill by label (fill: prefix)
officecli set doc.hwpx / --prop 'fill:대표자=홍길동' --prop 'fill:연락처=010-1234'

# Directional fill: right (default), down, left, up
officecli set doc.hwpx / --prop 'fill:주소>down=서울시'

# Shorthand (fill: prefix optional with /table/fill path)
officecli set doc.hwpx /table/fill --prop '이름=김서준'

Query (Extended Syntax)

officecli query doc.hwpx 'p'                          # all paragraphs
officecli query doc.hwpx 'tc[text~=홍길동]'           # cell text search
officecli query doc.hwpx 'run[bold=true]'              # bold runs
officecli query doc.hwpx 'p:has(tbl)'                  # paragraphs containing tables
officecli query doc.hwpx 'tbl > tr > tc[colSpan!=1]'   # merged cells
officecli query doc.hwpx 'run[fontsize>=20]'           # 20pt+ font
officecli query doc.hwpx 'p[heading=1]'                # heading 1

Operators: =, !=, ~= (contains), >=, <=
Pseudo-selectors: :empty, :contains(text), :has(child), :first, :last
Virtual attributes: text, bold, italic, fontsize, colSpan, rowSpan, heading

Resident Mode (Live Connection)

officecli open doc.hwpx          # returns IMMEDIATELY; daemon in bg
officecli view text               # view without re-opening
officecli set '/p[1]' --prop bold=true
officecli close                   # close session

Batch Mode

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

Compare

officecli compare a.hwpx b.hwpx                    # text diff (default)
officecli compare a.hwpx b.hwpx --mode outline      # heading diff
officecli compare a.hwpx b.hwpx --mode table --json  # table diff JSON

Uses LCS DP alignment (fallback greedy for >10M cells). Table similarity: dimension weight 0.3 + content weight 0.7. Page range filtering: --pages "1-3,5".

Image & Watermark

# Inline image
officecli add doc.hwpx /section[1] --type picture --prop path=/path/to/image.png

# Page-centered floating image
officecli add doc.hwpx /section[1] --type picture \
  --prop path=/path/to/image.png \
  --prop anchor=page --prop halign=center --prop valign=middle

# Watermark (opaque RGB PNG recommended)
officecli add doc.hwpx /section[1] --type watermark \
  --prop src=/path/to/watermark.png --prop bright=0 --prop contrast=0

Watch & HTML Preview

officecli watch doc.hwpx           # auto-refresh HTML on file change
officecli unwatch doc.hwpx         # stop
officecli view doc.hwpx html --browser  # one-shot A4 preview

Template Assembly System

HWP uses a unique base + overlay template system. Most HWPX creation for 공문/보고서/회의록/제안서 should use this instead of officecli create blank.

Available Templates

Method 1: build_hwpx.py (Recommended)

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

# Then edit content with officecli
officecli open Q4Report.hwpx
officecli set Q4Report.hwpx /table/fill --prop '제목=2026 Q4 보고'
# ... continue editing ...
officecli close Q4Report.hwpx

Method 2: Manual Overlay (for Customization)

# 1. Copy base skeleton
cp -r templates/base/ work/

# 2. Overlay domain-specific styles
cp -r templates/gonmun/* work/Contents/

# 3. Edit header.xml and section0.xml as needed
#    Reference: reference/header-xml-guide.md, reference/section0-xml-guide.md
#    Style IDs: reference/style_id_maps.md

# 4. Repack as HWPX (ZIP with strip + minify)
python3 scripts/ooxml/pack.py work/ out.hwpx

# 5. Validate
officecli validate out.hwpx

Reference-Based Editing

When the user says "format like X.hwpx", "공문 양식처럼", "기존 보고서 스타일", or provides a source file — start from the source, do not rebuild from scratch.

Workflow

1. Copy the source: cp source.hwpx target.hwpx — inherits header.xml (styles), section0.xml (structure), META-INF
2. Open: officecli open target.hwpx — daemon returns immediately (do NOT run as background)
3. Remove body paragraphs only — keep header.xml (charPr/paraPr/borderFill), META-INF, settings
4. Add new content using existing styleidref values — they auto-apply

Template Priority

1. User-provided source file — first-class template
2. tests/fixtures/agentic/*.hwpx — realistic samples (gonmun, report, minutes with tables)
3. templates/{base,gonmun,minutes,proposal,report}/ — Template Assembly system
4. officecli create blank — only when nothing else applies

Form Recognition & Fill

4-Strategy Recognition

3-Phase Fill Pipeline

1. In-cell patterns: checkbox ☐ → ☑, paren-blank fill, annotation fill
2. Table label-value: exact + prefix 60% matching, 4-directional (right/down/left/up)
3. Inline paragraph: regex lookbehind for "label: value" outside tables

AI Form Fill Workflow

# Step 1: Recognize all fields
officecli view form.hwpx forms --auto --json > fields.json

# Step 2: AI maps label -> value (your logic here)

# Step 3: Fill matched fields
officecli set form.hwpx /table/fill --prop '성 명=홍길동'

Binary HWP Support (Experimental)

Native binary .hwp operations are powered by the rhwp bridge. All operations are capability-gated — always check readiness before assuming support.

Discovery Commands

# Always run these first
officecli hwp doctor --json       # runtime readiness check
officecli capabilities --json     # full capability matrix
officecli hwp --json              # current recipes and policies

Supported Operations (When Ready)

# Create
officecli create file.hwp --json

# View / Export
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

# Edit fields
officecli set file.hwp /field --prop name=회사명 --prop value=리지 --prop output=out.hwp --json

# Edit text
officecli set file.hwp /text --prop find=마케팅 --prop value=브릿지 --prop output=out.hwp --json

# Insert text
officecli add file.hwp /text --type paragraph --prop value=새본문 --prop output=out.hwp --json

# Edit table cell
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

# Native operations (escape hatch)
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 to HWP export
officecli set input.hwpx /save-as-hwp --prop output=out.hwp --json

Equation Handling (수식)

HWPX equations use Hancom's proprietary script language. This is NOT MathML, NOT LaTeX, NOT OMML.

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

# View all equations
officecli view doc.hwpx objects --object-type equation

Korean Document Design Principles

Government Form Aesthetics (한국 공공양식 미감)

• Tables are the backbone: Korean forms are table-driven. Every label-value pair lives in a precisely merged cell grid. Preserve the grid structure exactly.
• Heading hierarchy: 제1조 (Articles) > 제1항 (Clauses) > 제1호 (Items). Use styleidref for outline levels.
• Fixed margins: Government forms use standard A4 margins (top/bottom ~15mm, left/right ~20mm). Do not alter margins on existing documents.
• Alignment: Body text is JUSTIFY (양쪽 정렬) by default. Headings may be CENTER. Never use LEFT for body text in formal documents.

Uniform Spacing Detection (균등분할)

Korean forms often use uniform character spacing for names in cells: "홍 길 동" (spaces between each character). This is a display convention, not data.

• Reading: strip uniform spaces to get the actual value ("홍길동")
• Writing: if the template cell uses uniform spacing, insert spaces to match (2-char: "이 준", 3-char: "홍 길 동", 4-char: "남궁민수")
• Detection regex: ^(\S)\s(\S)\s(\S)$ etc. (single-char groups separated by 1 space)

Document Type Classification

Mandatory Verification

# 1. Structural validation (MUST pass)
officecli validate output.hwpx

# 2. PDF visual verification (MUST check)
soffice --headless --convert-to pdf --outdir /tmp output.hwpx
# Verify: table positions, guide text removed, checkboxes correct,
#         merged cell text in correct row, numbers not corrupted

# 3. Visual QA via subagent (use reference/visual_qa_prompt.md)
python3 scripts/contact_sheet.py /tmp/output.pdf sheet.png

# 4. If Hancom Office available, also open .hwpx directly

Pre-Delivery Checklist

• officecli validate passes (0 errors)
• soffice --headless --convert-to pdf → visual check
• Table cells in correct positions (cellAddr mapping)
• Guide text (※, 예시) fully removed
• Checkboxes ☐/■ in intended cells only
• Merged cell text in correct row
• If Hancom available, open .hwpx directly

Security

Reference Materials & Scripts

Reference Documents (reference/)

Python Scripts (scripts/)

Pattern-Match Editing (L4 Fallback)

For complex form editing beyond officecli set/find-replace — KICE exams, multi-section regulations, fragmented text nodes.

Core Flow

# Unpack HWPX
python3 scripts/hwpx_cli.py open input.hwpx

# Edit XML files in work/Contents/
# (lineseg is stripped automatically by hwpx_cli.py)

# Repack
python3 scripts/hwpx_cli.py save output.hwpx

Key Patterns

Lineseg Strip (Critical)

When editing HWPX XML directly (NOT via officecli or scripts/hwpx_cli.py), you MUST strip ALL <hp:linesegarray> elements. Stale layout cache causes characters to overlap into a single line.

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

Common Pitfalls

Anti-Patterns (Must Avoid)

1. No equations in math exams = broken output — KICE docs require <hp:equation> elements
2. No unguarded HWP binary overwrite — prefer --prop output=...; only use safe in-place when safeInPlace.ready=true
3. No fake HWPX fallback when rhwp has a native primitive — if OfficeCLI lacks the route, report the gap and stop for approval
4. No XML editing without lineseg strip — stale cache causes overlapping text
5. No visible QA markers in fixed-layout exams — use screenshots or sidecar evidence instead
6. No cross-format skill loading — this skill is .hwp/.hwpx only
7. No rebuilding styles that exist in template — cp first and read reference/style_id_maps.md
8. No ignoring reference materials — header-xml-guide.md, section0-xml-guide.md, and style_id_maps.md are mandatory for custom XML work

Dependencies

Prerequisite Check

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

# LibreOffice (recommended, auto-installs when needed)
which soffice >/dev/null 2>&1 || echo "INFO: LibreOffice not installed"

# Python packages (optional for L3/L4)
python3 -c "import lxml; import pyhwp" 2>/dev/null || echo "OPTIONAL: pip install lxml pyhwp"

# Java (for HWP conversion only)
echo "JAVA_HOME=$JAVA_HOME"

Tool Discovery

Always confirm syntax from help before guessing.

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

Exam XML Structure Patterns

KICE-style exam sheets require special handling due to fixed-layout constraints.

HWP → HWPX Conversion

Format Detection

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

Structural Differences

Editing Strategies for Converted Files

1. Title: run-aware replacement — set_run_text(p0, 'old', 'new') (skip page-number runs)
2. Body: raw string replace on serialized XML — sec0.replace(old, new)
3. Multi-<t> cells: use ReplaceTextInCell() — concatenate all <t> → match → redistribute