讓 AI Agent 處理 Office 檔案，難點通常不是“能否寫出一段文字”，而是能否保留既有模板、正確更新公式和圖表、看見排版結果，並在交付前確認檔案已經真正儲存。OfficeCLI 是一個面向 Agent 的本地命令列工具，支援 .docx、.xlsx 和 .pptx 的讀取、建立、編輯與渲染，不需要安裝 Microsoft Office。
它適合放在本地自動化、CI 文件生成或受控 Agent 工作流中。它不應直接獲得共享盤、客戶原件或財務主檔案的無限寫許可權；先從副本和模板開始，經過預覽與人工稽核後再交付。
OfficeCLI 適合哪些任務
OfficeCLI 提供結構化命令來操作 Word、Excel 和 PowerPoint。常見用途包括：
- 從現有文件讀取文字、樣式、表格、公式或幻燈片結構；
- 用 JSON 或命令生成報告、簡報和工作簿；
- 批次查詢替換、統一樣式或按模板填充資料；
- 從資料庫或 API 生成固定格式的週報、報價單和專案彙總；
- 把 Office 檔案渲染為 HTML 或 PNG，讓 AI 和人工檢查版式；
- 在 CI 或容器環境中生成文件，而不依賴桌面版 Office。
對一次性的個人文件，桌面編輯器可能更快；對重複生成、批處理或需要 Agent 參與的場景，命令列和結構化輸出更容易審查、復現和測試。
安裝前先確定檔案邊界
在任何安裝和自動化前，先設定這三條邊界：
- 輸入目錄：只允許 Agent 讀取任務需要的模板或副本，不直接讀取整個共享盤。
- 輸出目錄：把生成結果寫入獨立的
out/或臨時目錄，避免覆蓋原始檔案。 - 交付動作：上傳、郵件傳送、覆蓋共享檔案和修改財務資料都應由人工確認。
Office 文件可能包含批註、修訂記錄、隱藏工作表、外部連結、宏或敏感後設資料。自動化前應先確認來源可信，並使用副本測試。不要把“能讀取檔案”誤認為“可以安全公開檔案中的所有內容”。
怎樣安裝並確認版本
OfficeCLI 提供各平臺的單二進位制檔案，也支援包管理器安裝。Windows 使用者可以優先使用已配置的軟體包渠道，例如：
|
|
也可從專案 Releases 下載對應平臺的二進位制檔案。安裝後先確認版本：
|
|
如果使用下載指令碼或全域性 npm 安裝，應先核對倉庫、版本和企業軟體策略；不要把未知來源的遠端指令碼直接放進高許可權終端。對團隊環境，建議固定經過測試的版本，而不是讓每臺機器自動追蹤最新版。
第一次建立和預覽 PowerPoint
最小工作流是“建立 → 寫入 → 預覽 → 儲存”。例如建立一份簡報並新增標題頁：
|
|
outline 適合快速核對幻燈片和文字結構，html 會生成可在瀏覽器中檢視的渲染結果。不要只根據命令成功就認為檔案可交付：標題溢位、形狀重疊、字型替換和圖表比例問題，往往要在渲染結果中才看得出來。
需要連續調整時，可以啟動實時預覽：
|
|
官方示例中預覽服務預設會在本機 http://localhost:26315 開啟。只在本機受控環境使用該埠，不要未經驗證就把預覽服務暴露到公網。
讓 AI Agent 按“讀、改、看、驗”工作
直接要求 Agent “生成一份 PPT”容易得到不可控的整檔案重寫。更穩定的提示方式是把動作拆開：
- 先讀取目標檔案的結構或匯出 JSON，不修改任何內容。
- 讓 Agent 列出計劃修改的頁面、單元格或段落路徑。
- 一次只改一個邏輯單元，例如一頁幻燈片或一個工作表區域。
- 渲染 HTML 或截圖，並檢查內容、溢位、對齊和資料正確性。
- 儲存到輸出目錄，最後由人工稽核並決定是否替換原件。
可直接使用的任務約束示例：
讀取
templates/monthly-report.pptx，不要修改原檔案。根據data/summary.json生成out/monthly-report-review.pptx；只替換標題、三個 KPI 和圖表資料。完成後匯出 HTML 預覽，列出所有修改路徑、未填充欄位和需要人工確認的內容。
這比“根據資料更新月報”更容易審查，也能防止 Agent 改動無關母版、備註或隱藏內容。
Word、Excel 和 PowerPoint 的差異
| 檔案型別 | Agent 常做的事 | 交付前重點檢查 |
|---|---|---|
Word .docx |
替換段落、表格、頁首頁尾、樣式和目錄 | 頁碼、分頁、引用、修訂記錄、字型與表格斷行 |
Excel .xlsx |
寫入單元格、公式、資料驗證、圖表和透視表 | 公式結果、引用範圍、隱藏表、篩選條件、圖表資料來源 |
PowerPoint .pptx |
新建幻燈片、形狀、圖片、圖表、備註和主題 | 標題溢位、元素重疊、配色、比例、放映效果 |
Excel 尤其需要謹慎：公式可以正確寫入，不代表業務口徑正確。應把指標定義、日期範圍、幣種、單位和舍入規則寫在任務輸入中，並讓 Agent 輸出計算來源和異常值，而不是隻給最終數字。
用模板合併代替重複生成
重複型報告不應每次都讓 Agent 從空白開始設計。OfficeCLI 的 merge 可用 JSON 資料替換 .docx、.xlsx 或 .pptx 中的 {{key}} 佔位符：
|
|
適合的做法是：第一次人工確定模板和欄位，後續由程式或 Agent 只准備經過校驗的資料並執行合併。這樣比每次重新排版更穩定，也能把“內容生成”和“版式控制”分開。
當欄位缺失時，應讓流程停止並報告缺失項，而不是用猜測值、空字串或上一次客戶的資料繼續生成。對報價單、合同、發票、績效表和麵向外部的報告尤其如此。
多步驟編輯要注意儲存時機
OfficeCLI 支援 resident mode，讓文件在記憶體中保持開啟狀態以加快多步驟操作：
|
|
在 resident mode 中，工具自身的讀取命令能看到最新記憶體狀態；但其他程式、同步客戶端或上傳流程未必能看到。交給 Word、Excel、渲染器、Python 指令碼或網盤之前，先執行 officecli save 或 officecli close，確保修改已寫入磁碟。
批次操作還要明確失敗策略。若每條命令都允許繼續執行，可能生成“部分更新”的檔案；對關鍵文件更適合使用 --stop-on-error 並把失敗任務留給人工處理。
生成後怎樣做質量檢查
建議把質量檢查分為三層：
- 結構檢查：確認頁數、工作表、段落、佔位符、表格行數和輸出路徑。
- 資料檢查：抽查公式、彙總金額、日期、圖表範圍和源資料版本。
- 視覺檢查：檢視 HTML 或 PNG，檢查文字截斷、頁邊距、重疊、顏色與模板一致性。
對批次生成檔案，可隨機抽樣人工複核，並保留輸入資料版本、模板版本、OfficeCLI 版本、命令日誌和生成時間。這樣出現錯誤時能定位是資料、模板、命令還是模型指令的問題。
常見問題
檔案生成了但樣式不對
先執行 officecli view <檔案> html 或截圖預覽，不要只檢查檔案是否能開啟。確認 Agent 是否改錯了物件路徑、是否覆蓋了主題或母版，以及輸入資料是否超過原模板的文字容量。將大段文字限制、圖片尺寸和圖表數量寫進任務約束。
Excel 資料正確但圖表或公式不對
核對圖表引用範圍、工作表名稱、絕對/相對引用和日期格式。對包含宏、外部資料連線、複雜外掛或企業模板的工作簿，先在副本上驗證相容性；自動化工具不應繞過組織對宏和外部連結的安全策略。
Agent 覆蓋了原始檔案
立即停止後續寫入，從版本控制、備份或原始模板恢復。之後將輸入路徑設為只讀副本，輸出路徑固定到獨立目錄，並要求 Agent 在每次寫入前報告目標檔案。不要依賴“請不要覆蓋”這句提示詞來保護檔案。
總結
OfficeCLI 讓 AI Agent 可以在本地、無 Office 安裝的環境中處理 Word、Excel 和 PowerPoint，但可靠性來自流程而非單條命令：限定輸入輸出目錄、從模板和副本開始、按讀改看驗迴圈操作、儲存後再交給外部程式，並對資料和版式進行人工複核。把它當作可審查的文件自動化元件，而不是自動釋出器，才能同時獲得效率與可控性。