@gong-ym/ai-spec-auto 0.2.3

package/src/visual/risk-board.js

@@ -0,0 +1,252 @@
+'use strict';
+
+/**
+ * RiskBoard — 风险与审计看板
+ * 展示策略拒绝、安全风险、越权尝试、审计操作
+ */
+
+const POLICY_DENIAL_TYPES = ['policy_denied'];
+const SECURITY_RISK_TYPES = ['security.risk', 'security.violation', 'security.alert'];
+const PRIVILEGE_ESCALATION_TYPES = ['agent.tool_denied', 'agent.file_scope', 'agent.max_iterations'];
+const AUDIT_OPERATION_TYPES = ['audit.operation', 'audit.approval', 'audit.rollback'];
+
+const RISK_LEVELS = ['low', 'medium', 'high', 'critical'];
+
+const SEVERITY_TO_RISK_LEVEL = {
+  info: 'low',
+  warn: 'medium',
+  error: 'high',
+  blocking: 'critical',
+  low: 'low',
+  medium: 'medium',
+  high: 'high',
+  critical: 'critical'
+};
+
+const RISK_LEVEL_RANK = { low: 0, medium: 1, high: 2, critical: 3 };
+
+/**
+ * 将 severity 映射为 riskLevel
+ * @param {string} severity
+ * @returns {string}
+ */
+function mapSeverityToRiskLevel(severity) {
+  return SEVERITY_TO_RISK_LEVEL[severity] || 'low';
+}
+
+/**
+ * 获取 riskLevel 排序权重
+ * @param {string} riskLevel
+ * @returns {number}
+ */
+function getRiskLevelRank(riskLevel) {
+  return RISK_LEVEL_RANK[riskLevel] ?? 0;
+}
+
+class RiskBoard {
+  constructor(options = {}) {
+    this._events = [];
+  }
+
+  /**
+   * 导入事件进行分析
+   * @param {object[]} events
+   */
+  ingestEvents(events) {
+    if (!Array.isArray(events)) return;
+    this._events = events;
+  }
+
+  /**
+   * 获取策略拒绝列表
+   * @returns {object[]}
+   */
+  getPolicyDenials() {
+    return this._events
+      .filter(e => POLICY_DENIAL_TYPES.includes(e.eventType))
+      .map(e => ({
+        eventId: e.eventId,
+        message: e.message,
+        severity: e.severity,
+        timestamp: e.timestamp,
+        metadata: e.metadata
+      }));
+  }
+
+  /**
+   * 获取安全风险列表
+   * @returns {object[]}
+   */
+  getSecurityRisks() {
+    return this._events
+      .filter(e => SECURITY_RISK_TYPES.includes(e.eventType))
+      .map(e => ({
+        eventId: e.eventId,
+        type: e.eventType,
+        message: e.message,
+        severity: e.severity,
+        timestamp: e.timestamp,
+        metadata: e.metadata
+      }));
+  }
+
+  /**
+   * 获取越权尝试列表
+   * @returns {object[]}
+   */
+  getPrivilegeEscalations() {
+    return this._events
+      .filter(e => PRIVILEGE_ESCALATION_TYPES.includes(e.eventType))
+      .map(e => ({
+        eventId: e.eventId,
+        type: e.eventType.replace('agent.', ''),
+        agentId: e.metadata?.agentId || 'unknown',
+        message: e.message,
+        severity: e.severity,
+        timestamp: e.timestamp
+      }));
+  }
+
+  /**
+   * 获取审计操作列表
+   * @returns {object[]}
+   */
+  getAuditOperations() {
+    return this._events
+      .filter(e => AUDIT_OPERATION_TYPES.includes(e.eventType))
+      .map(e => ({
+        eventId: e.eventId,
+        type: e.eventType,
+        message: e.message,
+        severity: e.severity,
+        timestamp: e.timestamp,
+        metadata: e.metadata
+      }));
+  }
+
+  /**
+   * 风险摘要
+   * @returns {object}
+   */
+  getRiskSummary() {
+    const denials = this.getPolicyDenials();
+    const risks = this.getSecurityRisks();
+    const escalations = this.getPrivilegeEscalations();
+    const audits = this.getAuditOperations();
+
+    // 风险等级判定
+    const riskLevel = this._computeRiskLevel(denials, risks, escalations);
+
+    // 顶级风险
+    const topRisks = this._computeTopRisks(denials, risks, escalations);
+
+    return {
+      totalPolicyDenials: denials.length,
+      totalSecurityRisks: risks.length,
+      totalPrivilegeEscalations: escalations.length,
+      totalAuditOperations: audits.length,
+      riskLevel,
+      topRisks,
+      computedAt: new Date().toISOString()
+    };
+  }
+
+  /**
+   * 计算风险等级
+   * - critical: 有 blocking 级别的安全事件
+   * - high: 有 error 级别的安全事件或 >5 次策略拒绝
+   * - medium: 有 warn 级别的安全事件
+   * - low: 无安全事件
+   */
+  _computeRiskLevel(denials, risks, escalations) {
+    const allSecurity = [...risks, ...escalations];
+
+    // blocking → critical
+    if (allSecurity.some(e => e.severity === 'blocking')) {
+      return 'critical';
+    }
+
+    // error 或 >5 次拒绝 → high
+    if (allSecurity.some(e => e.severity === 'error') || denials.length > 5) {
+      return 'high';
+    }
+
+    // warn → medium
+    if (allSecurity.some(e => e.severity === 'warn')) {
+      return 'medium';
+    }
+
+    return 'low';
+  }
+
+  /**
+   * 计算顶级风险
+   */
+  _computeTopRisks(denials, risks, escalations) {
+    const riskMap = new Map();
+
+    const addRisk = (type, count, severity) => {
+      if (count > 0) {
+        const riskLevel = mapSeverityToRiskLevel(severity);
+        riskMap.set(type, { type, count, severity, riskLevel });
+      }
+    };
+
+    addRisk('policy_denied', denials.length, denials.length > 5 ? 'error' : 'warn');
+    addRisk('security_risk', risks.length, risks.length > 0 ? risks[0].severity : 'info');
+    addRisk('privilege_escalation', escalations.length, escalations.length > 0 ? escalations[0].severity : 'info');
+
+    return Array.from(riskMap.values()).sort((a, b) => {
+      return getRiskLevelRank(b.riskLevel) - getRiskLevelRank(a.riskLevel);
+    });
+  }
+
+  /**
+   * 多维过滤
+   * @param {object} [filters]
+   * @param {string} [filters.severity]
+   * @param {string} [filters.type]
+   * @param {string} [filters.from]
+   * @param {string} [filters.to]
+   * @returns {object[]}
+   */
+  filter(filters = {}) {
+    let results = [...this._events];
+
+    if (filters.severity) {
+      results = results.filter(e => e.severity === filters.severity);
+    }
+    if (filters.type) {
+      results = results.filter(e =>
+        e.eventType === filters.type ||
+        e.eventType.startsWith(filters.type + '.')
+      );
+    }
+    if (filters.from) {
+      results = results.filter(e => e.timestamp >= filters.from);
+    }
+    if (filters.to) {
+      results = results.filter(e => e.timestamp <= filters.to);
+    }
+
+    return results;
+  }
+}
+
+function createRiskBoard(options) {
+  return new RiskBoard(options);
+}
+
+module.exports = {
+  POLICY_DENIAL_TYPES,
+  SECURITY_RISK_TYPES,
+  PRIVILEGE_ESCALATION_TYPES,
+  AUDIT_OPERATION_TYPES,
+  RISK_LEVELS,
+  SEVERITY_TO_RISK_LEVEL,
+  RISK_LEVEL_RANK,
+  mapSeverityToRiskLevel,
+  getRiskLevelRank,
+  RiskBoard,
+  createRiskBoard
+};

