@dommaker/harness 0.16.6 → 0.16.8

package/src/monitoring/analyzer-base.ts

@@ -0,0 +1,112 @@
+/**
+ * 分析器共享基础（工单 19-D）
+ *
+ * TraceAnalyzer 与 PerformanceAnalyzer 的镜像同构部分收敛于此：
+ * 分组、时间范围、统计助手、summary 文件读写。
+ * 两个分析器保持各自的公开类接口（P1 符号冻结），仅内部复用。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+export type Trend = 'stable' | 'rising' | 'falling';
+
+/**
+ * 按键分组（保持插入顺序）
+ */
+export function groupByKey<T>(items: T[], keyOf: (item: T) => string): Map<string, T[]> {
+  const grouped = new Map<string, T[]>();
+  for (const item of items) {
+    const key = keyOf(item);
+    const existing = grouped.get(key) || [];
+    existing.push(item);
+    grouped.set(key, existing);
+  }
+  return grouped;
+}
+
+/**
+ * 时间戳序列的起止范围
+ */
+export function timeRangeOf(timestamps: number[]): { start: number; end: number } {
+  return {
+    start: Math.min(...timestamps),
+    end: Math.max(...timestamps),
+  };
+}
+
+/**
+ * 找出出现次数最多的元素
+ */
+export function findMostCommon(items: string[]): string | undefined {
+  if (items.length === 0) return undefined;
+
+  const counts = new Map<string, number>();
+  for (const item of items) {
+    counts.set(item, (counts.get(item) || 0) + 1);
+  }
+
+  let maxCount = 0;
+  let mostCommon: string | undefined;
+  for (const [item, count] of counts) {
+    if (count > maxCount) {
+      maxCount = count;
+      mostCommon = item;
+    }
+  }
+  return mostCommon;
+}
+
+/**
+ * 平均值
+ */
+export function calcAverage(values: number[]): number {
+  if (values.length === 0) return 0;
+  return values.reduce((sum, v) => sum + v, 0) / values.length;
+}
+
+/**
+ * 百分位数（nearest-rank）
+ */
+export function calcPercentile(values: number[], percentile: number): number {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const index = Math.ceil((percentile / 100) * sorted.length) - 1;
+  return sorted[Math.max(0, index)];
+}
+
+/**
+ * 样本量不足时的趋势兜底阈值
+ */
+export const MIN_TREND_SAMPLES = 10;
+
+/**
+ * 按时间排序后对半分，供前后半段对比
+ */
+export function splitByTime<T extends { timestamp: number }>(items: T[]): [T[], T[]] {
+  const sorted = [...items].sort((a, b) => a.timestamp - b.timestamp);
+  const half = Math.floor(sorted.length / 2);
+  return [sorted.slice(0, half), sorted.slice(half)];
+}
+
+/**
+ * 保存 JSON summary 文件（目录不存在时创建）
+ */
+export function writeSummaryJson(summaryFile: string, data: unknown): void {
+  const dir = path.dirname(summaryFile);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(summaryFile, JSON.stringify(data, null, 2), 'utf-8');
+}
+
+/**
+ * 读取 JSON summary 文件；不存在时返回 null
+ */
+export function readSummaryJson<T>(summaryFile: string): T | null {
+  if (!fs.existsSync(summaryFile)) {
+    return null;
+  }
+  const content = fs.readFileSync(summaryFile, 'utf-8');
+  return JSON.parse(content) as T;
+}

package/src/monitoring/constraint-doctor.ts

@@ -14,66 +14,12 @@ import type {
   TraceAnomaly,
   TraceSummary,
 } from '../types/trace';
+import type { Diagnosis } from '../types/monitoring-types';
 import type { LLMAdapter } from '../llm/types';
+import { DIAGNOSIS_RULES } from './diagnosis-rules';
 
