@gong-ym/ai-spec-auto 0.2.3

package/src/visual/hook-dashboard.js

@@ -0,0 +1,216 @@
+'use strict';
+
+/**
+ * HookDashboard — Hook/Test/Repair 结果分析与可视化
+ * 支持 Hook 通过率、Test 通过率、Repair 成功率、失败原因分类
+ */
+
+const HOOK_EVENT_TYPES = ['hook.passed', 'hook.failed', 'hook.skipped'];
+const TEST_EVENT_TYPES = ['test.passed', 'test.failed', 'test.skipped'];
+const REPAIR_EVENT_TYPES = ['repair.attempt', 'repair.success', 'repair.failed'];
+
+class HookDashboard {
+  /**
+   * 分析 Hook 事件 → 返回 hook 视图
+   * @param {object[]} events
+   * @returns {object[]}
+   */
+  analyzeHookResults(events) {
+    const hookEvents = (events || []).filter(e => HOOK_EVENT_TYPES.includes(e.eventType));
+    const byHookId = new Map();
+
+    for (const e of hookEvents) {
+      const hookId = e.metadata?.hookId || e.eventType;
+      if (!byHookId.has(hookId)) {
+        byHookId.set(hookId, {
+          hookId,
+          hookType: e.stage || 'unknown',
+          totalRuns: 0,
+          passCount: 0,
+          failCount: 0,
+          skipCount: 0,
+          failures: [],
+          durations: []
+        });
+      }
+      const hook = byHookId.get(hookId);
+      hook.totalRuns++;
+
+      if (e.eventType === 'hook.passed') hook.passCount++;
+      else if (e.eventType === 'hook.failed') {
+        hook.failCount++;
+        hook.failures.push({
+          eventId: e.eventId,
+          reason: e.message,
+          timestamp: e.timestamp
+        });
+      }
+      else if (e.eventType === 'hook.skipped') hook.skipCount++;
+
+      if (e.metadata?.durationMs) {
+        hook.durations.push(e.metadata.durationMs);
+      }
+    }
+
+    return Array.from(byHookId.values()).map(h => ({
+      hookId: h.hookId,
+      hookType: h.hookType,
+      totalRuns: h.totalRuns,
+      passCount: h.passCount,
+      failCount: h.failCount,
+      skipCount: h.skipCount,
+      failures: h.failures,
+      avgDurationMs: h.durations.length > 0
+        ? Math.round(h.durations.reduce((a, b) => a + b, 0) / h.durations.length)
+        : 0
+    }));
+  }
+
+  /**
+   * 分析 Test 事件 → 返回 test 视图
+   * @param {object[]} events
+   * @returns {object}
+   */
+  analyzeTestResults(events) {
+    const testEvents = (events || []).filter(e => TEST_EVENT_TYPES.includes(e.eventType));
+    let passed = 0;
+    let failed = 0;
+    let skipped = 0;
+    const failures = [];
+
+    for (const e of testEvents) {
+      if (e.eventType === 'test.passed') passed++;
+      else if (e.eventType === 'test.failed') {
+        failed++;
+        failures.push({
+          eventId: e.eventId,
+          testName: e.metadata?.testName || e.message,
+          reason: e.message,
+          timestamp: e.timestamp
+        });
+      }
+      else if (e.eventType === 'test.skipped') skipped++;
+    }
+
+    const total = passed + failed + skipped;
+    return {
+      totalTests: total,
+      passed,
+      failed,
+      skipped,
+      passRate: total > 0 ? Math.round((passed / total) * 10000) / 100 : 0,
+      failures
+    };
+  }
+
+  /**
+   * 分析 Repair 事件 → 返回 repair 视图
+   * @param {object[]} events
+   * @returns {object}
+   */
+  analyzeRepairResults(events) {
+    const repairEvents = (events || []).filter(e => REPAIR_EVENT_TYPES.includes(e.eventType));
+    let totalRepairs = 0;
+    let successful = 0;
+    let failed = 0;
+    const repairs = [];
+    const byRunId = new Map();
+
+    for (const e of repairEvents) {
+      const runId = e.runId || 'unknown';
+      if (!byRunId.has(runId)) {
+        byRunId.set(runId, { attempts: 0, finalStatus: 'unknown', reason: null });
+      }
+      const run = byRunId.get(runId);
+
+      if (e.eventType === 'repair.attempt') run.attempts++;
+      if (e.eventType === 'repair.success') run.finalStatus = 'success';
+      if (e.eventType === 'repair.failed') {
+        run.finalStatus = 'failed';
+        run.reason = e.message;
+      }
+    }
+
+    for (const [runId, run] of byRunId) {
+      totalRepairs++;
+      if (run.finalStatus === 'success') successful++;
+      else failed++;
+
+      repairs.push({
+        runId,
+        attempts: run.attempts,
+        finalStatus: run.finalStatus,
+        reason: run.reason
+      });
+    }
+
+    const totalAttempts = repairs.reduce((sum, r) => sum + r.attempts, 0);
+    return {
+      totalRepairs,
+      successful,
+      failed,
+      avgAttempts: totalRepairs > 0 ? Math.round((totalAttempts / totalRepairs) * 100) / 100 : 0,
+      repairs
+    };
+  }
+
+  /**
+   * 失败摘要：失败原因分类 + 修复次数统计
+   * @param {object[]} events
+   * @returns {object}
+   */
+  getFailureSummary(events) {
+    const all = events || [];
+    const failures = all.filter(e => e.status === 'failed' || e.status === 'blocked');
+
+    const byReason = {};
+    const byStage = {};
+
+    for (const e of failures) {
+      const reason = e.message || e.eventType || 'unknown';
+      byReason[reason] = (byReason[reason] || 0) + 1;
+      const stage = e.stage || 'unknown';
+      byStage[stage] = (byStage[stage] || 0) + 1;
+    }
+
+    // 最高频失败原因
+    let topFailureReason = null;
+    let maxCount = 0;
+    for (const [reason, count] of Object.entries(byReason)) {
+      if (count > maxCount) {
+        maxCount = count;
+        topFailureReason = reason;
+      }
+    }
+
+    // 修复成功率
+    const repairEvents = all.filter(e => REPAIR_EVENT_TYPES.includes(e.eventType));
+    const repairSuccesses = repairEvents.filter(e => e.eventType === 'repair.success').length;
+    const repairTotal = repairEvents.filter(e => e.eventType === 'repair.success' || e.eventType === 'repair.failed').length;
+
+    return {
+      totalFailures: failures.length,
+      byReason,
+      byStage,
+      topFailureReason,
+      repairSuccessRate: repairTotal > 0 ? Math.round((repairSuccesses / repairTotal) * 10000) / 100 : 0
+    };
+  }
+}
+
+/**
+ * 工厂函数
+ * @param {object} [options]
+ * @returns {HookDashboard}
+ */
+function createHookDashboard(options = {}) {
+  return new HookDashboard(options);
+}
+
+module.exports = {
+  HOOK_EVENT_TYPES,
+  TEST_EVENT_TYPES,
+  REPAIR_EVENT_TYPES,
+  HookDashboard,
+  createHookDashboard
+};

