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 結果會與原始檔案位元組完全一致 — 這意味著「如果原始檔案能在韓文軟體中開啟,你的編輯版本也能開啟。」
工作流程
- 先檢查。
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)。它還會列印一個最小變更 diff,以便你可以確認僅有預期的變更存在。 - 在韓文軟體(한글)中進行來回測試。 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 就是你的證明。