-/**
- * 诊断结果
- */
-export interface Diagnosis {
-  /** 异常 ID */
-  anomalyId: string;
-
-  /** 约束 ID */
-  constraintId: string;
-
-  /** 诊断时间 */
-  diagnosedAt: number;
-
-  /** 根因分析 */
-  rootCause: {
-    /** 主要原因 */
-    primary: string;
-
-    /** 次要原因 */
-    secondary?: string[];
-
-    /** 相关 traces */
-    evidence: ExecutionTrace[];
-  };
-
-  /** 影响评估 */
-  impact: {
-    /** 影响程度 */
-    severity: 'low' | 'medium' | 'high';
-
-    /** 影响范围 */
-    scope: 'single_project' | 'multiple_projects' | 'team';
-
-    /** 用户影响 */
-    userImpact: string;
-  };
-
-  /** 改进建议 */
-  recommendations: {
-    /** 建议类型 */
-    type: 'add_exception' | 'adjust_threshold' | 'modify_constraint' | 'user_training';
-
-    /** 建议内容 */
-    content: string;
-
-    /** 预期效果 */
-    expectedOutcome: string;
-
-    /** 实施成本 */
-    implementationCost: 'low' | 'medium' | 'high';
-  }[];
-
-  /** 是否需要变更 */
-  needsChange: boolean;
-
-  /** 紧急程度 */
-  urgency: 'low' | 'medium' | 'high';
-}
+// 类型定义已归位 types 层（工单 14），此处再导出保持模块公开面不变
+export type { Diagnosis };
 
 /**
  * 诊断配置
@@ -108,7 +54,6 @@ export interface ConstraintDoctorConfig {
 export class ConstraintDoctor {
   private config: ConstraintDoctorConfig;
   private traces: ExecutionTrace[];
-  private summary: TraceSummary | null;
   private llm: LLMAdapter | null;
 
   constructor(config?: ConstraintDoctorConfig, llm?: LLMAdapter) {
@@ -119,16 +64,14 @@ export class ConstraintDoctor {
       ...config,
     };
     this.traces = [];
-    this.summary = null;
     this.llm = llm || null;
   }
 
   /**
    * 设置诊断数据
    */
