# PPT 大纲生成与受控生图经验总结

更新日期：2026-04-26

## 背景

PPT 生成从“一次性生成完整 PPT 图片”改成了“两段式流程”：

1. 先用文本模型生成公共风格提示词和每页 PPT 提示词，并创建占位 Frame。
2. 用户在 PPT 编辑的大纲视图中检查、优化、勾选页面，再选择图片模型和串行/并行策略生图。

这个改动的关键不是多加一个 UI，而是把“规划内容”和“消耗图片额度的执行动作”解耦。

## 经验原则

### 1. Skill 的模型选择要跟真实执行成本一致

“生成 PPT 大纲”只调用文本模型，不应该在底部输入栏暴露图片模型选择。

图片模型选择应该出现在真正提交图片任务的位置，也就是 PPT 大纲底部的“生成”操作旁边。这样用户能在确认提示词之后，再决定用哪个图片模型执行。

### 2. 工具名兼容不等于语义不变

底层仍可保留 `generate_ppt` 作为 MCP 工具名，避免破坏 workflow、agent parser 和旧配置。

但产品语义已经变成“生成 PPT 大纲”，所以：

- Skill 名称和空态提示应使用新文案。
- `generate_ppt` 路由只注入 `textModel/textModelRef`。
- 媒体模型推断不能再把 `outputType: 'ppt'` 当作图片输出。

### 3. 生图入口要有局部限流

PPT 大纲批量生图不要直接循环放飞 `createImageTask()`。

更稳的策略是：

- 串行：等待上一页生成成功，再把上一页图片作为当前页参考图。
- 并行：不传参考图，最多 5 个在途任务，完成一个补一个。

这个限流放在 PPT 大纲批量生成控制层即可，不需要顺手重构全局图片队列。

### 4. 大纲数据应复用现有 PPT 元数据

不要为了大纲视图新增一套 PPT 实体。

当前更轻的结构是：

- 每页提示词继续存 `pptMeta.slidePrompt`。
- 公共风格提示词存 `pptMeta.commonPrompt`。
- 结构化风格规格继续复用 `pptMeta.styleSpec`。

这样 PPT 视图、导出、播放、排序和单页重生成仍围绕 Frame 工作。

### 5. 抽屉 UI 要为窄宽度设计

项目抽屉不是主画布，控件必须紧凑：

- 顶部模式切换和工具按钮放在同一行。
- 底部选择数量应合并进选择按钮，例如 `取消2/2`。
- 生图按钮不要带多余图片 icon。
- 图片模型选择器和生成按钮同组靠右，宽度受控，避免撑破抽屉。

### 6. 提示词优化属于编辑能力，不属于生成流程

公共提示词和每页提示词都应能单独优化。

优化结果应只回填当前输入框并写回对应 `pptMeta`，不要自动触发生图。这样用户可以继续审查提示词，也避免误消耗图片任务。

### 7. 生图提示词必须区分“可见文字”和“结构说明”

整页 PPT 生图时，模型很容易把提示词里的字段名、页面角色或结构标签当成画面文字渲染出来，例如“封面：”“大纲：”“PPT 大纲”。

更稳的提示词结构是：

- 先给出“画面可见文字”白名单，只允许这些文本出现在幻灯片上。
- 再给出“设计参考信息”，明确它只供理解页面用途、版式和语义，不可作为画面文字。
- 对封面页使用“开场主视觉页”等用途描述，避免把“封面页”当成可见标题。
- 对大纲返回的 `title/subtitle/bullets` 做轻量清洗，剥离“封面：”“大纲：”“页面标题：”等提示词字段前缀。
- 公共提示词也要强调禁止渲染字段名、结构标签、引号、冒号、JSON/Markdown 标记或列表编号。

这类修复不应该只靠过滤某两个词。核心是建立“最终可见文字”和“给模型看的说明”的边界，否则后续换模型或用户输入稍变，仍会复现。

## 检查清单

- 选择“生成 PPT 大纲”时，底部输入栏只展示文本模型。
- `generate_ppt` workflow 参数不包含图片模型字段。
- 生成大纲后自动打开 PPT 编辑并切换到大纲视图。
- 公共提示词和每页提示词可编辑、可优化、可写回 `pptMeta`。
- 每页整图提示词包含“画面可见文字”白名单，结构说明不会被当成画面文字。
- 封面/目录/大纲等页面角色只作为版式语义，不以“封面：xxx”“大纲：xxx”形式进入可见文字。
- 大纲底部图片模型选择器会传给 `createImageTask`。
- 串行模式会把上一页已生成图片作为参考图。
- 并行模式最多 5 个在途任务，且不传参考图。
- PPT 视图、播放、导出、排序和手动重生成仍可用。

## 验证建议

```bash
pnpm --dir packages/drawnix exec vitest run \
  src/components/ai-input-bar/__tests__/skill-media-type.test.ts \
  src/components/ai-input-bar/__tests__/workflow-converter.test.ts \
  src/services/agent/__tests__/media-model-routing.test.ts \
  --no-file-parallelism --maxWorkers=1

pnpm nx run drawnix:typecheck
```

## 提交备注模板

```text
问题描述:
- 原“生成完整PPT”会把大纲生成和图片生成绑在一起，用户无法先审查提示词，也容易一次性提交大量图片任务。
- 改名为“生成PPT大纲”后，输入栏仍显示图片模型，模型选择位置和真实执行点不一致。

修复思路:
- 将 `generate_ppt` 调整为只生成大纲、公共提示词、每页提示词和占位 Frame。
- 在 PPT 大纲底部提供图片模型选择器、串行/并行切换和受控批量生成。
- 媒体模型路由中将 `generate_ppt` 视为文本规划工具，只注入文本模型。
- 单页生图提示词用“画面可见文字”白名单隔离最终渲染文字和结构说明。

更新代码架构:
- PPT 大纲编辑能力集中在 FramePanel 的 PPT 编辑面板内。
- PPT 提示词继续复用 `pptMeta`，不新增 PPT 实体。
- PPT 批量生图限流只落在大纲生成入口，不影响全局图片队列。
```