OfficeCLI 技术指南：面向 AI 代理的 Word/Excel/PowerPoint 自动化命令行套件

OfficeCLI 是一个专为 AI 代理设计的开源 Office 套件，以单一自包含二进制文件提供对 .docx、.xlsx、.pptx 的创建、读取、分析与修改能力，无需安装 Microsoft Office、无运行时依赖、跨平台可运行。本文以项目官方文档 README_ko.md 为主线，结合仓库源码，系统讲解其安装方式、命令体系、内建渲染/公式/透视表引擎、常驻与批处理模式、三层架构以及面向 AI 的 MCP 集成与结构化 JSON 输出，读者读完后即可用一条命令替代数十行脚本，搭建"渲染 → 查看 → 修复"的自动化文档流水线。

项目定位：给 AI 一双"眼睛"的 Office 套件

OfficeCLI 的核心设计目标非常明确：让任何 AI 代理以一行代码获得对 Word、Excel、PowerPoint 的完整控制权。它的产品特性可以概括为：

• 开源，采用 Apache 2.0 许可证（见 LICENSE）；
• 单二进制，.NET 运行时内嵌，无需额外安装任何运行时；
• 无需 Office，所有能力随二进制内置；
• 零依赖，可在所有主流平台运行；
• 内置高保真 HTML 渲染引擎——这正是它给 AI"眼睛"的关键：将 .docx / .xlsx / .pptx 渲染为 HTML 或 PNG，从而闭环"渲染 → 查看 → 修复"循环。

仓库源码 src/officecli/Program.cs 印证了这款 CLI 的设计取向：它对 UTF-8 输出做了跨平台处理（管道/文件重定向时使用自研 UTF-8 写入器，终端场景临时切换代码页并在退出时还原），并将进程级文化固定为 Invariant，确保 OOXML、JSON、CSS 中始终使用 . 作为小数分隔符，避免 nl-NL、de-DE、fr-FR 等区域设置下输出 141,73pt 或 0,5 之类的歧义值——这是机器可消费输出的关键基础。

安装与获取

一行安装

原文档给出的官方安装方式是直接管道执行安装脚本：

# 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

这两个脚本就在仓库根目录：install.sh 与 install.ps1。阅读 install.sh 可以看到安装器的几个工程细节：

• 镜像优先、GitHub 回退：主源 d.officecli.ai 超时（5 秒连接超时）后自动回退到 GitHub Releases；
• 版本解析：先通过 /releases/latest 重定向解析出不可变的版本化下载路径，避免 CDN 缓存（最长 4 小时）导致刚发布后下载到旧二进制；
• SHA256 校验：下载 SHA256SUMS 清单并按文件名精确列匹配校验；
• 原子替换：先以 .new 后缀暂存、签名、再 mv 覆盖，避免覆盖正在运行的二进制；
• macOS 兼容：清除 quarantine 属性，并在签名缺失时进行 ad-hoc 签名，确保 Apple Silicon 可执行；
• AI 技能自动安装：首次安装时自动检测 ~/.claude（Claude Code）、~/.copilot（GitHub Copilot）、~/.agents（Codex CLI）、~/.cursor（Cursor）、~/.windsurf（Windsurf）等已知配置目录，若存在则将 SKILL.md 安装进对应技能的 officecli 子目录。

包管理器安装

# Homebrew (macOS / Linux)
brew install officecli

# Scoop (Windows)
scoop install officecli

# npm (所有平台——安装时拉取对应平台的原生二进制)
npm install -g @officecli/officecli

npm 包的配置见 npm/package.json：postinstall 钩子执行 npm/install.js 下载平台对应的原生二进制，bin 字段将 officecli 命令指向 npm/officecli.js。

手动下载与自安装

也可以从官方 Releases 手动下载对应平台的二进制：

平台	二进制文件名
macOS Apple Silicon	officecli-mac-arm64
macOS Intel	officecli-mac-x64
Linux x64	officecli-linux-x64
Linux ARM64	officecli-linux-arm64
Windows x64	officecli-win-x64.exe
Windows ARM64	officecli-win-arm64.exe

安装完成后用 officecli --version 验证。若直接运行下载的二进制，也会触发自安装：

officecli install    # 显式安装
officecli            # 裸调用同样会触发安装

