OfficeCLI AI Office 套件详细部署教程

OfficeCLI 是首个专为 AI 智能体设计的办公套件，它能通过命令行或 MCP 协议让 AI 直接读写和编辑 Word、Excel、PowerPoint 文件。它非常轻量——单个自包含二进制文件，无需安装 Office，无需依赖，支持跨平台。本教程将指导您完成部署、配置和与 AI 助手的集成。

📋 目录

  1. OfficeCLI 是什么
  2. 核心设计：专为 AI 而生
  3. 系统要求与准备
  4. 安装 OfficeCLI
  5. 基本使用与演示
  6. AI 智能体集成
  7. 高级功能与工作流
  8. 更新与卸载
  9. 常见问题排查

OfficeCLI 是什么

OfficeCLI 是一个命令行工具，它将复杂办公软件的交互封装成了简单、可预测、适合脚本和 AI 调用的命令。其核心理念是让 AI 智能体能够像人类一样创建、读取、修改和验证 Office 文档。

核心优势：

  • AI 原生设计：所有命令支持结构化 JSON 输出，方便 AI 解析；错误信息包含建议和有效值范围，帮助 AI 自我纠正。
  • 单二进制，零依赖：内置了 .NET 运行时和文档渲染引擎，无需安装 Office 或任何额外库。
  • 路径化元素访问：使用稳定的元素路径（如 /slide[1]/shape[2]）定位文档中的任何部分，无需理解复杂的 XML。
  • 三层层级架构：从高层次的语义视图（L1）到结构化 DOM 操作（L2），再到原始 XML（L3），AI 可根据需求选择最合适的抽象层级。
  • 内置渲染引擎：能将文档渲染为 HTML 或 PNG，让 AI 能“看见”自己的产出，形成“渲染-观察-修正”的闭环。

核心设计：专为 AI 而生

三个层级，渐进复杂度

层级 目的 命令示例
L1: 读取 获取文档的语义视图，如大纲、文本、统计信息 officecli view deck.pptx outline
L2: DOM 操作 对文档结构进行增删改查 officecli add deck.pptx / --type slide --prop title="Q4 Report"
L3: 原始 XML 万能回退方案，直接操作底层 XML officecli raw-set report.docx document --xpath "//w:p[1]" --xml '<w:r><w:t>Injected</w:t></w:r>'

路径定位与结构化输出

OfficeCLI 使用稳定的路径语法定位元素（1-based索引，基于元素类型）：

  • /slide[1]：第一张幻灯片
  • /body/p[2]/r[1]：正文第二段的第一段文字片段

所有命令支持 --json 参数，输出结构化数据，便于 AI 解析和决策。错误信息清晰，并附带建议。

系统要求与准备

  • 操作系统：macOS（Apple Silicon/Intel）、Linux（x64/ARM64）、Windows（x64/ARM64）。
  • 网络：用于首次下载二进制文件（安装时）。
  • AI 助手（可选）：如 Claude Code、Cursor、Windsurf 等，以便进行集成。

安装 OfficeCLI

快速安装（推荐）

macOS / Linux (bash)：

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

Windows (PowerShell)：

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

通过包管理器安装

Homebrew (macOS/Linux)：

1
brew install officecli

Scoop (Windows)：

1
scoop install officecli

npm (所有平台)：

1
npm install -g @officecli/officecli

验证安装

1
officecli --version

基本使用与演示

1. 创建并预览一个 PowerPoint

在一个终端中启动实时预览，在另一个终端中执行修改，浏览器会实时更新。

终端 1：启动预览

1
2
3
4
5
# 创建一个空白演示文稿
officecli create deck.pptx

# 启动实时预览（浏览器会自动打开 http://localhost:26315）
officecli watch deck.pptx

终端 2：添加并修改内容

1
2
3
4
5
6
7
# 添加一张标题幻灯片
officecli add deck.pptx / --type slide --prop title="Q4 报告" --prop background=1A1A2E

# 添加一个形状（文本框）
officecli add deck.pptx '/slide[1]' --type shape \
  --prop text="营收增长 25%" --prop x=2cm --prop y=5cm \
  --prop font=Arial --prop size=24 --prop color=FFFFFF

此时，您打开的浏览器预览页面会自动刷新，显示新添加的幻灯片和内容。

2. 其他核心命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 查看文档大纲（纯文本结构）
officecli view deck.pptx outline

# 查看文档的 HTML 渲染结果
officecli view deck.pptx html

# 将某张幻灯片导出为 PNG 截图
officecli view deck.pptx screenshot -o slide_1.png --page 1

# 获取文档中某个元素的结构化信息
officecli get deck.pptx '/slide[1]/shape[1]' --json

# 保存并关闭文档（刷新到磁盘）
officecli close deck.pptx

AI 智能体集成

