@winspan/claude-forge 8.41.0 → 8.50.6

package/src/core/storage/tasks.ts

@@ -0,0 +1,170 @@
+/**
+ * TaskOperations — tasks 表读写
+ *
+ * 拆分自 sqlite.ts。
+ */
+
+import type Database from 'better-sqlite3';
+
+export interface TaskRecord {
+  id: string;
+  session_id: string;
+  title: string;
+  description?: string;
+  start_time: string;
+  end_time?: string;
+  status: 'active' | 'completed' | 'abandoned';
+  event_count: number;
+  project_path?: string;
+}
+
+export interface TaskFilter {
+  session_id?: string;
+  limit?: number;
+  offset?: number;
+  project?: string | string[];
+  from?: string;
+  to?: string;
+  search?: string;
+}
+
+export interface TaskPage {
+  items: TaskRecord[];
+  total: number;
+  has_more: boolean;
+}
+
+export class TaskOperations {
+  constructor(private db: Database.Database) {}
+
+  writeTask(task: { id: string; session_id: string; title: string; start_time: string }): void {
+    this.db.prepare(`
+      INSERT INTO tasks (id, session_id, title, start_time) VALUES (?, ?, ?, ?)
+    `).run(task.id, task.session_id, task.title, task.start_time);
+  }
+
+  updateTask(taskId: string, updates: { end_time?: string; status?: string; event_count?: number; title?: string }): void {
+    const sets: string[] = [];
+    const params: unknown[] = [];
+    if (updates.end_time !== undefined) { sets.push('end_time = ?'); params.push(updates.end_time); }
+    if (updates.status !== undefined) { sets.push('status = ?'); params.push(updates.status); }
+    if (updates.event_count !== undefined) { sets.push('event_count = ?'); params.push(updates.event_count); }
+    if (updates.title !== undefined) { sets.push('title = ?'); params.push(updates.title); }
+    if (sets.length === 0) return;
+    params.push(taskId);
+    this.db.prepare(`UPDATE tasks SET ${sets.join(', ')} WHERE id = ?`).run(...params);
+  }
+
+  linkEventToTask(taskId: string, eventId: string): void {
+    this.db.prepare(`INSERT OR IGNORE INTO task_events (task_id, event_id) VALUES (?, ?)`).run(taskId, eventId);
+    this.db.prepare(`UPDATE tasks SET event_count = event_count + 1, end_time = (SELECT timestamp FROM events WHERE event_id = ?) WHERE id = ?`).run(eventId, taskId);
+  }
+
+  /** Legacy simple query — returns bare array (used by detail route internally) */
+  queryTasks(filter: { session_id?: string; limit?: number } = {}): TaskRecord[] {
+    const conditions: string[] = [];
+    const params: unknown[] = [];
+    if (filter.session_id) { conditions.push('session_id = ?'); params.push(filter.session_id); }
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+    const limit = filter.limit ?? 50;
+    params.push(limit);
+    const rows = this.db.prepare(`SELECT * FROM tasks ${where} ORDER BY start_time DESC LIMIT ?`).all(...params) as Array<Record<string, unknown>>;
+    return rows.map(r => this.mapRow(r));
+  }
+
+  /**
+   * queryTasksFiltered — paginated query with full filter support.
+   * JOINs sessions to expose project_path.
+   */
+  queryTasksFiltered(filter: TaskFilter = {}): TaskPage {
+    const { conditions, params } = this.buildWhereConditions(filter);
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+
+    const limit = Math.min(Math.max(filter.limit ?? 50, 1), 200);
+    const offset = Math.max(filter.offset ?? 0, 0);
+
+    // Count query
+    const countRow = this.db.prepare(
+      `SELECT COUNT(*) as cnt FROM tasks t JOIN sessions s ON t.session_id = s.session_id ${where}`
+    ).get(...params) as { cnt: number };
+    const total = countRow?.cnt ?? 0;
+
+    // Data query
+    const dataParams = [...params, limit, offset];
+    const rows = this.db.prepare(
+      `SELECT t.*, s.project_path
+       FROM tasks t
+       JOIN sessions s ON t.session_id = s.session_id
+       ${where}
+       ORDER BY t.start_time DESC
+       LIMIT ? OFFSET ?`
+    ).all(...dataParams) as Array<Record<string, unknown>>;
+
+    const items = rows.map(r => this.mapRow(r));
+    return { items, total, has_more: offset + items.length < total };
+  }
+
+  /** Returns distinct project paths that have at least one task. */
+  queryTaskProjects(): string[] {
+    const rows = this.db.prepare(
+      `SELECT DISTINCT s.project_path
+       FROM sessions s
+       JOIN tasks t ON t.session_id = s.session_id
+       ORDER BY s.project_path`
+    ).all() as Array<{ project_path: string }>;
+    return rows.map(r => r.project_path);
+  }
+
+  getTaskEventIds(taskId: string): string[] {
+    const rows = this.db.prepare(`SELECT event_id FROM task_events WHERE task_id = ?`).all(taskId) as Array<{ event_id: string }>;
+    return rows.map(r => r.event_id);
+  }
+
+  private buildWhereConditions(filter: TaskFilter): { conditions: string[]; params: unknown[] } {
+    const conditions: string[] = [];
+    const params: unknown[] = [];
+
+    if (filter.session_id) {
+      conditions.push('t.session_id = ?');
+      params.push(filter.session_id);
+    }
+
+    if (filter.project) {
+      const projects = Array.isArray(filter.project) ? filter.project : [filter.project];
+      const placeholders = projects.map(() => '?').join(', ');
+      conditions.push(`s.project_path IN (${placeholders})`);
+      params.push(...projects);
+    }
+
+    if (filter.from) {
+      conditions.push('t.start_time >= ?');
+      params.push(filter.from);
+    }
+
+    if (filter.to) {
+      conditions.push('t.start_time <= ?');
+      params.push(filter.to);
+    }
+
+    if (filter.search) {
+      conditions.push('t.title LIKE ?');
+      params.push(`%${filter.search}%`);
+    }
+
+    return { conditions, params };
+  }
+
+  private mapRow(r: Record<string, unknown>): TaskRecord {
+    return {
+      id: r.id as string,
+      session_id: r.session_id as string,
+      title: r.title as string,
+      description: (r.description as string) || undefined,
+      start_time: r.start_time as string,
+      end_time: (r.end_time as string) || undefined,
+      status: (r.status as TaskRecord['status']) || 'active',
+      event_count: (r.event_count as number) || 0,
+      project_path: (r.project_path as string) || undefined,
+    };
+  }
+}