-  setData(traces: ExecutionTrace[], summary?: TraceSummary): void {
+  setData(traces: ExecutionTrace[], _summary?: TraceSummary): void {
     this.traces = traces;
-    this.summary = summary || null;
   }
 
   /**
@@ -184,119 +127,15 @@ export class ConstraintDoctor {
       urgency: 'low',
     };
 
-    // 根据异常类型诊断
-    switch (anomaly.type) {
-      case 'high_bypass_rate':
-        diagnosis.rootCause.primary = '约束过于严格，用户频繁绕过';
-        diagnosis.rootCause.secondary = [
-          '约束触发条件过于宽泛',
-          '缺乏必要的例外条件',
-          '约束定义与实际场景不匹配',
-        ];
-        diagnosis.impact.userImpact = '用户被迫绕过约束，降低信任度';
-        diagnosis.recommendations = [
-          {
-            type: 'add_exception',
-            content: `为约束 ${anomaly.constraintId} 添加常见例外条件`,
-            expectedOutcome: '绕过率降低至 20% 以下',
-            implementationCost: 'low',
-          },
-          {
-            type: 'adjust_threshold',
-            content: '调整触发条件，减少误触发',
-            expectedOutcome: '减少不必要的约束检查',
-            implementationCost: 'medium',
-          },
-        ];
-        diagnosis.needsChange = true;
-        diagnosis.urgency = anomaly.data.currentRate > 0.5 ? 'high' : 'medium';
-        break;
-
-      case 'rising_fail_rate':
-        diagnosis.rootCause.primary = '约束失败率呈上升趋势';
-        diagnosis.rootCause.secondary = [
-          '代码质量下降',
-          '约束检查逻辑存在 bug',
-          '环境变化导致约束不再适用',
-        ];
-        diagnosis.impact.userImpact = '开发效率下降，约束频繁阻止正常操作';
-        diagnosis.recommendations = [
-          {
-            type: 'modify_constraint',
-            content: '审查约束逻辑，确认是否符合预期',
-            expectedOutcome: '恢复正常的失败率水平',
-            implementationCost: 'medium',
-          },
-          {
-            type: 'user_training',
-            content: '指导用户正确理解约束要求',
-            expectedOutcome: '减少因误解导致的失败',
-            implementationCost: 'low',
-          },
-        ];
-        diagnosis.needsChange = true;
-        diagnosis.urgency = 'medium';
-        break;
-
-      case 'rising_bypass_rate':
-        diagnosis.rootCause.primary = '绕过率呈上升趋势';
-        diagnosis.rootCause.secondary = [
-          '用户对约束的接受度下降',
-          '约束规则逐渐不适应新的开发模式',
-          '用户发现了绕过约束的"捷径"',
-        ];
-        diagnosis.impact.userImpact = '约束逐渐失去约束力';
-        diagnosis.recommendations = [
-          {
-            type: 'modify_constraint',
-            content: '重新评估约束的必要性',
-            expectedOutcome: '恢复约束的权威性',
-            implementationCost: 'high',
-          },
-        ];
-        diagnosis.needsChange = true;
-        diagnosis.urgency = 'high';
-        break;
-
-      case 'low_pass_rate':
-        diagnosis.rootCause.primary = '约束通过率过低';
-        diagnosis.rootCause.secondary = [
-          '约束要求过于严格',
-          '实际代码质量不达标',
-          '约束定义存在歧义',
-        ];
-        diagnosis.impact.userImpact = '几乎所有操作都被阻止，开发受阻';
-        diagnosis.recommendations = [
-          {
-            type: 'adjust_threshold',
-            content: '放宽约束要求，设置合理阈值',
-            expectedOutcome: '通过率提升至 50% 以上',
-            implementationCost: 'low',
-          },
-        ];
-        diagnosis.needsChange = true;
-        diagnosis.urgency = 'high';
-        break;
-
-      case 'exception_overuse':
-        diagnosis.rootCause.primary = '例外条件被过度使用';
-        diagnosis.rootCause.secondary = [
-          '例外条件过于宽泛',
-          '例外条件定义不够精确',
-          '用户习惯性申请例外',
-        ];
-        diagnosis.impact.userImpact = '例外成为常态，约束失去意义';
-        diagnosis.recommendations = [
-          {
-            type: 'modify_constraint',
-            content: '缩小例外条件范围，提高例外门槛',
-            expectedOutcome: '例外使用率降低至 20% 以下',
-            implementationCost: 'medium',
-          },
-        ];
-        diagnosis.needsChange = true;
-        diagnosis.urgency = 'medium';
-        break;
+    // 根据异常类型诊断（工单 23-B：规则数据化，见 diagnosis-rules.ts）
+    const rule = DIAGNOSIS_RULES[anomaly.type];
+    if (rule) {
+      diagnosis.rootCause.primary = rule.primary;
+      diagnosis.rootCause.secondary = rule.secondary;
+      diagnosis.impact.userImpact = rule.userImpact;
+      diagnosis.recommendations = rule.recommendations(anomaly);
+      diagnosis.needsChange = rule.needsChange;
+      diagnosis.urgency = rule.urgency(anomaly);
     }
 
     // 根据约束层级调整严重性

package/src/monitoring/constraint-evolver.ts

@@ -9,94 +9,20 @@
  * - ~3000 Token/次
  */
 
-import type { Diagnosis } from './constraint-doctor';
 import type {
-  Constraint,
-  ConstraintLevel,
-} from '../types/constraint';
-import { IRON_LAWS, GUIDELINES, TIPS } from '../core/constraints/definitions';
+  Diagnosis,
+  ConstraintProposal,
+  ProposalReviewResult,
+} from '../types/monitoring-types';
+import type { Constraint } from '../types/constraint';
 
