@dommaker/harness 0.13.0 → 0.13.2

package/src/cli/commands/knowledge.ts

@@ -0,0 +1,391 @@
+/**
+ * harness knowledge 命令
+ *
+ * 知识库管理：list、search、import、decay、stats
+ */
+
+import chalk from 'chalk';
+import * as fs from 'fs';
+import { KnowledgeStore } from '../../knowledge/store';
+import { KnowledgeQuery } from '../../knowledge/query';
+import { KnowledgeLifecycle } from '../../knowledge/lifecycle';
+import { ColdStartImporter } from '../../knowledge/import';
+import type { KnowledgeType, MaturityLevel, QueryFilter } from '../../knowledge/types';
+
+export interface KnowledgeOptions {
+  /** 项目路径 */
+  projectPath?: string;
+  /** 输出 JSON 格式 */
+  json?: boolean;
+}
+
+/**
+ * 知识库列表
+ */
+export async function knowledgeList(options: KnowledgeOptions & {
+  type?: string;
+  maturity?: string;
+  tag?: string;
+}): Promise<void> {
+  const store = new KnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath) });
+
+  const filter: QueryFilter = { excludeArchived: false };
+  if (options.type) {
+    filter.types = options.type.split(',') as KnowledgeType[];
+  }
+  if (options.maturity) {
+    filter.maturity = options.maturity.split(',') as MaturityLevel[];
+  }
+  if (options.tag) {
+    filter.tags = options.tag.split(',');
+  }
+
+  const entries = store.list(filter);
+
+  if (options.json) {
+    console.log(JSON.stringify({ total: entries.length, entries }, null, 2));
+    return;
+  }
+
+  if (entries.length === 0) {
+    console.log(chalk.yellow('知识库为空'));
+    return;
+  }
+
+  console.log(chalk.blue(`📚 知识库 (${entries.length} 条)\n`));
+  for (const entry of entries) {
+    const maturityColor = entry.maturity === 'proven' ? chalk.green
+      : entry.maturity === 'verified' ? chalk.cyan
+      : entry.maturity === 'archived' ? chalk.gray
+      : chalk.yellow;
+    console.log(`  ${maturityColor(`[${entry.maturity}]`)} ${chalk.bold(entry.title)}`);
+    console.log(`    ${chalk.gray(`id: ${entry.id} | type: ${entry.type} | layer: ${entry.layer}`)}`);
+    if (entry.tags.length > 0) {
+      console.log(`    ${chalk.gray(`tags: ${entry.tags.join(', ')}`)}`);
+    }
+  }
+}
+
+/**
+ * 知识库搜索
+ */
+export async function knowledgeSearch(
+  query: string,
+  options: KnowledgeOptions & { limit?: number },
+): Promise<void> {
+  const store = new KnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath) });
+  const queryEngine = new KnowledgeQuery(store);
+
+  const budget = {
+    phase: 'cli',
+    maxTokens: 10000,
+    maxEntries: options.limit || 20,
+    focusTypes: [] as KnowledgeType[],
+  };
+
+  const result = queryEngine.query(budget);
+
+  // 简单文本匹配过滤
+  const q = query.toLowerCase();
+  const matched = result.entries.filter(e =>
+    e.title.toLowerCase().includes(q) ||
+    e.content.toLowerCase().includes(q) ||
+    e.tags.some(t => t.toLowerCase().includes(q))
+  );
+
+  if (options.json) {
+    console.log(JSON.stringify({ query, total: matched.length, entries: matched }, null, 2));
+    return;
+  }
+
+  if (matched.length === 0) {
+    console.log(chalk.yellow(`未找到匹配 "${query}" 的知识条目`));
+    return;
+  }
+
+  console.log(chalk.blue(`🔍 搜索 "${query}" (${matched.length} 条结果)\n`));
+  for (const entry of matched) {
+    console.log(`  ${chalk.bold(entry.title)} ${chalk.gray(`[${entry.maturity}]`)}`);
+    const preview = entry.content.slice(0, 100).replace(/\n/g, ' ');
+    console.log(`    ${chalk.gray(preview)}${entry.content.length > 100 ? '...' : ''}`);
+  }
+}
+
+/**
+ * 知识库导入（冷启动）
+ */
+export async function knowledgeImport(
+  options: KnowledgeOptions & { sources?: string; reset?: boolean },
+): Promise<void> {
+  const projectPath = options.projectPath || process.cwd();
+  const store = new KnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath) });
+
+  const sources = options.sources
+    ? options.sources.split(',') as Array<'code' | 'git' | 'docs' | 'manual'>
+    : ['code', 'git', 'docs'] as Array<'code' | 'git' | 'docs'>;
+
+  const importer = new ColdStartImporter({
+    projectRoot: projectPath,
+    store,
+    sources,
+  });
+
+  if (options.reset) {
+    importer.resetState();
+    if (!options.json) {
+      console.log(chalk.yellow('🔄 已重置导入状态'));
+    }
+  }
+
+  if (!options.json) {
+    console.log(chalk.blue(`📥 开始导入知识 (源: ${sources.join(', ')})...`));
+  }
+
+  const results = await importer.importAll();
+
+  const totalImported = results.reduce((sum, r) => sum + r.entries.length, 0);
+  const totalErrors = results.reduce((sum, r) => sum + r.errors.length, 0);
+
+  if (options.json) {
+    console.log(JSON.stringify({ totalImported, totalErrors, results }, null, 2));
+    return;
+  }
+
+  for (const result of results) {
+    if (result.entries.length > 0) {
+      console.log(chalk.green(`  ✅ ${result.source.type}: ${result.entries.length} 条`));
+    }
+    if (result.errors.length > 0) {
+      for (const err of result.errors) {
+        console.log(chalk.red(`  ❌ ${result.source.type}: ${err.message}`));
+      }
+    }
+  }
+
+  console.log(chalk.green(`\n✅ 导入完成: ${totalImported} 条，${totalErrors} 个错误`));
+}
+
+/**
+ * 知识库衰减周期
+ */
+export async function knowledgeDecay(options: KnowledgeOptions): Promise<void> {
+  const store = new KnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath) });
+  const lifecycle = new KnowledgeLifecycle(store);
+
+  if (!options.json) {
+    console.log(chalk.blue('🔄 运行衰减周期...'));
+  }
+
+  const changes = lifecycle.runDecayCycle();
+
+  if (options.json) {
+    console.log(JSON.stringify({ changes }, null, 2));
+    return;
+  }
+
+  if (changes.length === 0) {
+    console.log(chalk.green('✅ 没有需要衰减的知识条目'));
+    return;
+  }
+
+  console.log(chalk.yellow(`📉 ${changes.length} 条知识发生衰减:\n`));
+  for (const change of changes) {
+    console.log(`  ${change.entryId}: ${chalk.red(change.from)} → ${chalk.green(change.to)}`);
+    console.log(`    ${chalk.gray(change.reason)}`);
+  }
+}
+
+/**
+ * 知识库统计
+ */
+export async function knowledgeStats(options: KnowledgeOptions): Promise<void> {
+  const store = new KnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath) });
+  const entries = store.list({ excludeArchived: false });
+
+  const byType: Record<string, number> = {};
+  const byMaturity: Record<string, number> = {};
+  const byLayer: Record<string, number> = {};
+
+  for (const entry of entries) {
+    byType[entry.type] = (byType[entry.type] || 0) + 1;
+    byMaturity[entry.maturity] = (byMaturity[entry.maturity] || 0) + 1;
+    byLayer[entry.layer] = (byLayer[entry.layer] || 0) + 1;
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({ total: entries.length, byType, byMaturity, byLayer }, null, 2));
+    return;
+  }
+
+  console.log(chalk.blue(`📊 知识库统计\n`));
+  console.log(chalk.bold(`  总计: ${entries.length} 条\n`));
+
+  console.log(chalk.bold('  按类型:'));
+  for (const [type, count] of Object.entries(byType)) {
+    console.log(`    ${type}: ${count}`);
+  }
+
+  console.log(chalk.bold('\n  按成熟度:'));
+  for (const [maturity, count] of Object.entries(byMaturity)) {
+    const color = maturity === 'proven' ? chalk.green : maturity === 'archived' ? chalk.gray : chalk.yellow;
+    console.log(`    ${color(maturity)}: ${count}`);
+  }
+
+  console.log(chalk.bold('\n  按层级:'));
+  for (const [layer, count] of Object.entries(byLayer)) {
+    console.log(`    ${layer}: ${count}`);
+  }
+}
+
+export interface KnowledgeUpsertOptions {
+  scope: string;
+  title: string;
+  content?: string;
+  file?: string;
+  type?: string;
+  source?: string;
+}
+
+/**
+ * 设计时知识沉淀：写入 KnowledgeStore + 同步 Prisma Document（Studio UI 可见）
+ *
+ * 调用 Studio API POST /api/knowledge/upsert（内部端点，无 auth）
+ */
+export async function knowledgeUpsert(options: KnowledgeUpsertOptions): Promise<void> {
+  const apiPort = process.env.API_PORT || '3001';
+  const url = `http://localhost:${apiPort}/api/knowledge/upsert`;
+
+  // Read content from file if --file specified
+  let content = options.content || '';
+  if (options.file && !content) {
+    try {
+      content = fs.readFileSync(options.file, 'utf-8');
+    } catch (e: any) {
+      console.error(chalk.red(`Failed to read file: ${options.file}`));
+      console.error(chalk.red(String(e)));
+      process.exit(1);
+    }
+  }
+
+  if (!options.scope || !options.title || !content) {
+    console.error(chalk.red('--scope, --title, and --content (or --file) are required'));
+    process.exit(1);
+  }
+
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        scope: options.scope,
+        title: options.title,
+        content,
+        type: options.type || 'architecture',
+        source: options.source || 'cli',
+      }),
+    });
+
+    if (!res.ok) {
+      const err: any = await res.json().catch(() => ({ error: res.statusText }));
+      console.error(chalk.red(`API error ${res.status}: ${err.error || res.statusText}`));
+      process.exit(1);
+    }
+
+    const result: any = await res.json();
+    console.log(chalk.green(`✅ Knowledge upserted`));
+    console.log(`   KnowledgeStore: ${result.knowledgeStore?.action} → ${result.knowledgeStore?.entryId}`);
+    console.log(`   Studio UI: ${result.prismaDocument?.action} → ${result.prismaDocument?.docId || 'skipped'}`);
+  } catch (e: any) {
+    if (e?.code === 'ECONNREFUSED') {
+      console.error(chalk.red(`Cannot reach Studio API at ${url}. Is the API running?`));
+    } else {
+      console.error(chalk.red(`Upsert failed: ${e.message}`));
+    }
+    process.exit(1);
+  }
+}
+
+/**
+/**
+ * RAG 同步：扫描 .harness/knowledge-docs/ 输出需要 ingest 的文件列表
+ */
+export async function knowledgeSyncRag(options: KnowledgeOptions): Promise<void> {
+  const projectPath = options.projectPath || process.cwd();
+  const docsDir = `${projectPath}/.harness/knowledge-docs`;
+
+  if (!fs.existsSync(docsDir)) {
+    console.log(chalk.yellow('No .harness/knowledge-docs/ directory'));
+    return;
+  }
+
+  const files = fs.readdirSync(docsDir).filter(f => f.endsWith('.md'));
+  if (files.length === 0) {
+    console.log(chalk.gray('No knowledge docs found'));
+    return;
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({ directory: docsDir, files }, null, 2));
+    return;
+  }
+
+  console.log(chalk.blue(`📄 RAG sync candidates: ${files.length} files in ${docsDir}\n`));
+  for (const file of files) {
+    console.log(chalk.cyan(`  ${file}`));
+  }
+  console.log();
+  console.log(chalk.gray('Run `mcp__local-rag__ingest_file` for each to sync to RAG'));
+}
+
+/**
+ * 知识同步状态：检测所有 tracked scope 的新鲜度
+ */
+export async function knowledgeSyncStatus(options: KnowledgeOptions): Promise<void> {
+  const apiPort = process.env.API_PORT || '3001';
+  const url = `http://localhost:${apiPort}/api/knowledge/sync-status`;
+
+  try {
+    const res = await fetch(url);
+    if (!res.ok) {
+      const err: any = await res.json().catch(() => ({ error: res.statusText }));
+      console.error(chalk.red(`API error ${res.status}: ${err.error || res.statusText}`));
+      process.exit(1);
+    }
+
+    const data: any = await res.json();
+
+    if (options.json) {
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+
+    console.log(chalk.blue(`🔄 KnowledgeSync Status\n`));
+    console.log(chalk.bold(`Tracked scopes: ${data.trackedScopes?.join(', ') || 'none'}`));
+    console.log(chalk.bold(`Stale entries: ${data.stale?.length || 0}`));
+
+    if (data.stale?.length > 0) {
+      console.log(chalk.yellow(`\n⚠️  Stale knowledge:\n`));
+      for (const s of data.stale) {
+        console.log(chalk.yellow(`  ${s.scope} (${s.title}): ${s.stalenessHours}h old, files changed: ${s.changedFiles.join(', ')}`));
+      }
+    } else {
+      console.log(chalk.green('\n✅ All knowledge fresh'));
+    }
+
+    if (data.healed?.length > 0) {
+      console.log(chalk.cyan(`\n🩹 Auto-healed: ${data.healed.join(', ')}`));
+    }
+  } catch (e: any) {
+    if (e?.code === 'ECONNREFUSED') {
+      console.error(chalk.red(`Cannot reach Studio API at ${url}`));
+    } else {
+      console.error(chalk.red(`Sync check failed: ${e.message}`));
+    }
+    process.exit(1);
+  }
+}
+
+function getKnowledgeDir(projectPath?: string): string {
+  const base = projectPath || process.cwd();
+  return `${base}/.harness/knowledge`;
+}

package/src/cli/commands/passes-gate.ts

@@ -0,0 +1,158 @@
+/**
+ * harness passes-gate 命令
+ * 
+ * 运行测试门控，确保测试通过
+ */
+
+import chalk from 'chalk';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { execAsync } from '../../utils/exec';
+import { PassesGate } from '../../core/validators/passes-gate';
+import type { PassesGateConfig } from '../../types/passes-gate';
+
+export interface PassesGateOptions {
+  /** 测试命令 */
+  testCommand?: string;
+  /** 项目路径 */
+  projectPath?: string;
+  /** 是否允许部分通过 */
+  allowPartial?: boolean;
+  /** 最大重试次数 */
+  maxRetries?: number;
+}
+
+/**
+ * 检测项目的测试命令
+ */
+async function detectTestCommand(projectPath: string): Promise<string | undefined> {
+  const packageJsonPath = path.join(projectPath, 'package.json');
+
+  try {
+    const content = await fs.readFile(packageJsonPath, 'utf-8');
+    const pkg = JSON.parse(content);
+
+    if (pkg.scripts?.test && pkg.scripts.test !== 'echo "Error: no test specified"') {
+      return 'npm test';
+    }
+    if (pkg.scripts?.['test:ci']) {
+      return 'npm run test:ci';
+    }
+  } catch {
+    // 没有 package.json
+  }
+
+  // 检查其他项目类型
+  try {
+    await fs.access(path.join(projectPath, 'pytest.ini'));
+    return 'pytest';
+  } catch {}
+
+  try {
+    await fs.access(path.join(projectPath, 'go.mod'));
+    return 'go test ./...';
+  } catch {}
+
+  return undefined;
+}
+
+/**
+ * 执行测试门控
+ */
+export async function runPassesGate(options: PassesGateOptions): Promise<void> {
+  console.log(chalk.blue('🚦 运行测试门控...'));
+
+  const projectPath = options.projectPath || process.cwd();
+
+  // 检测测试命令
+  let testCommand = options.testCommand;
+  if (!testCommand) {
+    testCommand = await detectTestCommand(projectPath);
+  }
+
+  if (!testCommand) {
+    console.log(chalk.yellow('⚠️  未检测到测试命令，跳过测试门控'));
+    console.log(chalk.gray('提示: 使用 --test-command 指定测试命令'));
+    return;
+  }
+
+  console.log(chalk.gray(`测试命令: ${testCommand}`));
+
+  // 配置
+  const config: PassesGateConfig = {
+    enabled: true,
+    testCommand,
+    requireEvidence: false,
+    allowPartialPass: options.allowPartial || false,
+    maxRetries: options.maxRetries || 2,
+  };
+
+  // 执行测试
+  const passesGate = new PassesGate(config);
+
+  try {
+    const result = await passesGate.runTests();
+
+    console.log();
+    console.log(chalk.gray('测试结果:'));
+    console.log(chalk.gray(`  通过: ${result.passedTests}/${result.totalTests}`));
+    console.log(chalk.gray(`  失败: ${result.failedTests}/${result.totalTests}`));
+    console.log(chalk.gray(`  耗时: ${result.duration}ms`));
+
+    if (result.passed) {
+      console.log();
+      console.log(chalk.green('✅ 测试门控通过'));
+      console.log(chalk.green('   task.passes = true (由测试结果设置)'));
+    } else {
+      console.log();
+      console.log(chalk.red('❌ 测试门控未通过'));
+      console.log(chalk.red('   task.passes = false'));
+      
+      if (result.failures && result.failures.length > 0) {
+        console.log(chalk.red('\n失败的测试:'));
+        result.failures.forEach(f => {
+          console.log(chalk.red(`  - ${f.name}: ${f.message}`));
+        });
+      }
+
+      process.exit(1);
+    }
+  } catch (error) {
+    console.log(chalk.red(`\n❌ 测试执行失败: ${(error as Error).message}`));
+    process.exit(1);
+  }
+}
+
+/**
+ * 检查测试覆盖率
+ */
+export async function checkCoverage(projectPath: string, threshold: number = 80): Promise<boolean> {
+  console.log(chalk.blue(`📊 检查测试覆盖率 (阈值: ${threshold}%)...`));
+
+  try {
+    // 运行覆盖率检查
+    await execAsync('npm test -- --coverage --coverageReporters=json-summary', {
+      cwd: projectPath,
+    });
+
+    // 读取覆盖率报告
+    const coveragePath = path.join(projectPath, 'coverage', 'coverage-summary.json');
+    const content = await fs.readFile(coveragePath, 'utf-8');
+    const coverage = JSON.parse(content);
+
+    const totalCoverage = coverage.total?.lines?.pct || 0;
+
+    console.log(chalk.gray(`当前覆盖率: ${totalCoverage}%`));
+
+    if (totalCoverage >= threshold) {
+      console.log(chalk.green(`✅ 覆盖率达标 (${totalCoverage}% >= ${threshold}%)`));
+      return true;
+    } else {
+      console.log(chalk.red(`❌ 覆盖率不足 (${totalCoverage}% < ${threshold}%)`));
+      return false;
+    }
+  } catch (error) {
+    console.log(chalk.yellow(`⚠️  无法获取覆盖率信息: ${(error as Error).message}`));
+    return true; // 无法获取时跳过检查
+  }
+}

package/src/cli/commands/performance.ts

@@ -0,0 +1,108 @@
+/**
+ * harness performance 命令
+ *
+ * 性能门控，检查性能指标
+ */
+
+import chalk from 'chalk';
+import { PerformanceGate } from '../../gates/performance';
+
+export interface PerformanceOptions {
+  /** 项目路径 */
+  projectPath?: string;
+  /** 是否检查覆盖率 */
+  coverage?: boolean;
+  /** 覆盖率阈值 */
+  coverageThreshold?: number;
+  /** 是否检查打包大小 */
+  bundle?: boolean;
+  /** 打包大小阈值（KB） */
+  bundleThreshold?: number;
+  /** 是否检查基准测试 */
+  benchmark?: boolean;
+  /** 基准测试超时（秒） */
+  benchmarkTimeout?: number;
+}
+
+/**
+ * 执行性能门控
+ */
+export async function performance(options: PerformanceOptions): Promise<void> {
+  console.log(chalk.blue('⚡ 性能门控检查...'));
+
+  const projectPath = options.projectPath || process.cwd();
+
+  // 构建配置
+  const config: any = {};
+
+  if (options.coverage && options.coverageThreshold) {
+    config.thresholds = {
+      coverage: options.coverageThreshold,
+    };
+  }
+
+  if (options.bundleThreshold) {
+    config.thresholds = config.thresholds || {};
+    config.thresholds.bundleSize = options.bundleThreshold * 1024; // KB to bytes
+  }
+
+  if (options.benchmarkTimeout) {
+    config.benchmarkTimeout = options.benchmarkTimeout * 1000; // seconds to ms
+  }
+
+  // 创建性能门控实例
+  const gate = new PerformanceGate(config);
+
+  try {
+    const result = await gate.check({
+      projectPath,
+      checkCoverage: options.coverage,
+      checkBundle: options.bundle,
+      checkBenchmark: options.benchmark,
+    } as any);
+
+    if (result.passed) {
+      console.log();
+      console.log(chalk.green('✅ 性能门控检查通过'));
+
+      // 显示详细指标
+      if (result.details?.metrics) {
+        console.log();
+        console.log(chalk.gray('性能指标:'));
+
+        const metrics = result.details.metrics as any;
+        if (metrics.coverage !== undefined) {
+          const threshold = options.coverageThreshold || 80;
+          const status = metrics.coverage >= threshold ? '✅' : '❌';
+          console.log(chalk.gray(`  覆盖率: ${metrics.coverage.toFixed(2)}% ${status}`));
+        }
+
+        if (metrics.bundleSize !== undefined) {
+          const thresholdKB = options.bundleThreshold || 500;
+          const actualKB = metrics.bundleSize / 1024;
+          const status = actualKB <= thresholdKB ? '✅' : '❌';
+          console.log(chalk.gray(`  打包大小: ${actualKB.toFixed(2)} KB ${status}`));
+        }
+
+        if (metrics.benchmarkTime !== undefined) {
+          console.log(chalk.gray(`  基准测试: ${metrics.benchmarkTime}ms`));
+        }
+      }
+    } else {
+      console.log();
+      console.log(chalk.red('❌ 性能门控检查失败'));
+      console.log(chalk.red(`   ${result.message}`));
+      if (result.details?.failures) {
+        (result.details.failures as string[]).forEach((failure: string) => {
+          console.log(chalk.red(`   - ${failure}`));
+        });
+      }
+      process.exit(1);
+    }
+  } catch (error: any) {
+    console.log();
+    console.log(chalk.red('❌ 性能门控检查出错'));
+    console.log(chalk.red(`   ${error.message}`));
+    process.exit(1);
+  }
+}