@winspan/claude-forge 8.41.0 → 8.51.0

package/src/core/utils/error-handler.ts

@@ -0,0 +1,257 @@
+/**
+ * 友好的错误提示处理器
+ *
+ * 将技术性错误转换为用户友好的中文提示，并提供解决方案
+ */
+
+import { logger } from './logger.js';
+import { DEFAULTS } from '../constants.js';
+import chalk from 'chalk';
+
+export interface ErrorSolution {
+  message: string;
+  solutions: string[];
+  technicalDetails?: string;
+}
+
+export class ErrorHandler {
+  /**
+   * 处理端口占用错误
+   */
+  static handlePortInUse(port: number, error: any): ErrorSolution {
+    return {
+      message: `端口 ${port} 已被占用`,
+      solutions: [
+        `查看占用进程：lsof -i :${port}`,
+        `结束占用进程：kill -9 $(lsof -ti :${port})`,
+        `修改配置文件 ~/.claude-forge/config.yaml 中的端口号`,
+        `如果是守护进程自己占用，运行：claude-forge daemon stop`
+      ],
+      technicalDetails: error.message
+    };
+  }
+
+  /**
+   * 处理权限错误
+   */
+  static handlePermissionError(path: string, error: any): ErrorSolution {
+    return {
+      message: `没有权限访问：${path}`,
+      solutions: [
+        `检查文件权限：ls -la ${path}`,
+        `修复权限：chmod 755 ${path}`,
+        `如果是目录，确保父目录也有执行权限`,
+        `检查是否被其他进程锁定`
+      ],
+      technicalDetails: error.message
+    };
+  }
+
+  /**
+   * 处理数据库错误
+   */
+  static handleDatabaseError(dbPath: string, error: any): ErrorSolution {
+    const isCorrupted = error.message?.includes('corrupt') || error.message?.includes('malformed');
+    const isLocked = error.message?.includes('locked') || error.message?.includes('SQLITE_BUSY');
+
+    if (isCorrupted) {
+      return {
+        message: `数据库文件损坏：${dbPath}`,
+        solutions: [
+          `备份当前数据库：cp ${dbPath} ${dbPath}.backup`,
+          `删除损坏的数据库：rm ${dbPath}`,
+          `重启守护进程会自动创建新数据库`,
+          `如需恢复数据，请联系技术支持`
+        ],
+        technicalDetails: error.message
+      };
+    }
+
+    if (isLocked) {
+      return {
+        message: `数据库被锁定：${dbPath}`,
+        solutions: [
+          `检查是否有其他守护进程在运行：ps aux | grep claude-forge`,
+          `结束其他进程：claude-forge daemon stop`,
+          `如果问题持续，删除锁文件：rm ${dbPath}-wal ${dbPath}-shm`,
+          `重启守护进程`
+        ],
+        technicalDetails: error.message
+      };
+    }
+
+    return {
+      message: `数据库错误：${dbPath}`,
+      solutions: [
+        `检查磁盘空间：df -h`,
+        `检查文件权限：ls -la ${dbPath}`,
+        `查看详细日志：tail -f ~/.claude-forge/daemon.log`,
+        `如果问题持续，尝试重建数据库`
+      ],
+      technicalDetails: error.message
+    };
+  }
+
+  /**
+   * 处理 API Key 缺失
+   */
+  static handleMissingApiKey(): ErrorSolution {
+    return {
+      message: 'Anthropic API Key 未配置',
+      solutions: [
+        `设置环境变量：export ANTHROPIC_API_KEY=your-key-here`,
+        `或在配置文件中设置：~/.claude-forge/config.yaml`,
+        `获取 API Key：https://console.anthropic.com/settings/keys`,
+        `注意：没有 API Key 时，AI 功能（分类器、质量检查、提炼）将被禁用`
+      ]
+    };
+  }
+
+  /**
+   * 处理 Socket 连接错误
+   */
+  static handleSocketError(socketPath: string, error: any): ErrorSolution {
+    const isNotFound = error.code === 'ENOENT';
+    const isConnectionRefused = error.code === 'ECONNREFUSED';
+
+    if (isNotFound) {
+      return {
+        message: `Socket 文件不存在：${socketPath}`,
+        solutions: [
+          `检查守护进程是否运行：claude-forge daemon status`,
+          `启动守护进程：claude-forge daemon start`,
+          `检查 socket 目录权限：ls -la $(dirname ${socketPath})`
+        ],
+        technicalDetails: error.message
+      };
+    }
+
+    if (isConnectionRefused) {
+      return {
+        message: `无法连接到守护进程`,
+        solutions: [
+          `守护进程可能已崩溃，查看日志：tail -f ~/.claude-forge/daemon.log`,
+          `重启守护进程：claude-forge daemon stop && claude-forge daemon start`,
+          `检查是否有僵尸进程：ps aux | grep claude-forge`
+        ],
+        technicalDetails: error.message
+      };
+    }
+
+    return {
+      message: `Socket 连接错误`,
+      solutions: [
+        `检查守护进程状态：claude-forge daemon status`,
+        `查看日志：tail -f ~/.claude-forge/daemon.log`,
+        `尝试重启：claude-forge daemon stop && claude-forge daemon start`
+      ],
+      technicalDetails: error.message
+    };
+  }
+
+  /**
+   * 处理文件系统错误
+   */
+  static handleFileSystemError(path: string, error: any): ErrorSolution {
+    const isNoSpace = error.code === 'ENOSPC';
+    const isNotFound = error.code === 'ENOENT';
+
+    if (isNoSpace) {
+      return {
+        message: `磁盘空间不足`,
+        solutions: [
+          `检查磁盘使用情况：df -h`,
+          `清理日志文件：rm ~/.claude-forge/daemon.log.old`,
+          `清理旧数据：sqlite3 ~/.claude-forge/data.db "DELETE FROM events WHERE timestamp < datetime('now', '-30 days')"`
+        ],
+        technicalDetails: error.message
+      };
+    }
+
+    if (isNotFound) {
+      return {
+        message: `文件或目录不存在：${path}`,
+        solutions: [
+          `检查路径是否正确`,
+          `创建必要的目录：mkdir -p $(dirname ${path})`,
+          `如果是配置文件，运行初始化：claude-forge init`
+        ],
+        technicalDetails: error.message
+      };
+    }
+
+    return {
+      message: `文件系统错误：${path}`,
+      solutions: [
+        `检查路径权限：ls -la ${path}`,
+        `检查磁盘状态：df -h`,
+        `查看系统日志：dmesg | tail`
+      ],
+      technicalDetails: error.message
+    };
+  }
+
+  /**
+   * 格式化并打印错误信息
+   */
+  static printError(solution: ErrorSolution): void {
+    console.error(chalk.red.bold('\n✗ 错误：') + chalk.red(solution.message));
+
+    if (solution.solutions.length > 0) {
+      console.error(chalk.yellow('\n💡 解决方案：'));
+      solution.solutions.forEach((s, i) => {
+        console.error(chalk.yellow(`  ${i + 1}. ${s}`));
+      });
+    }
+
+    if (solution.technicalDetails) {
+      console.error(chalk.gray('\n📋 技术细节：'));
+      console.error(chalk.gray(`  ${solution.technicalDetails}`));
+    }
+
+    console.error(''); // 空行
+  }
+
+  /**
+   * 统一的错误处理入口
+   */
+  static handle(error: any, context?: string): void {
+    logger.error(`[ErrorHandler] ${context || 'Unknown context'}: ${error.message || error}`);
+
+    let solution: ErrorSolution | null = null;
+
+    // 根据错误类型自动识别并生成解决方案
+    if (error.code === 'EADDRINUSE') {
+      const port = parseInt(error.message?.match(/:(\d+)/)?.[1] || String(DEFAULTS.WEB_PORT));
+      solution = this.handlePortInUse(port, error);
+    } else if (error.code === 'EACCES' || error.code === 'EPERM') {
+      const path = error.path || error.message?.match(/['"]([^'"]+)['"]/)?.[1] || 'unknown';
+      solution = this.handlePermissionError(path, error);
+    } else if (error.code === 'ENOENT') {
+      const path = error.path || error.message?.match(/['"]([^'"]+)['"]/)?.[1] || 'unknown';
+      solution = this.handleFileSystemError(path, error);
+    } else if (error.code === 'ENOSPC') {
+      solution = this.handleFileSystemError('', error);
+    } else if (error.message?.includes('SQLITE') || error.message?.includes('database')) {
+      const dbPath = error.message?.match(/['"]([^'"]+\.db)['"]/)?.[1] || '~/.claude-forge/data.db';
+      solution = this.handleDatabaseError(dbPath, error);
+    } else if (error.code === 'ECONNREFUSED' || error.code === 'ENOENT') {
+      const socketPath = error.path || '~/.claude-forge/daemon.sock';
+      solution = this.handleSocketError(socketPath, error);
+    } else {
+      // 通用错误
+      solution = {
+        message: error.message || '未知错误',
+        solutions: [
+          '查看详细日志：tail -f ~/.claude-forge/daemon.log',
+          '检查守护进程状态：claude-forge daemon status',
+          '尝试重启：claude-forge daemon stop && claude-forge daemon start',
+          '如果问题持续，请提交 Issue：https://github.com/anthropics/claude-forge/issues'
+        ],
+        technicalDetails: error.stack
+      };
+    }
+
+    this.printError(solution);
+  }
+}

