xls-skill:Excel → Markdown,圖片保留在儲存格中
為什麼需要此技能
大多數 Excel 讀取程式(openpyxl、pandas、CSV 匯出)只會看到儲存格的值。有兩類圖片會被遺漏:
- 儲存格內圖片。 圖片本身就是儲存格的內容。
- 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或資料夾(遞迴)。每個活頁簿會輸出一行,包含圖片計數。 - 需要 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 | 每張圖片一個條目:圖片、工作表!儲存格、類型、大小、附近儲存格文字、OCR 文字及描述欄位 |
images/ | 每張圖片另存為檔案,命名規則為 `<工作表編號><工作表名稱><儲存格>_<cell |
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-> 先轉換為 PNG(例如在 Windows 上用 Pillow,其他平台用 LibreOffice)再檢視。charts> 0 -> 圖表僅被計數,未繪製;如果圖表重要,請直接在 Excel 中開啟或匯出該工作表。- 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 轉換;如果沒有這些軟體,則只能讀取儲存格值,報告中會說明此情況。
