@winspan/claude-forge 8.41.0 → 8.50.6

package/src/core/storage/injections.ts

@@ -0,0 +1,78 @@
+/**
+ * InjectionOperations — injections 表读写
+ *
+ * 拆分自 sqlite.ts。
+ */
+
+import type Database from 'better-sqlite3';
+import { randomUUID } from 'node:crypto';
+
+export interface Injection {
+  id?: string;
+  event_id?: string;
+  session_id: string;
+  timestamp: string;
+  source_handler: string;
+  injection_type: 'systemMessage' | 'additionalContext' | 'reason';
+  content: string;
+}
+
+export class InjectionOperations {
+  constructor(private db: Database.Database) {}
+
+  writeInjection(injection: Injection): void {
+    const id = injection.id || randomUUID();
+    const stmt = this.db.prepare(`
+      INSERT INTO injections (id, event_id, session_id, timestamp, source_handler, injection_type, content)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);
+    stmt.run(
+      id,
+      injection.event_id ?? null,
+      injection.session_id,
+      injection.timestamp,
+      injection.source_handler,
+      injection.injection_type,
+      injection.content,
+    );
+  }
+
+  queryInjections(filter: {
+    session_id?: string;
+    event_id?: string;
+    source_handler?: string;
+    limit?: number;
+  } = {}): Injection[] {
+    const conditions: string[] = [];
+    const params: unknown[] = [];
+
+    if (filter.session_id) {
+      conditions.push('session_id = ?');
+      params.push(filter.session_id);
+    }
+    if (filter.event_id) {
+      conditions.push('event_id = ?');
+      params.push(filter.event_id);
+    }
+    if (filter.source_handler) {
+      conditions.push('source_handler = ?');
+      params.push(filter.source_handler);
+    }
+
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+    const limit = filter.limit ?? 100;
+    const sql = `SELECT * FROM injections ${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 string,
+      event_id: (r.event_id as string) || undefined,
+      session_id: r.session_id as string,
+      timestamp: r.timestamp as string,
+      source_handler: r.source_handler as string,
+      injection_type: r.injection_type as Injection['injection_type'],
+      content: r.content as string,
+    }));
+  }
+}

package/src/core/storage/maintenance.ts

@@ -0,0 +1,59 @@
+/**
+ * MaintenanceOperations — 数据清理 / VACUUM / 体积监控
+ *
+ * 拆分自 sqlite.ts。
+ */
+
+import type Database from 'better-sqlite3';
+import { existsSync, statSync } from 'node:fs';
+import { logger } from '../utils/logger.js';
+
+export class MaintenanceOperations {
+  constructor(
+    private db: Database.Database,
+    private dbPath: string,
+  ) {}
+
+  /**
+   * Clean events older than specified days
+   * @param daysToKeep Number of days to keep (default: 30)
+   * @returns Number of events deleted
+   */
+  cleanOldEvents(daysToKeep: number = 30): number {
+    const cutoffDate = new Date();
+    cutoffDate.setDate(cutoffDate.getDate() - daysToKeep);
+    const cutoff = cutoffDate.toISOString();
+
+    const result = this.db.prepare(`
+      DELETE FROM events WHERE timestamp < ?
+    `).run(cutoff);
+
+    const deleted = result.changes;
+    if (deleted > 0) {
+      logger.info(`[Storage] Cleaned ${deleted} events older than ${daysToKeep} days`);
+    }
+    return deleted;
+  }
+
+  runMaintenance(maxSizeMb: number): void {
+    const sizeMb = this.getDbSizeMb();
+    if (sizeMb < maxSizeMb) {
+      logger.debug(`[Storage] DB size ${sizeMb.toFixed(1)}MB < ${maxSizeMb}MB, skipping maintenance`);
+      return;
+    }
+
+    logger.info(`[Storage] Running maintenance (size: ${sizeMb.toFixed(1)}MB)`);
+
+    this.cleanOldEvents(30);
+    this.vacuum();
+  }
+
+  vacuum(): void {
+    this.db.exec('VACUUM');
+  }
+
+  getDbSizeMb(): number {
+    if (!existsSync(this.dbPath)) return 0;
+    return statSync(this.dbPath).size / (1024 * 1024);
+  }
+}

