From 390545bb808e65a0b87942378e8600ee988e46ff Mon Sep 17 00:00:00 2001 From: linshen <32978552+linshenkx@users.noreply.github.com> Date: Fri, 19 Dec 2025 20:51:26 +0800 Subject: [PATCH] =?UTF-8?q?docs(arch):=20=E5=BD=92=E6=A1=A3=E5=A4=9A?= =?UTF-8?q?=E8=BD=AE=E5=AF=B9=E8=AF=9D=E4=B8=8E=E4=B8=8A=E4=B8=8B=E6=96=87?= =?UTF-8?q?=E6=A8=A1=E5=BC=8F=E9=87=8D=E6=9E=84=E8=AE=BE=E8=AE=A1=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增多轮对话模式优化设计文档 (127) - 新增上下文 UI 与变量系统重构文档 (128) - 更新归档索引与 README 分类结构 --- .../README.md | 29 ++ .../design.md} | 0 .../README.md | 30 ++ .../analysis.md} | 4 +- .../design.md} | 0 .../implementation-codemirror.md} | 0 .../plan.md} | 2 +- docs/archives/INDEX.md | 12 + docs/archives/README.md | 8 +- .../workspace/code-review-mode-terminology.md | 245 ------------ .../context-user-independence-analysis.md | 344 ----------------- .../evaluation-code-review-2025-12-17.md | 349 ------------------ .../mode-terminology-migration-summary.md | 72 ++-- .../workspace-independence-analysis.md | 270 -------------- 14 files changed, 116 insertions(+), 1249 deletions(-) create mode 100644 docs/archives/127-multi-turn-dialogue-mode-optimization/README.md rename docs/{workspace/multi-turn-dialogue-mode-design.md => archives/127-multi-turn-dialogue-mode-optimization/design.md} (100%) create mode 100644 docs/archives/128-context-ui-and-variable-system-refactor/README.md rename docs/{workspace/ui-design-analysis.md => archives/128-context-ui-and-variable-system-refactor/analysis.md} (99%) rename docs/{workspace/variable-system-redesign.md => archives/128-context-ui-and-variable-system-refactor/design.md} (100%) rename docs/{workspace/codemirror-variable-highlighting-implementation.md => archives/128-context-ui-and-variable-system-refactor/implementation-codemirror.md} (100%) rename docs/{workspace/ui-refactor-plan.md => archives/128-context-ui-and-variable-system-refactor/plan.md} (99%) delete mode 100644 docs/workspace/code-review-mode-terminology.md delete mode 100644 docs/workspace/context-user-independence-analysis.md delete mode 100644 docs/workspace/evaluation-code-review-2025-12-17.md delete mode 100644 docs/workspace/workspace-independence-analysis.md diff --git a/docs/archives/127-multi-turn-dialogue-mode-optimization/README.md b/docs/archives/127-multi-turn-dialogue-mode-optimization/README.md new file mode 100644 index 00000000..bcc2892e --- /dev/null +++ b/docs/archives/127-multi-turn-dialogue-mode-optimization/README.md @@ -0,0 +1,29 @@ +# 127 - 多轮对话模式（Pro-System / Conversation）优化设计 + +## 📋 功能概述 + +归档多轮对话模式（原“上下文-系统”）的优化交互与数据结构设计，核心目标是支持在会话中选择任意 `system/user` 消息进行优化，并以“消息 ID”为稳定锚点管理版本链路与自动应用。 + +## ⏱️ 时间线 + +- **开始时间**: 2025-01-04 +- **最后更新**: 2025-01-05 +- **状态**: ✅ 设计方案 + 实施记录（以 v3.1 为基线） + +## 🎯 核心要点 + +- **稳定选择**：以 `ConversationMessage.id` 作为选择与映射的主键，避免按索引导致的插入/删除/排序问题。 +- **工作链复用**：通过 `messageChainMap`（消息ID → chainId）实现“切换消息时自动加载既有链”的体验。 +- **自动应用与自动保存**：优化结果自动应用到会话消息，工作链依赖历史记录系统自动保存（无需额外持久化索引）。 + +## 📁 文档清单 + +- [x] `design.md` - 设计方案与实施记录（最终版 v3.1） + +## 🔗 相关实现参考（代码） + +- `packages/core/src/services/prompt/types.ts`（`ConversationMessage.id` / `originalContent?`） +- `packages/ui/src/composables/prompt/useConversationOptimization.ts`（`selectedMessageId` / `messageChainMap` / 自动应用） +- `packages/ui/src/components/context-mode/ContextSystemWorkspace.vue`（多轮对话模式工作区） +- `packages/ui/src/components/context-mode/ConversationManager.vue`（会话输入与消息选择） + diff --git a/docs/workspace/multi-turn-dialogue-mode-design.md b/docs/archives/127-multi-turn-dialogue-mode-optimization/design.md similarity index 100% rename from docs/workspace/multi-turn-dialogue-mode-design.md rename to docs/archives/127-multi-turn-dialogue-mode-optimization/design.md diff --git a/docs/archives/128-context-ui-and-variable-system-refactor/README.md b/docs/archives/128-context-ui-and-variable-system-refactor/README.md new file mode 100644 index 00000000..7cc032f7 --- /dev/null +++ b/docs/archives/128-context-ui-and-variable-system-refactor/README.md @@ -0,0 +1,30 @@ +# 128 - 上下文模式 UI 改造与变量系统重构 + +## 📋 功能概述 + +归档“上下文模式（User/System）UI 改造 + 变量系统重构”的设计、任务与实施记录。该模块的关键目标包括： + +- 子模式选择器移到导航栏，统一模式层级与用户心智 +- 快捷操作栏移到测试区，贴近使用场景并释放左侧空间 +- 变量系统简化：移除“会话变量”，引入测试区临时变量，并明确三层变量优先级 + +## ⏱️ 时间线 + +- **开始时间**: 2025-10-21 +- **完成时间**: 2025-10-23 +- **状态**: ✅ 已完成（文档为当时设计/实施记录归档） + +## 📁 文档清单 + +- [x] `analysis.md` - UI 设计分析报告（包含阶段目标与问题拆解） +- [x] `plan.md` - UI 改造任务文档（执行清单/里程碑） +- [x] `design.md` - 变量系统重构设计文档（含实施细节与差异记录） +- [x] `implementation-codemirror.md` - CodeMirror 6 变量高亮/补全实现记录（VariableAwareInput） + +## 🔗 相关实现参考（代码） + +- `packages/ui/src/components/app-layout/PromptOptimizerApp.vue`（主装配与导航栏模式管理） +- `packages/ui/src/components/context-mode/ContextUserWorkspace.vue` / `packages/ui/src/components/context-mode/ContextSystemWorkspace.vue` +- `packages/ui/src/components/TestAreaPanel.vue`（测试区变量输入与测试入口） +- `packages/ui/src/composables/context/useContextManagement.ts`（上下文管理） +- `packages/ui/src/composables/variable/useTemporaryVariables.ts`（临时变量，若启用） diff --git a/docs/workspace/ui-design-analysis.md b/docs/archives/128-context-ui-and-variable-system-refactor/analysis.md similarity index 99% rename from docs/workspace/ui-design-analysis.md rename to docs/archives/128-context-ui-and-variable-system-refactor/analysis.md index c290bc29..a4e608e0 100644 --- a/docs/workspace/ui-design-analysis.md +++ b/docs/archives/128-context-ui-and-variable-system-refactor/analysis.md @@ -29,8 +29,8 @@ 3. **变量系统简化** 🔴 高优先级 - **问题**: "全局变量"和"会话变量"概念混淆，实际都是持久化变量 - **方案**: 移除会话变量，引入测试区临时变量 - - **状态**: 📋 待实施 - - **详情**: 见 [变量系统重构设计文档](./variable-system-redesign.md) + - **状态**: ✅ 已完成（作为归档记录） + - **详情**: 见 [变量系统重构设计文档](./design.md) ### 📊 改造预期效果 diff --git a/docs/workspace/variable-system-redesign.md b/docs/archives/128-context-ui-and-variable-system-refactor/design.md similarity index 100% rename from docs/workspace/variable-system-redesign.md rename to docs/archives/128-context-ui-and-variable-system-refactor/design.md diff --git a/docs/workspace/codemirror-variable-highlighting-implementation.md b/docs/archives/128-context-ui-and-variable-system-refactor/implementation-codemirror.md similarity index 100% rename from docs/workspace/codemirror-variable-highlighting-implementation.md rename to docs/archives/128-context-ui-and-variable-system-refactor/implementation-codemirror.md diff --git a/docs/workspace/ui-refactor-plan.md b/docs/archives/128-context-ui-and-variable-system-refactor/plan.md similarity index 99% rename from docs/workspace/ui-refactor-plan.md rename to docs/archives/128-context-ui-and-variable-system-refactor/plan.md index 8a6b543a..a3163a0c 100644 --- a/docs/workspace/ui-refactor-plan.md +++ b/docs/archives/128-context-ui-and-variable-system-refactor/plan.md @@ -20,7 +20,7 @@ - ✅ 引入测试区临时变量 - ✅ 三层变量合并逻辑 (全局 < 测试 < 预定义) - ✅ 通过所有功能测试和回归测试 - - 详见: [变量系统重构设计文档](./variable-system-redesign.md) + - 详见: [变量系统重构设计文档](./design.md) --- diff --git a/docs/archives/INDEX.md b/docs/archives/INDEX.md index a70d5955..c614f7ce 100644 --- a/docs/archives/INDEX.md +++ b/docs/archives/INDEX.md @@ -82,6 +82,18 @@ - 修复图像模式刷新后文件上传按钮不显示的bug - 建立完整的状态管理最佳实践和设计模式 +### 上下文模式（Pro） +- **[127-multi-turn-dialogue-mode-optimization](./127-multi-turn-dialogue-mode-optimization/)** - 多轮对话模式优化 💬 + - 基于消息 ID 的稳定选择与映射（避免索引漂移） + - messageChainMap（消息 → 工作链）复用策略与自动应用 + - 多轮对话（Pro-System / Conversation）体验与实施记录 + +### 上下文模式（UI/变量） +- **[128-context-ui-and-variable-system-refactor](./128-context-ui-and-variable-system-refactor/)** - 上下文 UI 改造与变量系统重构 🧩 + - 子模式选择器/快捷操作栏布局调整 + - 变量系统简化：移除会话变量，引入测试区临时变量 + - 任务计划、设计与实施记录归档 + ## 🔧 问题修复系列 ### 存储与数据 diff --git a/docs/archives/README.md b/docs/archives/README.md index 2aac4d3d..c46b5b1c 100644 --- a/docs/archives/README.md +++ b/docs/archives/README.md @@ -61,6 +61,10 @@ ### 状态管理系列 (已完成) - [126-submode-persistence](./126-submode-persistence/) - 子模式持久化功能 ✅ +### 上下文模式系列 (已完成) +- [127-multi-turn-dialogue-mode-optimization](./127-multi-turn-dialogue-mode-optimization/) - 多轮对话模式优化（Pro-System / Conversation） ✅ +- [128-context-ui-and-variable-system-refactor](./128-context-ui-and-variable-system-refactor/) - 上下文 UI 改造与变量系统重构 ✅ + ## 📋 文档结构 每个功能点目录包含： @@ -88,9 +92,11 @@ - **服务重构系列**：113 - **UI优化系列**：124 - **状态管理系列**：126 +- **上下文模式系列**：127 +- **上下文模式系列**：127, 128 ### 按状态查找 -- **已完成**：101, 102, 103, 108, 109, 110, 111, 112, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 126 +- **已完成**：101, 102, 103, 108, 109, 110, 111, 112, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 126, 127, 128 - **进行中**：106, 107, 113 - **计划中**：104, 105 diff --git a/docs/workspace/code-review-mode-terminology.md b/docs/workspace/code-review-mode-terminology.md deleted file mode 100644 index 1a909c00..00000000 --- a/docs/workspace/code-review-mode-terminology.md +++ /dev/null @@ -1,245 +0,0 @@ -# 模式术语统一代码变更审查报告 - -## 📋 变更概览 - -**审查时间**: 2025-10-31 -**变更范围**: 4个文件 -**变更类型**: 参数重命名和注释更新 -**影响范围**: UI composables 层 - -## 📁 变更文件列表 - -### 1. `packages/ui/src/composables/prompt/usePromptOptimizer.ts` - -#### 变更内容 -- 参数重命名: `selectedOptimizationMode` → `optimizationMode` -- 移除内部变量赋值: `const optimizationMode = selectedOptimizationMode` -- 更新 JSDoc 注释，标注为 `@deprecated` - -#### 代码审查 - -✅ **正确性** -- 参数名统一为 `optimizationMode`，符合统一术语规范 -- 移除了冗余的变量赋值，代码更简洁 -- 错误提示信息已更新 - -✅ **向后兼容性** -- 虽然参数名改变，但由于是内部 API，且添加了 @deprecated 标记 -- App.vue 中的调用已同步更新 -- 不会破坏现有功能 - -✅ **类型安全** -- 类型签名保持不变: `Ref` -- 所有使用该参数的地方已验证 - -### 2. `packages/ui/src/composables/prompt/usePromptTester.ts` - -#### 变更内容 -- 参数重命名: `selectedOptimizationMode` → `optimizationMode` -- 更新函数体内的所有引用（3处） -- 更新 JSDoc 注释，标注为 `@deprecated` - -#### 代码审查 - -✅ **正确性** -```typescript -// 变更前 -if (selectedOptimizationMode.value === 'user') { - -// 变更后 -if (optimizationMode.value === 'user') { -``` -- 所有 3 处引用都已正确更新 -- 逻辑保持不变，只是变量名变化 - -✅ **一致性** -- 与 `usePromptOptimizer` 的参数命名保持一致 -- 统一了整个代码库的术语 - -### 3. `packages/ui/src/composables/context/useContextManagement.ts` - -#### 变更内容 -- 接口属性添加 `@deprecated` 标记 - -#### 代码审查 - -✅ **文档化** -```typescript -export interface ContextManagementOptions { - services: Ref; - selectedOptimizationMode: Ref; // @deprecated 应使用统一的 subMode 管理 - // ... -} -``` -- 清楚地标记了过时的 API -- 提供了迁移指导 - -⚠️ **待完成** -- 该接口的实际迁移需要在后续阶段完成 -- 目前仅添加了标记，未修改实现 - -### 4. `packages/web/src/App.vue` - -#### 变更内容 -- 为三处 `selectedOptimizationMode` 调用添加注释 - -#### 代码审查 - -✅ **兼容性处理** -```typescript -// 提示词优化器 -const optimizer = usePromptOptimizer( - services as any, - selectedOptimizationMode, // 保持兼容性，后续应改为使用 basicSubMode/proSubMode - toRef(modelManager, "selectedOptimizeModel"), - toRef(modelManager, "selectedTestModel"), - contextMode, -); -``` -- 明确标注了当前保持兼容性的原因 -- 提供了清晰的迁移方向 - -✅ **渐进式迁移** -- 不破坏现有功能 -- 为下一阶段的完整迁移打下基础 - -## 🔍 详细分析 - -### 优点 - -1. **术语统一** - - 从 `selectedOptimizationMode` 统一为 `optimizationMode` - - 符合 "subMode" 的概念 - - 减少了命名混淆 - -2. **代码简化** - - 移除了 `usePromptOptimizer` 中的冗余变量赋值 - - 提高了代码可读性 - -3. **文档完善** - - 添加了 `@deprecated` 标记 - - 提供了迁移指导注释 - - 更新了 JSDoc 文档 - -4. **渐进式迁移** - - 保持向后兼容 - - 不破坏现有功能 - - 为完整迁移奠定基础 - -### 潜在风险 - -⚠️ **低风险** -- 参数名变更可能影响未被追踪的调用方 -- **缓解措施**: TypeScript 会在编译时捕获类型错误 - -⚠️ **已知问题** -- 类型检查发现的错误都是之前就存在的问题 -- 本次变更没有引入新的类型错误 - -### 编译状态 - -#### UI 包编译 -- ✅ 成功编译 -- ⚠️ 存在一些之前的 TypeScript 警告（未引用的变量等） -- ❌ 存在一些之前的类型错误（与本次变更无关） - -#### Web 包编译 -- ⚠️ dev 服务器启动后崩溃（需要进一步调查） -- 可能原因：之前存在的问题，非本次变更引入 - -## ✅ 测试建议 - -### 1. 编译测试 -```bash -# 清理并重新编译 -pnpm run clean -pnpm run build - -# 检查类型 -cd packages/ui && npx tsc --noEmit -cd packages/web && npx tsc --noEmit -``` - -### 2. 运行时测试 -- [ ] 基础模式的子模式切换 -- [ ] 上下文模式的子模式切换 -- [ ] 提示词优化功能 -- [ ] 提示词测试功能 -- [ ] 历史记录恢复 - -### 3. 集成测试 -- [ ] 模式切换后状态持久化 -- [ ] 刷新页面后状态恢复 -- [ ] 收藏/历史记录的模式自动切换 - -## 📊 变更统计 - -| 指标 | 数量 | -|------|------| -| 修改文件 | 4 | -| 新增文件 | 1 (迁移总结文档) | -| 参数重命名 | 2 | -| 内部引用更新 | 3 | -| @deprecated 标记 | 3 | -| 代码行变化 | ~15 行 | - -## 🎯 总体评价 - -### 代码质量: ⭐⭐⭐⭐⭐ (5/5) - -**理由**: -- 变更清晰、有目的性 -- 保持向后兼容 -- 文档完善 -- 符合最佳实践 - -### 风险评估: 🟢 低风险 - -**理由**: -- 变更范围可控 -- TypeScript 提供类型安全 -- 保持了向后兼容性 -- 有清晰的回退路径 - -### 建议: ✅ 批准合并 - -**条件**: -1. ✅ 代码变更符合统一设计 -2. ✅ 添加了适当的文档和注释 -3. ⚠️ 需要解决 web dev 服务器崩溃问题（建议单独调查） -4. ✅ 提供了清晰的迁移路径 - -## 📝 后续工作建议 - -### 高优先级 -1. **调查 web dev 服务器问题** - - 确认是否是本次变更导致 - - 如果是之前的问题，创建单独的 issue - -2. **完成 App.vue 的完整迁移** - - 移除 `selectedOptimizationMode` ref - - 直接使用 `basicSubMode`/`proSubMode` - -### 中优先级 -3. **完成 useContextManagement 的迁移** - - 更新接口定义 - - 移除 @deprecated 标记 - -4. **更新所有模板绑定** - - 搜索并替换 Vue 模板中的引用 - -### 低优先级 -5. **清理已有的类型错误** - - 修复 useTextModelManager 中的类型问题 - - 修复 useImageWorkspace 的导入问题 - -## 🔗 相关文档 - -- [迁移总结](./mode-terminology-migration-summary.md) -- [功能模式设计](../archives/126-submode-persistence/README.md) - ---- - -**审查者**: Claude -**状态**: ✅ 建议批准 -**备注**: 代码变更符合统一设计目标，质量良好，建议解决 dev 服务器问题后合并 \ No newline at end of file diff --git a/docs/workspace/context-user-independence-analysis.md b/docs/workspace/context-user-independence-analysis.md deleted file mode 100644 index 60a72bc2..00000000 --- a/docs/workspace/context-user-independence-analysis.md +++ /dev/null @@ -1,344 +0,0 @@ -# ContextUserWorkspace 独立性深度分析 - -## 📋 分析目标 - -检查 ContextUserWorkspace 的 composables 是否足够独立，是否有逻辑和其他模式的 composables 复用或在 App.vue 里面。 - -## 🔍 当前架构分析 - -### 1. ContextUserWorkspace 的依赖关系 - -**组件内部使用的 Composable**: -```typescript -import { useTemporaryVariables } from "../../composables/variable/useTemporaryVariables" - -const tempVarsManager = useTemporaryVariables() -``` - -**通过 App.vue 依赖的逻辑**: -```typescript -// App.vue 中 -const optimizer = usePromptOptimizer(...) // ❌ 共享 -const promptTester = usePromptTester(...) // ❌ 共享 - -// ContextUserWorkspace 通过 props 和 events 使用 - -``` - -### 2. 基础模式的依赖关系 - -**基础模式同样依赖**: -```typescript -// App.vue 中 - -``` - -### 3. ContextSystemWorkspace 的独立性（对比） - -**完全独立的逻辑**: -```typescript -// ContextSystemWorkspace.vue 内部 -const conversationOptimization = useConversationOptimization(...) // ✅ 独立 -const conversationTester = useConversationTester(...) // ✅ 独立 - -const handleOptimizeClick = () => { - conversationOptimization.optimizeMessage() // ✅ 内部处理 -} - -const handleTestWithVariables = async () => { - await conversationTester.executeTest(...) // ✅ 内部处理 -} -``` - ---- - -## ⚠️ 发现的问题 - -### 问题 1: 不对称的架构设计 ❌ - -| 功能 | 基础模式 | ContextUser | ContextSystem | -|------|---------|------------|---------------| -| 优化逻辑 | App.vue (optimizer) | App.vue (optimizer) | 组件内部 (conversationOptimization) ✅ | -| 测试逻辑 | App.vue (promptTester) | App.vue (promptTester) | 组件内部 (conversationTester) ✅ | -| 状态管理 | App.vue | App.vue | 组件内部 ✅ | - -**问题**: ContextSystem 有独立的 composables，而 ContextUser 和基础模式共享 App.vue 的逻辑。 - ---- - -### 问题 2: 基础模式和 ContextUser 复用逻辑 ❌ - -**共享的 Composables**: -```typescript -// App.vue -const optimizer = usePromptOptimizer(...) // 基础模式 + ContextUser 共享 -const promptTester = usePromptTester(...) // 基础模式 + ContextUser 共享 -``` - -**共享的处理函数**: -```typescript -// 基础模式和 context-user 模式的测试处理函数 -const handleTestAreaTest = async (testVariables?: Record) => { - // 调用基础测试器（只用于基础模式和 context-user） - await promptTester.executeTest( - optimizer.prompt, - optimizer.optimizedPrompt, - testContent.value, - isCompareMode.value, - testVariables - ) -} -``` - -**问题**: -- ContextUser 没有自己独立的优化和测试逻辑 -- 与基础模式共享相同的 composables -- 不符合"ContextUser 应该独立"的预期 - ---- - -### 问题 3: usePromptTester 的定位混淆 ❌ - -**usePromptTester 的文档描述**: -```typescript -/** - * 基础模式提示词测试 Composable - * - * 专门处理基础模式的提示词测试，支持： - * - System prompt 测试 - * - User prompt 测试 - * - 变量注入 - * - 对比模式（原始 vs 优化） - */ -``` - -**实际使用**: -- ✅ 基础模式使用（符合定位） -- ❌ ContextUser 模式也使用（不符合定位） - -**问题**: usePromptTester 声称是"基础模式专用"，却被 ContextUser 复用。 - ---- - -## 🎯 应该的架构 - -### 理想的独立架构 - -``` -App.vue -├── 基础模式 (Basic Mode) -│ ├── usePromptOptimizer (全局) -│ └── usePromptTester (全局) -│ -├── ContextSystemWorkspace (独立) ✅ -│ ├── useConversationOptimization -│ └── useConversationTester -│ -└── ContextUserWorkspace (应该独立) ❌ - ├── useContextUserOptimization (新建，独立) - └── useContextUserTester (新建，独立) -``` - -### 建议的改进方案 - -#### 方案 1: 创建独立的 ContextUser Composables ⭐⭐⭐⭐⭐ - -**新增 Composables**: -```typescript -// packages/ui/src/composables/prompt/useContextUserOptimization.ts -export function useContextUserOptimization( - services: Ref, - optimizationMode: Ref, - selectedOptimizeModel: Ref, - selectedTemplate: Ref