@dommaker/harness 0.13.0 → 0.13.2

package/src/cli/commands/contract.ts

@@ -0,0 +1,168 @@
+/**
+ * harness contract 命令
+ *
+ * API 契约门控，检查 OpenAPI Schema 验证
+ */
+
+import chalk from 'chalk';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { ContractGate } from '../../gates/contract';
+
+export interface ContractOptions {
+  /** 项目路径 */
+  projectPath?: string;
+  /** 契约文件路径 */
+  contractPath?: string;
+  /** 是否严格模式 */
+  strict?: boolean;
+  /** 是否允许破坏性变更 */
+  allowBreaking?: boolean;
+}
+
+/**
+ * 执行契约门控
+ */
+export async function contract(options: ContractOptions): Promise<void> {
+  console.log(chalk.blue('📜 API 契约门控检查...'));
+
+  const projectPath = options.projectPath || process.cwd();
+  const contractPath = options.contractPath || 'openapi.yaml';
+
+  // 先验证文件是否存在
+  const fullPath = path.join(projectPath, contractPath);
+  try {
+    await fs.access(fullPath);
+  } catch {
+    console.log();
+    console.log(chalk.red('❌ 契约文件不存在'));
+    console.log(chalk.red(`   ${fullPath}`));
+    process.exit(1);
+  }
+
+  // 创建契约门控实例
+  const gate = new ContractGate({
+    contractPath,
+    strict: options.strict !== false, // 默认严格模式
+    allowBreakingChanges: options.allowBreaking || false,
+  });
+
+  try {
+    const result = await gate.check({
+      projectPath,
+    } as any);
+
+    if (result.passed) {
+      console.log();
+      console.log(chalk.green('✅ 契约门控检查通过'));
+
+      if (result.details) {
+        console.log(chalk.gray(`   Schema 有效: ✅`));
+        if (result.details.endpoints) {
+          console.log(chalk.gray(`   端点数: ${result.details.endpoints}`));
+        }
+        if (result.details.breakingChanges === false) {
+          console.log(chalk.gray(`   破坏性变更: 无`));
+        }
+      }
+    } else {
+      console.log();
+      console.log(chalk.red('❌ 契约门控检查失败'));
+      console.log(chalk.red(`   ${result.message}`));
+
+      if (result.details?.errors) {
+        console.log();
+        console.log(chalk.red('验证错误:'));
+        (result.details.errors as string[]).forEach((error: string) => {
+          console.log(chalk.red(`  - ${error}`));
+        });
+      }
+
+      if (result.details?.breakingChanges) {
+        console.log();
+        console.log(chalk.red('破坏性变更:'));
+        (result.details.breakingChanges as any[]).forEach((change: any) => {
+          console.log(chalk.red(`  - ${change.type}: ${change.path}`));
+          if (change.description) {
+            console.log(chalk.gray(`    ${change.description}`));
+          }
+        });
+      }
+
+      process.exit(1);
+    }
+  } catch (error: any) {
+    console.log();
+    console.log(chalk.red('❌ 契约门控检查出错'));
+    console.log(chalk.red(`   ${error.message}`));
+    process.exit(1);
+  }
+}
+
+/**
+ * 验证 OpenAPI Schema 语法
+ */
+export async function validateSchema(options: ContractOptions): Promise<void> {
+  console.log(chalk.blue('📜 验证 OpenAPI Schema...\n'));
+
+  const projectPath = options.projectPath || process.cwd();
+  const contractPath = options.contractPath || 'openapi.yaml';
+
+  try {
+    const yaml = await import('js-yaml');
+
+    const fullPath = path.join(projectPath, contractPath);
+    const content = await fs.readFile(fullPath, 'utf-8');
+
+    let schema: any;
+    try {
+      schema = yaml.load(content);
+    } catch (e: any) {
+      console.log(chalk.red(`❌ YAML 解析错误: ${e.message}`));
+      process.exit(1);
+    }
+
+    // 基本验证
+    const errors: string[] = [];
+
+    if (!schema.openapi) {
+      errors.push('缺少 openapi 字段');
+    } else if (!schema.openapi.startsWith('3.')) {
+      errors.push(`OpenAPI 版本建议使用 3.x，当前: ${schema.openapi}`);
+    }
+
+    if (!schema.info) {
+      errors.push('缺少 info 字段');
+    } else {
+      if (!schema.info.title) errors.push('缺少 info.title');
+      if (!schema.info.version) errors.push('缺少 info.version');
+    }
+
+    if (!schema.paths || Object.keys(schema.paths).length === 0) {
+      errors.push('缺少 paths 字段或路径为空');
+    }
+
+    if (errors.length > 0) {
+      console.log(chalk.red('❌ Schema 验证失败:\n'));
+      errors.forEach(err => console.log(chalk.red(`  - ${err}`)));
+      process.exit(1);
+    }
+
+    console.log(chalk.green('✅ Schema 验证通过'));
+    console.log();
+    console.log(chalk.gray('Schema 信息:'));
+    console.log(chalk.gray(`  版本: ${schema.openapi}`));
+    console.log(chalk.gray(`  标题: ${schema.info.title}`));
+    console.log(chalk.gray(`  API 版本: ${schema.info.version}`));
+
+    if (schema.paths) {
+      const endpoints = Object.keys(schema.paths).flatMap(path =>
+        Object.keys(schema.paths[path]).map(method => `${method.toUpperCase()} ${path}`)
+      );
+      console.log(chalk.gray(`  端点数: ${endpoints.length}`));
+    }
+  } catch (error: any) {
+    console.log(chalk.red(`❌ 验证失败: ${error.message}`));
+    process.exit(1);
+  }
+}

