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

更新日期：2026-04-26

## 背景

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

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

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

## 经验原则

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

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

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

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

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

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

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

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

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

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

更稳的结构是：

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

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

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

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

替换逻辑：

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

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

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

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

## 检查清单

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

## 验证建议

```bash
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
```

## 提交备注模板

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

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

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