对应地，src/officecli/Program.cs 中 install 命令与 MaybeAutoInstall 逻辑会在运行于非默认位置时将自身复制到 ~/.local/bin。

更新与配置

更新在后台自动检查；可用 officecli config autoUpdate false 关闭，或用环境变量 OFFICECLI_SKIP_UPDATE=1 跳过单次检查。配置保存在 ~/.officecli/config.json。

30 秒快速体验：创建、实时预览、添加内容

原文档提供了一个开发者视角的快速演示：安装后立刻体验"浏览器即实时反馈环"。

# 1. 安装（macOS / Linux）——或：brew install officecli / npm install -g @officecli/officecli
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

# 2. 创建空白 PowerPoint
officecli create deck.pptx

# 3. 启动实时预览——浏览器打开 http://localhost:26315
officecli watch deck.pptx

# 4. 另开一个终端，添加幻灯片——浏览器立即更新
officecli add deck.pptx / --type slide --prop title="Hello, World!"

watch 的默认端口 26315 在源码 src/officecli/CommandBuilder.Watch.cs 中直接定义：watchPortOpt.DefaultValueFactory = _ => 26315;。此后每次执行 add、set、remove 命令，预览都会实时刷新，浏览器就是你的活体反馈环。

快速上手：一条命令替代五十行脚本

完整命令示例

# 创建演示文稿并添加内容
officecli create deck.pptx
officecli add deck.pptx / --type slide --prop title="Q4 Report" --prop background=1A1A2E
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

# 查看大纲
officecli view deck.pptx outline
# → Slide 1: Q4 Report
# →   Shape 1 [TextBox]: Revenue grew 25%

# 以 HTML 查看——无需服务器，在浏览器中打开渲染后的预览
officecli view deck.pptx html

# 获取任意元素的结构化 JSON
officecli get deck.pptx '/slide[1]/shape[1]' --json

get --json 的返回示例：

{
  "tag": "shape",
  "path": "/slide[1]/shape[1]",
  "attributes": {
    "name": "TextBox 1",
    "text": "Revenue grew 25%",
    "x": "720000",
    "y": "1800000"
  }
}

注意 x、y 返回的是原始 EMU 单位（720000 EMU = 2cm，1800000 EMU = 5cm），底层存储与渲染单位保持一致。

对比：传统方式 vs 一条命令

原文档用一个典型案例说明价值——过去需要约 50 行 Python 和 3 个库：

from pptx import Presentation
from pptx.util import Inches, Pt
prs = Presentation()
slide = prs.slides.add_slide(prs.slide_layouts[0])
title = slide.shapes.title
title.text = "Q4 Report"
# ... 另外 45 行 ...
prs.save('deck.pptx')

现在只需一条命令：

officecli add deck.pptx / --type slide --prop title="Q4 Report"

能力总览与格式支持

OfficeCLI 的能力可归纳为五类：

• 创建（Create）——从零生成空白或带内容的文档；
• 读取（Read）——读取文本、结构、样式、公式，支持纯文本或结构化 JSON；
• 分析（Analyze）——检查格式问题、样式不一致与结构缺陷；
• 修改（Modify）——修改任意元素：文本、字体、颜色、布局、公式、图表、图片；
• 重组（Reorganize）——添加、删除、移动元素，甚至在文档间复制内容。

三种格式的读写改支持矩阵：

格式	读取	修改	创建
Word (.docx)	✅	✅	✅
Excel (.xlsx)	✅	✅	✅
PowerPoint (.pptx)	✅	✅	✅

各格式的能力覆盖（原文档逐一列出，此处整理为要点）：

