@winspan/claude-forge 8.41.0 → 8.51.0

package/src/web/analytics/anti-pattern-detector.ts

@@ -0,0 +1,367 @@
+/**
+ * AntiPatternDetector — 工作流反模式检测引擎
+ *
+ * 扫描 events / sessions 表，识别可操作的反模式：
+ *   - edit_loop:           同一文件反复 Edit/Write（调试鬼打墙）
+ *   - tool_failure_spike:  最近 24h 工具失败率突增
+ *   - no_commit:           长会话无 git commit
+ *   - event_overflow:      单 session 事件数异常
+ *
+ * 性能策略：
+ *   - 一次性拉取窗口内事件，4 条规则共享缓存
+ *   - 仅读 storage（getDatabase + queryEvents + querySessions），不改任何状态
+ */
+
+import { createHash } from 'node:crypto';
+import type { SQLiteStorage } from '../../core/storage/sqlite.js';
+import type { ForgeEvent } from '../../core/types.js';
+import type { SessionSummary } from '../../core/storage/sessions.js';
+
+export type AntiPatternType =
+  | 'edit_loop'
+  | 'tool_failure_spike'
+  | 'no_commit'
+  | 'event_overflow';
+
+export type AntiPatternSeverity = 'info' | 'warn' | 'critical';
+
+export interface AntiPattern {
+  id: string;
+  type: AntiPatternType;
+  severity: AntiPatternSeverity;
+  title: string;
+  description: string;
+  detail: Record<string, unknown>;
+  detectedAt: string;
+  sessionId?: string;
+  filePath?: string;
+}
+
+const DAY_MS = 24 * 3600 * 1000;
+const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit']);
+
+export class AntiPatternDetector {
+  constructor(private storage: SQLiteStorage) {}
+
+  /**
+   * 运行全部反模式规则。
+   *
+   * @param windowDays 检测窗口（天），默认 7
+   */
+  detectAll(windowDays: number = 7): AntiPattern[] {
+    const now = Date.now();
+    const sinceMs = now - windowDays * DAY_MS;
+    const sinceISO = new Date(sinceMs).toISOString();
+    const detectedAt = new Date(now).toISOString();
+
+    // 一次性拉取窗口内事件 + 会话，4 条规则共用
+    const events = this.queryEventsSince(sinceISO);
+    const sessions = this.querySessionsSince(sinceISO);
+
+    const patterns: AntiPattern[] = [
+      ...this.detectEditLoop(events, detectedAt),
+      ...this.detectToolFailureSpike(events, now, windowDays, detectedAt),
+      ...this.detectNoCommit(sessions, events, detectedAt),
+      ...this.detectEventOverflow(sessions, events, detectedAt),
+    ];
+
+    // 按 severity → critical→warn→info 排序，方便前端取 top N
+    const sevOrder: Record<AntiPatternSeverity, number> = { critical: 0, warn: 1, info: 2 };
+    patterns.sort((a, b) => sevOrder[a.severity] - sevOrder[b.severity]);
+    return patterns;
+  }
+
+  // ── 数据加载 ──────────────────────────────────────────────────────────
+
+  /**
+   * 拉取窗口内全部事件。
+   *
+   * H2 Phase 3: 改用 facade 聚合方法。
+   */
+  private queryEventsSince(sinceISO: string): ForgeEvent[] {
+    return this.storage.queryEventsByTimeRange({ since: sinceISO });
+  }
+
+  private querySessionsSince(sinceISO: string): SessionSummary[] {
+    return this.storage.querySessionsByTimeRange({ since: sinceISO });
+  }
+
+  // ── Rule 1: edit_loop ─────────────────────────────────────────────────
+
+  private detectEditLoop(events: ForgeEvent[], detectedAt: string): AntiPattern[] {
+    // 仅 PreToolUse 计一次（避免 Pre + Post 重复计数）
+    const buckets = new Map<string, {
+      sessionId: string;
+      filePath: string;
+      count: number;
+      firstAt: string;
+      lastAt: string;
+    }>();
+
+    for (const ev of events) {
+      if (ev.hook_type !== 'PreToolUse') continue;
+      if (!ev.tool_name || !EDIT_TOOLS.has(ev.tool_name)) continue;
+      const filePath = extractFilePath(ev.tool_input);
+      if (!filePath) continue;
+
+      const key = `${ev.session_id}::${filePath}`;
+      const cur = buckets.get(key);
+      if (cur) {
+        cur.count += 1;
+        if (ev.timestamp < cur.firstAt) cur.firstAt = ev.timestamp;
+        if (ev.timestamp > cur.lastAt) cur.lastAt = ev.timestamp;
+      } else {
+        buckets.set(key, {
+          sessionId: ev.session_id,
+          filePath,
+          count: 1,
+          firstAt: ev.timestamp,
+          lastAt: ev.timestamp,
+        });
+      }
+    }
+
+    const out: AntiPattern[] = [];
+    for (const b of buckets.values()) {
+      if (b.count < 5) continue;
+      const severity: AntiPatternSeverity = b.count >= 8 ? 'critical' : 'warn';
+      out.push({
+        id: stableId('edit_loop', b.sessionId, b.filePath),
+        type: 'edit_loop',
+        severity,
+        title: `编辑循环：${shortPath(b.filePath)} 被改动 ${b.count} 次`,
+        description: `会话 ${shortId(b.sessionId)} 内对同一文件反复 Edit/Write，疑似调试鬼打墙。`,
+        detail: {
+          filePath: b.filePath,
+          count: b.count,
+          sessionId: b.sessionId,
+          firstEditAt: b.firstAt,
+          lastEditAt: b.lastAt,
+        },
+        detectedAt,
+        sessionId: b.sessionId,
+        filePath: b.filePath,
+      });
+    }
+    return out;
+  }
+
+  // ── Rule 2: tool_failure_spike ────────────────────────────────────────
+
+  private detectToolFailureSpike(
+    events: ForgeEvent[],
+    nowMs: number,
+    windowDays: number,
+    detectedAt: string,
+  ): AntiPattern[] {
+    const recentCutoffMs = nowMs - DAY_MS;
+    const recentCutoffISO = new Date(recentCutoffMs).toISOString();
+
+    let recentTotal = 0;
+    let recentFailures = 0;
+    let baselineTotal = 0;
+    let baselineFailures = 0;
+
+    for (const ev of events) {
+      if (ev.hook_type !== 'PostToolUse') continue;
+      const failed = isFailedToolOutput(ev.tool_output);
+      if (ev.timestamp >= recentCutoffISO) {
+        recentTotal += 1;
+        if (failed) recentFailures += 1;
+      } else {
+        baselineTotal += 1;
+        if (failed) baselineFailures += 1;
+      }
+    }
+
+    if (recentTotal < 10) {
+      // 样本太少，不报警
+      return [];
+    }
+
+    const recentRate = recentFailures / recentTotal;
+    const baselineRate = baselineTotal > 0 ? baselineFailures / baselineTotal : 0;
+
+    if (recentRate < 0.2) return [];
+
+    const severity: AntiPatternSeverity = recentRate >= 0.4 ? 'critical' : 'warn';
+    return [{
+      id: stableId('tool_failure_spike', detectedAt.slice(0, 13)),
+      type: 'tool_failure_spike',
+      severity,
+      title: `工具失败率 ${(recentRate * 100).toFixed(1)}%（最近 24h）`,
+      description: `最近 24 小时 PostToolUse 失败比例显著高于过去 ${windowDays - 1} 天均值（${(baselineRate * 100).toFixed(1)}%）。`,
+      detail: {
+        recentFailureRate: round(recentRate, 4),
+        baselineFailureRate: round(baselineRate, 4),
+        recentWindowHours: 24,
+        baselineWindowDays: Math.max(windowDays - 1, 1),
+        totalToolUses: recentTotal,
+        failures: recentFailures,
+        baselineTotal,
+        baselineFailures,
+      },
+      detectedAt,
+    }];
+  }
+
+  // ── Rule 3: no_commit ─────────────────────────────────────────────────
+
+  private detectNoCommit(
+    sessions: SessionSummary[],
+    events: ForgeEvent[],
+    detectedAt: string,
+  ): AntiPattern[] {
+    // 预聚合：每个 session 内的 Bash 命令文本
+    const bashBySession = new Map<string, string[]>();
+    for (const ev of events) {
+      if (ev.tool_name !== 'Bash') continue;
+      if (ev.hook_type !== 'PreToolUse') continue;
+      const cmd = extractBashCommand(ev.tool_input);
+      if (!cmd) continue;
+      const list = bashBySession.get(ev.session_id);
+      if (list) list.push(cmd);
+      else bashBySession.set(ev.session_id, [cmd]);
+    }
+
+    const out: AntiPattern[] = [];
+    for (const s of sessions) {
+      const durationMs = isoDiffMs(s.start_time, s.end_time);
+      const durationMin = durationMs / 60000;
+      if (durationMin <= 30) continue;
+
+      const cmds = bashBySession.get(s.session_id) ?? [];
+      const hasCommit = cmds.some((c) => /\bgit\s+commit\b/.test(c));
+      if (hasCommit) continue;
+
+      const severity: AntiPatternSeverity = durationMin > 60 ? 'critical' : 'warn';
+      out.push({
+        id: stableId('no_commit', s.session_id),
+        type: 'no_commit',
+        severity,
+        title: `${Math.round(durationMin)} 分钟会话无 git commit`,
+        description: `会话 ${shortId(s.session_id)} 持续 ${Math.round(durationMin)} 分钟未沉淀提交。`,
+        detail: {
+          sessionId: s.session_id,
+          durationMin: Math.round(durationMin),
+          eventCount: s.event_count,
+          startTime: s.start_time,
+          endTime: s.end_time,
+          bashCommands: cmds.length,
+        },
+        detectedAt,
+        sessionId: s.session_id,
+      });
+    }
+    return out;
+  }
+
+  // ── Rule 4: event_overflow ────────────────────────────────────────────
+
+  private detectEventOverflow(
+    sessions: SessionSummary[],
+    events: ForgeEvent[],
+    detectedAt: string,
+  ): AntiPattern[] {
+    // 按 session 统计 top tools
+    const toolBySession = new Map<string, Map<string, number>>();
+    for (const ev of events) {
+      if (!ev.tool_name) continue;
+      let m = toolBySession.get(ev.session_id);
+      if (!m) {
+        m = new Map();
+        toolBySession.set(ev.session_id, m);
+      }
+      m.set(ev.tool_name, (m.get(ev.tool_name) ?? 0) + 1);
+    }
+
+    const out: AntiPattern[] = [];
+    for (const s of sessions) {
+      if (s.event_count <= 500) continue;
+      const severity: AntiPatternSeverity = s.event_count > 1000 ? 'critical' : 'warn';
+      const durationMin = Math.round(isoDiffMs(s.start_time, s.end_time) / 60000);
+      const topTools = topN(toolBySession.get(s.session_id), 5);
+
+      out.push({
+        id: stableId('event_overflow', s.session_id),
+        type: 'event_overflow',
+        severity,
+        title: `事件爆量：${s.event_count} 个事件`,
+        description: `会话 ${shortId(s.session_id)} 单次累计 ${s.event_count} 个事件，可能任务规划失败或循环失控。`,
+        detail: {
+          sessionId: s.session_id,
+          eventCount: s.event_count,
+          durationMin,
+          topTools,
+          startTime: s.start_time,
+          endTime: s.end_time,
+        },
+        detectedAt,
+        sessionId: s.session_id,
+      });
+    }
+    return out;
+  }
+}
+
+// ── helpers ─────────────────────────────────────────────────────────────
+
+function extractFilePath(input: ForgeEvent['tool_input']): string | undefined {
+  if (!input) return undefined;
+  const fp = input.file_path;
+  if (typeof fp === 'string' && fp.length > 0) return fp;
+  return undefined;
+}
+
+function extractBashCommand(input: ForgeEvent['tool_input']): string | undefined {
+  if (!input) return undefined;
+  const cmd = input.command;
+  return typeof cmd === 'string' ? cmd : undefined;
+}
+
+function isFailedToolOutput(out: Record<string, unknown> | undefined): boolean {
+  if (!out) return false;
+  // Claude Code 的 PostToolUse output 形态：
+  //   - { error: "..." }                    → 失败
+  //   - { success: false, error: "..." }    → 失败
+  //   - { stderr: "...", stdout: "" }       → 通常代表失败（仅当 stderr 非空且 stdout 空）
+  //   - { isError: true }                   → 失败
+  const err = out.error;
+  if (typeof err === 'string' && err.length > 0) return true;
+  if (out.success === false) return true;
+  if (out.isError === true) return true;
+  return false;
+}
+
+function isoDiffMs(startISO: string, endISO: string): number {
+  const s = Date.parse(startISO);
+  const e = Date.parse(endISO);
+  if (Number.isNaN(s) || Number.isNaN(e)) return 0;
+  return Math.max(0, e - s);
+}
+
+function topN(map: Map<string, number> | undefined, n: number): Array<{ tool: string; count: number }> {
+  if (!map) return [];
+  return [...map.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, n)
+    .map(([tool, count]) => ({ tool, count }));
+}
+
+function round(n: number, digits: number): number {
+  const f = 10 ** digits;
+  return Math.round(n * f) / f;
+}
+
+function shortId(id: string): string {
+  return id.length > 8 ? id.slice(0, 8) : id;
+}
+
+function shortPath(p: string): string {
+  if (p.length <= 60) return p;
+  return '…' + p.slice(-58);
+}
+
+function stableId(...parts: string[]): string {
+  return createHash('sha1').update(parts.join('|')).digest('hex').slice(0, 16);
+}