package/src/visual/timeline.js

@@ -0,0 +1,245 @@
+'use strict';
+
+/**
+ * RunTimeline — 单次 Run 的时间线聚合与展示
+ * 从事件列表聚合出阶段时间线，支持按阶段/事件类型分组、摘要生成
+ */
+
+const STAGE_ORDER = [
+  'pre-task', 'pre-edit', 'post-edit', 'pre-test', 'post-test', 'repair', 'archive'
+];
+
+const SEVERITY_RANK = { info: 0, warn: 1, error: 2, blocking: 3 };
+const STATUS_SEVERITY = {
+  success: 'info',
+  skipped: 'info',
+  failed: 'error',
+  blocked: 'blocking'
+};
+
+/**
+ * 取阶段内最严重的状态
+ * @param {object[]} events
+ * @returns {string}
+ */
+function resolveStageStatus(events) {
+  let worst = 'success';
+  let worstRank = -1;
+  for (const e of events) {
+    const sev = e.severity || STATUS_SEVERITY[e.status] || 'info';
+    const rank = SEVERITY_RANK[sev] ?? 0;
+    if (rank > worstRank) {
+      worstRank = rank;
+      worst = e.status || 'success';
+    }
+  }
+  return worst;
+}
+
+/**
+ * 提取失败原因
+ * @param {object[]} events
+ * @returns {string|null}
+ */
+function extractFailureReason(events) {
+  const failed = events.filter(e => e.status === 'failed' || e.status === 'blocked');
+  if (failed.length === 0) return null;
+  return failed[failed.length - 1].message || failed[failed.length - 1].eventType;
+}
+
+class RunTimeline {
+  constructor(options = {}) {
+    this._runId = options.runId || '';
+    this._stages = [];
+    this._totalDurationMs = 0;
+    this._totalEvents = 0;
+    this._failureCount = 0;
+    this._groupedByType = {};
+  }
+
+  /**
+   * 固定阶段排序列表
+   * @returns {string[]}
+   */
+  getStageOrder() {
+    return [...STAGE_ORDER];
+  }
+
+  /**
+   * 按阶段分组
+   * @param {object[]} events
+   * @returns {Map<string, object[]>}
+   */
+  groupByStage(events) {
+    const map = new Map();
+    for (const stage of STAGE_ORDER) {
+      map.set(stage, []);
+    }
+    for (const e of events) {
+      const stage = e.stage || 'pre-task';
+      if (!map.has(stage)) map.set(stage, []);
+      map.get(stage).push(e);
+    }
+    return map;
+  }
+
+  /**
+   * 按事件类型分组
+   * @param {object[]} events
+   * @returns {Map<string, object[]>}
+   */
+  groupByEventType(events) {
+    const map = new Map();
+    for (const e of events) {
+      const type = e.eventType || 'unknown';
+      if (!map.has(type)) map.set(type, []);
+      map.get(type).push(e);
+    }
+    return map;
+  }
+
+  /**
+   * 获取某阶段详情
+   * @param {string} stageName
+   * @returns {object|null}
+   */
+  getStageDetail(stageName) {
+    return this._stages.find(s => s.name === stageName) || null;
+  }
+
+  /**
+   * 从事件列表聚合出时间线
+   * @param {object[]} events
+   * @returns {object}
+   */
+  aggregate(events) {
+    if (!Array.isArray(events) || events.length === 0) {
+      this._stages = [];
+      this._totalDurationMs = 0;
+      this._totalEvents = 0;
+      this._failureCount = 0;
+      this._groupedByType = {};
+      return this.toJSON();
+    }
+
+    // 推断 runId
+    if (!this._runId && events[0].runId) {
+      this._runId = events[0].runId;
+    }
+
+    const grouped = this.groupByStage(events);
+    const typeGrouped = this.groupByEventType(events);
+    this._groupedByType = {};
+    for (const [type, evts] of typeGrouped) {
+      this._groupedByType[type] = evts;
+    }
+
+    const stages = [];
+    let totalDurationMs = 0;
+    let failureCount = 0;
+
+    for (const stageName of STAGE_ORDER) {
+      const stageEvents = grouped.get(stageName) || [];
+      if (stageEvents.length === 0) continue;
+
+      const timestamps = stageEvents
+        .map(e => e.timestamp ? new Date(e.timestamp).getTime() : 0)
+        .filter(t => t > 0)
+        .sort((a, b) => a - b);
+
+      const startedAt = timestamps.length > 0 ? new Date(timestamps[0]).toISOString() : null;
+      const completedAt = timestamps.length > 0 ? new Date(timestamps[timestamps.length - 1]).toISOString() : null;
+      const durationMs = timestamps.length > 1
+        ? timestamps[timestamps.length - 1] - timestamps[0]
+        : 0;
+
+      const status = resolveStageStatus(stageEvents);
+      const failureReason = extractFailureReason(stageEvents);
+
+      if (status === 'failed' || status === 'blocked') {
+        failureCount++;
+      }
+
+      stages.push({
+        name: stageName,
+        status,
+        events: stageEvents,
+        startedAt,
+        completedAt,
+        durationMs,
+        failureReason
+      });
+
+      totalDurationMs += durationMs;
+    }
+
+    this._stages = stages;
+    this._totalDurationMs = totalDurationMs;
+    this._totalEvents = events.length;
+    this._failureCount = failureCount;
+
+    return this.toJSON();
+  }
+
+  /**
+   * 摘要
+   * @returns {object}
+   */
+  getSummary() {
+    return {
+      runId: this._runId,
+      totalEvents: this._totalEvents,
+      totalDurationMs: this._totalDurationMs,
+      failureCount: this._failureCount,
+      stageCount: this._stages.length,
+      stages: this._stages.map(s => ({
+        name: s.name,
+        status: s.status,
+        eventCount: s.events.length,
+        durationMs: s.durationMs,
+        failureReason: s.failureReason
+      }))
+    };
+  }
+
+  /**
+   * 序列化（剥离 events 详情，只保留数量）
+   * @returns {object}
+   */
+  toJSON() {
+    return {
+      runId: this._runId,
+      stages: this._stages.map(s => ({
+        name: s.name,
+        status: s.status,
+        eventCount: s.events.length,
+        startedAt: s.startedAt,
+        completedAt: s.completedAt,
+        durationMs: s.durationMs,
+        failureReason: s.failureReason
+      })),
+      totalDurationMs: this._totalDurationMs,
+      totalEvents: this._totalEvents,
+      failureCount: this._failureCount
+    };
+  }
+}
+
+/**
+ * 工厂函数
+ * @param {object} [options]
+ * @returns {RunTimeline}
+ */
+function createTimeline(options) {
+  return new RunTimeline(options);
+}
+
+module.exports = {
+  STAGE_ORDER,
+  SEVERITY_RANK,
+  STATUS_SEVERITY,
+  resolveStageStatus,
+  extractFailureReason,
+  RunTimeline,
+  createTimeline
+};

