OfficeCLI 教學手冊 OfficeCLI — 為 AI Agent 而生的 Office 自動化命令列工具：以確定性的路徑定址（path addressing）與固定 JSON schema，讓 LLM 直接讀寫 Word／Excel／PowerPoint，免安裝 Office、免自行解析 OOXML 適用對象：資深後端／全端工程師、AI Agent 架構師、MCP 整合工程師、Document Engineering／Reverse Engineering 團隊、企業 IT 治理與導入負責人 文件性質：企業內部「AI Office Automation Platform」建置與維運教材＋開發規範參考＋大型軟體開發流程應用指南 版本基準：OfficeCLI（iOfficeAI/OfficeCLI，2026-03-15 建立、Apache License 2.0、單一 .NET 執行檔／C# 撰寫；最新版本 v1.0.143，發布於 2026-07-28）；本次撰寫查證時間點 2026-08-05
⚠️ 重要聲明（請務必先讀） OfficeCLI 仍在高速迭代中。 專案於 2026-03-15 建立，不到五個月內成長迅速。截至本次撰寫（2026-08-05，直接呼叫 api.github.com/repos/iOfficeAI/OfficeCLI 查證，非憑記憶）已有 25,503 Stars、1,714 Forks、73 Subscribers、44 個開放 Issue，自 2026-06-21 起多次登上 GitHub Trending 第一名。其 CLI 參數、JSON schema、Wiki 頁面結構在版本之間可能持續變動，任何指令與旗標在正式導入前，務必以最新官方 Repository／內建 officecli help 為準；本手冊所列數字與行為僅為查證當下快照。 本手冊的定位是「理解、彙整、分析、重組、補充最佳實務」，而非官方文件翻譯。 不直接翻譯 README、不大量抄錄原文，而是以企業教育訓練教材角度重新組織、加入架構圖、比較表、最佳實務與導入建議。 內容分兩類： 官方已確認事實：內文一律使用 repo 內實際指令／路徑／旗標名稱，不使用意譯替代。本次核校已透過 GitHub API 直接讀取 repo metadata、README.md／README_zh.md、SKILL.md、GitHub Wiki（Home／command-reference／command-view 等頁面）逐一比對，非僅憑記憶或二手轉述。 作者補充：凡屬作者依企業（含金融業、保險業、政府機關）導入 AI Agent Office Automation 之實務經驗所補充或推論之處，會標註 （作者建議） 或 （作者推論）。這些是最佳實務參考，非官方保證。 特別澄清（避免讀者對專案與架構產生誤解）： 命名衝突警告：GitHub 上另有一個完全不同、不相關的專案同樣以「OfficeCLI」自稱（officecli/officecli，主打「AI document generation CLI」、npm 安裝＋託管試用），與本手冊主題 iOfficeAI/OfficeCLI（25k+ Stars、Apache 2.0、單一二進位執行檔）並非同一專案。自行搜尋資料時請務必核對組織帳號 iOfficeAI，避免誤植指令或誤信功能。 OfficeCLI 本質上是一支 CLI／DOM 編輯器，MCP 只是它眾多整合介面之一（另有 Python SDK officecli-sdk、Node.js SDK @officecli/sdk、SKILL.md／load_skill 技能系統）。執行 officecli mcp <host> 才會啟動／設定 MCP Server，並非常駐預設行為。 PNG 輸出不是獨立的「渲染層」，而是 view screenshot 這個輸出模式，底層與 view html（HTML 預覽）共用同一套渲染引擎；且 view html 與 view svg 目前僅支援 PowerPoint（.pptx），並非任意格式皆可轉 HTML／SVG（查證自 Wiki command-view 頁面）。 PDF 匯出與 forms（互動表單欄位列舉）屬於「外掛相依」（plugin-dependent）功能，非核心二進位內建；官方文件明確寫著「Export the document to PDF via an installed exporter plugin」。 未見官方對舊版二進位格式（.doc／.xls／.ppt）或 CSV 作為第一類讀寫格式的原生支援證據；CSV 目前僅以 add --type csv 形式匯入 Excel，並非通用匯出格式。原始需求若涉及這些項目，本手冊會在對應章節明確標註「⚠️ 目前版本不支援，可透過 YYY 替代」，不會虛構不存在的指令。 未見官方 Docker Hub / GHCR 上架的正式容器映像；iOfficeAI 組織下的姊妹專案（AionUi）雖有內含 OfficeCLI 呼叫的 Dockerfile 範例，但那是應用層 Dockerfile，不等於 OfficeCLI 官方提供的映像。第三章的容器化安裝內容標註為**（作者建議）**的自建 Dockerfile 作法。 授權條款請留意「範圍界線」：OfficeCLI 本身（程式碼）採 Apache License 2.0，可自由商用、修改、內部散布。但這不代表經過 OfficeCLI 處理的文件內容本身著作權隨之開放——那是你自己或客戶的文件。金融業、保險業、政府機關導入前，仍應將「OfficeCLI 本機執行 vs. 透過 MCP 交給雲端 LLM 讀取內容」兩種情境的資料外洩風險分開評估（作者建議，詳見第十八章）。 官方權威來源與本次查證所用 URL／時間戳，請見〈附錄 A・參考資料〉。 目錄（Table of Contents） 符號約定 版本與相容性速查表 第一章 OfficeCLI 介紹 1.1 一句話定義 1.2 誕生背景與發展脈絡 1.3 解決哪些 AI Agent 痛點 1.4 設計理念與設計哲學 1.5 適用情境 1.6 不適用情境／限制 1.7 與傳統 Office Automation 的差異 1.8 核心特色 1.9 優勢 1.10 限制 1.11 未來發展方向與 Roadmap 1.12 AI Prompt 範例 1.13 本章 Checklist 與小結 第二章 OfficeCLI 系統架構 2.1 架構總覽 2.2 三層架構詳解（L1 → L2 → L3） 2.3 Resident Mode 常駐架構 2.4 CLI Layer 與指令分派 2.5 JSON Extractor／DOM 抽象層 2.6 與 OpenXML 的關係 2.7 Rendering Engine 概覽 2.8 MCP Server 架構 2.9 Watch Mode／Preview Server 架構 2.10 端到端資料流 2.11 AI Agent／LLM 整合點總覽 2.12 AI Prompt 範例 2.13 本章 Checklist 與小結 第三章 安裝 3.1 安裝路徑總覽 3.2 Windows 安裝 3.3 Linux 安裝 3.4 macOS 安裝 3.5 WSL 安裝 3.6 npm 安裝（跨平台） 3.7 Docker／Container 安裝 🧩（作者建議） 3.8 企業環境安裝：Air-gap／Offline Installation（作者建議） 3.9 企業代理（Proxy）設定（作者建議） 3.10 版本管理與更新 3.11 PATH 與環境變數 3.12 安裝驗證 Checklist 3.13 常見安裝錯誤 3.14 AI Prompt 範例 3.15 本章 Checklist 與小結 第四章 CLI 使用教學 4.1 指令總覽表 4.2 全域旗標與慣例 4.3 路徑定址語法 4.4 單位與數值慣例 4.5 create：建立空白文件 4.6 view：語意化讀取 4.7 get / query：查詢元素 4.8 set / add / remove / move / swap 4.9 raw / raw-set：L3 保底手段 4.10 validate 4.11 batch：原子化多指令執行 4.12 dump / merge 4.13 open / close：常駐模式操作 4.14 mcp：MCP Server 設定 4.15 install / plugins / skills / load_skill 4.16 help：內建三層說明系統 4.17 JSON 輸出格式與錯誤處理 4.18 錯誤案例與除錯 4.19 最佳實務 4.20 常見錯誤與 Anti-Pattern 4.21 AI Prompt 範例 4.22 本章 Checklist 與小結 第五章 支援格式 5.1 格式總覽表 5.2 DOCX（Word） 5.3 XLSX（Excel） 5.4 PPTX（PowerPoint） 5.5 Legacy 二進位格式（.doc／.xls／.ppt） 5.6 PDF 🧩 5.7 HTML／SVG（⚠️ 僅 PowerPoint） 5.8 JSON 5.9 PNG 5.10 Markdown（⚠️ 不支援原生輸出） 5.11 CSV（僅匯入 Excel） 5.12 格式選擇決策樹 5.13 最佳實務 5.14 常見錯誤 5.15 AI Prompt 範例 5.16 本章 Checklist 與小結 第六章 Rendering Engine 6.1 渲染引擎總覽 6.2 HTML Render 6.3 Image Render／PNG 6.4 Preview（watch 即時預覽） 6.5 Diff／增量更新機制 6.6 Page Layout 6.7 字型 6.8 圖片渲染 6.9 Table 渲染 6.10 Chart 渲染 6.11 SmartArt 渲染 6.12 最佳實務 6.13 常見錯誤與 Anti-Pattern 6.14 AI Prompt 範例 6.15 本章 Checklist 與小結 第七章 JSON Extraction 7.1 為什麼 JSON 是 OfficeCLI 與 LLM 之間的共同語言 7.2 JSON Envelope Schema 總覽（複習＋深化） 7.3 Document Structure（outline） 7.4 Table／Cell 7.5 Paragraph／Run 7.6 Image 7.7 Header／Footer 7.8 Style 7.9 Metadata（stats／issues） 7.10 dump：完整可重播 JSON 7.11 --output-schema-crc：Schema 版本指紋 7.12 JSON 在 AI Workflow 中的角色 7.13 最佳實務 7.14 常見錯誤 7.15 AI Prompt 範例 7.16 本章 Checklist 與小結 第八章 Office Editing 8.1 建立文件 8.2 Word 編輯 8.3 Excel 編輯 8.4 PowerPoint 編輯 8.5 圖片插入與格式設定（跨格式共通模式） 8.6 圖表建立速查表 8.7 樣式與格式化最佳實務 8.8 批次編輯 Workflow 8.9 最佳實務 8.10 常見錯誤與 Anti-Pattern 8.11 AI Prompt 範例 8.12 本章 Checklist 與小結 第九章 MCP Server 9.1 MCP 協定簡介 9.2 OfficeCLI 的 MCP 實作架構 9.3 officecli mcp 指令完整參考 9.4 Claude Code 設定 9.5 Claude Desktop 設定（⚠️ 作者補充，非官方一鍵指令） 9.6 Cursor 設定 9.7 VS Code／GitHub Copilot 設定 9.8 LM Studio 設定 9.9 Gemini CLI 設定（⚠️ 作者補充，非官方一鍵指令） 9.10 OpenAI Codex CLI 設定（⚠️ 作者補充，非官方一鍵指令） 9.11 MCP Tool 呼叫範例集 9.12 load_skill：動態技能載入 9.13 MCP Security 概覽 9.14 最佳實務 9.15 常見錯誤 9.16 AI Prompt 範例 9.17 本章 Checklist 與小結 第十章 Watch Mode 10.1 定位：watch 與其他預覽方式的差異 10.2 啟動與基本用法 10.3 HTTP Server 細節 10.4 Live Reload／Auto Reload 機制 10.5 API 端點 10.6 互動選取與 Marks 審閱工作流程 10.7 Browser 自動開啟與 Auto-Scroll 10.8 Hot Reload 情境示範 10.9 Debug 除錯技巧 10.10 最佳實務 10.11 常見錯誤與 Anti-Pattern 10.12 AI Prompt 範例 10.13 本章 Checklist 與小結 第十一章 AI Agent 整合 11.1 整合模式分類 11.2 Claude Code（官方支援） 11.3 Cursor（官方支援） 11.4 GitHub Copilot／VS Code（官方支援） 11.5 OpenAI Codex CLI（MCP 標準，需手動設定） 11.6 Gemini CLI（MCP 標準，需手動設定） 11.7 Windsurf（官方支援・Skill 檔自動偵測） 11.8 Shell-Exec 類 Agent 整合總表 11.9 選型建議 11.10 最佳實務 11.11 常見錯誤 11.12 AI Prompt 範例 11.13 本章 Checklist 與小結 第十二章 AI Workflow 12.1 端到端流程總覽 12.2 各階段詳解 12.3 範例 Walkthrough：月報自動化 12.4 範例 Walkthrough：合約套版審閱 12.5 人工確認關卡設計 12.6 失敗重試與回滾策略 12.7 最佳實務 12.8 常見錯誤 12.9 AI Prompt 範例 12.10 本章 Checklist 與小結 第十三章 Reverse Engineering 13.1 為什麼 Office 文件是 Legacy System 的隱藏規格書 13.2 Word 規格書 → 功能分析 13.3 Excel 試算表 → Database Schema 推導 13.4 PowerPoint 簡報 → 需求分析 13.5 從文件擷取 API／介面定義 13.6 產出正式規格書 13.7 與 Migration／Framework Upgrade 的銜接 13.8 案例 Walkthrough：舊保單管理系統文件化 13.9 最佳實務 13.10 常見錯誤 13.11 AI Prompt 範例 13.12 本章 Checklist 與小結 第十四章 Web Application 開發 14.1 OfficeCLI 在企業級 Web Application 開發流程中的定位 14.2 需求分析 14.3 Use Case 文件自動產出 14.4 ERD：從 Excel 欄位表到關聯圖 14.5 API／Swagger／OpenAPI 14.6 SDD／Spec 文件 14.7 Architecture／Sequence／Class／Component／Deployment Diagram 14.8 與 Spec Repository 的銜接 14.9 完整 Walkthrough：從 PRD 到 API 規格書 14.10 最佳實務 14.11 常見錯誤 14.12 AI Prompt 範例 14.13 本章 Checklist 與小結 第十五章 Framework Upgrade 15.1 為什麼升版評估需要文件工程 15.2 Spring Boot／Spring Framework 15.3 Jakarta EE／Java 15.4 Vue／Angular／React 15.5 .NET／Node.js 15.6 Maven／Gradle 15.7 通用 Upgrade Checklist 產生流程 15.8 Migration Plan 文件產出 15.9 案例 Walkthrough 15.10 最佳實務 15.11 常見錯誤 15.12 AI Prompt 範例 15.13 本章 Checklist 與小結 第十六章 AI 文件工程 16.1 從「AI 輔助」到「AI 原生」的典範轉移 16.2 Document Engineering（文件工程） 16.3 Prompt Engineering（文件情境） 16.4 Context Engineering（上下文工程） 16.5 Knowledge Engineering（知識工程）：RAG 與知識圖譜 16.6 Spec Engineering（規格工程） 16.7 五大工程領域的協作關係 16.8 最佳實務 16.9 常見錯誤 16.10 AI Prompt 範例 16.11 本章 Checklist 與小結 第十七章 系統維運 17.1 維運總覽 17.2 Monitoring 17.3 Logging 17.4 Troubleshooting 17.5 Performance ⚡ 17.6 Memory 17.7 Rendering 效能 17.8 Cache 17.9 CI/CD 整合範例 17.10 Kubernetes 部署範例（作者建議，批次渲染 Job） 17.11 最佳實務 17.12 常見錯誤 17.13 AI Prompt 範例 17.14 本章 Checklist 與小結 第十八章 安全性 18.1 威脅模型總覽 18.2 Office Macro／惡意文件 18.3 權限 18.4 Sandbox 18.5 MCP Security 18.6 JSON／指令注入 18.7 Prompt Injection（文件內藏惡意指令） 18.8 Secrets 18.9 最佳實務 18.10 常見錯誤 18.11 AI Prompt 範例 18.12 本章 Checklist 與小結 第十九章 最佳實務 19.1 大型企業導入原則總覽 19.2 銀行最佳架構 19.3 政府機關最佳架構 19.4 最佳流程 19.5 最佳 Prompt 原則 19.6 最佳資料夾結構（作者建議） 19.7 最佳 Git 規範 19.8 最佳 CI/CD 19.9 綜合案例 19.10 常見錯誤與 Anti-Pattern 19.11 AI Prompt 範例 19.12 本章 Checklist 與小結 第二十章 常見問題 FAQ 20.1 基礎與定位（Q1–Q10） 20.2 安裝與環境（Q11–Q20） 20.3 CLI 與路徑定址（Q21–Q32） 20.4 格式支援（Q33–Q42） 20.5 JSON 與資料擷取（Q43–Q50） 20.6 Rendering／Watch（Q51–Q60） 20.7 MCP 與 AI Agent 整合（Q61–Q70） 20.8 效能與維運（Q71–Q80） 20.9 安全性（Q81–Q92） 20.10 企業導入與治理（Q93–Q108） 20.11 本章 Checklist 與小結 第二十一章 Case Study 21.1 銀行｜放款契約自動套版審閱 21.2 銀行｜舊核心系統規格書逆向工程 21.3 保險｜理賠報告自動產出 21.4 保險｜舊保單管理系統文件化 21.5 政府機關｜Air-gap 環境公文範本自動化 21.6 政府機關｜招標規格書比對稽核 21.7 製造業｜品保報告自動彙整 21.8 製造業｜舊 ERP 欄位對照表現代化 21.9 AI 文件分析｜大量合約條款風險掃描 21.10 AI 文件分析｜財報簡報自動生成 21.11 Framework Upgrade｜Spring Boot 3 → 4 升版盤點 21.12 Framework Upgrade｜前端 Vue 2 → Vue 3 遷移文件化 21.13 跨國企業｜多語系月報自動化 21.14 新創 SaaS｜MCP 驅動的客製化提案簡報產生器 21.15 教育機構｜學習歷程報告批次產出 21.16 集團內部｜企業知識庫 RAG 建置 21.17 最佳實務（跨案例共通觀察） 21.18 常見錯誤 21.19 AI Prompt 範例 21.20 本章 Checklist 與小結 第二十二章 與其它工具比較 22.1 第一個關鍵區分：讀取／解析 vs. 讀寫／編輯 22.2 讀寫／編輯類比較 22.3 唯讀解析／擷取類比較（RAG／LLM 前處理導向） 22.4 綜合評分表（依五個面向，5 分制，作者依本章比較資料之主觀評分） 22.5 定位象限圖 22.6 選型決策樹 22.7 最佳實務 22.8 常見錯誤 22.9 AI Prompt 範例 22.10 本章 Checklist 與小結 第二十三章 OfficeCLI ＋ AI Agent 最佳架構 23.1 完整企業架構圖 23.2 各層職責說明 23.3 GitHub／GitLab 雙軌並存的實務考量 23.4 RAG／向量資料庫／知識圖譜的資料流 23.5 Reverse Engineering／Framework Upgrade 在架構中的位置 23.6 分階段導入建議 23.7 最佳實務 23.8 常見錯誤 23.9 AI Prompt 範例 23.10 本章 Checklist 與小結 第二十四章 Prompt Library 24.1 文件分析類（General Document Analysis） 24.2 Excel 分析類 24.3 PPT 分析類 24.4 Word 修改類 24.5 Migration 類 24.6 Architecture 類 24.7 Requirement 類 24.8 Spec 類 24.9 Testing 類 24.10 Review 類 24.11 十大類別總覽 24.12 最佳實務 24.13 常見錯誤 24.14 AI Prompt 範例（如何擴充本 Library） 24.15 本章 Checklist 與小結 第二十五章 完整企業導入指南 25.1 導入流程總覽 25.2 教育訓練 25.3 治理框架 25.4 版本管理 25.5 AI Agent 治理 25.6 MCP 治理 25.7 文件治理 25.8 ROI 衡量 25.9 成熟度模型 25.10 KPI 範例 25.11 最佳實務 25.12 常見錯誤 25.13 AI Prompt 範例 25.14 本章 Checklist 與小結 附錄 附錄 A・參考資料 附錄 B・全書 Checklist 總表 附錄 B.1・情境式 Checklist（跨章節整合） 附錄 C・FAQ 索引 附錄 D・版本歷程（本手冊） 結語 目錄將於全書完稿後以 python tools/markdown/generate_toc.py 重新產生並校正，撰寫期間之標題編號以此為準。
...