package/src/core/storage/token-usage.ts

@@ -0,0 +1,93 @@
+/**
+ * TokenUsageOperations — token_usage 表读写
+ *
+ * 拆分自 sqlite.ts。
+ */
+
+import type Database from 'better-sqlite3';
+import { logger } from '../utils/logger.js';
+
+export class TokenUsageOperations {
+  constructor(private db: Database.Database) {}
+
+  recordTokenUsage(params: {
+    session_id: string;
+    input_tokens: number;
+    output_tokens: number;
+    model?: string;
+    tool_name?: string;
+  }): void {
+    const total_tokens = params.input_tokens + params.output_tokens;
+    try {
+      this.db.prepare(`
+        INSERT INTO token_usage (session_id, timestamp,
+                                 input_tokens, output_tokens, total_tokens, model, tool_name)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        params.session_id,
+        Date.now(),
+        params.input_tokens,
+        params.output_tokens,
+        total_tokens,
+        params.model ?? null,
+        params.tool_name ?? null,
+      );
+    } catch (err) {
+      logger.debug(`[Storage] Failed to record token usage: ${err}`);
+    }
+  }
+
+  getTokenUsageBySession(session_id: string): {
+    total_tokens: number;
+    input_tokens: number;
+    output_tokens: number;
+  } {
+    const result = this.db.prepare(`
+      SELECT
+        COALESCE(SUM(input_tokens), 0) as input_tokens,
+        COALESCE(SUM(output_tokens), 0) as output_tokens,
+        COALESCE(SUM(total_tokens), 0) as total_tokens
+      FROM token_usage WHERE session_id = ?
+    `).get(session_id) as { input_tokens: number; output_tokens: number; total_tokens: number };
+    return result;
+  }
+
+  listTokenUsage(filter: {
+    session_id?: string;
+    limit?: number;
+  } = {}): Array<{
+    id: number;
+    session_id: string;
+    timestamp: number;
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    model: string | null;
+    tool_name: string | null;
+  }> {
+    const conditions: string[] = [];
+    const params: unknown[] = [];
+
+    if (filter.session_id) {
+      conditions.push('session_id = ?');
+      params.push(filter.session_id);
+    }
+
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+    const limit = filter.limit ?? 100;
+    const sql = `SELECT * FROM token_usage ${where} ORDER BY timestamp DESC LIMIT ?`;
+
+    params.push(limit);
+    const rows = this.db.prepare(sql).all(...params) as Array<Record<string, unknown>>;
+    return rows.map(r => ({
+      id: r.id as number,
+      session_id: r.session_id as string,
+      timestamp: r.timestamp as number,
+      input_tokens: r.input_tokens as number,
+      output_tokens: r.output_tokens as number,
+      total_tokens: r.total_tokens as number,
+      model: (r.model as string) || null,
+      tool_name: (r.tool_name as string) || null,
+    }));
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,154 @@
+/**
+ * Core event types used by all Forge handlers.
+ *
+ * Two layers exposed:
+ *
+ * 1. **Wire shape** — `ForgeEvent`: a permissive interface that mirrors the
+ *    raw Hook payload coming off the Unix socket. All optional fields are
+ *    `?:` because the Hook envelope is the same regardless of `hook_type`.
+ *    Storage / wire-level code (event-parser, sqlite rowToEvent, daemon
+ *    router) keeps using this — it's still the source of truth on disk.
+ *
+ * 2. **Narrowed views** — `PreToolUseEvent` / `PostToolUseEvent` /
+ *    `UserPromptSubmitEvent` / `NotificationEvent` / `StopEvent`: per-hook
+ *    discriminated union with required fields filled in. Use these in
+ *    handlers and downstream services where the hook type is already known.
+ *
+ *    Convert with the type guards `isPreToolUse` / `isPostToolUse` / etc.
+ *    They narrow correctly under TS control flow analysis.
+ *
+ * The split exists so we get compile-time guarantees inside handlers
+ * (no more `event.tool_name!`) without forcing every caller of the wire
+ * shape to do a 5-way switch.
+ */
+export interface ForgeEvent {
+  session_id: string;
+  project_path: string;
+  timestamp: string;
+  hook_type: 'PreToolUse' | 'PostToolUse' | 'UserPromptSubmit' | 'Notification' | 'Stop';
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+  tool_output?: Record<string, unknown>;
+  user_prompt?: string;
+  ai_response?: string;
+  pipeline_id?: string;
+  event_id?: string;
+}
+
+interface BaseEvent {
+  session_id: string;
+  project_path: string;
+  timestamp: string;
+  event_id?: string;
+  pipeline_id?: string;
+}
+
+export interface PreToolUseEvent extends BaseEvent {
+  hook_type: 'PreToolUse';
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+}
+
+export interface PostToolUseEvent extends BaseEvent {
+  hook_type: 'PostToolUse';
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+  tool_output: Record<string, unknown>;
+}
+
+export interface UserPromptSubmitEvent extends BaseEvent {
+  hook_type: 'UserPromptSubmit';
+  user_prompt: string;
+}
+
+export interface NotificationEvent extends BaseEvent {
+  hook_type: 'Notification';
+  ai_response?: string;
+}
+
+export interface StopEvent extends BaseEvent {
+  hook_type: 'Stop';
+  ai_response?: string;
+}
+
+/** Narrow union for handlers / services that already know the hook type. */
+export type ForgeEventNarrow =
+  | PreToolUseEvent
+  | PostToolUseEvent
+  | UserPromptSubmitEvent
+  | NotificationEvent
+  | StopEvent;
+
+// ── Type Guards ──────────────────────────────────────────────────────────
+// Use these in handlers/services to narrow ForgeEvent → specific event type.
+// Under TS control-flow analysis they upgrade `event.tool_name` from
+// `string | undefined` to `string` without runtime asserts.
+
+export function isPreToolUse(e: ForgeEvent): e is PreToolUseEvent & ForgeEvent {
+  return e.hook_type === 'PreToolUse'
+    && typeof e.tool_name === 'string'
+    && e.tool_input !== undefined;
+}
+
+export function isPostToolUse(e: ForgeEvent): e is PostToolUseEvent & ForgeEvent {
+  return e.hook_type === 'PostToolUse'
+    && typeof e.tool_name === 'string'
+    && e.tool_input !== undefined
+    && e.tool_output !== undefined;
+}
+
+export function isUserPromptSubmit(e: ForgeEvent): e is UserPromptSubmitEvent & ForgeEvent {
+  return e.hook_type === 'UserPromptSubmit' && typeof e.user_prompt === 'string';
+}
+
+export function isNotification(e: ForgeEvent): e is NotificationEvent & ForgeEvent {
+  return e.hook_type === 'Notification';
+}
+
+export function isStop(e: ForgeEvent): e is StopEvent & ForgeEvent {
+  return e.hook_type === 'Stop';
+}
+
+/**
+ * Hook execution result
+ */
+export interface HookResult {
+  allow: boolean;
+  reason?: string;
+  systemMessage?: string;
+  additionalContext?: string;
+}
+
+/**
+ * Security configuration
+ */
+export interface SecurityConfig {
+  destructiveOps: boolean;
+  secretsCheck: boolean;
+  diffSizeCheck: boolean;
+  diffSizeThreshold: number;
+}
+
+/**
+ * Configuration structure
+ */
+export interface ForgeConfig {
+  ai: {
+    api_key: string;
+    model: string;
+    base_url?: string;
+    provider: string;
+  };
+  storage: {
+    path: string;
+    max_size_mb: number;
+  };
+  web: {
+    enabled: boolean;
+    port: number;
+  };
+  skill_matching?: {
+    api_key?: string;
+  };
+  security?: SecurityConfig;
+}

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

@@ -0,0 +1,256 @@
+/**
+ * 友好的错误提示处理器
+ *
+ * 将技术性错误转换为用户友好的中文提示，并提供解决方案
+ */
+
+import { logger } from './logger.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] || '3721');
+      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/forge.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);
+  }
+}