PromptX/Bug报告-MCP多项目环境记忆路径错误.md

🐛 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. 执行流程追踪

// 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. 问题代码定位

// 文件：src/lib/utils/executionContext.js 行89-94
// 策略3：现有.promptx目录
const existingPrompxRoot = findExistingPromptxDirectory(context.startDir);
if (existingPrompxRoot) {
  console.error(`[执行上下文] 发现现有.promptx目录: ${existingPrompxRoot}`);
  return existingPrompxRoot; // ❌ 返回了错误的项目路径！
}

// 文件：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. 创建多项目环境:

   mkdir -p ~/Desktop/ProjectA && echo '{}' > ~/Desktop/ProjectA/package.json
   mkdir -p ~/Desktop/ProjectB && echo '{}' > ~/Desktop/ProjectB/package.json
   mkdir -p ~/Desktop/PromptX  # 当前工作项目
   

2. 初始化.promptx目录:

   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. 检查记忆保存位置:

   find ~/Desktop -name "memory.xml" -exec ls -la {} \;
   

✅ 预期结果 vs 实际结果

步骤	预期结果	实际结果	状态
记忆保存位置	~/Desktop/PromptX/.promptx/memory/	~/Desktop/ProjectA/.promptx/memory/	❌ 失败
文件完整性	记忆保存到正确项目	记忆保存到错误项目	❌ 失败

---

🛠️ 潜在解决方案分析

🎯 方案1: 优化策略优先级 (推荐)

核心思路: 调整getWorkspaceSynchronous()的策略顺序，优先使用更精确的方法

// 修改建议：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: 智能项目匹配算法 (中期)

核心思路: 增加项目特征识别和距离计算

// 新增函数：智能项目根目录查找
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配置中明确指定工作目录

// 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主动提供工作目录

// 工具接口修改
{
  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模式不受影响
• 不同操作系统下表现一致

🎯 自动化测试方案

// 测试用例设计
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 规范
• Claude Desktop MCP配置指南
• Node.js 路径解析最佳实践

---

🎯 结论与建议

🚨 严重性评估

此Bug属于高危级别，直接影响用户数据完整性和系统可信度，需要立即修复。

💡 修复建议

1. 立即: 通过文档指导用户配置环境变量解决
2. 短期: 实施方案1优化策略优先级
3. 中期: 开发智能项目匹配算法
4. 长期: 重构MCP接口设计

🎖️ 经验总结

1. 多环境兼容性: 路径解析需要考虑复杂的多项目环境
2. 用户体验: 系统应该智能处理路径歧义，减少用户配置负担
3. 测试覆盖: 需要增加多项目环境的测试用例
4. 文档完善: MCP配置指南需要更详细的环境变量说明

---

报告生成时间: 2025-06-25
报告版本: v1.0
下次更新: 修复实施后
状态: 🔴 待修复

---

📞 联系信息

如有问题或需要进一步信息，请联系：

• 技术负责人: AI Memory Specialist
• 项目仓库: PromptX GitHub Repository
• 优先级: 高危 - 立即处理