agent-office-pipeline · 把 agent 挂进你的 Office 文件夹

你现在运行 agent-office-pipeline 技能。这门课不写新文件，而是让 agent 去动用户已经有的一整个 Office 文件夹：合同模板批量套数据、财务模型追加月度数据后公式重算、PPT 模板批量替换字段，最后把结果配一份 HTML 视觉审阅稿 + 一份 manifest.json 交回来。

底层工具是 iOfficeAI/OfficeCLI（Apache 2.0）。一个单文件原生 CLI，本地跑 350+ Excel 函数、支持路径寻址、渲染真·自包含 HTML/PDF/SVG。不装 Word / Excel / WPS，也不需要任何 API key。

前置

• Node ≥ 18（node -v 检查）
• 操作系统：macOS / Linux / Windows 都行
• 不需要 MS Office、不需要 WPS
• 不需要任何第三方 API key
• 断网也能跑（除首次 npm 安装外）

安装（三选一，首选第一种）

# 推荐：全局装 npm 包，会自动拉对应平台的原生二进制
npm install -g @officecli/officecli

# 也可以：官方 curl 一键脚本
curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash

# 已装 pnpm 的话
pnpm add -g @officecli/officecli

装完 officecli --help 能出来即可。

工作流程（3 步）

第 1 步 · 摸清目录

先把用户的 Office 文件夹结构问清楚：

• 哪些是模板（含 {{占位符}} 或 ${变量}）？
• 哪些是数据源（xlsx / csv / json）？
• 哪些是已有模型（需要追加数据 + 重算公式）？
• 输出到哪个目录（默认 ./out/）？

不确定就用 officecli view <file> outline 或 officecli view <file> text 先扫一眼结构。

第 2 步 · 决定 pipeline 类型

三条典型路径 —— 选一条或组合：

路径 A · Mail-Merge（模板 + 数据 → 多份文件）

• 支持 .docx / .xlsx / .pptx 三种模板。
• 模板里写 {{字段名}}；agent 读数据源逐行套模板，输出到 ./out/<name>/<row>.<ext>。
• 命令：

  officecli merge <template> <output> --data <row.json>
  

  --data 支持一个 JSON 文件；批量时在 shell 里 loop，或写一个 officecli batch。

路径 B · 公式重算（追加数据 → 全表刷新）

• 用于财务模型、报表模板：Assumptions / Raw / Derived / Summary 结构。
• 用 officecli set <file> /<Sheet>/<Cell> --prop value=... 逐格写；或 officecli import <file> /<Sheet>/<Range> <csv> 批量导入。
• 用 officecli batch <file> --input plan.json 一次性提交多条指令，一次落盘。
• Derived / Summary 里的 SUM / AVERAGE / IF / VLOOKUP 等 350+ 函数由 CLI 本地求值，无需打开 Excel。

路径 C · 结构化抽表（读取已有 Office 文件 → JSON）

• 用 officecli get <file> <path> --json / officecli query <file> <selector> --json 把内容抽成结构化 JSON。
• path 走路径寻址：/Sheet1/B3、/slide[1]/shape[@name=Title]、/body/p[3]。
• 禁止手工解 zip / XML；用 CLI 的 path 或 selector。

第 3 步 · 人类看得懂 · 存证据

任何 pipeline 跑完都产出两样：

1. HTML 视觉预览 —— 每份关键产物都渲染一份：

   officecli view <file> html -o preview/<name>.html
   

   （xlsx 会带 sheet 切换 tab；docx / pptx 是自包含单文件。）

2. manifest.json —— 至少写清：每份产物用了哪一份输入 / 字段映射 / 未替换的占位符 / 公式重算是否有 #REF! / #VALUE! / 循环引用。这一份 JSON 就是 agent 和人类共同的审阅接口。

如果做了「改前 / 改后」这种带 diff 的产物，同一 Summary/Slide 各渲染一份 HTML，人类肉眼就能过。

关键命令速查

officecli help <format> <verb> 会列该格式下每个元素支持的 verb 与 prop。写不通就先看 help。

三个可直接跑的例子

例 1 · 合同批量套模板 + HTML 预览审阅

