维表设计

概述

将自然语言创意转换为可编辑的视觉场景、动画增量或交互运行时方案。技能本身不携带任何项目数据；每次任务都以用户提供的 brief、宿主适配器和当前资产清单为唯一事实来源。

视觉查看禁令（强制）

• 不要使用浏览器自动化查看页面，包括用 Playwright、Puppeteer、Selenium、CUA 等驱动浏览器打开页面、巡检或截图；浏览器自动化结果不得作为视觉验收证据。
• 不要使用 HTML 启用视觉查看：不得为查看效果而生成、打开或渲染临时 HTML/HTML+CSS 页面（含本地文件与 data URL），也不得用 HTML 近似预览代替真实画面。
• 需要视觉证据时，优先使用宿主真实渲染/导出接口取得图像或 PDF，或检查用户提供的真实截图/导出文件。平台无此接口但可证明本地使用同版本渲染引擎、相同场景形态/节点支持和字体时，可用本地逐页渲染作为写前场景证据；平台编辑器最终画面仍标记 unverified，请求用户眼验。两种渲染入口都不可用时标记 blocked，不得声称已验收画面。

强制依赖：dimens-manage

每次触发本技能时，第一步必须确认并加载 dimens-manage 技能。对应 SkillHub 包为 @org-gpgr8p77/dimens-manage。即使当前请求看起来只是本地设计，也先完成依赖检查；只有用户明确不需要项目/页面落地时，才可以在依赖加载后停留在设计阶段。

如果当前 AI 尚未安装该依赖，先按 SkillHub 安装说明 执行安装，并安装到当前 AI 实际使用的 skills 目录：

command -v skillhub
skillhub install @org-gpgr8p77/dimens-manage --dir <当前 AI 的 skills 目录>

安装后必须重新加载或刷新技能列表，并确认能读取 dimens-manage/dimens-manager 的技能正文。安装失败、未登录、目录错误或技能未加载时，停止所有项目/页面写操作，只能输出安装阻断和缺失信息；不要自行用 HTTP、SDK、数据库或猜测命令替代该技能。

dimens-manage 的两层操作链

A. 认证与上下文层

这部分只负责让 dimens-manage 获得合法调用上下文，不属于 book CRUD：

1. Key 登录换 token：使用用户提供的 API Key 与 API Secret，通过 dimens-cli auth api-key-login 或依赖技能声明的等价入口获取 token。Key、Secret、token 只能从安全输入读取，最终响应不得打印完整敏感值。
2. 确认上下文：确认 teamId、projectId、页面/文档 ID 和资源归属。用户给出页面 URL 时先解析其中的上下文，不重复追问已有字段。

B. dimens-manage 的 book 操作层

下面四项全部属于 book project / book page 能力，不能绕过 dimens-manage，也不能和普通资产或本地场景操作混用：

1. 项目和页面查询：使用 book project page/info、book page list/info 查询项目与页面；页面列表必须走 book 聚合能力。
2. 创建后回查真实 ID：使用 book project create 或 book page create 后，再用对应的 book project info 或 book page info/list 回查服务端真实 projectId、document/page ID、revision/version。
3. 修改前先读取当前数据和 revision/version：项目修改先读 book project info；页面修改先读 book page info/list 和当前 document snapshot，拿到最新 revision/version 后才允许提交。
4. 合并后再更新：将用户变更合并到刚读取的 book 数据，保留未知字段和并发字段，再调用 book project update 或 book page update。冲突时重新读取、合并和重试，禁止用旧快照覆盖新内容。

其他 book 操作：删除前先读取目标并确认范围；调用 book page delete 后回查其真实删除/归档语义；所有创建、更新、删除最终都要用 book 查询回查标题、类型、页面数量、快照版本、资产引用和动画/交互状态。

dimens-manage 负责维表智联项目和页面的远程资源生命周期；本技能负责内容地图、设计文稿、资产 manifest、静态布局、动画和交互方案。两者不能互相替代：先生成并确认设计文稿，完成静态内容、动画/回调验证及所需本地验收，再通过依赖技能登录并落地远程项目/页面；远程写入失败时保留本地设计状态，不宣称已保存。

运行边界

始终区分三层：