package/src/core/utils/forge-resume-block.ts

@@ -0,0 +1,74 @@
+/**
+ * 项目根目录 CLAUDE.md 中的「续接」状态摘要的统一落盘格式。
+ *
+ * - 写入：`buildForgeResumeEnvelope`（ResumeEngine）
+ * - 剥离：`stripForgeResumeBlocks`（注入前清理、clearResumeBlock）
+ * - 检测：`hasForgeResumeBlock`（含旧版 `<!-- forge:resume -->` 与新版 begin 标记）
+ */
+import { randomUUID } from 'crypto';
+
+/** 旧版续接块（正文裸放，易被 HTML 注释子串破坏） */
+const LEGACY_RESUME_BLOCK_RE = /\n*<!-- forge:resume -->[\s\S]*?<!-- forge:end-resume -->\s*/g;
+
+/** forge:resume-begin / end 之间的 UUID（randomUUID 小写） */
+const RESUME_UUID = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}';
+
+function scopedResumeBlockRe(): RegExp {
+  return new RegExp(
+    `\\n*<!-- forge:resume-begin:(${RESUME_UUID}) -->[\\s\\S]*?<!-- forge:resume-end:\\1 -->\\s*`,
+    'gi'
+  );
+}
+
+/**
+ * 构造续接信封：外层用 UUID 配对注释定界，正文保存在兼容旧解析器的 fenced block 中。
+ */
+export function buildForgeResumeEnvelope(innerUtf8Markdown: string): string {
+  const id = randomUUID();
+  const iso = new Date().toISOString();
+  const body = innerUtf8Markdown.trim();
+
+  return [
+    `<!-- forge:resume-begin:${id} -->`,
+    '```forge-resume-body',
+    body,
+    '```',
+    '',
+    `_生成时间: ${iso}_`,
+    `<!-- forge:resume-end:${id} -->`,
+  ].join('\n');
+}
+
+/** 是否包含旧版或新版续接块 */
+export function hasForgeResumeBlock(content: string): boolean {
+  return (
+    content.includes('<!-- forge:resume -->') ||
+    new RegExp(`<!-- forge:resume-begin:${RESUME_UUID} -->`).test(content)
+  );
+}
+
+/**
+ * 移除全部续接块（新版 UUID 信封 + 旧版裸正文），并压缩多余空行。
+ */
+export function stripForgeResumeBlocks(content: string): string {
+  let s = content.replace(scopedResumeBlockRe(), '\n');
+  s = s.replace(LEGACY_RESUME_BLOCK_RE, '\n');
+  s = s.replace(/\n{4,}/g, '\n\n\n');
+  return s.trimEnd();
+}
+
+export function decodeForgeResumeInnerFromClaudeMd(content: string): string {
+  const fencedMatch = content.match(/```forge-resume-body\n([\s\S]*?)\n```/);
+  if (fencedMatch) {
+    return fencedMatch[1].trim();
+  }
+
+  const scopedMatch = content.match(
+    new RegExp(`<!-- forge:resume-begin:${RESUME_UUID} -->\\n([\\s\\S]*?)\\n(?:_生成时间:[\\s\\S]*?)?<!-- forge:resume-end:${RESUME_UUID} -->`)
+  );
+  if (scopedMatch) {
+    return scopedMatch[1].trim();
+  }
+
+  return '';
+}