启动 agent-office-pipeline skill。我在 ./inputs 放了：一份 Word 合同模板 contract_template.docx（里面有 {{甲方公司}} {{甲方联系人}} {{金额}} {{签约日期}} 占位符），和一份客户名单 clients.xlsx（每行一位客户，列名对应上述占位符）。请用 OfficeCLI 依次做四件事：
  (1) 读 clients.xlsx 拿到每一行客户数据；
  (2) 复制 contract_template.docx，把每一份对应占位符替换成客户数据，产出到 ./out/contracts/<客户拼音>.docx；
  (3) 对每一份生成一份 HTML 预览 ./out/preview/<客户拼音>.html 供人工审阅；
  (4) 汇总一份 ./out/manifest.json，列出每份合同的输入行、字段映射、生成时间和源模板名。
全过程本地跑，不启动 Word/WPS。最后告诉我 out 目录路径，并挑一份让我打开 HTML 预览快速看一眼是否套错。

例 2 · 多 sheet 财务模型公式重算 + 改前改后视觉 diff

启动 agent-office-pipeline skill。我在 ./inputs 放了：一份多 sheet 财务模型 fin_model.xlsx（Assumptions / Raw / Derived / Summary 四个 sheet，Derived 和 Summary 是纯公式），以及 3 个月的最新 CSV：aug.csv / sep.csv / oct.csv。请用 OfficeCLI 依次做四件事：
  (1) 把 3 份 CSV 追加到 Raw sheet 对应区域（保持列顺序），并把 Derived 页的公式行同步延伸；
  (2) 导出改后的 fin_model_updated.xlsx 到 ./out/；
  (3) 用 officecli view html 分别渲染改前 fin_model.xlsx 和改后 fin_model_updated.xlsx 的 Summary sheet，产出 ./out/diff/before.html 与 after.html，再拼一个并列对照页 report.html；
  (4) 汇总一份 ./out/manifest.json，列出改动的单元格、公式重算前后值、任何 #REF! / #VALUE! / 循环引用告警。
全程本地，不启动 Excel/WPS。最后把 out 路径给我并提醒我先看 report.html。

例 3 · PPT 入职欢迎页批量个性化

启动 agent-office-pipeline skill。我有一份 welcome.pptx 模板，里面 4 张幻灯片带 {{甲方公司}} {{甲方联系人}} {{服务项目}} 三个占位符。数据源是 hr_new_hires.csv，每行一名新客户。请用 officecli merge 依次把每一行套进 welcome.pptx，输出到 ./out/welcome/<客户拼音>.pptx，同时用 officecli view <file> html -o preview/<name>.html 给每一份出一份可在浏览器打开的预览页，最后写一个 manifest.json 汇总所有 pptx 路径、每张幻灯片替换的字段和总数。

常见坑

• {{占位符}} 不生效 — 确认模板里的花括号没有被 Word 自动智能引号替换成全角。用 officecli view <file> text 反查一眼。
• officecli set --prop value=金额 --prop type=number — 中文文本要用 type=string；只有真正数字用 type=number。
• 公式跨页引用 — Derived 里写 =Raw!B2、跨绝对引用 Assumptions!$B$2；CLI 会本地求值并写入 cachedValue，人在 Excel 打开也能直接看到结果。
• batch 一条失败会跳过后续吗 — 不会，batch 会继续跑剩下的，最后回报 succeeded / failed。想全部失败即回滚，就自己在 shell 里判断退出码。
• HTML 预览太重 — 单份 docx 渲染出的 HTML 约 50 KB，xlsx 20–30 KB，pptx 20 KB。不要一次渲染 1000 份放同一个目录里，分批。
• Windows 下路径 — 用 \\ 或加引号。
• 不要手工解 zip/XML — 有需求先看 officecli help <format> 有没有 verb；实在没有再用 raw-set 兜底。

学习完成后

告诉用户：

我已经学会了 agent-office-pipeline。给我一个 Office 文件夹（模板 + 数据源），我用 OfficeCLI 帮你做批量套模板、公式重算、结构化抽表，并给每份产物配一份 HTML 预览和一份 manifest.json。全程本地，不装 Office，不出网。