package/src/visual/visual-client.js

@@ -0,0 +1,94 @@
+const { URL } = require('url');
+const { PrivacyFilter } = require('./privacy-filter');
+
+class VisualClientError extends Error {
+  constructor(code, message, suggestion, details = {}) {
+    super(message);
+    this.name = 'VisualClientError';
+    this.code = code;
+    this.suggestion = suggestion || '';
+    this.details = details;
+  }
+}
+
+function joinVisualUrl(visualUrl, endpoint) {
+  if (!visualUrl) return endpoint;
+  if (/^https?:\/\//i.test(endpoint)) return endpoint;
+  return `${String(visualUrl).replace(/\/+$/, '')}/${String(endpoint).replace(/^\/+/, '')}`;
+}
+
+async function parseVisualResponse(response) {
+  let body;
+  try {
+    body = await response.json();
+  } catch (error) {
+    throw new VisualClientError('VISUAL_RESPONSE_INVALID', 'Visual 返回不是合法 JSON', '请检查 Collector API 响应格式。', { error: error.message });
+  }
+  if (!response.ok || body?.success === false) {
+    const visualError = body?.error || {};
+    throw new VisualClientError(
+      visualError.code || `HTTP_${response.status}`,
+      visualError.message || `Visual 请求失败：HTTP ${response.status}`,
+      visualError.suggestion || '请检查 engineered-spec-visual 服务状态。',
+      { status: response.status },
+    );
+  }
+  if (body && Object.prototype.hasOwnProperty.call(body, 'success')) {
+    return body.data;
+  }
+  return body;
+}
+
+class VisualClient {
+  constructor(options = {}) {
+    this.visualUrl = options.visualUrl || '';
+    this.privacyFilter = options.privacyFilter || new PrivacyFilter();
+  }
+
+  resolveVisualUrl(inputVisualUrl) {
+    return String(inputVisualUrl || this.visualUrl || '').replace(/\/+$/, '');
+  }
+
+  async post(endpoint, payload, options = {}) {
+    const visualUrl = this.resolveVisualUrl(options.visualUrl || payload.visualUrl);
+    if (!visualUrl) {
+      throw new VisualClientError('VISUAL_URL_MISSING', '未配置 Visual URL，无法上报运行态数据', '请传入 --visual-url 或配置 AI_SPEC_VISUAL_URL。');
+    }
+    const safePayload = this.privacyFilter.filter(payload);
+    const url = new URL(joinVisualUrl(visualUrl, endpoint));
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(safePayload),
+      });
+      return await parseVisualResponse(response);
+    } catch (error) {
+      if (error instanceof VisualClientError) throw error;
+      throw new VisualClientError('VISUAL_NETWORK_ERROR', `Visual 网络请求失败：${error.message}`, '请检查 Visual URL、网络或服务是否启动。');
+    }
+  }
+
+  async sendProjectState(payload, options = {}) {
+    return this.post('/api/collector/project-state', payload, options);
+  }
+
+  async sendRunEvent(payload, options = {}) {
+    return this.post('/api/collector/run-event', payload, options);
+  }
+
+  async sendHistory(payload, options = {}) {
+    this.privacyFilter.assertRelativeChangedFiles(payload.changedFiles || []);
+    return this.post('/api/collector/history', payload, options);
+  }
+
+  async sendIncident(payload, options = {}) {
+    return this.post('/api/collector/incident', payload, options);
+  }
+}
+
+module.exports = {
+  VisualClient,
+  VisualClientError,
+  joinVisualUrl,
+};

