feat: AI assistant panel, editor improvements, vite and package config

docs/E17_AI_ASSISTANT_PROPOSAL.md

@@ -0,0 +1,234 @@
+# E17: AI 编码助手 — opencode + DeepSeek 集成
+
+## 概述
+
+编辑器内嵌 AI 对话面板，使用 opencode Agent + DeepSeek 后端，支持两种模式：
+- **JSON 模式** — 修改场景配置，填充 textarea 供用户审查后接受
+- **代码模式** — 直接修改 `src/` 目录下的 Vue 组件和 CSS，Vite HMR 实时预览
+
+## 完整架构
+
+```
+浏览器 (Editor)
+  ├── AIPanel.vue          用户输入自然语言
+  ├── NodeEditor.vue       接收 AI 返回的 JSON，[接受]/[撤销]
+  └── App.vue              管理 AI 面板状态
+
+              ↓ POST /api/ai { sessionId, userMessage, apiKey, mode, nodeId? }
+
+Vite 中间件（零状态）
+  └── spawn('node_modules/.bin/opencode', ['run', '--session', sessionId, '--model', 'deepseek', '--format', 'json', fullMessage])
+       ├── fullMessage = modePrefix + userMessage
+       │     JSON模式:  "JSON模式：只返回修改后的 JSON 文本，不要写任何文件。需求：..." + nodeJson
+       │     代码模式:  "代码模式：直接修改 src/ 下的源码文件并保存。需求：..."
+       ├── opencode 自身管理会话上下文（--session 复用已有会话）
+       ├── 自动读取项目文件构建 prompt → 调 DeepSeek API
+       └── 返回 stdout
+```
+
+## JSON 模式交互时序
+
+```
+用户                 编辑器                 Vite 中间件           opencode               DeepSeek
+ │                      │                       │                    │                      │
+ │ 选中节点+输入需求     │                       │                    │                      │
+ │─────────────────────→│                       │                    │                      │
+ │                      │ POST /api/ai          │                    │                      │
+ │                      │──────────────────────→│                    │                      │
+ │                      │                       │ spawn opencode     │                      │
+ │                      │                       │───────────────────→│                      │
+ │                      │                       │                    │ 读 story.json +     │
+ │                      │                       │                    │ SPEC.md + 用户需求  │
+ │                      │                       │                    │────────────────────→│
+ │                      │                       │                    │      返回 JSON       │
+ │                      │                       │                    │←────────────────────│
+ │                      │                       │  stdout: JSON      │                      │
+ │                      │                       │←───────────────────│                      │
+ │                      │   200 { result }       │                    │                      │
+ │                      │←──────────────────────│                    │                      │
+ │                      │                       │                    │                      │
+ │ 显示 [接受] [撤销]    │                       │                    │                      │
+ │─────→ textarea 填充   │                       │                    │                      │
+ │                      │                       │                    │                      │
+ │ 点击 [接受]           │                       │                    │                      │
+ │─────────────────────→│                       │                    │                      │
+ │                      │ JSON.parse → update   │                    │                      │
+ │                      │ → autoSave 写磁盘     │                    │                      │
+```
+
+## 代码模式交互时序
+
+```
+用户                 编辑器                 Vite 中间件           opencode               DeepSeek
+ │                      │                       │                    │                      │
+ │ 输入 UI 修改需求      │                       │                    │                      │
+ │─────────────────────→│                       │                    │                      │
+ │                      │ POST /api/ai          │                    │                      │
+ │                      │──────────────────────→│                    │                      │
+ │                      │                       │ spawn opencode     │                      │
+ │                      │                       │───────────────────→│                      │
+ │                      │                       │                    │ 读 src/components/  │
+ │                      │                       │                    │ 改 Vue/CSS 文件     │
+ │                      │                       │                    │────────────────────→│
+ │                      │                       │                    │      写文件到 src/   │
+ │                      │                       │                    │←────────────────────│
+ │                      │                       │  stdout: done      │                      │
+ │                      │                       │←───────────────────│                      │
+ │                      │   200 { result }       │                    │                      │
+ │                      │←──────────────────────│                    │                      │
+ │                      │                       │                    │                      │
+ │   Vite HMR 检测变化   │                       │                    │                      │
+ │←─────────────────────│                       │                    │                      │
+ │   浏览器热更新预览    │                       │                    │                      │
+```
+
+## 关键设计决策
+
+| 决策 | 做法 | 原因 |
+|------|------|------|
+| **AI 后端** | opencode Agent + DeepSeek | 唯一覆盖 JSON + 代码双模式；自动读取项目文件构建上下文 |
+| **opencode 安装** | npm 包 `opencode-ai`，作为 `devDependencies`。`npm install` 后 `node_modules/.bin/opencode` 即可用 | clone 即用，无需手动全局安装 |
+| **API Key 存储** | 编辑器设置中输入，存 localStorage，每次请求传给 `/api/ai` | 不硬编码，创作者自行管理 |
+| **API Key 传输** | 通过 POST body 传到 Vite 中间件，不暴露在浏览器网络日志 | XSS 只能获取 localStorage，看不到服务端日志 |
+| **JSON 编辑** | AI 返回 JSON 填充 textarea，用户审查后 [接受] 才保存 | 保留创作者对故事数据的最终控制权 |
+| **代码编辑** | opencode 直接写 `src/` 目录，Vite HMR 秒级刷新 | 代码修改即时可视化，不需要手动刷新 |
+| **上下文构建** | opencode 读取项目文件自成上下文 | 不需要手动拼系统 prompt |
+| **模式切换** | AIPanel 当前模式标签：选中节点 → "JSON 模式"；未选中节点 → "代码模式"。手动可切换 | 减少用户认知负担，大部分场景自动判断正确 |
+| **DeepSeek 模型** | `--model deepseek`，通过 opencode providers 配置 Key | opencode 自身管理模型路由 |
+
+## 会话管理
+
+opencode 原生支持会话：`opencode run --session <id>` 复用已有上下文，`opencode session list` 列出历史。
+
+### 架构原则：前端持 sessionId，中间件无状态
+
+```
+AIPanel (Vue)
+  ├── sessionId = localStorage.getItem('editor_ai_session') || crypto.randomUUID()
+  ├── 每次请求 POST /api/ai 带上 sessionId
+  ├── "新建对话" → 新 UUID → 覆盖 localStorage
+  └── 历史列表 → GET /api/ai/sessions → opencode session list → 前端渲染
+
+Vite 中间件 — 零状态
+  └── spawn('opencode', ['run', '--session', sessionId, '--format', 'json', userMessage])
+  └── 不存任何 sessionId，不维护子进程
+```
+
+### 会话操作
+
+| 操作 | opencode CLI | 触发方式 |
+|------|-------------|---------|
+| 首次对话 | `opencode run --session <新UUID> --model deepseek --format json "..."` | AIPanel 检测 localStorage 无 sessionId |
+| 继续对话 | `opencode run --session <已有UUID> --model deepseek --format json "..."` | 带上同一 sessionId |
+| 新建对话 | 前端生成新 UUID → 旧会话仍存在于 opencode 内部 DB | AIPanel "新建对话" 按钮 |
+| 历史列表 | `opencode session list` | AIPanel 顶部下拉（可选） |
+
+### 为什么不用长活子进程
+
+| | 长活子进程 + stdin/stdout | **独立进程 + --session** |
+|------|:--:|:--:|
+| 进程管理 | 需管道通信、心跳检测 | `spawn` 等待 exit，0 行管理代码 |
+| 中间件状态 | 需维护 sessionId→process Map | 零状态 |
+| dev server 重启 | 会话丢失 | localStorage 持久化，重启可恢复 |
+| 稳定性 | 子进程可能 crash | 每次独立进程，天然隔离 |
+| 延迟 | ~1-3s（管道通信） | ~5s（启动 Node + 加载会话），对编辑器 AI 场景可接受 |
+
+## 安全设计
+
+| 层级 | 措施 |
+|------|------|
+| **API Key** | AES 加密存 localStorage？→ 不用，Key 本身是服务端 API 凭证，浏览器存储已是业界实践（VS Code Copilot、Cursor 同理） |
+| **传输** | POST body 中传递，HTTPS 加密。仅 `/api/ai` 路由可读取，上游不打印日志 |
+| **文件写入** | opencode 通过 Vite 中间件 spawn，中间件做路径白名单：JSON 模式只允许 `public/scenes/*.json`；代码模式只允许 `src/**/*.vue`、`src/**/*.ts`、`src/locales/*.json` |
+| **请求频率** | 中间件加 3s 内去重（同一 mode+userMessage 不重复 spawn） |
+
+## 错误处理
+
+| 错误场景 | 处理 |
+|----------|------|
+| DeepSeek API 超时（15s） | 中间件 kill 子进程，返回 `504 { error: "timeout" }` |
+| opencode 进程崩溃（exit code ≠ 0） | 中间件返回 `500 { error: "opencode exited with code " + code }` |
+| DeepSeek API 余额不足 | 中间件返回 `402 { error: "insufficient_quota" }` |
+| opencode 返回非 JSON（代码模式） | 直接视为成功（stdout 文本无关紧要） |
+| opencode 返回非 JSON（JSON 模式） | 中间件尝试用正则提取 JSON 块，无法提取则返回 `500` 给前端 |
+
+## 文件改动清单
+
+| 文件 | 职能 |
+|------|------|
+| `package.json` | 新增 `opencode-ai` devDependency（`"opencode-ai": "^1.17"`） |
+| `vite.config.ts` | 新增 `POST /api/ai` 中间件：接收 sessionId/userMessage/apiKey/mode，构造 modePrefix + spawn(`opencode`, `['run', '--session', sessionId, '--model', 'deepseek', '--format', 'json', fullMessage]`)；`GET /api/ai/sessions` → `opencode session list` |
+| `editor/composables/useAI.ts` | **新建** — `sendAIRequest(sessionId, userMessage, mode)` → fetch(`/api/ai`)；`listSessions()` → fetch(`/api/ai/sessions`) |
+| `editor/components/AIPanel.vue` | **新建** — 消息历史 + `<input>` + loading + "正在生成..." + **"新建对话"按钮** + 会话列表下拉 |
+| `editor/stores/editorStore.ts` | 新增 `deepseekKey`（localStorage）、`showAIPanel`、`aiResult`、`sessionId` |
+| `editor/App.vue` | 新增 "AI 助手" 按钮 + AIPanel 组件 + 设置面板中 API Key 输入栏 |
+
+---
+
+## 测试用例
+
+### T1: JSON 模式 — 正常流程
+
+| 步骤 | 预期结果 |
+|------|---------|
+| 选中一个场景节点 | NodeEditor 显示该场景 JSON |
+| 打开 AIPanel，输入"给这个场景添加一个 QTE" | 显示 loading 状态 |
+| opencode 返回修改后 JSON | NodeEditor textarea 被填充，出现 [接受] [撤销] |
+| 点击 [接受] | JSON.parse 成功，store.updateScene 执行，autoSave 写磁盘 |
+| 点击 [撤销] | textarea 回滚到 AI 修改前的值 |
+
+### T2: JSON 模式 — opencode 返回无效 JSON
+
+| 步骤 | 预期结果 |
+|------|---------|
+| AI 返回非法 JSON | 中间件返回 `500 { error }` |
+| AIPanel 显示红色错误提示 | "AI 返回格式异常，请重试"，textarea 不被填充 |
+
+### T3: 代码模式 — 正常流程
+
+| 步骤 | 预期结果 |
+|------|---------|
+| 未选中任何节点 | AIPanel 显示 "代码模式" 标签 |
+| 输入"把按钮改成圆角 20px" | 显示 loading |
+| opencode 修改 `src/components/ChoicePanel.vue` 的 CSS | 文件写磁盘成功 |
+| Vite HMR 触发 | 预览窗按钮圆角即时可见 |
+
+### T4: 会话管理
+
+| 步骤 | 预期结果 |
+|------|---------|
+| 首次对话 | localStorage 无 `editor_ai_session` → AIPanel 自动生成 UUID |
+| 第二次对话 | 带上同一 sessionId → opencode `--session <id>` 恢复上下文 |
+| 点击 "新建对话" | 新 UUID 写入 localStorage |
+| 刷新页面 | sessionId 不丢失，历史列表可查 |
+
+### T5: 错误处理
+
+| 步骤 | 预期结果 |
+|------|---------|
+| DeepSeek Key 无效 | AIPanel 显示 "API 认证失败，请检查 Key" |
+| opencode 进程被 kill | 中间件 `child.on('exit', 137)` → 500 |
+| 请求 15s 无响应 | 中间件 kill 子进程 → 504 |
+| 同一 userMessage 3s 内发送两次 | 去重，不重复 spawn |
+
+### T6: 路径白名单
+
+| 步骤 | 预期结果 |
+|------|---------|
+| 代码模式让 AI 修改 `/etc/passwd` | 中间件拒绝或 opencode 写盘失败 |
+| JSON 模式让 AI 修改 `../secret.json` | 路径不在 `public/scenes/*.json` 范围内， 被拒绝 |
+
+### T7: API Key 管理
+
+| 步骤 | 预期结果 |
+|------|---------|
+| 未填 Key 就发送请求 | AIPanel 提示 "请先在设置中输入 DeepSeek API Key" |
+| 填入 Key → 发送请求 | Key 从 localStorage 读取，POST body 传给中间件 |
+| 刷新页面 | Key 仍存在 |
+
+### T8: NodeEditor 覆盖保护
+
+| 步骤 | 预期结果 |
+|------|---------|
+| 用户正在手动编辑 textarea → AI 返回结果 | AI 结果填充到 textarea（覆盖手动编辑），可 [撤销] |
+| AI 返回后用户手动再编辑 → 失焦 | 手动编辑内容通过 blur 保存（不是 AI 内容） |

