TrueGrowth/docs/PPT_OUTLINE_GENERATION_FLOW_LESSONS.md

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 视图、播放、导出、排序和手动重生成仍可用。

验证建议

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

提交备注模板

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

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

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