1. 设计层：页面地图、节点清单、尺寸推导、视觉 token、资产 manifest、动画时间序列、交互状态机和验收矩阵。
2. 场景层：宿主声明的受限 proposal DTO。它不是宿主内部场景 JSON；导入时由适配器校验、归一化、生成真实 ID 并写入历史。
3. 运行层：预览、动画、交互和媒体生命周期。运行状态不能写回静态 DTO。

如果用户只要不可编辑的平面图，不要强行生成场景 proposal。

内容丰富度与单页信息密度

生成的电子书、杂志、海报套件或长页不能停留在“一个标题 + 一张图 + 一句说明”的简化草稿。除非用户明确要求极简留白风格，否则每个页面都要有丰满且有组织的内容结构：主标题/导语、正文或要点、数据/事实/案例、图注或辅助说明、页码/章节信息，以及与页面目标相关的行动或导航信息。不同页面可以调整组合，但不能用重复句子、无意义装饰或虚构数据填充。

面向手机、平板和电脑阅读的杂志/H5，正文在目标窄屏实际显示字号默认不得小于 16 CSS px，建议行高为字号的 1.5–1.8 倍。固定画布缩放后若低于此值，应调整排版或提供适配阅读布局，不能只按设计稿画布上的字号判定合格。辅助文字可以更小，但仍须在真实渲染中清楚可辨。测量和验收方法见 [visual-acceptance.md](references/visual-acceptance.md)。

内容生成必须遵守：

• 多页作品的页数从来源文档/brief 自动推导：先提取章节、独立主张、证据、案例、步骤和结论，再按读者阅读任务、单页可读信息量、内容密度和叙事节奏组成页面。将推导后的页数与逐页内容地图写入设计稿，并简述依据；不要要求用户先指定页数或停下来等待页数确认。用户明确给了页数/一对一保留要求时，按该约束组织内容。12 页不能只是同一版式重复 12 次。
• 生成前先定义可见的风格系统：编辑立场、视觉性格、主辅色及面积倾向、标题/正文/数据字体角色、密度节奏、图像处理和可复用母题。用具体表现解释“现代/高级”等风格词，并按每页内容关系选择构图；完整方法见 [style-composition.md](references/style-composition.md)。
• 鲜艳色彩是默认方向之一：除非用户明确要求低饱和、黑白或极简灰阶，否则不得把全书统一处理成灰白底 + 单一蓝色。生成前必须建立至少 1 个主色、3 个高饱和辅助色和 1 个中性色；辅助色优先使用可辨识的高饱和色相，并记录预计面积比例、使用层级和对比度。重点结论、关键数据、产品优势和 CTA 必须使用强调色块、数字、标签、图形或边缘标记中的至少一种真实视觉承载，不能只换文字颜色。不同章节至少使用两组可辨识的色彩组合，单页至少有一个非灰阶视觉锚点。颜色变化必须服务页面角色（例如封面高对比、问题页暖色警示、能力页蓝绿系统、结尾使用品牌强调色），不能只随机换色。正文与背景的真实渲染对比度不达标时，优先调整背景面积和文字色，不以降低饱和度掩盖层级问题。
• 每页规划 pageJob 与节奏标签（anchor、dense、breathing），比较邻页和章节弧线；封面提取来源内容的具体 hook，结尾回收核心结论或来源支持的行动方向。可复用母题用于连续性，不得将其变成每页重复的同一套卡片模板。
• 页面使用可辨识的布局变化（如封面主视觉、目录分栏、时间线、数据图表、跨栏叙事、步骤清单、引言页、对比页、图文拼贴、结尾 CTA 等，具体以内容和宿主能力为准）。设计文稿要逐页记录唯一的 layoutVariant、网格/栏数、主视觉位置与图文比例；相邻页的主版式结构不能相同，全书按布局矩阵和 [visual-acceptance.md](references/visual-acceptance.md) 的差异率门槛验收。品牌色、字体和间距等设计系统可以统一；宿主能力不足以支持不同版式时，在设计确认前说明限制并与用户确认。
• 页面配色与布局一起参与结构验收：仅更换文案、装饰色或卡片标题，不算页面差异。需记录 colorSignature（背景色、主色、辅助色、强调色及面积比例）；连续页面不得同时复用相同的 layoutFingerprint 与 colorSignature。
• 设计文稿必须逐页写明页码/总页数、章节和前后页衔接、页面叙事作用、内容展示形式（如图表/流程图/时间线/对比表/正文/图片）及来源，并用普通语言描述动画大致效果、触发和作用对象；无动画写 none，不得把意向当成已实现。最后一页必须说明主题如何收尾、核心观点如何总结，以及适用的结尾行动引导/CTA；不适用 CTA 时说明原因。
• 每页至少规划一个主叙事单元和两个以上辅助信息单元。辅助单元可以是事实卡、数据点、时间线、步骤、引用、图注、术语解释、对比、目录导航或 CTA，具体组合由页面类型决定。
• 页面需要有“内容证据”：数据必须来自用户或可信输入；缺失时使用明确的待补字段或语义占位，不编造事实、统计数字、人物引语或来源。
• 长文本拆成可编辑的标题、导语、段落、列表、标签和图注，避免把整页内容塞进一个不可读的大文本框。
• 内容密度通过层级、网格、分栏、卡片、编号和留白组织；丰富不等于拥挤。任何新增内容都必须重新估算文本高度、图片比例、节点预算和重叠关系。
• 设计文稿必须记录每页的 contentUnits、informationGoal、evidenceSources、requiredUnits 和 optionalUnits。预算不足时优先保留主叙事、关键数据和必要图注，删除装饰而不是删除核心信息。

