2026-04-19-02-26-05 集成AI撰写功能：Kimi-2.5多模态API、AI可编辑区域、Diff确认弹窗、语音与图片输入、快捷指令
This commit is contained in:
78
工程分析/实现方案-2026-04-19-02-26-05.md
Normal file
78
工程分析/实现方案-2026-04-19-02-26-05.md
Normal file
@@ -0,0 +1,78 @@
|
||||
# 实现方案 — 2026-04-19-02-26-05
|
||||
|
||||
## 1. 方案概述
|
||||
基于现有 `contentEditable` 架构，引入 `ai-region` DOM 区块作为 AI 的"手术锚点"。通过标准 Fetch API 接入 Kimi 多模态接口，采用 JSON Schema 约束输出。所有 AI 状态集中在 ReportEditor 管理，TemplateManage 仅负责区域插入。
|
||||
|
||||
## 2. 详细步骤
|
||||
|
||||
### 步骤 1：`src/types.ts` — 扩展 SystemSettings
|
||||
**目标文件**：`src/types.ts`
|
||||
**修改内容**：
|
||||
- `SystemSettings` 接口新增 `kimiApiKey?: string` 和 `kimiApiEndpoint?: string`
|
||||
- 默认值兜底在 `SystemSettings.tsx` 中处理
|
||||
|
||||
### 步骤 2：`src/pages/SystemSettings.tsx` — 完善 AI 接口配置
|
||||
**目标文件**：`src/pages/SystemSettings.tsx`
|
||||
**修改内容**：
|
||||
- AI 接口集成卡片中，将现有的 `apiEndpoint` / `apiKey` 的 placeholder 和 label 改为明确指向 Kimi
|
||||
- `testApi` 函数改为真实调用 Kimi `/v1/models` 或简单 chat completion 进行连通性测试
|
||||
- `resetToDefault` 中保留新字段的默认空值
|
||||
|
||||
### 步骤 3：`src/pages/TemplateManage.tsx` — 工具栏新增 AI 区域按钮
|
||||
**目标文件**：`src/pages/TemplateManage.tsx`
|
||||
**修改内容**：
|
||||
- import 中增加 `Bot` from `lucide-react`
|
||||
- 新增 `insertAiRegion` 函数：prompt 输入名称 → 重名检查（`querySelector([data-ai-id="..."])`）→ `execCommand('insertHTML')` 插入标准 `ai-region` DOM
|
||||
- 工具栏 JSX 中在 `ImageIcon` 右侧新增蓝色 `Bot` 按钮
|
||||
- 插入后调用 `saveTemplateContent()`
|
||||
|
||||
### 步骤 4：`src/pages/ReportEditor.tsx` — 工具栏 + activeTab 扩展
|
||||
**目标文件**：`src/pages/ReportEditor.tsx`
|
||||
**修改内容**：
|
||||
- import 中增加 `Bot`, `Mic`, `MicOff`, `ImagePlus`, `Sparkles`, `Send` 等图标
|
||||
- `activeTab` 类型扩展为 `'info' | 'video' | 'ai'`
|
||||
- 工具栏 JSX 中在 `ImageIcon` 右侧新增蓝色 `Bot` 按钮及 `insertAiRegion` 函数
|
||||
- 右侧 Tab 按钮区新增 "AI撰写" 切换按钮
|
||||
|
||||
### 步骤 5：`src/pages/ReportEditor.tsx` — AI 核心状态与逻辑
|
||||
**目标文件**：`src/pages/ReportEditor.tsx`
|
||||
**修改内容**：
|
||||
- 新增 State：
|
||||
- `chatInput`, `chatMessages`, `isGenerating`
|
||||
- `aiSelectedFrames`, `aiTargetRegion`, `aiModifyEnabled`
|
||||
- `isListening`, `aiUploadedImages`, `speechRecognitionRef`
|
||||
- `quickPrompts`, `isEditingPrompts`
|
||||
- `diffModal`
|
||||
- 新增函数：
|
||||
- `checkAiRegions()`: 扫描编辑器内所有 `.ai-region` 返回 id/title 列表
|
||||
- `toggleListening()`: Web Speech API 语音识别
|
||||
- `handleAIGenerate(text)`: 组装多模态 message → Fetch 调用 Kimi → 解析 JSON → 更新聊天 → 触发 Diff
|
||||
- `confirmAiInjection(newHtml, regionId)`: 注入 HTML → 视觉高亮动画 → saveDraft
|
||||
- 注意：所有 DOM 修改后必须同步 `contentRef.current = editorRef.current.innerHTML` 并 `saveDraftToStorage()`
|
||||
|
||||
### 步骤 6：`src/pages/ReportEditor.tsx` — AI 面板 UI
|
||||
**目标文件**：`src/pages/ReportEditor.tsx`
|
||||
**修改内容**：
|
||||
- 在 `activeTab === 'ai'` 分支中渲染完整面板：
|
||||
- 顶部：聊天气泡区（user 右蓝 / model 左白）
|
||||
- 中部：区域锚定下拉 + "允许修改正文" checkbox
|
||||
- 中下部：关键帧缩略图多选 + 本地图片预览
|
||||
- 底部：快捷指令胶囊 + 多行输入框（带 Mic / ImagePlus / Send 按钮）
|
||||
- 在最外层新增 `diffModal` 弹窗 DOM（左右对比、可编辑右侧、确认/放弃按钮）
|
||||
|
||||
### 步骤 7：`src/index.css` — AI 区域打印样式
|
||||
**目标文件**：`src/index.css`
|
||||
**修改内容**：
|
||||
- `@media print` 中隐藏 `.ai-region` 的蓝色边框和标签，或将其设为透明/灰色，避免打印时显示编辑态样式
|
||||
|
||||
## 3. 依赖关系
|
||||
- 步骤 1（types）必须在步骤 2/3/4/5/6 之前
|
||||
- 步骤 3（TemplateManage）和步骤 4-6（ReportEditor）可并行
|
||||
- 步骤 2（SystemSettings）可独立并行
|
||||
- 步骤 7（CSS）在最后执行
|
||||
|
||||
## 4. 风险预案
|
||||
- 若 Kimi API 调用失败，catch 中向聊天列表追加 `[系统错误]` 消息，不阻断页面
|
||||
- 若 `JSON.parse` 失败，尝试用正则提取 JSON 子串后再解析，仍失败则展示原始文本
|
||||
- 若用户浏览器不支持 Web Speech API，点击麦克风时 alert 提示并优雅降级
|
||||
- 若 `ai-region` 被用户手动删除，下拉选择器实时扫描会同步更新为空
|
||||
80
工程分析/测试方案-2026-04-19-02-26-05.md
Normal file
80
工程分析/测试方案-2026-04-19-02-26-05.md
Normal file
@@ -0,0 +1,80 @@
|
||||
# 测试方案 — 2026-04-19-02-26-05
|
||||
|
||||
## 1. 测试范围
|
||||
- TemplateManage / ReportEditor 工具栏 AI 区域插入
|
||||
- SystemSettings Kimi API 配置保存
|
||||
- ReportEditor AI 撰写面板全链路（聊天、多模态输入、API调用、Diff确认、注入高亮）
|
||||
- 构建与部署验证
|
||||
|
||||
## 2. 测试步骤与预期结果
|
||||
|
||||
### 场景 1：AI 区域插入（TemplateManage）
|
||||
1. 进入 `/template-manage`，点击工具栏蓝色 Bot 图标
|
||||
预期：弹出 prompt，要求输入区域名称
|
||||
2. 输入 "手术步骤"，点击确认
|
||||
预期：编辑器中出现蓝色虚线框区域，右上角有 "手术步骤-AI可编辑区域" 标签
|
||||
3. 再次点击 Bot，再次输入 "手术步骤"
|
||||
预期：alert 提示 "该区域名称已存在..."
|
||||
4. 输入 "术后总结"
|
||||
预期：成功插入第二个区域
|
||||
|
||||
### 场景 2：AI 区域插入（ReportEditor）
|
||||
1. 进入 `/report-editor`，点击工具栏蓝色 Bot 图标
|
||||
预期：与 TemplateManage 行为一致
|
||||
|
||||
### 场景 3：SystemSettings 配置保存
|
||||
1. 进入 `/system-settings`，在 AI 接口集成中输入 API Key 和 Endpoint
|
||||
2. 点击保存
|
||||
预期：提示"设置已保存"，刷新后值仍然保留
|
||||
|
||||
### 场景 4：AI 面板基础聊天（纯聊模式）
|
||||
1. 进入 `/report-editor`，确保编辑器内已有 `ai-region`
|
||||
2. 点击右侧 "AI撰写" Tab
|
||||
预期：出现聊天面板，底部有输入框
|
||||
3. 取消勾选 "允许修改正文"
|
||||
4. 输入 "你好"，按 Enter
|
||||
预期：出现 user 气泡（右侧蓝色），随后出现 model 气泡（左侧白色），正文未被修改
|
||||
|
||||
### 场景 5：AI 修改正文（Diff 模式）
|
||||
1. 勾选 "允许修改正文"
|
||||
2. 在下拉框中选择一个 AI 区域
|
||||
3. 输入 "请完善这段手术步骤描述"
|
||||
4. 按 Enter
|
||||
预期：AI 返回后弹出 Diff 弹窗，左侧显示原文，右侧显示 AI 版本
|
||||
5. 在右侧编辑几个字，点击"确认并写入报告"
|
||||
预期：弹窗关闭，编辑器对应区域内容更新，区域背景出现深蓝→淡蓝→透明渐变
|
||||
6. 点击"放弃修改"
|
||||
预期：弹窗关闭，正文保持原样
|
||||
|
||||
### 场景 6：多模态输入
|
||||
1. 上传一个本地图片到 AI 面板
|
||||
预期：输入框上方出现小图预览，带删除按钮
|
||||
2. 在视频分析中截取一帧，回到 AI 面板勾选该帧
|
||||
预期：缩略图上有蓝色勾选标记
|
||||
3. 发送消息
|
||||
预期：消息正常发送，图片随请求提交
|
||||
|
||||
### 场景 7：快捷指令
|
||||
1. 点击快捷指令旁的 "⚙️"
|
||||
预期：进入编辑模式，每个指令右上角出现红色删除按钮
|
||||
2. 点击 "+ 添加"，输入新的快捷指令
|
||||
预期：新指令出现在列表中
|
||||
3. 点击胶囊按钮
|
||||
预期：指令文本自动填充到输入框
|
||||
|
||||
### 场景 8：路由切换数据保持
|
||||
1. 在 AI 面板中发送几条消息
|
||||
2. 切换到 `/report-manage`，再返回 `/report-editor`
|
||||
预期：AI 聊天记录丢失（因未设计持久化，属于预期行为），但报告正文、AI 区域结构保留
|
||||
|
||||
### 场景 9：构建与部署
|
||||
1. 执行 `npm run lint`
|
||||
预期：无 TypeScript 类型错误
|
||||
2. 执行 `npm run build`
|
||||
预期：构建成功，dist/ 生成
|
||||
3. 执行 `npm run preview -- --host`
|
||||
预期：`http://localhost:4173/` 返回 200
|
||||
|
||||
## 3. 回滚检查
|
||||
- 若测试失败，执行 `git checkout main` 恢复到修改前状态（本次 commit 之前）
|
||||
- 或从 Gitea 拉取上一个可用版本
|
||||
43
工程分析/需求分析-2026-04-19-02-26-05.md
Normal file
43
工程分析/需求分析-2026-04-19-02-26-05.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# 需求分析 — 2026-04-19-02-26-05
|
||||
|
||||
## 1. 需求背景
|
||||
为 ReportEditor 加入 AI 撰写功能，接入 Kimi-2.5 多模态模型，实现智能化的手术报告辅助撰写。参考 "参考-ReportEditor.tsx" 的设计范式，构建现代化的沉浸式 AI 对话 UI。
|
||||
|
||||
## 2. 需求拆解
|
||||
- [ ] **Task 1**：TemplateManage 工具栏新增 "插入AI可编辑区域" 按钮，支持命名且不可重名
|
||||
- [ ] **Task 2**：ReportEditor 工具栏同步新增同样的 AI 区域插入按钮
|
||||
- [ ] **Task 3**：SystemSettings 完善 AI 接口集成，适配 Kimi-2.5 API（baseURL + apiKey）
|
||||
- [ ] **Task 4**：ReportEditor 右侧新增 "AI撰写" Tab 面板，包含：
|
||||
- 类微信风格的聊天对话 UI（气泡、Loading 动画）
|
||||
- 定向区域锚定（下拉选择 `ai-region`）
|
||||
- "允许修改正文" 沙盒开关
|
||||
- 多模态输入：语音输入（Web Speech API）、视频关键帧选择、本地图片上传
|
||||
- 快捷指令胶囊（可添加/删除/编辑）
|
||||
- Diff 二次确认弹窗（左右对比、可编辑右侧、确认后注入）
|
||||
- 注入后视觉反馈（深蓝→淡蓝→透明渐变高亮）
|
||||
- [ ] **Task 5**：AI 调用逻辑：Fetch API 调用 Kimi API，严格 JSON Schema 输出（reply + updatedHtml）
|
||||
|
||||
## 3. 影响范围
|
||||
| 文件 | 修改类型 | 风险等级 |
|
||||
|------|----------|----------|
|
||||
| `src/types.ts` | 修改（扩展 SystemSettings） | 低 |
|
||||
| `src/pages/SystemSettings.tsx` | 修改（AI设置UI） | 中 |
|
||||
| `src/pages/TemplateManage.tsx` | 修改（工具栏+插入逻辑） | 中 |
|
||||
| `src/pages/ReportEditor.tsx` | 大规模修改（工具栏、状态、右侧面板、Diff弹窗、API调用） | **高** |
|
||||
|
||||
## 4. 优先级
|
||||
- P0：ReportEditor AI 面板核心功能（聊天、API调用、Diff确认）
|
||||
- P1：TemplateManage / ReportEditor 工具栏 AI 区域插入
|
||||
- P1：SystemSettings Kimi 接口配置
|
||||
- P2：语音输入、快捷指令编辑等增强体验
|
||||
|
||||
## 5. 验收标准
|
||||
- [ ] 可在 TemplateManage 中插入 `ai-region` 区域，重名时弹窗阻止
|
||||
- [ ] 可在 ReportEditor 中插入 `ai-region` 区域
|
||||
- [ ] SystemSettings 可配置 Kimi API Key 和 Base URL，保存后持久化
|
||||
- [ ] ReportEditor 右侧有 "AI撰写" Tab，点击可展开聊天面板
|
||||
- [ ] 可向 AI 发送文本+图片（关键帧/本地上传），AI 返回 JSON 结构化回复
|
||||
- [ ] 勾选"允许修改正文"时，AI 返回的 HTML 会触发 Diff 弹窗，确认后才注入
|
||||
- [ ] 不勾选"允许修改正文"时，AI 回复仅在聊天气泡中展示，不修改正文
|
||||
- [ ] 注入后目标区域有视觉高亮反馈
|
||||
- [ ] 重新部署后页面可正常访问，无构建错误
|
||||
Reference in New Issue
Block a user