name: office360 slug: office360 displayName: office360 version: 2.1.0 description: "Office 檔案讀寫·建立·轉換·編輯工具箱。支援 PDF/DOCX/PPTX/XLSX 的讀取、建立與格式轉換（→PDF/→CSV/→JSON/→TXT）。XLSX 建立/編輯支援公式（SUM/AVERAGE/IF 等）+ 13 種財務配色（藍=輸入/黑=公式/綠=跨表），並由 LibreOffice 無頭真重算得到計算值；PPTX 支援視覺 QA；PDF 支援 OCR 與表單。讀取零依賴；轉換支援 WPS/Microsoft Office(COM) 與 LibreOffice 雙引擎。當用戶需要讀取/開啟/檢視/建立/寫入/編輯/轉換/匯出 .pdf/.docx/.pptx/.xlsx 檔案時觸發。" license: MIT visibility: public metadata: requires: bins: - python3 - libreoffice # 推薦：XLSX 公式真重算 + PPTX 視覺 QA + PDF 跨平臺兜底轉換 - pdftotext # PDF 文本提取 pipDeps: - openpyxl==3.1.5 - python-pptx==1.0.2 - pypdf - pdfplumber - reportlab - pytesseract - pdf2image - python-docx optionalBins: - soffice # = libreoffice，部分發行版命令名不同 optionalPipDeps: - pywin32==312 # 僅 Windows：Office/WPS COM 自動化轉 PDF platforms: - windows - macos - linux notes: "讀取/建立/編輯純 Python 跨平臺；→PDF 轉換優先 Windows COM(Office/WPS)，否則回退 LibreOffice 無頭；XLSX 公式真重算統一走 LibreOffice 無頭。"

office360 — Office 檔案工具箱 (v2.1.0)

v2.1.0 | 讀取·建立·轉換·編輯 | 四管道路由 | 驗證: 2026-07-20 融合 v1.5.0 前身(輕量/工程化/Windows COM) 與 skills-office-v1(公式真重算/視覺 QA/全 PDF 能力) 兩者優點。

5 分鐘快速開始

下面三個完整工作流無需翻看其他檔案，複製程式碼即可跑通。執行前先檢查環境：

python scripts/env_check.py     # 一鍵診斷依賴，缺什麼裝什麼

場景一：讀取 Excel → 計算 → 寫入新檔案（零依賴，僅需 Python）

"""只有 Python 標準庫就能跑：讀原始成績表，加總分和等級，寫出新檔案。"""
from openpyxl import load_workbook, Workbook

# 1. 讀取
wb = load_workbook("原始成績.xlsx")
ws = wb.active
old_data = [[cell.value for cell in row] for row in ws.rows]
wb.close()

# 2. 計算：追加"總分"和"等級"列
new_data = [old_data[0] + ["總分", "等級"]]  # 表頭
for row in old_data[1:]:
    name, *scores = row[0], *(v for v in row[1:] if isinstance(v, (int, float)))
    total = sum(scores)
    grade = "A" if total >= 270 else "B" if total >= 240 else "C" if total >= 210 else "D"
    new_data.append(row + [total, grade])

# 3. 寫入
out = Workbook(); out_ws = out.active
for r in new_data: out_ws.append(r)
out.save("成績帶等級.xlsx"); out.close()
print("✅ 成績帶等級.xlsx 已生成")

場景二：批次 Office 檔案轉 PDF（一條命令）

訪問小蔥技能站7w4.net，解鎖更多實用的AI技能外掛。

# 整個目錄下所有 docx/xlsx/pptx 轉為 PDF，自動硬邊界/重試/失敗彙總
python scripts/batch_convert.py ./文件/ ./輸出/

# 單個檔案
soffice --headless --convert-to pdf 報告.docx
# Windows 高保真轉換可走 COM（批次和單個都支援）

場景三：建立帶公式的 Excel → 重算 → 轉 PDF（完整鏈路）

"""生成銷售報表，含 SUM/IF 公式，LibreOffice 重算後匯出 PDF。"""
from openpyxl import Workbook
wb = Workbook(); ws = wb.active
ws.append(["地區", "銷售額", "目標"])
ws.append(["華東", 120, 100])
ws.append(["華北", 90, 100])
ws.append(["華南", 150, 100])
ws.append(["合計", "=SUM(B2:B4)", "=SUM(C2:C4)"])
ws.append(["達成率", "=IF(C5>0, B5/C5, 0)", ""])
wb.save("銷售表.xlsx")
print("✅ 銷售表.xlsx 已生成，含未重算公式")

