feat: add version history and AI diff highlighting in editor
This commit is contained in:
336
docs/E18_VERSION_AND_DIFF_PROPOSAL.md
Normal file
336
docs/E18_VERSION_AND_DIFF_PROPOSAL.md
Normal file
@@ -0,0 +1,336 @@
|
||||
# E18: 版本回滚 & AI 修改标记
|
||||
|
||||
## 概述
|
||||
|
||||
为编辑器的 AI 助手增加两个生产级功能：
|
||||
1. **版本回滚** — AI 修改前自动存档，错误时可恢复到任意历史版本
|
||||
2. **修改标记** — AI 修改后在 SceneGraph 节点上显示角标（新增/修改/删除），视觉可感知变更
|
||||
|
||||
---
|
||||
|
||||
## 一、版本回滚
|
||||
|
||||
### 流程
|
||||
|
||||
```
|
||||
用户发起 AI 请求
|
||||
→ buildMessage → POST /api/ai
|
||||
→ AIPanel.send() 在调用 sendAIRequest 前：
|
||||
editorStore.saveVersion("AI 修改前")
|
||||
→ AI 修改完成 → reloadFromDisk() → gameData 刷新
|
||||
|
||||
用户发现改错了
|
||||
→ AIPanel 版本下拉 → 选择历史版本
|
||||
→ editorStore.restoreVersion(index)
|
||||
→ gameData = version.gameData → autoSave()
|
||||
→ SceneGraph + NodeEditor 重绘
|
||||
```
|
||||
|
||||
### 涉及文件
|
||||
|
||||
| 文件 | 改动 |
|
||||
|------|------|
|
||||
| `editor/stores/editorStore.ts` | 新增 `versions` ref、`saveVersion(label)`、`restoreVersion(idx)` |
|
||||
| `editor/db/editorDB.ts` | **新建** — IndexedDB 封装：`put`/`get`/`clear`，按 `sourcePath` 分组 |
|
||||
| `editor/components/AIPanel.vue` | 新增版本下拉 UI（在聊天区顶部），send() 前调用 `saveVersion()` |
|
||||
|
||||
### 版本数据结构
|
||||
|
||||
```ts
|
||||
interface EditorVersion {
|
||||
id: string // crypto.randomUUID()
|
||||
sourcePath: string // "/scenes/demo.json"
|
||||
timestamp: number // Date.now()
|
||||
label: string // "AI 修改前" / "初始版本"
|
||||
gameData: GameData // 完整游戏数据快照
|
||||
}
|
||||
```
|
||||
|
||||
### IndexedDB 设计
|
||||
|
||||
```
|
||||
数据库: editor_versions
|
||||
表: versions
|
||||
索引: sourcePath (查询同一文件的所有版本)
|
||||
索引: timestamp (排序)
|
||||
```
|
||||
|
||||
保留策略：同一 `sourcePath` 最多 20 个版本，超出删除最旧的。
|
||||
|
||||
### editorDB.ts API
|
||||
|
||||
```ts
|
||||
// 保存版本
|
||||
putVersion(v: EditorVersion): Promise<void>
|
||||
|
||||
// 获取某文件的所有版本（按时间倒序）
|
||||
getVersions(sourcePath: string): Promise<EditorVersion[]>
|
||||
|
||||
// 清除某文件的所有版本（切换文件时）
|
||||
clearVersions(sourcePath: string): Promise<void>
|
||||
```
|
||||
|
||||
### 版本 UI 设计
|
||||
|
||||
```
|
||||
AIPanel 顶部
|
||||
┌──────────────────────┐
|
||||
│ 历史版本: [AI 修改前 ▼] │ ← 下拉列表，默认隐藏
|
||||
│ 2026-06-15 14:30 AI 修改前 │
|
||||
│ 2026-06-15 14:28 初始版本 │ ← restoreVersion 后刷新全部
|
||||
└──────────────────────┘
|
||||
```
|
||||
|
||||
恢复后逻辑：
|
||||
1. `gameData = version.gameData`
|
||||
2. `autoSave()` 写回磁盘
|
||||
3. `selectedNodeId = null`（重置选中）
|
||||
4. AIPanel 聊天区显示 "已恢复到 'AI 修改前'"
|
||||
5. 不清除该版本快照（用户可能想在不同版本间多次切换）
|
||||
|
||||
### saveVersion 触发时机
|
||||
|
||||
| 时机 | 标签 |
|
||||
|------|------|
|
||||
| AI 模式 `send()` 调用前（`reloadFromDisk` 之前） | `"AI 修改前"` |
|
||||
| `App.vue` 首次加载 demo.json 后 | `"初始版本"` |
|
||||
|
||||
不自动在手动编辑时保存版本（用户手动点"保存版本"按钮即可，可选后续添加）。
|
||||
|
||||
---
|
||||
|
||||
## 二、AI 修改标记
|
||||
|
||||
### 流程
|
||||
|
||||
```
|
||||
reloadFromDisk() 前：
|
||||
记下 preGameData = gameData（深拷贝）
|
||||
|
||||
reloadFromDisk() 后：
|
||||
diff = computeDiff(preGameData, newGameData)
|
||||
aiChanges = { added, modified, deleted }
|
||||
|
||||
SceneGraph:
|
||||
渲染时根据 aiChanges 给对应节点加角标
|
||||
```
|
||||
|
||||
### 数据结构
|
||||
|
||||
```ts
|
||||
interface AIDiff {
|
||||
added: string[] // 新 gameData 中有，旧 gameData 中没有的 scene ID
|
||||
modified: string[] // 相同 ID，JSON.stringify 不同的 scene ID
|
||||
deleted: string[] // 旧 gameData 中有，新 gameData 中没有的 scene ID
|
||||
globalFields: string[] // 变更的全局配置字段名，例如 ["title", "assetBase"]
|
||||
}
|
||||
```
|
||||
|
||||
### diff 计算逻辑（editorStore.reloadFromDisk 内）
|
||||
|
||||
```ts
|
||||
const { scenes: oldScenes, ...oldGlobal } = oldGameData
|
||||
const { scenes: newScenes, ...newGlobal } = newGameData
|
||||
const diff: AIDiff = { added: [], modified: [], deleted: [], globalFields: [] }
|
||||
|
||||
for (const id of Object.keys(newScenes)) {
|
||||
if (!oldScenes[id]) diff.added.push(id)
|
||||
else if (JSON.stringify(oldScenes[id]) !== JSON.stringify(newScenes[id])) diff.modified.push(id)
|
||||
}
|
||||
for (const id of Object.keys(oldScenes)) {
|
||||
if (!newScenes[id]) diff.deleted.push(id)
|
||||
}
|
||||
|
||||
for (const key of Object.keys({ ...oldGlobal, ...newGlobal })) {
|
||||
if (JSON.stringify(oldGlobal[key]) !== JSON.stringify(newGlobal[key])) {
|
||||
diff.globalFields.push(key)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
同时检测全局配置变更（startScene、title 等），记录到 `globalFields`。
|
||||
|
||||
### 角标视觉效果
|
||||
|
||||
Vue Flow 自定义节点模板（SceneGraph.vue 已有 `CustomNode` 组件）：
|
||||
|
||||
```
|
||||
┌──────────────┐
|
||||
│ ● NEW │ ← 绿色角标 (纯 CSS 色块)
|
||||
│ scene_A │
|
||||
└──────────────┘
|
||||
|
||||
┌──────────────┐
|
||||
│ ● MOD │ ← 橙色角标
|
||||
│ scene_B │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
CSS 实现：在节点元素右上角添加绝对定位的 `<span class="diff-badge">`。
|
||||
|
||||
### 全局配置变更标记
|
||||
|
||||
当 `aiChanges.globalFields` 非空时，在 `NodeEditor` 的"全局配置"标题区展示：
|
||||
|
||||
```
|
||||
┌─────────────────────────────┐
|
||||
│ 全局配置 ● 已修改 3 字段 │ ← 橙色圆点 + 变更字段数
|
||||
│ ╭──────────────────╮ │
|
||||
│ │ title: "xxx" │ │ ← 鼠标 hover 时弹出 tooltip
|
||||
│ │ startScene: "yyy" │ │ 列出具体变更的字段名
|
||||
│ │ assetBase: "zzz" │ │
|
||||
│ ╰──────────────────╯ │
|
||||
│ { │
|
||||
│ "title": "xxx", ← 正常 JSON textarea 不变
|
||||
│ ... │
|
||||
└─────────────────────────────┘
|
||||
```
|
||||
|
||||
**不变更项占位**：用逗号分隔字段名，如 `已修改 3 字段`；hover 列出所有字段名。
|
||||
|
||||
**清除**：用户 blur JSON textarea 后标记消失（手工编辑即为最终确认）。
|
||||
|
||||
### 标记清除时机
|
||||
|
||||
| 条件 | 行为 |
|
||||
|------|------|
|
||||
| 用户手动编辑任意节点后 blur 保存 | 清除 `aiChanges`，所有标记消失 |
|
||||
| 用户手动编辑全局配置后 blur 保存 | 清除全局配置标记 |
|
||||
| AIPanel 点击"清除高亮"按钮 | 手动清除所有标记 |
|
||||
| 新一轮 AI 修改 | 覆盖旧 diff（新 diff 替换旧 diff） |
|
||||
|
||||
### 涉及文件
|
||||
|
||||
| 文件 | 改动 |
|
||||
|------|------|
|
||||
| `editor/stores/editorStore.ts` | 新增 `aiChanges` ref、diff 计算逻辑、标记清除 |
|
||||
| `editor/components/SceneGraph.vue` | watch `aiChanges`、自定义节点模板加角标 |
|
||||
| `editor/components/NodeEditor.vue` | 全局配置标题加变更提示 |
|
||||
|
||||
---
|
||||
|
||||
## 三、完整交互时序
|
||||
|
||||
```
|
||||
用户输入需求 "添加一个新场景 scene_battle"
|
||||
│
|
||||
▼
|
||||
AIPanel.send()
|
||||
① saveVersion("AI 修改前") ← 快照
|
||||
② preGameData = clone gameData ← 记下旧值
|
||||
③ sendAIRequest(buildMessage(msg), ...)
|
||||
│
|
||||
▼
|
||||
opencode 读文件 → 新增 scene_battle → 写盘 → 回复 "已创建 scene_battle"
|
||||
│
|
||||
▼
|
||||
AIPanel 收到 result
|
||||
④ 聊天显示 result
|
||||
⑤ store.reloadFromDisk()
|
||||
├─ fetch → 新 gameData
|
||||
├─ diff(oldGameData, newGameData) → aiChanges = { added: ["scene_battle"], modified: [], deleted: [], globalFields: [] }
|
||||
├─ gameData = newGameData
|
||||
└─ selectedNodeId = null
|
||||
│
|
||||
▼
|
||||
SceneGraph 检测到 aiChanges 非空
|
||||
→ 新增节点 scene_battle 渲染时显示绿色 "NEW" 角标
|
||||
→ 已有节点无角标
|
||||
│
|
||||
▼
|
||||
用户手动编辑任一节点后 blur
|
||||
→ store.clearAIMarkers()
|
||||
→ 所有角标消失
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、改动清单
|
||||
|
||||
### editor/db/editorDB.ts（新建）
|
||||
|
||||
| API | 说明 |
|
||||
|-----|------|
|
||||
| `initDB()` | 打开/创建 `editor_versions` 数据库 |
|
||||
| `putVersion(v)` | 存入版本快照 |
|
||||
| `getVersions(sourcePath)` | 获取某文件所有版本（按时间倒序，最多 20） |
|
||||
| `clearVersions(sourcePath)` | 清除某文件的版本（切换文件/删除旧版本时） |
|
||||
|
||||
### editor/stores/editorStore.ts
|
||||
|
||||
| 新增 | 说明 |
|
||||
|------|------|
|
||||
| `versions: Ref<EditorVersion[]>` | 当前文件的所有历史版本 |
|
||||
| `aiChanges: Ref<AIDiff>` | 上次 AI 修改的 diff 结果 |
|
||||
| `saveVersion(label)` | 深拷贝 gameData → 存 IndexedDB → 更新 versions |
|
||||
| `restoreVersion(idx)` | gameData = versions[idx].gameData → autoSave |
|
||||
| `reloadFromDisk()` 增强 | diff 计算 + 设置 aiChanges |
|
||||
| `clearAIMarkers()` | aiChanges = null |
|
||||
| `loadVersions()` | 加载当前 sourcePath 的版本列表 |
|
||||
|
||||
### editor/components/SceneGraph.vue
|
||||
|
||||
| 新增 | 说明 |
|
||||
|------|------|
|
||||
| `watch(aiChanges)` | 重新渲染时按 aiChanges 给节点加 badge |
|
||||
| CSS `.diff-badge` / `.diff-badge-added` / `.diff-badge-modified` / `.diff-badge-deleted` | 角标样式 |
|
||||
|
||||
### editor/components/AIPanel.vue
|
||||
|
||||
| 新增 | 说明 |
|
||||
|------|------|
|
||||
| 版本下拉 UI | `<select v-model="selectedVersion">` + 恢复按钮 |
|
||||
| `send()` 前调 `saveVersion("AI 修改前")` | 在 `loading = true` 前 |
|
||||
| "清除高亮" 按钮 | 调用 `store.clearAIMarkers()` |
|
||||
|
||||
### editor/components/NodeEditor.vue
|
||||
|
||||
| 新增 | 说明 |
|
||||
|------|------|
|
||||
| 全局配置标题加标记 | `全局配置 ● 已修改 N 字段` + hover tooltip 显示字段名，当 `aiChanges.globalFields` 非空 |
|
||||
| `onBlur()` 时调 `clearAIMarkers()` | 编辑后清除标记 |
|
||||
|
||||
---
|
||||
|
||||
## 五、非侵入性保证
|
||||
|
||||
| 项 | 保障 |
|
||||
|----|------|
|
||||
| IndexedDB 故障容忍 | try/catch 包裹所有操作，失败不影响主流程 |
|
||||
| 版本存储增长 | 20 个上限 + 切换文件时清空旧文件的版本 |
|
||||
| SceneGraph 性能 | diff 比较仅用 `Object.keys` + `JSON.stringify`，百级节点 < 2ms |
|
||||
| 不影响手动编辑 | `clearAIMarkers()` 在 blur 时调用，角标不留存 |
|
||||
| 不影响 Code 模式 | 仅在 JSON 模式 `reloadFromDisk()` 时做 diff |
|
||||
| 不使用 emoji | CSS 纯色圆点 + 文字实现角标 |
|
||||
|
||||
---
|
||||
|
||||
## 六、测试用例
|
||||
|
||||
### V1：版本自动保存
|
||||
| 步骤 | 预期 |
|
||||
|------|------|
|
||||
| 编辑器中加载 demo.json | 自动创建版本 "初始版本" |
|
||||
| 打开 AIPanel，JSON 模式发送"添加场景" | 自动创建版本 "AI 修改前" |
|
||||
| 打开版本下拉 | 显示两个版本 |
|
||||
|
||||
### V2：版本恢复
|
||||
| 步骤 | 预期 |
|
||||
|------|------|
|
||||
| AI 修改后选择 "AI 修改前" 版本 | 点击恢复 |
|
||||
| 编辑器内容回到修改前 | SceneGraph + NodeEditor 刷新为旧内容 |
|
||||
|
||||
### V3：修改标记
|
||||
| 步骤 | 预期 |
|
||||
|------|------|
|
||||
| AI 新增 scene_battle | SceneGraph 中该节点显示绿色 "NEW" 角标 |
|
||||
| AI 修改 scene_start | 该节点显示橙色 "MOD" 角标 |
|
||||
| AI 修改 title + startScene | NodeEditor 全局配置标题显示 "● 已修改 2 字段"，hover 列出 title/startScene |
|
||||
| 用户手动编辑任一节点后 blur | 所有角标消失 |
|
||||
| 用户手动编辑全局配置后 blur | 全局配置标记消失 |
|
||||
|
||||
### V4：非侵入
|
||||
| 步骤 | 预期 |
|
||||
|------|------|
|
||||
| 不通过 AI 直接手动编辑 JSON | 不触发版本保存，不显示角标 |
|
||||
| 浏览器不支持 IndexedDB | 版本功能静默失效，不影响编辑 |
|
||||
Reference in New Issue
Block a user