paper-excel-to-table

paper-excel-to-table

紙様式の Excel 帳票 (人間の記入しやすさを最適化したレイアウト) を PDF 化したものから、構造化 CSV を取り出すワークフロー。

いつこの skill を使うか

• 「水道事業業務年報みたいな 紙帳票 Excel を CSV にしたい」
• 「セル結合・装飾だらけの調査票レイアウトを機械判読可能にしたい」
• 「e-Stat の調査票レイアウト PDF を構造化したい」

入力前提 (重要)

• 入力は PDF 固定。xlsx を渡された場合は、ユーザーに以下を案内して中断する:
  • Excel の「ファイル → 名前を付けて保存 → PDF」
  • Numbers の「書き出す → PDF」
  • LibreOffice の「ファイル → エクスポート → PDF」
  • xlsx → 画像の自動化は意図的に非対応 (見た目の再現性・安定性の問題。詳細は docs/dev/plugins/paper-excel-to-table.md §4.1)
• macOS のみ。rasterize.swift が PDFKit を使うため、Darwin 以外では fail-fast

抽出ワークフロー

以下を必ず順番に踏む。各ステップを飛ばさない。

1. ユーザーコンテキストの確認 (省略しない)

抽出の精度はユーザーから得られる前提情報で大きく変わる。ユーザーに以下を尋ねる (既に提供されていれば繰り返さない):

• この帳票は何の調査票・年報か (正式名称、発行元)
• 既知の列・項目・語彙 (「item_code は右端にある」「※印は脚注番号」など)
• 対象ページ (複数ページ PDF の場合)
• スキーマ (YAML) を持っているか — 持っていれば絶対パスを受け取る
• 出力 CSV の保存先

コンテキストが薄いまま進めない。抽出精度を律速する。

2. PDF を画像化

scripts/rasterize.py を uv run --script で呼ぶ (単一 PDF は 1 コマンドで全ページを出す):

uv run --script <PLUGIN_ROOT>/skills/paper-excel-to-table/scripts/rasterize.py \
  <INPUT_PDF> <OUT_DIR> [--dpi 300] [--pages 1-]

• デフォルト --dpi 300 (A4 縦 ~2481×3508 px)。下げない。高解像度を保ったまま後段の crop で自然に API 入力上限に収まる設計
• 出力は OUT_DIR/page-001.png, page-002.png, ...
• stdout に Backend Contract の JSON (page_count、ページごとの width_px/height_px/megapixels 等) が出る。次ステップで渡すパスはここから拾う
• 一度 rasterize すれば PDF のページ数・寸法は JSON に全部入るので、その後は mdls/mdfind/pdfinfo 等で同じ情報を取り直さない (ユーザーに余計な permission プロンプトを出すだけ)。事前に「この PDF 何ページあるか先に見たい」など rasterize 前に知りたい用途で mdls -name kMDItemNumberOfPages <pdf> を使うのは OK

3. サブエージェント paper-excel-to-table:paper-excel-extractor で抽出

重要: 画像 Read や抽出ロジックは subagent 側で行う。main セッションでは画像を直接 Read しない — コンテキスト汚染を避けるため。

Agent tool で subagent_type=paper-excel-to-table:paper-excel-extractor を起動し、prompt に以下を プレーンテキストで 詰める。

image_paths:
  - <abs path to page-001.png>
  - (必要なら追加ページ)
output_csv_path: <abs path to out.csv>
user_context: |
  - 帳票名: 地方公営企業決算状況調査 (水道事業) レイアウト
  - 年度: 2025
  - 既知の列: ...
schema_path: <abs path to schema yaml, 省略可>
workdir: <abs path for crop outputs, 省略可>
rasterize_info: |
  page_count: 10
  target_pages:
    - index: 1
      width_px: 2481
      height_px: 3508
      megapixels: 8.70
  # step 2 で受け取った JSON の "pages" 配列から、image_paths に対応する分を抜粋

rasterize_info を入れておくと subagent が mdls / pdfinfo 等で同じ情報を取り直さずに済むので、ユーザーへの無駄な permission プロンプトが減る。

subagent は内部で観察プラン策定 → CSV 書き出し → 低確度箇所の crop → 再観察 → (schema があれば) validate まで回し、main には短いレポートだけを返す。

4. subagent の応答を処理

返答パターン別に対応します。

• 通常応答 (csv_path, rows, id_column, hierarchy_signal, crops_used, low_confidence, schema_validation, notes_for_user): ユーザーに要約を提示。low_confidence に項目があればその旨を明示
• INSUFFICIENT_CONTEXT: から始まる応答: 続く質問をユーザーに投げ、回答を受けて手順 3 をやり直す
• MISSING_INPUT: から始まる応答: 自分の prompt 組み立てが不完全。不足を補って再実行