单页验收至少检查：内容单元是否达到页面目标、信息层级是否清楚、正文是否可读、数据是否有来源或占位标记、页面是否存在明显空洞区域、内容是否因超长被静默截断，以及所有内容是否仍在宿主节点预算和安全区内。只有“内容完整 + 布局可读 + 事实可追溯”才可进入静态确认。

先发现宿主能力

开始任何实现前，读取或询问宿主的适配器清单：

• 项目类型、画布预设、页面模型和输出渠道。
• proposal schema、节点白名单、预算、颜色/URL 安全规则和坐标单位。
• 按当前 projectType 核实实际可渲染的场景节点：交叉检查适配器/渲染器白名单与多份同类型真实文档的 tag 直方图。节点可写入、可回查或素材 URL 可访问，都不能证明该 tag 可见；演示文稿不得直接沿用其他类型的整页 Image 管线。
• 资产 API、模板 registry、槽位 schema、动画 preset、motion scene、custom node 和导出能力。
• 真实页面快照、稳定语义 key 到运行时 ID 的映射、版本和最近验证报告。
• 预览/导出副本、reduced-motion、运行时时钟、输入和清理 API。

没有这些事实时，只输出设计文稿、能力差异和待确认项；不要猜尺寸、ID、preset、插件配置或远程地址。宿主没有提供的能力标为 unknown、needs-adapter 或 unsupported。

五类输出类型与尺寸咨询

创建前必须先确定 projectType、页型（单页/多页）和每种画布的 canvasSpec。多页作品的 pageCount 根据来源文档或 brief 自动推导并记录理由，不要求用户指定。页型及动画边界如下：

以上页型和动画边界是生成约束：海报不得生成动画增量；H5 的长内容仍是一个页面；视频画册按多个分镜页面组织。若用户要多张海报或多个 H5 页面，应视为多个独立单页交付物，分别确认画布和数量，不能误当成单个多页项目。

文字度量与真实渲染门禁见 [visual-acceptance.md](references/visual-acceptance.md)：fontSize、lineHeight、letterSpacing 必须使用 px 绝对值，电子杂志默认逐页动画；静态草案一次生成全部页面，生成后逐页通过宿主或已核实的同引擎本地渲染门禁，远程写入前必须通过静态门禁。

电子杂志的一键完整生成规范：若宿主提供整本生成入口，该入口应在一次用户操作内连续完成内容地图、全部静态页、版式重排、动画分镜、质量检查和草稿保存。静态阶段不得设置“三张代表页”或其他少量页面门槛；必须生成整本后再逐页真实宿主验收。AI 返回不完整时只允许在内部有限重试，失败须保留既有草稿并报告阻断原因。

