文档工坊基础能力质量契约

这份规则约束 Cindy 内置的 PDF、Word、PPT、Excel 文档能力。它描述的是基础产品应该稳定做到的事，不要求用户安装插件，也不把排版责任推回给用户。

1. 基础工序：HTML-first，但不把 HTML 当成最终交付

当用户要一份正式文档时，Agent 默认先在脑中或临时内容里形成一份自包含 HTML 初稿：样式内联，图片使用 data URI、可访问的公网地址或任务目录内的本地资源，页面有明确的封面、层级、留白和内容标题。HTML 是排版草图和跨格式的共同视觉参考，不是要求用户看懂的中间产物。

随后按交付格式选择顶层工具：render_pdf、make_docx、make_pptx、make_xlsx。工具描述中的版式工序优先于任何外部 skill；六个文档工具直接暴露，不能再教 Agent 通过已下线的 list_tools / call_tool 二级入口分派。

落地后必须做结构自检：PDF 用 inspect_pdf；Word、PPT、Excel 至少检查文件存在、尺寸/数量和关键内容是否落盘。发现失败时先回看原始 XML 或结构数据，再判断是否真的缺失，不能把目检台的折叠、域、编号递推或资源限制误判成生成失败。

2. 四种格式的统一视觉语言

四种格式共享三套受控主题（light、dark、navy），共享以下设计骨架：

• 封面：主题色强调带或色块、清晰主标题、可选副标题/来源/日期；不把标题挤在页顶，也不让封面只剩一片空白。
• 内容页：标题层级稳定，正文有足够行距和留白，强调色只承担导航和重点，不用满屏彩色装饰。
• 内容标题：封面标题、章节标题、表头/页眉和作品卡标题使用同一套语义角色；格式可以不同，但不能各自发明一套视觉身份。
• 交付元数据：格式、主题、标题/副标题和数量（页/幻灯片/工作表/行列）可被上层 UI 消费。它们只描述生成结果，不代表视觉复核或用户验收。

格式差异是语义差异，不是随意差异：PDF 重视打印尺寸和分页，Word 重视可编辑层级和表格，PPT 重视单页信息密度和演讲节奏，Excel 重视扫描、筛选、冻结和汇总识别。

3. Session 作品卡

作品卡是 Cindy 内置能力，不是插件专属能力。它不是普通文件 chip 的放大版，而是交付结果的轻量封面：

• 左侧使用类型化封面（PDF / Word / PPT / Excel 各有稳定字标和主题色）；
• 中间显示标题，标题缺失时回退到文件名；副标题显示格式或主题，避免把内部路径当主信息；
• 下方显示页数、幻灯片数、工作表/行数或文件大小等可读摘要；
• 作品卡只显示真实的文件与生成摘要；工具返回的 warning 仍留在工具结果中，不转换成“待视觉复核”“已检查”或其它验收状态；
• 点击仍沿用文件正文的打开策略，右键仍保留复制、定位和打开方式；
• Light 与 Dark 都必须使用语义 token，不写仅适配一个模式的固定颜色；
• 多个产物使用统一卡片骨架，不能因为格式不同而退化成四套互不相干的组件。

作品卡只展示真实存在且属于当前 turn 的文件。无法确认归属或远端 stat 失败时宁可不展示，不显示一个用户点不开的“完成品”。

4. 内置能力与插件边界

内置能力负责“任何会话都能完成”：顶层工具、受控主题、HTML-first 排版契约、格式落地、结构自检和 Session 作品卡。它不能依赖插件是否安装。

插件未来负责“更快、更傻瓜、更有选择”：模板库、报表/简历/周报等场景卡、模板选择面板、成品记录和跨格式编排引导。插件可以调用内置工具，但不能复制一份与工具描述或本规则冲突的排版说明，也不能成为基础文档能力的唯一入口。

文件生成成功、结构检查通过、视觉复核通过、用户接受交付是四个不同事件。本期没有用户接受、拒绝、批注或侧栏审阅状态，也不会在作品卡中模拟这些状态。inspect_pdf 的 verdict 只属于该工具的一次结构检查，不会自动回写作品卡。

5. 失败与质量门槛

工具失败返回稳定的错误码和人话 hint：说明发生了什么、最可能的原因、下一步应该改哪个输入。原始 message 只作为诊断字段保留给日志/审计，不作为默认用户文案直接倾倒到对话里。

提交前必须覆盖相关单测、涉及 package 的 typecheck、i18n 与 glossary 门禁；不能启动 Electron、dev server、CDP，也不能用 LibreOffice、pandoc 或外部 Office 工具假装完成目检。PDF 若无法在当前环境实机视觉验证，交付说明必须明确“结构已测、视觉未实机验证”。