Community生產力與協作github.com

xls-skill

將 Excel 活頁簿(.xlsx/.xlsm/.xls)轉換為 AI 可讀的 Markdown,並將所有圖片放回原本所在的位置——包括嵌入儲存格內的圖片(WPS Office 的 =DISPIMG 和 Microsoft 365 的「置入儲存格」),以及浮動圖片、文字方塊、公式、合併/隱藏結構和 OCR。適用於讀取、轉換、稽核或回答含有照片、標籤、標誌、螢幕截圖、繪圖或簽名(無論在儲存格內或格線上方)的試算表。

xls-skill 是什麼?

此技能專為需要從 Excel 活頁簿中提取完整資訊(尤其是圖片內容)的 AI 代理程式和開發者設計。它能將 .xlsx/.xlsm/.xls 檔案轉換為結構化的 Markdown,並保留所有圖片在原始儲存格中的位置。這解決了大多數 Excel 讀取程式(如 openpyxl 或 pandas)會忽略的兩類圖片:透過 WPS Office =DISPIMG 或 Microsoft 365「Place in Cell」功能嵌入儲存格的圖片,以及繪製在格線上的浮動圖形和文字方塊。支援的平台包括 Python 指令碼環境(需要 Python 3.9+ 和 openpyxl),並可選用 Pillow 處理影像尺寸、Tesseract OCR 擷取圖片文字,以及 Microsoft Excel 或 LibreOffice 來開啟舊版 .xls 檔案。輸出內容包含完整的 Markdown 表格、圖片清單、公式清單、形狀清單以及轉換報告,代理程式應先檢視報告中的警告(如缺少圖片、EMF/WMF 格式或圖表),並搭配實際圖片內容進行分析,以提供準確的回覆。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/hougw/xls-skill/tree/HEAD

Installed? Explore more 生產力與協作 skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

預覽

來自技能 README

Parts!B2

說明文件

xls-skill:Excel → Markdown,圖片保留在儲存格中

為什麼需要此技能

大多數 Excel 讀取程式(openpyxl、pandas、CSV 匯出)只會看到儲存格的值。有兩類圖片會被遺漏:

  1. 儲存格內圖片。 圖片本身就是儲存格的內容。
    • WPS Office「嵌入儲存格」:儲存格只顯示 =DISPIMG("ID_...",1);圖片位於 xl/cellimages.xml。
    • Microsoft 365「置入儲存格」/ IMAGE:儲存格顯示 #VALUE!;圖片需透過 xl/metadata.xml 和 xl/richData/ 取得。
  2. 浮動圖片和文字方塊 繪製在格線上方(處理照片、標籤、表單編號)。

此技能會擷取所有這些圖片,將每張圖片另存為檔案,並將其寫回 Markdown 表格中其所在的儲存格,讓讀者能同時看到表格和圖片:

| # | A | B | C | D |
|---|---|---|---|---|
| 2 | 支架 | ![Parts!B2](images/01_Parts_B2_cell1.png) | 支架 \| 儲存格內圖片 | 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

代理程式的工作流程

  1. 轉換。 對活頁簿執行指令稿。
  2. 先讀取報告。 開啟 conversion_report.json。處理每個警告:
    • image not found in package -> 該儲存格標記為 [image missing: ID];如實告知,不要猜測圖片內容。
    • .emf/.wmf saved as-is -> 先轉換為 PNG(例如在 Windows 上用 Pillow,其他平台用 LibreOffice)再檢視。
    • charts > 0 -> 圖表僅被計數,未繪製;如果圖表重要,請直接在 Excel 中開啟或匯出該工作表。
    • OCR 跳過或缺少語言 -> 依靠親自檢視圖片。
  3. 檢視圖片。 開啟 <名稱>.images.md 中列出的每個檔案,並將每個 description 佔位符替換為圖片顯示的內容:物體、可讀文字(標籤、型號、標記)、符號,以及它與附近儲存格的關係。OCR 只是線索,不是最終答案;小標籤文字通常需要裁切或放大。
  4. 同時從表格和圖片中回答。 使用 Markdown 表格取得精確的儲存格值、公式和結構;使用圖片回答「它看起來像什麼 / 零件上寫了什麼」。兩者都引用 工作表!儲存格。
  5. 誠實回報缺口。 如果步驟 2 中的任何項目仍未解決,則將該活頁簿標記為需要人工檢查。

規則

  • 當活頁簿包含圖片、文字方塊、顏色或隱藏內容時,僅有 CSV 或純值表格並不能作為完整證據。請檢查工作表事實和各個清單。
  • 將每張圖片與其儲存格及相鄰儲存格配對;切勿僅依賴圖片順序。
  • 重要的文字可能位於儲存格之外:文字方塊(表單編號、修訂標記)、註解、頁首/頁尾。文字方塊和註解已被擷取;頁首/頁尾則否——如果缺少文件編號,請在 Excel 中檢查它們。
  • 顏色本身可能是資料(通過/失敗、風險等級、狀態)。此指令稿不解碼填滿色彩或條件式格式;如果顏色帶有意義,請使用 openpyxl 或頁面匯出檢查它們,並說明對應關係。
  • 合併範圍的值僅保留在左上角儲存格;在解釋空白儲存格之前,請先閱讀 merged: 那一行。
  • 隱藏的工作表、列和欄會被轉換並列出,不會被刪除。如果答案來自隱藏內容,請說明。
  • 不要信任終端機中的亂碼路徑;在回報檔案遺失之前,請先確認實際路徑是否存在。

限制

  • 浮動圖片會連結到其左上角錨點儲存格;跨越許多儲存格的圖片會在其清單中列出 to_cell。
  • 群組形狀會被讀取,但以獨立形狀繪製的箭頭和標註框只有在頁面渲染中才能保持與照片的關聯。當佈局很重要時(「哪個箭頭指向哪裡」),請使用 Excel 或 LibreOffice 將工作表匯出為 PDF/PNG,並與 Markdown 對照檢視。
  • 頁首/頁尾(VML)和註解中的圖片不會被擷取。
  • .xls 需要先透過 Microsoft Excel(Windows,pywin32)或 LibreOffice 轉換;如果沒有這些軟體,則只能讀取儲存格值,報告中會說明此情況。

相關技能