package/src/core/utils/format.ts

@@ -0,0 +1,69 @@
+/**
+ * 通用格式化工具（日志、错误）
+ */
+
+/**
+ * 格式化错误对象为日志友好的字符串
+ */
+export function formatError(error: unknown): string {
+  if (error instanceof Error) {
+    return `${error.name}: ${error.message}${error.stack ? '\n' + error.stack : ''}`;
+  }
+  if (typeof error === 'string') {
+    return error;
+  }
+  return JSON.stringify(error);
+}
+
+/**
+ * 格式化错误对象为简短消息（不含堆栈）
+ */
+export function formatErrorShort(error: unknown): string {
+  if (error instanceof Error) {
+    return `${error.name}: ${error.message}`;
+  }
+  if (typeof error === 'string') {
+    return error;
+  }
+  return String(error);
+}
+
+/**
+ * 格式化日志上下文（添加时间戳和级别）
+ */
+export function formatLogContext(level: string, message: string, context?: Record<string, unknown>): string {
+  const timestamp = new Date().toISOString();
+  const contextStr = context ? ` ${JSON.stringify(context)}` : '';
+  return `[${timestamp}] [${level.toUpperCase()}] ${message}${contextStr}`;
+}
+
+/**
+ * 截断长字符串（用于日志显示）
+ */
+export function truncateString(str: string, maxLength: number = 100): string {
+  if (!str) return '';
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength) + '...';
+}
+
+/**
+ * 格式化 JSON 为紧凑格式（单行，无缩进）
+ */
+export function formatCompactJson(obj: unknown): string {
+  try {
+    return JSON.stringify(obj);
+  } catch {
+    return String(obj);
+  }
+}
+
+/**
+ * 格式化 JSON 为可读格式（多行，带缩进）
+ */
+export function formatPrettyJson(obj: unknown): string {
+  try {
+    return JSON.stringify(obj, null, 2);
+  } catch {
+    return String(obj);
+  }
+}