每种类型都必须核实画布宽度与高度，不能只记录方向或比例。缺尺寸时先询问，或让用户从宿主预设中选择；宽高比、实际宽高、单位、分辨率和安全区要互相匹配。不能沿用其他类型或历史任务尺寸。视频画册必须确认画幅方向：横版与竖版是两种独立的宽高配置；按目标渠道读取宿主预设或向用户确认实际宽×高/比例。若两种都要交付，建立两套独立 canvasSpec 并分别检查构图、安全区和字幕，不把一个画布简单拉伸成另一个。横版/竖版不等于固定像素值或必然比例，除非用户或宿主明确给出，不能擅自套用常见分辨率。

尺寸字段写入 canvasSpecs 数组，每种独立画幅一项：width、height、unit、orientation、aspectRatio、safeArea、bleed、resolution、frameRate、duration。通常一个交付物对应一项；双画幅视频必须分别记录横版和竖版，不能共用或推导未确认的数值。宽高必须显式确认或来自宿主预设；比例应与确认的宽高一致。不适用字段写 not-applicable，未知值写 unknown。尺寸确认与画布方案通过设计门禁前，不生成静态页面或动画。

按需读取：

• [asset-inventory.md](references/asset-inventory.md)：资产元数据、来源、授权、导入和降级。
• [audit_asset_manifest.py](scripts/audit_asset_manifest.py)：资产清单为 JSON 且需要校验字段、状态和重复 key 时运行。
• [capability-catalog.md](references/capability-catalog.md)：如何建立通用能力目录和适配器证据。
• [design-spec.md](references/design-spec.md)：完整视觉交互设计文稿。
• [style-composition.md](references/style-composition.md)：风格系统、页面角色/节奏、内容驱动构图和跨页母题。
• [production-workflow.md](references/production-workflow.md)：分阶段创建、修改和回归。
• [output-schema.md](references/output-schema.md)：设计包装、proposal、动画增量和 hook report。
• [hooks.md](references/hooks.md)：阶段门禁。
• [static-layout.md](references/static-layout.md)：节点清单、尺寸、布局和重叠审计。
• [visual-acceptance.md](references/visual-acceptance.md)：文字像素单位、结构差异、真实宿主渲染、视觉评分、动画核验和远程写入门禁；生成静态页及远程更新前必须读取。
• [leafer-rendering.md](references/leafer-rendering.md)：Leafer Node 初始化、CJK 字体、场景形态探针，以及 book 演示文稿的节点白名单/黑屏排查、增量重渲染和审计复核；宿主使用 Leafer 时必须读取。
• [complex-animation.md](references/complex-animation.md)：复杂动画状态机。
• [animation-pitfalls.md](references/animation-pitfalls.md)：动画目标、时序、回调和静态回退的常见风险；生成动画时读取。
• [interactive-runtime.md](references/interactive-runtime.md)：交互运行时生命周期。
• [dimens-integration.md](references/dimens-integration.md)：远程项目/页面认证、CRUD、先读后改和写后回查；涉及维表智联资源时必须读取。

资产先行

先扫描用户提供的文件、宿主资产 API 和模板 registry，再建立 manifest。每项资产记录真实 key/id、来源范围、状态、原始名称、MIME/扩展名、大小、尺寸/比例或时长、透明/色彩、焦点和安全区、可编辑性、导入方式、依赖、授权证据、验证状态、替代资产和 fallback。不可得值写 unknown，不可从文件名、标签、URL 或历史说明推断。

来源范围使用通用枚举：bundled、builtin、session-upload、project-upload、remote、archive。归档资源只作设计或迁移参考，不能直接复活为可用资产。图片、SVG、音频、视频和字体分别读取对应技术元数据；许可证据与技术可读性分开记录。

当画面需要照片背景、场景图或氛围图，而用户/项目没有合适图片时，可以直接选用 Unsplash 上可访问的图片 URL 作为替代素材来源。必须使用真实可访问的图片地址，不编造 URL；在 manifest 记录 Unsplash 来源页/图片 URL、用途、宽高/比例、裁切焦点和许可核验状态，并验证目标宿主能加载、预览和导出。Unsplash 来源不代表尺寸、持续可用性或许可已自动验证。按宿主导入协议将图片登记/导入为资产；若宿主明确支持远程 URL 资产可按其 API 使用，否则 proposal 仍引用 manifest key，不将任意外链直接塞进内部场景 JSON。加载失败时提供替代 URL 或语义占位符。

