zimoliao / document
Use when the user wants to create or inspect DOCX, PPTX, or XLSX files, generate a downloadable Office deliverable, or verify its structure and layout warnings with scholaraio document inspect.
Office 文档生成与检查
Capability Routing
当前 Agent 原生能力优先，但必须先做能力检查：按最终交付物路由，不按 Agent 品牌路由。若当前会话实际提供内容写作、演示设计、图表或版式能力，就由当前使用的 Agent 原生能力先完成内容与视觉方案。只有用户需要可下载、可复现的 DOCX/PPTX/XLSX 文件时，才使用本 skill 的 Office API 和检查闭环。
Output Contract
| 用户要的产物 | 默认实现 | 必做检查 |
|---|---|---|
| 正式报告、综述、简报 | python-docx → DOCX | 标题层级、段落、表格、图片、样式 |
| 汇报、演示、答辩 | python-pptx → PPTX | 页数、shape 边界、文字溢出警告、图片、表格 |
| 数据表、统计、清单 | openpyxl → XLSX | sheet、数据范围、冻结窗格、格式、图表 |
把用户交付物写到 workspace/ 下；正式文件默认放 workspace/reports/，系统生成图表默认放 workspace/_system/figures/。不要把产物写到仓库根目录。
Workflow
- 明确最终格式、受众、语言、模板、页数或篇幅，以及是否需要可编辑源文件。
- 使用当前会话实际可用的原生能力完成内容、故事线和视觉方案；需要文献数据时再组合 ScholarAIO 的检索或写作 skill。
只读取与目标格式对应的实现参考：
- DOCX：读取 [references/docx.md](references/docx.md)
- PPTX：读取 [references/pptx.md](references/pptx.md)
- XLSX：读取 [references/xlsx.md](references/xlsx.md)
- 用一个可重复运行的 Python 脚本生成文件。脚本与产物都放在对应 workspace 中，避免散落临时代码。
- 运行
scholaraio document inspect <file>；发现结构问题或溢出警告时，修改脚本、重新生成并再次检查。 - 若当前会话实际具备 Office/PDF 渲染或页面预览能力，再对所有页面或幻灯片做视觉检查。否则明确说明只完成了结构检查和启发式布局检查，不要声称已经视觉验收。
- 向用户提供最终文件路径、格式和已完成的检查。
Inspection Commands
scholaraio document inspect workspace/reports/report.docx
scholaraio document inspect workspace/reports/presentation.pptx
scholaraio document inspect workspace/reports/data.xlsxdocument inspect 是结构化检查器：
- PPTX：报告每页 shape 的位置、尺寸和内容，并给出边界/文字溢出启发式警告。
- DOCX：报告章节、段落、表格、图片和样式结构。
- XLSX：报告 sheet、数据范围、冻结窗格、合并单元格、预览和图表。
它不能代替完整的 Office 渲染器。无警告不等于视觉布局一定正确。
Composition Rules
| 前置任务 | 组合方式 |
|---|---|
| 绘制流程图或论文图 | /draw 生成 SVG/PNG，再嵌入 Office 文件 |
| 搜索或整理论文 | /search、/workspace 或写作 skill 先生成有来源的内容 |
| 文献综述或论文章节 | /literature-review 或 /paper-writing 先完成内容，再封装 DOCX |
| 普通演示稿 | 先完成故事线与逐页内容，再生成 PPTX |
Quality Gates
- 保留输入数据、生成脚本和最终 Office 文件，使交付可重复生成。
- 不编造引用、图表数据或缺失内容；无法核验的内容必须标注。
- DOCX 使用语义化标题样式，不用手工字号假装标题层级。
- PPTX 统一页面尺寸、边距、标题层级和视觉网格，避免默认模板堆字。
- XLSX 保留原始数据精度，显式设置数字格式、冻结表头和筛选范围。
- 检查结果失败或出现警告时，先修复再交付；不能修复时明确列出剩余问题。
Simple Conversion Escape Hatch
只有简单 Markdown → DOCX 且不需要高级排版时，才使用：
scholaraio export docx --input workspace/report.md --output workspace/reports/report.docx即使使用快捷转换，也要运行 scholaraio document inspect。
Examples
用户说：“帮我总结文献库，交付一份 Word 简报”
→ 先检索和核验内容 → 读取 DOCX 参考 → 生成 DOCX → inspect → 有渲染能力时再视觉检查
用户说：“把工作区论文做成给导师汇报的 PPT”
→ 先组织故事线和逐页信息 → 读取 PPTX 参考 → 生成 PPTX → inspect → 逐页视觉检查
用户说：“把论文统计导出为 Excel”
→ 获取结构化数据 → 读取 XLSX 参考 → 生成带格式和筛选的 XLSX → inspect