Communitygithub.com

kangdacool/hwpx-editing-skill

LLMエージェント(Claude Code・Codexなど)が韓国語.hwpxファイルを壊さず編集できるようにする、検証済みのルール+Pythonツールスキル。

hwpx-editing-skill とは?

このスキルは、Claude CodeやCodexなどのLLMエージェント向けに、韓国語ワープロ形式HWPX(.hwpx)ファイルを安全かつ正確に編集するためのルールセットとPythonスクリプト群を提供します。HWPXファイルはXMLを含むZIPアーカイブであり、適切に扱わないと破損しやすいため、本スキルは専用の圧縮ツール(raw-preserving repacker)を使い、未編集エントリはバイトコピー、編集したエントリのみ再圧縮することで、元のファイルとバイト単位で同一性を保ちます。ワークフローは「最初に構造を調査 → ガイドの該当セクションを参照 → lxmlでXML編集 → repack_preserveで再パッケージ → verify.pyで検証 → 한글で最終確認」という6ステップで構成され、各ステップで破損を防ぐための具体的な不変条件(linesegarray削除、id重複防止、定義再利用など)が徹底されています。CUIツールとしての動作に特化しており、ユーザー認証やリモート通信は不要で、元ファイルを保護するよう設計されています。

対応✓Claude Code✓Codex CLI~Cursor
npx skills add kangdacool/hwpx-editing-skill

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

HWPX 編集

HWPX は XML(HWPML)のZIP です。ファイルを破損させる罠は外からはわかりにくいため、編集前に references/hwpx-guide.md の該当セクションを読み、scripts/ 内のスクリプトを実行して再パッケージ・検証してください — 手作業でZIPを作ったり、目視で正しさを確認したりしないでください。

HWPX 限定。 このスキルは .hwpx(ZIP + XML)のみ扱います。レガシーな .hwp(OLE バイナリ、シグネチャ D0CF11E0)は、まず 한글 で 他の名前で保存 → HWPX(.hwpx) により変換する必要があります。スクリプトは .hwp を検出するとその旨を表示します。

最も重要な唯一のルール

通常のZIPライターでHWPXを再圧縮してはいけません。 한글 は、変更していないエントリが再deflateされたファイルを拒否します。raw-preserving repacker(scripts/hwpxlib.py:repack_preserve)を使用してください:これは変更していない各エントリをバイトコピーし、変更したエントリだけを再deflateするため、何も変更しない再パッケージは元のファイルとバイト単位で同一になります。つまり、「元のファイルが한글で開ければ、あなたの編集後ファイルも開ける」ということです。

ワークフロー

  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検証ヘルパー。import して使用。
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 リパック(raw-preserving) — 王冠の宝石のリパッカー。hwpxlib と対応。
  • §3 共通ルール — linesegarray 削除、クローン後のID重複除去。
  • §4 コンテンツ編集 — 段落、表(セル幅の合計が表幅と一致しないと 한글 が拒否;結合)、画像(orgSz=px×75、サイズ計算、コンテンツで検証(抽出順序ではない)、matplotlibの可読性「小さい図、大きい文字」)、書式、文末脚注・脚注(<hp:ctrl> ラッピング必須)、メモ、および誤植監査の範囲(総当たり正規表現は禁止)。
  • §5 カラム・目次・数式 — colPr、TABLEOFCONTENTS(アウトラインレベル段落から)、한컴 数式スクリプト(LaTeX ではなく;フォーム一覧付き)。
  • §6 ページ/カラム管理 — まず隠れた改行、孤立見出し防止(keepWithNext、見出し後の空段落禁止、条件付き columnBreak)、白紙ページ削除、幅広の表 → 1カラム領域、secPr ブロックのセクション境界を越えた移動。
  • §7 検証チェックリスト — verify.py が自動化する内容と、往復確認の注意点。

ガードレール

  • このスキルはドキュメントの編集のみを行います。ユーザーの認証情報を必要とせず、リモートコンテンツを取得・実行しません。コピーで作業し、オリジナルは保持してください。
  • 作成者のコンテンツを保護:ユーザーが依頼したものだけを変更すること。verify.py の最小変更diffがその証明です。

関連スキル