免 Office 文档引擎（office-kit）
为 Agent 提供"无 Office 环境下处理 docx / xlsx / pptx"的统一引擎：读内容、写内容、批量改模板占位符、抽取数据、转讲稿文本。可选包装 GitHub 热门项目 OfficeCLI（iOfficeAI/OfficeCLI，Apache-2.0），其缺失时自动降级到纯 Python 标准库。
三步流程（Agent 必须遵守）
第 1 步 · 能力探测
先跑 scripts/capability_check.py（或 --json）获取本机能力矩阵，决定每条操作走哪条通道：
- 首选 officecli（若在 PATH）；转 PDF 时 soffice；否则纯标准库。
python3 scripts/capability_check.py --json
第 2 步 · 通道决策
决策规则（详见 references/capability-matrix.md）：
1. officecli 可用 → 读写/merge 一律用 OfficeCLI（真实命令，见 references/officecli-guide.md）；
2. 无 officecli、需转 PDF → 用 soffice --headless --convert-to pdf；
3. 都无 → 纯标准库：读文本、写最小文件、merge 占位符、导出 txt/csv。PDF 会报"无通道，请安装 OfficeCLI 或 LibreOffice"。
第 3 步 · 执行并输出
统一入口 scripts/office_task.py（支持 read / write / merge / convert / report / check）：
# 读
python3 scripts/office_task.py read 文件.docx [--format docx|xlsx|pptx] [--channel officecli|std]
# 写
python3 scripts/office_task.py write 文件.docx --content $'正文\n正文'
# 批量占位替换
python3 scripts/office_task.py merge 模板.docx --out out.docx --data '{"client":"Acme"}'
# 转换
python3 scripts/office_task.py convert 文件.xlsx --out 文件.csv --to csv|txt|pdf
# HTML 操作报告（白底淡蓝，交付/审阅用）
python3 scripts/office_task.py report 文件.txt --out report.html --title "标题"
输出为结构化文本 / JSON / HTML 报告。关键文件交付前务必读回抽检（读回可用 read）。
JSON 操作 schema
统一入口参数（office_task.py）：
- read <file> [--format] [--channel] → stdout 文本 / 错误走 stderr 并 exit 1
- write <file> [--content|--rows|--titles] → 生成最小文件，输出"已生成: <path> (N 字节)"
- merge <template> --out <out> --data <json> --channel → 占位替换，输出"已合并: <out>"
- convert <file> --out <out> --to <txt|csv|pdf> → 输出文件；PDF 无通道时明确报错
- report <file> --out <html> [--title] → 白底淡蓝 HTML 报告
- check [--json] → 能力矩阵
能力探测（capability_check.py --json）返回：
{"python": "3.12", "channels": {"officecli": {"found":true,"path":"...","version":"v1.0.158"}, ...},
"stdlib_available": true, "operations": {"read.docx":["officecli","python-stdlib"], ...},
"install_guide": "officecli 未安装时的最短安装指引"}
资源清单
| 路径 | 用途 |
|---|---|
scripts/capability_check.py |
能力探测，输出能力矩阵 JSON + 安装指引 |
scripts/office_task.py |
统一任务执行（纯标准库降级通道 + officecli 通道） |
references/officecli-guide.md |
OfficeCLI 实测用法（安装/命令/退出码，全部来自官方 README） |
references/capability-matrix.md |
降级矩阵（各操作 × 各通道 能/不能/质量差异） |
references/recipes.md |
10+ 常见任务配方（含通道选择逻辑） |
references/NOTICE.md |
上游 Apache-2.0 归属与免责声明 |
降级矩阵摘要（完整版见 references/capability-matrix.md）
| 操作 | OfficeCLI | soffice | 纯标准库 |
|---|---|---|---|
| 读 docx/xlsx/pptx | ✅ 全能力 | ✅ 部分 | ✅ 文本级（格式弱） |
| 写 docx/xlsx/pptx | ✅ 全能力 | 受限 | ✅ 最小文件 |
| 模板占位替换 {{key}} | ✅ merge | 部分 | ✅ 文本级 |
| 转 txt/csv | ✅ | ✅ | ✅ |
| 转 PDF | ✅（需插件） | ✅ 推荐 | ❌ 无通道（提示安装） |
| 样式/图表/公式保真 | ✅ | 部分 | ❌ 丢失 |
合规与免责（审核红线）
- 红线：本技能只做本地文件读写与转换；不下载 ZIP、不执行远程脚本、不索取密码。三个脚本不含任何网络拉取与凭证逻辑。
- 不打包二进制：officecli 单二进制（约 33–35MB）由用户按
references/officecli-guide.md自行安装；本技能仅shutil.which探测，缺失即降级。 - 上游归属：OfficeCLI 为第三方 Apache-2.0 开源项目，责任归属上游；署名/许可见
NOTICE.md。 - 能力边界：纯标准库只是"最小可用兜底"，不替代 Office；高质量版式/图表/公式请装 OfficeCLI 或 soffice。
- 输出建议抽检：基于本技能生成/转换的文件，交付前请用
read读回或人工抽样核对，尤其涉及投标、合同、报表等正式文档。
依赖与降级（透明披露）
三通道矩阵：officecli（本地开源 CLI，PATH 探测）→ soffice（LibreOffice，转 PDF）→ 纯 Python 标准库（零依赖兜底）。
- officecli/sffice 均为 本地工具，无任何在线服务调用（officecli.ai 官网已 301 至 GitHub 仓库，安装一律走 GitHub 渠道：brew/npm/scoop/GitHub Releases）；
- 未安装 officecli 时：docx/xlsx/pptx 读写、合并占位符、批量批处理自动降级纯标准库执行（版式保真度下降会如实标注）；
- PDF 转换例外：无 officecli（含 converter 插件）或 soffice 时 不做任何降级，直接报错并附安装指引——宁可失败提示，不静默产出错文件。