当前 proposal 只引用 manifest key 或语义占位符；真实 URL、data URL、音视频对象、字体文件、SVG scene、模板 payload 和任意脚本必须走宿主导入协议。

能力路由

先建立能力矩阵，再选择实现路径：

历史模板或旧脚本要先做 API、schema、资源、生命周期、导出和测试证据的迁移清单；迁移完成前保持 archive-only，不复制旧源码。

分阶段工作流

新建项目时严格按此门禁顺序推进：先提交设计文档并取得用户确认 → 内容到布局路由 → 真实布局指纹预算 → 最小宿主渲染探针 → 一次生成全部静态页 → 自动同质化/越界/字号检查 → 逐页用宿主或已核实的同引擎本地渲染及视觉标准验收 → 静态门禁 → 按类型策略生成动画（电子杂志默认必须生成，除非用户明确要求静态；海报纯静态）→ 验证动画字段、目标、autoplay、回调及生命周期 → proposal 转换为 EditorDraft 并校验 → 登录维表并创建项目/页面草稿 → 保存并全量回查 → 按要求执行预览和导出验收。修改已有项目是例外：必须先登录并完整读取项目及全部页面，才能基于真实基线撰写/确认修改文档；但任何远程更新仍须等静态修改、动画及回调验证完成后。宿主与可比对的同引擎本地渲染都不可用、文字/结构/视觉门禁失败或动画审计未通过时，禁止远程写入。用户明确跳过适用阶段时记录原因与状态，不把跳过写成通过。

端到端执行流程图（创建 → 验证 → 上传草稿）

执行任务时必须沿箭头推进；每个菱形都是硬门禁，未通过只能回到标注的修复节点，不能直接上传草稿。流程终点是远程草稿完成预览/导出验收，后续公共分发不在本技能范围内。

flowchart TD
    A[接收 brief 与来源] --> B[确认 projectType、页型、宽高与渠道]
    B --> C{尺寸与宿主能力齐全?}
    C -- 否 --> C1["记录 unknown / needs-adapter<br/>补齐事实或向用户询问"] --> B
    C -- 是 --> D["扫描资产与模板<br/>建立 manifest、内容地图、能力矩阵"]
    D --> E[编写版本化设计文稿]
    E --> F{用户已确认设计文稿?}
    F -- 否 --> E1[等待确认或修订设计文稿] --> E
    F -- 是 --> G[内容目标到布局类型路由]
    G --> G0[计算真实 layoutFingerprint 预算]
    G0 --> G1{最小宿主渲染探针通过?}
    G1 -- 否 --> G2["仅保留 design-only<br/>记录阻断，不得远程写入"] --> D
    G1 -- 是 --> H[一次生成全部静态 proposal]
    H --> H1["运行字段、同质化、越界和字号审计<br/>audit_layout_diversity.py"]
    H1 --> H2{自动静态审计通过?}
    H2 -- 否 --> H3["修复页面内容/节点骨架<br/>重新计算 fingerprint 并审计"] --> H
    H2 -- 是 --> I["逐页真实宿主/同引擎渲染<br/>做字体、bounds、安全区、密度和结构差异检查"]
    I --> J0{静态门禁通过?}
    J0 -- 否 --> I1["定位页面/节点问题<br/>增量修复并重新渲染"] --> H
    J0 -- 是 --> J["按类型生成或跳过动画<br/>（杂志默认逐页入场）"]
    J --> K[验证目标 ID、autoplay、回调、清理、静态回退]
    K --> L{动画/交互门禁通过?}
    L -- 否 --> J1["修复动画/交互或标记 unsupported<br/>回退到静态基线"] --> J
    L -- 是 --> M[proposal → EditorDraft 转换并校验]
    M --> M1{Draft 结构与 ID 映射通过?}
    M1 -- 否 --> M2["修复转换器或字段映射<br/>保留本地产物"] --> M
    M1 -- 是 --> N0[登录并确认 team/project/page 上下文]
    N0 --> N[创建或合并更新维表项目/页面草稿]
    N --> O["写后全量回查<br/>ID、页数、顺序、revision、节点、资产、动画状态"]
    O --> P{远程回查与本地交付一致?}
    P -- 否 --> N1["重新读取最新版本、合并并重试<br/>保留未知字段"] --> N
    P -- 是 --> Q[平台预览与私有导出验证]
    Q --> R{预览/导出门禁通过?}
    R -- 否 --> Q1[记录阻断并回到对应设计/静态/动画阶段] --> H
    R -- 是 --> V[输出草稿验收报告与产物路径]

