Communitygithub.com

kangdacool/hwpx-editing-skill

一個可攜式 AI 代理技能,讓 Claude Code、Codex 等 LLM 代理能夠在不破壞文件的情況下編輯韓文 .hwpx 檔案。

hwpx-editing-skill 是什麼?

此技能專為 LLM 代理(如 Claude Code、Codex)設計,使其能安全編輯韓文 HWPX(.hwpx)檔案。HWPX 本質上是 XML 的 zip 壓縮包,直接使用一般壓縮工具處理極易造成檔案損毀。該技能透過提供一套經過驗證的規則與 Python 腳本,強制代理遵循正確的工作流程:先檢查檔案結構、閱讀對應的指南章節、使用 lxml 進行編輯,最後透過保留原始壓縮方式的 repack 工具進行打包。核心規則是絕不使用一般的 zip 寫入器重新壓縮,以避免韓文軟體(한글)拒絕開啟。主要支援所有能執行 Python 腳本的 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。 韓文軟體(한글)會拒絕開啟那些未修改項目被重新 deflate 的檔案。請使用保留原始壓縮方式的 repack 工具(scripts/hwpxlib.py:repack_preserve):它會逐位元組複製你未觸及的項目,並僅對你修改過的項目進行重新 deflate,因此無操作的 repack 結果會與原始檔案位元組完全一致 — 這意味著「如果原始檔案能在韓文軟體中開啟,你的編輯版本也能開啟。」

工作流程

  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)。它還會列印一個最小變更 diff,以便你可以確認僅有預期的變更存在。
  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證明 repack 工具在沒有實際檔案的情況下是無損的。
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 重新打包(保留原始壓縮方式) — 核心 repack 工具。與 hwpxlib 對應。
  • §3 通用規則 — 移除 linesegarray、克隆後去重 ID。
  • §4 內容編輯 — 段落、表格(儲存格寬度總和必須等於表格寬度,否則韓文軟體會拒絕;合併)、圖片(orgSz=px×75、尺寸計算、按內容而非提取順序驗證、matplotlib 可讀性「小圖、大字」)、格式設定、章節附註/腳註(需要 <hp:ctrl> 包裝)、備註,以及錯字審查範圍(不進行全域正則表達式)。
  • §5 欄 · 目錄 · 方程式 — colPr、TABLEOFCONTENTS(來自大綱層級段落)、한컴 方程式腳本(非 LaTeX;形式表)。
  • §6 頁/欄管理 — 優先處理隱藏斷行、防止標題孤兒(keepWithNext,標題後不留空段落,條件式 columnBreak)、清理空白頁、寬表格 → 單欄區域 + 跨區段邊界移動 secPr 區塊。
  • §7 驗證檢查清單 — verify.py 自動化的內容,以及來回測試的注意事項。

護欄

  • 此技能僅編輯文件;絕不需要使用者的憑證,也不會擷取或執行遠端內容。請在副本上作業並保留原始檔案。
  • 保留作者的內容:只更改使用者要求的內容;verify.py 中的最小變更 diff 就是你的證明。

相關技能