• Word：完整 i18n 与 RTL 支持（按脚本的字体槽、lang.latin/ea/cs 语言标签、复杂脚本粗体/斜体/字号、贯穿段落/运行/节/表格/样式/页眉页脚/docDefaults 的 direction=rtl、rtlGutter + pgBorders 简写、印地语/阿拉伯语/泰语/CJK 区域感知页码），以及段落、运行、表格、样式、页眉/页脚、图片（PNG/JPG/GIF/SVG）、公式、批注、脚注、水印、书签、目录、图表、超链接、节、表单字段、内容控件（SDT）、字段（22 种零参数类型 + MERGEFIELD / REF / PAGEREF / SEQ / STYLEREF / DOCPROPERTY / IF）、OLE 对象、文档属性等；
• Excel：单元格（添加时支持注音/振假名）、公式（150+ 内置函数自动计算，动态数组自动加 _xlfn. 前缀）、工作表（visible/hidden/veryHidden、打印边距、printTitleRows/Cols、RTL sheetView、级联感知的重命名）、表格、排序（工作表/区域、多关键字、sidecar 感知）、条件格式、图表（箱线图、帕累托自动排序 + 累计%、对数轴）、透视表（多字段、日期分组、showDataAs、排序、总计、小计、紧凑/大纲/表格布局、重复项标签、空行、计算字段）、切片器、名称范围、数据验证、图片（PNG/JPG/GIF/SVG 双表示回退）、迷你图、批注（RTL）、自动筛选、形状、OLE 对象、CSV/TSV 导入、$Sheet:A1 单元格寻址；
• PowerPoint：幻灯片（页眉/页脚/日期/幻灯片编号开关、隐藏）、形状（图案填充、模糊效果、超链接工具提示 + 幻灯片跳转链接）、图片（PNG/JPG/GIF/SVG，填充模式 stretch/contain/cover/tile、亮度/对比度/光晕/阴影）、表格、图表、动画、变形切换、3D 模型（.glb）、幻灯片缩放、公式、主题、连接线、视频/音频、组合、备注（RTL、lang）、批注（RTL）、OLE 对象、占位符（按 phType 添加/设置）。

核心引擎与生成原语

原文档强调：OfficeCLI 完全自包含，以下能力全部内置在二进制中，不需要 Office。

内建高保真渲染引擎

这是 OfficeCLI 的基石：从头实现的高保真 HTML 渲染引擎，让 AI 代理"看到"渲染后的文档而不是从 DOM 猜测。它覆盖形状、图表（趋势线、误差线、瀑布、蜡烛图、迷你图）、公式（OMML → LaTeX，经 KaTeX 渲染）、经 Three.js 渲染的 3D .glb 模型、变形切换、幻灯片缩放与形状效果。逐页 PNG 截图则通过把渲染后的 HTML 送入无头浏览器捕获生成。三种使用模式：

• view html——独立 HTML 文件，资源内联，可在任意浏览器打开；
• view screenshot——逐页 PNG，供多模态代理阅读；
• watch——本地 HTTP 服务器 + 自动刷新预览，每次 add / set / remove 即时更新浏览器。Excel 的 watch 还支持内联单元格编辑与拖拽重排图表。

officecli view deck.pptx html -o /tmp/deck.html
officecli view deck.pptx screenshot -o /tmp/deck.png # 更多页用 --page 1-N
officecli watch deck.pptx                            # http://localhost:26315

原文档特别点出：没有可视化，生成幻灯片的代理就是在盲目飞行——它能读 DOM，却无法判断标题是否溢出、两个形状是否重叠。因为渲染内置在二进制里，"渲染 → 查看 → 修复"循环在 CI、Docker、无显示器的服务器等任何二进制可运行的环境中都成立。

从源码结构看，渲染能力分布在 src/officecli/Core/HtmlPreviewHelper.cs（HTML 预览组装）、src/officecli/Core/HtmlScreenshot.cs（无头浏览器截图）与 src/officecli/Core/PowerPointPngBackend.cs（PPT 的 PNG 后端）中。

公式引擎与透视表引擎

公式引擎：350+ 内置 Excel 函数在写入时自动求值——写入 =SUM(A1:A2)，再 get 该单元格，值已经在那里，无需经 Office 重算往返。覆盖：

• 溢出的动态数组：FILTER / SORT / UNIQUE / SEQUENCE / LET / LAMBDA，自动加 _xlfn. 前缀；
• 查找类：VLOOKUP / XLOOKUP / INDEX / MATCH；
• 金融与债券函数（XIRR / PRICE / YIELD / DURATION / COUPNUM 等）；
• 统计分布、检验与回归（NORM.DIST / T.TEST / LINEST 等）；
• 日期与文本函数。

公式引擎的实现位于 src/officecli/Core/Formula/（目录下 17 个源文件）。

透视表引擎：从源区域一条命令生成原生 OOXML 透视表——多字段行/列/筛选、10 种聚合、showDataAs 模式、日期分组、计算字段、Top-N、多种布局。透视缓存 + 定义都会写入 OOXML，Excel 打开文件时聚合结果已就绪：

