PPT 提示词分层与大纲替换经验总结

更新日期：2026-04-26

背景

这次优化涉及两个容易反复踩坑的问题：

PPT 生图提示词需要同时保证“整套风格统一”和“单页内容具体”，但全局规则如果每页都重复，会让单页提示词冗长且难维护。
一个画布只允许有一套 PPT，再次执行“生成PPT大纲”时应该替换旧 PPT，而不是把新大纲追加到旧大纲后面。

核心经验是：全局约束要沉到公共提示词，单页提示词只描述本页差异；PPT 语义要以 pptMeta 为边界，替换时只清理已有 PPT 及其绑定内容。

经验原则

1. 公共提示词承载全局设计系统

公共提示词适合放所有跨页不变的规则：

核心生成要求，例如输出整页 16:9 幻灯片、文字语言、只渲染白名单文字。
设计一致性，例如色板比例、字体继承、组件复用、重复视觉母题、对比度和留白。
单页设计边界，例如不得为单页创造新色板、新字体体系、新画风或新组件样式。
禁止事项，例如不要把“封面页”“页面标题”“视觉概念”等字段名渲染进画面。

这些规则如果放进每页提示词，会造成重复、增加 token，也会让后续维护时出现公共约束和单页约束不一致。

2. 单页提示词只描述本页差异

单页提示词应该尽量短，只保留本页需要变化的内容：

画面可见文字白名单。
当前页用途、版式、标题语义、内容语义。
本页视觉锚点。
版式指导。
上一页/下一页摘要。
用户额外要求。

这样每页提示词只负责“这一页怎么表达”，不负责重复定义“整套 PPT 应该是什么风格”。

3. 可见文字和结构说明必须分层

图片模型容易把提示词里的字段名当成幻灯片文字渲染出来。

更稳的结构是：

画面可见文字：唯一允许出现在幻灯片上的文本。
设计参考信息：只供模型理解页面用途和版式，不允许渲染。
公共禁止事项：统一约束所有页面，不在每页重复。

这比只过滤“封面”“大纲”几个词更可靠。

4. 单画布单 PPT 要在工具入口替换

generate_ppt 是创建 PPT 大纲的唯一工具入口，因此替换旧 PPT 应在新 Frame 创建前完成。

替换逻辑：

用 isFrameElement(element) && element.pptMeta 识别已有 PPT Frame。
用 FrameTransforms.getFrameContents(board, frameIds) 收集 PPT Frame 及其 frameId 绑定内容。
额外收集 pptMeta.slideImageElementId 和 pptMeta.slideImageHistory[].elementId，避免旧图片脱离 frame 绑定后残留。
通过 ID 倒序 Transforms.removeNode 删除，避免删除过程中索引漂移。
普通 Frame 和非 PPT 内容不清理。

5. 文案也要同步真实行为

当工具行为从“追加新 Frame”变成“替换已有 PPT”后，内置 Skill 文案和 MCP tool warnings 必须同步。

否则 Agent 可能继续按旧语义提示用户，或让用户误以为多次执行会保留多套 PPT。

检查清单

公共提示词包含设计一致性、单页边界和禁止事项。
单页提示词不再重复输出公共规则块。
单页提示词仍保留可见文字、视觉锚点、版式指导和相邻页上下文。
再次执行 generate_ppt 会删除旧 PPT 页面及其绑定内容。
旧 PPT 的当前图和历史图引用不会残留。
普通 Frame 不受 PPT 替换影响。
Skill 文案明确“同一画布只保留一套 PPT”。

验证建议

pnpm --dir packages/drawnix exec vitest run \
  src/services/ppt/__tests__/ppt-prompts.test.ts \
  src/mcp/tools/__tests__/ppt-generation.test.ts \
  --no-file-parallelism --maxWorkers=1

提交备注模板

问题描述:
- PPT 单页提示词重复携带全局设计边界和禁止事项，导致提示词冗长且公共约束难维护。
- 同一画布多次执行“生成PPT大纲”会追加多套 PPT，不符合单画布单 PPT 的产品约束。

修复思路:
- 将全局设计一致性、单页边界和禁止事项集中到公共提示词。
- 单页提示词只保留可见文字、视觉锚点、版式指导和相邻页上下文。
- 在 `generate_ppt` 创建新 Frame 前，按 `pptMeta` 清理旧 PPT 页面、绑定内容和历史图片引用。

更新代码架构:
- PPT prompt 层按公共提示词和单页提示词分层。
- PPT 替换逻辑集中在 `generate_ppt` 工具入口，不新增 PPT 实体。

4.5 KiB Raw Blame History Unescape Escape