5. (schema 未指定のときの提案)

schema 無しで走ったケースでは、最後に「この CSV から YAML schema を抽出して、次回以降は schema-driven モードで検証可能にしますか？」とユーザーに提案する (実装は別タスク)。

典型的な落とし穴 (必ず目を通す)

インデントによる階層 → level 列に必ず落とす

紙帳票は インデント幅・箇条書き記号・フォント太さ・段付けた番号 (1 / 1.1 / 1.1.1) で階層を表現する。この情報は CSV では消えるので、整数 level 列 (0 始まり) に落とし込む。subagent にはこれを厳守させるよう明示する。

レイアウトは左→右とは限らない

ID / 項目コード / 連番が 右端 にある帳票は珍しくない。左→右ルールを盲信しない。subagent のレポートに「ID 列の位置 (left/right)」を必ず書かせる。

視覚的なセル結合 ≠ 論理的なセル結合

• 枠線がなくても別項目の場合がある
• 枠線があっても親項目 + 子項目を合体表示している場合がある
• 「値が空のセル」と「そもそもセルが存在しないセル」を区別する

脚注・補足記号 (※, 注1), *)

CSV 化のときは必ず別列 (notes など) に分ける。値列に混ぜない。

確信が持てないセルは空欄にしない

subagent は読み取れない値を 必ず ? でマークするルール。空欄と混同しないこと。ユーザーへのレポートでも ? の残存を明示する。

ユーザーコンテキストの提供を促す

帳票には「その組織・業界で自明の語彙」が大量に入っている。LLM が推測するより、ユーザーに聞く方が圧倒的に速く正確。1. のステップをショートカットしない。

リソース / CLI 引数

scripts/rasterize.py

uv run --script <...>/scripts/rasterize.py <pdf> <out_dir>
  [--dpi 300] [--box media|crop] [--colorspace sRGB|Gray]
  [--alpha] [--no-annots] [--pages 1-|1,3,5|2-4,7]

• Swift 側 (rasterize.swift) が Backend Contract (docs/dev/plugins/paper-excel-to-table.md §4.3) に従った JSON を stdout に 1 発出す
• 300 DPI で A4 縦 ~2481×3508 px。意図的に Claude Vision の API 入力上限 (~2576 px) を超え、後段 crop 時に native 解像度を温存する

scripts/crop.py

uv run --script <...>/scripts/crop.py <image>
  (--box x,y,w,h | --rel-box x,y,w,h) -o <out.png>
  ...同じ種類の --box/--rel-box と -o を同数ペアで繰り返して複数 crop 可

• 原点は 左上。--box は絶対 px、--rel-box は画像サイズに対する比率 0..1
• 同一コマンド内で --box と --rel-box を混ぜられない (Typer が複数種類のオプション間の登場順を保持しないため、ペアリングが壊れる)。両方必要なら 2 回に分けて呼ぶ
• 出力 PNG は入力 PNG の DPI メタを引き継ぐ

scripts/schema.py

uv run --script <...>/scripts/schema.py validate <csv> --schema <yaml>
uv run --script <...>/scripts/schema.py dump-json-schema --schema <yaml>

• YAML から Pydantic モデルを動的生成して CSV を validate
• allow_unknown: true の列では ? (未読センチネル) を通す
• validate 失敗時は stderr に行単位の issue を列挙して non-zero exit

参考 schema

• scripts/schemas/suido_gyomu_nenpo.yaml — 水道事業決算状況調査レイアウト用の最小例

環境

• 必須: macOS + Xcode Command Line Tools (swift コマンド)
• 不要: ANTHROPIC_API_KEY (MVP の抽出は Claude-native; subagent が Claude Code セッション内で動く)
• 将来 (Anthropic API 直叩き経路に昇格したとき): ANTHROPIC_API_KEY, PAPER_EXCEL_MODEL 等を追加 — docs/dev/plugins/paper-excel-to-table.md §9 参照

初回 install 直後の注意

Claude Code で本 plugin を install した直後、subagent (paper-excel-extractor) が認識されない場合があります。その時は以下を 1 回だけ実行します。

/reload-plugins

推奨 allowlist (任意)

ワークフロー中で呼ぶ Bash コマンドで permission プロンプトを抑えたいとき、ユーザーの ~/.claude/settings.json に以下を追加すると快適:

{
  "permissions": {
    "allow": [
      "Bash(uv run --script *)",
      "Bash(swift --version)",
      "Bash(xcode-select -p)"
    ]
  }
}

plugin 側で allowlist を配布する仕組みは現状ありません (plugin 同梱 settings.json は agent / subagentStatusLine キーのみ対応)。