package/src/cli/commands/failure.ts

@@ -0,0 +1,117 @@
+/**
+ * harness failure 命令
+ *
+ * 失败记录管理：list、stats、clear
+ */
+
+import chalk from 'chalk';
+import * as path from 'path';
+import { FailureRecorder } from '../../failure/recorder';
+
+export interface FailureOptions {
+  /** 项目路径 */
+  projectPath?: string;
+  /** 输出 JSON 格式 */
+  json?: boolean;
+}
+
+/**
+ * 获取失败记录器
+ */
+function getRecorder(projectPath?: string): FailureRecorder {
+  const base = projectPath || process.cwd();
+  return new FailureRecorder({
+    logFile: path.join(base, '.harness', 'failures', 'failures.log'),
+  });
+}
+
+/**
+ * 失败记录列表
+ */
+export async function failureList(
+  options: FailureOptions & { limit?: number; type?: string; level?: string },
+): Promise<void> {
+  const recorder = getRecorder(options.projectPath);
+
+  let records = await recorder.getHistory();
+
+  if (options.type) {
+    records = records.filter(r => r.type === options.type);
+  }
+  if (options.level) {
+    records = records.filter(r => r.level === options.level);
+  }
+  if (options.limit && options.limit > 0) {
+    records = records.slice(-options.limit);
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({ total: records.length, records }, null, 2));
+    return;
+  }
+
+  if (records.length === 0) {
+    console.log(chalk.yellow('没有失败记录'));
+    return;
+  }
+
+  console.log(chalk.red(`📋 失败记录 (${records.length} 条)\n`));
+  for (const record of records) {
+    const levelColor = record.level === 'L4' ? chalk.red
+      : record.level === 'L3' ? chalk.yellow
+      : record.level === 'L2' ? chalk.cyan
+      : chalk.gray;
+    const time = new Date(record.timestamp).toLocaleString();
+    console.log(`  ${levelColor(`[${record.level}]`)} ${chalk.bold(record.type)} ${chalk.gray(time)}`);
+    console.log(`    ${record.message}`);
+  }
+}
+
+/**
+ * 失败记录统计
+ */
+export async function failureStats(options: FailureOptions): Promise<void> {
+  const recorder = getRecorder(options.projectPath);
+  const stats = await recorder.getStats();
+
+  if (options.json) {
+    console.log(JSON.stringify(stats, null, 2));
+    return;
+  }
+
+  if (stats.total === 0) {
+    console.log(chalk.green('✅ 没有失败记录'));
+    return;
+  }
+
+  console.log(chalk.red(`📊 失败统计\n`));
+  console.log(chalk.bold(`  总计: ${stats.total} 条\n`));
+
+  console.log(chalk.bold('  按类型:'));
+  for (const [type, count] of Object.entries(stats.byType)) {
+    console.log(`    ${type}: ${count}`);
+  }
+
+  console.log(chalk.bold('\n  按等级:'));
+  for (const [level, count] of Object.entries(stats.byLevel)) {
+    const color = level === 'L4' ? chalk.red : level === 'L3' ? chalk.yellow : chalk.gray;
+    console.log(`    ${color(level)}: ${count}`);
+  }
+}
+
+/**
+ * 清空失败记录
+ */
+export async function failureClear(options: FailureOptions): Promise<void> {
+  const recorder = getRecorder(options.projectPath);
+  const stats = await recorder.getStats();
+
+  await recorder.clear();
+
+  if (options.json) {
+    console.log(JSON.stringify({ cleared: stats.total }));
+    return;
+  }
+
+  console.log(chalk.green(`✅ 已清空 ${stats.total} 条失败记录`));
+}

