--- name: officecli description: 用 officecli 读写 .docx/.xlsx/.pptx——创建、读取、结构化查询、修改、模板批量填充、渲染截图。当用户要产出或修改 Word/Excel/PPT 文档、要从既有文档里取内容或查格式问题、要把研究结果交付成 Office 文件时用。兰台内经 MCP 工具 mcp__office__officecli 调用。 --- # officecli（兰台版） officecli 是单二进制 Office 套件（.docx/.xlsx/.pptx 读写 + 内置渲染引擎），无需安装 Office。 ## 1. 调用面（兰台） - 工具名 **`mcp__office__officecli`**，唯一参数 `command`： - **argv 数组**（推荐——含空格/引号/括号的值一律用数组形态）； - 或字符串命令行（一行 CLI，按 shell 规则切词）。 - 调用示例： ``` {"command": ["create", "报告.docx"]} {"command": ["add", "报告.docx", "/body", "--type", "paragraph", "--prop", "text=季度总结", "--prop", "style=Heading1"]} {"command": ["get", "数据.xlsx", "/Sheet1/A1", "--json"]} {"command": ["view", "汇报.pptx", "screenshot", "-o", "D:/tmp/p1.png", "--page", "1"]} ``` - 二进制缺席时工具会报未就绪/找不到命令：先 `{"command": "--version"}` 自检，别继续猜。 - 路径 **1-based**：`/slide[1]/shape[2]`、`/body/p[3]`、`/Sheet1/A1`。稳定 ID 形态更耐改：`/slide[1]/shape[@id=550950021]`、`/body/p[@paraId=1A2B3C4D]`。 ## 2. 兰台特有铁律（违反必出错，先读这段） 1. **落盘边界**：officecli 自己的读（`get`/`query`/`view`）总见最新编辑，但**兰台/别的程序读的是盘上字节**。凡是要让兰台回读（媒体预览、附件、交付、外部打开）或截图前，先 `save `（保 resident）或 `close `（落盘并释放）。 —— 简单记法：**每次要让别人看见结果之前，先 save。** 2. **模型看不到图**：`view screenshot` 返回的是图片内容块，兰台的工具结果契约只收文本 ⇒ **图会丢**。要看效果只能： - 落盘 `{"command": ["view", f, "screenshot", "-o", "<绝对路径>.png", "--page", "N"]}`，再 - `show_asset(kind='file', payload={filePath: '<该 png 绝对路径>', label: '第 N 页', ext: 'png'})` 给用户看； - 自己的自检用文本面：`validate` + `view issues` + `view text`。 3. **不要跑 `officecli install`**（它会往 ~/.claude、Cursor 等目录写技能/配置）；不要开启自动更新（兰台部署已设 `OFFICECLI_SKIP_UPDATE=1`）。 4. **别猜属性名**：不确定就跑 `help`（见 §4），一次 help 胜过多次失败重试。 5. **≥3 处修改用 `batch`**：一次开关、默认**原子回滚**（任一项失败则整批不落盘）。要"尽力而为"加 `--best-effort`。 6. Word/WPS 打开着目标文件时写入会 `file_locked`——请用户先关掉。 ## 3. 策略：L1 读 → L2 DOM → L3 裸 XML 优先高层，够用就别下沉： | 层 | 用途 | 命令 | |---|---|---| | **L1 读** | 理解文档结构/内容/问题 | `view`（modes：`text` `annotated` `outline` `stats` `issues` `html` `svg` `screenshot`）、`get`、`query`、`validate` | | **L2 DOM** | 改元素 | `set`、`add`、`remove`、`move`、`swap`、`batch` | | **L3 裸 XML** | L2 表达不了时的万能兜底 | `raw`、`raw-set`、`add-part` | 一切读命令加 `--json` 拿结构化输出（别去正则解析文本）。 ```bash view 报告.docx issues --json # 格式/内容/结构问题清单 view 汇报.pptx outline # 逐页大纲 get 数据.xlsx /Sheet1/B2 --json # 单元格（含公式求值结果） query 报告.docx 'paragraph[style=Heading1]' # CSS 式选择器，支持 :contains / and / or ``` ## 4. help 优先（不许猜） ```bash help # 全部命令与全局选项 help docx # 该格式可用的元素类型 help pptx set shape # 某元素的全部可设属性（动词过滤） help docx paragraph --json # 机器可读 schema ``` ## 5. 交付门槛（delivery gate —— 报告"做完了"之前逐条过） 1. **Schema**：`validate ` 干净； 2. **内容**：`view issues` 无溢出/格式/结构问题；并用 `view text` 扫残留占位符（`xxxx`、`lorem/ipsum`、``、`{{...}}`、`$VAR$`、空 `()`/`[]`）； 3. **视觉**：布局敏感（幻灯片尤其）要出图——按兰台铁律 2 落盘 PNG + `show_asset` 交给用户判；图渲染不出来就如实说"未经视觉验证"； 4. **落盘**：`save `（收尾必做，永不丢失、永不出错）。 **validate 通过 ≠ 可交付。** 逐格式的权威门槛在专项技能里（§6）。 ### 5.1 `view issues` 到底抓什么（逐类实测——这决定你还要自己查什么） **抓得到**（可信，别重复劳动）： | 类 | 实测输出 | |---|---| | docx 格式 | `[F1] Body paragraph missing first-line indent` + `Suggestion: …`（中文正文默认就报） | | pptx 几何 | `[O1] … extends 16.1cm past slide right edge`（形状甩出画布） | | pptx 溢出 | `[O2] text overflow: 39 lines at 40.0pt need 1872pt, usable 21pt. suggest.height=66.3cm`（**连改法都给**） | | xlsx 公式错 | `[F1] Formula error: #DIV/0!` / `[F2] Formula error: #VALUE!`（带 `Context:` 原文） | | xlsx 未求值 | `[U3] Formula written but not evaluated (no cachedValue, evaluator unsupported)`——写了求值器不认识的函数时，**单元格没有值**（Excel 打开才现算），别以为写进去了 | **抓不到**（实测盲区——**这些必须你自己查或交人判**）： | 盲区 | 自检动作 | |---|---| | **占位符残留**（docx 与 pptx 都不报 `{{x}}`/``/`xxxx`） | 必扫 `view text`——**这一步是承重的，不是保险**；`merge` 的失败形态就是静默留下 `{{key}}` | | **图片缺 alt 文本**（issues 不报） | `query 'picture:no-alt'`（docx 也可 `image:no-alt`）——命中即无 alt，自己补 | | **空白内容**（空文档/空段落/空标题页 → 0 issues，`validate` 也过） | 只能靠人判（截图 + `view outline`/`text` 看有没有内容）；**"干净"不等于"有东西"** | > 结论：**机械正确性交给 validate + issues；内容存在性与占位符残留必须自己扫；视觉效果交人判。** 三层各管一段，谁都替代不了谁。 ## 6. 专项技能（按需加载，一次一个，别叠加） ``` {"command": ["load_skill", "word"]} # 或 pptx / excel / academic-paper / ... {"command": ["load_skill"]} # 不带名 = 列出全部 ``` | 场景 | 加载 | |---|---| | 研报 / 论文 / 学术报告（引用、公式、交叉引用、多栏） | `academic-paper` | | 通用 Word（报告、信函、备忘录、方案） | `word` | | **可填写表单**（内容控件 SDT / 表单域 / 邮件合并 / 文档保护） | `word-form` | | 通用幻灯片（汇报、评审、发布） | `pptx` | | 融资路演 | `pitch-deck` | | 动效 / Morph / 3D 演示 | `morph-ppt` / `morph-ppt-3d` | | 通用表格、公式、透视 | `excel` | | 财务模型 / 预测 | `financial-model` | | 数据看板（CSV → KPI/图表） | `data-dashboard` | **实测体量（本机逐个量过）**：25–65 KB —— `morph-ppt-3d` 25.2 / `data-dashboard` 28.7 / `excel` 34.4 / `word` 41.8 / `pptx` 43.6 / `academic-paper` 44.4 / `word-form` 46.1 / `financial-model` 46.7 / `morph-ppt` 47.8 / **`pitch-deck` 64.9（最大，≈1.6 万 token）**。 ⇒ **一件产物只加载一个**（规则加载后持续有效，别每轮重载）；`pitch-deck` 这类大件尤其别顺手多载。 部分技能**自带参考文件**（`morph-ppt` 实测带 7 个）：正文末尾会给清单， 用 `{"command": ["load_skill", "<名>", "--path", ""]}` 单独取一份——比整篇重载省得多。 ## 7. 三条高频工作流（兰台场景） ### 7.1 卷/研究结果 → 交付物 **新建的 .docx 里只有 `Normal` 一个样式**（实测）——直接在段落上写 `style=Heading1` 会有警告 `style 'Heading1' not found in styles part`。要用的样式**先定义再加**，一次 `batch` 建骨架： ``` {"command": ["create", "报告.docx"]} {"command": ["batch", "报告.docx", "--commands", "[{\"command\":\"add\",\"parent\":\"/styles\",\"type\":\"style\",\"props\":{\"id\":\"Heading1\",\"name\":\"heading 1\",\"type\":\"paragraph\",\"basedOn\":\"Normal\"}},{\"command\":\"add\",\"parent\":\"/body\",\"type\":\"paragraph\",\"props\":{\"text\":\"季度研究报告\",\"style\":\"Heading1\"}},{\"command\":\"add\",\"parent\":\"/body\",\"type\":\"paragraph\",\"props\":{\"text\":\"本季度收入同比增长 25%。\"}}]", "--json"]} {"command": ["validate", "报告.docx"]} {"command": ["view", "报告.docx", "issues"]} ``` - **中文正文必须设首行缩进**：默认 `view issues` 会报 `[F1] Body paragraph missing first-line indent`（validate 却是干净的——**validate 通过 ≠ 可交付**）。 修复：`{"command": ["set", f, "/body/p[2]", "--prop", "firstLineChars=200"]}`（`firstLineChars` 是 **1/100 字符**单位，200 = 2 字符；也可用 `firstLineIndent=0.85cm`）。 - `batch` 的 `--commands` 参数是一整串 JSON——**必须用 argv 数组形态**传，字符串形态会被引号地狱撕碎。 - 回执里读 `data.summary.succeeded/failed` 判成败（默认原子：任一项失败整批回滚）。 - `save` 幂等，回执两种形态：`Saved x` / `x is already saved to disk.`（命令间隙可能已自动落盘）。 ### 7.2 模板 → 批量交付（先学样张，再灌数据） ```bash dump 用户给的样张.docx -o blueprint.json # 结构化蓝图（不是裸 XML），可读可改 batch 新件.docx --input blueprint.json # 回放；失败默认整批回滚 merge 发票模板.docx 出-001.docx --data '{"client":"Acme","total":"¥5,200"}' ``` **实测口径（可当验收判据）**：一份「样式 + 标题 + 正文 + 表格」的 docx，`dump` 出来是**细粒度项集** （本机实测 16 项，非 4 项），回放到新件 `succeeded: 16 / failed: 0`，`view text` 三处内容与表格都在、 `validate` 干净；`merge` 回执带 `Replaced keys: N`（本例 2），成品里不再有 `{{`。 → 模板流的正确姿势：**样式与版式设计一次（贵）→ dump 存蓝图 → 数据灌 N 次（便宜、确定性）**。 ⚠️ **`merge` 的失败形态是静默的**：`{{key}}` 没被替换时工具不报错、`view issues` 也不报（见 §5.1 盲区） ——**灌完必须扫一遍 `view text` 确认没有 `{{`**，否则交付物里会带着模板记号出门。 ### 7.3 既有文档注疏 → 回写（Word 原生批注 + 修订痕迹） ``` {"command": ["view", "来文.docx", "text"]} # 先读（或 annotated 带格式读） {"command": ["add", "来文.docx", "/body/p[1]", "--type", "comment", "--prop", "text=口径需与附件核对"]} {"command": ["set", "来文.docx", "/body/p[2]/r[1]", "--prop", "revision.type=ins", "--prop", "revision.author=兰台"]} {"command": ["get", "来文.docx", "/comments", "--json"]} # 批注读回（锚点/作者/时间都在） {"command": ["query", "来文.docx", "revision", "--json"]} # 修订读回（含 nativePath） {"command": ["set", "来文.docx", "/body/p[2]/ins[1]", "--prop", "revision.action=accept"]} ``` - **批注**锚在段落/元素上；读回用 `get /comments` 或 `query comment`（`query comment[@author=…]` 可筛）。 ⚠️ `view annotated` **不显示批注**（实测只给正文 + 格式），别用它验批注。 - **修订**：run 宿主上 `revision.author` **必须与 `revision.type=ins|del|format|moveFrom|moveTo` 成对** （只有 author 会被拒——那会写出空快照 `rPrChange`，等于记录了一个不存在的改动）。 - **接受/拒绝修订**用 **native path**（`/body/p[N]/ins[1]`，`query revision --json` 的 `format.revision.nativePath` 给出宿主位置），**不是** `set /revision[@id=…]`，也不是 `set /` （后者对 revision.action 会报 `Malformed path '/'`）。按作者批量：`set '/revision[@author=兰台]' …`。 - 批注与修订是两条互不干扰的通道：接受修订不动批注。 - **一个 run 同时只能挂一个修订**：重复挂会报 `run is already inside a track-change wrapper; accept/reject the existing revision first` ——要同时表达"改前→改后"，用 `revision.type=format` 或分别落在不同 run 上（实测）。 - **⚠️ 读数陷阱（实测，容易误判整篇文档）**：**待决删除的文本在 `view text` 里不出现** （那一段看起来是空的），而在 `view annotated` 里**照常显示、且不标注**它处于修订态 ——两个读数面都不告诉你"这里有未决修订"。**判定修订状态只有一个真源：`query revision`** （回 `revision.type` / `revision.author` / `nativePath`）。读一份带修订的来文时先跑它， 否则你会以为某段不存在（其实是待决删除）、或以为某段是原文（其实挂着修订）。 ### 7.4 xlsx 数据面（公式 / 透视 / CSV 进表） ``` {"command": ["create", "数据.xlsx"]} {"command": ["set", "数据.xlsx", "/Sheet1/A1", "--prop", "value=Region", "--prop", "bold=true"]} {"command": ["set", "数据.xlsx", "/Sheet1/B4", "--prop", "value==SUM(B2:B3)"]} {"command": ["add", "数据.xlsx", "/Sheet1", "--type", "pivottable", "--prop", "source=Sheet1!A1:B3", "--prop", "rows=Region", "--prop", "values=Revenue:sum"]} {"command": ["get", "数据.xlsx", "/Sheet1/B4", "--json"]} ``` - **公式要写 `value==SUM(B2:B3)`（两个 `=`）**——`--prop key=value` 的第一个 `=` 是分隔符，值本身以 `=` 开头 才被当公式；漏掉前导 `=` 会**静默存成字符串**（`evaluated: false`，看不出来）。 - 求值结果直接读：`get --json` 的 `format.computedValue` / `evaluated` / `formula`（写入即算，无需 Excel 回环）。 - 透视表一条命令落 OOXML；`view text` 能看到透视输出区（含 `Grand Total`）。 ### 7.5 纸面活预览（截图刷新路——兰台当前无"环回 URL 窗口"平台件时的正式形态） 要点：**同一份文档固定用同一个 PNG 路径**，靠 `update_asset` 原地刷新资产块（不新开块、不刷屏）。 1. **首次**：`{"command": ["view", f, "screenshot", "-o", "<绝对路径>/<文档名>-第N页.png", "--page", "N"]}` → `show_asset(kind='file', title='<文档名> 预览', payload={filePath: <该 png>, label: '第N页', ext: 'png'})` → **记下返回的 `assetId`**。 2. **每次改完**：`save `（**必做**）→ 重新截到**同一路径** → `update_asset(assetId, payload={filePath: <同一路径>, label: '第N页', ext: 'png'})`。 3. **多页**：`--page N` 一页一张（每页一个块/一次 update）；想一眼看全册用 `--grid auto` 出联系表。 4. **判据**：内容改了、图必须跟着变。**实测已证**：Save 后重截同一路径，PNG 字节确实不同 （`src-ui/tests/office-cli-e2e.test.ts` ⑨ 用字节差钉死这条语义）；图没变先怀疑漏了 `save`。 —— 这是"活预览"在兰台的最小可用形态；`officecli watch` 的活刷新页已有一条真机验证过的通路 （平台件：窗入口二态 + 环回 URL，`office_preview_open` 开窗；实测帧内 SSE `readyState=OPEN`、页面真渲染）， 但**在技能里不必自己内嵌**——开窗是插件工具的事，技能只管产出与自检。 ### 7.6 幻灯片（pptx）最小工作流（逐条实测） ``` {"command": ["create", "汇报.pptx"]} {"command": ["add", "汇报.pptx", "/", "--type", "slide", "--prop", "title=季度汇报", "--prop", "background=1A1A2E"]} {"command": ["add", "汇报.pptx", "/slide[1]", "--type", "shape", "--prop", "text=收入增长 25%", "--prop", "x=2cm", "--prop", "y=5cm", "--prop", "size=24", "--prop", "color=FFFFFF"]} {"command": ["view", "汇报.pptx", "outline"]} {"command": ["view", "汇报.pptx", "issues"]} {"command": ["view", "汇报.pptx", "screenshot", "-o", "<绝对路径>-第1页.png", "--page", "1"]} {"command": ["view", "汇报.pptx", "screenshot", "-o", "<绝对路径>-全册.png", "--grid", "auto"]} {"command": ["validate", "汇报.pptx"]} {"command": ["save", "汇报.pptx"]} ``` **实测口径**：`add / --type slide` 建页（`title` 与 `background` 同时给）；`add /slide[N] --type shape` 加文本框，四类属性一次到位（文本/坐标/字号/颜色）；`view outline` 出一页一行的大纲； `view issues` 本机干净（0 条）；`screenshot --page N` 出单页 PNG，**`--grid auto` 出全册联系表** （2 页 deck 实测 26.6 KB）——两者都能直接喂纸面资产块；`validate` 干净。 标题是**占位符**（`isTitle=true`），新加的 shape 是普通文本框——改标题请寻址 `shape[@id=2]` 那类稳定 id， 别用 positional `shape[1]`。 **长度**：`cm` / `mm` / `in` / `pt` / `pc` / `px` / `Q` / **裸 EMU**（如 `914400` = 1 英寸）。 ⚠️ **`%` 不是合法长度**（`x=10%` 会被拒：`Invalid length value '10%'`）——百分比只在**行距**上有意义。 **颜色**：6 位 hex（`FF0000`）/ 3 位简写（`F00`）/ 8 位含 alpha（`80FF0000` = AARRGGBB）/ 4 位简写（`#F00A`）/ 命名色（`red`）/ `rgb()` `rgba()` `hsl()` `hsla()` / `transparent` / 主题色 `accent1`..`accent6`。 回执会带**归一化结果**（`color=rgb(255,0,0) (applied: color=#FF0000)`；带 alpha 的读回是 `#RRGGBBAA` 形态）。 **行距（lineSpacing）**：倍数 `1.5x` / 百分比 `150%`（→ applied `1.5x`）/ 定值 `18pt` / 长度 `0.5cm`（→ 14.15pt）/ `1in`（→ 72pt）——五形态全通。 **字号**：`14` 或 `14pt`；**坐标**：`x=2cm` / `y=5cm`（幻灯片绝对定位）或 `anchor=x,y,w,h` 简写。 ## 9. 常见坑 | 坑 | 正解 | |---|---| | `--name "foo"` | 属性一律 `--prop name="foo"` | | shell 里 `/slide[1]` 被 glob 展开 | 用 argv 数组形态（兰台推荐）或加引号 | | PPT 里 `shape[1]` 改了标题 | `shape[1]`（positional）通常是**标题占位符**（`isTitle=true`、`zorder=1`），正文从 `shape[2]` 起；**优先用稳定寻址 `shape[@id=N]` / `shape[@name=X]`**（实测：新建的 shape 拿到 `shape[@id=100000]`，改完插删不会漂） | | 猜属性名 | 跑 `help ` | | 新建 docx 里 `style=Heading1` 报警告 | 新建文档只有 `Normal`，先 `add /styles --type style` 定义（§7.1） | | `view issues` 报中文正文缺首行缩进 | `--prop firstLineChars=200`（2 字符） | | 同一 run 上叠第二个修订被拒 | 一 run 一修订；换个 run，或用 `revision.type=format`（§7.3） | | 带修订的文档"少了一段" / 看不出哪段有修订 | `view text` 隐藏待决删除、`annotated` 不标注——真源是 `query revision`（§7.3） | | 改了但兰台/别的程序看不到 | 没 `save`（铁律 1） | | 想看效果却"看不到图" | 工具结果里的图会丢——落盘 PNG + `show_asset`（铁律 2） |