# 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 内保持规范更稳妥）。

## 决策顺序（从优到劣）

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