zagens-office：Office 文档生成与编辑
单二进制 CLI，无 Office 依赖。默认安装：~/.zagens-pro/bin/zagens-office.exe（已在 PATH 时可直接 zagens-office）。
默认只读本文件，不要预读 references/。 正式/精修 PPTX → pptx-design.md + pptx-craft.md；改已有 XLSX 表单 → xlsx-fill.md（不足再 xlsx-grid.md）；DOCX/PDF 细节 → docx-pdf.md。字段以 schema 为准，勿凭记忆猜。
§0 · Skill 路由（Hub + Spoke）
| 用户意图 / 信号 | 加载 | 入口 |
|---|---|---|
| 8D / 巡检 / merge 企业模板 / fillmap | 留本 skill | read fillmap → edit fill；未覆盖格见 xlsx-grid.md |
| 洗订单/名单/台账、去重、统一格式、clean_report | load_skill office-xlsx-clean |
见该 spoke（integrate 默认捆绑；勿在本 skill 展开 transform） |
多文件/多 Sheet 合并、拼表、归档、merge_report |
load_skill office-xlsx-merge |
merge / merge_office（schema merge） |
| 从 CSV 做带样式新报表（无清洗管道） | 本 skill 或 office-data-report |
write xlsx-table / source |
首次使用：先确认引擎已安装
本 skill 仅含说明；引擎在 ~/.zagens-pro/bin/（CLI + GUI 均需安装）。按当前 shell探测，不要混用变量语法：
| Shell | 推荐探测命令 |
|---|---|
| Bash / Git Bash / 多数 Agent 终端 | "$HOME/.zagens-pro/bin/zagens-office.exe" --version |
| PowerShell | & "$env:USERPROFILE\.zagens-pro\bin\zagens-office.exe" --version |
| cmd.exe | "%USERPROFILE%\.zagens-pro\bin\zagens-office.exe" --version |
| 已在 PATH | zagens-office --version |
禁止在 Bash 里写 %USERPROFILE%...（不展开 → 误判未安装）。以 stdout 版本号为准，勿凭退出码或 || 兜底文案。探测失败则 agent 自动按 https://zagens.com/download/install.md（备用：https://raw.githubusercontent.com/didclawapp-ai/zagens-office/main/install.md）执行 §1–§4 安装 CLI + GUI，勿只发链接。装完再 --version；评估期 90 天，到期走 license contact。
通用纪律（四格式共用）
- 先契约：
schema write <pptx|xlsx|docx|pdf>或schema edit（100 op，不可按格式过滤）。 - 信封：stdout 一行 JSON；
ok=false时按code/error/suggestion修正，勿盲目重放。 - 复杂 JSON 用文件：
--input-file <file>；简单才--input '<json>'。 - 多步改稿：
edit --op batch+"atomic": true；失败看result.rolled_back。白名单含fill/upsert_slide/add_sheet/set_text/set_props/add_slide/delete_slide；preflight/auto_fix/fit_text/avoid_overlap/align/distribute/snap_to_grid/generate_variants/rank_variants/ 动画 / 切换 不在 batch。完整名单以schema edit为准。dry_run：JSON"dry_run": true或edit --dry-run。 - 多稿择优：
generate_variants（out_dir/recipes，默认rank）→result.report.ranked.winner；已有文件用rank_variants+candidates（≤8）。 - 交付自检：
preflight（版式/语义）或至少validate（仅 OPC）。不对 PDF 跑 validate。 - 路径：Windows 用正斜杠或整段加引号。远程
urlCLI 不抓取 → 本地path。 - 授权：期满 write/edit →
license_locked。跑license contact，按banner_markdown打开授权页后license activate --key。read/schema/license/update不锁。升级后新开宿主会话。
| 命令面 | 用法 |
|---|---|
| 生成 | write {pptx\|xlsx\|xlsx-table\|docx\|pdf} --path <out> ... |
| 编辑 | edit --path <file> --op <op> ... |
| 读取 | 改前先读再 batch / preflight |
1. PPTX
入口：write pptx · edit · read pptx --mode outline|text|stats · view/--preview。
| 场景 | 路径 | 纪律 |
|---|---|---|
| 正式 / 精修 / 高级感（路演、公司介绍、咨询、政务、官网样张、文旅、用户要求好看） | 骨架 write → 逐页 upsert_slide |
禁止一次 write 塞满多页重 elements[] |
| ≥8 页，或单页自由画布很重 | 同上 | 同上 |
| ≤6 页且只要速出 | 整份 write pptx |
勿自称「精修」 |
| 只改正文/颜色/位置 | set_text / set_props / align/distribute/snap_to_grid |
勿整页 upsert |
| 删页 | delete_slide（target=/slide[N]） |
— |
硬规则： 「精修 / 高级感 / 正式样张 / 官网 / 对外交付」→ 默认逐页 upsert，即使只有 5～6 页。正式稿必须先读 pptx-design.md 与 pptx-craft.md（封面/theme/元素限制/修版）。时间轴用 shape+textbox 或 smartart，无 type:"timeline"。
骨架 write：theme + master（要页码则 "page_number":true）+ include_end + slides[] 每页仅 title（可选 role/thesis，整份 write 不写入 OOXML）。然后一页一个 upsert_slide：{"target":"/slide[N]","slide":{...}}（slide 与 write.slides[i] 同构）。全部落盘后 preflight。
zagens-office write pptx --path deliverables/deck.pptx --input-file skeleton.json
zagens-office edit --path deliverables/deck.pptx --op upsert_slide --input-file slide-01.json
zagens-office edit --path deliverables/deck.pptx --op preflight --input '{}'
骨架最小：{"title":"公司简介","theme":"consulting","cover":false,"include_end":false,"master":{"page_number":true},"slides":[{"title":"封面","role":"cover"},{"title":"关于我们","role":"content"}]}。单页 upsert 最小：{"target":"/slide[2]","slide":{"title":"关于我们","title_style":{"engine":false},"elements":[{"type":"textbox","x_pct":0.08,"y_pct":0.2,"w_pct":0.84,"h_pct":0.2,"runs":[{"text":"主标题","size":28,"bold":true}]}]}}。
2. XLSX
入口：write xlsx / write xlsx-table · edit（含 op: fill）· read xlsx --mode table|grid|fillmap|fields。写 grid/html 常需 --workspace .。
layout |
用途 |
|---|---|
table（默认） |
数据表/清单 |
grid |
精确版式 / sections 表单 |
html |
模型友好 HTML <table> → 同 grid |
template / promote |
模板填值 / 入库（见 schema） |
多 Sheet：第 1 张 write；后续 edit --op add_sheet（可进 batch）。勿同 path 反复 write 覆盖。复杂新建先 --validate-only，细节见 xlsx-grid.md。
改已有表单（首选）： read --mode fillmap → edit --op fill（≥20 格先 "dry_run": true）。流程与禁区见 xlsx-fill.md。fillmap 未覆盖格再走坐标层 xlsx-grid.md（grid + batch + view html）。
3. DOCX · 4. PDF
- DOCX：
write docx·edit·read --mode outline|text|stats。sections[]与顶层blocks[]互斥。细节见docx-pdf.md。 - PDF：几乎只有
write pdf。无read pdf，不要对.pdf跑validate。无 chart/textbox/shape。
跨格式备忘
schema write不含 Pro vault 字段；抄来的data_ref等会被忽略。- 不确定字段 → 跑对应
schema write <format>，不要把四格式字段混用。