officecli add sales.xlsx '/Sheet1' --type pivottable \
  --prop source='Data!A1:E10000' --prop rows='Region,Category' \
  --prop cols=Quarter --prop values='Revenue:sum,Units:avg' \
  --prop showDataAs=percentOfTotal

透视表相关的实现分散在 src/officecli/Core/PivotTableHelper.cs 及其 Parse/Definition/Cache/Set/Render/Readback 配套文件中。

模板合并：一次设计，多次填充

merge 命令将任意 .docx / .xlsx / .pptx 中的 {{key}} 占位符替换为 JSON 数据——在段落、表格单元格、形状、页眉、页脚与图表标题中全范围生效。代理只设计一次布局（昂贵），生产代码填充 N 次（廉价、确定性、零 token 成本）。这避免了"代理每次从零重新生成报告、产生 N 个不一致布局"的失败模式。

officecli merge invoice-template.docx out-001.docx --data '{"client":"Acme","total":"$5,200"}'
officecli merge q4-template.pptx q4-acme.pptx --data data.json

Dump 往返：从现有文档学习

dump 将任意 .docx、.pptx、.xlsx——整个文档或任意子树（单个段落、表格、幻灯片、工作表，以及 styles、numbering、theme、settings 部件）——序列化为可重放的 batch JSON；batch 负责重放。给定一个用户希望模仿的样例文档，代理读取结构化规格（而非原始 OOXML XML），修改后重放。它架起了"我已有现成模板"与"帮我生成 100 个变体"之间的桥梁。

officecli dump existing.docx -o blueprint.json                  # 整个文档
officecli dump existing.docx /body/tbl[1] -o table.json         # 任意子树
officecli dump existing.xlsx /Sheet1 -o sheet.json              # 单个工作表
officecli batch new.docx --input blueprint.json

常驻模式与批处理

对多步骤工作流，常驻模式让文档驻留内存；批处理模式在一次 open/save 周期内执行多项操作。

# 常驻模式——经命名管道实现近乎零延迟
officecli open report.docx
officecli set report.docx /body/p[1]/r[1] --prop bold=true
officecli set report.docx /body/p[2]/r[1] --prop color=FF0000
officecli close report.docx

# 批处理模式——一次执行多条命令（默认原子：任一失败则整批回滚）
echo '[{"command":"set","path":"/slide[1]/shape[1]","props":{"text":"Hello"}},
      {"command":"set","path":"/slide[1]/shape[2]","props":{"fill":"FF0000"}}]' \
  | officecli batch deck.pptx --json

# 内联批处理——无需 stdin
officecli batch deck.pptx --commands '[{"op":"set","path":"/slide[1]/shape[1]","props":{"text":"Hi"}}]'

# 用 --force 跳过错误继续执行
officecli batch deck.pptx --input updates.json --force --json

--force 仅用于绕过 docx 保护；原子回滚语义下，失败项带有机器可读的 code 字段，整批回滚的 JSON 摘要会带有 "atomicRolledBack": true。

值得补充的是刷新时机：当另一个程序要读取文件时（python-docx/openpyxl、Word、渲染器、上传），应先执行 officecli save <file>（刷新磁盘但保持常驻）或 close（刷新并释放）。常驻空闲后也会自动刷新（自适应 2–10 秒，按文档实测保存成本缩放）。

三层架构：L1 → L2 → L3

从简单开始，只在必要时深入：

层	用途	命令
L1：读取	内容的语义视图	view（text、annotated、outline、stats、issues、html、svg、screenshot）
L2：DOM	结构化元素操作	get、query、set、add、remove、move、swap
L3：原始 XML	XPath 直接访问——通用回退	raw、raw-set、add-part、validate

# L1 —— 高层视图
officecli view report.docx annotated
officecli view budget.xlsx text --cols A,B,C --max-lines 50

# L2 —— 元素级操作
officecli query report.docx "run:contains(TODO)"
officecli add budget.xlsx / --type sheet --prop name="Q2 Report"
officecli move report.docx /body/p[5] --to /body --index 1

# L3 —— L2 不够时使用原始 XML
officecli raw deck.pptx '/slide[1]'
officecli raw-set report.docx document \
  --xpath "//w:p[1]" --action append \
  --xml '<w:r><w:t>Injected text</w:t></w:r>'

