Initial TrueGrowth source import

docs/PPT_PROMPT_LAYERING_AND_REPLACEMENT_LESSONS.md

@@ -0,0 +1,104 @@
+# 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 实体。
+```