package/src/web/analytics/drift-detector.ts

@@ -0,0 +1,219 @@
+/**
+ * DriftDetector — CLAUDE.md 漂移检测引擎
+ *
+ * 对比 CLAUDE.md 中声明的行为预期与实际事件流数据，
+ * 生成合规度报告（DriftReport）。
+ *
+ * 只读 storage，不写入任何数据。
+ */
+
+import type { SQLiteStorage } from '../../core/storage/sqlite.js';
+
+export interface DriftReport {
+  generatedAt: string;
+  period: { days: number; since: string };
+  checks: DriftCheck[];
+  overallScore: number; // 0-100, 100=完全符合
+}
+
+export interface DriftCheck {
+  rule: string;
+  expected: string;
+  actual: string;
+  status: 'pass' | 'warn' | 'fail';
+  detail?: string;
+}
+
+export class DriftDetector {
+  constructor(private storage: SQLiteStorage) {}
+
+  /**
+   * 执行全部漂移检测规则，返回报告。
+   */
+  run(days: number = 7): DriftReport {
+    const since = Date.now() - days * 24 * 3600 * 1000;
+    const sinceISO = new Date(since).toISOString();
+
+    const checks: DriftCheck[] = [
+      this.checkAgentDelegationRate(since),
+      this.checkSkillTriggerRate(since),
+      this.checkActiveSkillCoverage(since),
+      this.checkEventContinuity(),
+      this.checkTaskSegmentation(since),
+    ];
+
+    const overallScore = this.computeScore(checks);
+
+    return {
+      generatedAt: new Date().toISOString(),
+      period: { days, since: sinceISO },
+      checks,
+      overallScore,
+    };
+  }
+
+  /**
+   * 规则 1: Agent 委托率
+   * 预期: CLAUDE.md 声明"默认 spawn Agent"，obeyed 率应 >30%
+   */
+  private checkAgentDelegationRate(since: number): DriftCheck {
+    const events = this.storage.queryRoutingEvents({ since_ts: since, limit: 10000 });
+    const total = events.length;
+    const obeyed = events.filter(e => e.obeyed === 1).length;
+    const rate = total > 0 ? Math.round((obeyed / total) * 1000) / 10 : 0;
+
+    let status: DriftCheck['status'];
+    if (total === 0) {
+      status = 'warn';
+    } else if (rate >= 30) {
+      status = 'pass';
+    } else if (rate >= 10) {
+      status = 'warn';
+    } else {
+      status = 'fail';
+    }
+
+    return {
+      rule: 'Agent 委托率',
+      expected: '>30% 路由事件被 Agent 执行 (obeyed=1)',
+      actual: `${rate}% (${obeyed}/${total})`,
+      status,
+      detail: total === 0 ? '期间无路由事件' : undefined,
+    };
+  }
+
+  /**
+   * 规则 2: Skill 触发率
+   * 预期: 有 Skill 系统就应该有触发，>10%
+   */
+  private checkSkillTriggerRate(since: number): DriftCheck {
+    const routingEvents = this.storage.queryRoutingEvents({ since_ts: since, limit: 10000 });
+    const totalRouting = routingEvents.length;
+    const invocations = this.storage.querySkillInvocations({ since, limit: 10000 });
+    const totalInvocations = invocations.length;
+
+    const rate = totalRouting > 0
+      ? Math.round((totalInvocations / totalRouting) * 1000) / 10
+      : 0;
+
+    let status: DriftCheck['status'];
+    if (totalRouting === 0) {
+      status = 'warn';
+    } else if (rate >= 10) {
+      status = 'pass';
+    } else if (rate >= 5) {
+      status = 'warn';
+    } else {
+      status = 'fail';
+    }
+
+    return {
+      rule: 'Skill 触发率',
+      expected: '>10% (skill_invocations / routing_events)',
+      actual: `${rate}% (${totalInvocations}/${totalRouting})`,
+      status,
+      detail: totalRouting === 0 ? '期间无路由事件' : undefined,
+    };
+  }
+
+  /**
+   * 规则 3: 活跃 Skill 覆盖率
+   * 预期: 至少 3 个不同 Skill 被调用
+   */
+  private checkActiveSkillCoverage(since: number): DriftCheck {
+    // H2 Phase 3: 改用 facade。countDistinctSkillsSince 接收 unix ms。
+    const distinctCount = this.storage.countDistinctSkillsSince(since);
+
+    let status: DriftCheck['status'];
+    if (distinctCount >= 3) {
+      status = 'pass';
+    } else if (distinctCount >= 1) {
+      status = 'warn';
+    } else {
+      status = 'fail';
+    }
+
+    return {
+      rule: '活跃 Skill 覆盖率',
+      expected: '>=3 个不同 Skill 被调用',
+      actual: `${distinctCount} 个不同 Skill`,
+      status,
+    };
+  }
+
+  /**
+   * 规则 4: 事件记录连续性
+   * 预期: 最近 7 天中至少 5 天有事件（工作日）
+   */
+  private checkEventContinuity(): DriftCheck {
+    // H2 Phase 3: 改用 facade。
+    // 旧 SQL: timestamp >= date('now', '-7 days')
+    // 新口径：调用方计算 ISO 字符串。
+    const sevenDaysAgoIso = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+    const activeDays = this.storage.countActiveDays({ since: sevenDaysAgoIso });
+
+    let status: DriftCheck['status'];
+    if (activeDays >= 5) {
+      status = 'pass';
+    } else if (activeDays >= 3) {
+      status = 'warn';
+    } else {
+      status = 'fail';
+    }
+
+    return {
+      rule: '事件记录连续性',
+      expected: '最近 7 天中 >=5 天有事件',
+      actual: `${activeDays} 天有事件`,
+      status,
+    };
+  }
+
+  /**
+   * 规则 5: 任务分段有效性
+   * 预期: 每个 session 至少有 1 个 task (tasks/sessions >= 0.8)
+   */
+  private checkTaskSegmentation(since: number): DriftCheck {
+    // H2 Phase 3: 改用 facade。
+    const sinceISO = new Date(since).toISOString();
+    const sessionCount = this.storage.countSessionsByRange({ since: sinceISO });
+    const taskCount = this.storage.countTasksByRange({ since: sinceISO });
+
+    const ratio = sessionCount > 0
+      ? Math.round((taskCount / sessionCount) * 100) / 100
+      : 0;
+
+    let status: DriftCheck['status'];
+    if (sessionCount === 0) {
+      status = 'warn';
+    } else if (ratio >= 0.8) {
+      status = 'pass';
+    } else if (ratio >= 0.5) {
+      status = 'warn';
+    } else {
+      status = 'fail';
+    }
+
+    return {
+      rule: '任务分段有效性',
+      expected: 'tasks/sessions >= 0.8',
+      actual: `${ratio} (${taskCount} tasks / ${sessionCount} sessions)`,
+      status,
+      detail: sessionCount === 0 ? '期间无会话' : undefined,
+    };
+  }
+
+  /**
+   * 计算总体合规分数 (0-100)
+   * pass=20, warn=10, fail=0 (每条规则满分 20)
+   */
+  private computeScore(checks: DriftCheck[]): number {
+    const maxPerCheck = 100 / checks.length;
+    let total = 0;
+    for (const check of checks) {
+      if (check.status === 'pass') total += maxPerCheck;
+      else if (check.status === 'warn') total += maxPerCheck * 0.5;
+    }
+    return Math.round(total);
+  }
+}