raw-set 的动作包括 append、prepend、insertbefore、insertafter、replace、remove、setattr。这套渐进式复杂度设计贯穿在 src/officecli/CommandBuilder.*.cs 的命令构建体系中。

AI 集成

内建 MCP 服务器

二进制内置 MCP 服务器，一条命令即可注册到主流 AI 工具：

officecli mcp claude       # Claude Code
officecli mcp cursor       # Cursor
officecli mcp vscode       # VS Code / Copilot
officecli mcp lmstudio     # LM Studio
officecli mcp list         # 查看注册状态

它通过 JSON-RPC 暴露所有文档操作，无需 shell 访问。其分发逻辑与服务器实现在 src/officecli/Program.cs、src/officecli/McpServer.cs 与 src/officecli/McpInstaller.cs 中。

直接 CLI 集成

两步接入任何 AI 代理：

1. 安装二进制——一条命令（见上文安装章节）；
2. 完成。 OfficeCLI 自动检测 AI 工具（Claude Code、GitHub Copilot、Codex 等）的已知配置目录并安装技能文件，代理立即可创建、读取、修改任意 Office 文档。

需要手动安装技能文件时，可把仓库根目录的 SKILL.md 内容喂给代理，或放入 ~/.claude/skills/。技能目录 skills/officecli/SKILL.md 及其专项技能（pitch-deck、morph-ppt、data-dashboard 等）可通过 officecli load_skill <name> 读取（只读、无安装副作用）。

为什么代理在 OfficeCLI 上表现出色

原文档给出了九条设计依据：

• 确定性 JSON 输出——每条命令支持 --json 且 schema 一致，无需正则解析、无需抓取 stdout；
• 基于路径的寻址——每个元素都有稳定路径（/slide[1]/shape[2]），代理无需理解 XML 命名空间即可遍历文档（OfficeCLI 语法：1-based 索引、元素本地名，不是 XPath）；
• 渐进式复杂度（L1 → L2 → L3）——代理从只读视图开始，升级到 DOM 操作，仅在必要时回退原始 XML，最大化节约 token；
• 自愈工作流——validate、view issues 与结构化错误码（not_found、invalid_value、unsupported_property）会返回建议与有效范围，代理无需人工介入即可自我纠正；
• 内建代理友好渲染引擎——view html / view screenshot / watch 原生输出 HTML 与 PNG，无需 Office，在 CI / Docker / 无头环境也能"看见"输出并修复布局问题；
• 内建公式与透视表引擎——写入时自动求值 350+ 函数；一条命令从源区域生成原生 OOXML 透视表，代理可立即读取计算值与聚合结果；
• 模板合并——代理设计一次布局，下游代码填充 {{key}} 占位符 N 次，避免每次重新生成报告烧掉 token；
• 往返 Dump——dump 将任意 .docx / .pptx / .xlsx 转为可重放 batch JSON，代理通过读结构化规格（而非原始 OOXML）向人工编写的样例学习；
• 自动安装——检测并自动配置 AI 工具，无需手动设置技能文件。

内建帮助系统

不确定属性名时不要猜，直接下钻帮助：

officecli help pptx set              # 所有可设置的元素与属性
officecli help pptx set shape        # 单个元素类型的详情
officecli help docx query            # 选择器参考：属性、:contains、:has() 等

格式名 pptx 可替换为 docx 或 xlsx；动词为 view、get、query、set、add、raw。officecli --help 给出完整总览。在 src/officecli/Program.cs 中，--help / -h / -? 会被统一重写为 help 命令，保证代理只看到一个帮助入口。

JSON 输出模式

所有命令支持 --json。常见响应形态：

单个元素（get --json）：

{"tag": "shape", "path": "/slide[1]/shape[1]", "attributes": {"name": "TextBox 1", "text": "Hello"}}

元素列表（query --json）：

[
  {"tag": "paragraph", "path": "/body/p[1]", "attributes": {"style": "Heading1", "text": "Title"}},
  {"tag": "paragraph", "path": "/body/p[5]", "attributes": {"style": "Heading1", "text": "Summary"}}
]

错误返回结构化错误对象，含错误码、修改建议与可用值：