OfficeCLI 提供了两种与 AI 助手集成的方式。

方式一：通过 MCP 服务器（推荐）

OfficeCLI 内置了 MCP（模型上下文协议）服务器，可以将所有文档操作作为工具暴露给支持 MCP 的 AI 客户端。

注册 MCP 服务器：

1
2
3
4
5
6
7
8
9
10
11
# 为 Claude Code 注册
officecli mcp claude

# 为 Cursor 注册
officecli mcp cursor

# 为 VS Code / Copilot 注册
officecli mcp vscode

# 查看注册状态
officecli mcp list

注册后，您就可以在 AI 助手（如 Claude Desktop）的配置中使用它，或在支持 MCP 的编辑器中直接调用 OfficeCLI 工具。

方式二：通过 SKILL.md 文件（通用）

您可以将 OfficeCLI 的使用说明书提供给任何 AI 助手。

1. 获取技能文件

1
2
# 直接输出 SKILL.md 内容
curl -fsSL https://officecli.ai/SKILL.md

2. 安装为 Claude Code 技能

1
curl -fsSL https://officecli.ai/SKILL.md -o ~/.claude/skills/officecli.md

3. 用于其他 AI 助手：将 SKILL.md 的内容粘贴到系统提示词或工具描述中。安装后，AI 就学会了所有命令。

安装后的自动化流程：
OfficeCLI 会自动检测您机器上的 AI 工具（Claude Code, Cursor, Windsurf等），并尝试自动配置。当您在 AI 对话中提出文档相关的需求时，AI 会自动调用 OfficeCLI 命令来完成。

高级功能与工作流

模板合并 (merge)

让 AI 设计好模板，然后在批量生成时填充数据，避免重复消耗 token。

1
2
# 使用 JSON 数据替换模板中的 {{key}} 占位符
officecli merge invoice-template.docx invoice-001.docx --data '{"client":"Acme Inc.","total":"$5,200"}'

转储与回放 (dump / batch)

AI 可以从一个现有的好文档中“学习”结构，然后批量生成变体。

1
2
3
4
5
# 1. 将现有文档的结构 dump 为 JSON 蓝图
officecli dump existing-report.docx -o blueprint.json

# 2. 微调 JSON 后，批量回放生成新文档
officecli batch new-report.docx --input blueprint.json

批量操作 (batch)

将多个修改打包成一次原子操作，失败会自动回滚。

1
2
3
# 通过 stdin 传入 JSON 指令
echo '[{"command":"set","path":"/slide[1]/shape[1]","props":{"text":"New Text"}}, {"command":"add","parent":"/","type":"slide"}]' \
  | officecli batch deck.pptx --json

使用 SDK（Python / Node.js）

对于复杂集成，可以使用官方 SDK，它通过管道通信，避免了重复启动进程的开销。

Python：

1
2
3
import officecli
with officecli.open("report.docx") as doc:
    doc.send({"command": "set", "path": "/body/p[1]/r[1]", "props": {"bold": True}})

Node.js：

1
2
3
4
const oc = require("@officecli/sdk");
const doc = await oc.open("report.docx");
await doc.send({ command: "set", path: "/body/p[1]/r[1]", props: { bold: true } });
await doc.close();

更新与卸载

更新 OfficeCLI

1
2
3
4
5
6
7
# 自动更新（默认启用）
officecli install

# 或通过包管理器更新
brew upgrade officecli          # Homebrew
scoop update officecli          # Scoop
npm update -g @officecli/officecli # npm

卸载 OfficeCLI

1
2
3
4
# 删除二进制文件（并移除 PATH 条目）
officecli uninstall

# 如果使用包管理器，通过对应方式卸载

常见问题排查

问题：安装后 officecli 命令找不到。

  • 解决：确保安装脚本将二进制放入了 PATH。可以手动将安装目录（通常是 ~/.officecli/bin）添加到 PATH 中。

问题：AI 助手无法调用 OfficeCLI。

  • 解决：
    1. 确认二进制已安装且可执行：officecli --version。
    2. 检查 MCP 注册状态：officecli mcp list。
    3. 对于 Claude Code，确认 ~/.claude/skills/officecli.md 文件存在。

问题：officecli watch 预览没有自动刷新。

  • 解决：确保所有修改命令都针对同一个文件路径执行。预览服务会监听文件变化。

问题：中文或其他语言内容显示异常。

  • 解决：OfficeCLI 支持全面的国际化（i18n）和从右至左（RTL）书写。创建文档时可指定区域设置：officecli create document.docx --locale zh-CN。

通过以上步骤，您应该能成功部署并开始使用 OfficeCLI。这个工具将赋予您的 AI 助手强大的办公文档处理能力，是自动化报告生成、内容制作和文档工作流的利器。如需了解更多高级用法，请查阅项目 Wiki 或使用内置帮助：officecli help。