@chongyan/autospec 1.0.1

package/plugins/hooks/README.md

@@ -0,0 +1,56 @@
+# Hooks 脚本目录
+
+本目录包含所有 Claude Code hooks 脚本，随 init 过程复制到 `.autospec/plugins/hooks/` 目录。
+
+## 目录结构
+
+```
+hooks/
+├── trace-initialization.js        # Trace ID 初始化
+├── frozen-zone-guard.js           # 冻结区保护
+├── scope-sentinel.js              # 范围防漂移
+├── constitution-guard.js          # 宪法门禁
+├── layer1-validator.js            # Layer 1 检查
+├── environment-manager.js         # 环境管理
+├── ai-project-guard.js            # AI 项目安全
+├── execution-tracker.js           # 执行追踪
+├── artifact-evaluation-hook.js    # 产出物评测
+├── pipeline-observer.js           # 流程观察
+├── lib/                           # 工具库
+│   ├── source-code-scanner.js
+│   ├── detection-pattern-loader.js
+│   ├── validation-patterns.js
+│   ├── hook-logger.js
+│   ├── hook-state-manager.js
+│   ├── trace-context.js
+│   ├── rollback-tracker.js
+│   ├── artifact-evaluator.js
+│   ├── execution-path.js
+│   └── metrics-analyzer.js
+└── README.md                      # 本文件
+```
+
+## Hook 触发时机
+
+| Hook | PreToolUse | PostToolUse | Stop |
+|------|------------|-------------|------|
+| trace-initialization | ✅ | | |
+| frozen-zone-guard | ✅ | | |
+| scope-sentinel | ✅ | | |
+| constitution-guard | ✅ | | |
+| layer1-validator | ✅ | ✅ | |
+| environment-manager | ✅ | | ✅ |
+| ai-project-guard | ✅ | ✅ | |
+| execution-tracker | | ✅ | |
+| artifact-evaluation-hook | | ✅ | |
+| pipeline-observer | | ✅ | ✅ |
+
+## 自闭环要求
+
+本目录中的脚本必须自闭环，满足以下要求：
+
+1. **只依赖 Node.js 内置模块**（fs, path 等）
+2. **只依赖 `./lib/` 本地工具库**
+3. **不依赖任何脚手架代码**
+
+这样确保复制到 `.autospec/plugins/hooks/` 后可以独立运行。