流程节点与状态约定

状态不可跨级伪造： design-only → proposal-generated → schema-validated → imported → preview-verified → export-verified。写入成功只能进入 imported；回查成功不能替代预览；预览成功不能替代导出。export-verified 是本技能的交付终点。

0. 设计文稿

输出并确认完整设计文稿：范围、页面地图、节点/尺寸/位置、样式和资产 manifest、动画、交互、能力矩阵、验收、假设和待确认项。创建和修改都必须有版本；修改必须声明基线、影响节点、未改变字段、失效 hook 和回滚点。修改已有项目时，先依照“修改”流程读取并核实项目全部页面快照，再基于该完整基线编写/确认修改设计文稿；不得先按不完整或未知基线确认修改方案。

设计文稿确认后进入静态内容生成，不能因此提前创建远程项目/页面。新建项目待静态页数据、动画及回调验证完成后，才登录维表并创建项目/页面。修改现有项目则须先登录并读取项目详情、全部页面快照、版本基线和资源归属，完成修改设计文稿确认、静态修改及动画/回调验证后再远程更新。详见 [production-workflow.md](references/production-workflow.md) 与 [dimens-integration.md](references/dimens-integration.md)。

一键完整生成协议

对于电子杂志，单次用户操作可以在内部连续完成内容地图、全部静态页、版式重排、动画分镜、质量检查和草稿保存；不得要求用户逐页生成、逐页确认或手工补齐。每页必须有 pageJob、主叙事、至少两个辅助信息单元和 evidenceSources。布局指纹必须来自真实节点的网格/栏数、主视觉位置、节点角色、阅读顺序和节奏；相邻页面不得重复，全书页面对至少 80% 结构不同。动画优先使用宿主已登记的复杂 preset、timeline 和 motion scene，至少组织建立场面、叙事揭示、强调收束轨道，并验证目标 ID、enabled、autoplay、reduced-motion 与静态最终态回退。

内容目标到布局路由

先确定页面要让读者理解的内容目标，再选择布局骨架；不能先套卡片模板再填文案。相邻页面禁止连续复用同一优先布局。

真实布局指纹与同质化审计

layoutVariant 只能作为人类可读标签，不能作为差异证据。静态 proposal 生成后，必须从真实节点重新计算 layoutFingerprint，至少包含 gridColumns、primaryVisual、nodeRoles、readingOrder、density、主视觉面积比例和归一化几何模板。仅改颜色、文案、间距或 layoutVariant，而真实指纹相同，必须判定失败。

运行 [audit_layout_diversity.py](scripts/audit_layout_diversity.py)：

python3 scripts/audit_layout_diversity.py path/to/proposal.json > layout-audit.json

审计器必须输出页面结构相似度矩阵、相邻重复数、全书两两差异率、节点角色分布和每页真实 fingerprint。默认门槛为：相邻页相似度 < 0.75，全书两两结构差异率 ≥ 80%；任一门槛失败即 blocked，回到页面内容/节点骨架生成，不得远程写入。审计器计算出的 fingerprint 才能写入设计文稿和验收报告。

页面内容契约

每页必须同时具备以下字段，缺失任意字段都不能进入静态 proposal：

{
  "pageJob": "说明问题",
  "informationGoal": "让读者理解统一工作台的必要性",
  "contentUnits": ["主标题", "导语", "三条痛点", "页脚来源"],
  "requiredUnits": ["headline", "body", "source", "pageNumber"],
  "optionalUnits": ["quote", "diagram"],
  "evidenceSources": ["产品说明.md#解决的业务问题"]
}

