Communitygithub.com

kangdacool/hwpx-editing-skill

LLM 代理(如 Claude Code、Codex 等)可用的已验证规则与 Python 工具,用于无损编辑韩文 .hwpx 文件。

hwpx-editing-skill 是什么?

该技能提供了一套经过验证的规则和 Python 脚本,使 Claude Code、Codex 等 LLM 代理能够安全编辑韩文 HWPX(.hwpx)文件。HWPX 是基于 Zip 的 XML(HWPML)格式,直接编辑易导致文件损坏,因此该技能强制要求使用专用重打包器(`hwpxlib.py`)来保留未修改条目的字节不变,仅重新压缩变更部分,从而实现零操作与源文件字节一致,确保编辑后的文件在韩文软件中正常打开。技能内置了从检查、编辑、重打包到验证的完整工作流:使用 `inspect_hwpx.py` 分析文档结构,遵循 `references/hwpx-guide.md` 中的指南编辑 XML,利用 `hwpxlib` 库处理 ID 去重、`linesegarray` 移除等关键不变性,并用 `verify.py` 执行全面的自检(包括字节一致性、XML 格式、重复 ID、Zip 完整性)。同时,该技能明确不处理旧版 .hwp(OLE 二进制),需先在韩文中转换。它适用于任何支持规则文件和脚本执行的 LLM 编码代理,是处理韩文办公文档自动化的强大工具。

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add kangdacool/hwpx-editing-skill

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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):它会按字节复制未修改的条目,仅重新压缩您更改的部分,因此无操作重打包的结果与源文件字节一致——这意味着“如果原始文件能在韩文中打开,您的编辑版本也能打开。”

工作流程

  1. 先检查。 python scripts/inspect_hwpx.py FILE.hwpx --breaks —— 查看每节的段落、表格、pic、equation、字段的数量,以及关键点:哪些段落携带有隐藏的 pageBreak/columnBreak。如果标题与其内容分离,或页面/列空白,优先处理这些分隔符(§6-A)—— 不要直接使用 keepWithNext。正文段落中的分隔符通常是残留垃圾。
  2. 阅读 references/hwpx-guide.md 中的相应指南章节(见下方映射)。XML 的 id/引用(charPrIDRef、paraPrIDRef、borderFillIDRef 等)在不同文件中各不相同——始终从实际文件中读取,切勿假定。
  3. 使用 lxml 编辑 XML,遵循以下不变性:
    • 编辑或创建任何段落后,删除其 <hp:linesegarray>(缓存的行布局会过时 → 导致间距错误)。结构编辑后,从整个节中移除 linesegarray,以便韩文完全重新布局。使用 hwpxlib.strip_linesegarray。
    • 克隆节点(尾注、表格、公式、图像)时,它会继承原始节点的 id/instId → 重复 → 不稳定。使用 hwpxlib.make_uid 分配新 id,包括嵌套的 subList>p / tbl/tc/p 的 id。
    • 重用现有的 charPr/paraPr 定义,而不是添加新定义;如果必须添加,请更新 itemCnt,否则韩文会拒绝文件。
  4. 使用 hwpxlib.repack_preserve(src, changed, out, added) 重打包:changed = 编辑的条目(保持顶部的 XML 声明),added = 新条目,如 BinData/imageN.png 或新的 sectionN.xml(也需在 content.hpf 中注册)。
  5. 验证每个构建版本:python scripts/verify.py EDITED.hwpx --orig ORIG.hwpx。所有严格检查必须通过(字节一致性自检、格式良好的 XML 包括 content.hpf、零重复 ID、Zip 完整性 + mimetype 位于第一个且为 STORED)。它还会输出一个最小变更差异,以便您确认只存在预期更改。
  6. 在韩文中往返测试。 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 中的最小变更差异就是您的证明。

相关技能