# 重算公式（關鍵！不重算則下游讀到空值）
python scripts/recalc.py 銷售表.xlsx
# → 輸出 JSON：status=success, total_formulas=3, total_errors=0

# 匯出 PDF
soffice --headless --convert-to pdf 銷售表.xlsx
# → 生成 銷售表.pdf，B5=360, C5=300, B6=1.20 ✅

下一步： 需要更詳細的 API 引數或管道細節時，瀏覽下方的「快速開始：選對管道」和 references/ 目錄。

v2 相對前代的關鍵增強

快速開始：選對管道（觸發決策）

使用者一句話通常對應四條管道之一。先判斷意圖，再進對應 references/*：

管道不疊加：一個任務通常只走一條主管道。如「做表 → 重算 → 轉 PDF」是 CREATE 起步、完成後接 CONVERT，仍按主意圖選 CREATE。

編輯入口對照表（防混淆）

使用者說“編輯/修改/更新”時，先按檔案格式選入口，不要死記模組名：

記憶口訣：Excel 找 edit.md，Word 找 docx_edit.md，不用理解四個模組的完整劃分。

端到端示例（一句話需求 → 落地）： - 使用者：「幫我把這份 Word 轉成 PDF」 → CONVERT：soffice --headless --convert-to pdf 文件.docx（Windows 可走 office_to_pdf COM） - 使用者：「做個帶公式的銷售表」 → CREATE：create_xlsx(...)（含 SUM/IF）→ 收尾 python scripts/recalc.py 銷售表.xlsx 真重算 - 使用者：「提取這個掃描 PDF 的文字」 → READ：先 pdftotext；若為空 → OCR（pytesseract + pdf2image，見 read.md 掃描件 OCR 段） - 使用者：「把表裡 B2 改成 100」 → EDIT：openpyxl 改單元格 → 自動 .bak 備份

端到端實戰：含公式銷售報表 → 真重算 → 轉 PDF

把 CREATE → recalc → CONVERT 串成一條完整鏈路，覆蓋複雜場景。下面以「生成帶公式的銷售表，算出合計/達成率，再匯出 PDF」為例。

① CREATE — 生成帶公式的工作表

from openpyxl import Workbook
wb = Workbook(); ws = wb.active
ws.append(["地區", "銷售額", "目標"])
ws.append(["華東", 120, 100])
ws.append(["華北", 90, 100])
ws.append(["華南", 150, 100])
ws.append(["合計", "=SUM(B2:B4)", "=SUM(C2:C4)"])   # 公式字串，尚未計算
ws.append(["達成率", "=IF(C5>0, B5/C5, 0)", ""])     # 公式字串
wb.save("銷售表.xlsx")

② RECALC（關鍵）— LibreOffice 無頭真重算

create_xlsx 只寫入公式字串，非 Excel 程式讀到的是空值。必須由 recalc.py 呼叫 LibreOffice 真正計算並寫回數值：

python scripts/recalc.py 銷售表.xlsx
# 重算後：B5=360, C5=300, B6=1.20（達成率）

③ CONVERT — 轉 PDF

soffice --headless --convert-to pdf 銷售表.xlsx   # 跨平臺兜底
# Windows 高保真走 COM：python scripts/com_probe.py（探測可用後呼叫 office_to_pdf）

④ QA（可選）— 核對落盤值

pdftotext 銷售表.pdf - | grep -E "360|300|120%"
# 命中即證明公式已真重算並寫入 PDF

要點：recalc.py 是含公式 XLSX 的強制收尾步驟，否則下游讀到空值。批次同理——每張表生成後都走一遍 recalc.py。

限制與前置依賴（用前必讀）

把藏在程式碼裡的限制顯式列出，避免誤用：

• 零依賴可用：讀取 PDF/DOCX/XLSX/PPTX、建立基礎 DOCX/XLSX/PPTX，僅需 python3（標準庫）。
• 需 LibreOffice（soffice）：XLSX 公式真重算（recalc.py）、PPTX 視覺 QA、跨平臺 →PDF 兜底轉換。
• 僅 Windows 可用：原生高保真 →PDF 走 Office/WPS 的 COM 自動化（com_probe.py 探測）；macOS/Linux 不支援。
• 需 Tesseract + chi_sim：PDF 掃描件 OCR。
• 批次 / 大檔案：單任務有明確硬邊界，避免無限等待或資源耗盡；超限時指令碼會自動拒絕或拆批，不再只是"建議"。
• 單次任務：最多處理 100 個檔案 或總大小 ≤ 500MB（以先到為準）。
• 單個 XLSX 編輯：檔案 > 15MB 時，改用 read_only / write_only 模式或分工作表處理。
• 單個 PDF/Office 轉換：檔案 > 100MB 或頁數 > 500 頁 時自動拆批。
• 單次外部程序呼叫：預設 300 秒 超時，超時會自動結束並返回可讀錯誤。
• 超過上述任一閾值，指令碼會丟擲 ValueError 或自動拆批，而不是默默執行。
• 最小可用路徑：只想讀 / 建立基礎文件 → 只裝 python3；要全功能 → 裝 LibreOffice + 下列 pip 依賴。

pip install python-pptx openpyxl python-docx pypdf pdfplumber reportlab pytesseract pdf2image
# 系統側：LibreOffice、Poppler(pdftotext/pdftoppm)、Tesseract(+chi_sim)、qpdf/pdftk(可選)

異常速查（不用翻文件）

遇到報錯時先查下表，大部分問題可秒定位：

完整排查流程見 references/troubleshooting.md。執行前推薦先跑 python scripts/env_check.py 確認環境。

執行穩定性保障

office360 將批次與特殊環境的處理從"手工建議"變成指令碼級自動化，降低使用者手動調整成本：

• 自動硬邊界：batch_convert.py 對批次轉換做 100 檔案 / 500MB 總計 / 100MB 單檔案 / 300 秒超時 自動攔截；超限時直接給出結構化錯誤，不會無限卡死。
• 自動重試：每個檔案轉換失敗會重試 3 次；重試仍失敗保留在彙總結果中，成功/失敗一目瞭然。
• 環境先行：env_check.py 在執行前檢查 Python 庫、系統二進位制、Windows COM 狀態，並給出安裝命令，避免報錯後翻文件。
• 結構化錯誤：recalc.py、docx_edit.py、batch_convert.py 出錯時統一返回 {error, suggestion}，明確"為什麼失敗"和"下一步怎麼做"。

定位宣告

office360 是離線批處理工具箱，專注「檔案進、檔案出」的批次讀寫 / 建立 / 轉換 / 編輯。 - ✅ 覆蓋 PDF（讀取 / 抽取 / OCR / 表單 / 合併拆分 / 生成） - ✅ 跨平臺：讀取/建立/編輯功能僅需 Python，macOS / Linux / Windows 均可執行 - ✅ 零外部服務依賴：純 Python，無需常駐任何編輯器程序 - ✅ 批處理 / 自動化：適合「把 N 個檔案批次轉換 / 抽取 / 改」的指令碼活 - ✅ 離線編輯已有 XLSX/DOCX：改單元格/公式/行列插刪（自動備份原檔案） - ✅ XLSX 公式真重算：LibreOffice 無頭計算，匯出檔案自帶計算值 - ✅ PPTX 視覺 QA：自動檢測版式問題 - ❌ 不做即時協作編輯：不開啟你正看的文件做所見即所得修改 - ❌ 不接入線上文件：不直接讀寫雲端協作文件

平臺相容性

依賴說明：只要裝了 libreoffice，macOS/Linux 即可獲得公式重算 + PDF 轉換 + 視覺 QA；Windows 若裝有 Office/WPS 則 COM 轉 PDF 保真度更佳，否則同樣走 LibreOffice。

路由表 — 四管道模式

載入規則： 只讀取使用者當前任務對應的參考檔案，不要全部載入。一次只走一個管道。

遇到錯誤？ 載入 references/troubleshooting.md 檢視錯誤碼對照表和常見問題解答。 想避開常見坑？ 載入 references/anti-patterns.md 檢視「不該怎麼做」的反模式清單。 第一次用？ 載入 references/workflow.md 檢視 3 個完整端到端流程演示。

能力矩陣

狀態圖例： ✅ 已驗證 = 已通過驗證；— = 不適用；❌ = 不支援。

環境依賴

基礎（推薦安裝，解鎖重算/QA/PDF 能力）

• python3 3.11+
• libreoffice（或 soffice）：XLSX 公式真重算、PPTX 視覺 QA、PDF 跨平臺轉換兜底
• pdftotext（PDF 文本提取；macOS 可用 brew install poppler，Linux apt install poppler-utils）
• Python 庫：openpyxl==3.1.5、python-pptx==1.0.2、pypdf、pdfplumber、reportlab、pytesseract、pdf2image、python-docx

Windows 可選：COM 自動化（保真度更高的 →PDF）

• pywin32==312 + 已安裝 Microsoft Office 或 WPS Office 專業版（office_to_pdf() 自動探測引擎）

零依賴讀取：即使不裝 LibreOffice/Office，僅用 Python stdlib 也可讀取全部四種格式（read.md）與建立基礎 XLSX/DOCX、XLSX→CSV/JSON。

關鍵技術警告

Python 3.13+ ElementTree 名稱空間 Bug（已驗證） ElementTree.iter('{namespace}tag') 在 Python 3.13+ 對 OOXML 名稱空間處理不穩定，可能返回空結果。 所有 XML 解析必須使用 tag.endswith('}localname') 方式匹配（見 read.md/create.md 實現）。

核心增強一：XLSX 公式真重算（v2 關鍵）

背景：create_xlsx / edit_cell 寫入的是 <f>公式</f><v></v>（值留空）。Excel/WPS 開啟時會計算，但被 openpyxl（非 data_only）或 stdlib 讀回時 <v> 為空——程式化下游會拿到空值。v2 統一在建立/編輯後呼叫重算，讓檔案自帶計算值。

用法（建立或編輯含公式的 XLSX 後必做）：

python scripts/recalc.py <file.xlsx>

• 首次自動配置 LibreOffice StarBasic 宏 RecalculateAndSave（calculateAll → store → close）。
• 掃描所有單元格，檢測 7 類錯誤：#VALUE! #DIV/0! #REF! #NAME? #NULL! #NUM! #N/A。
• 輸出 JSON：status(success/errors_found)、total_errors、error_summary、total_formulas。
• Agent 據錯誤定位修復 → 再次 recalc，迭代至零錯誤。

無 LibreOffice 的回退：若環境無 libreoffice，改用 scripts/formula_check.py <file.xlsx> 做靜態錯誤掃描（#REF! 等），並明確告知使用者「公式值需由 Excel/WPS 開啟時計算」。此回退不寫回 <v>。

CREATE 管道收尾：create_xlsx(...) 後若無 LibreOffice 會警告；建議始終 python scripts/recalc.py 輸出.xlsx 收尾。 EDIT 管道收尾：改了公式的單元格後同樣呼叫 recalc.py（已自動 .bak 備份，可放心重算）。

核心增強二：PPTX 視覺 QA（v2 關鍵）

建立 PPTX 後，轉換為圖片做視覺檢查，自動發現版式問題：

# 1) PPTX → PDF（LibreOffice 無頭）
soffice --headless --convert-to pdf presentation.pptx
# 2) PDF → JPEG（每頁一張）
pdftoppm -jpeg -r 150 presentation.pdf slide
# 生成 slide-1.jpg, slide-2.jpg ...

隨後用子代理（subagent）逐張檢查：佔位符文本未替換、元素重疊、文本溢位、低對比度、字型未生效。發現問題 → 回到 create_pptx 修正 → 重新 QA。

PPTX 設計指引（避免通用 AI 醜版式）： - 配色：每套演示固定 1 主色 + 1 輔色 + 中性灰，全篇統一（勿每頁隨機色）。 - 佈局：優先「標題 + 要點列表」「雙欄」「圖示行」「半幅圖」四類，避免滿屏文字。 - 字型：中文用 微軟雅黑/思源黑體；英文用 Arial/Calibri；標題 28–40pt，正文 18–24pt。 - 留白：正文框邊距 ≥0.5 英寸，單頁要點 ≤6 條。 - 一致性：同層級標題/正文字號、顏色必須一致。

核心增強三：PDF 全能力（v2 關鍵）

載入 references/read.md 與下方要點：

• OCR 掃描件：pdftotext 拿不到文字時，用 pytesseract + pdf2image（PDF→圖片→識別）： python from pdf2image import convert_from_path import pytesseract pages = convert_from_path('scan.pdf', dpi=300) text = '\n'.join(pytesseract.image_to_string(p, lang='chi_sim+eng') for p in pages)
• 合併 / 拆分 / 旋轉 / 加水印 / 加密：pypdf（PdfReader/PdfWriter）+ pdftk + qpdf。
• 生成 PDF：reportlab（程式化排版）或 weasyprint（HTML→PDF）。
• 填表：pypdf 讀取/填寫 AcroForm 欄位（複雜表單建議先 pdf2image 轉圖人工核對欄位座標）。
• 文本/表格提取：pdfplumber（保留表格結構）或 pdftotext -layout。

轉換 →PDF：雙引擎擇優

references/convert.md 的 office_to_pdf() 實現： - Windows：優先 Microsoft Office COM（保真度高），WPS 候選失敗自動優雅回退 MSO（_detect_engine() 真實 Dispatch 探測，取首個可用 ProgID）。 - 跨平臺 / 無 Office：改用 LibreOffice 無頭： bash soffice --headless --convert-to pdf --outdir <outdir> <file> - 決策規則：有 Office/WPS 且需最高保真 → COM；否則 → LibreOffice。兩者輸出均為標準 PDF，可繼續走 PPTX 視覺 QA 或 PDF 文本提取。

各管道要點

• READ：見 references/read.md（PDF pdftotext；DOCX/XLSX/PPTX unzip+XML stdlib，零依賴；PDF 掃描件見上文 OCR）。
• CREATE：見 references/create.md（create_xlsx 模板骨架+13 財務色系+多 Sheet；create_docx stdlib/python-docx；create_pptx python-pptx）。XLSX 含公式須收尾 recalc.py；PPTX 須收尾視覺 QA。
• CONVERT：見 references/convert.md（XLSX→CSV/JSON stdlib；PDF→TXT；DOCX/PPTX/XLSX→PDF 雙引擎；PDF→DOCX 兩步法；MD/HTML/IMG→PDF）。
• EDIT：XLSX 見 references/edit.md（openpyxl 改單元格/公式/插刪行列，預設 .bak 備份，改公式後 recalc.py）；DOCX 見 references/docx_edit.md（stdlib 文本/段落替換，自動 .bak 備份）。

測試記錄（誠實宣告）

標註說明：【自動】 = 自動化用例；【人工】 = 需在本機用 WPS/Office 開啟驗證。 v2 在 v1.5.0 基礎上新增/變更：

誠實邊界：recalc.py / 視覺 QA / PDF 跨平臺轉換依賴 libreoffice；COM 轉 PDF 依賴 Windows + Office/WPS。釋出包不含測試檔案，使用者裝到的版本不含測試。

已知限制

• DOCX/XLSX stdlib 建立僅支援純文本/數值，無樣式表格圖片（用 python-docx/openpyxl 可破）。
• PPTX 建立必須用 python-pptx（WPS 要求 ~47 個內部檔案，stdlib 不可行）。
• PDF→DOCX 轉換質量低，建議兩步法：pdftotext + create_docx。
• PDF 掃描件需 OCR（已支援 pytesseract）。
• Office→PDF：Windows 優先 COM；無 Office 時走 LibreOffice（保真度略低但可用）。
• XLSX 中文字型：stdlib 手寫必須設 宋體/微軟雅黑 + charset=134（推薦 openpyxl 避坑）。
• 公式真重算/視覺 QA/跨平臺 PDF 均需 libreoffice。

效能預期

變更記錄

參考檔案索引

• references/read.md — 四種格式讀取（含 PDF OCR 提示）
• references/create.md — 建立 XLSX/DOCX/PPTX（含公式與 13 財務色系；XLSX 收尾重算）
• references/convert.md — 轉換（XLSX→CSV/JSON、→PDF 雙引擎、PDF→TXT/DOCX、MD/HTML/IMG→PDF）
• references/edit.md — 編輯已有 XLSX（openpyxl，自動備份）
• references/docx_edit.md — 編輯已有 DOCX（stdlib，自動備份）
• references/anti-patterns.md — 反模式清單
• references/troubleshooting.md — 排錯與錯誤碼
• references/workflow.md — 3 個端到端流程
• scripts/recalc.py — XLSX 公式真重算 + 錯誤掃描（LibreOffice），返回結構化錯誤與建議
• scripts/formula_check.py — XLSX 公式靜態錯誤掃描（無 LibreOffice 回退）
• scripts/com_probe.py — Windows COM 引擎自檢
• scripts/env_check.py — 環境依賴一鍵診斷（Python 庫 / 系統二進位制 / COM 狀態）
• scripts/batch_convert.py — 批次 Office → PDF 自動轉換（硬邊界 / 進度 / 重試 / 失敗彙總）
• scripts/docx_edit.py / scripts/docx_format.py — DOCX 編輯與 GB/T 9704 排版
• scripts/version_check.py — 版本一致性校驗
• templates/minimal_docx / templates/minimal_xlsx — 預驗證骨架

這個 Skill 質量不錯，功能覆蓋面廣，能處理 PDF、Word、Excel、PPT 四種格式的讀取、建立、轉換和編輯。文件非常貼心，提供了詳細的避坑指南和故障排查手冊，環境檢查指令碼能一鍵診斷缺失依賴。公式重算和雙引擎轉換等關鍵功能都有實現，適合需要批次處理 Office 檔案的使用者。主要小遺憾是 PPT 格式暫不支援直接編輯，需要重建檔案。總體推薦。