xls-skill: Excel -> Markdown、画像をセル内に保持
なぜこのスキールが必要か
ほとんどのExcelリーダー(openpyxl、pandas、CSVエクスポート)はセルの値しか認識しません。以下の2種類の画像が失われます。
- セル内画像:画像がセルのコンテンツそのもの。
- WPS Office「セル内に埋め込む」:セルには
=DISPIMG("ID_...",1)のみ表示。画像はxl/cellimages.xmlに格納。 - Microsoft 365「セル内に配置」 /
IMAGE:セルには#VALUE!が表示。画像はxl/metadata.xmlとxl/richData/から取得。
- WPS Office「セル内に埋め込む」:セルには
- フローティング画像やテキストボックス:グリッド上に描画されたもの(プロセス写真、ラベル、フォーム番号など)。
このスキールはこれらすべてを抽出し、各画像をファイルとして保存し、Markdownテーブルの該当セルに書き戻すため、読者はテーブルと画像を一緒に見ることができます。
| # | A | B | C | D |
|---|---|---|---|---|
| 2 | ブラケット |  | ブラケット \| セル内画像 | 4 |
実行方法
python <skill-dir>/scripts/xlsx_to_md.py <ファイルまたはフォルダ> [...] -o <出力ディレクトリ> [--ocr auto|off] [--ocr-lang eng+chi_sim]
.xlsx、.xlsm、.xls、またはフォルダ(再帰的)を受け入れます。ワークブックごとに画像数を1行で出力します。- Python 3.9以上と
openpyxlが必要。オプション:Pillow(画像サイズ)、Tesseract OCR(画像内テキスト)、Microsoft ExcelまたはLibreOffice(.xlsを開くため)。 - セルフテスト:
python <skill-dir>/tests/run_tests.pyでWPSおよびMicrosoft 365の疑似ワークブックを生成し、すべての画像が正しいセルに配置されているか確認します。
ワークブックごとに得られるもの(<出力ディレクトリ>/<名前>/)
| ファイル | 内容 |
|---|---|
<名前>.md | ワークブックインデックス、各シートを完全なMarkdownテーブル(切り詰めなし)で画像をセル内にインライン表示;各テーブルの上にシート情報(非表示状態、結合範囲、非表示行/列、コメント、テキストボックス、チャート数) |
<名前>.images.md | 画像ごとに1エントリ:画像、シート!セル、種類、サイズ、近隣セルのテキスト、OCRテキスト、説明スロット |
images/ | すべての画像をファイルとして保存。ファイル名は `<シート番号><シート名><セル>_<セル |
sheets_csv/ | シートの値;画像セルは [image: images/...] と表示 |
image_manifest.csv | シート、セル、種類(in-cell (WPS DISPIMG) / in-cell (Microsoft 365) / floating)、ファイル、パッケージパート、代替テキスト、サイズ、OCR、近隣テキスト |
formula_manifest.csv | セルごとの数式テキストと計算値 |
shapes_manifest.csv | フローティングテキストボックス/図形からのテキスト、アンカーセル付き |
conversion_report.json | カウント、警告、review_required |
エージェントのワークフロー
- 変換:スクリプトをワークブックに対して実行します。
- 最初にレポートを読む:
conversion_report.jsonを開き、すべての警告に対処:image not found in package(パッケージ内に画像が見つからない) -> セルは[image missing: ID]とマークされます。その旨を伝え、画像を推測しないでください。.emf/.wmf saved as-is(.emf/.wmfがそのまま保存) -> 参照する前にPNGに変換(WindowsではPillow、それ以外ではLibreOfficeなど)。charts> 0 -> チャートはカウントされ、描画されません。チャートが重要な場合はシートを開くかエクスポートしてください。- OCRがスキップされた、または言語が見つからない -> 自分で画像を確認してください。
- 画像を確認:
<名前>.images.mdにリストされたすべてのファイルを開き、各description(説明)プレースホルダーを画像が示す内容に置き換えます:オブジェクト、読み取り可能なテキスト(ラベル、型番、マーク)、シンボル、そして近隣セルとの関連。OCRはヒントであり、答えではありません。小さなラベルテキストは多くの場合、切り抜きや拡大が必要です。 - テーブルと画像を合わせて回答:Markdownテーブルから正確なセル値、数式、構造を取得。画像から「どのように見えるか / 部品に何が書かれているか」を取得。両方に
シート!セルを引用します。 - ギャップを正直に報告:ステップ2で未解決の問題が残っている場合、そのワークブックは手動レビューが必要とマークします。
ルール
- CSVや値のみのテーブルは、ワークブックに画像、テキストボックス、色、非表示コンテンツがある場合、完全な証拠にはなりません。シート情報とマニフェストを確認してください。
- 各画像をそのセルおよび隣接セルとペアにし、画像の順序だけで判断しないでください。
- 重要なテキストはセルの外側にある場合があります:テキストボックス(フォーム番号、改訂マーク)、コメント、ヘッダー/フッター。テキストボックスとコメントは抽出されます。ヘッダー/フッターは抽出されません。文書番号がない場合はExcelで確認してください。
- 色はデータ(合格/不合格、リスクレベル、ステータス)である可能性があります。このスクリプトは塗りつぶしや条件付き書式をデコードしません。色に意味がある場合は、openpyxlまたはページエクスポートで調査し、マッピングを明示してください。
- 結合範囲は左上のセルにのみ値が保持されます。空白セルを解釈する前に
merged:(結合)行を読んでください。 - 非表示のシート、行、列は変換され、リストされ、削除されません。回答が非表示コンテンツからのものである場合はその旨を伝えてください。
- 端末内の文字化けしたパスを信用しないでください。ファイルが存在することを報告する前に、実際のパスを確認してください。
制限事項
- フローティング画像は左上のアンカーセルに関連付けられます。複数のセルにまたがる画像は、マニフェストに
to_cell(宛先セル)とともにリストされます。 - グループ化された図形は読み取られますが、別々の図形として描画された矢印や吹き出しは、ページレンダリングでのみ写真との関係が維持されます。レイアウトが重要な場合(「どの矢印がどこを指しているか」)は、ExcelまたはLibreOfficeでシートをPDF/PNGにエクスポートし、Markdownと一緒に確認してください。
- ヘッダー/フッター内の画像(VML)およびコメント内の画像は抽出されません。
.xlsは最初に変換するためにMicrosoft Excel(Windows、pywin32)またはLibreOfficeが必要です。これらがない場合はセルの値のみが読み取られ、レポートにその旨が記載されます。
