@chongyan/autospec 1.0.1

package/plugins/hooks/lib/artifact-evaluator.js

@@ -0,0 +1,414 @@
+/**
+ * Artifact Evaluator - 产出物评测核心模块
+ *
+ * 提供产出物质量评测功能：
+ * - 结构完整性检查（自动化，100%执行）
+ * - 一致性检测（复用 consistency-checker）
+ * - 质量评估（AI，采样执行）
+ * - 下游反馈追踪
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { getState, getMetrics, updateMetrics } from './hook-state-manager.js';
+import { getTraceId, recordEvent } from './trace-context.js';
+
+/**
+ * 评测类型
+ */
+export const EVAL_TYPES = {
+  STRUCTURE: 'structure',      // 结构完整性
+  CONSISTENCY: 'consistency',  // 一致性检测
+  QUALITY: 'quality',          // 质量评估（AI）
+  FEEDBACK: 'feedback'         // 下游反馈
+};
+
+/**
+ * 产出物类型
+ */
+export const ARTIFACT_TYPES = {
+  REQUIREMENT: 'requirement.md',
+  DESIGN: 'design.md',
+  CODE: 'code',
+  REVIEW: 'review',
+  TEST: 'test',
+  EVALUATION: 'evaluation'
+};
+
+/**
+ * 各产出物的结构完整性检查规则
+ */
+export const STRUCTURE_RULES = {
+  'requirement.md': {
+    requiredSections: ['背景', '目标', '范围', '验收标准'],
+    minLength: 500,
+    patterns: [
+      { name: 'acceptanceCriteria', pattern: /验收标准|Acceptance/i, required: true },
+      { name: 'scope', pattern: /范围|Scope/i, required: true }
+    ],
+    noVagueWords: ['可能', '大概', '尽量', '适当', '也许']
+  },
+  'design.md': {
+    requiredSections: ['架构设计', '接口设计', '数据设计'],
+    minLength: 800,
+    patterns: [
+      { name: 'api', pattern: /API|接口|endpoint/i, required: true },
+      { name: 'requirementRef', pattern: /requirement|需求/i, required: false }
+    ]
+  },
+  'review-requirement.md': {
+    requiredSections: ['审查结论', '问题清单', '改进建议'],
+    minLength: 300
+  },
+  'review-design.md': {
+    requiredSections: ['审查结论', '问题清单', '改进建议'],
+    minLength: 300
+  },
+  'review-code.md': {
+    requiredSections: ['审查结论', '问题清单', '改进建议'],
+    minLength: 300
+  },
+  'consistency-report.md': {
+    requiredSections: ['检查结论', '一致性分析'],
+    minLength: 200
+  }
+};
+
+/**
+ * 产出物评测配置
+ */
+export const ARTIFACT_EVAL_CONFIG = {
+  'requirement.md': {
+    structure: { enabled: true, weight: 0.2 },
+    consistency: { enabled: false },  // 第一个产物，无需一致性检查
+    quality: { enabled: true, sampleRate: 0.3, weight: 0.5 },
+    feedback: { enabled: true, weight: 0.3 }
+  },
+  'design.md': {
+    structure: { enabled: true, weight: 0.15 },
+    consistency: { enabled: true, weight: 0.25 },
+    quality: { enabled: true, sampleRate: 0.3, weight: 0.4 },
+    feedback: { enabled: true, weight: 0.2 }
+  },
+  'review-code.md': {
+    structure: { enabled: true, weight: 0.15 },
+    consistency: { enabled: false },
+    quality: { enabled: true, sampleRate: 0.5, weight: 0.55 },
+    feedback: { enabled: true, weight: 0.3 }
+  }
+};
+
+/**
+ * 执行结构完整性检查
+ * @param {string} artifactPath - 产出物路径
+ * @param {string} artifactType - 产出物类型
+ * @returns {Object} 检查结果
+ */
+export function checkStructure(artifactPath, artifactType) {
+  const rules = STRUCTURE_RULES[artifactType];
+
+  if (!rules) {
+    return {
+      passed: true,
+      score: 100,
+      issues: [],
+      message: '无结构检查规则，默认通过'
+    };
+  }
+
+  const issues = [];
+  let score = 100;
+
+  // 检查文件是否存在
+  if (!fs.existsSync(artifactPath)) {
+    return {
+      passed: false,
+      score: 0,
+      issues: [{ type: 'file_not_found', message: `文件不存在: ${artifactPath}` }],
+      message: '文件不存在'
+    };
+  }
+
+  // 读取文件内容
+  const content = fs.readFileSync(artifactPath, 'utf-8');
+
+  // 检查最小长度
+  if (rules.minLength && content.length < rules.minLength) {
+    issues.push({
+      type: 'too_short',
+      message: `内容长度不足: ${content.length} < ${rules.minLength}`,
+      severity: 'medium'
+    });
+    score -= 10;
+  }
+
+  // 检查必要章节
+  if (rules.requiredSections) {
+    for (const section of rules.requiredSections) {
+      if (!content.includes(section)) {
+        issues.push({
+          type: 'missing_section',
+          message: `缺少必要章节: ${section}`,
+          severity: 'high'
+        });
+        score -= 15;
+      }
+    }
+  }
+
+  // 检查模式匹配
+  if (rules.patterns) {
+    for (const pattern of rules.patterns) {
+      const found = pattern.pattern.test(content);
+      if (pattern.required && !found) {
+        issues.push({
+          type: 'missing_pattern',
+          message: `缺少必要内容: ${pattern.name}`,
+          severity: 'medium'
+        });
+        score -= 10;
+      }
+    }
+  }
+
+  // 检查歧义词
+  if (rules.noVagueWords) {
+    for (const word of rules.noVagueWords) {
+      if (content.includes(word)) {
+        issues.push({
+          type: 'vague_word',
+          message: `发现歧义词: "${word}"`,
+          severity: 'low'
+        });
+        score -= 2;
+      }
+    }
+  }
+
+  return {
+    passed: score >= 60,
+    score: Math.max(0, score),
+    issues,
+    message: score >= 60 ? '结构检查通过' : '结构检查未通过'
+  };
+}
+
+/**
+ * 检测产出物类型
+ * @param {string} filePath - 文件路径
+ * @returns {string|null} 产出物类型
+ */
+export function detectArtifactType(filePath) {
+  const fileName = path.basename(filePath);
+
+  for (const [type, pattern] of Object.entries(ARTIFACT_TYPES)) {
+    if (fileName.includes(pattern) || fileName === pattern) {
+      return type;
+    }
+  }
+
+  // 检查路径模式
+  if (filePath.includes('requirement')) return 'REQUIREMENT';
+  if (filePath.includes('design')) return 'DESIGN';
+  if (filePath.includes('review-')) return 'REVIEW';
+  if (filePath.includes('test')) return 'TEST';
+
+  return null;
+}
+
+/**
+ * 判断是否为关键产出物
+ * @param {string} filePath - 文件路径
+ * @returns {boolean}
+ */
+export function isKeyArtifact(filePath) {
+  const keyPatterns = [
+    'requirement.md',
+    'design.md',
+    'review-requirement.md',
+    'review-design.md',
+    'review-code.md',
+    'consistency-report.md',
+    'evaluation-report.md'
+  ];
+
+  const fileName = path.basename(filePath);
+  return keyPatterns.some(p => fileName.includes(p));
+}
+
+/**
+ * 记录产出物评测结果
+ * @param {string} projectRoot - 项目根目录
+ * @param {string} artifactPath - 产出物路径
+ * @param {string} artifactType - 产出物类型
+ * @param {Object} evalResult - 评测结果
+ */
+export function recordArtifactEval(projectRoot, artifactPath, artifactType, evalResult) {
+  const metrics = getMetrics(projectRoot, false);
+
+  if (!metrics.artifacts) {
+    metrics.artifacts = {};
+  }
+
+  const artifactKey = path.basename(artifactPath);
+
+  if (!metrics.artifacts[artifactKey]) {
+    metrics.artifacts[artifactKey] = {
+      path: artifactPath,
+      type: artifactType,
+      evaluations: {},
+      overallScore: 0,
+      evaluatedAt: new Date().toISOString()
+    };
+  }
+
+  // 更新评测结果
+  metrics.artifacts[artifactKey].evaluations = {
+    ...metrics.artifacts[artifactKey].evaluations,
+    ...evalResult
+  };
+
+  // 更新时间戳
+  metrics.artifacts[artifactKey].evaluatedAt = new Date().toISOString();
+
+  // 记录到 trace 日志
+  const traceId = getTraceId(projectRoot);
+  if (traceId) {
+    recordEvent(projectRoot, 'artifact_evaluated', {
+      source: 'artifact-evaluator',
+       data: {
+        artifactPath,
+        artifactType,
+        evalType: Object.keys(evalResult)[0],
+        score: Object.values(evalResult)[0]?.score
+      }
+    });
+  }
+
+  updateMetrics(projectRoot, metrics);
+}
+
+/**
+ * 计算产出物综合评分
+ * @param {Object} evaluations - 评测结果
+ * @param {string} artifactType - 产出物类型
+ * @returns {number} 综合评分
+ */
+export function calculateArtifactScore(evaluations, artifactType) {
+  const config = ARTIFACT_EVAL_CONFIG[artifactType];
+  if (!config) {
+    // 默认权重
+    let totalScore = 0;
+    let totalWeight = 0;
+    for (const [type, result] of Object.entries(evaluations)) {
+      if (result && typeof result.score === 'number') {
+        totalScore += result.score;
+        totalWeight++;
+      }
+    }
+    return totalWeight > 0 ? Math.round(totalScore / totalWeight) : 0;
+  }
+
+  let weightedScore = 0;
+  let totalWeight = 0;
+
+  for (const [type, weight] of Object.entries(config)) {
+    if (weight.enabled && evaluations[type] && typeof evaluations[type].score === 'number') {
+      weightedScore += evaluations[type].score * weight.weight;
+      totalWeight += weight.weight;
+    }
+  }
+
+  return totalWeight > 0 ? Math.round(weightedScore / totalWeight * 100) : 0;
+}
+
+/**
+ * 更新产出物质量汇总
+ * @param {string} projectRoot - 项目根目录
+ */
+export function updateArtifactSummary(projectRoot) {
+  const metrics = getMetrics(projectRoot, false);
+  const artifacts = metrics.artifacts || {};
+
+  const scores = [];
+  const lowScoreArtifacts = [];
+  let consistencyIssues = 0;
+  let qualityEvalCount = 0;
+
+  for (const [key, artifact] of Object.entries(artifacts)) {
+    if (artifact.overallScore) {
+      scores.push(artifact.overallScore);
+    }
+
+    if (artifact.overallScore < 70) {
+      lowScoreArtifacts.push(key);
+    }
+
+    if (artifact.evaluations?.consistency?.gaps?.length > 0) {
+      consistencyIssues += artifact.evaluations.consistency.gaps.length;
+    }
+
+    if (artifact.evaluations?.quality) {
+      qualityEvalCount++;
+    }
+  }
+
+  metrics.artifactSummary = {
+    averageScore: scores.length > 0 ? Math.round(scores.reduce((a, b) => a + b, 0) / scores.length) : 0,
+    lowScoreArtifacts,
+    consistencyIssues,
+    qualityEvalCount
+  };
+
+  updateMetrics(projectRoot, metrics);
+}
+
+/**
+ * 检查是否应该执行 AI 质量评估
+ * @param {string} projectRoot - 项目根目录
+ * @param {string} artifactType - 产出物类型
+ * @returns {Object} { shouldEval: boolean, reason: string }
+ */
+export function shouldRunQualityEval(projectRoot, artifactType) {
+  const config = ARTIFACT_EVAL_CONFIG[artifactType];
+
+  if (!config?.quality?.enabled) {
+    return { shouldEval: false, reason: '该产出物类型未启用质量评估' };
+  }
+
+  const metrics = getMetrics(projectRoot, true);
+  const artifact = Object.values(metrics?.artifacts || {}).find(a => a.type === artifactType);
+
+  // 首次生成：必评
+  if (!artifact?.evaluations?.quality) {
+    return { shouldEval: true, reason: '首次生成，建立基线' };
+  }
+
+  // 低分产物：100% 重评
+  if (artifact.overallScore < 70) {
+    return { shouldEval: true, reason: '低分产出物，需要重评' };
+  }
+
+  // 采样评估
+  const sampleRate = config.quality.sampleRate || 0.3;
+  const shouldSample = Math.random() < sampleRate;
+
+  return {
+    shouldEval: shouldSample,
+    reason: shouldSample ? '采样评估' : '跳过采样'
+  };
+}
+
+export default {
+  EVAL_TYPES,
+  ARTIFACT_TYPES,
+  STRUCTURE_RULES,
+  ARTIFACT_EVAL_CONFIG,
+  checkStructure,
+  detectArtifactType,
+  isKeyArtifact,
+  recordArtifactEval,
+  calculateArtifactScore,
+  updateArtifactSummary,
+  shouldRunQualityEval
+};