package/src/visual/visual-config.js

@@ -0,0 +1,40 @@
+const { readProjectState } = require('../project/project-files');
+
+function normalizeVisualUrl(value) {
+  const text = String(value || '').trim();
+  if (!text) return '';
+  return text.replace(/\/+$/, '');
+}
+
+function resolveVisualConfig(rootDir, options = {}) {
+  const state = rootDir ? readProjectState(rootDir) : {};
+  const policyVisual = state.policy?.visual || {};
+  const source = options.visualUrl ? 'cli' : policyVisual.url ? 'policy' : process.env.AI_SPEC_VISUAL_URL ? 'env' : 'empty';
+  const visualUrl = normalizeVisualUrl(
+    options.visualUrl ||
+      policyVisual.url ||
+      process.env.AI_SPEC_VISUAL_URL ||
+      '',
+  );
+  const enabled = options.visualEnabled !== undefined
+    ? Boolean(options.visualEnabled)
+    : source === 'cli' || source === 'env'
+      ? Boolean(visualUrl)
+      : source === 'policy'
+        ? policyVisual.enabled !== false
+        : false;
+
+  return {
+    enabled,
+    url: visualUrl,
+    nonBlocking: options.nonBlocking !== undefined
+      ? Boolean(options.nonBlocking)
+      : policyVisual.nonBlocking !== false,
+    source,
+  };
+}
+
+module.exports = {
+  normalizeVisualUrl,
+  resolveVisualConfig,
+};