HWP

このスキルの機能

kordoc で .hwp / .hwpx / .hwpml ドキュメントを AI が読みやすい Markdown または JSON に変換し、 必要に応じてドキュメント比較、フォームフィールド抽出、Markdown→HWPX 逆変換を実行します。

このスキルの基本エンジンは常に kordoc です。ドキュメント変換、比較、フィールド抽出、逆変換まで同じツールで一貫して処理します。

スキルルーティング — この hwp スキルは参照・変換（読み取り専用） 専用です。 HWP バイナリ編集（本文テキスト挿入・削除、表作成、セル編集、置換）は rhwp-edit スキルが、 レイアウトデバッグ・IR ダンプ・サムネイル・デプロイ用ドキュメントロック解除などの高度な検査は rhwp-advanced スキルが担当します。

使用する場合

• 「このHWPファイルをMarkdownに変換してほしい」
• 「公式文書をJSON構造で抽出してAIに読ませてほしい」
• 「2つのバージョンのドキュメント差分を見たい」
• 「申請書HWPX内のフォームフィールドを抽出してほしい」
• 「AIが作成したMarkdownを再度HWPXで保存してほしい」
• 「フォルダ内のドキュメントを一括変換してほしい」

使用しない場合

• OCR が必須だが OCR プロバイダー接続がなく、イメージベースの PDF のみある場合
• .docx、.xlsx、.pdf のみを扱う場合で、ドキュメント解析自体ではなくエディター GUI 自動化が必要な場合
• 元のプログラムのリアルタイム UI 制御が必須の場合
• 本文テキスト直接挿入・削除・置換または表構造変更 — rhwp-edit スキルの k-skill-rhwp CLI を使用します
• ページ SVG レンダリングデバッグ・IR ダンプ・ir-diff・サムネイル抽出 — rhwp-advanced スキルのアップストリーム rhwp CLI を使用します

前提条件

• Node.js 18+
• 出力パスへの書き込み権限
• kordoc と pdfjs-dist を同じグローバル・ローカル環境にインストール済み、または両方を含む npx --yes --package kordoc --package pdfjs-dist kordoc ... 実行環境
• 現在配布されている kordoc CLI は起動時に pdfjs-dist を直ちにロードするため、PDF を使用しなくても一緒にインストールする必要があります

入力

• 元の .hwp、.hwpx、.hwpml ファイルパスまたはフォルダ・グロブパス
• 希望する結果形式：markdown、json、hwpx
• 出力ファイル・ディレクトリパス
• ページ範囲指定の有無
• 比較・フォームフィールド抽出・逆変換の有無

ルーティングポリシー

デフォルト：kordoc

以下のタスクはすべてデフォルトで kordoc で処理されます。

• HWP/HWPX/HWPML → Markdown
• HWP/HWPX/HWPML → JSON（blocks、metadata）
• バッチ変換
• ページ範囲解析
• 画像・表・フォームを含む公式文書構造抽出
• ディレクトリ監視変換（watch）
• Markdown→HWPX 逆変換
• HWPX フォームフィールド抽出

オプションライブラリパス

CLI だけでは不十分な場合は Node API を使用します。

• parse() — Markdown + 構造化ブロック
• compare() — 旧新ドキュメント比較
• extractFormFields() — 解析されたブロックからフォームフィールド抽出
• markdownToHwpx() — Markdown→HWPX 逆変換

ワークフロー

1. CLI ランタイムの準備

1 回限りの変換であれば、両方を含む npx 形式をそのまま使用します。

npx --yes --package kordoc --package pdfjs-dist kordoc --help

繰り返し実行用のグローバルインストールが必要な場合：

npm install -g kordoc pdfjs-dist

現在配布されている kordoc CLI は pdfjs-dist がないと kordoc --help の段階から失敗するため、 クリーンな環境では 2 つのパッケージをまとめてインストールしてから実行します。

2. Node API サンプル用のローカルプロジェクトの準備