{
  "success": false,
  "error": {
    "error": "Slide 50 not found (total: 8)",
    "code": "not_found",
    "suggestion": "Valid Slide index range: 1-8"
  }
}

错误码包括：not_found、invalid_value、unsupported_property、invalid_path、unsupported_type、missing_property、file_not_found、file_locked、invalid_selector。属性名支持自动纠错——拼错属性名会返回最近匹配的建议。

错误恢复——代理通过检查可用元素来自我纠正：

# 代理尝试无效路径
officecli get report.docx /body/p[99] --json
# 返回: {"success": false, "error": {"error": "...", "code": "not_found", "suggestion": "..."}}

# 代理检查可用元素后自我纠正
officecli get report.docx /body --depth 1 --json
# 返回可用子元素列表，代理据此选择正确路径

变更确认（set、add、remove、move、create 加 --json 时）：

{"success": true, "path": "/slide[1]/shape[1]"}

退出码语义：0 表示操作落地；1 表示未落地（进程或业务失败，信封携带 error）；2 表示带警告执行（如 unsupported_property 被丢弃，或校验器产生警告）——2 同时覆盖"带警告落地"（success: true）与"全部被拒"（success: false）两种情况，因此脚本必须读取信封中的 success 字段而非只看退出码；warnings[] 列出被丢弃的内容。MCP 服务器也按同一信封派生 isError。

方案对比

	OfficeCLI	Microsoft Office	LibreOffice	python-docx / openpyxl
开源且免费	✓ (Apache 2.0)	✗ (付费许可)	✓	✓
AI 原生 CLI + JSON	✓	✗	✗	✗
零安装（单二进制）	✓	✗	✗	✗ (需 Python + pip)
任意语言调用	✓ (CLI)	✗ (COM/插件)	✗ (UNO API)	仅 Python
基于路径的元素访问	✓	✗	✗	✗
原始 XML 回退	✓	✗	✗	部分支持
内建代理友好渲染引擎	✓	✗	✗	✗
无头 HTML/PNG 输出	✓	✗	部分支持	✗
跨格式模板合并（{{key}}）	✓	✗	✗	✗
Dump → batch JSON 往返	✓	✗	✗	✗
实时预览（编辑后自动刷新）	✓	✗	✗	✗
无头 / CI	✓	✗	部分支持	✓
跨平台	✓	Windows/Mac	✓	✓
Word + Excel + PowerPoint	✓	✓	✓	需多个库

命令参考

命令	说明
create	创建空白 .docx、.xlsx、.pptx（按扩展名判断类型）
view	查看内容（模式：outline、text、annotated、stats、issues、html）
get	获取元素及其子元素（--depth N、--json）
query	CSS 风格查询（[attr=value]、:contains()、:has() 等）
set	修改元素属性
add	添加元素（或 --from <path> 克隆）
remove	删除元素
move	移动元素（--to <parent>、--index N、--after <path>、--before <path>）
swap	交换两个元素
validate	按 OpenXML schema 校验
batch	一次 open/save 周期内执行多项操作（stdin、--input 或 --commands；默认首错即停，--force 继续）
merge	模板合并——用 JSON 数据替换 {{key}} 占位符
watch	浏览器中实时 HTML 预览，自动刷新
mcp	为 AI 工具集成启动 MCP 服务器
raw	查看文档部件的原始 XML
raw-set	通过 XPath 修改原始 XML
add-part	添加新文档部件（页眉、图表等）
open	启动常驻模式（文档驻留内存）
close	保存并退出常驻模式
install	安装二进制 + 技能 + MCP（all、claude、cursor 等）
config	读取或修改配置
help <format> <command>	内建帮助（例如 officecli help pptx set shape）

完整的命令构建与解析实现见 src/officecli/CommandBuilder.*.cs，帮助系统依据 schemas/help/ 下的结构化 schema（docx、pptx、xlsx 分目录）渲染。

端到端工作流示例

一个典型的代理自愈工作流：创建演示文稿、填充内容、校验、修复问题——全程无需人工介入。

# 1. 创建
officecli create report.pptx

# 2. 添加内容
officecli add report.pptx / --type slide --prop title="Q4 Results"
officecli add report.pptx '/slide[1]' --type shape \
  --prop text="Revenue: $4.2M" --prop x=2cm --prop y=5cm --prop size=28
