對 AI agent 來說，Office 檔一直是最痛的一環：格式是 ZIP 加 XML、二進位、動輒幾十 MB，而且多數人只能靠 python-docx、openpyxl 這類覆蓋面窄的程式庫去打補丁。結果是——改一個字級要寫十行代碼，改完還不知道有沒有弄壞排版。
OfficeCLI 把問題反轉：它不叫 AI 去學 OOXML，而是提供一層穩定、可查詢、可批次、支援 JSON 的命令面。你（或 agent）只需要講「哪個位置、改什麼屬性」，其餘由工具處理。本文以實測版本 officecli v1.0.156 為準，逐層拆解，並附上真實渲染圖。
為什麼要把 Office「CLI 化」？
三項設計決定令它特別適合 agent：
- 單一二進位：無需裝 Microsoft Office，也無 Python 環境依賴；
- schema 驅動：屬性名、值格式全部可以問，不用背；
- 三層退化：高層表達不到就落低層，永遠有兜底。
對 agent 而言，最值錢的是「可驗證」：每一步都能 get 回讀、validate 校驗，而不是盲目改完祈禱檔案沒壞。想先熟悉命令列基本概念，可讀 Terminal、Shell、CLI：三個詞的差別，與十行保命指令。
安裝與驗證
curl -fsSL https://d.officecli.ai/install.sh | bash
officecli --version
裝完如果還找不到命令，開一個新終端機（讓 PATH 生效）。--version 應印出 1.0.156。
三層模型：L1 讀 → L2 編輯 → L3 原始 XML
官方建議永遠先用高層，只在表達不到時才落低層。這條「退化階梯」是整個工具的骨幹：
| 層 | 用途 | 代表命令 |
|---|---|---|
| L1 | 建立、檢視、查詢、驗證 | create view get query validate |
| L2 | 改屬性、加刪搬、批次提交 | set add remove move swap batch |
| L3 | L2 表達不到時的兜底 | raw raw-set add-part |
officecli create report.docx # L1：建立
officecli view report.docx outline # L1：檢視大綱
officecli set report.docx /body/p[1] --prop bold=true # L2：編輯
officecli raw report.docx /document # L3：直接看原始 XML
實作：三種檔、三條路
4.1 PowerPoint：由零生成一頁
officecli create slides.pptx
officecli add slides.pptx /slide[1] --type shape --prop text="Q4 Report" --prop size=24
officecli set slides.pptx '/slide[1]/shape[1]' --prop fill=1A1A2E
留意：/slide[1] 要加引號，否則 zsh 會把方括號當 glob 展開。形狀屬性可以用 officecli help pptx shape 查，不必靠猜。
4.2 Word：段落與樣式
officecli create report.docx
officecli add report.docx /body --type paragraph --prop text="Executive Summary" --prop style=Heading1
officecli add report.docx /body --type paragraph --prop text="Revenue increased by 25% year-over-year."
4.3 Excel：儲存格直接用路徑寫
officecli create data.xlsx
officecli set data.xlsx /Sheet1/A1 --prop value="Name" --prop bold=true
officecli set data.xlsx /Sheet1/A2 --prop value="Alice"
.xlsx 直接按 /Sheet1/A1 路徑賦值；formula 屬性可寫公式（不加等號），numberformat 可設格式碼。
Resident 常住模式：效能關鍵
每個命令首次執行會自動起一個 resident（閒置約 60 秒收），避免反覆開關檔。長 session 可明確控制：
officecli open report.docx
officecli set report.docx /body/p[1] --prop align=center
officecli save report.docx
officecli close report.docx
只有交去非 officecli 程式（python-docx、Word、上傳）之前才需要 save 或 close 落盤；officecli 自己的讀取永遠看得到最新編輯。
批次與 Watch：原子提交與互動改稿
6.1 批次（batch）＝ 原子
多個操作一次過提交，預設原子：任何一項失敗 → 整批回滾，檔案保持 byte-identical。
echo '[
{"command":"set","path":"/Sheet1/A1","props":{"value":"Done"}},
{"command":"set","path":"/Sheet1/B1","props":{"value":"OK"}}
]' | officecli batch data.xlsx --json
想「成功幾多得幾多」就加 --best-effort；officecli dump 更能輸出可重播的 batch JSON，做完美 round-trip。
6.2 Watch 互動：你點選、AI 就改
watch 起一個會自動刷新的 HTML 預覽（預設埠 26315），你在瀏覽器點選形狀，CLI 讀到「當前選取」再動作：
officecli watch deck.pptx
officecli get deck.pptx selected --json
選取用穩定 ID（@id=）表示，所以編輯後選取仍然有效。
專項技能與 MCP 接入
「報告／論文／融資 deck／財務模型／儀表板」各有規範。先看有哪些技能，再裝需要的：
officecli skills list
officecli skills install pitch-deck
| 格式 | 技能 | 幾時用 |
|---|---|---|
| Word | word / academic-paper | 報告信件／論文（APA、交叉引用） |
| PPT | pptx / pitch-deck / morph-ppt | 通用簡報／融資／Morph 動畫 |
| Excel | excel / financial-model / data-dashboard | 通用／財務模型／KPI 儀表板 |
MCP 方面，officecli mcp 起 stdio server，officecli mcp <target> 註冊到客戶端。MCP 工具只有一個 command 參數，原樣傳去 CLI：
{ "command": "set report.docx /body/p[1] --prop bold=true" }
五個常見錯誤
| 陷阱 | 正解 |
|---|---|
--name "foo" | 全部屬性行 --prop name=value |
zsh 直接打 /slide[1] | 必須加引號：'/slide[1]'，否則 glob 爆 |
用 shape[1] 當內容 | shape[1] 通常係標題 placeholder，內容由 shape[2] 起 |
| 猜屬性名 | officecli help docx paragraph |
--prop text="$15M" | $ 會被 shell 食掉，用單引號包起來 |
下一步
- 生成側：圖像與多模態素材用 ArtCraft 深度教學：AI 生成 App（macOS）與它的工具鏈定位；
- 排版側：出血、多欄、IDML 出版用 DesignCraft 深度教學：用 designcraft-cli 做排版與出版；
- 接進 agent：
officecli install一次裝好 binary、技能與 MCP，再讀 OpenClaw 安裝教學：一條指令裝好屬於你的 AI Agent Gateway 把 Gateway 也裝起來。