package/plugins/hooks/ai-project-guard.js

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+
+/**
+ * AutoSpec Hook: AI Project Guard
+ *
+ * AI 项目专项保护 Hook，合并了安全和效果验证功能：
+ * - PostToolUse: AI 安全检查（原 ai-security-guard.js）
+ * - PostToolUse: AI 效果验证（原 ai-effect-validator.js）
+ *
+ * 职责：
+ * 1. 检测 AI 项目（依赖/目录）
+ * 2. 安全检查：敏感操作、依赖安装、网络请求
+ * 3. 效果验证：测试/评估命令结果捕获
+ */
+
+import { createHookLogger, safeJsonParse, handleHookError, readStdin, findProjectRootAsync, fileExists, globalHookCache } from './lib/hook-logger.js';
+import {
+  checkCommandSecurity,
+  detectEvalCommands,
+  detectTestFramework,
+  extractTestMetrics,
+  extractLintMetrics,
+  extractTypeMetrics,
+} from './lib/validation-patterns.js';
+
+const logger = createHookLogger('ai-project-guard');
+const projectTypeCache = globalHookCache;
+
+// ========== AI 项目检测 ==========
+
+const AI_PROJECT_INDICATORS = [
+  'requirements.txt', 'pyproject.toml', 'Pipfile',
+  'ml/', 'ai/', 'model/', 'rag/', 'agents/', 'prompts/',
+  'embeddings/', 'vectorstore/'
+];
+
+const AI_DEPENDENCIES = [
+  'langchain', 'llamaindex', 'openai', 'anthropic',
+  'transformers', 'torch', 'tensorflow', 'huggingface',
+  'crewai', 'autogen', 'vanna'
+];
+
+const AI_DIRECTORIES = ['ml', 'ai', 'model', 'rag', 'agents', 'prompts', 'embeddings', 'vectorstore'];
+
+/**
+ * 快速检测是否为 AI 项目
+ */
+async function detectAIProject(projectRoot) {
+  // 检查 AI 相关依赖文件
+  const aiDependencyFiles = ['requirements.txt', 'pyproject.toml', 'Pipfile', 'package.json'];
+
+  for (const file of aiDependencyFiles) {
+    const filePath = `${projectRoot}/${file}`;
+    if (await fileExists(filePath)) {
+      try {
+        const fs = await import('fs');
+        const content = await fs.promises.readFile(filePath, 'utf-8');
+
+        if (AI_DEPENDENCIES.some(ind => content.toLowerCase().includes(ind))) {
+          logger.debug('AI dependency detected', { file });
+          return true;
+        }
+      } catch (err) {
+        logger.debug('Failed to read dependency file', { file, error: err.message });
+      }
+    }
+  }
+
+  // 检查 AI 相关目录
+  for (const dir of AI_DIRECTORIES) {
+    if (await fileExists(`${projectRoot}/${dir}`)) {
+      logger.debug('AI directory detected', { dir });
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * 检查项目类型（带缓存）
+ */
+async function checkProjectType(projectRoot) {
+  const cacheKey = `ai-project:${projectRoot}`;
+  let isAIProject = projectTypeCache.get(cacheKey);
+
+  if (isAIProject === undefined) {
+    isAIProject = await detectAIProject(projectRoot);
+    projectTypeCache.set(cacheKey, isAIProject, 5 * 60 * 1000);
+    logger.debug('Project type detected', { isAIProject, projectRoot });
+  } else {
+    logger.debug('Using cached project type', { isAIProject });
+  }
+
+  return isAIProject;
+}
+
+// ========== 安全检查 ==========
+// 使用 validation-patterns.js 中的 checkCommandSecurity 函数
+
+/**
+ * 格式化安全报告
+ */
+function formatSecurityReport(issues, command) {
+  let report = `[AutoSpec AI-Security] 检测到 ${issues.length} 个安全问题\n`;
+  report += `命令：${command.slice(0, 80)}${command.length > 80 ? '...' : ''}\n\n`;
+
+  const bySeverity = { HIGH: [], MEDIUM: [], LOW: [] };
+  for (const issue of issues) {
+    bySeverity[issue.severity].push(issue);
+  }
+
+  for (const severity of ['HIGH', 'MEDIUM', 'LOW']) {
+    if (bySeverity[severity].length > 0) {
+      const icons = { HIGH: '🚨', MEDIUM: '⚠️', LOW: 'ℹ️' };
+      report += `${icons[severity]} **${severity}** (${bySeverity[severity].length}个):\n`;
+      for (const issue of bySeverity[severity]) {
+        report += `  • ${issue.message}\n`;
+        report += `    建议：${issue.recommendation}\n`;
+      }
+      report += '\n';
+    }
+  }
+
+  return report;
+}
+
+/**
+ * 处理安全检查
+ */
+async function handleSecurityCheck(input, projectRoot) {
+  const command = input.tool_input?.command || '';
+  if (!command) {
+    logger.debug('Empty command, skipping');
+    return;
+  }
+
+  logger.debug('Checking AI project command', { command: command.slice(0, 100) });
+
+  const securityIssues = checkCommandSecurity(command, projectRoot);
+
+  if (securityIssues.length === 0) {
+    logger.debug('No security issues detected');
+    return;
+  }
+
+  logger.info('Security issues detected', { count: securityIssues.length });
+
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      additionalContext: formatSecurityReport(securityIssues, command)
+    }
+  };
+
+  process.stdout.write(JSON.stringify(output));
+}
+
+// ========== 效果验证 ==========
+// 使用 validation-patterns.js 中的检测函数
+
+/**
+ * 收集评估结果 - 使用公共模块的指标提取函数
+ */
+function collectEvalResults(evalCommands, response) {
+  const results = [];
+  const exitCode = response.exitCode ?? (response.error ? 1 : 0);
+  const stdout = response.stdout || '';
+  const stderr = response.stderr || '';
+
+  for (const cmd of evalCommands) {
+    const result = {
+      type: cmd.type,
+      framework: cmd.framework,
+      pass: exitCode === 0,
+      exitCode: exitCode,
+      details: extractDetails(stdout, stderr)
+    };
+
+    if (cmd.type === 'test') {
+      result.metrics = extractTestMetrics(stdout, stderr);
+    } else if (cmd.type === 'lint') {
+      result.metrics = extractLintMetrics(stdout, stderr);
+    } else if (cmd.type === 'type_check') {
+      result.metrics = extractTypeMetrics(stdout, stderr);
+    }
+
+    results.push(result);
+  }
+
+  return results;
+}
+
+/**
+ * 提取详细信息
+ */
+function extractDetails(stdout, stderr) {
+  const output = (stdout || '') + (stderr || '');
+  const lines = output.split('\n').filter(l => l.trim());
+  return lines.slice(-5).join('\n');
+}
+
+/**
+ * 格式化评估报告
+ */
+function formatEvalReport(results) {
+  let report = '[AutoSpec AI-Effect] AI 效果验证\n';
+  report += `检测到 ${results.length} 个评估命令\n\n`;
+
+  let allPass = true;
+  for (const result of results) {
+    const status = result.pass ? '✅ PASS' : '❌ FAIL';
+    report += `### ${result.type.toUpperCase()}: ${status}\n`;
+    report += `Exit Code: ${result.exitCode}\n`;
+
+    if (result.framework) {
+      report += `Framework: ${result.framework}\n`;
+    }
+
+    if (result.metrics && Object.keys(result.metrics).length > 0) {
+      report += '指标:\n';
+      for (const [key, value] of Object.entries(result.metrics)) {
+        report += `  - ${key}: ${value}\n`;
+      }
+    }
+
+    if (!result.pass && result.details) {
+      report += '失败详情:\n```\n';
+      report += result.details.substring(0, 500) + '\n```\n';
+    }
+
+    report += '\n';
+
+    if (!result.pass) allPass = false;
+  }
+
+  if (allPass && results.length > 0) {
+    report += '✅ 所有效果验证通过\n';
+    report += '可进入下一阶段或进行 Layer 2 审查\n';
+  } else if (results.length > 0) {
+    report += '❌ 效果验证未通过\n';
+    report += '[CP6] 错误即信号 - 请分析失败原因后再重试\n';
+  }
+
+  return report;
+}
+
+/**
+ * 处理效果验证
+ */
+async function handleEffectValidation(input, projectRoot) {
+  const command = input.tool_input?.command || '';
+  const response = input.tool_response || {};
+
+  const evalCommands = detectEvalCommands(command);
+
+  if (evalCommands.length === 0) {
+    logger.debug('No evaluation commands detected, skipping');
+    return;
+  }
+
+  logger.debug('Evaluation commands detected', { count: evalCommands.length });
+
+  const evalResults = collectEvalResults(evalCommands, response);
+
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      additionalContext: formatEvalReport(evalResults)
+    }
+  };
+
+  process.stdout.write(JSON.stringify(output));
+}
+
+/**
+ * 主函数
+ */
+async function main() {
+  let input;
+  try {
+    const rawInput = await readStdin(1000);
+    input = safeJsonParse(rawInput, null, 'hook input');
+
+    if (!input) {
+      logger.debug('Empty or invalid input, skipping');
+      process.exit(0);
+    }
+  } catch (err) {
+    logger.error('Failed to parse input', { error: err.message });
+    process.exit(0);
+  }
+
+  // 只处理 Bash 命令
+  if (input.tool_name !== 'Bash') {
+    logger.debug('Not a Bash command, skipping', { toolName: input.tool_name });
+    process.exit(0);
+  }
+
+  // Find project root
+  const cwd = input.cwd || process.cwd();
+  const projectRoot = await findProjectRootAsync(cwd);
+
+  if (!projectRoot) {
+    logger.debug('No project root found, skipping');
+    process.exit(0);
+  }
+
+  // 检查是否为 AI 项目
+  const isAIProject = await checkProjectType(projectRoot);
+  if (!isAIProject) {
+    logger.debug('Not an AI project, skipping');
+    process.exit(0);
+  }
+
+  // 执行安全检查和效果验证
+  await handleSecurityCheck(input, projectRoot);
+  await handleEffectValidation(input, projectRoot);
+
+  process.exit(0);
+}
+
+main().catch((err) => {
+  const result = handleHookError('ai-project-guard', err, {
+    eventName: 'PostToolUse'
+  });
+  process.stdout.write(JSON.stringify(result.hookSpecificOutput));
+  process.exit(0);
+});

