officecli 批量写入规则

本规则适用于通过 @officecli MCP 工具操作 .xlsx / .docx / .pptx 的所有批量写入场景。

核心约束

1. 禁止使用 stdin（`--input -`）

当前 agent 通过 MCP 调用 officecli，只能传递一个 command 字符串参数，没有 stdin 管道。 --input - 会让进程启动后一直阻塞等待标准输入，永远等不到数据，表现为“卡住无响应”直到被取消。

禁止：batch <file> --input -
禁止：任何依赖管道 | 或 heredoc <<EOF 向 officecli 喂数据的写法（MCP 环境不存在 shell 管道）

2. 批量写入首选 `--commands` 内联

把批量操作的 JSON 直接作为 --commands 的参数值内联传入，一次调用完成，不经过 stdin、不写临时文件。

batch <file> --commands '[
  {"command":"set","path":"/Sheet1/A1","props":{"value":"字段","bold":"true"}},
  {"command":"set","path":"/Sheet1/A2","props":{"value":"数据"}}
]' --json

始终带 --json，便于读取 matched / 成功失败计数 / atomicRolledBack 等结构化结果。
batch 默认原子执行：任一条失败则整批回滚，文件保持批处理前的状态。需要“保留已成功项”时才加 --best-effort。

3. 不要退化成逐条 `set`

逐条 set（一格/一行一条命令）只作为最后兜底，不是默认方案。能用一次 batch --commands 解决的，不要拆成几十次调用。

4. 超大批量才考虑临时文件

仅当批量 JSON 大到 --commands 内联不现实时，才改用 --input <真实文件路径>：

必须是 officecli 进程有权读取、且真实存在的文件路径。
用 write 工具写 JSON 时，路径必须落在 write.allowedPaths 允许的目录内。
写完后用 batch <file> --input /真实/路径/ops.json --json 读取。
绝不使用 --input -。

参数拼写与转义

路径含 [N] 时整体加引号：'/Sheet1/A1'、"/slide[1]"。
文本含 $、换行等特殊字符时，优先放进 --commands 的 JSON 里，避免 shell 层转义问题（MCP 透传虽不经 shell，但 JSON 内保持规范更稳妥）。

决策顺序（从优到劣）

batch --commands '[...]' --json —— 默认，绝大多数场景用这个
batch --input <真实文件> --json —— 仅超大批量
逐条 set —— 仅当以上都不可行时的兜底
--input -（stdin） —— 永远不用

officecli-batch-rules.md 2.4 KB Historie Surový

officecli 批量写入规则

核心约束

1. 禁止使用 stdin（--input -）

2. 批量写入首选 --commands 内联

3. 不要退化成逐条 set