@yun520-1/heartflow 0.15.2

package/src/cli/commands/engines.ts

@@ -0,0 +1,280 @@
+/**
+ * engines.ts — HeartFlow 引擎面板
+ * @version v0.12.50
+ *
+ * 提供引擎状态查询接口：
+ *   - 记忆引擎 (Memory Engine)
+ *   - 检查点引擎 (Checkpoint Engine)
+ *   - 向量存储引擎 (Vector Store Engine)
+ *   - 核心引擎 (Core Engine)
+ *
+ * 支持 --watch 实时监控模式（每 3 秒刷新一次）
+ */
+
+import * as os from 'os';
+import * as path from 'path';
+import * as fs from 'fs';
+
+// 动态加载 storage 模块（避免循环依赖）
+let _storage: any = null;
+function getStorage() {
+  if (!_storage) {
+    try {
+      _storage = require('../../storage').createStorageEngine();
+    } catch (e) {
+      _storage = null;
+    }
+  }
+  return _storage;
+}
+
+export interface EngineStatus {
+  name: string;
+  status: 'online' | 'offline' | 'error' | 'unknown';
+  details: Record<string, any>;
+  uptime?: string;       // 运行时长（如 "2h 34m"）
+  memoryMB?: number;     // 内存占用 MB
+  lastActivity?: string; // ISO 时间
+}
+
+export interface PanelSnapshot {
+  timestamp: string;
+  hostname: string;
+  platform: string;
+  uptime: string;
+  loadavg: number[];
+  memory: { total: number; free: number; used: number; usedPercent: number };
+  engines: EngineStatus[];
+  totalMemoryMB: number;
+}
+
+/** 格式化字节为 MB */
+function toMB(bytes: number): number {
+  return Math.round((bytes / 1024 / 1024) * 100) / 100;
+}
+
+/** 格式化秒为人类可读时长 */
+function formatUptime(seconds: number): string {
+  if (seconds < 60) return `${Math.floor(seconds)}s`;
+  const m = Math.floor(seconds / 60);
+  if (m < 60) return `${m}m ${Math.floor(seconds % 60)}s`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ${m % 60}m`;
+  const d = Math.floor(h / 24);
+  return `${d}d ${h % 24}h`;
+}
+
+// ─── 引擎状态采集器 ───────────────────────────────────────────────────────
+
+function getMemoryEngineStatus(): EngineStatus {
+  const name = 'Memory Engine';
+  try {
+    const storage = getStorage();
+    if (!storage) {
+      return { name, status: 'offline', details: { reason: 'storage not initialized' } };
+    }
+    const stats = storage.checkpoint.getStats();
+    return {
+      name,
+      status: 'online',
+      details: {
+        totalSnapshots: stats.totalSnapshots,
+        maxKeep: stats.maxKeep,
+        checkpointDir: stats.dir,
+        lastSavedAt: stats.lastSavedAt ?? 'never',
+      },
+      lastActivity: stats.lastSavedAt ?? undefined,
+    };
+  } catch (e: any) {
+    return { name, status: 'error', details: { error: e.message } };
+  }
+}
+
+function getCheckpointEngineStatus(): EngineStatus {
+  const name = 'Checkpoint Engine';
+  try {
+    const storage = getStorage();
+    if (!storage) {
+      return { name, status: 'offline', details: { reason: 'storage not initialized' } };
+    }
+    const stats = storage.checkpoint.getStats();
+    const list = storage.checkpoint.list();
+    return {
+      name,
+      status: 'online',
+      details: {
+        snapshots: stats.totalSnapshots,
+        maxKeep: stats.maxKeep,
+        dir: stats.dir,
+        latestSnapshot: list.success && list.snapshots.length > 0
+          ? list.snapshots[0].savedAt
+          : 'none',
+      },
+      lastActivity: stats.lastSavedAt ?? undefined,
+    };
+  } catch (e: any) {
+    return { name, status: 'error', details: { error: e.message } };
+  }
+}
+
+function getVectorStoreEngineStatus(): EngineStatus {
+  const name = 'Vector Store Engine';
+  try {
+    const storage = getStorage();
+    if (!storage) {
+      return { name, status: 'offline', details: { reason: 'storage not initialized' } };
+    }
+    const size = storage.vector.size();
+    return {
+      name,
+      status: 'online',
+      details: {
+        vectors: size,
+        persistPath: storage.vector.persistPath ?? 'in-memory',
+      },
+    };
+  } catch (e: any) {
+    return { name, status: 'error', details: { error: e.message } };
+  }
+}
+
+function getCoreEngineStatus(): EngineStatus {
+  const name = 'Core Engine';
+  try {
+    const rootPath = path.join(os.homedir(), '.hermes', 'heartflow');
+    const versionFile = path.join(rootPath, 'VERSION');
+    const pkgFile = path.join(rootPath, 'package.json');
+    let version = 'unknown';
+    let state = 'unknown';
+
+    if (fs.existsSync(versionFile)) {
+      version = fs.readFileSync(versionFile, 'utf8').trim();
+    }
+    if (fs.existsSync(pkgFile)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf8'));
+      version = pkg.version ?? version;
+    }
+
+    // 尝试读取心跳状态
+    const heartbeatFile = path.join(rootPath, '.heartbeat');
+    if (fs.existsSync(heartbeatFile)) {
+      try {
+        const hb = JSON.parse(fs.readFileSync(heartbeatFile, 'utf8'));
+        state = hb.status ?? state;
+      } catch { /* ignore */ }
+    }
+
+    return {
+      name,
+      status: state === 'alive' ? 'online' : 'unknown',
+      details: { version, rootPath, state },
+    };
+  } catch (e: any) {
+    return { name, status: 'error', details: { error: e.message } };
+  }
+}
+
+// ─── 主采集函数 ───────────────────────────────────────────────────────────
+
+export function collectPanelSnapshot(): PanelSnapshot {
+  const totalMem = os.totalmem();
+  const freeMem = os.freemem();
+  const usedMem = totalMem - freeMem;
+
+  const engines: EngineStatus[] = [
+    getCoreEngineStatus(),
+    getMemoryEngineStatus(),
+    getCheckpointEngineStatus(),
+    getVectorStoreEngineStatus(),
+  ];
+
+  const engineMemMB = engines.reduce((sum, e) => sum + (e.memoryMB ?? 0), 0);
+
+  return {
+    timestamp: new Date().toISOString(),
+    hostname: os.hostname(),
+    platform: `${os.platform()} ${os.arch()} (${os.release()})`,
+    uptime: formatUptime(os.uptime()),
+    loadavg: os.loadavg(),
+    memory: {
+      total: Math.round(totalMem / 1024 / 1024),
+      free: Math.round(freeMem / 1024 / 1024),
+      used: Math.round(usedMem / 1024 / 1024),
+      usedPercent: Math.round((usedMem / totalMem) * 100),
+    },
+    engines,
+    totalMemoryMB: toMB(usedMem + engineMemMB * 1024 * 1024),
+  };
+}
+
+// ─── 表格渲染 ─────────────────────────────────────────────────────────────
+
+const STATUS_SYMBOLS: Record<string, string> = {
+  online:  '🟢',
+  offline: '⚪',
+  error:   '🔴',
+  unknown: '🟡',
+};
+
+export function renderPanelTable(snapshot: PanelSnapshot): string {
+  const lines: string[] = [];
+
+  lines.push('');
+  lines.push('┌──────────────────────────────────────────────────────────────┐');
+  lines.push('│                   HeartFlow Engine Panel                     │');
+  lines.push('└──────────────────────────────────────────────────────────────┘');
+  lines.push(`  Host:     ${snapshot.hostname}`);
+  lines.push(`  Platform: ${snapshot.platform}`);
+  lines.push(`  Uptime:   ${snapshot.uptime}  |  Load: ${snapshot.loadavg.map(l => l.toFixed(2)).join(', ')}`);
+  lines.push(`  Time:     ${snapshot.timestamp}`);
+  lines.push('');
+  lines.push('  Memory:');
+  lines.push(`    Total:   ${snapshot.memory.total} MB`);
+  lines.push(`    Used:    ${snapshot.memory.used} MB (${snapshot.memory.usedPercent}%)`);
+  lines.push(`    Free:    ${snapshot.memory.free} MB`);
+  lines.push('');
+  lines.push('  ┌─────────────────────┬────────┬─────────────────────────────┐');
+  lines.push('  │ Engine               │ Status │ Details                     │');
+  lines.push('  ├─────────────────────┼────────┼─────────────────────────────┤');
+
+  for (const eng of snapshot.engines) {
+    const sym = STATUS_SYMBOLS[eng.status] ?? '⚪';
+    const detailsStr = Object.entries(eng.details)
+      .map(([k, v]) => `${k}=${v}`)
+      .join(', ');
+    const truncated = detailsStr.length > 35 ? detailsStr.slice(0, 32) + '...' : detailsStr;
+    lines.push(
+      `  │ ${eng.name.padEnd(19)} │ ${sym} ${eng.status.padEnd(4)} │ ${truncated.padEnd(27)} │`
+    );
+  }
+
+  lines.push('  └─────────────────────┴────────┴─────────────────────────────┘');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+// ─── Watch 模式 ────────────────────────────────────────────────────────────
+
+export async function watchPanel(intervalMs = 3000, onUpdate?: (snap: PanelSnapshot) => void): Promise<() => void> {
+  let running = true;
+
+  async function loop() {
+    while (running) {
+      const snap = collectPanelSnapshot();
+
+      // 清屏重绘
+      process.stdout.write('\x1b[2J\x1b[H');
+      process.stdout.write(renderPanelTable(snap));
+
+      if (onUpdate) onUpdate(snap);
+
+      await new Promise(resolve => setTimeout(resolve, intervalMs));
+    }
+  }
+
+  loop().catch(console.error);
+
+  // 返回停止函数
+  return () => { running = false; };
+}

package/src/cli/commands/health.ts

@@ -0,0 +1,433 @@
+/**
+ * health.ts — HeartFlow 健康检查命令
+ * @version v0.12.50
+ *
+ * 提供全面健康检查：
+ *   - 存储引擎可用性
+ *   - 关键文件和目录存在性
+ *   - 内存和系统资源状态
+ *   - 版本信息完整性
+ */
+
+import * as os from 'os';
+import * as path from 'path';
+import * as fs from 'fs';
+
+// ─── 类型定义 ───────────────────────────────────────────────────────────────
+
+export type HealthStatus = 'ok' | 'warn' | 'fail' | 'skip';
+
+export interface HealthItem {
+  name: string;
+  status: HealthStatus;
+  message: string;
+  details?: Record<string, any>;
+}
+
+export interface HealthReport {
+  timestamp: string;
+  hostname: string;
+  uptime: string;
+  overall: HealthStatus;
+  items: HealthItem[];
+  summary: {
+    ok: number;
+    warn: number;
+    fail: number;
+    skip: number;
+  };
+}
+
+// ─── 工具函数 ──────────────────────────────────────────────────────────────
+
+function formatUptime(seconds: number): string {
+  if (seconds < 60) return `${Math.floor(seconds)}s`;
+  const m = Math.floor(seconds / 60);
+  if (m < 60) return `${m}m ${Math.floor(seconds % 60)}s`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ${m % 60}m`;
+  const d = Math.floor(h / 24);
+  return `${d}d ${h % 24}h`;
+}
+
+// ─── 健康检查项 ─────────────────────────────────────────────────────────────
+
+function checkStorageEngine(): HealthItem {
+  const name = 'Storage Engine';
+  try {
+    const storage = require('../../storage').createStorageEngine();
+    if (!storage) {
+      return { name, status: 'fail', message: 'Storage engine not initialized' };
+    }
+    return {
+      name,
+      status: 'ok',
+      message: 'Storage engine available',
+      details: {
+        hasCheckpoint: !!storage.checkpoint,
+        hasVector: !!storage.vector,
+      },
+    };
+  } catch (e: any) {
+    return { name, status: 'fail', message: `Failed to load storage: ${e.message}` };
+  }
+}
+
+function checkMemoryTiers(): HealthItem {
+  const name = 'Memory Tiers';
+  // 实际记忆路径：src/memory/ (CORE/LEARNED/EPHEMERAL) + data/reflection-memory/
+  const memoryDir = path.join(process.cwd(), 'src/memory');
+  const reflectionDir = path.join(process.cwd(), 'data/reflection-memory');
+  const tiers = [
+    { key: 'CORE',      file: 'meaningful-core.json',     dir: memoryDir },
+    { key: 'LEARNED',   file: 'meaningful-learned.json',  dir: memoryDir },
+    { key: 'EPHEMERAL', file: 'meaningful-ephemeral.json', dir: memoryDir },
+    { key: 'hot',       file: 'hot.json',                 dir: memoryDir },
+    { key: 'warm',      file: 'warm.json',                dir: memoryDir },
+    { key: 'cold',      file: 'cold.json',                dir: memoryDir },
+  ];
+  const reflexionFile = path.join(reflectionDir, 'reflections.json');
+  const reflexionPatternsFile = path.join(process.cwd(), 'data/evolution/reflexion-patterns.json');
+
+  const found: string[] = [];
+  const missing: string[] = [];
+
+  for (const tier of tiers) {
+    const filePath = path.join(tier.dir, tier.file);
+    if (fs.existsSync(filePath)) {
+      try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        const data = JSON.parse(content);
+        found.push(`${tier.key}(${Array.isArray(data) ? data.length : 'invalid'})`);
+      } catch {
+        found.push(`${tier.key}(read-error)`);
+      }
+    } else {
+      missing.push(tier.key);
+    }
+  }
+
+  // 检查 reflexion 数据
+  let reflexionCount = 0;
+  if (fs.existsSync(reflexionFile)) {
+    try {
+      const content = fs.readFileSync(reflexionFile, 'utf8');
+      const data = JSON.parse(content);
+      reflexionCount = Array.isArray(data) ? data.length : 0;
+      found.push(`reflexions(${reflexionCount})`);
+    } catch {
+      found.push('reflexions(read-error)');
+    }
+  } else {
+    missing.push('reflexions');
+  }
+
+  // 检查 evolution 数据
+  if (fs.existsSync(reflexionPatternsFile)) {
+    try {
+      const content = fs.readFileSync(reflexionPatternsFile, 'utf8');
+      const data = JSON.parse(content);
+      found.push(`evolution(${Array.isArray(data) ? data.length : 'invalid'})`);
+    } catch {
+      found.push('evolution(read-error)');
+    }
+  }
+
+  if (missing.length > 0) {
+    return {
+      name,
+      status: 'warn',
+      message: `Missing tier files: ${missing.join(', ')}`,
+      details: { found, missing },
+    };
+  }
+  return {
+    name,
+    status: 'ok',
+    message: `All tiers present: ${found.join(', ')}`,
+    details: { found },
+  };
+}
+
+function checkCheckpointEngine(): HealthItem {
+  const name = 'Checkpoint Engine';
+  try {
+    const storage = require('../../storage').createStorageEngine();
+    if (!storage?.checkpoint) {
+      return { name, status: 'fail', message: 'Checkpoint engine not available' };
+    }
+    const stats = storage.checkpoint.getStats();
+    const list = storage.checkpoint.list();
+    return {
+      name,
+      status: 'ok',
+      message: `Snapshots: ${stats.totalSnapshots}, MaxKeep: ${stats.maxKeep}`,
+      details: {
+        totalSnapshots: stats.totalSnapshots,
+        maxKeep: stats.maxKeep,
+        lastSavedAt: stats.lastSavedAt ?? 'never',
+        dir: stats.dir,
+      },
+    };
+  } catch (e: any) {
+    return { name, status: 'fail', message: `Checkpoint error: ${e.message}` };
+  }
+}
+
+function checkVectorStore(): HealthItem {
+  const name = 'Vector Store';
+  try {
+    const storage = require('../../storage').createStorageEngine();
+    if (!storage?.vector) {
+      return { name, status: 'fail', message: 'Vector store not available' };
+    }
+    const size = storage.vector.size();
+    return {
+      name,
+      status: 'ok',
+      message: `Vectors: ${size}`,
+      details: {
+        vectors: size,
+        persistPath: storage.vector.persistPath ?? 'in-memory',
+      },
+    };
+  } catch (e: any) {
+    return { name, status: 'fail', message: `Vector store error: ${e.message}` };
+  }
+}
+
+function checkSystemResources(): HealthItem {
+  const name = 'System Resources';
+  const totalMem = os.totalmem();
+  const freeMem = os.freemem();
+  const usedPercent = Math.round(((totalMem - freeMem) / totalMem) * 100);
+  const loadavg = os.loadavg();
+
+  let status: HealthStatus = 'ok';
+  if (usedPercent > 90) status = 'fail';
+  else if (usedPercent > 75) status = 'warn';
+
+  const memUsedMB = Math.round((totalMem - freeMem) / 1024 / 1024);
+  const memTotalMB = Math.round(totalMem / 1024 / 1024);
+
+  return {
+    name,
+    status,
+    message: `Memory: ${memUsedMB}/${memTotalMB} MB (${usedPercent}%) | Load: ${loadavg.map(l => l.toFixed(2)).join(', ')}`,
+    details: {
+      memoryUsedPercent: usedPercent,
+      memoryUsedMB: memUsedMB,
+      memoryTotalMB: memTotalMB,
+      loadavg,
+    },
+  };
+}
+
+function checkCriticalFiles(): HealthItem {
+  const name = 'Critical Files';
+  const rootPath = path.join(os.homedir(), '.hermes', 'heartflow');
+  const criticalPaths = [
+    { path: 'VERSION', desc: 'Version file' },
+    { path: 'package.json', desc: 'Package manifest' },
+    { path: 'src/core/heartflow.js', desc: 'Core engine' },
+    { path: 'HEARTCORE/heartbeat.js', desc: 'Heartbeat script' },
+  ];
+
+  const found: string[] = [];
+  const missing: string[] = [];
+
+  for (const cp of criticalPaths) {
+    const fullPath = path.join(rootPath, cp.path);
+    if (fs.existsSync(fullPath)) {
+      found.push(cp.desc);
+    } else {
+      missing.push(cp.desc);
+    }
+  }
+
+  if (missing.length > 0) {
+    return {
+      name,
+      status: 'fail',
+      message: `Missing: ${missing.join(', ')}`,
+      details: { found, missing },
+    };
+  }
+  return {
+    name,
+    status: 'ok',
+    message: `All critical files present (${found.length})`,
+    details: { found },
+  };
+}
+
+function checkNodeModules(): HealthItem {
+  const name = 'Dependencies';
+  const nodeModulesPath = path.join(process.cwd(), 'node_modules');
+  const pkgPath = path.join(process.cwd(), 'package.json');
+
+  if (!fs.existsSync(nodeModulesPath)) {
+    return {
+      name,
+      status: 'fail',
+      message: 'node_modules not found — run npm install',
+    };
+  }
+
+  if (!fs.existsSync(pkgPath)) {
+    return {
+      name,
+      status: 'fail',
+      message: 'package.json not found',
+    };
+  }
+
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    const depCount = Object.keys({ ...pkg.dependencies, ...pkg.devDependencies }).length;
+    return {
+      name,
+      status: 'ok',
+      message: `${depCount} dependencies installed`,
+      details: { depCount },
+    };
+  } catch (e: any) {
+    return { name, status: 'fail', message: `package.json parse error: ${e.message}` };
+  }
+}
+
+function checkVersion(): HealthItem {
+  const name = 'Version Info';
+  const rootPath = path.join(os.homedir(), '.hermes', 'heartflow');
+  const versionFile = path.join(rootPath, 'VERSION');
+  const pkgFile = path.join(rootPath, 'package.json');
+
+  let version = 'unknown';
+  let source = 'unknown';
+
+  if (fs.existsSync(versionFile)) {
+    version = fs.readFileSync(versionFile, 'utf8').trim();
+    source = 'VERSION file';
+  }
+  if (fs.existsSync(pkgFile)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf8'));
+      version = pkg.version ?? version;
+      source = 'package.json';
+    } catch { /* ignore */ }
+  }
+
+  return {
+    name,
+    status: 'ok',
+    message: `v${version} (${source})`,
+    details: { version, source },
+  };
+}
+
+// ─── 主采集函数 ──────────────────────────────────────────────────────────────
+
+export function collectHealthReport(): HealthReport {
+  const checks: HealthItem[] = [
+    checkVersion(),
+    checkSystemResources(),
+    checkCriticalFiles(),
+    checkNodeModules(),
+    checkStorageEngine(),
+    checkMemoryTiers(),
+    checkCheckpointEngine(),
+    checkVectorStore(),
+  ];
+
+  const summary = {
+    ok: checks.filter(c => c.status === 'ok').length,
+    warn: checks.filter(c => c.status === 'warn').length,
+    fail: checks.filter(c => c.status === 'fail').length,
+    skip: checks.filter(c => c.status === 'skip').length,
+  };
+
+  let overall: HealthStatus = 'ok';
+  if (summary.fail > 0) overall = 'fail';
+  else if (summary.warn > 0) overall = 'warn';
+
+  return {
+    timestamp: new Date().toISOString(),
+    hostname: os.hostname(),
+    uptime: formatUptime(os.uptime()),
+    overall,
+    items: checks,
+    summary,
+  };
+}
+
+// ─── 渲染输出 ────────────────────────────────────────────────────────────────
+
+const STATUS_SYMBOLS: Record<HealthStatus, string> = {
+  ok:   '✓',
+  warn: '⚠',
+  fail: '✗',
+  skip: '○',
+};
+
+const STATUS_COLORS: Record<HealthStatus, string> = {
+  ok:   '\x1b[32m',   // green
+  warn: '\x1b[33m',   // yellow
+  fail: '\x1b[31m',   // red
+  skip: '\x1b[90m',   // gray
+};
+
+const RESET = '\x1b[0m';
+
+export function renderHealthReport(report: HealthReport): string {
+  const lines: string[] = [];
+  const overallSym = STATUS_SYMBOLS[report.overall];
+  const overallColor = STATUS_COLORS[report.overall];
+
+  lines.push('');
+  lines.push('┌──────────────────────────────────────────────────────────────┐');
+  lines.push('│                   HeartFlow Health Check                      │');
+  lines.push('└──────────────────────────────────────────────────────────────┘');
+  lines.push(`  Host:     ${report.hostname}`);
+  lines.push(`  Uptime:   ${report.uptime}`);
+  lines.push(`  Time:     ${report.timestamp}`);
+  lines.push('');
+  lines.push(`  Overall:  ${overallColor}${overallSym} ${report.overall.toUpperCase()}${RESET}`);
+  lines.push(`             ok=${report.summary.ok}  warn=${report.summary.warn}  fail=${report.summary.fail}  skip=${report.summary.skip}`);
+  lines.push('');
+  lines.push('  ── Details ────────────────────────────────────────────────────');
+
+  for (const item of report.items) {
+    const sym = STATUS_SYMBOLS[item.status];
+    const color = STATUS_COLORS[item.status];
+    lines.push(`  ${color}${sym}${RESET} ${item.name}: ${item.message}`);
+  }
+
+  lines.push('');
+  lines.push('───────────────────────────────────────────────────────────────');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+// ─── CLI 入口 ────────────────────────────────────────────────────────────────
+
+export async function runHealthCheck(): Promise<number> {
+  const report = collectHealthReport();
+  console.log(renderHealthReport(report));
+
+  if (report.overall === 'fail') {
+    console.log('Health check FAILED. Please fix the issues above.');
+    return 1;
+  } else if (report.overall === 'warn') {
+    console.log('Health check passed with warnings.');
+    return 0;
+  }
+  console.log('Health check passed.');
+  return 0;
+}
+
+// 直接运行时执行检查
+runHealthCheck().then(code => process.exit(code)).catch(e => {
+  console.error('Health check error:', e);
+  process.exit(1);
+});