-/**
- * 约束提案
- */
-export interface ConstraintProposal {
-  /** 提案 ID */
-  id: string;
-
-  /** 提案时间 */
-  proposedAt: number;
-
-  /** 来源诊断 */
-  diagnosisId: string;
-
-  /** 约束 ID */
-  constraintId: string;
-
-  /** 提案类型 */
-  type: 'add_exception' | 'remove_exception' | 'adjust_trigger' | 'change_level' | 'modify_message' | 'new_constraint';
-
-  /** 提案内容 */
-  content: {
-    /** 当前值（如果有） */
-    current?: any;
-
-    /** 建议值 */
-    proposed: any;
-
-    /** 变更描述 */
-    description: string;
-  };
-
-  /** 理由 */
-  reasoning: string;
-
-  /** 预期效果 */
-  expectedOutcome: string;
-
-  /** 风险评估 */
-  risk: {
-    /** 风险等级 */
-    level: 'low' | 'medium' | 'high';
-
-    /** 风险描述 */
-    description: string;
-
-    /** 回滚方案 */
-    rollbackPlan?: string;
-  };
-
-  /** 实施信息 */
-  implementation: {
-    /** 改动文件 */
-    files: string[];
-
-    /** 改动量估计 */
-    linesChanged: number;
-
-    /** 测试要求 */
-    testsRequired: boolean;
-  };
-
-  /** 状态 */
-  status: 'proposed' | 'reviewing' | 'accepted' | 'rejected' | 'implemented';
-
-  /** 审核意见 */
-  reviewComment?: string;
-}
+// 类型定义已归位 types 层（工单 14），此处再导出保持模块公开面不变
+export type { ConstraintProposal, ProposalReviewResult };
 
 /**
- * 提案审核结果
+ * 约束查找函数（工单 15：约束集参数化，替代对 core/constraints/definitions 的值依赖）
  */
