@dommaker/harness 0.13.0 → 0.13.2

package/src/monitoring/index.ts

@@ -0,0 +1,23 @@
+/**
+ * 监控模块导出
+ *
+ * Execution Trace 系统：
+ * - TraceCollector：轻量收集，零 Token
+ * - TraceAnalyzer：统计汇总，异常检测
+ * - ConstraintDoctor：Agent 诊断接口
+ * - ConstraintEvolver：约束提案流程
+ *
+ * Performance Trace 系统：
+ * - PerformanceCollector：性能日志收集，零 Token
+ * - PerformanceAnalyzer：统计汇总，异常检测
+ */
+
+export * from './traces';
+export * from './trace-analyzer';
+export * from './constraint-doctor';
+export * from './constraint-evolver';
+export * from './performance-collector';
+export * from './performance-analyzer';
+export * from './context-tracker';
+export { KnowledgeDoctor } from './knowledge-doctor';
+export { KnowledgeEvolver } from './knowledge-evolver';

package/src/monitoring/knowledge-doctor.ts

@@ -0,0 +1,323 @@
+/**
+ * 知识库健康诊断
+ *
+ * 从 ConstraintDoctor 转型，聚焦知识库健康：
+ * - 孤儿条目检测
+ * - 矛盾检测
+ * - 过时检测
+ * - 成熟度异常
+ * - 引用健康度
+ */
+
+import type { KnowledgeEntry, LintIssue } from '../knowledge/types';
+import type { ConstraintStats } from '../constraints/types';
+
+// ── 诊断类型 ─────────────────────────────────────────────
+
+export type DiagnosisSeverity = 'low' | 'medium' | 'high' | 'critical';
+
+export interface KnowledgeDiagnosis {
+  id: string;
+  type: 'orphan' | 'contradiction' | 'outdated' | 'decay' | 'low_reference' | 'stale_index';
+  severity: DiagnosisSeverity;
+  entryId?: string;
+  title: string;
+  description: string;
+  rootCause: string;
+  impact: string;
+  recommendations: string[];
+  timestamp: string;
+}
+
+export interface DiagnosisReport {
+  timestamp: string;
+  totalEntries: number;
+  healthScore: number; // 0-100
+  diagnoses: KnowledgeDiagnosis[];
+  summary: Record<DiagnosisSeverity, number>;
+}
+
+// ── 配置 ─────────────────────────────────────────────────
+
+export interface KnowledgeDoctorConfig {
+  /** 低引用阈值（低于此值标记为 low_reference） */
+  lowReferenceThreshold?: number;
+  /** 过时天数（超过此天数未引用标记为 outdated） */
+  outdatedDays?: number;
+  /** 衰减预警天数 */
+  decayWarningDays?: number;
+}
+
+const DEFAULT_CONFIG: Required<KnowledgeDoctorConfig> = {
+  lowReferenceThreshold: 2,
+  outdatedDays: 180,
+  decayWarningDays: 90,
+};
+
+// ── 知识库诊断器 ─────────────────────────────────────────
+
+export class KnowledgeDoctor {
+  private config: Required<KnowledgeDoctorConfig>;
+
+  constructor(config?: KnowledgeDoctorConfig) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * 诊断知识库健康
+   */
+  diagnose(entries: KnowledgeEntry[], lintIssues: LintIssue[] = []): DiagnosisReport {
+    const diagnoses: KnowledgeDiagnosis[] = [];
+
+    // 从 lint issues 转换
+    diagnoses.push(...this.fromLintIssues(lintIssues));
+
+    // 知识库特有诊断
+    diagnoses.push(...this.checkOrphans(entries));
+    diagnoses.push(...this.checkOutdated(entries));
+    diagnoses.push(...this.checkDecay(entries));
+    diagnoses.push(...this.checkLowReference(entries));
+
+    // 计算健康分数
+    const healthScore = this.calculateHealthScore(entries, diagnoses);
+
+    // 统计
+    const summary: Record<DiagnosisSeverity, number> = {
+      low: 0,
+      medium: 0,
+      high: 0,
+      critical: 0,
+    };
+    for (const d of diagnoses) {
+      summary[d.severity]++;
+    }
+
+    return {
+      timestamp: new Date().toISOString(),
+      totalEntries: entries.length,
+      healthScore,
+      diagnoses,
+      summary,
+    };
+  }
+
+  /**
+   * 从 Lint issues 生成诊断
+   */
+  private fromLintIssues(issues: LintIssue[]): KnowledgeDiagnosis[] {
+    return issues.map(issue => ({
+      id: `lint-${issue.type}-${issue.entryId ?? 'unknown'}`,
+      type: issue.type as KnowledgeDiagnosis['type'],
+      severity: issue.severity,
+      entryId: issue.entryId,
+      title: issue.description,
+      description: issue.description,
+      rootCause: this.inferRootCause(issue),
+      impact: this.inferImpact(issue),
+      recommendations: [issue.suggestion],
+      timestamp: new Date().toISOString(),
+    }));
+  }
+
+  /**
+   * 检查孤儿条目
+   */
+  private checkOrphans(entries: KnowledgeEntry[]): KnowledgeDiagnosis[] {
+    const diagnoses: KnowledgeDiagnosis[] = [];
+
+    for (const entry of entries) {
+      if (entry.maturity === 'archived') continue;
+
+      const hasRefs = entry.referencedBy.length > 0;
+      const hasContributors = entry.contributors.length > 0;
+      const hasProjects = entry.projects.length > 0;
+
+      if (!hasRefs && !hasContributors && !hasProjects && entry.maturity === 'draft') {
+        diagnoses.push({
+          id: `orphan-${entry.id}`,
+          type: 'orphan',
+          severity: 'low',
+          entryId: entry.id,
+          title: `孤儿条目: ${entry.title}`,
+          description: `条目 ${entry.id} 无引用、无贡献者、无项目验证`,
+          rootCause: '条目可能是自动生成但未被任何工作流引用',
+          impact: '占用知识库空间但不产生价值',
+          recommendations: ['归档该条目', '或标记为需要验证后等待引用'],
+          timestamp: new Date().toISOString(),
+        });
+      }
+    }
+
+    return diagnoses;
+  }
+
+  /**
+   * 检查过时条目
+   */
+  private checkOutdated(entries: KnowledgeEntry[]): KnowledgeDiagnosis[] {
+    const diagnoses: KnowledgeDiagnosis[] = [];
+    const threshold = new Date();
+    threshold.setDate(threshold.getDate() - this.config.outdatedDays);
+
+    for (const entry of entries) {
+      if (entry.maturity === 'archived') continue;
+      if (entry.maturity !== 'draft') continue;
+
+      const lastRef = entry.lastReferenced ? new Date(entry.lastReferenced) : new Date(entry.created);
+      if (lastRef < threshold) {
+        diagnoses.push({
+          id: `outdated-${entry.id}`,
+          type: 'outdated',
+          severity: 'medium',
+          entryId: entry.id,
+          title: `过时条目: ${entry.title}`,
+          description: `条目 ${entry.id} 超过 ${this.config.outdatedDays} 天未引用且为 draft`,
+          rootCause: '长期未被引用，可能已失去相关性',
+          impact: '降低知识库整体质量',
+          recommendations: ['归档该条目', '或验证后提升成熟度'],
+          timestamp: new Date().toISOString(),
+        });
+      }
+    }
+
+    return diagnoses;
+  }
+
+  /**
+   * 检查衰减预警
+   */
+  private checkDecay(entries: KnowledgeEntry[]): KnowledgeDiagnosis[] {
+    const diagnoses: KnowledgeDiagnosis[] = [];
+    const warningThreshold = new Date();
+    warningThreshold.setDate(warningThreshold.getDate() - this.config.decayWarningDays);
+
+    for (const entry of entries) {
+      if (entry.maturity !== 'proven' && entry.maturity !== 'verified') continue;
+
+      const lastRef = entry.lastReferenced ? new Date(entry.lastReferenced) : new Date(entry.created);
+      if (lastRef < warningThreshold) {
+        diagnoses.push({
+          id: `decay-${entry.id}`,
+          type: 'decay',
+          severity: entry.maturity === 'proven' ? 'high' : 'medium',
+          entryId: entry.id,
+          title: `衰减预警: ${entry.title}`,
+          description: `${entry.maturity} 条目 ${entry.id} 超过 ${this.config.decayWarningDays} 天未引用`,
+          rootCause: '长期未被引用，成熟度可能需要降级',
+          impact: '高成熟度条目未被引用，可能已过时',
+          recommendations: ['检查条目是否仍然相关', '如已过时则降级成熟度'],
+          timestamp: new Date().toISOString(),
+        });
+      }
+    }
+
+    return diagnoses;
+  }
+
+  /**
+   * 检查低引用条目
+   */
+  private checkLowReference(entries: KnowledgeEntry[]): KnowledgeDiagnosis[] {
+    const diagnoses: KnowledgeDiagnosis[] = [];
+
+    for (const entry of entries) {
+      if (entry.maturity === 'archived') continue;
+      if (entry.maturity === 'draft') continue;
+
+      if (entry.referencedBy.length < this.config.lowReferenceThreshold) {
+        diagnoses.push({
+          id: `low-ref-${entry.id}`,
+          type: 'low_reference',
+          severity: 'low',
+          entryId: entry.id,
+          title: `低引用: ${entry.title}`,
+          description: `${entry.maturity} 条目 ${entry.id} 仅被引用 ${entry.referencedBy.length} 次`,
+          rootCause: '条目可能不够通用或不易被发现',
+          impact: '高成熟度但低引用，投入产出比低',
+          recommendations: ['检查条目是否需要更新以提高相关性', '考虑在更多场景中引用'],
+          timestamp: new Date().toISOString(),
+        });
+      }
+    }
+
+    return diagnoses;
+  }
+
+  /**
+   * 计算健康分数（0-100）
+   */
+  private calculateHealthScore(entries: KnowledgeEntry[], diagnoses: KnowledgeDiagnosis[]): number {
+    if (entries.length === 0) return 100;
+
+    let penalty = 0;
+    for (const d of diagnoses) {
+      switch (d.severity) {
+        case 'critical': penalty += 10; break;
+        case 'high': penalty += 5; break;
+        case 'medium': penalty += 2; break;
+        case 'low': penalty += 1; break;
+      }
+    }
+
+    // 每个条目的最大扣分
+    const maxPenalty = entries.length * 10;
+    const score = Math.max(0, 100 - Math.round((penalty / Math.max(maxPenalty, 1)) * 100));
+    return score;
+  }
+
+  private inferRootCause(issue: LintIssue): string {
+    switch (issue.type) {
+      case 'orphan': return '条目未被任何工作流或项目引用';
+      case 'contradiction': return '同标签下存在成熟度差异大的条目';
+      case 'outdated': return '长期未引用的 draft 条目';
+      case 'duplicate': return '同类型同标题的重复条目';
+      case 'index_inconsistent': return '索引与磁盘文件不一致';
+      default: return '未知原因';
+    }
+  }
+
+  private inferImpact(issue: LintIssue): string {
+    switch (issue.type) {
+      case 'orphan': return '占用空间但不产生价值';
+      case 'contradiction': return '可能误导 Agent 决策';
+      case 'outdated': return '降低知识库整体质量';
+      case 'duplicate': return '浪费查询预算';
+      case 'index_inconsistent': return '可能导致查询失败';
+      default: return '未知影响';
+    }
+  }
+
+  /**
+   * 生成诊断报告（Markdown）
+   */
+  generateReport(report: DiagnosisReport): string {
+    const lines: string[] = [];
+
+    lines.push(`# 知识库健康报告`);
+    lines.push(`时间: ${report.timestamp}`);
+    lines.push(`条目总数: ${report.totalEntries}`);
+    lines.push(`健康分数: ${report.healthScore}/100`);
+    lines.push('');
+
+    lines.push(`## 问题统计`);
+    lines.push(`- 严重: ${report.summary.critical}`);
+    lines.push(`- 高: ${report.summary.high}`);
+    lines.push(`- 中: ${report.summary.medium}`);
+    lines.push(`- 低: ${report.summary.low}`);
+    lines.push('');
+
+    if (report.diagnoses.length > 0) {
+      lines.push(`## 诊断详情`);
+      for (const d of report.diagnoses) {
+        lines.push(`### [${d.severity.toUpperCase()}] ${d.title}`);
+        lines.push(d.description);
+        lines.push(`**根因**: ${d.rootCause}`);
+        lines.push(`**影响**: ${d.impact}`);
+        lines.push(`**建议**: ${d.recommendations.join(', ')}`);
+        lines.push('');
+      }
+    }
+
+    return lines.join('\n');
+  }
+}

