@chongyan/autospec 1.0.1

package/plugins/hooks/lib/hook-state-manager.js

@@ -0,0 +1,480 @@
+/**
+ * State Utilities - 统一的状态管理模块
+ *
+ * 提供统一的 state.json 和 metrics.json 读写功能
+ * 替代各 hook 中分散的状态读写逻辑
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+// 缓存
+const stateCache = new Map();
+const metricsCache = new Map();
+const CACHE_TTL = 5000; // 5秒缓存
+
+/**
+ * 获取状态文件路径
+ * @param {string} projectRoot - 项目根目录
+ * @returns {string} state.json 路径
+ */
+function getStatePath(projectRoot) {
+  return path.join(projectRoot, '.autospec', 'runtime', 'state.json');
+}
+
+/**
+ * 获取指标文件路径
+ * @param {string} projectRoot - 项目根目录
+ * @returns {string} metrics.json 路径
+ */
+function getMetricsPath(projectRoot) {
+  return path.join(projectRoot, '.autospec', 'runtime', 'metrics.json');
+}
+
+/**
+ * 安全地读取 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 hook-state-manager] ⚠️ 权限错误: 无法写入 ${filePath}`);
+      console.error(`[AutoSpec hook-state-manager] 请运行: sudo chown -R $(whoami) .autospec`);
+    }
+    return false;
+  }
+}
+
+// ============================================================
+// State 操作
+// ============================================================
+
+/**
+ * 获取完整 state 对象
+ * @param {string} projectRoot - 项目根目录
+ * @param {boolean} useCache - 是否使用缓存
+ * @returns {Object|null} state 对象
+ */
+export function getState(projectRoot, useCache = false) {
+  if (useCache) {
+    const cached = stateCache.get(projectRoot);
+    if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
+      return cached.data;
+    }
+  }
+
+  const statePath = getStatePath(projectRoot);
+  const state = safeReadJson(statePath, null);
+
+  if (useCache && state) {
+    stateCache.set(projectRoot, { data: state, timestamp: Date.now() });
+  }
+
+  return state;
+}
+
+/**
+ * 更新 state 对象
+ * @param {string} projectRoot - 项目根目录
+ * @param {Object} updates - 要更新的字段
+ * @returns {boolean} 是否成功
+ */
+export function updateState(projectRoot, updates) {
+  const state = getState(projectRoot, false) || {};
+  const newState = { ...state, ...updates };
+
+  const statePath = getStatePath(projectRoot);
+  const success = safeWriteJson(statePath, newState);
+
+  if (success) {
+    stateCache.set(projectRoot, { data: newState, timestamp: Date.now() });
+  }
+
+  return success;
+}
+
+/**
+ * 读取 state 特定字段
+ * @param {string} projectRoot - 项目根目录
+ * @param {string} field - 字段名，支持点号分隔（如 'stages.stage01'）
+ * @param {any} defaultValue - 默认值
+ * @returns {any} 字段值
+ */
+export function readStateField(projectRoot, field, defaultValue = null) {
+  const state = getState(projectRoot, true);
+  if (!state) return defaultValue;
+
+  const parts = field.split('.');
+  let current = state;
+
+  for (const part of parts) {
+    if (current === null || current === undefined) {
+      return defaultValue;
+    }
+    current = current[part];
+  }
+
+  return current !== undefined ? current : defaultValue;
+}
+
+/**
+ * 设置 state 特定字段
+ * @param {string} projectRoot - 项目根目录
+ * @param {string} field - 字段名，支持点号分隔
+ * @param {any} value - 值
+ * @returns {boolean} 是否成功
+ */
+export function setStateField(projectRoot, field, value) {
+  const state = getState(projectRoot, false) || {};
+  const parts = field.split('.');
+  let current = state;
+
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i];
+    if (!(part in current) || typeof current[part] !== 'object') {
+      current[part] = {};
+    }
+    current = current[part];
+  }
+
+  current[parts[parts.length - 1]] = value;
+
+  return updateState(projectRoot, state);
+}
+
+/**
+ * 获取当前阶段
+ * @param {string} projectRoot - 项目根目录
+ * @returns {string|null} 当前阶段
+ */
+export function getCurrentStage(projectRoot) {
+  return readStateField(projectRoot, 'currentStage', null);
+}
+
+/**
+ * 获取阶段数据
+ * @param {string} projectRoot - 项目根目录
+ * @param {string} stageKey - 阶段键（如 'stage01'）
+ * @returns {Object|null} 阶段数据
+ */
+export function getStageData(projectRoot, stageKey) {
+  return readStateField(projectRoot, `stages.${stageKey}`, null);
+}
+
+/**
+ * 检查阶段是否有 Layer 1 执行记录
+ * @param {string} projectRoot - 项目根目录
+ * @param {string} stageKey - 阶段键
+ * @returns {boolean} 是否有 Layer 1 记录
+ */
+export function hasLayer1Execution(projectRoot, stageKey) {
+  const stageData = getStageData(projectRoot, stageKey);
+  return stageData?.layer1Results && Object.keys(stageData.layer1Results).length > 0;
+}
+
+// ============================================================
+// Metrics 操作
+// ============================================================
+
+/**
+ * 获取完整 metrics 对象
+ * @param {string} projectRoot - 项目根目录
+ * @param {boolean} useCache - 是否使用缓存
+ * @returns {Object} metrics 对象
+ */
+export function getMetrics(projectRoot, useCache = false) {
+  if (useCache) {
+    const cached = metricsCache.get(projectRoot);
+    if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
+      return cached.data;
+    }
+  }
+
+  const metricsPath = getMetricsPath(projectRoot);
+  const defaultMetrics = {
+    pipelineStart: new Date().toISOString(),
+    stages: {},
+    totals: {
+      layer1Pass: 0,
+      layer1Fail: 0,
+      agentCalls: 0,
+      agentSuccess: 0,
+      agentFail: 0,
+      errors: [],
+      retries: 0,
+      humanInterventions: 0
+    }
+  };
+
+  const metrics = safeReadJson(metricsPath, defaultMetrics);
+
+  if (useCache) {
+    metricsCache.set(projectRoot, { data: metrics, timestamp: Date.now() });
+  }
+
+  return metrics;
+}
+
+/**
+ * 更新 metrics 对象
+ * @param {string} projectRoot - 项目根目录
+ * @param {Object} updates - 要更新的字段
+ * @returns {boolean} 是否成功
+ */
+export function updateMetrics(projectRoot, updates) {
+  const metrics = getMetrics(projectRoot, false);
+  const newMetrics = { ...metrics, ...updates };
+
+  const metricsPath = getMetricsPath(projectRoot);
+  const success = safeWriteJson(metricsPath, newMetrics);
+
+  if (success) {
+    metricsCache.set(projectRoot, { data: newMetrics, timestamp: Date.now() });
+  }
+
+  return success;
+}
+
+/**
+ * 更新阶段指标
+ * @param {string} projectRoot - 项目根目录
+ * @param {string} stage - 阶段名
+ * @param {Object} updates - 要更新的字段
+ * @returns {boolean} 是否成功
+ */
+export function updateStageMetrics(projectRoot, stage, updates) {
+  const metrics = getMetrics(projectRoot, false);
+
+  if (!metrics.stages[stage]) {
+    metrics.stages[stage] = {
+      layer1Pass: 0,
+      layer1Fail: 0,
+      agentCalls: 0,
+      agentSuccess: 0,
+      agentFail: 0,
+      errors: []
+    };
+  }
+
+  metrics.stages[stage] = { ...metrics.stages[stage], ...updates };
+
+  return updateMetrics(projectRoot, metrics);
+}
+
+/**
+ * 增加总计指标
+ * @param {string} projectRoot - 项目根目录
+ * @param {string} field - 字段名
+ * @param {number} increment - 增量
+ * @returns {boolean} 是否成功
+ */
+export function incrementTotalMetric(projectRoot, field, increment = 1) {
+  const metrics = getMetrics(projectRoot, false);
+
+  if (typeof metrics.totals[field] === 'number') {
+    metrics.totals[field] += increment;
+  }
+
+  return updateMetrics(projectRoot, metrics);
+}
+
+/**
+ * 增加阶段指标
+ * @param {string} projectRoot - 项目根目录
+ * @param {string} stage - 阶段名
+ * @param {string} field - 字段名
+ * @param {number} increment - 增量
+ * @returns {boolean} 是否成功
+ */
+export function incrementStageMetric(projectRoot, stage, field, increment = 1) {
+  const metrics = getMetrics(projectRoot, false);
+
+  if (!metrics.stages[stage]) {
+    metrics.stages[stage] = {
+      layer1Pass: 0,
+      layer1Fail: 0,
+      agentCalls: 0,
+      agentSuccess: 0,
+      agentFail: 0,
+      errors: []
+    };
+  }
+
+  if (typeof metrics.stages[stage][field] === 'number') {
+    metrics.stages[stage][field] += increment;
+  }
+
+  return updateMetrics(projectRoot, metrics);
+}
+
+/**
+ * 添加错误记录
+ * @param {string} projectRoot - 项目根目录
+ * @param {Object} errorEntry - 错误条目
+ * @param {string} stage - 阶段名（可选）
+ * @returns {boolean} 是否成功
+ */
+export function addErrorEntry(projectRoot, errorEntry, stage = null) {
+  const metrics = getMetrics(projectRoot, false);
+
+  const entry = {
+    time: new Date().toISOString(),
+    ...errorEntry
+  };
+
+  metrics.totals.errors.push(entry);
+
+  if (stage && metrics.stages[stage]) {
+    metrics.stages[stage].errors.push(entry);
+  }
+
+  return updateMetrics(projectRoot, metrics);
+}
+
+// ============================================================
+// 缓存管理
+// ============================================================
+
+/**
+ * 清除 state 缓存
+ * @param {string} projectRoot - 项目根目录（可选，不提供则清除所有）
+ */
+export function clearStateCache(projectRoot = null) {
+  if (projectRoot) {
+    stateCache.delete(projectRoot);
+  } else {
+    stateCache.clear();
+  }
+}
+
+/**
+ * 清除 metrics 缓存
+ * @param {string} projectRoot - 项目根目录（可选，不提供则清除所有）
+ */
+export function clearMetricsCache(projectRoot = null) {
+  if (projectRoot) {
+    metricsCache.delete(projectRoot);
+  } else {
+    metricsCache.clear();
+  }
+}
+
+/**
+ * 清除所有缓存
+ */
+export function clearAllCache() {
+  stateCache.clear();
+  metricsCache.clear();
+}
+
+// ============================================================
+// Trace 相关操作
+// ============================================================
+
+/**
+ * 获取 Trace ID
+ * @param {string} projectRoot - 项目根目录
+ * @returns {string|null} Trace ID
+ */
+export function getTraceId(projectRoot) {
+  const state = getState(projectRoot, true);
+  return state?.traceId || null;
+}
+
+/**
+ * 设置 Trace ID
+ * @param {string} projectRoot - 项目根目录
+ * @param {string} traceId - Trace ID
+ * @returns {boolean} 是否成功
+ */
+export function setTraceId(projectRoot, traceId) {
+  return updateState(projectRoot, {
+    traceId,
+    traceStartedAt: new Date().toISOString()
+  });
+}
+
+/**
+ * 重置 Trace ID（流程结束时调用）
+ * @param {string} projectRoot - 项目根目录
+ * @returns {boolean} 是否成功
+ */
+export function resetTraceId(projectRoot) {
+  return updateState(projectRoot, {
+    traceId: null,
+    traceEndedAt: new Date().toISOString()
+  });
+}
+
+/**
+ * 获取执行模式
+ * @param {string} projectRoot - 项目根目录
+ * @returns {string} 执行模式 ('interactive' | 'autonomous')
+ */
+export function getExecutionMode(projectRoot) {
+  const state = getState(projectRoot, true);
+  return state?.executionMode || 'interactive';
+}
+
+/**
+ * 设置执行模式
+ * @param {string} projectRoot - 项目根目录
+ * @param {string} mode - 执行模式
+ * @returns {boolean} 是否成功
+ */
+export function setExecutionMode(projectRoot, mode) {
+  return updateState(projectRoot, { executionMode: mode });
+}
+
+export default {
+  getState,
+  updateState,
+  readStateField,
+  setStateField,
+  getCurrentStage,
+  getStageData,
+  hasLayer1Execution,
+  getMetrics,
+  updateMetrics,
+  updateStageMetrics,
+  incrementTotalMetric,
+  incrementStageMetric,
+  addErrorEntry,
+  clearStateCache,
+  clearMetricsCache,
+  clearAllCache,
+  // Trace 相关
+  getTraceId,
+  setTraceId,
+  resetTraceId,
+  getExecutionMode,
+  setExecutionMode,
+};