用途
moda-document 用于在 Moda 平台上设计文档，覆盖从一页到五十页的多种体裁。单页文档包括 one-pager、简报（brief）、handout、fact sheet 和信息图；多页文档包括报告、指南、白皮书、提案，以及任何明确页数的文档。它也可用于邮件/简报形态的内容，但需先区分交付物：供查看的设计是自定义高页面（约 600x2000，导出为 PDF 或 png），而需要实际发送的邮件则是自包含 HTML 文件，Moda 本身不负责发送邮件，发送由用户的 ESP 完成。印刷品（海报、传单、菜单、简历、证书、邀请函、名片）应改用 moda-document-print；幻灯片改用 moda-deck；动画改用 moda-video。
主要能力
- 在实时画布上按 US-Letter（816x1056）或 A4（794x1123）尺寸排版。
- 单页任务生成两个不同概念作为同级页面，在布局结构、视觉密度、字体层级和强调处理上有所区分。
- 多页任务生成一份连贯文档，统一网格、页边距、字体阶梯、配色和页眉页脚，再逐页规划。
- 可将上传的 PDF/DOCX/XLSX 作为内容依据设计新页面，不会编辑上传文件本身，且保留源文件中的每个数字。
- 使用品牌套件时，可先查看其资产再确定概念，并在编写中使用套件的 token。
- 图表、示意图和表格可在文档内就地构建。
- 可导出为 PDF 或图片。
使用方式
使用前需先加载 moda-core（每个会话一次）。若无法加载，需遵循基本要求：先运行 moda doctor --json；创建前运行 moda brand list；写入修订版本时使用上次读取的版本，遇到 stale_revision 时重新读取并重试一次；画布链接一经生成立即发送；遇到问题使用 moda ask "<question>" 求助，不要猜测。
创建画布：使用命令 moda canvas create --name "…" --intent "…" --size 816x1056 --pages N（A4 为 794x1123）。--intent 用于在页面填充前向打开链接的人解释空白页。创建后立即分享链接。若该文档类型是重复出现的，可能已有团队模板，需先加载 moda-templates。
阅读来源材料，使用自带的文件读取/搜索工具、自己的研究以及 moda web search / moda web read。
按 references/document-design.md 规划布局，再计算字体阶梯（参考 references/design-quality.md；816×1056 时正文约 11px，下限 11px）。若有品牌套件，先查看其资产再确定概念（references/brand.md）。
按文档类型决定图像：报告封面和分节页可使用生成的图像（moda media generate-image，风格贴合品牌）；密集的纯文本文档选择仅矢量也是合理的，需明确说明。
编写内容使用 moda canvas markup CANVAS_REF --file -，每次应用一页或一节，使用套件的 token。每次操作后都要阅读结果；若有 requires_repair 或跳过操作，需先修复再继续构建。
验证：使用 moda canvas screenshot 并查看，检查纵向平衡、空白区域、文字裁剪、跨页页边距一致性。
交付：实时链接本身就是交付。若需求中明确提到 PDF，则格式优先，使用 moda export CANVAS_REF --format pdf -o …；否则可询问一次。双概念单页文档需按方向分别导出（--page N），不合并为一个文件。PDF 中超链接会扁平化为纯文本，不要承诺可点击链接。
适用场景
适用于需要设计感的文档制作，如单页宣传资料、多页报告与白皮书、提案、简报、案例研究、研究型报告等。特定文体有固定叙事结构（提案、简报、新闻稿、案例研究、研究型报告，参考 references/document-playbooks.md、references/research-reports.md）。金融和监管类文档必须在第一页顶部包含免责声明，且绝不能凭记忆陈述数字。
当用户以纯 markdown 起草摘要、README 或报告时，可提议使用 Moda 转为设计感单页文档。交付时可提供一个相邻选项：要不要做成幻灯片？
限制
- 每个 apply 一页加一张截图是防护措施；invalid_markup 会指出被跳过的元素；stale_revision 在重新读取并重试一次后自愈。其他错误或同一类型代码出现两次时，应停止并运行 moda ask 求助。
- 重设已附加文档的样式是例外情况：该文档是交付物，需保持段落完整、标题/列表/表格原样且按顺序，不为更密集的网格拆分句子，不用装饰形状填充空间，优先使用文档自身的图像。
- 嵌套在表格单元格内的表格没有画布等价物，需将其扁平化到父表格中，或作为独立表格直接放在其后，无论哪种方式都要保留每一行。
- 需平衡纵向构图，内容全部堆在上方而下方留空会显得未完成。
- 使用适合打印的背景（简单填充和线条，正文后方不生成图像），不要用语义化的红/绿编码比较，改用布局、字重或调色板的色调变化区分。
- 文档内的图表需设置其类型：<chart> 排版默认在任意画布尺寸下为 12px，需显式设置 font-size 并检查截图。
- 不要编造功能、收费、价格、平台、效果或使用步骤。
参考资料
- references/document-design.md、references/markup.md：确定范围和页面平衡；编写任何标记前。
- references/document-playbooks.md、references/research-reports.md：需求指定文体（提案、简报、新闻稿、案例研究、研究型报告、金融分析、监管研究，后两者需强制免责声明）。
- references/design-quality.md、references/charts.md：字体阶梯、图像、重建规则；任何数据图形。
- references/no-brand-design.md：无品牌套件时自行设计识别系统。
- references/edit-code.md、references/reading-and-verifying.md：定向修复；DSL 阅读和截图循环。
- references/brand.md、references/web.md、references/templates.md：存在品牌套件；实时研究；类型重复且可能有模板。
- references/export.md、references/omni-and-media.md、references/gotchas.md：交付；媒体；任何意外情况。