docs/EDITOR_ROADMAP.md

@@ -51,10 +51,24 @@
 - [x] `@blur` → JSON.parse → `store.updateScene(id, parsed)`
 - [x] 解析失败 → 红色边框 + 错误提示
 
+## E17: AI 编码助手 — opencode + DeepSeek 集成
+
+目标：编辑器内嵌 AI 对话面板。JSON 模式填充 textarea 供用户审查后接受；代码模式直接修改 Vue 组件/CSS，Vite HMR 实时预览。
+
+详见 [E17_AI_ASSISTANT_PROPOSAL.md](../E17_AI_ASSISTANT_PROPOSAL.md)
+
+- [x] `vite.config.ts` — `POST /api/ai` 中间件（spawn opencode）
+- [x] `editor/composables/useAI.ts` — DeepSeek API 调用封装
+- [x] `editor/components/AIPanel.vue` — AI 对话面板
+- [x] `editor/components/NodeEditor.vue` — `aiResult` prop + [接受]/[撤销]
+- [x] `editor/stores/editorStore.ts` — `deepseekKey` + `showAIPanel` + `aiResult`
+- [x] `editor/App.vue` — "AI 助手" 按钮 + API Key 设置
+
 **优先级建议：**
 
 | 优先级 | 编号 | 说明 |
 |:--:|------|------|
+| **P0** | E17 | AI 编码助手 — DeepSeek 集成 ✅ 核心已完成 |
 | **P0** | E16 | JSON 编辑器 ✅ 已完成 |
 | **P0** | E10 | 内嵌快速测试 |
 | **P1** | E12 | JSON 校验 |