HWP (한글)

通过 OfficeCLI 创建、读取、编辑 HWP/HWPX 韩文文档

默认启用：是 二进制 HWP：实验性

快速参考

完整的任务到命令查询表。每行显示该操作是否受支持以及使用哪个命令。

"~해줌" 使用示例

触发此技能的自然韩语提示。只需描述你需要什么即可。

编辑升级阶梯

当主要工具无法处理任务时，技能会逐级升级，共四个级别。优先使用低级别；仅在必要时才使用高级别。

升级信号

• 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

# 从 Markdown 创建（默认 JUSTIFY 对齐）
officecli create doc.hwpx --from-markdown input.md

# 左对齐 Markdown 导入
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 markdown 导出
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=서울시'

# 简写（/table/fill 路径下 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]'              # 加粗的 run
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]'                # 一级标题

运算符：=、!=、~=（包含）、>=、<=
伪选择器：: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 空白文档 — 仅在没有其他选择时使用

表单识别与填充

四策略识别

三阶段填充流水线

1. 单元格内模式：复选框 ☐ → ☑、括号留空填充、标注填充
2. 表格标签-值：精确匹配 + 前缀 60% 匹配，四方向（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（양쪽 정렬）。标题可能居中。正式文档的正文绝不要使用 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. 如果有韩软 Office，也直接打开 .hwpx 检查

交付前检查清单

• officecli validate 通过（0 个错误）
• soffice --headless --convert-to pdf → 视觉检查
• 表格单元格位置正确（cellAddr 映射）
• 引导文字（※、예시）已完全移除
• 复选框 ☐/■ 仅在预期单元格中
• 合并单元格文本在正确的行
• 如果有韩软 Office，直接打开 .hwpx 检查

安全

参考资料与脚本

参考文档（reference/）

Python 脚本（scripts/）

模式匹配编辑（L4 备选方案）

用于超出 officecli set/find-replace 能力的复杂表单编辑 — KICE 考试、多章节法规、碎片化文本节点。

核心流程

# 解包 HWPX
python3 scripts/hwpx_cli.py open input.hwpx

# 编辑 work/Contents/ 中的 XML 文件
#（hwpx_cli.py 会自动去除 lineseg）

# 重新打包
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. 数学考试中没有公式 = 输出损坏 — KICE 文档必须包含 <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 结构模式

KICE 风格的考试试卷因固定布局限制需要特殊处理。

HWP → HWPX 转换

格式检测

file doc.hwpx   # "Zip archive" -> HWPX（ZIP + OWPML XML）
file doc.hwp    # "HWP Document" -> HWP 5.0 二进制

结构差异

转换文件的编辑策略

1. 标题：run 感知替换 — set_run_text(p0, 'old', 'new')（跳过页码 run）
2. 正文：对序列化 XML 进行原始字符串替换 — sec0.replace(old, new)
3. 多 <t> 单元格：使用 ReplaceTextInCell() — 拼接所有 <t> → 匹配 → 重新分配