officecli add report.pptx / --type slide --prop title="Details"
officecli add report.pptx '/slide[2]' --type shape \
  --prop text="Growth driven by new markets" --prop x=2cm --prop y=5cm

# 3. 校验
officecli view report.pptx outline
officecli validate report.pptx

# 4. 修复发现的问题
officecli view report.pptx issues --json
# 根据输出修复问题，例如：
officecli set report.pptx '/slide[1]/shape[1]' --prop font=Arial

单位与颜色

所有尺寸与颜色属性都接受灵活输入格式：

类型	支持格式	示例
尺寸	cm、in、pt、px 或原始 EMU	2cm、1in、72pt、96px、914400
颜色	十六进制、颜色名、RGB、主题色	#FF0000、FF0000、red、rgb(255,0,0)、accent1
字体大小	纯数字或 pt 后缀	14、14pt、10.5pt
间距	pt、cm、in 或倍数	12pt、0.5cm、1.5x、150%

常用模式与编程调用

常用命令组合

# 替换 Word 文档中所有 Heading1 文本
officecli query report.docx "paragraph[style=Heading1]" --json | ...
officecli set report.docx /body/p[1]/r[1] --prop text="New Title"

# 将全部幻灯片内容导出为 JSON
officecli get deck.pptx / --depth 2 --json

# 批量更新 Excel 单元格
officecli batch budget.xlsx --input updates.json --json

# 将 CSV 数据导入 Excel 工作表
officecli add budget.xlsx / --type sheet --prop name="Q1 Data"
officecli import budget.xlsx "/Q1 Data" sales.csv --header

# 模板合并批量生成报告
officecli merge invoice-template.docx invoice-001.docx --data '{"client":"Acme","total":"$5,200"}'

# 交付前检查文档质量
officecli validate report.docx && officecli view report.docx issues --json

从 Python / Node.js 调用

方式一：直接包装子进程——包一层，所有调用都返回解析后的 JSON：

import json, subprocess

def cli(*args):
    return json.loads(subprocess.check_output(["officecli", *args, "--json"], text=True))

cli("create", "deck.pptx")
cli("add", "deck.pptx", "/", "--type", "slide", "--prop", "title=Q4 보고서")
slide = cli("get", "deck.pptx", "/slide[1]")
print(slide["attributes"]["text"])

方式二：使用官方 SDK——仓库在 sdk/python/ 与 sdk/node/ 提供了轻量常驻管道 SDK。以 sdk/python/officecli.py 为例，它只做一件事：把命令转发给运行中的常驻进程的命名管道，send 单发、batch 多命令单次往返，热路径上无每次调用的进程启动开销：

import officecli
with officecli.create("deck.pptx") as doc:          # 或 officecli.open("deck.pptx")
    doc.send({"command": "add", "parent": "/", "type": "slide"})
    print(doc.send({"command": "get", "path": "/slide[1]"}))

Node 版对应 sdk/node/index.js，命令字典与 batch 列表完全一致，无第二套词汇。两个 SDK 在缺少 CLI 时会自动调用官方安装器，并在缺失时明确提示，而不是静默安装。SDK 协议与 src/officecli/Core/ResidentServer.cs / src/officecli/Core/ResidentClient.cs 保持一致：管道名 officecli-<SHA256(fullpath)[:16]>、单请求行 + 单响应行的 UTF-8 换行帧格式。

可运行示例与文档

仓库 examples/ 目录为三种格式提供了可直接复制运行的 .sh / .py 脚本与输出文件：examples/word/（段落格式、运行格式、表格、图表、域、修订等）、examples/excel/（单元格格式、图表 20+ 种、数据验证、透视表、切片器、迷你图等）、examples/ppt/（文本、形状、表格、图片、图表、动画、过渡、3D 模型、OLE 等）。专项技能文档见 skills/ 目录（morph-ppt、officecli-pptx、officecli-xlsx 等），插件协议见 plugins/plugin-protocol.md。

从源码构建

编译仅需 .NET 10 SDK；产物是自包含的原生二进制——.NET 已嵌入二进制，运行时无需安装。项目文件为 src/officecli/officecli.csproj。

./build.sh

许可

本项目采用 Apache License 2.0，完整第三方声明见 THIRD-PARTY-NOTICES.txt。