@chongyan/autospec 1.0.2 → 1.0.3

package/plugins/hooks/lib/memory-manager.js

@@ -1,673 +0,0 @@
-/**
- * Memory Manager - 统一的记忆管理模块
- *
- * 提供全局 + 项目双模式的记忆读写功能
- * 复用 hook-state-manager.js 的设计模式
- */
-
-import fs from 'fs';
-import path from 'path';
-import os from 'os';
-import {
-  GLOBAL_MEMORY_DIR,
-  MEMORY_DIRS,
-  MEMORY_FILES,
-  MEMORY_SCOPE,
-  MEMORY_TTL,
-  MEMORY_LAYERS,
-  DEFAULT_NORTH_STAR,
-  DEFAULT_TEAM_PREFERENCES,
-  DEFAULT_CONSTRAINTS,
-  DEFAULT_MEMORY_META
-} from '../../../scripts/install/constants.js';
-
-// 缓存
-const memoryCache = new Map();
-const CACHE_TTL = 300000; // 5分钟缓存
-
-/**
- * 获取全局记忆目录路径
- * @returns {string} 全局记忆目录路径
- */
-export function getGlobalMemoryDir() {
-  return path.join(os.homedir(), GLOBAL_MEMORY_DIR);
-}
-
-/**
- * 获取项目记忆目录路径
- * @param {string} projectRoot - 项目根目录
- * @returns {string} 项目记忆目录路径
- */
-export function getProjectMemoryDir(projectRoot) {
-  return path.join(projectRoot, '.autospec', MEMORY_DIRS.ROOT);
-}
-
-/**
- * 解析记忆文件路径
- * @param {string} scope - 作用域 ('global' | 'project')
- * @param {string} relativePath - 相对路径
- * @param {string} projectRoot - 项目根目录（project scope 时必需）
- * @returns {string} 完整文件路径
- */
-export function resolveMemoryPath(scope, relativePath, projectRoot = null) {
-  if (scope === MEMORY_SCOPE.GLOBAL) {
-    return path.join(getGlobalMemoryDir(), relativePath);
-  } else {
-    if (!projectRoot) {
-      throw new Error('projectRoot is required for project scope');
-    }
-    return path.join(getProjectMemoryDir(projectRoot), relativePath);
-  }
-}
-
-/**
- * 安全地读取 JSON 文件
- * @param {string} filePath - 文件路径
- * @param {any} defaultValue - 默认值
- * @returns {any} 解析后的数据或默认值
- */
-function safeReadJson(filePath, defaultValue = null) {
-  try {
-    if (!fs.existsSync(filePath)) {
-      return defaultValue;
-    }
-    const content = fs.readFileSync(filePath, 'utf-8');
-    return JSON.parse(content);
-  } catch (e) {
-    return defaultValue;
-  }
-}
-
-/**
- * 安全地写入 JSON 文件
- * @param {string} filePath - 文件路径
- * @param {any} data - 要写入的数据
- * @returns {boolean} 是否成功
- */
-function safeWriteJson(filePath, data) {
-  try {
-    const dir = path.dirname(filePath);
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true });
-    }
-    fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
-    return true;
-  } catch (e) {
-    if (e.code === 'EACCES') {
-      console.error(`[AutoSpec memory-manager] ⚠️ 权限错误: 无法写入 ${filePath}`);
-      console.error(`[AutoSpec memory-manager] 请运行: sudo chown -R $(whoami) ${path.dirname(filePath)}`);
-    }
-    return false;
-  }
-}
-
-// ============================================================
-// Memory 读取操作
-// ============================================================
-
-/**
- * 获取记忆内容
- * @param {string} scope - 作用域 ('global' | 'project')
- * @param {string} memoryFile - 记忆文件路径（相对）
- * @param {string} projectRoot - 项目根目录（project scope 时必需）
- * @param {boolean} useCache - 是否使用缓存
- * @returns {Object|null} 记忆内容
- */
-export function getMemory(scope, memoryFile, projectRoot = null, useCache = false) {
-  const cacheKey = `${scope}:${memoryFile}:${projectRoot || 'global'}`;
-
-  if (useCache) {
-    const cached = memoryCache.get(cacheKey);
-    if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
-      return cached.data;
-    }
-  }
-
-  const filePath = resolveMemoryPath(scope, memoryFile, projectRoot);
-  const memory = safeReadJson(filePath, null);
-
-  if (useCache && memory) {
-    memoryCache.set(cacheKey, { data: memory, timestamp: Date.now() });
-  }
-
-  return memory;
-}
-
-/**
- * 更新记忆内容
- * @param {string} scope - 作用域 ('global' | 'project')
- * @param {string} memoryFile - 记忆文件路径（相对）
- * @param {Object} updates - 要更新的内容
- * @param {string} projectRoot - 项目根目录（project scope 时必需）
- * @returns {boolean} 是否成功
- */
-export function updateMemory(scope, memoryFile, updates, projectRoot = null) {
-  const existing = getMemory(scope, memoryFile, projectRoot, false) || {};
-  const newMemory = {
-    ...existing,
-    ...updates,
-    lastUpdated: new Date().toISOString()
-  };
-
-  const filePath = resolveMemoryPath(scope, memoryFile, projectRoot);
-  const success = safeWriteJson(filePath, newMemory);
-
-  if (success) {
-    const cacheKey = `${scope}:${memoryFile}:${projectRoot || 'global'}`;
-    memoryCache.set(cacheKey, { data: newMemory, timestamp: Date.now() });
-  }
-
-  return success;
-}
-
-// ============================================================
-// 北极星指标 (项目级)
-// ============================================================
-
-/**
- * 获取北极星指标
- * @param {string} projectRoot - 项目根目录
- * @returns {Object} 北极星指标
- */
-export function getNorthStar(projectRoot) {
-  return getMemory(MEMORY_SCOPE.PROJECT, MEMORY_FILES.NORTH_STAR, projectRoot, true)
-    || DEFAULT_NORTH_STAR;
-}
-
-/**
- * 更新北极星指标
- * @param {string} projectRoot - 项目根目录
- * @param {Object} updates - 要更新的内容
- * @returns {boolean} 是否成功
- */
-export function updateNorthStar(projectRoot, updates) {
-  return updateMemory(MEMORY_SCOPE.PROJECT, MEMORY_FILES.NORTH_STAR, updates, projectRoot);
-}
-
-/**
- * 添加关键结果
- * @param {string} projectRoot - 项目根目录
- * @param {Object} keyResult - 关键结果
- * @returns {boolean} 是否成功
- */
-export function addKeyResult(projectRoot, keyResult) {
-  const northStar = getNorthStar(projectRoot);
-  const newKR = {
-    id: `kr-${Date.now()}`,
-    ...keyResult,
-    status: keyResult.status || 'on-track'
-  };
-  northStar.keyResults = northStar.keyResults || [];
-  northStar.keyResults.push(newKR);
-  return updateNorthStar(projectRoot, { keyResults: northStar.keyResults });
-}
-
-/**
- * 添加活跃决策
- * @param {string} projectRoot - 项目根目录
- * @param {Object} decision - 决策
- * @returns {boolean} 是否成功
- */
-export function addActiveDecision(projectRoot, decision) {
-  const northStar = getNorthStar(projectRoot);
-  const newDecision = {
-    id: `dec-${Date.now()}`,
-    madeAt: new Date().toISOString().split('T')[0],
-    ...decision
-  };
-  northStar.activeDecisions = northStar.activeDecisions || [];
-  northStar.activeDecisions.push(newDecision);
-  return updateNorthStar(projectRoot, { activeDecisions: northStar.activeDecisions });
-}
-
-// ============================================================
-// 团队偏好 (全局优先，项目可覆盖)
-// ============================================================
-
-/**
- * 获取团队偏好（优先项目覆盖，fallback 全局）
- * @param {string} projectRoot - 项目根目录
- * @returns {Object} 团队偏好
- */
-export function getTeamPreferences(projectRoot) {
-  // 优先读取项目级偏好
-  const projectPrefs = getMemory(MEMORY_SCOPE.PROJECT, MEMORY_FILES.TEAM_PREFERENCES, projectRoot, true);
-  if (projectPrefs && Object.keys(projectPrefs).length > 1) {
-    return projectPrefs;
-  }
-
-  // Fallback 到全局偏好
-  const globalPrefs = getMemory(MEMORY_SCOPE.GLOBAL, MEMORY_FILES.TEAM_PREFERENCES, null, true);
-  if (globalPrefs && Object.keys(globalPrefs).length > 1) {
-    return globalPrefs;
-  }
-
-  return DEFAULT_TEAM_PREFERENCES;
-}
-
-/**
- * 更新团队偏好
- * @param {string} scope - 作用域 ('global' | 'project')
- * @param {Object} updates - 要更新的内容
- * @param {string} projectRoot - 项目根目录（project scope 时必需）
- * @returns {boolean} 是否成功
- */
-export function updateTeamPreferences(scope, updates, projectRoot = null) {
-  return updateMemory(scope, MEMORY_FILES.TEAM_PREFERENCES, updates, projectRoot);
-}
-
-// ============================================================
-// 约束条件 (全局优先，项目可覆盖)
-// ============================================================
-
-/**
- * 获取约束条件（优先项目覆盖，fallback 全局）
- * @param {string} projectRoot - 项目根目录
- * @returns {Object} 约束条件
- */
-export function getConstraints(projectRoot) {
-  // 优先读取项目级约束
-  const projectConstraints = getMemory(MEMORY_SCOPE.PROJECT, MEMORY_FILES.CONSTRAINTS, projectRoot, true);
-  if (projectConstraints && (projectConstraints.hardConstraints?.length > 0 || projectConstraints.softConstraints?.length > 0)) {
-    return projectConstraints;
-  }
-
-  // Fallback 到全局约束
-  const globalConstraints = getMemory(MEMORY_SCOPE.GLOBAL, MEMORY_FILES.CONSTRAINTS, null, true);
-  if (globalConstraints && (globalConstraints.hardConstraints?.length > 0 || globalConstraints.softConstraints?.length > 0)) {
-    return globalConstraints;
-  }
-
-  return DEFAULT_CONSTRAINTS;
-}
-
-/**
- * 添加硬约束
- * @param {string} scope - 作用域
- * @param {string} constraint - 约束内容
- * @param {string} projectRoot - 项目根目录（project scope 时必需）
- * @returns {boolean} 是否成功
- */
-export function addHardConstraint(scope, constraint, projectRoot = null) {
-  const constraints = getConstraints(projectRoot);
-  constraints.hardConstraints = constraints.hardConstraints || [];
-  constraints.hardConstraints.push({
-    id: `hc-${Date.now()}`,
-    content: constraint,
-    addedAt: new Date().toISOString()
-  });
-  return updateMemory(scope, MEMORY_FILES.CONSTRAINTS, constraints, projectRoot);
-}
-
-// ============================================================
-// 当前上下文 (工作记忆)
-// ============================================================
-
-/**
- * 获取当前任务上下文
- * @param {string} projectRoot - 项目根目录
- * @returns {Object|null} 当前上下文
- */
-export function getCurrentContext(projectRoot) {
-  return getMemory(MEMORY_SCOPE.PROJECT, MEMORY_FILES.CURRENT_CONTEXT, projectRoot, true);
-}
-
-/**
- * 更新当前任务上下文
- * @param {string} projectRoot - 项目根目录
- * @param {Object} updates - 要更新的内容
- * @returns {boolean} 是否成功
- */
-export function updateCurrentContext(projectRoot, updates) {
-  const existing = getCurrentContext(projectRoot) || {};
-  const newContext = {
-    ...existing,
-    ...updates,
-    updatedAt: new Date().toISOString()
-  };
-  return updateMemory(MEMORY_SCOPE.PROJECT, MEMORY_FILES.CURRENT_CONTEXT, newContext, projectRoot);
-}
-
-/**
- * 清除当前任务上下文
- * @param {string} projectRoot - 项目根目录
- * @returns {boolean} 是否成功
- */
-export function clearCurrentContext(projectRoot) {
-  const filePath = resolveMemoryPath(MEMORY_SCOPE.PROJECT, MEMORY_FILES.CURRENT_CONTEXT, projectRoot);
-  try {
-    if (fs.existsSync(filePath)) {
-      fs.unlinkSync(filePath);
-    }
-    const cacheKey = `${MEMORY_SCOPE.PROJECT}:${MEMORY_FILES.CURRENT_CONTEXT}:${projectRoot}`;
-    memoryCache.delete(cacheKey);
-    return true;
-  } catch (e) {
-    return false;
-  }
-}
-
-// ============================================================
-// 会话记忆
-// ============================================================
-
-/**
- * 获取会话索引
- * @param {string} projectRoot - 项目根目录
- * @returns {Object} 会话索引
- */
-export function getSessionsIndex(projectRoot) {
-  return getMemory(MEMORY_SCOPE.PROJECT, MEMORY_FILES.SESSIONS_INDEX, projectRoot, true)
-    || { sessions: [], lastIndexed: null };
-}
-
-/**
- * 添加会话记录
- * @param {string} projectRoot - 项目根目录
- * @param {Object} session - 会话信息
- * @returns {boolean} 是否成功
- */
-export function addSession(projectRoot, session) {
-  const index = getSessionsIndex(projectRoot);
-  const newSession = {
-    id: `sess-${Date.now()}`,
-    date: new Date().toISOString().split('T')[0],
-    ...session
-  };
-
-  index.sessions = index.sessions || [];
-  index.sessions.unshift(newSession); // 最新的在前面
-  index.lastIndexed = new Date().toISOString();
-
-  // 保留最近 100 条
-  if (index.sessions.length > 100) {
-    index.sessions = index.sessions.slice(0, 100);
-  }
-
-  return updateMemory(MEMORY_SCOPE.PROJECT, MEMORY_FILES.SESSIONS_INDEX, index, projectRoot);
-}
-
-// ============================================================
-// 项目记忆 (技术栈、架构等)
-// ============================================================
-
-/**
- * 获取技术栈信息
- * @param {string} projectRoot - 项目根目录
- * @returns {Object} 技术栈信息
- */
-export function getTechStack(projectRoot) {
-  return getMemory(MEMORY_SCOPE.PROJECT, MEMORY_FILES.TECH_STACK, projectRoot, true) || {
-    primary: {},
-    tools: [],
-    patterns: []
-  };
-}
-
-/**
- * 更新技术栈信息
- * @param {string} projectRoot - 项目根目录
- * @param {Object} updates - 要更新的内容
- * @returns {boolean} 是否成功
- */
-export function updateTechStack(projectRoot, updates) {
-  return updateMemory(MEMORY_SCOPE.PROJECT, MEMORY_FILES.TECH_STACK, updates, projectRoot);
-}
-
-/**
- * 获取架构决策记录
- * @param {string} projectRoot - 项目根目录
- * @returns {Object} 架构决策记录
- */
-export function getArchitecture(projectRoot) {
-  return getMemory(MEMORY_SCOPE.PROJECT, MEMORY_FILES.ARCHITECTURE, projectRoot, true) || {
-    version: '1.0',
-    decisions: []
-  };
-}
-
-/**
- * 添加架构决策
- * @param {string} projectRoot - 项目根目录
- * @param {Object} decision - 决策内容
- * @returns {boolean} 是否成功
- */
-export function addArchitectureDecision(projectRoot, decision) {
-  const arch = getArchitecture(projectRoot);
-  const newDecision = {
-    id: `adr-${Date.now()}`,
-    status: 'accepted',
-    decidedAt: new Date().toISOString().split('T')[0],
-    ...decision
-  };
-  arch.decisions = arch.decisions || [];
-  arch.decisions.unshift(newDecision);
-  return updateMemory(MEMORY_SCOPE.PROJECT, MEMORY_FILES.ARCHITECTURE, arch, projectRoot);
-}
-
-// ============================================================
-// 记忆搜索
-// ============================================================
-
-/**
- * 搜索记忆
- * @param {string} projectRoot - 项目根目录
- * @param {string} query - 搜索关键词
- * @param {Array<string>} layers - 搜索层次
- * @returns {Object} 搜索结果
- */
-export function searchMemory(projectRoot, query, layers = ['core', 'project']) {
-  const results = {
-    core: [],
-    project: []
-  };
-  const queryLower = query.toLowerCase();
-
-  // 搜索核心记忆
-  if (layers.includes('core')) {
-    const northStar = getNorthStar(projectRoot);
-    if (JSON.stringify(northStar).toLowerCase().includes(queryLower)) {
-      results.core.push({
-        file: MEMORY_FILES.NORTH_STAR,
-        type: 'north-star',
-        content: northStar
-      });
-    }
-
-    const preferences = getTeamPreferences(projectRoot);
-    if (JSON.stringify(preferences).toLowerCase().includes(queryLower)) {
-      results.core.push({
-        file: MEMORY_FILES.TEAM_PREFERENCES,
-        type: 'preferences',
-        content: preferences
-      });
-    }
-  }
-
-  // 搜索项目记忆
-  if (layers.includes('project')) {
-    const techStack = getTechStack(projectRoot);
-    if (JSON.stringify(techStack).toLowerCase().includes(queryLower)) {
-      results.project.push({
-        file: MEMORY_FILES.TECH_STACK,
-        type: 'tech-stack',
-        content: techStack
-      });
-    }
-
-    const architecture = getArchitecture(projectRoot);
-    const matchingDecisions = architecture.decisions?.filter(d =>
-      JSON.stringify(d).toLowerCase().includes(queryLower)
-    );
-    if (matchingDecisions?.length > 0) {
-      results.project.push({
-        file: MEMORY_FILES.ARCHITECTURE,
-        type: 'architecture',
-        content: matchingDecisions
-      });
-    }
-  }
-
-  return results;
-}
-
-// ============================================================
-// 记忆初始化
-// ============================================================
-
-/**
- * 初始化全局记忆目录
- * @returns {boolean} 是否成功
- */
-export function initGlobalMemory() {
-  const globalDir = getGlobalMemoryDir();
-
-  try {
-    // 创建目录结构
-    Object.values(MEMORY_DIRS).forEach(dir => {
-      const fullPath = path.join(globalDir, dir);
-      if (!fs.existsSync(fullPath)) {
-        fs.mkdirSync(fullPath, { recursive: true });
-      }
-    });
-
-    // 创建默认文件
-    const defaultFiles = [
-      { path: MEMORY_FILES.TEAM_PREFERENCES, content: DEFAULT_TEAM_PREFERENCES },
-      { path: MEMORY_FILES.CONSTRAINTS, content: DEFAULT_CONSTRAINTS },
-      { path: MEMORY_FILES.MEMORY_META, content: { ...DEFAULT_MEMORY_META, scope: 'global' } }
-    ];
-
-    defaultFiles.forEach(({ path: relPath, content }) => {
-      const filePath = path.join(globalDir, relPath);
-      if (!fs.existsSync(filePath)) {
-        safeWriteJson(filePath, content);
-      }
-    });
-
-    return true;
-  } catch (e) {
-    console.error(`[AutoSpec memory-manager] 初始化全局记忆失败: ${e.message}`);
-    return false;
-  }
-}
-
-/**
- * 初始化项目记忆目录
- * @param {string} projectRoot - 项目根目录
- * @returns {boolean} 是否成功
- */
-export function initProjectMemory(projectRoot) {
-  const projectDir = getProjectMemoryDir(projectRoot);
-
-  try {
-    // 创建目录结构
-    Object.values(MEMORY_DIRS).forEach(dir => {
-      const fullPath = path.join(projectDir, dir);
-      if (!fs.existsSync(fullPath)) {
-        fs.mkdirSync(fullPath, { recursive: true });
-      }
-    });
-
-    // 创建默认文件
-    const defaultFiles = [
-      { path: MEMORY_FILES.NORTH_STAR, content: DEFAULT_NORTH_STAR },
-      { path: MEMORY_FILES.MEMORY_META, content: { ...DEFAULT_MEMORY_META, scope: 'project' } }
-    ];
-
-    defaultFiles.forEach(({ path: relPath, content }) => {
-      const filePath = path.join(projectDir, relPath);
-      if (!fs.existsSync(filePath)) {
-        safeWriteJson(filePath, content);
-      }
-    });
-
-    return true;
-  } catch (e) {
-    console.error(`[AutoSpec memory-manager] 初始化项目记忆失败: ${e.message}`);
-    return false;
-  }
-}
-
-/**
- * 检查全局记忆是否存在
- * @returns {boolean} 是否存在
- */
-export function hasGlobalMemory() {
-  const globalDir = getGlobalMemoryDir();
-  return fs.existsSync(globalDir);
-}
-
-/**
- * 检查项目记忆是否存在
- * @param {string} projectRoot - 项目根目录
- * @returns {boolean} 是否存在
- */
-export function hasProjectMemory(projectRoot) {
-  const projectDir = getProjectMemoryDir(projectRoot);
-  return fs.existsSync(projectDir);
-}
-
-// ============================================================
-// 缓存管理
-// ============================================================
-
-/**
- * 清除记忆缓存
- * @param {string} scope - 作用域（可选，不提供则清除所有）
- * @param {string} projectRoot - 项目根目录（可选）
- */
-export function clearMemoryCache(scope = null, projectRoot = null) {
-  if (scope && projectRoot) {
-    const prefix = `${scope}:`;
-    for (const key of memoryCache.keys()) {
-      if (key.startsWith(prefix)) {
-        memoryCache.delete(key);
-      }
-    }
-  } else {
-    memoryCache.clear();
-  }
-}
-
-export default {
-  // 路径解析
-  getGlobalMemoryDir,
-  getProjectMemoryDir,
-  resolveMemoryPath,
-  // 通用读写
-  getMemory,
-  updateMemory,
-  // 北极星指标
-  getNorthStar,
-  updateNorthStar,
-  addKeyResult,
-  addActiveDecision,
-  // 团队偏好
-  getTeamPreferences,
-  updateTeamPreferences,
-  // 约束条件
-  getConstraints,
-  addHardConstraint,
-  // 工作记忆
-  getCurrentContext,
-  updateCurrentContext,
-  clearCurrentContext,
-  // 会话记忆
-  getSessionsIndex,
-  addSession,
-  // 项目记忆
-  getTechStack,
-  updateTechStack,
-  getArchitecture,
-  addArchitectureDecision,
-  // 搜索
-  searchMemory,
-  // 初始化
-  initGlobalMemory,
-  initProjectMemory,
-  hasGlobalMemory,
-  hasProjectMemory,
-  // 缓存
-  clearMemoryCache
-};