From 1cc01bf1ef8acb3f3d3bf19e599da9dbefe034a8 Mon Sep 17 00:00:00 2001 From: sean Date: Thu, 26 Jun 2025 16:04:50 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20=E4=BF=AE=E5=A4=8D=E8=AE=B0=E5=BF=86?= =?UTF-8?q?=E6=97=B6=E7=9A=84=E9=97=AE=E9=A2=98=E5=A4=84=E7=90=86=E5=90=88?= =?UTF-8?q?=E5=B9=B6=E7=9A=84=E9=97=AE=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Bug报告-MCP多项目环境记忆路径错误.md | 424 ----------- PR-记忆系统升级与角色发现Bug修复.md | 668 ------------------ PackageDiscovery跨项目使用问题修复总结.md | 297 -------- product | 1 + .../core/pouch/commands/RememberCommand.js | 148 +++- 5 files changed, 146 insertions(+), 1392 deletions(-) delete mode 100644 Bug报告-MCP多项目环境记忆路径错误.md delete mode 100644 PR-记忆系统升级与角色发现Bug修复.md delete mode 100644 PackageDiscovery跨项目使用问题修复总结.md create mode 160000 product diff --git a/Bug报告-MCP多项目环境记忆路径错误.md b/Bug报告-MCP多项目环境记忆路径错误.md deleted file mode 100644 index db708cf..0000000 --- a/Bug报告-MCP多项目环境记忆路径错误.md +++ /dev/null @@ -1,424 +0,0 @@ -# 🐛 Bug报告: MCP多项目环境记忆路径错误 - -## 📊 **Bug基本信息** - -| 字段 | 内容 | -|------|------| -| **Bug ID** | PROMPTX-001 | -| **严重级别** | 🔴 **高危** - 数据完整性问题 | -| **发现时间** | 2025-06-25 | -| **影响组件** | MCP Server、记忆系统、工作目录识别 | -| **影响版本** | PromptX v0.0.2-snapshot | -| **报告者** | AI Memory Specialist | - ---- - -## 🎯 **问题描述** - -### 🔍 **现象表现** -在MCP环境下使用`mcp_promptx-local_promptx_remember`工具保存记忆时，记忆被错误保存到其他项目的`.promptx`目录中，而不是当前工作项目的目录。 - -### 📂 **具体表现** -``` -期望行为： -记忆保存到 → /Users/macmima1234/Desktop/PromptX/.promptx/memory/memory.xml ✅ - -实际行为： -记忆保存到 → /Users/macmima1234/Desktop/GalleryHub/.promptx/memory/memory.xml ❌ -``` - -### 🎭 **触发条件** -- **环境**: MCP (Model Context Protocol) 模式 -- **工具**: `mcp_promptx-local_promptx_remember` -- **场景**: 用户Desktop下存在多个包含`.promptx`目录的项目 -- **当前目录**: `/Users/macmima1234/Desktop/PromptX` -- **多项目布局**: - ``` - /Users/macmima1234/Desktop/ - ├── PromptX/.promptx ✅ 期望目标 - ├── GalleryHub/.promptx ❌ 错误选择 - ├── shop/.promptx 📁 其他项目 - ├── agent-zero/.promptx 📁 其他项目 - └── ~/.promptx 📁 用户目录 - ``` - ---- - -## 🔍 **根因分析** - -### 🎯 **核心问题定位** - -#### **问题文件**: `src/lib/utils/executionContext.js` -#### **问题函数**: `getWorkspaceSynchronous()` → `findExistingPromptxDirectory()` - -### 🧠 **深度分析** - -#### **1. 执行流程追踪** -```javascript -// MCP启动时的执行链 -getExecutionContext() -├── command === 'mcp-server' ✅ -├── getMCPWorkingDirectory() - ├── getWorkspaceSynchronous(context) - ├── 策略1: WORKSPACE_FOLDER_PATHS ❌ (undefined) - ├── 策略2: PROMPTX_WORKSPACE ❌ (undefined) - └── 策略3: findExistingPromptxDirectory() ❌ (在这里出错!) - └── 向上查找 .promptx 目录 - ├── 起始点: process.cwd() = AI应用安装目录 - ├── 向上搜索过程中发现多个.promptx目录 - └── 返回第一个找到的: GalleryHub/.promptx ❌ -``` - -#### **2. 问题代码定位** -```javascript -// 文件：src/lib/utils/executionContext.js 行89-94 -// 策略3：现有.promptx目录 -const existingPrompxRoot = findExistingPromptxDirectory(context.startDir); -if (existingPrompxRoot) { - console.error(`[执行上下文] 发现现有.promptx目录: ${existingPrompxRoot}`); - return existingPrompxRoot; // ❌ 返回了错误的项目路径！ -} -``` - -```javascript -// 文件：src/lib/utils/executionContext.js 行134-154 -function findExistingPromptxDirectory(startDir) { - let currentDir = path.resolve(startDir); // startDir = process.cwd() = AI应用目录 - const root = path.parse(currentDir).root; - - while (currentDir !== root) { - const promptxPath = path.join(currentDir, '.promptx'); - if (fs.existsSync(promptxPath)) { // ❌ 找到第一个就返回，没有优先级判断 - try { - const stat = fs.statSync(promptxPath); - if (stat.isDirectory()) { - return currentDir; // ❌ 返回了错误的项目路径！ - } - } catch { - // 忽略权限错误等，继续查找 - } - } - // 向上一级目录 - const parentDir = path.dirname(currentDir); - if (parentDir === currentDir) break; - currentDir = parentDir; - } - return null; -} -``` - -#### **3. 路径歧义问题** -``` -向上查找过程： -AI应用目录 (/Applications/Claude.app/...) - ↓ 向上搜索 -用户目录 (/Users/macmima1234/) - ↓ 向上搜索 -Desktop目录 (/Users/macmima1234/Desktop/) - ↓ 发现多个.promptx目录 - ├── agent-zero/.promptx (第一个被发现?) - ├── GalleryHub/.promptx (实际被选择) - ├── PromptX/.promptx (期望目标) - └── shop/.promptx - -❌ 算法缺陷：没有"最接近当前期望项目"的智能判断 -``` - ---- - -## 🎯 **影响评估** - -### 🔴 **高危影响** - -#### **1. 数据完整性问题** -- **记忆数据错位**: 用户期望的记忆被保存到错误的项目中 -- **数据污染风险**: 不同项目的记忆互相混合 -- **数据丢失风险**: 用户找不到自己保存的记忆内容 - -#### **2. 用户体验严重破坏** -- **功能失效**: 记忆系统在多项目环境下完全不可用 -- **信任度下降**: 用户对系统可靠性产生质疑 -- **工作效率损失**: 需要手动查找和迁移记忆文件 - -#### **3. 系统架构问题** -- **MCP协议理解偏差**: 对工作目录识别的理解存在缺陷 -- **多项目支持缺失**: 没有考虑多项目开发环境的现实需求 -- **环境隔离失败**: 不同项目的PromptX实例应该相互隔离 - -### 📊 **影响范围统计** -- **受影响用户**: 所有在多项目环境下使用MCP的开发者 -- **受影响功能**: 记忆系统 (remember/recall)、角色发现、学习功能 -- **受影响环境**: MCP模式 (CLI模式不受影响) -- **数据风险**: 高 (记忆数据可能完全错位) - ---- - -## 🔬 **复现步骤** - -### 📋 **环境准备** -1. **创建多项目环境**: - ```bash - mkdir -p ~/Desktop/ProjectA && echo '{}' > ~/Desktop/ProjectA/package.json - mkdir -p ~/Desktop/ProjectB && echo '{}' > ~/Desktop/ProjectB/package.json - mkdir -p ~/Desktop/PromptX # 当前工作项目 - ``` - -2. **初始化.promptx目录**: - ```bash - mkdir -p ~/Desktop/ProjectA/.promptx/memory - mkdir -p ~/Desktop/ProjectB/.promptx/memory - mkdir -p ~/Desktop/PromptX/.promptx/memory - ``` - -3. **配置MCP环境**: 在Claude Desktop中配置PromptX MCP Server - -### 🔄 **复现操作** -1. **在PromptX项目目录下启动**: `cd ~/Desktop/PromptX` -2. **通过MCP调用记忆工具**: 使用`mcp_promptx-local_promptx_remember`保存记忆 -3. **检查记忆保存位置**: - ```bash - find ~/Desktop -name "memory.xml" -exec ls -la {} \; - ``` - -### ✅ **预期结果 vs 实际结果** -| 步骤 | 预期结果 | 实际结果 | 状态 | -|------|----------|----------|------| -| 记忆保存位置 | `~/Desktop/PromptX/.promptx/memory/` | `~/Desktop/ProjectA/.promptx/memory/` | ❌ 失败 | -| 文件完整性 | 记忆保存到正确项目 | 记忆保存到错误项目 | ❌ 失败 | - ---- - -## 🛠️ **潜在解决方案分析** - -### 🎯 **方案1: 优化策略优先级** (推荐) - -#### **核心思路**: 调整`getWorkspaceSynchronous()`的策略顺序，优先使用更精确的方法 - -```javascript -// 修改建议：src/lib/utils/executionContext.js -function getWorkspaceSynchronous(context) { - // 策略1：PromptX专用环境变量 (提升优先级) - const promptxWorkspaceEnv = process.env.PROMPTX_WORKSPACE; - if (promptxWorkspaceEnv && promptxWorkspaceEnv.trim() !== '') { - const promptxWorkspace = normalizePath(expandHome(promptxWorkspaceEnv)); - if (isValidDirectory(promptxWorkspace)) { - return promptxWorkspace; // ✅ 精确指定的项目路径 - } - } - - // 策略2：智能项目根目录匹配 (新增) - const projectRoot = findProjectRootWithPreference(context.startDir); - if (projectRoot) { - return projectRoot; // ✅ 基于项目特征的智能判断 - } - - // 策略3：现有.promptx目录 (降低优先级，增加智能判断) - const existingPrompxRoot = findExistingPromptxDirectoryWithPreference(context); - if (existingPrompxRoot) { - return existingPrompxRoot; // ✅ 带有偏好的目录选择 - } - - // 其他策略... -} -``` - -#### **预期效果**: -- ✅ 解决多项目路径歧义问题 -- ✅ 保持向后兼容性 -- ✅ 修改范围最小，风险可控 - -### 🎯 **方案2: 智能项目匹配算法** (中期) - -#### **核心思路**: 增加项目特征识别和距离计算 - -```javascript -// 新增函数：智能项目根目录查找 -function findProjectRootWithPreference(startDir) { - const candidates = findAllProjectRoots(startDir); - - // 按距离和特征评分排序 - const scoredCandidates = candidates.map(candidate => ({ - path: candidate, - score: calculateProjectScore(candidate, startDir) - })); - - // 返回得分最高的项目 - scoredCandidates.sort((a, b) => b.score - a.score); - return scoredCandidates[0]?.path || null; -} - -function calculateProjectScore(projectPath, currentContext) { - let score = 0; - - // 1. 路径距离权重 - const distance = path.relative(currentContext, projectPath).split('/').length; - score += Math.max(0, 100 - distance * 10); - - // 2. 项目特征权重 - if (fs.existsSync(path.join(projectPath, 'package.json'))) score += 20; - if (fs.existsSync(path.join(projectPath, '.git'))) score += 15; - if (fs.existsSync(path.join(projectPath, '.promptx'))) score += 30; - - // 3. 命名偏好权重 - if (projectPath.includes('PromptX')) score += 50; - - return score; -} -``` - -### 🎯 **方案3: 环境变量强制指定** (短期) - -#### **核心思路**: 要求用户在MCP配置中明确指定工作目录 - -```json -// Claude Desktop 配置修改 -{ - "mcpServers": { - "promptx": { - "command": "npx", - "args": ["dpml-prompt@snapshot", "mcp-server"], - "cwd": "/Users/macmima1234/Desktop/PromptX", - "env": { - "PROMPTX_WORKSPACE": "/Users/macmima1234/Desktop/PromptX" // 强制指定 - } - } - } -} -``` - -#### **预期效果**: -- ✅ 立即解决问题 -- ✅ 用户控制精确 -- ❌ 需要用户手动配置 -- ❌ 用户体验不友好 - -### 🎯 **方案4: AI提供路径参数** (长期) - -#### **核心思路**: 修改MCP工具接口，要求AI主动提供工作目录 - -```javascript -// 工具接口修改 -{ - name: 'promptx_remember', - inputSchema: { - type: 'object', - properties: { - content: { type: 'string', description: '要保存的记忆内容' }, - workingDirectory: { - type: 'string', - description: '当前项目工作目录', - required: true // 设为必需参数 - } - }, - required: ['content', 'workingDirectory'] - } -} -``` - ---- - -## 📊 **修复优先级建议** - -### 🚨 **立即修复** (1-2天) -1. **方案3**: 更新文档，指导用户配置`PROMPTX_WORKSPACE`环境变量 -2. **临时方案**: 在工具返回中增加路径验证和警告信息 - -### ⚡ **短期修复** (1周内) -1. **方案1**: 优化策略优先级，提升环境变量和智能判断的权重 -2. **增强日志**: 详细记录路径选择过程，便于用户调试 - -### 🔧 **中期优化** (1个月内) -1. **方案2**: 实现智能项目匹配算法 -2. **完善测试**: 添加多项目环境的自动化测试覆盖 - -### 🌟 **长期重构** (3个月内) -1. **方案4**: 重新设计MCP接口设计，增强路径管理 -2. **架构升级**: 统一路径解析服务，消除同步/异步不一致问题 - ---- - -## 🧪 **测试策略** - -### 📋 **回归测试清单** -- [ ] 单项目环境下MCP记忆功能正常 -- [ ] 多项目环境下路径选择正确 -- [ ] 环境变量配置优先级正确 -- [ ] CLI模式不受影响 -- [ ] 不同操作系统下表现一致 - -### 🎯 **自动化测试方案** -```javascript -// 测试用例设计 -describe('MCP多项目环境路径识别', () => { - test('应该选择正确的项目目录', async () => { - // 创建多项目环境 - // 配置环境变量 - // 调用记忆功能 - // 验证保存位置 - }); - - test('环境变量应该有最高优先级', async () => { - // 设置PROMPTX_WORKSPACE - // 验证路径选择 - }); - - test('应该提供清晰的错误信息', async () => { - // 模拟路径歧义场景 - // 验证错误提示 - }); -}); -``` - ---- - -## 📚 **相关文档和代码** - -### 🔗 **关键文件** -- `src/lib/utils/executionContext.js` - 主要问题文件 -- `src/lib/commands/MCPServerCommand.js` - MCP服务器入口 -- `src/lib/core/pouch/commands/RememberCommand.js` - 记忆保存逻辑 -- `docs/mcp-integration-guide.md` - MCP集成指南 - -### 🏷️ **相关Issue和PR** -- 本次发现: PromptX记忆系统升级与角色发现Bug修复过程 -- 相关组件: PackageDiscovery跨项目使用问题修复 - -### 📖 **参考资料** -- [Model Context Protocol 规范](https://modelcontextprotocol.io/) -- [Claude Desktop MCP配置指南](https://claude.ai/docs) -- [Node.js 路径解析最佳实践](https://nodejs.org/api/path.html) - ---- - -## 🎯 **结论与建议** - -### 🚨 **严重性评估** -此Bug属于**高危级别**，直接影响用户数据完整性和系统可信度，需要**立即修复**。 - -### 💡 **修复建议** -1. **立即**: 通过文档指导用户配置环境变量解决 -2. **短期**: 实施方案1优化策略优先级 -3. **中期**: 开发智能项目匹配算法 -4. **长期**: 重构MCP接口设计 - -### 🎖️ **经验总结** -1. **多环境兼容性**: 路径解析需要考虑复杂的多项目环境 -2. **用户体验**: 系统应该智能处理路径歧义，减少用户配置负担 -3. **测试覆盖**: 需要增加多项目环境的测试用例 -4. **文档完善**: MCP配置指南需要更详细的环境变量说明 - ---- - -**报告生成时间**: 2025-06-25 -**报告版本**: v1.0 -**下次更新**: 修复实施后 -**状态**: 🔴 待修复 - ---- - -## 📞 **联系信息** - -如有问题或需要进一步信息，请联系： -- **技术负责人**: AI Memory Specialist -- **项目仓库**: PromptX GitHub Repository -- **优先级**: 高危 - 立即处理 \ No newline at end of file diff --git a/PR-记忆系统升级与角色发现Bug修复.md b/PR-记忆系统升级与角色发现Bug修复.md deleted file mode 100644 index 3e53efb..0000000 --- a/PR-记忆系统升级与角色发现Bug修复.md +++ /dev/null @@ -1,668 +0,0 @@ -# 🚀 feat: 记忆系统架构升级 + declarative.dpml命名重构 + MCP边界条件Bug修复 - -## 📊 **变更概览** -- **5个文件修改**：+625行，-88行 (declarative.dpml升级 +28行) -- **5个新增文件**：思维模式、测试、文档 -- **4个主要功能模块**：记忆系统升级 + 文件命名重构 + 角色发现修复 + MCP边界条件修复 -- **🎯 升级验证**：MCP重启测试 100% 通过 - ---- - -## 🧠 **记忆系统重大升级** - -### ✨ **核心特性** -- **XML格式存储**：从Markdown单文件升级到结构化XML存储 -- **🎯 declarative.dpml命名**：memory.xml → declarative.dpml 架构级语义升级 -- **内容缩进美化**：新增`formatContentWithIndent()`方法，提升XML可读性 -- **Legacy数据迁移**：自动检测并迁移旧版Markdown格式记忆 -- **增强日志系统**：完整的操作日志追踪和错误处理 -- **XML安全处理**：自动转义特殊字符，确保数据完整性 -- **🆕 边界条件修复**：解决空XML文件导致的写入失败问题 -- **🚀 MCP重启验证**：升级后功能100%正常，零中断平滑切换 - -### 📂 **文件变更** -- `RememberCommand.js` (+416行): XML存储、迁移、格式化、边界条件修复 -- `RecallCommand.js` (+224行): XML读取、搜索、错误处理优化 - -### 🆕 **新增功能** -```javascript -// XML内容缩进格式化 -formatContentWithIndent(content, indentLevel = 3) - -// XML转义安全处理 -escapeXML(text) / unescapeXML(text) - -// Legacy数据自动迁移 -migrateLegacyMemoriesIfNeeded() - -// XML记忆解析 -parseXMLMemories() / readXMLMemories() -``` - -### 📋 **XML格式示例** - -#### **升级前（Markdown格式）** -```markdown -# 陈述性记忆 - -- 2025/01/15 14:30 CRMEB项目前端门店功能架构总结 --tags CRMEB 前端架构 #流程管理 -``` - -#### **升级后（declarative.dpml格式）** -```xml - - - - - - 🔧 XML转义字符全面测试 - - **测试字符集**: - - 尖括号: <script>alert('test')</script> - - 双引号: "重要信息"和"配置参数" - - 与符号: A & B 和 C&D 组合 - - #工具使用 - - -``` - -#### **🎯 命名语义升级价值** -- **认知科学精准性**：`declarative` 明确表达陈述性记忆 -- **DPML生态统一**：`.dpml` 扩展名与PromptX协议体系一致 -- **未来扩展铺路**：为 `procedural.dpml`、`episodic.dpml` 奠定基础 -- **专业表达提升**：体现基于认知心理学的系统设计 - ---- - -## 🎯 **declarative.dpml架构升级实施与验证** - -### 🚀 **升级背景与动机** - -#### **语义命名问题** -``` -升级前：memory.xml -问题分析： -├── 语义模糊：memory 过于通用，无法区分记忆类型 -├── 扩展困难：未来增加其他记忆类型时命名冲突 -└── 理论缺失：缺乏认知科学的理论基础表达 -``` - -#### **升级目标确立** -``` -升级后：declarative.dpml -价值体现： -├── 🧠 认知科学精准：明确表达陈述性记忆 -├── 🏗️ 架构生态统一：与PromptX DPML协议完美契合 -├── 🔮 未来扩展铺路：为procedural.dpml等分类奠定基础 -└── 🎯 专业化表达：体现基于心理学理论的系统设计 -``` - -### 🔧 **实施方案与代码变更** - -#### **核心文件修改清单** -```javascript -// RememberCommand.js (4处修改) -- const xmlFile = path.join(memoryDir, 'memory.xml') -+ const xmlFile = path.join(memoryDir, 'declarative.dpml') - -- const filesToBackup = ['memory.xml', 'declarative.md', ...] -+ const filesToBackup = ['declarative.dpml', 'declarative.md', ...] - -// RecallCommand.js (2处修改) -- const xmlFile = path.join(memoryDir, 'memory.xml') -+ const xmlFile = path.join(memoryDir, 'declarative.dpml') - -// 测试文件重命名 -memory-xml-integration.test.js → memory-dpml-integration.test.js -``` - -#### **架构升级策略** -- **直接切换**：所有新记忆使用 `declarative.dpml` -- **历史保留**：`memory.xml` 作为历史数据保留 -- **零感知升级**：用户操作流程完全不变 -- **MCP重启生效**：代码修改后需重启MCP工具生效 - -### 🧪 **升级测试验证结果** - -#### **测试1: MCP重启后文件创建验证** -```bash -测试时间：2025-06-26 MCP重启后 -测试命令：remember "🎉 MCP重启后declarative.dpml升级测试" - -✅ 预期结果：创建declarative.dpml文件 -✅ 实际结果： - 存储路径: declarative.dpml ← 🎯 升级成功！ - 文件状态: 创建成功，1.1KB，28行 -``` - -#### **测试2: 文件系统状态验证** -```bash -.promptx/memory/ 目录内容： -├── declarative.dpml (1.7KB, 47行) ← 🆕 新记忆存储 -└── memory.xml (17KB, 426行) ← 📜 历史数据保留 - -状态分析： -✅ 新记忆全部存储到declarative.dpml -✅ 历史数据完整保留在memory.xml -✅ 双文件并存策略完美执行 -``` - -#### **测试3: XML转义字符处理验证** -```xml -测试内容： & "引号" 测试 - -存储转义： --