HWPX 编辑
HWPX 是 XML 的 Zip 压缩包(HWPML)。造成文件损坏的陷阱从外部并不明显,因此编辑前请阅读 references/hwpx-guide.md 的相关章节,并运行 scripts/ 中的脚本进行重打包和验证——不要手动处理 Zip 或目测正确性。
仅限 HWPX。 此技能仅处理
.hwpx(Zip + XML)。传统.hwp(OLE 二进制,签名D0CF11E0)必须先在韩文软件中通过 다른 이름으로 저장 → HWPX(.hwpx) 进行转换。脚本会检测.hwp并给出提示。
最重要的规则
切勿使用普通 Zip 写入器重新压缩 HWPX 文件。 韩文软件会拒绝未修改条目被重新压缩的文件。请使用保留原始数据的重打包器(scripts/hwpxlib.py:repack_preserve):它会按字节复制未修改的条目,仅重新压缩您更改的部分,因此无操作重打包的结果与源文件字节一致——这意味着“如果原始文件能在韩文中打开,您的编辑版本也能打开。”
工作流程
- 先检查。
python scripts/inspect_hwpx.py FILE.hwpx --breaks—— 查看每节的段落、表格、pic、equation、字段的数量,以及关键点:哪些段落携带有隐藏的pageBreak/columnBreak。如果标题与其内容分离,或页面/列空白,优先处理这些分隔符(§6-A)—— 不要直接使用keepWithNext。正文段落中的分隔符通常是残留垃圾。 - 阅读
references/hwpx-guide.md中的相应指南章节(见下方映射)。XML 的 id/引用(charPrIDRef、paraPrIDRef、borderFillIDRef等)在不同文件中各不相同——始终从实际文件中读取,切勿假定。 - 使用 lxml 编辑 XML,遵循以下不变性:
- 编辑或创建任何段落后,删除其
<hp:linesegarray>(缓存的行布局会过时 → 导致间距错误)。结构编辑后,从整个节中移除 linesegarray,以便韩文完全重新布局。使用hwpxlib.strip_linesegarray。 - 克隆节点(尾注、表格、公式、图像)时,它会继承原始节点的
id/instId→ 重复 → 不稳定。使用hwpxlib.make_uid分配新 id,包括嵌套的subList>p/tbl/tc/p的 id。 - 重用现有的
charPr/paraPr定义,而不是添加新定义;如果必须添加,请更新itemCnt,否则韩文会拒绝文件。
- 编辑或创建任何段落后,删除其
- 使用
hwpxlib.repack_preserve(src, changed, out, added)重打包:changed= 编辑的条目(保持顶部的 XML 声明),added= 新条目,如BinData/imageN.png或新的sectionN.xml(也需在content.hpf中注册)。 - 验证每个构建版本:
python scripts/verify.py EDITED.hwpx --orig ORIG.hwpx。所有严格检查必须通过(字节一致性自检、格式良好的 XML 包括content.hpf、零重复 ID、Zip 完整性 + mimetype 位于第一个且为 STORED)。它还会输出一个最小变更差异,以便您确认只存在预期更改。 - 在韩文中往返测试。 LibreOffice 无法渲染 HWPX,因此依赖渲染的判断(如哪些标题孤行、间距是否正确)需要用户在韩文中打开文件,对于公式和目录,运行 도구→차례 새로 고침 或双击→关闭以完成。请告知用户。
脚本(scripts/)——运行这些,不要重新发明
| 脚本 | 用途 |
|---|---|
hwpxlib.py | 库:repack_preserve、own(真实正文,排除 각주·미주·메모 / 脚注·尾注·备忘录)、make_uid、strip_linesegarray、find_duplicate_ids、structural_counts,以及 §7 验证辅助函数。导入使用。 |
inspect_hwpx.py FILE [--text] [--breaks] | 结构导出;查找隐藏的页/列分隔符。 |
verify.py EDITED [--orig ORIG] | 运行完整的 §7 检查清单;失败时返回非零退出码(可用于 CI 门控)。 |
selftest.py | 证明重打包器在无真实文件情况下无损。 |
tables_to_xlsx.py FILE [OUT] | 将表格导出为 Excel(.xlsx),保留合并单元格(需要 openpyxl)。仅包含图像/公式的单元格 → [그림]/[수식];拒绝旧版 .hwp 并给出指导。 |
脚本需要 lxml(pip install lxml);表格转 Excel 还需要 openpyxl。Python 3.10+。
指南文件(references/hwpx-guide.md)的阅读位置
仅加载所需章节——指南以 “흔한 실패 TOP”(常见失败模式) 开头;先略读,然后跳转到:
- §1 结构与解析 —— 命名空间、
own()、“检查所有节”、按单元格获取表格文本(非批量itertext)。 - §2 重打包(保留原始数据) —— 核心重打包器。与
hwpxlib对应。 - §3 通用规则 ——
linesegarray移除、克隆后的 ID 去重。 - §4 内容编辑 —— 段落、表格(单元格宽度之和必须等于表格宽度,否则韩文拒绝;合并)、图像(
orgSz=像素×75、尺寸计算、按内容而非提取顺序验证、matplotlib 可读性“小图大字”)、格式、尾注/脚注(需要<hp:ctrl>包裹)、备忘录,以及拼写检查范围限定(不使用全局正则)。 - §5 列 · 目录 · 公式 ——
colPr、TABLEOFCONTENTS根据大纲级别段落、한컴公式脚本(非 LaTeX;形式表)。 - §6 页/列管理 —— 优先处理隐藏分隔符、防止标题孤行(
keepWithNext,标题后不留空段落,条件性columnBreak)、清除空白页、宽表格 → 单列区域 + 将secPr块跨节边界移动。 - §7 验证检查清单 ——
verify.py自动化的内容,加上往返测试的注意事项。
安全围栏
- 此技能仅编辑文档;从不获取用户凭据,也不获取或执行远程内容。请在副本上操作并保留原件。
- 保留作者的内容:只更改用户要求的内容;
verify.py中的最小变更差异就是您的证明。