package/src/visual/index.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const visualConfig = require('./visual-config');
+const visualClient = require('./visual-client');
+const visualReporter = require('./visual-reporter');
+const eventMapper = require('./event-mapper');
+const privacyFilter = require('./privacy-filter');
+const eventGateway = require('./event-gateway');
+const timeline = require('./timeline');
+const hookDashboard = require('./hook-dashboard');
+const agentVisual = require('./agent-visual');
+const metrics = require('./metrics');
+const riskBoard = require('./risk-board');
+
+module.exports = {
+  ...visualConfig,
+  ...visualClient,
+  ...visualReporter,
+  ...eventMapper,
+  ...privacyFilter,
+  ...eventGateway,
+  ...timeline,
+  ...hookDashboard,
+  ...agentVisual,
+  ...metrics,
+  ...riskBoard
+};

package/src/visual/metrics.js

@@ -0,0 +1,287 @@
+'use strict';
+
+/**
+ * MetricsEngine — 质量指标与趋势分析
+ * 统计任务成功率、首次通过率、修复成功率、Hook 失败率、Rule 命中率
+ */
+
+const VALID_WINDOWS = ['daily', 'weekly'];
+
+class MetricsEngine {
+  constructor(options = {}) {
+    this._metrics = null;
+    this._computedAt = null;
+    this._totalRuns = 0;
+    this._totalEvents = 0;
+  }
+
+  /**
+   * 从全量事件计算指标
+   * @param {object[]} allEvents
+   * @returns {object}
+   */
+  compute(allEvents) {
+    if (!Array.isArray(allEvents) || allEvents.length === 0) {
+      this._metrics = {
+        taskSuccessRate: 0,
+        firstPassRate: 0,
+        repairSuccessRate: 0,
+        hookFailureRate: 0,
+        ruleHitRate: 0,
+        computedAt: new Date().toISOString(),
+        totalRuns: 0,
+        totalEvents: 0
+      };
+      this._computedAt = this._metrics.computedAt;
+      this._totalRuns = 0;
+      this._totalEvents = 0;
+      return this._metrics;
+    }
+
+    this._totalEvents = allEvents.length;
+
+    // 按 runId 分组
+    const runs = new Map();
+    for (const e of allEvents) {
+      const runId = e.runId || 'unknown';
+      if (!runs.has(runId)) runs.set(runId, []);
+      runs.get(runId).push(e);
+    }
+    this._totalRuns = runs.size;
+
+    // 任务成功率：最终状态为 success 的 run 占比
+    let successRuns = 0;
+    for (const [, events] of runs) {
+      const lastEvent = events[events.length - 1];
+      if (lastEvent.status === 'success') successRuns++;
+    }
+    const taskSuccessRate = runs.size > 0
+      ? Math.round((successRuns / runs.size) * 10000) / 10000
+      : 0;
+
+    // 首次通过率：无 repair 事件直接成功的 run 占比
+    let firstPassRuns = 0;
+    for (const [runId, events] of runs) {
+      const hasRepair = events.some(e =>
+        e.eventType === 'repair.attempt' ||
+        e.eventType === 'repair.success' ||
+        e.eventType === 'repair.failed'
+      );
+      const lastEvent = events[events.length - 1];
+      if (!hasRepair && lastEvent.status === 'success') firstPassRuns++;
+    }
+    const firstPassRate = runs.size > 0
+      ? Math.round((firstPassRuns / runs.size) * 10000) / 10000
+      : 0;
+
+    // 修复成功率：有 repair 事件最终成功的 run 占比
+    let repairRuns = 0;
+    let repairSuccessRuns = 0;
+    for (const [, events] of runs) {
+      const hasRepair = events.some(e =>
+        e.eventType === 'repair.attempt' ||
+        e.eventType === 'repair.success' ||
+        e.eventType === 'repair.failed'
+      );
+      if (hasRepair) {
+        repairRuns++;
+        const lastEvent = events[events.length - 1];
+        if (lastEvent.status === 'success') repairSuccessRuns++;
+      }
+    }
+    const repairSuccessRate = repairRuns > 0
+      ? Math.round((repairSuccessRuns / repairRuns) * 10000) / 10000
+      : 0;
+
+    // Hook 失败率：hook.failed 事件占总 hook 事件比例
+    const hookEvents = allEvents.filter(e =>
+      e.eventType === 'hook.passed' ||
+      e.eventType === 'hook.failed' ||
+      e.eventType === 'hook.skipped'
+    );
+    const hookFailures = hookEvents.filter(e => e.eventType === 'hook.failed');
+    const hookFailureRate = hookEvents.length > 0
+      ? Math.round((hookFailures.length / hookEvents.length) * 10000) / 10000
+      : 0;
+
+    // Rule 命中率：policy_denied 事件占总事件比例
+    const policyDenied = allEvents.filter(e => e.eventType === 'policy_denied');
+    const ruleHitRate = allEvents.length > 0
+      ? Math.round((policyDenied.length / allEvents.length) * 10000) / 10000
+      : 0;
+
+    this._metrics = {
+      taskSuccessRate,
+      firstPassRate,
+      repairSuccessRate,
+      hookFailureRate,
+      ruleHitRate,
+      computedAt: new Date().toISOString(),
+      totalRuns: runs.size,
+      totalEvents: allEvents.length
+    };
+    this._computedAt = this._metrics.computedAt;
+
+    return this._metrics;
+  }
+
+  getTaskSuccessRate() {
+    return this._metrics?.taskSuccessRate ?? 0;
+  }
+
+  getFirstPassRate() {
+    return this._metrics?.firstPassRate ?? 0;
+  }
+
+  getRepairSuccessRate() {
+    return this._metrics?.repairSuccessRate ?? 0;
+  }
+
+  getHookFailureRate() {
+    return this._metrics?.hookFailureRate ?? 0;
+  }
+
+  getRuleHitRate() {
+    return this._metrics?.ruleHitRate ?? 0;
+  }
+
+  /**
+   * 趋势：按时间窗口聚合
+   * @param {string} metricName
+   * @param {string} window — 'daily' | 'weekly'
+   * @param {object[]} allEvents
+   * @returns {object}
+   */
+  getTrend(metricName, window, allEvents) {
+    if (!VALID_WINDOWS.includes(window)) {
+      return { metricName, window, dataPoints: [], error: `非法 window: ${window}` };
+    }
+    if (!Array.isArray(allEvents) || allEvents.length === 0) {
+      return { metricName, window, dataPoints: [] };
+    }
+
+    // 按时间窗口分桶
+    const buckets = new Map();
+    for (const e of allEvents) {
+      if (!e.timestamp) continue;
+      const d = new Date(e.timestamp);
+      if (isNaN(d.getTime())) continue;
+
+      let key;
+      if (window === 'daily') {
+        key = d.toISOString().slice(0, 10);
+      } else {
+        // weekly: ISO 周一所在日期
+        const day = d.getUTCDay();
+        const diff = day === 0 ? 6 : day - 1;
+        const monday = new Date(d);
+        monday.setUTCDate(d.getUTCDate() - diff);
+        key = monday.toISOString().slice(0, 10);
+      }
+
+      if (!buckets.has(key)) buckets.set(key, []);
+      buckets.get(key).push(e);
+    }
+
+    // 每个桶计算指标
+    const sortedKeys = Array.from(buckets.keys()).sort();
+    const dataPoints = sortedKeys.map(period => {
+      const events = buckets.get(period);
+      const value = this._computeMetric(metricName, events);
+      return { period, value, sampleSize: events.length };
+    });
+
+    return { metricName, window, dataPoints };
+  }
+
+  /**
+   * 在单个桶内计算指定指标
+   * @param {string} metricName
+   * @param {object[]} events
+   * @returns {number}
+   */
+  _computeMetric(metricName, events) {
+    const runs = new Map();
+    for (const e of events) {
+      const runId = e.runId || 'unknown';
+      if (!runs.has(runId)) runs.set(runId, []);
+      runs.get(runId).push(e);
+    }
+
+    switch (metricName) {
+      case 'taskSuccessRate': {
+        let success = 0;
+        for (const [, evts] of runs) {
+          if (evts[evts.length - 1].status === 'success') success++;
+        }
+        return runs.size > 0 ? Math.round((success / runs.size) * 10000) / 10000 : 0;
+      }
+      case 'firstPassRate': {
+        let firstPass = 0;
+        for (const [, evts] of runs) {
+          const hasRepair = evts.some(e =>
+            e.eventType === 'repair.attempt' ||
+            e.eventType === 'repair.success' ||
+            e.eventType === 'repair.failed'
+          );
+          if (!hasRepair && evts[evts.length - 1].status === 'success') firstPass++;
+        }
+        return runs.size > 0 ? Math.round((firstPass / runs.size) * 10000) / 10000 : 0;
+      }
+      case 'repairSuccessRate': {
+        let repairRuns = 0;
+        let repairSuccess = 0;
+        for (const [, evts] of runs) {
+          const hasRepair = evts.some(e =>
+            e.eventType === 'repair.attempt' ||
+            e.eventType === 'repair.success' ||
+            e.eventType === 'repair.failed'
+          );
+          if (hasRepair) {
+            repairRuns++;
+            if (evts[evts.length - 1].status === 'success') repairSuccess++;
+          }
+        }
+        return repairRuns > 0 ? Math.round((repairSuccess / repairRuns) * 10000) / 10000 : 0;
+      }
+      case 'hookFailureRate': {
+        const hookEvents = events.filter(e =>
+          e.eventType === 'hook.passed' ||
+          e.eventType === 'hook.failed' ||
+          e.eventType === 'hook.skipped'
+        );
+        const failures = hookEvents.filter(e => e.eventType === 'hook.failed');
+        return hookEvents.length > 0 ? Math.round((failures.length / hookEvents.length) * 10000) / 10000 : 0;
+      }
+      case 'ruleHitRate': {
+        const denied = events.filter(e => e.eventType === 'policy_denied');
+        return events.length > 0 ? Math.round((denied.length / events.length) * 10000) / 10000 : 0;
+      }
+      default:
+        return 0;
+    }
+  }
+
+  toJSON() {
+    return this._metrics || {
+      taskSuccessRate: 0,
+      firstPassRate: 0,
+      repairSuccessRate: 0,
+      hookFailureRate: 0,
+      ruleHitRate: 0,
+      computedAt: null,
+      totalRuns: 0,
+      totalEvents: 0
+    };
+  }
+}
+
+function createMetricsEngine(options) {
+  return new MetricsEngine(options);
+}
+
+module.exports = {
+  VALID_WINDOWS,
+  MetricsEngine,
+  createMetricsEngine
+};

