OfficeCLI

OfficeCLI 是一款开源工具，让 AI 智能体（如 Claude Code、Cursor、Copilot）能够完全掌控 Word、Excel 和 PowerPoint。它无需安装庞大的 Office 套件，无需 Python 依赖，仅凭一个单一的可执行文件，即可在任何平台（Windows/macOS/Linux）上实现文档的创建、读取、修改和分析。

对于开发者而言，它将原本需要几十行代码和多个库的复杂操作，简化为一行命令；对于 AI 智能体，它提供了确定性的 JSON 输出和基于路径的寻址系统，彻底解决了大模型在处理 Office 文档时“幻觉”多、格式乱、难调试的痛点。

核心亮点：为什么 AI 需要 OfficeCLI？

1. AI 原生设计 (AI-Native)

• 确定性 JSON 输出：所有命令支持 --json 标志，返回结构一致的数据。AI 无需通过正则表达式去“猜”解析结果，直接处理结构化对象。
• 基于路径的寻址：类似文件系统的路径语法（如 /slide[1]/shape[2]），让 AI 能精准定位文档元素，无需理解复杂的 OpenXML 命名空间。
• 自愈式工作流：内置 validate 和 view issues 命令，AI 可以自动检测文档错误（如样式不一致、损坏的结构）并自行修复，无需人工干预。
• 自动技能安装：只需运行一行命令，OfficeCLI 会自动检测并配置 Claude Code、Cursor 等工具的 Skill 文件，即刻生效。

2. 极致轻量与便携

• 零依赖：基于 .NET 构建，运行时已内嵌在二进制文件中。无需安装 Python、Java 或 Office 软件。
• 全平台支持：提供 macOS (Intel/ARM)、Linux (x64/ARM)、Windows (x64/ARM) 的原生二进制文件。
• 无头模式 (Headless)：完美适配 Docker 容器、CI/CD 流水线和服务器环境，无需图形界面即可处理文档。

3. 三层架构：从简单到精通

OfficeCLI 设计了渐进式的复杂度，适应不同需求：

• L1 读取层：语义化视图 (view)。快速查看大纲、文本、统计信息或 HTML 预览。
• L2 DOM 层：结构化操作 (get, set, add, remove)。像操作 JSON 一样操作文档元素。
• L3 原始层：XML 兜底 (raw, raw-set)。当高层抽象不够用时，直接通过 XPath 操作底层 OpenXML。

快速开始：从零到生成 PPT

只需几秒钟，即可创建一个专业的演示文稿：

# 1. 创建新文件
officecli create deck.pptx

# 2. 添加幻灯片
officecli add deck.pptx / --type slide --prop title="Q4 Report" --prop background=1A1A2E

# 3. 添加文本形状
officecli add deck.pptx /slide[1] --type shape \
  --prop text="Revenue grew 25%" --prop x=2cm --prop y=5cm \
  --prop font=Arial --prop size=24 --prop color=FFFFFF

# 4. 查看大纲
officecli view deck.pptx outline

输出：

Slide 1: Q4 Report
  Shape 1 [TextBox]: Revenue grew 25%

对比传统 Python 方案：
以前你需要引入 python-pptx，编写 50+ 行代码来处理幻灯片布局、坐标单位和保存逻辑；现在，一条命令搞定。

核心功能详解

1. 全面的文档操作

支持 Word (.docx), Excel (.xlsx), PowerPoint (.pptx) 的全生命周期管理：

• Word：段落、表格、样式、页眉页脚、公式、批注、书签、目录等。
• Excel：单元格、公式（内置 150+ 函数自动求值）、透视表、图表、条件格式、数据验证等。
• PowerPoint：幻灯片、形状、动画、3D 模型 (.glb)、 morph 过渡、视频音频、备注等。

2. 实时预览 (Watch Mode)

启动本地 HTTP 服务器，实时在浏览器中预览 PPT 修改效果，非常适合与 AI 配合进行迭代设计：

officecli watch deck.pptx
# 访问 http://localhost:18080，每次修改自动刷新

3. 高性能批量处理

• 驻留模式：open / close 命令将文档保留在内存中，通过命名管道通信，实现接近零延迟的连续操作。
• 批量模式：batch 命令允许在一次文件打开/保存周期内执行数十条指令，原子化操作，效率极高。

4. 模板合并 (Mail Merge)

强大的模板引擎，支持将 JSON 数据注入到 Word、PPT、Excel 的任意文本位置（包括表格、形状、页眉）：

officecli merge invoice-template.docx output.docx '{"client":"Acme","total":"$5,200"}'

AI 智能体集成指南

OfficeCLI 的设计初衷就是让 AI “开箱即用”。

自动安装（推荐）

在你的 AI 对话框（如 Claude Code）中粘贴以下命令，它会自动下载二进制文件并配置技能：

curl -fsSL https://officecli.ai/SKILL.md

SKILL.md 包含 239 行详细的指令，教会 AI 如何使用所有命令、处理错误和理解架构。

手动集成 MCP

OfficeCLI 内置了 MCP (Model Context Protocol) 服务器，可一键注册到各类 AI 工具：

officecli mcp claude    # 集成到 Claude Code
officecli mcp cursor    # 集成到 Cursor
officecli mcp vscode    # 集成到 VS Code Copilot

为什么 AI 偏爱 OfficeCLI？

1. 无幻觉导航：路径语法简单明确，AI 不会迷失在 XML 树中。
2. 错误自纠正：如果 AI 尝试访问不存在的路径，OfficeCLI 会返回结构化错误建议（如“有效索引范围是 1-8”），AI 可据此自动修正。
3. 内置帮助：AI 可随时运行 officecli pptx set shape 查询属性格式，无需查阅外部文档。

安装方法

一键安装脚本

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex

手动下载

前往 GitHub Releases 下载对应平台的二进制文件，无需任何安装步骤，解压即用。

验证安装

officecli --version

应用场景

• 📄 自动化报告生成：从数据库或 API 拉取数据，自动生成格式完美的 Word/PPT 报告。
• 🏭 CI/CD 文档流水线：在构建流程中自动验证文档规范、提取测试结果为 Excel、生成发布说明。
• 🤖 AI 驱动的内容创作：让用户通过自然语言描述需求，AI 调用 OfficeCLI 直接生成完整的演示文稿或合同。
• 🔄 批量文档处理：一次性更新成千上万个文档的样式、替换Logo、提取关键数据。
• 📦 容器化办公：在 Docker 环境中运行无头 Office 自动化任务，无需昂贵的 Office 授权。