package/src/cli/commands/flow.ts

@@ -0,0 +1,275 @@
+/**
+ * harness flow 命令
+ *
+ * 一键执行诊断 + 提案流程
+ */
+
+import chalk from 'chalk';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as readline from 'readline';
+import { TraceCollector } from '../../monitoring/traces';
+import { TraceAnalyzer } from '../../monitoring/trace-analyzer';
+import { ConstraintDoctor, Diagnosis } from '../../monitoring/constraint-doctor';
+import { ConstraintEvolver, ConstraintProposal } from '../../monitoring/constraint-evolver';
+import { ConstraintLifecycleRunner, type ExecutionResult } from '../../constraints/lifecycle-runner';
+import type { TraceAnomaly } from '../../types/trace';
+
+export interface FlowOptions {
+  /** 项目路径 */
+  projectPath?: string;
+  /** 从哪个步骤开始 */
+  from?: 'analyze' | 'diagnose' | 'propose';
+  /** 自动应用低风险提案 */
+  autoApply?: boolean;
+  /** 自动执行已接受的提案（调用 ConstraintLifecycleRunner） */
+  autoExecute?: boolean;
+  /** 时间范围（小时） */
+  hours?: number;
+}
+
+/**
+ * 创建 readline 接口
+ */
+function createReadlineInterface(): readline.ReadLine {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+/**
+ * 询问用户
+ */
+function ask(rl: readline.ReadLine, question: string): Promise<string> {
+  return new Promise(resolve => {
+    rl.question(question, answer => {
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+
+/**
+ * 执行流程
+ */
+export async function flow(options: FlowOptions): Promise<void> {
+  const projectPath = options.projectPath || process.cwd();
+  const harnessDir = path.join(projectPath, '.harness');
+  const tracesPath = path.join(harnessDir, 'traces', 'execution.log');
+  const diagnosesDir = path.join(harnessDir, 'diagnoses');
+  const proposalsDir = path.join(harnessDir, 'proposals');
+
+  console.log(chalk.blue('🔄 Harness 自动化流程'));
+  console.log();
+
+  // 检查前置条件
+  if (!fs.existsSync(tracesPath)) {
+    console.log(chalk.yellow('⚠️  暂无 Trace 记录'));
+    console.log(chalk.gray('💡 运行 harness check 开始记录'));
+    return;
+  }
+
+  // 读取 traces
+  const tracesContent = fs.readFileSync(tracesPath, 'utf-8');
+  const lines = tracesContent.trim().split('\n').filter(Boolean);
+  const traces = lines.map(line => {
+    try {
+      return JSON.parse(line);
+    } catch {
+      return null;
+    }
+  }).filter(Boolean);
+
+  // 创建收集器和分析器
+  const collector = new TraceCollector({ traceFile: tracesPath });
+  const analyzer = new TraceAnalyzer(collector);
+  const summaries = analyzer.summarize(traces);
+  let anomalies = analyzer.detectAnomalies(summaries);
+
+  const rl = createReadlineInterface();
+
+  try {
+    // 步骤 1: 分析统计
+    if (!options.from || options.from === 'analyze') {
+      console.log(chalk.blue('📊 步骤 1/4: 分析统计'));
+      console.log(chalk.gray('────────────────────────────'));
+
+      console.log(chalk.gray(`约束统计: ${summaries.length} 条`));
+      console.log(chalk.gray(`检测异常: ${anomalies.length} 个`));
+
+      if (anomalies.length === 0) {
+        console.log(chalk.green('✅ 未发现异常'));
+        rl.close();
+        return;
+      }
+
+      console.log(chalk.yellow('发现异常:'));
+      anomalies.forEach((a: TraceAnomaly) => {
+        console.log(chalk.yellow(`  - ${a.constraintId}: ${a.type}`));
+      });
+      console.log();
+
+      // 询问是否继续
+      const continue1 = await ask(rl, '是否继续运行诊断？ [Y/n] ');
+      if (continue1 === 'n') {
+        console.log(chalk.gray('已取消'));
+        rl.close();
+        return;
+      }
+      console.log();
+    }
+
+    // 步骤 2: 运行诊断
+    console.log(chalk.blue('🔍 步骤 2/4: 运行诊断'));
+    console.log(chalk.gray('────────────────────────────'));
+
+    const doctor = new ConstraintDoctor();
+    const diagnoses: Diagnosis[] = [];
+
+    for (const anomaly of anomalies) {
+      try {
+        const diagnosis = await doctor.diagnose(anomaly);
+        diagnoses.push(diagnosis);
+      } catch (e) {
+        console.log(chalk.yellow(`  ⚠️ ${anomaly.constraintId} 诊断失败`));
+      }
+    }
+
+    console.log(chalk.gray(`诊断数量: ${diagnoses.length}`));
+
+    if (diagnoses.length > 0) {
+      console.log();
+      diagnoses.forEach((d: Diagnosis) => {
+        console.log(chalk.yellow(`  ${d.constraintId}`));
+        console.log(chalk.gray(`    根因: ${d.rootCause.primary}`));
+        console.log(chalk.gray(`    严重度: ${d.impact.severity}`));
+      });
+    }
+
+    // 保存诊断结果
+    if (diagnoses.length > 0) {
+      fs.mkdirSync(diagnosesDir, { recursive: true });
+      const diagnosisFile = path.join(diagnosesDir, `${new Date().toISOString().split('T')[0]}.json`);
+      fs.writeFileSync(diagnosisFile, JSON.stringify(diagnoses, null, 2));
+      console.log(chalk.green(`✅ 诊断已保存: ${diagnosisFile}`));
+    }
+    console.log();
+
+    // 询问是否继续
+    const continue2 = await ask(rl, '是否继续生成优化提案？ [Y/n] ');
+    if (continue2 === 'n') {
+      console.log(chalk.gray('已取消'));
+      rl.close();
+      return;
+    }
+    console.log();
+
+    // 步骤 3: 生成提案
+    console.log(chalk.blue('💡 步骤 3/4: 生成提案'));
+    console.log(chalk.gray('────────────────────────────'));
+
+    const evolver = new ConstraintEvolver();
+    const proposals: ConstraintProposal[] = [];
+
+    for (const diagnosis of diagnoses) {
+      try {
+        const proposal = await evolver.propose(diagnosis);
+        if (proposal) {
+          proposals.push(proposal);
+        }
+      } catch (e) {
+        console.log(chalk.yellow(`  ⚠️ ${diagnosis.constraintId} 提案生成失败`));
+      }
+    }
+
+    console.log(chalk.gray(`提案数量: ${proposals.length}`));
+
+    if (proposals.length === 0) {
+      console.log(chalk.green('✅ 无需优化'));
+      rl.close();
+      return;
+    }
+
+    console.log();
+    proposals.forEach((p: ConstraintProposal, i: number) => {
+      console.log(chalk.yellow(`提案 ${i + 1}:`));
+      console.log(chalk.gray(`  约束: ${p.constraintId}`));
+      console.log(chalk.gray(`  操作: ${p.type}`));
+      console.log(chalk.gray(`  风险: ${p.risk.level}`));
+      console.log();
+    });
+
+    // 保存提案
+    fs.mkdirSync(proposalsDir, { recursive: true });
+    const proposalFile = path.join(proposalsDir, `${new Date().toISOString().split('T')[0]}.json`);
+    fs.writeFileSync(proposalFile, JSON.stringify({ proposals, timestamp: new Date().toISOString() }, null, 2));
+    console.log(chalk.green(`✅ 提案已保存: ${proposalFile}`));
+    console.log();
+
+    // 步骤 4: 审核提案
+    console.log(chalk.blue('📝 步骤 4/4: 审核提案'));
+    console.log(chalk.gray('────────────────────────────'));
+
+    const runner = options.autoExecute ? new ConstraintLifecycleRunner() : null;
+    const executionResults: ExecutionResult[] = [];
+
+    for (let i = 0; i < proposals.length; i++) {
+      const p = proposals[i];
+
+      // 低风险 → 可自动应用
+      if (options.autoApply && p.risk.level === 'low') {
+        console.log(chalk.green(`✅ 自动应用提案 ${i + 1} (低风险)`));
+        if (runner) {
+          const result = runner.execute(p);
+          executionResults.push(result);
+          if (result.success) {
+            console.log(chalk.green(`  ✅ 已执行: ${result.details}`));
+          } else {
+            console.log(chalk.yellow(`  ⚠️ 执行失败: ${result.details}`));
+          }
+        }
+        continue;
+      }
+
+      // 需要人工审核
+      const answer = await ask(rl, `是否应用提案 ${i + 1}？ [y/N] `);
+      if (answer === 'y') {
+        console.log(chalk.green(`✅ 提案 ${i + 1} 已标记为应用`));
+        if (runner) {
+          const result = runner.execute(p);
+          executionResults.push(result);
+          if (result.success) {
+            console.log(chalk.green(`  ✅ 已执行: ${result.details}`));
+          } else {
+            console.log(chalk.yellow(`  ⚠️ 执行失败: ${result.details}`));
+          }
+        } else {
+          console.log(chalk.gray('  请手动更新约束配置'));
+        }
+      } else {
+        console.log(chalk.gray(`⏭️  跳过提案 ${i + 1}`));
+      }
+    }
+
+    // 显示执行摘要
+    if (executionResults.length > 0) {
+      console.log();
+      console.log(chalk.blue('📊 执行摘要:'));
+      const succeeded = executionResults.filter(r => r.success).length;
+      const failed = executionResults.filter(r => !r.success).length;
+      console.log(chalk.gray(`  成功: ${succeeded}, 失败: ${failed}`));
+    }
+
+    console.log();
+    console.log(chalk.green('✅ 流程完成！'));
+    console.log();
+    console.log(chalk.blue('💡 下一步:'));
+    console.log(chalk.gray('  1. 查看提案文件确认变更'));
+    if (!runner) {
+      console.log(chalk.gray('  2. 手动更新约束配置'));
+    }
+    console.log(chalk.gray(`  ${runner ? '2' : '3'}. 运行 harness status 查看效果`));
+  } finally {
+    rl.close();
+  }
+}

package/src/cli/commands/index.ts

@@ -0,0 +1,26 @@
+/**
+ * CLI 命令导出
+ */
+
+export { check, listLaws, type CheckOptions } from './check';
+export { validate, createExampleCheckpoint, DEFAULT_CHECKPOINTS, type ValidateOptions } from './validate';
+export { runPassesGate, checkCoverage, type PassesGateOptions } from './passes-gate';
+export { init, type InitOptions } from './init';
+export { report, type ReportOptions } from './report';
+export { status, type StatusOptions } from './status';
+export { flow, type FlowOptions } from './flow';
+export { specValidate, listSpecTypes, type SpecValidateOptions } from './spec';
+export { acceptance, listAcceptanceCriteria, type AcceptanceOptions } from './acceptance';
+export { performance, type PerformanceOptions } from './performance';
+export { security, auditDetails, type SecurityOptions } from './security';
+export { contract, validateSchema, type ContractOptions } from './contract';
+export { review, reviewStatus, type ReviewOptions } from './review';
+export { executeCommand, type CommandCheckOptions } from './command';
+export { syncDocs, type SyncDocsOptions } from './sync-docs';
+export { knowledgeList, knowledgeSearch, knowledgeImport, knowledgeDecay, knowledgeStats, knowledgeUpsert, knowledgeSyncStatus, knowledgeSyncRag, type KnowledgeOptions, type KnowledgeUpsertOptions } from './knowledge';
+export { failureList, failureStats, failureClear, type FailureOptions } from './failure';
+export { postevalPlan, type PostEvalPlanOptions } from './posteval-plan';
+export { release, type ReleaseOptions } from './release';
+export { analyzeSessions, type AnalyzeSessionsOptions } from './analyze-sessions';
+export { updateUserModel, type UpdateUserModelOptions } from './update-user-model';
+export { constraints, getConstraintsMeta, type ConstraintsMeta } from './constraints';