OfficeCLI — AI 原生的 Office 命令行技能
概述
OfficeCLI（github.com/iOfficeAI/OfficeCLI，Apache 2.0）是专为 AI 智能体设计的 Office 套件：单一自包含二进制（.NET 运行时内嵌），无需安装 Microsoft Office、零外部依赖，跨 macOS / Linux / Windows 运行。它把 Word/Excel/PowerPoint 的完整操作封装为 CLI，并内置高保真 HTML 渲染引擎，支持 view html / view screenshot / watch 三种渲染模式，让智能体"看到"排版效果而非盲改。
采用三层架构，始终优先使用更高层：
- L1 读取视图：
view（outline/text/annotated/stats/issues/html/screenshot）、get、query、validate - L2 DOM 操作：
set、add、move、swap、remove、batch - L3 原始 XML：
raw、raw-set、add-part（仅当 L2 无法表达时使用）
何时使用本技能
- 从零创建 .docx / .xlsx / .pptx（本机无 Office 或需要 headless/CI 环境）
- 读取、检查既有文档：结构、文本、格式问题、公式、图表
- 批量修改文档：查找替换、批量设格式、模板合并（
{{key}}占位符）、CSV 导入 - 需要视觉验证排版效果时：渲染成 HTML/PNG 后查看，再决定修复项
- 交付前质检：
validate+view issues
与其他本地 Office 技能的分工：本技能侧重程序化批量操作与渲染验证闭环；文档排版美化类交付（如生成面向客户的精排 Word）仍走对应 Office 交付技能，两者可接力使用。
安装与自检
未安装时按平台安装一行命令：
# Windows（PowerShell）
irm https://d.officecli.ai/install.ps1 | iex
# 备用：irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex
# macOS / Linux
curl -fsSL https://d.officecli.ai/install.sh | bash
# 备用：curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash
# 包管理器（任选其一）
brew install officecli # macOS / Linux
scoop install officecli # Windows
npm install -g @officecli/officecli # 全平台（自动拉取对应平台原生二进制）
安装后必须验证：执行 officecli --version。Windows 上若提示命令未找到，先开一个新终端（PATH 未刷新），或直接调用安装目录下的 officecli.exe。
也可运行本技能自带的自检脚本：scripts/check-install.sh（自动探测 PATH 与常见安装位置并输出版本号）。
更新与配置：默认后台自动更新；officecli config autoUpdate false 关闭；单次跳过设环境变量 OFFICECLI_SKIP_UPDATE=1；配置文件位于 ~/.officecli/config.json。
核心工作流
1. 先查帮助，严禁猜测属性名
officecli help # 全部命令 + 全局选项
officecli help pptx # 列出 pptx 全部元素类型
officecli help pptx set shape # shape 在 set 下的全部可设属性
officecli help docx query # 选择器语法参考
格式别名：word→docx，excel→xlsx，ppt/powerpoint→pptx。
2. 创建与读取
officecli create deck.pptx # 按扩展名创建空白文档
officecli view deck.pptx outline # 结构大纲
officecli view report.docx text --max-lines 50 # 纯文本（xlsx 可加 --cols A,B,C）
officecli view report.docx annotated # 带格式注释的文本
officecli view report.docx issues --json # 格式/内容/结构问题清单
officecli get slides.pptx '/slide[1]' --depth 1 --json # 结构化读取某节点
officecli query report.docx "paragraph[style=Heading1]" --json
3. 修改（L2）
# 添加元素：所有属性一律走 --prop
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 add report.docx /body --type paragraph --prop text="Executive Summary" --prop style=Heading1
# 设属性/格式（点号别名可用：--prop font.color=red --prop font.bold=true）
officecli set report.docx '/body/p[1]/r[1]' --prop bold=true
# 查找替换（支持正则；/ 表示全文范围）
officecli set report.docx / --find draft --replace final
officecli set doc.docx '/body/p[1]' --find '\d+%' --prop regex=true --prop color=red
# 移动 / 交换 / 删除 / 克隆
officecli move report.docx /body/p[5] --to /body --index 1
officecli swap deck.pptx '/slide[1]' '/slide[2]'
officecli remove report.docx '/body/p[4]'
officecli add deck.pptx / --from '/slide[1]' # 克隆整页
# Excel 单元格与透视表
officecli set data.xlsx /Sheet1/A1 --prop value="Name" --prop bold=true
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'
# 模板合并
officecli merge invoice-template.docx out-001.docx --data '{"client":"Acme","total":"$5,200"}'
4. 批量操作（batch，默认原子回滚）
officecli batch deck.pptx --commands '[{"op":"set","path":"/slide[1]/shape[1]","props":{"text":"Hi"}}]' --json
echo '[{"command":"set","path":"/Sheet1/A1","props":{"value":"Name"}}]' | officecli batch data.xlsx --json
默认原子性：任一项失败整批回滚（磁盘文件保持原样）。需要"保留成功项"时加 --best-effort；--stop-on-error 改为遇错即停。
5. 渲染验证闭环（本技能标志性能力）
officecli view deck.pptx html -o /tmp/deck.html # 静态 HTML 快照
officecli view deck.pptx screenshot -o /tmp/deck.png # 每页 PNG（--page N 指定页）
officecli view report.docx html --page 2 # docx 指定页
流程：渲染 → 读取图片/HTML 检查排版 → set 修复 → 重新渲染对比。交付前务必执行：
officecli validate report.docx && officecli view report.docx issues --json
watch（http://localhost:26315 实时刷新）面向人工交互场景，智能体自动化优先用一次性 html / screenshot 模式。
6. 常驻模式与落盘时机
首次访问文件时自动启动常驻实例（60s 空闲超时）；长会话建议显式管理：
officecli open report.docx # 载入内存
officecli set report.docx ... # 零 I/O 开销连续操作
officecli close report.docx # 保存并释放
仅在"非 officecli 程序要读文件"前才需要 flush（save 保留常驻 / close 保存并释放）：python-docx、openpyxl、Word/WPS 打开、渲染交付、上传之前。officecli 自身的读取命令始终看到最新修改，中途无需保存。
专门技能（按文档类型加载）
officecli load_skill word # 通用文档：报告、信函、备忘录、方案
officecli load_skill academic-paper # 学术论文（APA/Chicago/IEEE/MLA、参考文献）
officecli load_skill pptx # 通用演示文稿
officecli load_skill pitch-deck # 仅融资路演（seed~C 轮）
officecli load_skill morph-ppt # Morph 动画演示
officecli load_skill excel # 通用工作簿
officecli load_skill financial-model # 财务模型
officecli load_skill data-dashboard # 数据看板
规则：按最匹配场景加载一个；已加载规则跨轮次有效，不要每轮重复加载；一个产物一个技能，不要叠加。
关键陷阱（必读）
| 陷阱 | 正确做法 |
|---|---|
--name "foo" |
所有属性一律 --prop name="foo" |
| bash/zsh 中路径不写引号 | 含 [N] 的路径必须引号包裹：'/slide[1]' |
PPT 用 shape[1] 放正文 |
shape[1] 通常是标题占位符，正文用 shape[2]+ |
| 猜属性名 | 先 officecli help <fmt> <element> |
| 修改正被 Office/WPS 打开的文件 | 先关闭再改 |
--prop text="$15M" |
$ 被 shell 吞掉，用单引号 --prop text='$15M' |
--prop text="a\nb" |
换行写 \\n |
| 路径/索引基数混淆 | 元素路径 1 起（/body/p[3]=第3段）；--index 0 起；Excel 的 add --type row/col 例外，--index 1 起 |
| batch 失败想保留部分结果 | 加 --best-effort |
Windows 特别说明
- 安装走 PowerShell 的
irm ... | iex；二进制为officecli.exe - 在 Git Bash 中调用时路径用正斜杠或加引号：
officecli view "D:/work/deck.pptx" html - 安装后先开新终端刷新 PATH；自检脚本
scripts/check-install.sh可帮助定位二进制 raw-set等 L3 操作无需手写 xmlns 声明，前缀自动注册- MCP 集成（供 Claude Code / Cursor / VS Code 等使用）：
officecli mcp claude/cursor/vscode/lmstudio/opencode；本环境直接走 CLI 即可
资源文件
references/cli-reference.md— 完整命令参考：view 各模式详解、get/query 选择器、set/add 值格式、batch JSON schema、dump/refresh 往返、L3 raw XML、watch 交互、MCP、专门技能明细。命令细节记不清时读取此文件。scripts/check-install.sh— 安装自检脚本：探测 PATH 与常见安装位置，输出版本号；未安装时给出对应平台的安装命令。