contentUnits 至少包含一个主叙事单元和两个辅助信息单元；来源缺失写 needs-source 或 placeholder，不能用重复文案或虚构数据补齐。

最小宿主渲染探针

全量生成前，使用当前宿主和当前 projectType 生成 1 页最小探针，至少包含中文标题、正文、矩形、圆形和一项动画。记录宿主版本、节点白名单、字体 alias、画布尺寸、场景加载路径和渲染入口，并检查非背景像素、文字行框、CJK 字体、节点尺寸和动画字段。探针失败时只允许保留 design-only，禁止创建或更新远程项目/页面；探针通过后才能生成整本。

proposal → EditorDraft 转换

远程导入前必须显式执行并记录 convertProposalToEditorDraft()：将语义页面 key 映射为数字页面 ID，将 activePageId 映射为 activePage，同步重映射场景 key 与页面 ID，并保留宿主要求的 settings、viewMode、canvasPresetId 和未知字段。转换器输出必须通过 schema 校验、页面数量校验、ID 引用校验和字段保留校验；不能依赖临时脚本隐式转换。

生成失败复盘

每次生成或修复都要在 hook report 记录：generationAttempt、failedGates、repairStrategy、previousSnapshotRevision、rollbackPoint、userFeedback。同质化失败后，下一次生成必须把上一版真实节点骨架列为禁止复用约束，并在审计报告中给出新的相似度矩阵。

1. 静态 proposal

先列节点，再按真实宿主字体计算文本尺寸，再布局；所有 fontSize、lineHeight、letterSpacing 在 proposal 中用 px 绝对数值表示。对文本与图形做实际 bounds 相交和画布/安全区检查，不以坐标合法代替布局验收。只使用宿主白名单节点和预算。若宿主存在两种页面数据形态，先为每种形态做最小真实渲染探针，只选择有非背景内容像素、正确尺寸和中文字体证据的形态；无证据时停留在 design-only/blocked。宿主为 Leafer 时先读取 [leafer-rendering.md](references/leafer-rendering.md)。按 [visual-acceptance.md](references/visual-acceptance.md) 一次生成全部静态页，再逐页使用宿主或已核实的同引擎本地渲染，并满足页面结构差异与逐页视觉评分硬门槛，之后确认静态基线。视觉查看必须遵守上述禁令。

演示文稿的 book 场景先按实测白名单校验每个节点，不允许以整页 PNG/CDN Image 作为未经验证的回退。先在同引擎中用含正文的最小页探针确认内容像素，再逐页检查非背景内容、文本行框、越界/重叠/容纳与实际结构差异；写后逐字段对账。book page list 的页数、顺序、节点和 URL 全对，也只证明 schema 往返，不证明编辑器渲染。平台无预览/导出接口时将最终编辑器画面留给用户刷新眼验，并在报告中保留该未验证项。

2. 动画与回调验证

仅在静态版本确认后执行。电子杂志默认每页都有进入动画，用户明确要求静态时才跳过；海报固定跳过动画。凡设计文稿含动画意向，必须在真实宿主支持的 animations、animationSequence 或 timeline 字段实现，并校验每页目标 ID 存在、动画启用和 autoplay（适用时）。优先宿主已登记 preset；复杂效果拆为状态机、时间序列和生命周期适配器。声明稳定语义 key、真实 ID 映射、暂停/恢复/取消、reduced-motion、静态导出回退和有限无环完成链。按宿主实际提供的契约列出回调/生命周期事件，记录触发条件、预期次数、关键参数/目标 ID、实际结果、超时/错误和清理结果；用受控预览或宿主测试入口逐项验证，检查重复触发、取消后迟到回调及旧版本回调。宿主未提供回调能力时标记 unsupported，不得臆造 API 或报告通过。

Keynote 风格动画编排约束

• 不得把所有页面默认生成为 fade-in 或 fade-up。必须先读取宿主真实 AnimationPreset 白名单，将每个 preset 归入语义族，再按页面角色选择。用户所说的 30+ 动画必须落成宿主真实可用的 30+ preset；下面的名称是选择语义，不是可直接猜测的 API key，实际 key 必须来自当前宿主 registry，找不到映射就标记 unsupported：