package/src/monitoring/knowledge-evolver.ts

@@ -0,0 +1,289 @@
+/**
+ * 知识成熟度进化器
+ *
+ * 从 ConstraintEvolver 转型，聚焦知识成熟度进化：
+ * - 基于引用数据提议成熟度变更
+ * - 自动审核（安全规则）
+ * - 执行变更
+ */
+
+import type { KnowledgeEntry, MaturityLevel } from '../knowledge/types';
+import type { KnowledgeDiagnosis } from './knowledge-doctor';
+import { KnowledgeStore } from '../knowledge/store';
+
+// ── 进化提案 ─────────────────────────────────────────────
+
+export type ProposalAction = 'promote' | 'demote' | 'archive' | 'merge' | 'freeze';
+
+export interface EvolutionProposal {
+  id: string;
+  entryId: string;
+  action: ProposalAction;
+  currentMaturity: MaturityLevel;
+  targetMaturity: MaturityLevel;
+  reason: string;
+  evidence: string[];
+  risk: 'low' | 'medium' | 'high';
+  autoApprovable: boolean;
+  status: 'pending' | 'approved' | 'rejected' | 'implemented';
+  createdAt: string;
+}
+
+export interface EvolutionReport {
+  timestamp: string;
+  proposals: EvolutionProposal[];
+  summary: Record<ProposalAction, number>;
+}
+
+// ── 配置 ─────────────────────────────────────────────────
+
+export interface KnowledgeEvolverConfig {
+  /** 升级所需最小引用次数 */
+  promoteThreshold?: number;
+  /** 降级触发天数（未引用） */
+  demoteDays?: number;
+  /** 是否自动执行低风险提案 */
+  autoImplement?: boolean;
+}
+
+const DEFAULT_CONFIG: Required<KnowledgeEvolverConfig> = {
+  promoteThreshold: 2,
+  demoteDays: 180,
+  autoImplement: false,
+};
+
+// ── 成熟度进化规则 ───────────────────────────────────────
+
+const MATURITY_ORDER: MaturityLevel[] = ['draft', 'verified', 'proven'];
+
+function nextMaturity(current: MaturityLevel): MaturityLevel | undefined {
+  const idx = MATURITY_ORDER.indexOf(current);
+  return idx < MATURITY_ORDER.length - 1 ? MATURITY_ORDER[idx + 1] : undefined;
+}
+
+function prevMaturity(current: MaturityLevel): MaturityLevel | undefined {
+  const idx = MATURITY_ORDER.indexOf(current);
+  return idx > 0 ? MATURITY_ORDER[idx - 1] : undefined;
+}
+
+// ── 知识进化器 ───────────────────────────────────────────
+
+export class KnowledgeEvolver {
+  private config: Required<KnowledgeEvolverConfig>;
+  private store?: KnowledgeStore;
+
+  constructor(config?: KnowledgeEvolverConfig, store?: KnowledgeStore) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.store = store;
+  }
+
+  /**
+   * 从知识条目和诊断生成进化提案
+   */
+  generateProposals(
+    entries: KnowledgeEntry[],
+    diagnoses: KnowledgeDiagnosis[] = [],
+  ): EvolutionProposal[] {
+    const proposals: EvolutionProposal[] = [];
+
+    for (const entry of entries) {
+      if (entry.maturity === 'archived') continue;
+
+      // 升级检查
+      const promoteProposal = this.checkPromote(entry);
+      if (promoteProposal) proposals.push(promoteProposal);
+
+      // 降级检查
+      const demoteProposal = this.checkDemote(entry);
+      if (demoteProposal) proposals.push(demoteProposal);
+    }
+
+    // 从诊断生成提案
+    for (const diagnosis of diagnoses) {
+      if (diagnosis.type === 'contradiction' && diagnosis.entryId) {
+        const entry = entries.find(e => e.id === diagnosis.entryId);
+        if (entry) {
+          proposals.push({
+            id: `freeze-${entry.id}-${Date.now()}`,
+            entryId: entry.id,
+            action: 'freeze',
+            currentMaturity: entry.maturity,
+            targetMaturity: entry.maturity,
+            reason: diagnosis.description,
+            evidence: [diagnosis.rootCause],
+            risk: 'medium',
+            autoApprovable: false,
+            status: 'pending',
+            createdAt: new Date().toISOString(),
+          });
+        }
+      }
+    }
+
+    return proposals;
+  }
+
+  /**
+   * 检查是否可以升级
+   */
+  private checkPromote(entry: KnowledgeEntry): EvolutionProposal | undefined {
+    const target = nextMaturity(entry.maturity);
+    if (!target) return undefined;
+
+    const refCount = entry.referencedBy.length;
+    const projectCount = entry.projects.length;
+
+    // draft → verified: 需要至少 1 次引用
+    if (entry.maturity === 'draft' && refCount >= 1) {
+      return this.createProposal(entry, 'promote', target,
+        `被引用 ${refCount} 次，可以升级为 verified`,
+        [`引用次数: ${refCount}`],
+        'low',
+      );
+    }
+
+    // verified → proven: 需要 ≥2 个项目验证
+    if (entry.maturity === 'verified' && projectCount >= this.config.promoteThreshold) {
+      return this.createProposal(entry, 'promote', target,
+        `被 ${projectCount} 个项目验证，可以升级为 proven`,
+        [`项目数: ${projectCount}`],
+        'low',
+      );
+    }
+
+    return undefined;
+  }
+
+  /**
+   * 检查是否应该降级
+   */
+  private checkDemote(entry: KnowledgeEntry): EvolutionProposal | undefined {
+    const target = prevMaturity(entry.maturity);
+    if (!target) return undefined;
+
+    const lastRef = entry.lastReferenced
+      ? new Date(entry.lastReferenced)
+      : new Date(entry.created);
+    const daysSinceRef = Math.floor(
+      (Date.now() - lastRef.getTime()) / (1000 * 60 * 60 * 24),
+    );
+
+    if (daysSinceRef >= this.config.demoteDays) {
+      return this.createProposal(entry, 'demote', target,
+        `超过 ${this.config.demoteDays} 天未引用，建议降级`,
+        [`最后引用: ${daysSinceRef} 天前`],
+        'low',
+      );
+    }
+
+    return undefined;
+  }
+
+  private createProposal(
+    entry: KnowledgeEntry,
+    action: ProposalAction,
+    targetMaturity: MaturityLevel,
+    reason: string,
+    evidence: string[],
+    risk: 'low' | 'medium' | 'high',
+  ): EvolutionProposal {
+    return {
+      id: `${action}-${entry.id}-${Date.now()}`,
+      entryId: entry.id,
+      action,
+      currentMaturity: entry.maturity,
+      targetMaturity,
+      reason,
+      evidence,
+      risk,
+      autoApprovable: risk === 'low',
+      status: 'pending',
+      createdAt: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * 审核提案（规则自动审核）
+   */
+  review(proposal: EvolutionProposal): { approved: boolean; reason: string } {
+    // 安全规则：proven 不允许直接归档
+    if (proposal.currentMaturity === 'proven' && proposal.action === 'archive') {
+      return { approved: false, reason: 'proven 条目不允许直接归档，需先降级' };
+    }
+
+    // 安全规则：矛盾条目不允许升级
+    if (proposal.action === 'promote' && proposal.risk === 'high') {
+      return { approved: false, reason: '高风险提案需要人工审核' };
+    }
+
+    // 低风险自动通过
+    if (proposal.risk === 'low' && proposal.autoApprovable) {
+      return { approved: true, reason: '低风险提案自动通过' };
+    }
+
+    return { approved: true, reason: '提案通过审核' };
+  }
+
+  /**
+   * 执行提案
+   */
+  implement(proposal: EvolutionProposal): boolean {
+    if (!this.store) return false;
+    if (proposal.status !== 'approved') return false;
+
+    const entry = this.store.get(proposal.entryId);
+    if (!entry) return false;
+
+    switch (proposal.action) {
+      case 'promote':
+      case 'demote':
+        this.store.update(proposal.entryId, { maturity: proposal.targetMaturity });
+        break;
+      case 'archive':
+        this.store.update(proposal.entryId, { maturity: 'archived' as MaturityLevel });
+        break;
+      case 'freeze':
+        // 冻结：不修改成熟度，只标记
+        break;
+      default:
+        return false;
+    }
+
+    proposal.status = 'implemented';
+    return true;
+  }
+
+  /**
+   * 批量审核 + 执行
+   */
+  processProposals(proposals: EvolutionProposal[]): EvolutionReport {
+    for (const proposal of proposals) {
+      const review = this.review(proposal);
+      if (review.approved) {
+        proposal.status = 'approved';
+        if (this.config.autoImplement && proposal.autoApprovable) {
+          this.implement(proposal);
+        }
+      } else {
+        proposal.status = 'rejected';
+      }
+    }
+
+    const summary: Record<ProposalAction, number> = {
+      promote: 0,
+      demote: 0,
+      archive: 0,
+      merge: 0,
+      freeze: 0,
+    };
+    for (const p of proposals) {
+      summary[p.action]++;
+    }
+
+    return {
+      timestamp: new Date().toISOString(),
+      proposals,
+      summary,
+    };
+  }
+}