package/src/core/utils/git.ts

@@ -0,0 +1,23 @@
+import { execSync } from 'node:child_process';
+
+/**
+ * Walk up the directory tree from `start` using `git rev-parse --show-toplevel`
+ * to find the git repository root.
+ *
+ * Fallback: returns `start` unchanged if:
+ *   - `start` is not inside a git repository
+ *   - the git command fails for any reason (git not on PATH, permission error, etc.)
+ */
+export function resolveGitRoot(start: string = process.cwd()): string {
+  try {
+    const result = execSync('git rev-parse --show-toplevel', {
+      cwd: start,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+      .toString()
+      .trim();
+    return result || start;
+  } catch {
+    return start;
+  }
+}

package/src/core/utils/logger.ts

@@ -0,0 +1,134 @@
+/**
+ * Simple logger writing to stderr (or file in daemon mode)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export enum LogLevel {
+  DEBUG = 0,
+  INFO = 1,
+  WARN = 2,
+  ERROR = 3,
+}
+
+/**
+ * Parse log level from LOG_LEVEL env var.
+ * Accepts: debug, info, warn, error (case-insensitive). Falls back to INFO.
+ */
+function getLogLevelFromEnv(): LogLevel {
+  const envLevel = (process.env.LOG_LEVEL ?? '').toLowerCase();
+  const levelMap: Record<string, LogLevel> = {
+    debug: LogLevel.DEBUG,
+    info: LogLevel.INFO,
+    warn: LogLevel.WARN,
+    error: LogLevel.ERROR,
+  };
+  return levelMap[envLevel] ?? LogLevel.INFO;
+}
+
+let currentLevel: LogLevel = getLogLevelFromEnv();
+let logFilePath: string | null = null;
+let lastSizeCheck = 0;
+let cachedSize = 0;
+
+const MAX_SIZE = 10 * 1024 * 1024; // 10MB
+const MAX_FILES = 3;
+const SIZE_CHECK_INTERVAL = 60000; // Check size every 60s
+
+function timestamp(): string {
+  return new Date().toISOString();
+}
+
+function format(level: string, message: string): string {
+  return `[${timestamp()}] [${level}] ${message}`;
+}
+
+function rotateLogIfNeeded(): void {
+  if (!logFilePath || !fs.existsSync(logFilePath)) return;
+
+  // Cache size check to avoid frequent stat calls
+  const now = Date.now();
+  if (now - lastSizeCheck >= SIZE_CHECK_INTERVAL) {
+    const stats = fs.statSync(logFilePath);
+    cachedSize = stats.size;
+    lastSizeCheck = now;
+  }
+
+  // Check if rotation is needed
+  if (cachedSize < MAX_SIZE) return;
+
+  // Rotate: .log -> .log.1 -> .log.2 -> .log.3 (delete oldest)
+  try {
+    for (let i = MAX_FILES - 1; i >= 1; i--) {
+      const oldPath = `${logFilePath}.${i}`;
+      const newPath = `${logFilePath}.${i + 1}`;
+      if (fs.existsSync(oldPath)) {
+        if (i === MAX_FILES - 1) {
+          fs.unlinkSync(oldPath); // Delete oldest
+        } else {
+          fs.renameSync(oldPath, newPath);
+        }
+      }
+    }
+    fs.renameSync(logFilePath, `${logFilePath}.1`);
+    cachedSize = 0; // Reset cache after rotation
+    lastSizeCheck = 0; // Force recheck on next write
+  } catch (err) {
+    // If rotation fails, just continue (better than crashing)
+    console.error(`[Logger] Log rotation failed: ${err}`);
+  }
+}
+
+function write(level: LogLevel, levelName: string, message: string): void {
+  if (level < currentLevel) return;
+  const formatted = format(levelName, message);
+
+  if (logFilePath) {
+    rotateLogIfNeeded();
+    try {
+      fs.appendFileSync(logFilePath, formatted + '\n');
+      // Update cached size after write
+      cachedSize += formatted.length + 1;
+    } catch (err) {
+      // Fallback to stderr if file write fails
+      console.error(formatted);
+    }
+  } else {
+    console.error(formatted);
+  }
+}
+
+export const logger = {
+  debug(message: string): void {
+    write(LogLevel.DEBUG, 'DEBUG', message);
+  },
+
+  info(message: string): void {
+    write(LogLevel.INFO, 'INFO', message);
+  },
+
+  warn(message: string): void {
+    write(LogLevel.WARN, 'WARN', message);
+  },
+
+  error(message: string): void {
+    write(LogLevel.ERROR, 'ERROR', message);
+  },
+};
+
+export function setLogLevel(level: LogLevel): void {
+  currentLevel = level;
+}
+
+/**
+ * Enable file logging (for daemon mode)
+ * @param filePath Path to log file
+ */
+export function enableFileLogging(filePath: string): void {
+  logFilePath = filePath;
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}

package/src/core/utils/lru-cache.ts

@@ -0,0 +1,54 @@
+/**
+ * Simple LRU cache for AI responses
+ */
+
+export class LRUCache<K, V> {
+  private cache = new Map<K, V>();
+  private maxSize: number;
+
+  constructor(maxSize: number = 100) {
+    this.maxSize = maxSize;
+  }
+
+  get(key: K): V | undefined {
+    const value = this.cache.get(key);
+    if (value !== undefined) {
+      // Move to end (most recently used)
+      this.cache.delete(key);
+      this.cache.set(key, value);
+    }
+    return value;
+  }
+
+  set(key: K, value: V): void {
+    // Remove if exists (to update position)
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    }
+
+    // Add to end
+    this.cache.set(key, value);
+
+    // Evict oldest if over capacity
+    if (this.cache.size > this.maxSize) {
+      const firstKey = this.cache.keys().next().value as K;
+      this.cache.delete(firstKey);
+    }
+  }
+
+  has(key: K): boolean {
+    return this.cache.has(key);
+  }
+
+  delete(key: K): boolean {
+    return this.cache.delete(key);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  size(): number {
+    return this.cache.size;
+  }
+}

package/src/core/utils/path.ts

@@ -0,0 +1,19 @@
+import { homedir } from 'node:os';
+import { relative } from 'node:path';
+
+/**
+ * Expand ~ to the user's home directory
+ */
+export function expandPath(p: string): string {
+  if (p.startsWith('~/') || p === '~') {
+    return homedir() + p.slice(1);
+  }
+  return p;
+}
+
+/**
+ * Return path relative to cwd
+ */
+export function relPath(p: string): string {
+  return relative(process.cwd(), p);
+}

package/src/core/utils/session.ts

@@ -0,0 +1,26 @@
+/**
+ * Session ID 处理工具
+ */
+
+/**
+ * 截断 Session ID 到指定长度（用于日志显示）
+ */
+export function truncateSessionId(sessionId: string, length: number = 8): string {
+  if (!sessionId) return 'unknown';
+  return sessionId.slice(0, length);
+}
+
+/**
+ * 验证 Session ID 格式（UUID v4）
+ */
+export function isValidSessionId(sessionId: string): boolean {
+  const uuidV4Regex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+  return uuidV4Regex.test(sessionId);
+}
+
+/**
+ * 生成短 Session ID（用于显示）
+ */
+export function formatSessionId(sessionId: string): string {
+  return `session:${truncateSessionId(sessionId)}`;
+}

package/src/core/utils/time.ts

@@ -0,0 +1,37 @@
+/**
+ * 时间戳归一化工具
+ *
+ * 统一处理 ISO 8601 时间戳的 Z 后缀问题，确保所有时间戳都带 Z。
+ */
+
+/**
+ * 归一化时间戳，确保带 Z 后缀
+ */
+export function normalizeTimestamp(timestamp: string): string {
+  if (!timestamp) return new Date().toISOString();
+  return timestamp.endsWith('Z') ? timestamp : timestamp + 'Z';
+}
+
+/**
+ * 将时间戳转换为 Unix 毫秒数
+ */
+export function timestampToMs(timestamp: string): number {
+  return new Date(normalizeTimestamp(timestamp)).getTime();
+}
+
+/**
+ * 计算两个时间戳之间的毫秒差
+ */
+export function timeDiff(start: string, end: string): number {
+  return timestampToMs(end) - timestampToMs(start);
+}
+
+/**
+ * 格式化时间差为人类可读格式
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  if (ms < 3600000) return `${(ms / 60000).toFixed(1)}m`;
+  return `${(ms / 3600000).toFixed(1)}h`;
+}