@chongyan/autospec 1.0.1

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

@@ -0,0 +1,673 @@
+/**
+ * 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 = 5000; // 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
+};