-export interface ProposalReviewResult {
-  /** 是否接受 */
-  accepted: boolean;
-
-  /** 审核意见 */
-  comment: string;
-
-  /** 修改建议（如果拒绝） */
-  modifications?: Partial<ConstraintProposal>;
-}
+export type ConstraintLookup = (constraintId: string) => Constraint | null | undefined;
 
 /**
  * Constraint Evolver - 约束进化器
@@ -117,9 +43,11 @@ export interface ProposalReviewResult {
  */
 export class ConstraintEvolver {
   private proposalsDir: string;
+  private constraintLookup: ConstraintLookup | undefined;
 
-  constructor(proposalsDir?: string) {
+  constructor(proposalsDir?: string, constraintLookup?: ConstraintLookup) {
     this.proposalsDir = proposalsDir || '.harness/proposals';
+    this.constraintLookup = constraintLookup;
   }
 
   /**
@@ -495,7 +423,7 @@ export class ConstraintEvolver {
   /**
    * 估算实施信息
    */
-  private estimateImplementation(constraintId: string): ConstraintProposal['implementation'] {
+  private estimateImplementation(_constraintId: string): ConstraintProposal['implementation'] {
     return {
       files: ['src/core/constraints/definitions.ts'],
       linesChanged: 10, // 通常只需修改几行
@@ -504,13 +432,10 @@ export class ConstraintEvolver {
   }
 
   /**
-   * 查找约束定义
+   * 查找约束定义（经注入的 lookup；未注入时返回 null）
    */
   private findConstraint(constraintId: string): Constraint | null {
-    return IRON_LAWS[constraintId] ||
-           GUIDELINES[constraintId] ||
-           TIPS[constraintId] ||
-           null;
+    return this.constraintLookup?.(constraintId) ?? null;
   }
 
   /**
@@ -568,6 +493,9 @@ export class ConstraintEvolver {
 /**
  * 创建进化器
  */
-export function createEvolver(proposalsDir?: string): ConstraintEvolver {
-  return new ConstraintEvolver(proposalsDir);
+export function createEvolver(
+  proposalsDir?: string,
+  constraintLookup?: ConstraintLookup
+): ConstraintEvolver {
+  return new ConstraintEvolver(proposalsDir, constraintLookup);
 }

package/src/monitoring/diagnosis-rules.ts

@@ -0,0 +1,132 @@
+/**
+ * 诊断规则表（工单 23-B）
+ *
+ * constraint-doctor.ruleBasedDiagnose 的巨型 switch 数据化：
+ * 每种异常类型一条规则（根因/影响/建议/紧急度），新增异常类型只需加表项。
+ */
+
+import type { TraceAnomaly } from '../types/trace';
+import type { Diagnosis } from '../types/monitoring-types';
+
+export interface DiagnosisRule {
+  primary: string;
+  secondary: string[];
+  userImpact: string;
+  recommendations: (anomaly: TraceAnomaly) => Diagnosis['recommendations'];
+  needsChange: boolean;
+  urgency: (anomaly: TraceAnomaly) => Diagnosis['urgency'];
+}
+
+export const DIAGNOSIS_RULES: Record<string, DiagnosisRule> = {
+  high_bypass_rate: {
+    primary: '约束过于严格，用户频繁绕过',
+    secondary: [
+      '约束触发条件过于宽泛',
+      '缺乏必要的例外条件',
+      '约束定义与实际场景不匹配',
+    ],
+    userImpact: '用户被迫绕过约束，降低信任度',
+    recommendations: (anomaly) => [
+      {
+        type: 'add_exception',
+        content: `为约束 ${anomaly.constraintId} 添加常见例外条件`,
+        expectedOutcome: '绕过率降低至 20% 以下',
+        implementationCost: 'low',
+      },
+      {
+        type: 'adjust_threshold',
+        content: '调整触发条件，减少误触发',
+        expectedOutcome: '减少不必要的约束检查',
+        implementationCost: 'medium',
+      },
+    ],
+    needsChange: true,
+    urgency: (anomaly) => ((anomaly.data.currentRate as number) > 0.5 ? 'high' : 'medium'),
+  },
+
+  rising_fail_rate: {
+    primary: '约束失败率呈上升趋势',
+    secondary: [
+      '代码质量下降',
+      '约束检查逻辑存在 bug',
+      '环境变化导致约束不再适用',
+    ],
+    userImpact: '开发效率下降，约束频繁阻止正常操作',
+    recommendations: () => [
+      {
+        type: 'modify_constraint',
+        content: '审查约束逻辑，确认是否符合预期',
+        expectedOutcome: '恢复正常的失败率水平',
+        implementationCost: 'medium',
+      },
+      {
+        type: 'user_training',
+        content: '指导用户正确理解约束要求',
+        expectedOutcome: '减少因误解导致的失败',
+        implementationCost: 'low',
+      },
+    ],
+    needsChange: true,
+    urgency: () => 'medium',
+  },
+
+  rising_bypass_rate: {
+    primary: '绕过率呈上升趋势',
+    secondary: [
+      '用户对约束的接受度下降',
+      '约束规则逐渐不适应新的开发模式',
+      '用户发现了绕过约束的"捷径"',
+    ],
+    userImpact: '约束逐渐失去约束力',
+    recommendations: () => [
+      {
+        type: 'modify_constraint',
+        content: '重新评估约束的必要性',
+        expectedOutcome: '恢复约束的权威性',
+        implementationCost: 'high',
+      },
+    ],
+    needsChange: true,
+    urgency: () => 'high',
+  },
+
+  low_pass_rate: {
+    primary: '约束通过率过低',
+    secondary: [
+      '约束要求过于严格',
+      '实际代码质量不达标',
+      '约束定义存在歧义',
+    ],
+    userImpact: '几乎所有操作都被阻止，开发受阻',
+    recommendations: () => [
+      {
+        type: 'adjust_threshold',
+        content: '放宽约束要求，设置合理阈值',
+        expectedOutcome: '通过率提升至 50% 以上',
+        implementationCost: 'low',
+      },
+    ],
+    needsChange: true,
+    urgency: () => 'high',
+  },
+
+  exception_overuse: {
+    primary: '例外条件被过度使用',
+    secondary: [
+      '例外条件过于宽泛',
+      '例外条件定义不够精确',
+      '用户习惯性申请例外',
+    ],
+    userImpact: '例外成为常态，约束失去意义',
+    recommendations: () => [
+      {
+        type: 'modify_constraint',
+        content: '缩小例外条件范围，提高例外门槛',
+        expectedOutcome: '例外使用率降低至 20% 以下',
+        implementationCost: 'medium',
+      },
+    ],
+    needsChange: true,
+    urgency: () => 'medium',
+  },
+};

package/src/monitoring/knowledge-doctor.ts

@@ -10,7 +10,6 @@
  */
 
 import type { KnowledgeEntry, LintIssue } from '../knowledge/types';
-import type { ConstraintStats } from '../constraints/types';
 
 // ── 诊断类型 ─────────────────────────────────────────────