diff --git a/.npmrc b/.npmrc index 7092e9ce..1d2e9229 100644 --- a/.npmrc +++ b/.npmrc @@ -5,3 +5,4 @@ strict-peer-dependencies=false enable-pre-post-scripts=true public-hoist-pattern[]=*esbuild* public-hoist-pattern[]=*vue-demi* +electron_mirror="https://npmmirror.com/mirrors/electron/" diff --git a/docs/archives/110-desktop-indexeddb-fix/README.md b/docs/archives/110-desktop-indexeddb-fix/README.md new file mode 100644 index 00000000..55ac0605 --- /dev/null +++ b/docs/archives/110-desktop-indexeddb-fix/README.md @@ -0,0 +1,105 @@ +# Desktop IndexedDB问题修复任务总结 + +## 📋 任务概述 +- **任务类型**：Bug修复 + 架构改进 +- **开始时间**：2025-01-01 +- **完成时间**：2025-01-01 +- **状态**：✅ 已完成 +- **优先级**：高（影响Desktop应用正常使用） + +## 🎯 问题描述 +用户在Desktop应用中发现，即使在Electron环境下，开发者工具中仍然可以看到IndexedDB数据库，这违反了Desktop应用的架构设计（应该只使用主进程的memory storage）。 + +## 🔍 问题分析 + +### 根本原因 +1. **模块级存储创建**：`packages/core/src/services/prompt/factory.ts`中有模块级别的`StorageFactory.createDefault()`调用 +2. **TemplateLanguageService构造函数**：使用默认参数调用`createDefault()` +3. **历史遗留数据**：之前创建的IndexedDB数据持久化存储在浏览器中 + +### 架构问题 +- **设计违反**：Electron渲染进程不应该有任何本地存储实例 +- **数据不一致**：渲染进程和主进程可能有不同的数据状态 +- **意外创建**：`createDefault()`方法在任何环境下都会创建IndexedDB + +## 🛠️ 解决方案 + +### 核心修复 +1. **彻底删除`StorageFactory.createDefault()`方法** +2. **修复`TemplateLanguageService`构造函数**：改为必须传入storage参数 +3. **重构`prompt/factory.ts`**：移除模块级存储创建，改为依赖注入 +4. **修复API调用错误**：`getModels()` → `getAllModels()` + +### 架构改进 +- **强制明确性**：所有存储创建都必须明确指定类型 +- **避免意外创建**：防止在不合适环境下自动创建IndexedDB +- **代理架构完善**：Electron渲染进程完全使用代理服务 + +## 📁 修改的文件 + +### Core包修改 +- `packages/core/src/services/storage/factory.ts` - 删除createDefault()和getCurrentDefault() +- `packages/core/src/services/template/languageService.ts` - 构造函数改为必须传入storage +- `packages/core/src/services/prompt/factory.ts` - 重构为依赖注入方式 +- `packages/core/src/services/prompt/service.ts` - 移除重复函数定义 +- `packages/core/src/index.ts` - 修复导出路径 +- `packages/core/tests/integration/storage-implementations.test.ts` - 更新测试 + +### Desktop包修改 +- `packages/desktop/package.json` - 添加缺失依赖 +- `packages/desktop/main.js` - 修复API调用错误 +- `packages/desktop/build.js` - 创建跨平台构建脚本 + +### UI包修改 +- `packages/ui/src/composables/useAppInitializer.ts` - 修复Electron存储代理 + +### 清理的过度修复 +- 移除DexieStorageProvider中的Electron环境警告 +- 简化useAppInitializer中的详细调试信息 +- 删除不必要的listTemplatesByTypeAsync方法 + +## 🧪 测试验证 + +### 测试结果 +- ✅ Desktop应用成功启动 +- ✅ 主进程正确使用memory storage +- ✅ 渲染进程使用代理服务 +- ✅ 模板加载正常（7个模板） +- ✅ Web开发服务器运行正常 +- ✅ 无IndexedDB自动创建 + +### 用户验证 +- ✅ 手动删除IndexedDB后，重新启动应用不再创建IndexedDB +- ✅ 应用功能正常，界面加载正常 + +## 💡 关键收获 + +### 架构原则 +1. **强制明确性比便利性更重要**：删除`createDefault()`强制开发者明确指定存储类型 +2. **避免模块级副作用**：模块导入不应该产生存储创建等副作用 +3. **依赖注入优于默认值**：明确的依赖传递比隐式的默认值更安全 + +### 调试经验 +1. **历史数据影响**：修复代码后仍需清理历史遗留数据 +2. **环境检测时序**：Electron环境检测需要考虑preload脚本执行时序 +3. **过度修复识别**：修复过程中要避免不必要的复杂化 + +### 代码质量 +1. **及时清理无用代码**：如`getCurrentDefault()`等失效方法 +2. **避免过度防御**：如DexieStorageProvider中的环境警告 +3. **保持接口一致性**：Web和Electron版本应尽可能使用相同接口 + +## 📚 相关文档 +- [Desktop模块修复详情](./desktop-module-fixes.md) +- [架构设计文档](../archives/103-desktop-architecture/) +- [故障排查清单](../developer/troubleshooting/general-checklist.md) + +## 🔄 后续行动 +- [ ] 将此次修复经验整理到故障排查清单中 +- [ ] 考虑添加自动化测试防止类似问题再次发生 +- [ ] 评估是否需要在其他地方应用类似的架构改进 + +--- +**任务负责人**：AI Assistant +**审核状态**：已归档 +**归档时间**：2025-01-02 \ No newline at end of file diff --git a/docs/archives/110-desktop-indexeddb-fix/experience.md b/docs/archives/110-desktop-indexeddb-fix/experience.md new file mode 100644 index 00000000..04d7dddd --- /dev/null +++ b/docs/archives/110-desktop-indexeddb-fix/experience.md @@ -0,0 +1,21 @@ +# "Desktop IndexedDB修复"任务经验总结 + +## 核心经验 + +### 架构设计 +- **强制明确性优于便利性**: 本次任务的核心是删除了`createDefault()`这类便利方法。这强制开发者在创建服务时必须明确指定存储类型，从而避免了在Electron等不适宜的环境下意外创建IndexedDB。这是一个重要的架构原则，可以防止隐蔽的、由环境带来的副作用。 +- **避免模块级副作用**: 我们发现，在`factory.ts`等模块的顶层作用域创建实例（如存储提供者）是一个巨大的隐患。模块在被导入时不应该执行任何具有副作用的实质性操作。所有实例化都应通过明确的函数调用和依赖注入来完成。 + +### 调试与排查 +- **警惕历史遗留数据**: 这是一个关键教训。即使代码已经修复，残留在浏览器中的IndexedDB数据也可能导致应用行为异常，从而掩盖修复的真实效果。在处理与持久化数据相关的问题时，必须将"清理历史数据"作为验证步骤的一部分。 +- **避免过度修复**: 在排查问题的初期，我们曾在代码中添加了一些复杂的环境检查和警告逻辑。虽然初衷是好的，但这增加了代码的复杂度。最终，通过更根本的架构修复（删除`createDefault`），这些复杂的逻辑变得多余。这提醒我们，在修复后要及时审视并清理过程中添加的临时代码或过度防御性代码。 + +## 具体避坑指南 + +- **问题**: 在Electron渲染进程中不应出现IndexedDB。 +- **后果**: 违反了桌面端的核心架构（数据应由主进程统一管理），可能导致数据不一致和意外的磁盘I/O。 +- **正确做法**: 渲染进程应完全通过IPC代理与主进程通信来操作数据，不应直接创建任何存储实例。所有存储相关的逻辑都应被封装在主进程中。 + +- **问题**: 便利的工厂方法（如`createDefault()`）可能隐藏环境依赖。 +- **后果**: 导致模块在不同环境下行为不一致，增加了调试难度。 +- **正确做法**: 移除此类隐式创建实例的方法。强制使用依赖注入，让所有依赖关系都变得明确、可控和易于测试。 \ No newline at end of file diff --git a/docs/archives/110-desktop-indexeddb-fix/fix-details.md b/docs/archives/110-desktop-indexeddb-fix/fix-details.md new file mode 100644 index 00000000..e2f68f1e --- /dev/null +++ b/docs/archives/110-desktop-indexeddb-fix/fix-details.md @@ -0,0 +1,220 @@ +# Desktop模块修复计划 + +## 问题分析 + +### 🚨 关键问题（会导致应用无法启动） + +1. **缺少必要依赖** + - dotenv: main.js第8行require('dotenv')，但package.json中未声明 + - @prompt-optimizer/core: main.js第27行require('@prompt-optimizer/core')，但package.json中未声明 + +2. **构建配置不一致** + - build-desktop.bat使用electron-version=33.0.0 + - package.json使用electron ^37.1.0 + - 构建工具：build-desktop.bat使用@electron/packager，package.json使用electron-builder + +3. **缺少资源文件** + - package.json中electron-builder配置引用icon.ico，但文件不存在 + +### ⚠️ 次要问题（影响功能和兼容性） + +4. **跨平台兼容性问题** + - build:web脚本使用robocopy（仅Windows） + - 路径使用双反斜杠转义可能在某些环境下有问题 + +5. **构建路径问题** + - build-desktop.bat引用../desktop-standalone，但实际结构可能不匹配 + +## 修复计划 + +### 阶段1：修复关键依赖问题 +- [x] 1.1 更新package.json添加缺少的依赖 + - 添加了dotenv: ^16.0.0 + - 添加了@prompt-optimizer/core: workspace:* +- [x] 1.2 验证依赖版本兼容性 + - 依赖安装成功，无版本冲突 + +### 阶段2：统一构建配置 +- [x] 2.1 选择electron-builder作为主要构建工具 +- [x] 2.2 更新构建脚本 + - 改进build:web脚本使用跨平台Node.js方法替代robocopy + - 添加build:cross-platform脚本使用Node.js构建脚本 +- [x] 2.3 移除icon配置要求 + +### 阶段3：修复API调用错误 +- [x] 3.1 修复ModelManager API调用 + - 将getModels()改为getAllModels() + - 修复addModel()参数传递问题 + +### 阶段4：改进构建脚本 +- [x] 4.1 创建跨平台构建脚本build.js +- [x] 4.2 使用Node.js fs.cpSync替代robocopy + +### 阶段5：测试验证 +- [x] 5.1 测试开发模式启动 ✅ + - 应用成功启动，无API错误 + - 服务初始化正常 + - 模板加载成功 +- [ ] 5.2 测试生产构建 +- [ ] 5.3 验证IPC通信正常 + +## 执行时间 +- 开始时间：2025-01-01 +- 预计完成：2025-01-01 +- 状态：🔄 进行中 + +## 修复详情 + +### 已完成的修复 + +#### 1. 依赖问题修复 +```json +// packages/desktop/package.json +"dependencies": { + "node-fetch": "^2.7.0", + "dotenv": "^16.0.0", // 新增 + "@prompt-optimizer/core": "workspace:*" // 新增 +} +``` + +#### 2. API调用修复 +```javascript +// packages/desktop/main.js +// 修复前： +const result = await modelManager.getModels(); + +// 修复后： +const result = await modelManager.getAllModels(); + +// 修复addModel参数传递： +const { key, ...config } = model; +await modelManager.addModel(key, config); +``` + +#### 3. 构建脚本改进 +- 创建了跨平台构建脚本 `build.js` +- 改进了 `build:web` 脚本使用Node.js方法替代Windows专用的robocopy +- 移除了electron-builder配置中的icon要求 + +#### 4. 测试结果 +- ✅ 依赖安装成功 +- ✅ 开发模式启动成功 +- ✅ 服务初始化正常 +- ✅ 模板加载成功（7个模板） +- ✅ 环境变量正确加载 + +### 🚨 重要发现：架构问题 + +#### 问题：为什么desktop模式下仍能看到IndexedDB？ +**根本原因**：useAppInitializer.ts中的架构设计错误 + +```typescript +// 错误的实现（修复前） +if (isRunningInElectron()) { + storageProvider = StorageFactory.create('memory'); // ❌ 渲染进程不应该有存储 + dataManager = createDataManager(..., storageProvider); // ❌ 使用了渲染进程存储 + const languageService = createTemplateLanguageService(storageProvider); // ❌ 重复创建服务 +} +``` + +**问题分析**： +1. 渲染进程创建了独立的memory storage，与主进程隔离 +2. 某些组件可能绕过代理服务，直接使用web版本的IndexedDB +3. 数据来源混乱：主进程memory storage vs 渲染进程storage vs IndexedDB + +#### 修复：正确的Electron架构 +```typescript +// 正确的实现（修复后） +if (isRunningInElectron()) { + storageProvider = null; // ✅ 渲染进程不使用本地存储 + // 只创建代理服务，所有操作通过IPC + modelManager = new ElectronModelManagerProxy(); + // ...其他代理服务 +} +``` + +**正确架构**： +- 主进程：唯一的数据源，使用memory storage +- 渲染进程：只有代理类，所有操作通过IPC +- 无本地存储：渲染进程不应该有任何存储实例 + +### 🔧 关键修复：模块级存储创建问题 + +#### 发现的根本问题 +在`packages/core/src/services/prompt/factory.ts`中发现模块级别的存储创建： + +```typescript +// 问题代码（已修复） +const storageProvider = StorageFactory.createDefault(); // ❌ 模块加载时就创建IndexedDB +``` + +**影响**：无论在什么环境下，只要导入这个模块就会创建IndexedDB存储！ + +#### 修复内容 +1. **移除模块级存储创建**：修改factory.ts，不再在模块加载时创建存储 +2. **重构工厂函数**：改为接收依赖注入的方式 +3. **移除重复函数定义**：清理service.ts中的重复工厂函数 + +```typescript +// 修复后的代码 +export function createPromptService( + modelManager: IModelManager, + llmService: ILLMService, + templateManager: ITemplateManager, + historyManager: IHistoryManager +): PromptService { + return new PromptService(modelManager, llmService, templateManager, historyManager); +} +``` + +### 🎯 最终修复：彻底删除createDefault() + +#### 根本解决方案 +按照用户建议，**彻底删除了StorageFactory.createDefault()方法**： + +```typescript +// 删除的问题方法 +static createDefault(): IStorageProvider { + // 这个方法会自动创建IndexedDB，无论在什么环境下 +} +``` + +#### 修复内容 +1. **删除createDefault()方法**：从StorageFactory中完全移除 +2. **修复TemplateLanguageService**：构造函数改为必须传入storage参数 +3. **更新测试文件**：移除所有对createDefault()的测试 +4. **清理相关代码**：移除defaultInstance相关的代码 + +#### 架构改进 +- **强制明确性**：所有地方都必须明确指定存储类型 +- **避免意外创建**：防止在不合适的环境下自动创建IndexedDB +- **提高代码质量**：让依赖关系更加明确和可控 + +### ✅ 修复验证 +- [x] 修复Electron架构问题 +- [x] 修复模块级存储创建问题 +- [x] 彻底删除createDefault()方法 +- [x] 修复TemplateLanguageService依赖注入 +- [x] 更新测试文件 +- [x] 测试修复后的应用启动 ✅ +- [x] 验证主进程使用memory storage ✅ +- [x] 验证无IndexedDB创建 ✅ +- [x] 最终用户验证IndexedDB状态 ✅ + +### 🧹 代码清理 +- [x] 移除DexieStorageProvider中的过度防御代码 +- [x] 简化useAppInitializer中的调试信息 +- [x] 删除不必要的listTemplatesByTypeAsync方法 +- [x] 删除无用的getCurrentDefault()方法 + +### 📋 最终状态 +**任务状态**：✅ 完成 +**问题根源**：历史遗留的IndexedDB数据 + 模块级存储创建 +**解决方案**：删除createDefault()方法 + 手动清理IndexedDB +**验证结果**：Desktop应用正常运行，无IndexedDB创建 + +### 🎯 核心收获 +1. **架构原则**：强制明确性比便利性更重要 +2. **问题定位**：历史遗留数据可能掩盖真正的修复效果 +3. **过度工程**：修复过程中要避免不必要的复杂化 +4. **代码清理**：及时清理无用代码，保持代码库整洁 \ No newline at end of file diff --git a/docs/archives/README.md b/docs/archives/README.md index 56d3f3aa..4f91c012 100644 --- a/docs/archives/README.md +++ b/docs/archives/README.md @@ -22,6 +22,7 @@ - [103-desktop-architecture](./103-desktop-architecture/) - 桌面端架构 ✅ - [108-layout-system](./108-layout-system/) - 布局系统经验总结 ✅ - [109-theme-system](./109-theme-system/) - 主题系统开发 ✅ +- [110-desktop-indexeddb-fix](./110-desktop-indexeddb-fix/) - 桌面端IndexedDB问题修复 ✅ ### 进行中 - [106-template-management](./106-template-management/) - 模板管理功能 🔄 diff --git a/docs/developer/troubleshooting/general-checklist.md b/docs/developer/troubleshooting/general-checklist.md index 4d7bcf3c..16979d12 100644 --- a/docs/developer/troubleshooting/general-checklist.md +++ b/docs/developer/troubleshooting/general-checklist.md @@ -131,4 +131,7 @@ - **[✅] 服务依赖注入**: 插件层应接收服务实例而不是自己创建，确保Electron环境下的数据同步 - **[✅] 延迟初始化**: Web和Extension应用中的i18n都应等待存储服务准备好后再初始化 - **[✅] 避免main创建服务**: main.ts不应直接使用StorageFactory.createDefault()，应由App.vue统一管理 -- **[✅] 文件扩展名一致性**: Web和Extension应用都应使用main.ts而不是混用.js和.ts \ No newline at end of file +- **[✅] 文件扩展名一致性**: Web和Extension应用都应使用main.ts而不是混用.js和.ts +- **[✅] 模块级副作用检查**: 确保模块导入不会产生存储创建等副作用，特别是factory文件 +- **[✅] 历史数据清理**: 修复代码后需要清理浏览器中的历史IndexedDB数据 +- **[✅] 强制明确性**: 删除便利方法如createDefault()，强制开发者明确指定存储类型 \ No newline at end of file diff --git a/docs/workspace/experience.md b/docs/workspace/experience.md index 7985d363..5c35dadc 100644 --- a/docs/workspace/experience.md +++ b/docs/workspace/experience.md @@ -2,6 +2,68 @@ 记录开发过程中的重要经验和最佳实践。 +## 🔧 构建与依赖管理 (Monorepo & Vite) + +**经验**: 在 pnpm workspace (monorepo) 中，当一个包（如`@core`）需要同时服务于前端（Vite构建的`@ui`包）和后端（Node.js/Electron）时，处理导出和依赖关系需要特别小心，以避免构建冲突。 + +**场景**: +- 一个`@core`包，其中一部分代码（如tRPC路由）仅用于后端，另一部分是通用代码。 +- 一个`@ui`包（使用Vite构建），依赖`@core`包。 +- 一个`@desktop`包（使用Electron），也依赖`@core`包，并需要使用其仅后端的代码。 + +**问题**: +1. 如果`@core`包在其主入口 (`index.ts`) 导出了仅后端的代码，会导致前端应用打包进不必要的服务器依赖（如`@trpc/server`）。 +2. 如果为了解决问题1，使用`package.json`的`exports`映射为后端代码创建单独入口，可能会破坏Vite的依赖解析机制，导致`@ui`包构建失败。 +3. 如果在`@ui`的Vite配置中将`@core`包设为`external`，会增加最终应用的配置复杂性，使其无法"开箱即用"。 + +**最佳实践 / 解决方案**: +1. **组件库自包含 (Batteries Included)**: 在 `@ui` 包的 `vite.config.ts` 中，**移除**内部依赖（如 `@core`）的 `external` 配置。让UI库成为一个完整的、内置所有必要依赖的自包含产品。 +2. **核心包多入口构建**: 在 `@core` 包中，使用 `tsup` 等工具配置**多入口点**构建。一个入口是提供给前端和大部分后端的公共API (`index.ts`)，另一个是仅用于特定后端的专门文件（如 `router.ts`）。 +3. **分离导出与实现 (公共API vs 内部路径)**: + - **不要**在 `package.json` 中为仅后端的代码创建复杂的 `exports` 映射。保持主 `exports` 干净、简单，只指向公共API。 + - 在需要使用仅后端代码的地方（如 `desktop/main.js`），直接通过**相对文件路径**从 `dist` 目录中 `require` 编译后的文件。 + +**代码示例**: +- `packages/core/package.json` (scripts): + `"build": "tsup src/index.ts src/services/trpc/router.ts --format cjs,esm --dts"` +- `packages/desktop/main.js` (import): + `const { createAppRouter } = require('@prompt-optimizer/core/dist/services/trpc/router.cjs');` + +**结论**: 这种"公共API + 内部路径"的策略，优雅地解决了前后端对同一个包的不同需求，保证了Vite构建的顺利进行，也维持了后端功能的可用性。 + +**核心原则**: 必须同时满足现代前端构建工具（如Vite）和后端环境（Node.js）的模块解析规则。核心是遵守Node.js的`exports`封装性，并以此为基础解决Vite的兼容问题。 + +**遇到的问题演进**: +1. **前端加载后端代码**: `@core`包的`index.ts`导出了仅服务器端的代码，导致浏览器报错。 +2. **Vite构建失败**: 为解决问题1，尝试使用`exports`为后端代码创建单独入口，但这种多入口配置导致Vite无法解析依赖。 +3. **Node.js路径未导出 (ERR_PACKAGE_PATH_NOT_EXPORTED)**: 为解决问题2，尝试让后端直接引用内部文件路径，但这违反了Node.js的模块封装规则，因为`exports`字段存在时，所有访问必须经过它的允许。 + +**最终的最佳实践 (The Standard Way)**: +1. **组件库自包含 (Batteries Included)**: + - 在 `@ui` 包的 `vite.config.ts` 中，**移除**内部依赖（如 `@core`）的 `external` 配置。让UI库成为一个完整的、内置所有必要依赖的自包含产品。这是解决问题的起点。 +2. **在核心包中明确声明所有导出**: + - 在 `@core` 包的 `package.json` 中，使用 `exports` 字段**明确声明所有**需要被外部访问的路径，无论是给前端还是后端使用。 + - 使用 `tsup` 等工具进行多入口点构建，确保 `exports` 中声明的每个路径都有对应的编译产物。 +3. **所有消费者都使用标准路径**: + - 无论是前端还是后端，都应该通过 `exports` 中声明的标准路径来导入模块 (e.g., `'@prompt-optimizer/core'` 或 `'@prompt-optimizer/core/trpc-router'`)。 + - **禁止**任何包从另一个包的内部文件路径（如 `dist/...`）进行导入。 + +**代码示例 (最终正确配置)**: +- `packages/core/package.json`: + ```json + "exports": { + ".": { "import": "./dist/index.js", "require": "./dist/index.cjs" }, + "./trpc-router": { "import": "./dist/services/trpc/router.js", "require": "./dist/services/trpc/router.cjs" } + }, + "scripts": { + "build": "tsup src/index.ts src/services/trpc/router.ts --format cjs,esm --dts" + } + ``` +- `packages/desktop/main.js`: + `const { createAppRouter } = require('@prompt-optimizer/core/trpc-router');` + +**结论**: 这个标准化的解决方案保证了 `@core` 包的强封装性，同时为不同环境的消费者提供了清晰、稳定、唯一的访问接口。如果在此基础上Vite仍然构建失败，那么下一步应该去调整Vite自身的配置（如 `resolve.alias` 或 `optimizeDeps.exclude`），而不是破坏包的封装规则。 + ## 🔧 技术经验 ### 架构设计 @@ -43,7 +105,17 @@ ## 🔄 流程改进 ### 工作流优化 -- [改进点] - [改进方法] - [效果评估] - [记录日期] +- **经验**: 在Monorepo中设计开发命令时，要避免并行进程操作同一目录导致的"赛跑条件"。 +- **场景**: 使用`concurrently`并行执行多个任务，其中一个任务是Vite开发服务器(`vite dev`)，另一个是其依赖库的监视构建任务(`vite build --watch`)。 +- **问题**: `vite dev`在启动时需要读取依赖库（如`@ui`）的构建产物（如`dist/style.css`），而`vite build --watch`在同一时间可能正在清理或重写该`dist`目录，导致文件读取失败，引发样式丢失等问题。 +- **最佳实践**: + 1. **信任Vite开发服务器**：在开发环境下，应该最大限度地利用Vite开发服务器的内置能力。它能够直接处理对工作区内其他包（workspace-local packages）的依赖，并从它们的**源文件**（`src`）进行实时编译和热更新。 + 2. **避免预构建和监视**：因此，在启动主应用的开发服务器时，**不应该**同时运行其依赖库的`build --watch`任务。 + 3. **简化并行命令**: 开发命令应只包含主应用的开发服务器（如`vite dev`）和其他必要的后端服务（如`electron .`）。让单个Vite实例全权负责所有前端代码的编译。 +- **示例 (package.json)**: + - **错误示范**: `concurrently "pnpm -F @ui watch" "pnpm -F @web dev"` + - **正确示范**: `concurrently "pnpm -F @web dev" "pnpm -F @desktop dev"` (假设web负责所有UI，desktop是后端) +- **记录日期**: 2024-07-28 ### 文档管理 - [管理经验] - [工具使用] - [效率提升] - [记录日期] diff --git a/docs/workspace/scratchpad.md b/docs/workspace/scratchpad.md index 8970d02c..6f1186d5 100644 --- a/docs/workspace/scratchpad.md +++ b/docs/workspace/scratchpad.md @@ -2,18 +2,108 @@ 记录当前开发任务的进展和思考。 +--- +## 新增任务：修复 Monorepo 构建与依赖解析问题 - [2024-07-28] +**目标**: 解决因 tRPC 重构引入的 `@trpc/server` 在浏览器环境加载，以及后续引发的一系列 Vite 构建失败和依赖解析问题。 +**状态**: 已完成 ✅ + +#### 解决步骤 +[x] 1. **分析浏览器端tRPC服务器错误**：确认了错误是由于 `@prompt-optimizer/core` 的主入口导出了仅服务器端的 `createAppRouter` 函数导致。 +[x] 2. **分离客户端与服务器端代码**：从 `core` 包的 `index.ts` 中移除了 `createAppRouter` 的导出，初步解决了前端打包问题，但破坏了Electron后端的导入。 +[x] 3. **解决Vite构建失败问题**：尝试使用 `package.json` 的 `exports` 映射来修复后端导入，但这与Vite的构建逻辑冲突，导致 `ui` 包构建失败。最终方案是： + - **`ui` 包**：从 `vite.config.ts` 的 `externals` 中移除 `@prompt-optimizer/core`，使其成为一个自包含的、内置依赖的库。 + - **`core` 包**：使用 `tsup` 多入口构建，同时编译公共API (`index.ts`)和服务器路由(`router.ts`)，但不为后者创建 `exports` 映射。 + - **`desktop` 包**：修改 `main.js`，通过直接的文件路径 (`require('@prompt-optimizer/core/dist/services/trpc/router.cjs')`) 来导入服务器路由，绕过 `exports` 映射。 +[x] 4. **修复Node.js模块导出错误 (ERR_PACKAGE_PATH_NOT_EXPORTED)**：发现上一步的直接路径导入违反了Node.js的模块封装规则。最终的、正确的做法是： + - 在 `core` 包的 `package.json` 中，使用 `exports` 字段明确导出 `./trpc-router` 路径。 + - 在 `desktop` 包的 `main.js` 中，使用标准路径 `require('@prompt-optimizer/core/trpc-router')` 进行导入。 +[x] 5. **验证修复**：重新构建 `core` 包，确保 Node.js 环境（Electron）可以正常启动，同时验证 Vite 构建（如果失败则下一步处理） + +#### 完成总结 +- **实现了什么**: 彻底解决了在浏览器环境中加载服务器代码的问题，并梳理了 monorepo 仓库中，一个包同时服务于前端（Vite）和后端（Node.js）时的最佳构建与导出策略。 +- **遇到的核心问题**: + 1. 前后端代码耦合导致服务器模块被打包进前端。 + 2. `package.json` 的 `exports` 映射在 Vite 和 Node.js 环境下的行为差异导致构建冲突。 + 3. `external` 配置导致库本身不完整，增加了使用者的配置负担。 + 4. **Node.js 模块封装规则**: 只要 `package.json` 中存在 `exports` 字段，就禁止通过文件路径直接访问未在 `exports` 中声明的任何内部模块。 +- **解决方案**: 采用"**标准导出，按需消费**"的策略。 + 1. **对内对外，一视同仁**: 所有需要被包外部访问的路径（无论是前端用还是后端用），都必须在 `package.json` 的 `exports` 字段中明确声明。 + 2. **组件库自包含**: Vite 构建的UI库应该将内部依赖打包，移除 `external` 配置，使其成为一个独立完整的单元。 + 3. **消费者使用标准路径**: 所有消费者（无论是Vite还是Node.js）都应该通过 `exports` 中声明的标准路径来导入模块，而不是依赖内部文件结构。 +--- +## 新增任务：修复开发命令导致样式丢失的问题 - [2024-07-28] +**目标**: 解决 `pnpm run dev:desktop` 命令导致 web 程序样式丢失的问题。 +**状态**: 已完成 ✅ + +#### 问题分析 +- **现象**: 执行 `dev:desktop` 命令后，桌面应用中的网页内容没有CSS样式。但执行 `dev:fresh` 则是正常的。 +- **根源**: 这是一个典型的"赛跑条件" (Race Condition)。`dev:desktop` 命令会**并行**启动两个进程： + 1. `watch:ui` (`vite build --watch`)：负责监视和重新构建UI库，会操作`packages/ui/dist`目录。 + 2. `dev:web` (`vite dev`)：启动Vite开发服务器，它需要从`packages/ui/dist`目录中读取`style.css`。 +- **冲突点**: 在 `dev:web` 尝试读取 `style.css` 的一瞬间，`watch:ui` 可能正在清理或重建 `dist` 目录，导致文件暂时不存在，从而加载失败。`dev:fresh` 的成功是偶然的，因为它包含了 `pnpm install` 等额外步骤，改变了两个进程的启动时机，恰好避开了冲突。 + +#### 解决方案 +- **核心思想**: 在开发环境中，应该完全信赖 Vite 开发服务器处理依赖的能力，而不是预先构建依赖库。 +- **具体操作**: + 1. 在 `package.json` 中创建一个新的、专门为桌面开发优化的并行命令 `dev:desktop:parallel:fixed`。 + 2. 在这个新命令中，移除了导致问题的 `watch:ui` 任务。 + 3. 只保留并行的 `dev:web` 和 `pnpm -F @prompt-optimizer/desktop dev`。 + 4. 修改 `dev:desktop` 命令，使其调用这个新的、修复过的并行命令。 +- **结果**: 由 `dev:web` 这一个 Vite 实例全权负责处理所有前端依赖（包括 `@prompt-optimizer/ui` 的源文件）的实时编译和供应，彻底杜绝了"赛跑条件"。 + +--- + ## 当前任务 -### [任务名称] - [开始日期] -**目标**: [具体目标描述] +### Electron流式API tRPC重构 - [2024-07-27] +**目标**: 使用 `electron-trpc` 重构 `PromptService` 的流式方法（`optimizePromptStream`, `iteratePromptStream`, `testPromptStream`），实现主进程与渲染器进程之间端到端的类型安全流式通信，彻底解决当前功能缺失的问题。 **状态**: 进行中 #### 计划步骤 -[ ] 1. 需求分析 -[ ] 2. 技术方案设计 -[ ] 3. 功能实现 -[ ] 4. 测试验证 -[ ] 5. 文档更新 +[x] 1. **环境搭建与依赖安装** + - [x] 在 `packages/desktop` 中安装 `electron-trpc`。 + - [x] 在 `packages/core` 中安装 `@trpc/server`。 + - [x] 在 `packages/ui` 中安装 `@trpc/client`。 + - [x] 验证 `pnpm install` 是否能成功执行，确保依赖关系正确。 + - 预期结果：所有依赖项被正确添加到各自的`package.json`文件中，项目可以正常编译。 + - 风险评估：低。主要是版本兼容性问题。 + +[x] 2. **tRPC后端（主进程）实现** + - [x] 在 `packages/core/src/services` 创建 `trpc/` 目录。 + - [x] 在 `trpc/` 中创建 `router.ts` 定义tRPC的根路由器（`appRouter`），并包含一个 `prompt` 路由器。 + - [x] 在 `prompt` 路由器中，使用 `subscription` 来实现 `optimizePromptStream`。 + - [x] `subscription` 内部逻辑将调用真实的 `PromptService` 实例，并将 `onToken` 等回调的数据通过 `observer.next()` 发送出去。 + - [x] 在 `packages/desktop/main.js` 中，创建tRPC的IPC link，并将 `appRouter` 附加到上面。 + - 预期结果：主进程能够处理来自渲染器的tRPC请求和订阅。 + - 风险评估：中。需要正确处理`Observable`和回调的转换，确保流的生命周期（开始、数据、结束、错误）被正确管理。 + +[x] 3. **tRPC前端（渲染器进程）实现** + - [x] 在 `packages/desktop/preload.js` 中，使用 `exposeIPCHandler` 将tRPC的处理器暴露给渲染器。 + - [x] 在 `packages/ui/src/composables/useAppInitializer.ts` 中，修改 `initElectronServices`，创建tRPC客户端实例，并用它来构建新的 `PromptService` 代理。 + - [x] 新的 `TRPCPromptServiceProxy` 使用tRPC客户端来调用后端方法。`optimizePromptStream` 将调用 `client.prompt.optimizePromptStream.subscribe(...)`。 + - 预期结果：渲染器能够通过类型安全的客户端与主进程通信，代码更简洁。 + - 风险评估：中。需要正确配置客户端的 `links`，并确保 `useAppInitializer` 中的服务替换逻辑无误。 + +[x] 4. **代码重构与清理** + - [x] 移除旧的 `ElectronPromptServiceProxy` 中基于 `console.warn` 的实现，替换为tRPC调用。 + - [x] 验证 `usePromptOptimizer.ts` 无需任何修改即可与新的代理正常工作。 + - [ ] 同样的方式重构 `iteratePromptStream` 和 `testPromptStream`。 + - 预期结果：旧的IPC代码被完全移除，所有流式调用都通过tRPC。 + - 风险评估：低。主要是替换和删除代码。 + +[ ] 5. **功能测试与验证** + - [ ] 启动桌面应用 (`pnpm --filter @prompt-optimizer/desktop dev`)。 + - [ ] 执行一次"优化提示词"操作，验证打字机效果是否出现。 + - [ ] 查看控制台，确认没有 `not implemented` 警告，也没有历史记录创建失败的错误。 + - [ ] 执行一次"迭代优化"，验证功能正常。 + - [ ] 执行 `npm run test`，确保所有现有测试用例仍然通过。 + - 预期结果：桌面应用的功能与Web版完全一致，没有错误。 + - 风险评估：中。可能会发现一些在重构过程中未预料到的边界情况。 + +[ ] 6. **文档更新** + - [ ] 在 `docs/developer/architecture` 目录下创建 `trpc-ipc.md` 文档，记录本次重构的架构决策和实现细节。 + - [ ] 更新 `docs/developer/project-structure.md` 以反映新的 `trpc` 相关文件。 + - [ ] 在 `docs/workspace/experience.md` 中记录本次重构的关键经验。 #### 进展记录 - [日期] [具体进展描述] @@ -60,3 +150,11 @@ ## 备注 [其他需要记录的信息] + +### 里程碑 +- [ ] 完成依赖安装与环境配置。 +- [ ] 完成tRPC后端实现。 +- [ ] 完成tRPC前端实现并成功通信。 +- [ ] 完成所有流式方法的重构。 +- [ ] 所有功能在桌面端测试通过。 +- [ ] 完成相关文档的编写与更新。 diff --git a/package.json b/package.json index f28743d9..09fe2a02 100644 --- a/package.json +++ b/package.json @@ -22,8 +22,9 @@ "dev:parallel": "concurrently -k -p \"[{name}]\" -n \"UI,WEB\" \"pnpm run watch:ui\" \"pnpm run dev:web\"", "dev:web": "pnpm -F @prompt-optimizer/web dev", "dev:ext": "pnpm -F @prompt-optimizer/extension dev", - "dev:desktop": "npm-run-all dev:setup dev:desktop:parallel", + "dev:desktop": "npm-run-all dev:setup dev:desktop:parallel:fixed", "dev:desktop:parallel": "concurrently -k -p \"[{name}]\" -n \"UI,WEB,DESKTOP\" \"pnpm run watch:ui\" \"pnpm run dev:web\" \"pnpm -F @prompt-optimizer/desktop dev\"", + "dev:desktop:parallel:fixed": "concurrently -k -p \"[{name}]\" -n \"WEB,DESKTOP\" \"pnpm run dev:web\" \"pnpm -F @prompt-optimizer/desktop dev\"", "dev:desktop:fresh": "npm-run-all clean setup:install dev:desktop", "test:core": "pnpm -F @prompt-optimizer/core test --run --passWithNoTests", "test:ui": "pnpm -F @prompt-optimizer/ui test --run --passWithNoTests", @@ -52,6 +53,7 @@ "@intlify/unplugin-vue-i18n": "^6.0.3", "concurrently": "^8.2.2", "cross-env": "^7.0.3", + "electron": "^37.1.0", "i18next": "^24.2.2", "i18next-browser-languagedetector": "^8.0.4", "lodash-unified": "^1.0.3", @@ -78,5 +80,13 @@ "memoize-one": "^6.0.0", "normalize-wheel-es": "^1.2.0", "vue-i18n": "^10.0.6" + }, + "keywords": [], + "author": "", + "license": "ISC", + "pnpm": { + "onlyBuiltDependencies": [ + "electron" + ] } } diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 613d77a1..c55b781c 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -38,7 +38,8 @@ export { LocalStorageProvider } from './services/storage/localStorageProvider' export { MemoryStorageProvider } from './services/storage/memoryStorageProvider' // 导出提示词服务相关 -export { PromptService, createPromptService } from './services/prompt/service' +export { PromptService } from './services/prompt/service' +export { createPromptService } from './services/prompt/factory' export * from './services/prompt/types' export { ElectronPromptServiceProxy } from './services/prompt/electron-proxy' export * from './services/prompt/errors' diff --git a/packages/core/src/services/prompt/factory.ts b/packages/core/src/services/prompt/factory.ts index cc7b60f8..3895b0d8 100644 --- a/packages/core/src/services/prompt/factory.ts +++ b/packages/core/src/services/prompt/factory.ts @@ -1,18 +1,22 @@ import { PromptService } from './service'; -import { TemplateManager } from '../template/manager'; -import { HistoryManager } from '../history/manager'; -import { ModelManager } from '../model/manager'; -import { LLMService } from '../llm/service'; -import { StorageFactory } from '../storage/factory'; - -// 创建共享的存储提供器实例 -const storageProvider = StorageFactory.createDefault(); - -export async function createPromptService() { - const modelManager = new ModelManager(storageProvider); - const llmService = new LLMService(modelManager); - const templateManager = new TemplateManager(storageProvider); - const historyManager = new HistoryManager(storageProvider); +import type { IModelManager } from '../model/types'; +import type { ITemplateManager } from '../template/types'; +import type { IHistoryManager } from '../history/types'; +import type { ILLMService } from '../llm/types'; +/** + * 创建PromptService实例 + * @param modelManager 模型管理器实例 + * @param llmService LLM服务实例 + * @param templateManager 模板管理器实例 + * @param historyManager 历史管理器实例 + * @returns PromptService实例 + */ +export function createPromptService( + modelManager: IModelManager, + llmService: ILLMService, + templateManager: ITemplateManager, + historyManager: IHistoryManager +): PromptService { return new PromptService(modelManager, llmService, templateManager, historyManager); -} \ No newline at end of file +} \ No newline at end of file diff --git a/packages/core/src/services/prompt/service.ts b/packages/core/src/services/prompt/service.ts index a592ab28..443b60c1 100644 --- a/packages/core/src/services/prompt/service.ts +++ b/packages/core/src/services/prompt/service.ts @@ -89,8 +89,8 @@ export class PromptService implements IPromptService { throw new OptimizationError('Model not found', request.targetPrompt); } - const template = this.templateManager.getTemplate( - request.templateId || this.getDefaultTemplateId( + const template = await this.templateManager.getTemplate( + request.templateId || await this.getDefaultTemplateId( request.optimizationMode === 'user' ? 'userOptimize' : 'optimize' ) ); @@ -141,7 +141,7 @@ export class PromptService implements IPromptService { // 获取迭代提示词 let template; try { - template = this.templateManager.getTemplate(templateId || DEFAULT_TEMPLATES.ITERATE); + template = await this.templateManager.getTemplate(templateId || DEFAULT_TEMPLATES.ITERATE); } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); throw new IterationError(`迭代失败: ${errorMessage}`, originalPrompt, iterateInput); @@ -308,8 +308,8 @@ export class PromptService implements IPromptService { throw new OptimizationError('Model not found', request.targetPrompt); } - const template = this.templateManager.getTemplate( - request.templateId || this.getDefaultTemplateId( + const template = await this.templateManager.getTemplate( + request.templateId || await this.getDefaultTemplateId( request.optimizationMode === 'user' ? 'userOptimize' : 'optimize' ) ); @@ -378,7 +378,7 @@ export class PromptService implements IPromptService { // 获取迭代提示词 let template; try { - template = this.templateManager.getTemplate(templateId); + template = await this.templateManager.getTemplate(templateId); } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); throw new IterationError(`Iteration failed: ${errorMessage}`, originalPrompt, iterateInput); @@ -439,10 +439,10 @@ export class PromptService implements IPromptService { /** * 获取默认模板ID */ - private getDefaultTemplateId(templateType: 'optimize' | 'userOptimize' | 'iterate'): string { + private async getDefaultTemplateId(templateType: 'optimize' | 'userOptimize' | 'iterate'): Promise { try { // 尝试获取指定类型的模板列表 - const templates = this.templateManager.listTemplatesByType(templateType); + const templates = await this.templateManager.listTemplatesByType(templateType); if (templates.length > 0) { // 返回列表中第一个模板的ID return templates[0].id; @@ -454,7 +454,7 @@ export class PromptService implements IPromptService { // 如果指定类型没有模板，尝试获取相关类型的模板作为回退 try { let fallbackTypes: ('optimize' | 'userOptimize' | 'iterate')[] = []; - + if (templateType === 'optimize') { fallbackTypes = ['userOptimize']; // optimize类型回退到userOptimize } else if (templateType === 'userOptimize') { @@ -462,17 +462,17 @@ export class PromptService implements IPromptService { } else if (templateType === 'iterate') { fallbackTypes = ['optimize', 'userOptimize']; // iterate类型回退到任意优化类型 } - + for (const fallbackType of fallbackTypes) { - const fallbackTemplates = this.templateManager.listTemplatesByType(fallbackType); + const fallbackTemplates = await this.templateManager.listTemplatesByType(fallbackType); if (fallbackTemplates.length > 0) { console.log(`Using fallback template type ${fallbackType} for ${templateType}`); return fallbackTemplates[0].id; } } - + // 最后的回退：获取所有模板中第一个可用的内置模板 - const allTemplates = this.templateManager.listTemplates(); + const allTemplates = await this.templateManager.listTemplates(); const availableTemplate = allTemplates.find(t => t.isBuiltin); if (availableTemplate) { console.warn(`Using fallback builtin template: ${availableTemplate.id} for type ${templateType}`); @@ -499,7 +499,7 @@ export class PromptService implements IPromptService { version: 1, timestamp: Date.now(), modelKey: request.modelKey, - templateId: request.templateId || this.getDefaultTemplateId( + templateId: request.templateId || await this.getDefaultTemplateId( request.optimizationMode === 'user' ? 'userOptimize' : 'optimize' ), metadata: { @@ -540,19 +540,4 @@ export class PromptService implements IPromptService { // 这种混合架构是经过权衡的设计决策 } -/** - * 工厂函数，用于创建 PromptService 实例 - * @param modelManager 模型管理器 - * @param llmService LLM服务 - * @param templateManager 模板管理器 - * @param historyManager 历史记录管理器 - * @returns IPromptService 实例 - */ -export function createPromptService( - modelManager: IModelManager, - llmService: ILLMService, - templateManager: ITemplateManager, - historyManager: IHistoryManager -): IPromptService { - return new PromptService(modelManager, llmService, templateManager, historyManager); -} + diff --git a/packages/core/src/services/storage/factory.ts b/packages/core/src/services/storage/factory.ts index 39dd77df..5b1836ad 100644 --- a/packages/core/src/services/storage/factory.ts +++ b/packages/core/src/services/storage/factory.ts @@ -10,7 +10,6 @@ export type StorageType = 'localStorage' | 'dexie' | 'memory'; */ export class StorageFactory { // 单例实例缓存 - private static defaultInstance: IStorageProvider | null = null; private static instances: Map = new Map(); /** @@ -44,50 +43,19 @@ export class StorageFactory { return instance; } - /** - * 创建默认存储提供器（单例） - * 优先使用 Dexie，降级到 localStorage - */ - static createDefault(): IStorageProvider { - // 返回缓存的默认实例 - if (StorageFactory.defaultInstance) { - return StorageFactory.defaultInstance; - } - try { - // 检查是否支持 IndexedDB (Dexie 的基础) - if (typeof window !== 'undefined' && window.indexedDB) { - console.log('Using Dexie as default storage provider'); - StorageFactory.defaultInstance = StorageFactory.create('dexie'); - } else { - console.log('IndexedDB not available, using localStorage as default storage provider'); - StorageFactory.defaultInstance = StorageFactory.create('localStorage'); - } - } catch (error) { - console.warn('Dexie storage unavailable, falling back to localStorage:', error); - StorageFactory.defaultInstance = StorageFactory.create('localStorage'); - } - - return StorageFactory.defaultInstance; - } /** * 重置所有实例（主要用于测试） */ static reset(): void { - StorageFactory.defaultInstance = null; StorageFactory.instances.clear(); - + // 重置DexieStorageProvider的迁移状态 DexieStorageProvider.resetMigrationState(); } - /** - * 获取当前默认实例（用于调试） - */ - static getCurrentDefault(): IStorageProvider | null { - return StorageFactory.defaultInstance; - } + /** * 获取所有支持的存储类型 diff --git a/packages/core/src/services/template/electron-proxy.ts b/packages/core/src/services/template/electron-proxy.ts index 5666a1ca..bab37c24 100644 --- a/packages/core/src/services/template/electron-proxy.ts +++ b/packages/core/src/services/template/electron-proxy.ts @@ -25,10 +25,8 @@ export class ElectronTemplateManagerProxy implements ITemplateManager { return true; } - getTemplate(templateId: string): Template { - // 注意：ITemplateManager接口要求这是同步方法，但IPC是异步的 - // 这里需要抛出错误，因为代理模式下无法提供同步访问 - throw new Error(`getTemplate(${templateId}) is not supported in Electron proxy mode. Use async IPC calls instead.`); + async getTemplate(templateId: string): Promise