rhwp-advanced

このスキルの役割

アップストリームの rhwp CLI(Rust ネイティブバイナリ)を使用して、HWP ファイルの レイアウトデバッグ・IR 構造検査・バージョン比較・サムネイル抽出・配布用ドキュメントのロック解除 を実行します。 k-skill-rhwp(Node 編集 CLI)では対応できない構造分析・レンダリング問題の診断に使用します。

このスキルは 編集を行いません。編集は rhwp-edit スキル、ドキュメント → Markdown/JSON 変換は hwp スキル(kordoc)を使用してください。

使用場面

• 「表/セルが変に切れている。どこで壊れているのか IR ダンプを見たい」
• 「2 つの HWP ファイルの構造差分を行単位で見たい」
• 「SVG レンダリングがおかしい。段落/表の境界線を視覚的に確認したい」
• 「ページ数が何ページあり、どの段落が何ページにまたがっているか見たい」
• 「配布用(読み取り専用) HWP ファイルのロックを解除したい」
• 「HWP ファイルから PrvImage サムネイルを抽出したい」

使用しないケース

• テキスト/表の編集 → rhwp-edit スキル(k-skill-rhwp CLI)
• HWP → Markdown/JSON/フォームフィールド変換 → hwp スキル(kordoc)
• GUI 自動化、한컴セキュリティモジュール回避、Windows レジストリ制御 → スコープ外です。
• Node コードでライブラリ API による編集 → k-skill-rhwp を Node API として使用してください。

前提条件

• rhwp CLI バイナリ。以下のいずれか:
  • cargo install rhwp (Rust ツールチェーン必要。Rust 1.75+。ネイティブビルドなので PDF export を含むすべてのサブコマンドが使用可能)
  • またはアップストリームのリリースページ https://github.com/edwardkim/rhwp/releases からプラットフォーム別の事前ビルドバイナリをダウンロード(利用可能なプラットフォームのみ)
• PATH に rhwp 実行ファイルがあるか、rhwp --help で事前に確認してください。
• 出力ファイルの書き込み権限。
• オプション: PDF export を使用する場合は、アップストリームドキュメントで該当するサブコマンドの追加要件を確認してください。

入力

• 入力 HWP/HWPX ファイルパス
• サブコマンド別の座標(領域/段落インデックス)またはページ番号
• 出力パス(一部のサブコマンド)

ルーティングポリシー

目的	サブコマンド	典型例
基本メタ(ページ/フォント/セクション統計)	rhwp info	rhwp info sample.hwp
ページを SVG にレンダリング	rhwp export-svg	rhwp export-svg sample.hwp -o out/ -p 0 --debug-overlay
ページを PDF にレンダリング(ネイティブビルドのみ)	rhwp export-pdf	rhwp export-pdf sample.hwp -o out.pdf
ドキュメント IR 構造をダンプ	rhwp dump	rhwp dump sample.hwp -s 0 -p 3
ページネーション結果をダンプ	rhwp dump-pages	rhwp dump-pages sample.hwp -p 2
原始レコードをダンプ	rhwp dump-records	rhwp dump-records sample.hwp
番号/箇条書き/アウトラインの診断	rhwp diag	rhwp diag sample.hwp
2 つのファイルの IR を比較	rhwp ir-diff	rhwp ir-diff a.hwpx b.hwp
PrvImage サムネイルを抽出	rhwp thumbnail	rhwp thumbnail sample.hwp -o thumb.png
配布用(読み取り専用) → 編集可能に変換	rhwp convert	rhwp convert locked.hwp unlocked.hwp
空のテーブルを含むドキュメントテンプレートを生成	rhwp gen-table	rhwp gen-table out.hwp

rhwp v0.7.3 CLI には 編集(edit/insert-text/save)サブコマンドがありません。 編集は rhwp-edit スキル(k-skill-rhwp CLI)を使用してください。

ワークフロー

1. インストール確認: rhwp --help を実行。サブコマンドリストが表示されない場合はインストールから実行してください。

   command -v rhwp || cargo install rhwp
   rhwp --help | head
   