parse()、compare()、extractFormFields()、markdownToHwpx() などの ESM サンプルは グローバル NODE_PATH ではなくローカルプロジェクトインストール基準で実行します。

mkdir -p ./kordoc-local && cd ./kordoc-local
npm init -y
npm install kordoc pdfjs-dist

既に package.json があるワークディレクトリの場合は、npm install kordoc pdfjs-dist を追加実行するだけです。

3. ドキュメントを Markdown に変換

npx --yes --package kordoc --package pdfjs-dist kordoc 報告書.hwp -o 報告書.md

複数のドキュメントを一度に処理する場合：

npx --yes --package kordoc --package pdfjs-dist kordoc ./ドキュメント/* -d ./変換結果

特定ページ範囲のみ読み込む場合：

npx --yes --package kordoc --package pdfjs-dist kordoc 報告書.hwp --pages 1-3

4. AI・自動化用の構造化 JSON を抽出

npx --yes --package kordoc --package pdfjs-dist kordoc 審査書.hwpx --format json > 審査書.json

JSON 結果では success、markdown、blocks、metadata を優先確認します。 表や画像が重要な場合は、blocks 内の table、image タイプを確認します。

5. 解析されたブロックから HWPX フォームフィールドを検査

node --input-type=module - <<'EOF'
import { parse, extractFormFields } from "kordoc";

const result = await parse("申請書.hwpx");
if (!result.success) {
  console.error(result.error);
  process.exit(1);
}

const fields = extractFormFields(result.blocks);
console.log(JSON.stringify(fields, null, 2));
EOF

自動変換が継続的に入ってくるフォルダの場合は、CLI の watch コマンドを使用します。

npx --yes --package kordoc --package pdfjs-dist kordoc watch ./ドキュメント

6. Markdown を HWPX に逆変換

node --input-type=module - <<'EOF'
import { markdownToHwpx } from "kordoc";
import { writeFileSync } from "node:fs";

const hwpx = await markdownToHwpx("# タイトル\n\n本文\n\n| 項目 | 値 |\n| --- | --- |\n| 氏名 | 太郎 |");
writeFileSync("出力.hwpx", Buffer.from(hwpx));
EOF

7. 差分が重要な場合、2 つのドキュメントバージョンを比較

node --input-type=module - <<'EOF'
import { compare } from "kordoc";
import { readFileSync } from "node:fs";

const before = readFileSync("旧バージョン.hwp");
const after = readFileSync("最新バージョン.hwpx");
const diff = await compare(before, after);
console.log(diff.stats);
EOF

実行後の出力を検証

• Markdown：ファイルが生成され、見出し・本文・表構造が壊れていないか確認
• JSON：success: true と blocks / metadata の存在確認
• バッチ処理：入力数と出力数が大きくずれていないか確認
• フォームフィールド抽出：extractFormFields(result.blocks) の結果が空でないか確認
• 逆変換：生成された .hwpx ファイルが開き、基本書式・テーブル構造が維持されているか確認
• 比較：diff.stats の added / removed / modified 値が合理的か確認

完了条件

• 要求された Markdown / JSON / HWPX 成果物が生成されている
• 公式文書の表・画像・メタデータが必要なレベルで確認されている
• フォームフィールド抽出または逆変換要求があった場合は、結果・出力構造まで検証されている
• バッチ要求の場合は、処理範囲と失敗件数が整理されている

障害パターン

• 破損した HWP / HWPX / HWPML ファイル
• 暗号化・配布制限ドキュメントで一部解析の制限が発生
• イメージベースの PDF で OCR プロバイダーがない
• 出力ディレクトリ権限不足
• フォームラベルがテンプレート内で予想と異なる配置となり、一部フィールドが認識されない

注記

• kordoc は HWP / HWPX だけでなく HWPML、PDF、XLSX、DOCX も扱います
• 基本目的は AI が読める Markdown / JSON 変換 です
• 現在の配布ベースでは、ドキュメント化された CLI コマンドは基本変換と watch であり、フォーム処理は extractFormFields() などの Node API で接続されます