package/src/visual/privacy-filter.js

@@ -0,0 +1,100 @@
+const path = require('path');
+
+const FORBIDDEN_KEYS = new Set([
+  'sourceCode',
+  'sourceContent',
+  'fileContent',
+  'rawPrompt',
+  'rawResponse',
+  'absolutePath',
+  'userName',
+  'apiKey',
+  'password',
+  'token',
+  'secret',
+]);
+
+const SECRET_TEXT_RE = /(^|\b)(api[_-]?key|password|token|secret)\s*[:=]/i;
+const ENV_TEXT_RE = /(^|\n)\s*[A-Z0-9_]{3,}\s*=\s*.+/;
+
+class PrivacyPolicyError extends Error {
+  constructor(message = '上报数据包含不允许采集的敏感字段。') {
+    super(message);
+    this.name = 'PrivacyPolicyError';
+    this.code = 'PRIVACY_POLICY_VIOLATED';
+    this.suggestion = '请移除源码、原始提示词、原始响应、绝对路径或密钥信息后重试。';
+  }
+}
+
+function isAbsolutePathText(value) {
+  const text = String(value || '');
+  return path.isAbsolute(text) || /^[A-Za-z]:[\\/]/.test(text) || text.includes('/Users/');
+}
+
+function createPrivacy() {
+  return {
+    sourceCodeIncluded: false,
+    rawPromptIncluded: false,
+    rawResponseIncluded: false,
+    absolutePathIncluded: false,
+  };
+}
+
+function visit(value, fieldPath = '') {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => visit(item, `${fieldPath}[${index}]`));
+    return;
+  }
+  if (!value || typeof value !== 'object') {
+    if (typeof value === 'string') {
+      if (isAbsolutePathText(value) || SECRET_TEXT_RE.test(value) || ENV_TEXT_RE.test(value) || value.includes('.env')) {
+        throw new PrivacyPolicyError(`上报字段 ${fieldPath || '<root>'} 包含敏感内容。`);
+      }
+    }
+    return;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    if (FORBIDDEN_KEYS.has(key)) {
+      throw new PrivacyPolicyError(`上报数据不允许包含 ${key}。`);
+    }
+    visit(child, fieldPath ? `${fieldPath}.${key}` : key);
+  }
+}
+
+class PrivacyFilter {
+  filter(payload = {}) {
+    const next = {
+      ...payload,
+      privacy: createPrivacy(),
+    };
+    this.assertSafe(next);
+    return next;
+  }
+
+  assertSafe(payload = {}) {
+    if (payload.privacy && typeof payload.privacy === 'object') {
+      const flags = payload.privacy;
+      if (flags.sourceCodeIncluded || flags.rawPromptIncluded || flags.rawResponseIncluded || flags.absolutePathIncluded) {
+        throw new PrivacyPolicyError();
+      }
+    }
+    visit(payload);
+  }
+
+  assertRelativeChangedFiles(changedFiles = []) {
+    for (const file of changedFiles || []) {
+      if (!file || typeof file !== 'object') continue;
+      const filePath = String(file.path || '');
+      if (!filePath || isAbsolutePathText(filePath)) {
+        throw new PrivacyPolicyError('changedFiles 只能包含相对路径。');
+      }
+    }
+  }
+}
+
+module.exports = {
+  PrivacyFilter,
+  PrivacyPolicyError,
+  createPrivacy,
+  isAbsolutePathText,
+};