2. メタ情報を確認して座標範囲を把握: まず rhwp info でページ数、セクション数、使用フォント、表/画像統計を取得します。

   rhwp info sample.hwp
   

3. 目的別フロー:

   • SVG レンダリングがおかしいとき — デバッグオーバーレイ付きの SVG を出力します。

     mkdir -p out
     rhwp export-svg sample.hwp -o out/ -p 0 --debug-overlay
     open out/page-0.svg    # 段落/表の境界線と `s{sec}:pi={idx} y={y}` ラベルが可視化されます
     

   • 特定ページのレイアウトをより詳しく確認したいとき — ページネーションダンプを使用します。

     rhwp dump-pages sample.hwp -p 2
     

   • 表が壊れているように見えるとき — IR ダンプでセル構造・ParaShape・LINE_SEG を確認します。

     rhwp dump sample.hwp -s 0 -p 3
     

   • 2 つのバージョンを比較 — IR diff で構造変更のみを抽出します。

     rhwp ir-diff draft-v1.hwp draft-v2.hwp > ir-diff.txt
     

   • サムネイルを抽出:

     rhwp thumbnail sample.hwp -o cover.png
     # またはデータ URI が必要な場合: --data-uri
     

   • 配布用(読み取り専用)ドキュメントのロックを解除:

     rhwp convert locked.hwp unlocked.hwp
     # その後の編集は rhwp-edit スキルの k-skill-rhwp CLI で実行
     

4. 結果を PR/レポートに添付するとき: SVG/PDF/サムネイルはファイル自体を添付し、ダンプ出力が長すぎる場合は上位 200～500 行のみを引用し、全体はファイルで添付してください。個人情報を含むドキュメントの本文テキストはマスキングしてください。

出力の検証

• export-svg: 指定した -o パスに page-N.svg ファイルが生成され、開いたときにテキスト/図形が表示され、--debug-overlay 使用時に赤/青のガイドラインが表示されます。
• dump / dump-pages / dump-records: stdout に JSON/テキスト構造が最低でも数十行以上出力されます。
• ir-diff: 2 つのファイルが構造的に同じ場合はほぼ空で、異なる場合は行単位の delta が表示されます。
• thumbnail: 指定した出力パスの PNG が実際の画像ビューアで開きます。
• convert: 出力ファイルを再度 rhwp info で開いたとき、読み取り専用フラグが消えています。

完了条件

• デバッグ/検査目的の場合: ユーザーが求めた構造/レンダリング情報が出力され、どのサブコマンド、どのフラグで出力したかが明示されています。
• convert のようなワンショット変換の場合: 出力ファイルが生成され、rhwp info で再確認可能です。

障害モード

• rhwp: command not found → cargo install rhwp またはリリースバイナリをインストールしてください。
• export-pdf が失敗 → PDF はネイティブビルドでのみ保証されます。@rhwp/core WASM パスでは不可能です。ネイティブ cargo install バイナリで実行中であることを確認してください。
• HWPX 保存パスが無効(rhwp #196) → rhwp CLI 自体が HWPX を再度 HWPX にエクスポートすることがないようにブロックされています。保存が必要な作業は HWP 5.x でのみ実行してください。
• 編集サブコマンドの不在 → v0.7.3 基準で rhwp CLI は編集コマンドを提供していません。編集は rhwp-edit スキルで実行してください。
• Windows セキュリティモジュール/한컴 GUI 自動化 → このスキルのスコープ外です。rhwp はファイルフォーマットエンジンです。
• バージョンドリフト → rhwp は活発に開発中です。サブコマンドフラグが変更または追加される可能性があるため、まず rhwp <subcommand> --help を確認してください。

注釈

• アップストリーム: https://github.com/edwardkim/rhwp
• 編集パス(このリポジトリ): rhwp-edit
• クエリ/変換パス(このリポジトリ): hwp
• このスキルは インストールガイド + 実行レシピ に近いガイダンススキルです。プログラム的な制御が必要な場合は rhwp-edit の Node API(k-skill-rhwp)を使用し、ここでは高速デバッグ用途でのみ使用してください。