Initial TrueGrowth source import

docs/PROMPT_HISTORY_SYNC_LESSONS.md

@@ -0,0 +1,79 @@
+# 提示词历史同步经验
+
+更新日期：2026-04-27
+
+## 背景
+
+“我的提示词”和提示词选择器曾经分别从通用历史、图片/视频本地历史、任务历史和预设排序状态中取数。多个入口都能置顶、删除、编辑标题或新建提示词，但没有统一的变更通知和事实源，导致同一条提示词在不同入口里出现新增不可见、标题不同步、置顶状态不一致等问题。
+
+## 经验
+
+1. 提示词内容状态必须只有一个事实源
+
+置顶状态不能同时由 `promptHistoryCache` 和 `presetDataCache[type].pinnedPrompts` 各自决定。更稳定的规则是：
+
+- `promptHistoryCache` 的 content pinned 是最终事实源
+- `presetDataCache[type].pinnedPrompts` 只用于保留同类型排序辅助
+- 取消置顶时同步清理所有类型的旧 pinned 排序记录
+- 排序时可以参考辅助顺序，但是否置顶必须回到 content pinned 判断
+
+2. 选择器候选集要覆盖同类型“我的提示词”
+
+图片/视频选择器如果只合并本地图片/视频历史、任务历史和默认预设，那么“我的提示词”中新建的图片/视频记录不会进入候选集。
+
+落地原则：
+
+- 图片选择器合并 `modelType=image` 的通用历史
+- 视频选择器合并 `modelType=video` 的通用历史
+- 仍然过滤不同类型历史，避免 PPT 页面、视频提示词污染图片入口
+- 去重前先走 `resolveContent`，保证编辑后的内容参与合并
+
+3. 展示元数据和发送内容要分开
+
+标题修改失败的根因不是标题没保存，而是图片/视频选择器路径没有读取 `resolveMetadata`。提示词列表项应同时携带：
+
+- `content`：点击后回填的提示词内容
+- `title`：列表展示标题
+- `tags`：轻量标签
+- `sentPrompt`：实际发送内容，用于详情/hover 展示
+
+不要为了展示标题修改 `content`，否则会破坏回填和去重语义。
+
+4. 跨组件刷新不能只靠打开时重新读
+
+只在 hover 打开、手动刷新或本组件 action 后重新读，会让已打开的选择器保留旧数据。存储层需要提供轻量订阅。
+
+落地原则：
+
+- 存储服务暴露 `subscribeChanges(listener)`
+- 新增、删除、置顶、取消置顶、元数据编辑后广播
+- 多个连续写入用微任务合并，避免短时间重复刷新
+- 选择器和弹窗订阅广播后只 bump 本地版本号，不做昂贵同步
+
+5. 无结果提示词可以编辑发送内容
+
+已有结果的任务提示词和生成结果绑定，直接改发送提示词会让历史结果失真。无结果提示词则更像用户维护的提示词资产，应允许编辑内容。
+
+落地原则：
+
+- `resultCount > 0` 的记录：发送提示词只读
+- `resultCount === 0` 的记录：发送提示词可编辑
+- 保存时显式传 `allowSentPromptEdit`
+- 服务层通过 `setContentEdited` 迁移内容、置顶和覆盖关系
+
+## 实现要点
+
+- `prompt-storage-service` 负责统一存储缓存、置顶事实源和变更广播。
+- `prompt-utils` 负责选择器候选集合并、去重、排序、元数据补齐。
+- `PromptInput`、`PromptHistoryPopover`、图片/视频生成弹窗只订阅变更并触发轻量重算。
+- `PromptHistoryTool` 只在无结果记录中放开发送提示词编辑，其它任务历史保持只读。
+- 测试要覆盖“双向置顶一致”“新增同类记录可见”“标题元数据同步”“广播后刷新”“无结果可编辑”。
+
+## 回归检查清单
+
+- 在“我的提示词”新建图片/视频提示词后，对应选择器是否立即可见？
+- 在任一入口置顶/取消置顶后，另一个入口是否状态一致？
+- 修改标题后，选择器是否显示新标题，同时点击仍回填原提示词内容？
+- 打开的选择器是否能响应其它入口的新增/编辑/置顶广播？
+- 无结果记录是否可编辑发送提示词，有结果记录是否仍只读？
+- 删除/隐藏是否不会留下旧 pinned 排序状态？