package/src/core/storage/migrations/002_add_skill_tracking.sql

@@ -0,0 +1,6 @@
+-- Migration: 新增 Skill 监控字段
+-- Date: 2026-05-11
+-- Description: 为 routing_events 表新增 skill_confidence 和 skill_source 字段
+
+ALTER TABLE routing_events ADD COLUMN skill_confidence REAL;
+ALTER TABLE routing_events ADD COLUMN skill_source TEXT;

package/src/core/storage/migrations/003_add_skill_invocations.sql

@@ -0,0 +1,23 @@
+-- Migration: 新增 skill_invocations 表
+-- Date: 2026-05-11
+-- Description: 追踪 Agent 动态调用 Skill 的链路
+
+CREATE TABLE IF NOT EXISTS skill_invocations (
+  id TEXT PRIMARY KEY,                     -- UUID
+  route_request_id TEXT,                   -- 关联外层路由（routing_events.route_request_id）
+  session_id TEXT NOT NULL,
+  agent_id TEXT,                           -- 发起调用的 Agent（可能为 NULL 如果是主 Claude）
+  skill_id TEXT NOT NULL,                  -- 被调用的 Skill ID
+  invocation_type TEXT NOT NULL,           -- 'static'（静态依赖） / 'dynamic'（动态调用） / 'slash_command'
+  reason TEXT,                             -- Agent 提供的调用理由
+  depth INTEGER DEFAULT 0,                 -- 调用嵌套深度
+  success INTEGER DEFAULT 1,               -- 1 成功 / 0 失败
+  error TEXT,                              -- 错误信息（如 skill 不存在）
+  timestamp INTEGER NOT NULL,              -- 调用时间戳（ms）
+  created_at TEXT DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_skill_invocations_route_request ON skill_invocations(route_request_id);
+CREATE INDEX IF NOT EXISTS idx_skill_invocations_session ON skill_invocations(session_id);
+CREATE INDEX IF NOT EXISTS idx_skill_invocations_skill ON skill_invocations(skill_id);
+CREATE INDEX IF NOT EXISTS idx_skill_invocations_timestamp ON skill_invocations(timestamp DESC);

package/src/core/storage/performance-indexes.sql

@@ -0,0 +1,23 @@
+-- Performance optimization indexes
+-- Add these indexes to improve query performance
+
+-- Sessions table optimization
+CREATE INDEX IF NOT EXISTS idx_sessions_start_time ON sessions(start_time DESC);
+CREATE INDEX IF NOT EXISTS idx_sessions_end_time ON sessions(end_time DESC);
+CREATE INDEX IF NOT EXISTS idx_sessions_last_event ON sessions(last_event_time DESC);
+
+-- V2 decisions table optimization (timestamp index)
+CREATE INDEX IF NOT EXISTS idx_v2_decisions_timestamp ON v2_decisions(timestamp DESC);
+
+-- Injections table optimization
+CREATE INDEX IF NOT EXISTS idx_injections_handler ON injections(source_handler);
+
+-- Tasks table optimization
+CREATE INDEX IF NOT EXISTS idx_tasks_session ON tasks(session_id);
+CREATE INDEX IF NOT EXISTS idx_tasks_start_time ON tasks(start_time DESC);
+CREATE INDEX IF NOT EXISTS idx_tasks_end_time ON tasks(end_time DESC);
+
+-- Composite indexes for common query patterns
+CREATE INDEX IF NOT EXISTS idx_events_session_timestamp ON events(session_id, timestamp DESC);
+CREATE INDEX IF NOT EXISTS idx_events_project_timestamp ON events(project_path, timestamp DESC);
+CREATE INDEX IF NOT EXISTS idx_sessions_project_start ON sessions(project_path, start_time DESC);

package/src/core/storage/routing.ts

@@ -0,0 +1,194 @@
+/**
+ * RoutingOperations — routing_events + experiment_assignments 读写
+ *
+ * 拆分自 sqlite.ts。
+ *
+ * 注意：experiment_assignments 表在 base.ts 的 deprecated 列表里被 DROP 了，
+ * 但保留访问方法以维持 API 向后兼容（旧库残留 / 不同 schema 版本）。
+ */
+
+import type Database from 'better-sqlite3';
+
+export interface RoutingEventRecord {
+  id?: number;
+  session_id: string;
+  route_request_id?: string | null;
+  project_path: string;
+  ts: number;
+  prompt: string;
+  intent_json: string;
+  routed_to_type?: 'agent' | 'skill' | 'none' | null;
+  routed_to_name?: string | null;
+  is_forced?: number;
+  obeyed?: number | null;
+  classification_ms?: number | null;
+  fallback_used?: number;
+  refusal_reason?: string | null;
+  first_tool_name?: string | null;
+  first_tool_ts?: number | null;
+  completed_ts?: number | null;
+  total_execution_ms?: number | null;
+  completion_reason?: string | null;
+  downstream_task_chain?: string | null;
+  injection_version?: string | null;
+  experiment_id?: string | null;
+  experiment_group?: string | null;
+  skill_confidence?: number | null;
+  skill_source?: 'auto' | 'slash_command' | 'agent_dependency' | null;
+}
+
+export interface RoutingEventRow extends RoutingEventRecord {
+  id: number;
+  created_at: string;
+}
+
+export class RoutingOperations {
+  constructor(private db: Database.Database) {}
+
+  writeRoutingEvent(record: RoutingEventRecord): number {
+    const result = this.db.prepare(`
+      INSERT INTO routing_events (
+        session_id, route_request_id, project_path, ts, prompt, intent_json,
+        routed_to_type, routed_to_name, is_forced, obeyed,
+        classification_ms, fallback_used, refusal_reason,
+        first_tool_name, first_tool_ts, completed_ts,
+        total_execution_ms, completion_reason, downstream_task_chain,
+        injection_version, experiment_id, experiment_group
+      ) VALUES (
+        @session_id, @route_request_id, @project_path, @ts, @prompt, @intent_json,
+        @routed_to_type, @routed_to_name, @is_forced, @obeyed,
+        @classification_ms, @fallback_used, @refusal_reason,
+        @first_tool_name, @first_tool_ts, @completed_ts,
+        @total_execution_ms, @completion_reason, @downstream_task_chain,
+        @injection_version, @experiment_id, @experiment_group
+      )
+    `).run({
+      session_id: record.session_id,
+      route_request_id: record.route_request_id ?? null,
+      project_path: record.project_path,
+      ts: record.ts,
+      prompt: record.prompt,
+      intent_json: record.intent_json,
+      routed_to_type: record.routed_to_type ?? null,
+      routed_to_name: record.routed_to_name ?? null,
+      is_forced: record.is_forced ?? 0,
+      obeyed: record.obeyed ?? null,
+      classification_ms: record.classification_ms ?? null,
+      fallback_used: record.fallback_used ?? 0,
+      refusal_reason: record.refusal_reason ?? null,
+      first_tool_name: record.first_tool_name ?? null,
+      first_tool_ts: record.first_tool_ts ?? null,
+      completed_ts: record.completed_ts ?? null,
+      total_execution_ms: record.total_execution_ms ?? null,
+      completion_reason: record.completion_reason ?? null,
+      downstream_task_chain: record.downstream_task_chain ?? null,
+      injection_version: record.injection_version ?? null,
+      experiment_id: record.experiment_id ?? null,
+      experiment_group: record.experiment_group ?? null,
+    });
+    return Number(result.lastInsertRowid);
+  }
+
+  updateRoutingEvent(id: number, patch: Partial<RoutingEventRecord>): void {
+    const fields = Object.keys(patch).filter((k) => k !== 'id');
+    if (fields.length === 0) return;
+    const setClause = fields.map((f) => `${f} = @${f}`).join(', ');
+    this.db.prepare(`UPDATE routing_events SET ${setClause} WHERE id = @id`).run({
+      ...patch,
+      id,
+    });
+  }
+
+  queryRoutingEvents(filter: {
+    session_id?: string;
+    project_path?: string;
+    since_ts?: number;
+    routed_to_name?: string;
+    obeyed?: number | null;
+    limit?: number;
+  } = {}): RoutingEventRow[] {
+    const conds: string[] = [];
+    const params: Record<string, unknown> = {};
+    if (filter.session_id) { conds.push('session_id = @session_id'); params.session_id = filter.session_id; }
+    if (filter.project_path) { conds.push('project_path = @project_path'); params.project_path = filter.project_path; }
+    if (filter.since_ts !== undefined) { conds.push('ts >= @since_ts'); params.since_ts = filter.since_ts; }
+    if (filter.routed_to_name) { conds.push('routed_to_name = @routed_to_name'); params.routed_to_name = filter.routed_to_name; }
+    if (filter.obeyed !== undefined) {
+      if (filter.obeyed === null) conds.push('obeyed IS NULL');
+      else { conds.push('obeyed = @obeyed'); params.obeyed = filter.obeyed; }
+    }
+    const where = conds.length > 0 ? `WHERE ${conds.join(' AND ')}` : '';
+    const limit = filter.limit ?? 100;
+    params.limit = limit;
+    const rows = this.db.prepare(
+      `SELECT * FROM routing_events ${where} ORDER BY ts DESC LIMIT @limit`
+    ).all(params) as RoutingEventRow[];
+    return rows;
+  }
+
+  /** Pending events with NULL obeyed within the last N seconds; used by daemon restart recovery. */
+  findPendingRoutingEvents(ageMs: number): RoutingEventRow[] {
+    const cutoff = Date.now() - ageMs;
+    return this.db.prepare(
+      `SELECT * FROM routing_events WHERE obeyed IS NULL AND ts >= ? ORDER BY ts DESC`
+    ).all(cutoff) as RoutingEventRow[];
+  }
+
+  /** Get the most recent routing_event for a session (used by Agent observation). */
+  getRecentRoutingEvent(sessionId: string): { id: number } | null {
+    const row = this.db.prepare(`
+      SELECT id FROM routing_events
+      WHERE session_id = ?
+      ORDER BY ts DESC
+      LIMIT 1
+    `).get(sessionId) as { id: number } | undefined;
+    return row ?? null;
+  }
+
+  // ── Experiment Assignments ──────────────────────────────────────────────
+
+  getExperimentAssignment(sessionId: string, experimentId: string): string | null {
+    const row = this.db.prepare(
+      `SELECT group_id FROM experiment_assignments WHERE session_id = ? AND experiment_id = ?`
+    ).get(sessionId, experimentId) as { group_id: string } | undefined;
+    return row ? row.group_id : null;
+  }
+
+  setExperimentAssignment(sessionId: string, experimentId: string, groupId: string): void {
+    this.db.prepare(
+      `INSERT OR IGNORE INTO experiment_assignments (session_id, experiment_id, group_id)
+       VALUES (?, ?, ?)`
+    ).run(sessionId, experimentId, groupId);
+  }
+
+  queryExperimentStats(experimentId: string): Array<{
+    group_id: string;
+    total: number;
+    obeyed: number;
+    refused: number;
+    unknown: number;
+    avg_classification_ms: number | null;
+  }> {
+    const rows = this.db.prepare(`
+      SELECT
+        experiment_group AS group_id,
+        COUNT(*) AS total,
+        SUM(CASE WHEN obeyed = 1 THEN 1 ELSE 0 END) AS obeyed,
+        SUM(CASE WHEN obeyed = 0 THEN 1 ELSE 0 END) AS refused,
+        SUM(CASE WHEN obeyed IS NULL THEN 1 ELSE 0 END) AS unknown,
+        AVG(classification_ms) AS avg_classification_ms
+      FROM routing_events
+      WHERE experiment_id = ? AND experiment_group IS NOT NULL
+      GROUP BY experiment_group
+      ORDER BY experiment_group ASC
+    `).all(experimentId) as Array<{
+      group_id: string;
+      total: number;
+      obeyed: number;
+      refused: number;
+      unknown: number;
+      avg_classification_ms: number | null;
+    }>;
+    return rows;
+  }
+}

package/src/core/storage/rows.ts

@@ -0,0 +1,112 @@
+/**
+ * 数据库行的 TypeScript 类型定义。
+ *
+ * 每个 interface 对应一张表的查询结果行（shape 与 schema.sql + runMigrations 后
+ * 的最终结构一致）。sqlite.ts 的所有 get/all 返回值都应该用这些类型而非 any，
+ * 以确保 schema 变动能在编译期而不是运行期暴露。
+ *
+ * 约定：
+ * - 字段可空性严格对齐 schema.sql 的 NOT NULL / DEFAULT NULL / 外键约束
+ * - enum 字段（status / mode / trigger_type 等）使用 string literal union
+ * - timestamp 字段按实际存储类型：文本时间戳 → string，Unix 毫秒数 → number
+ */
+
+// ── events ────────────────────────────────────────────────────────────────
+
+export interface EventRow {
+  event_id: string;
+  session_id: string;
+  project_path: string;
+  timestamp: string;
+  hook_type: 'PreToolUse' | 'PostToolUse' | 'UserPromptSubmit' | 'Notification' | 'Stop';
+  tool_name: string | null;
+  tool_input: string | null; // JSON string
+  tool_output: string | null; // JSON string
+  user_prompt: string | null;
+  ai_response: string | null;
+  created_at: string;
+}
+
+// ── sessions ──────────────────────────────────────────────────────────────
+
+export interface SessionRow {
+  session_id: string;
+  project_path: string;
+  status: 'active' | 'completed' | 'interrupted' | 'resumed' | 'abandoned';
+  first_prompt: string | null;
+  start_time: string;
+  end_time: string | null;
+  last_event_time: string | null;
+  event_count: number;
+  created_at: string;
+  updated_at: string;
+}
+
+// ── injections ────────────────────────────────────────────────────────────
+
+export interface InjectionRow {
+  id: string;
+  event_id: string | null;
+  session_id: string;
+  timestamp: string;
+  source_handler: string;
+  injection_type: 'systemMessage' | 'additionalContext' | 'reason';
+  content: string;
+  created_at: string;
+}
+
+// ── tasks ─────────────────────────────────────────────────────────────────
+
+export interface TaskRow {
+  id: string;
+  session_id: string;
+  title: string;
+  description: string | null;
+  start_time: string;
+  end_time: string | null;
+  status: 'active' | 'completed' | 'abandoned';
+  event_count: number;
+  created_at: string;
+}
+
+// ── token_usage ───────────────────────────────────────────────────────────
+
+export interface TokenUsageRow {
+  id: number;
+  session_id: string;
+  timestamp: number;
+  input_tokens: number;
+  output_tokens: number;
+  total_tokens: number;
+  model: string | null;
+  tool_name: string | null;
+  created_at: string;
+}
+
+// ── skill_invocations ─────────────────────────────────────────────────────
+// Skill 调用链路追踪：Agent 动态调用 Skill 的每一次记录。
+// invocation_type 区分静态依赖（agent frontmatter 声明）、动态调用（MCP 工具 `skill_invoke`）、
+// 以及 slash_command（用户直接通过 /skill-xxx 触发）。
+
+export interface SkillInvocationRow {
+  id: string;
+  route_request_id: string | null;
+  session_id: string;
+  agent_id: string | null;
+  skill_id: string;
+  invocation_type: 'static' | 'dynamic' | 'slash_command';
+  reason: string | null;
+
+  // 工作流追踪字段（v8.38+）：从 reason 字段解析的 <workflow>/<phase>[:feature-slug] 元信息。
+  // 解析失败或非工作流调用时所有字段为 null，以保持向后兼容。
+  workflow: string | null;             // 'bmad' / 'harness' / 其他工作流标识
+  phase: string | null;                // 'analyze' / 'design' / 'safety-net' 等
+  feature_slug: string | null;         // 可选，关联同一 feature 的多次调用
+  artifact_path: string | null;        // 可选，调用产出的文档路径
+
+  depth: number;
+  success: number; // SQLite 存储为 INTEGER (0 | 1)
+  error: string | null;
+  timestamp: number;
+  created_at: string;
+}