宿主能力不足时按可用语义族降级，并记录缺失族；不得用一个 fade preset 冒充 30+ 能力。

• 多页演讲型项目（presentation、magazine）若页数不少于 6，至少使用 5 个不同语义族；同一主进入族不得覆盖超过 40% 页面，透明/模糊族合计不得超过 30%，除非宿主白名单确实不足并在报告中给出证据。电子杂志默认每页有动画，动画类型必须随 pageJob、构图方向和讲述节奏变化。
• 每页至少组织三条动画轨道：establish（建立场面）、reveal（揭示内容）、emphasize（强调结论）。轨道必须有明确目标 ID、开始时间、持续时间、缓动和完成态；不允许只给一个节点挂一个淡入效果就算完成。
• 页面之间要形成动效节奏：封面用缩放/翻转/共享元素转场建立空间感；问题页用相反方向的推入表达对比；时间线和矩阵用方向滑入、路径移动与分组 stagger；数据页用聚焦、计数或逐项揭示；结尾 CTA 用一次弹性或聚焦强调。相邻页面不得连续使用相同的主进入 preset，除非设计文稿说明是章节转场。
• 方向类动画必须与构图方向一致：左侧进入的节点使用 slide-left，右侧进入的节点使用 slide-right；上下分层结构使用 fade-up/fade-down；禁止动画方向与阅读顺序相反。
• 每页至少有一次分组 stagger 或 with/after 关系，建议 80–180ms；总进入时长默认 900–1800ms，避免所有节点同时出现或逐字慢播。关键结论应在正文后 120–300ms 出现，形成演示节奏。
• 动画审计必须输出每页的 primaryPreset、presetFamily、preset 数量、目标数量、轨道数、stagger、总时长和静态最终态；报告全书的 preset 总数、语义族数量、页面族分布、primaryPreset 重复率和透明/模糊占比。primaryPreset 全书唯一率至少 50%，动画 preset 分布不能全部集中在透明淡入类。
• reduced-motion 模式必须跳过位移、翻转、模糊和弹跳，只保留静态最终态或低强度透明切换；导出不得依赖动画播放完成。

3. 交互

动画完成或明确跳过后执行。简单 click/hover 使用受限绑定；键盘、触摸、连续 tick、碰撞、计分和游戏使用独立 runtime。规则用纯 reducer/state machine，宿主提供单一时钟；dispose 必须幂等并释放监听器、计时器、RAF、媒体、纹理、Object URL 和 DOM。

4. 集成验收

导入、预览和导出使用版本化私有副本。逐项验证场景往返、ID 引用、资产加载、字体 fallback、SVG 保真、媒体行为、reduced-motion、静态回退、移动端和修改回归。多页项目记录逐页翻页/渲染结果；涉及用户要求时记录移动端视口、PNG/PDF 导出文件与页数。必须区分 design-only、proposal-generated、schema-validated、imported、preview-verified 和 export-verified，未实际执行的检查保留 not-verified。

远程项目或页面还必须通过依赖技能写后回查：项目详情、页面列表、页面顺序、快照版本、资产引用和动画/交互状态都要与本地交付报告一致。本技能只保存和验收远程草稿。

禁止宣称

• 有文件不等于资产可用；有 URL 不等于授权成立。
• registry 或 helper 存在不等于 AI 可以自由生成该能力。
• proposal 通过不等于导入、预览或导出通过。
• schema 往返通过不等于渲染通过；有效 CDN src 不等于宿主支持 Image 节点。纯底色 PNG、非空文件或快照哈希一致也不构成内容可见证据。
• 历史脚本、归档模板和设计草稿不等于当前运行时实现。
• 未验证的尺寸、时长、DPI、色彩、字体、版权、性能和浏览器行为必须保持 unknown。

最终响应

按以下格式报告：

阶段：设计文稿 | 静态提案 | 动画增量 | 交互运行时 | 集成验收
宿主能力来源：<适配器/用户提供的清单和版本>
设计文稿：<路径或摘要>
已生成：<产物、版本和状态>
验证：<schema、布局、动画、运行时、资产和导出证据>
阻断/待确认：<事实缺口、授权、资源、能力或版本问题>
下一步：<通过门禁后唯一可推进阶段>