package/plugins/hooks/artifact-evaluation-hook.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+
+/**
+ * AutoSpec PostToolUse Hook: Artifact Evaluator
+ *
+ * 产出物评测 Hook
+ * - 触发时机：关键产出物生成后
+ * - 执行策略：
+ *   - 结构检查：100% 执行
+ *   - 一致性检测：100% 执行
+ *   - AI 质量评估：采样执行（首次必评，后续 30% 采样）
+ */
+
+import { createHookLogger, safeJsonParse, handleHookError, readStdin, findProjectRootAsync } from './lib/hook-logger.js';
+import {
+  isKeyArtifact,
+  detectArtifactType,
+  checkStructure,
+  recordArtifactEval,
+  calculateArtifactScore,
+  updateArtifactSummary,
+  shouldRunQualityEval
+} from './lib/artifact-evaluator.js';
+import { getTraceId, recordEvent } from './lib/trace-context.js';
+import { getState, getMetrics, updateMetrics } from './lib/hook-state-manager.js';
+
+const logger = createHookLogger('artifact-evaluation-hook');
+
+/**
+ * 执行产出物评测
+ * @param {string} projectRoot - 项目根目录
+ * @param {string} artifactPath - 产出物路径
+ * @param {string} artifactType - 产出物类型
+ */
+async function evaluateArtifact(projectRoot, artifactPath, artifactType) {
+  const evaluations = {};
+
+  // 1. 结构完整性检查（100% 执行）
+  logger.info('执行结构完整性检查', { artifactPath, artifactType });
+  const structureResult = checkStructure(artifactPath, artifactType);
+  evaluations.structure = structureResult;
+
+  // 2. 一致性检测（如果有上游产物）
+  // 注：一致性检测需要多个产物，这里只标记需要检测
+  // 实际的一致性检测由 consistency-checker skill 执行
+  if (artifactType !== 'REQUIREMENT') {
+    evaluations.consistency = {
+      score: null,
+      status: 'pending',
+      message: '等待一致性检测'
+    };
+  }
+
+  // 3. AI 质量评估（采样执行）
+  const qualityDecision = shouldRunQualityEval(projectRoot, artifactType);
+  if (qualityDecision.shouldEval) {
+    logger.info('触发 AI 质量评估', { reason: qualityDecision.reason });
+    evaluations.quality = {
+      score: null,
+      status: 'pending',
+      message: '等待 AI 评估',
+      triggerReason: qualityDecision.reason
+    };
+
+    // 输出提示，让主流程知道需要执行 AI 评估
+    outputQualityEvalPrompt(artifactPath, artifactType);
+  } else {
+    logger.debug('跳过 AI 质量评估', { reason: qualityDecision.reason });
+  }
+
+  // 4. 下游反馈（标记为待评估）
+  evaluations.feedback = {
+    score: null,
+    status: 'pending',
+    message: '等待下游阶段反馈'
+  };
+
+  // 记录评测结果
+  recordArtifactEval(projectRoot, artifactPath, artifactType, evaluations);
+
+  // 计算当前可用评分
+  const currentScore = calculateArtifactScore(evaluations, artifactType);
+
+  // 更新产出物质量汇总
+  updateArtifactSummary(projectRoot);
+
+  // 低分告警
+  if (structureResult.score < 60) {
+    outputLowScoreWarning(artifactPath, structureResult.score, 'structure');
+  }
+
+  return {
+    evaluations,
+    currentScore
+  };
+}
+
+/**
+ * 输出 AI 质量评估提示
+ */
+function outputQualityEvalPrompt(artifactPath, artifactType) {
+  const prompt = `
+[AutoSpec] 产出物质量评估触发
+
+产出物: ${artifactPath}
+类型: ${artifactType}
+
+建议执行 AI 质量评估：
+1. 读取 framework/skills/support/ai-artifact-evaluator.md
+2. 使用 Agent 工具执行评估
+3. 将结果记录到 metrics.json
+
+评估维度：
+- 内容质量评分
+- 与历史优秀案例对比
+- 改进建议
+`;
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      additionalContext: prompt
+    }
+  }));
+}
+
+/**
+ * 输出低分告警
+ */
+function outputLowScoreWarning(artifactPath, score, evalType) {
+  const isSevere = score < 40;
+  const level = isSevere ? '🚨 严重' : '⚠️ 警告';
+
+  const warning = `
+[AutoSpec ${level}] 产出物质量评分较低
+
+产出物: ${artifactPath}
+评测类型: ${evalType}
+评分: ${score}/100
+
+${isSevere ? `
+**建议暂停当前流程**，产出物结构严重不完整：
+- 检查产出物是否符合模板要求
+- 确保必要章节完整
+- 建议重新生成后再继续下一阶段
+
+执行 /autospec:evaluate 获取详细评测报告。
+` : `
+建议：
+- 检查产出物是否符合模板要求
+- 确保必要章节完整
+- 考虑重新生成或人工审查
+`}
+`;
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      additionalContext: warning
+    }
+  }));
+}
+
+async function main() {
+  let input;
+  try {
+    const rawInput = await readStdin(1000);
+    input = safeJsonParse(rawInput, null, 'hook input');
+
+    if (!input) {
+      logger.debug('Empty or invalid input, skipping');
+      process.exit(0);
+    }
+  } catch (err) {
+    logger.error('Failed to parse input', { error: err.message });
+    process.exit(0);
+  }
+
+  const toolName = input.tool_name;
+
+  // 只处理 Write 操作
+  if (toolName !== 'Write') {
+    process.exit(0);
+  }
+
+  const filePath = input.tool_input?.file_path || '';
+
+  // 检查是否为关键产出物
+  if (!isKeyArtifact(filePath)) {
+    logger.debug('Not a key artifact, skipping', { filePath });
+    process.exit(0);
+  }
+
+  const cwd = input.cwd || process.cwd();
+  const projectRoot = await findProjectRootAsync(cwd);
+
+  if (!projectRoot) {
+    logger.debug('No .autospec directory found, skipping');
+    process.exit(0);
+  }
+
+  // 检测产出物类型
+  const artifactType = detectArtifactType(filePath);
+  if (!artifactType) {
+    logger.debug('Unknown artifact type, skipping', { filePath });
+    process.exit(0);
+  }
+
+  logger.info('Detected key artifact for evaluation', { filePath, artifactType });
+
+  // 执行评测
+  await evaluateArtifact(projectRoot, filePath, artifactType);
+
+  // 记录事件到 trace 日志
+  const traceId = getTraceId(projectRoot);
+  if (traceId) {
+    recordEvent(projectRoot, 'artifact_created', {
+      source: 'artifact-evaluation-hook',
+      tool: 'Write',
+      action: 'create_artifact',
+       data: {
+        artifactPath: filePath,
+        artifactType
+      }
+    });
+  }
+
+  process.exit(0);
+}
+
+main().catch((err) => {
+  const result = handleHookError('artifact-evaluation-hook', err, {
+    eventName: 'PostToolUse'
+  });
+  process.stdout.write(JSON.stringify(result.hookSpecificOutput));
+  process.exit(0);
+});