@dommaker/harness 1.1.0 → 1.2.0

package/src/types/monitoring-types.ts

@@ -1,68 +0,0 @@
-/**
- * 监控域类型（诊断）
- *
- * 原定义位于 monitoring/constraint-doctor.ts，
- * 但被 types/index.ts 反向再导出（类型层依赖业务模块，分层倒挂）。
- * 工单 14 将类型定义归位到 types 层，monitoring 改从 types 导入。
- */
-
-import type { ExecutionTrace } from './trace';
-
-/**
- * 诊断结果
- */
-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';
-}

package/src/types/performance.ts

@@ -1,295 +0,0 @@
-/**
- * Performance Trace 类型定义
- *
- * 轻量设计：只记录核心信息，零 Token 成本
- *
- * 与 ExecutionTrace 的区别：
- * - ExecutionTrace: 记录约束检查结果（业务行为）
- * - PerformanceTrace: 记录操作耗时（性能指标）
- */
-
-/**
- * 性能追踪记录
- *
- * 设计原则：
- * - 只记录核心字段（零 Token）
- * - 文件存储，追加写入
- * - 支持多种操作类型
- */
-export interface PerformanceTrace {
-  // ========================================
-  // 核心字段（必须）
-  // ========================================
-
-  /** 操作类型 */
-  operation: string;
-
-  /** 时间戳（Unix timestamp） */
-  timestamp: number;
-
-  /** 耗时（毫秒） */
-  duration: number;
-
-  /** 结果 */
-  result: 'ok' | 'exceeded' | 'error';
-
-  // ========================================
-  // 上下文（可选）
-  // ========================================
-
-  /** 阈值（毫秒），用于计算是否超阈值 */
-  threshold?: number;
-
-  /** 项目路径（用于区分多项目） */
-  projectPath?: string;
-
-  /** 会话 ID（用于追踪同一会话的多次操作） */
-  sessionId?: string;
-
-  /** 任务 ID */
-  taskId?: string;
-
-  /** 角色ID（用于角色相关操作） */
-  roleId?: string;
-
-  /** 额外元数据 */
-  metadata?: Record<string, unknown>;
-}
-
-/**
- * 性能统计汇总
- */
-export interface PerformanceSummary {
-  /** 操作类型 */
-  operation: string;
-
-  /** 统计时间范围 */
-  timeRange: {
-    start: number;
-    end: number;
-  };
-
-  // ========================================
-  // 核心统计
-  // ========================================
-
-  /** 总执行次数 */
-  totalCalls: number;
-
-  /** 成功次数 */
-  okCount: number;
-
-  /** 超阈值次数 */
-  exceededCount: number;
-
-  /** 错误次数 */
-  errorCount: number;
-
-  // ========================================
-  // 耗时统计
-  // ========================================
-
-  /** 平均耗时（毫秒） */
-  avgDuration: number;
-
-  /** 最大耗时 */
-  maxDuration: number;
-
-  /** 最小耗时 */
-  minDuration: number;
-
-  /** P95 耗时 */
-  p95Duration: number;
-
-  /** P99 耗时 */
-  p99Duration: number;
-
-  // ========================================
-  // 比率统计
-  // ========================================
-
-  /** 成功率 (0-1) */
-  okRate: number;
-
-  /** 超阈值率 (0-1) */
-  exceededRate: number;
-
-  /** 错误率 (0-1) */
-  errorRate: number;
-
-  // ========================================
-  // 趋势分析
-  // ========================================
-
-  /** 最近趋势 */
-  recentTrend: 'stable' | 'rising' | 'falling';
-
-  /** 对比上一周期的变化 */
-  changeFromLastPeriod?: {
-    avgDurationDelta: number;
-    exceededRateDelta: number;
-  };
-}
-
-/**
- * 性能异常
- */
-export interface PerformanceAnomaly {
-  /** 异常类型 */
-  type:
-    | 'high_avg_duration'      // 平均耗时过高
-    | 'rising_duration'        // 耗时趋势上升
-    | 'high_exceeded_rate'     // 超阈值率过高
-    | 'rising_exceeded_rate'   // 超阈值率上升
-    | 'high_error_rate';       // 错误率过高
-
-  /** 操作类型 */
-  operation: string;
-
-  /** 异常描述 */
-  message: string;
-
-  /** 相关数据 */
-  data: {
-    currentValue: number;
-    threshold: number;
-    trend?: 'rising' | 'falling' | 'stable';
-  };
-
-  /** 检测时间 */
-  detectedAt: number;
-
-  /** 建议的下一步 */
-  suggestedAction?: 'optimize' | 'adjust_threshold' | 'notify_user';
-}
-
-/**
- * 性能追踪过滤条件
- */
-export interface PerformanceTraceFilter {
-  /** 操作类型（可选） */
-  operation?: string;
-
-  /** 结果类型（可选） */
-  result?: 'ok' | 'exceeded' | 'error';
-
-  /** 时间范围（可选） */
-  timeRange?: {
-    start: number;
-    end: number;
-  };
-
-  /** 项目路径（可选） */
-  projectPath?: string;
-
-  /** 会话 ID（可选） */
-  sessionId?: string;
-
-  /** 任务 ID（可选） */
-  taskId?: string;
-
-  /** 角色 ID（可选） */
-  roleId?: string;
-}
-
-/**
- * PerformanceCollector 配置
- */
-export interface PerformanceCollectorConfig {
-  /** 日志文件路径，默认 .harness/logs/performance.log */
-  logFile?: string;
-
-  /** 最大文件大小（字节），超出则滚动，默认 10MB */
-  maxFileSize?: number;
-
-  /** 是否启用（默认 true） */
-  enabled?: boolean;
-}
-
-/**
- * PerformanceAnalyzer 配置
- */
-export interface PerformanceAnalyzerConfig {
-  /** Summary 文件路径 */
-  summaryFile?: string;
-
-  /** 周期长度（毫秒），默认 1 小时 */
-  periodMs?: number;
-
-  /** 异常阈值 */
-  thresholds?: {
-    /** 平均耗时阈值（毫秒），超过则告警 */
-    avgDuration?: number;
-    /** 超阈值率阈值，默认 0.3 */
-    exceededRate?: number;
-    /** 错误率阈值，默认 0.1 */
-    errorRate?: number;
-  };
-}
-
-/**
- * Token 使用记录
- */
-export interface TokenUsageRecord {
-  /** 时间戳 */
-  timestamp: number;
-
-  /** 会话/会议 ID */
-  sessionId: string;
-
-  /** 任务 ID（可选） */
-  taskId?: string;
-
-  /** 角色 ID（可选） */
-  roleId?: string;
-
-  /** 上下文 Token 数 */
-  contextTokens: number;
-
-  /** 执行 Token 数 */
-  executionTokens: number;
-
-  /** 总 Token 数 */
-  totalTokens: number;
-
-  /** 预算 */
-  budget: number;
-
-  /** 是否超预算 */
-  exceeded: boolean;
-
-  /** 项目路径 */
-  projectPath?: string;
-}
-
-/**
- * Token 使用统计
- */
-export interface TokenUsageSummary {
-  /** 会话 ID */
-  sessionId: string;
-
-  /** 时间范围 */
-  timeRange: {
-    start: number;
-    end: number;
-  };
-
-  /** 总 Token 使用 */
-  totalTokens: number;
-
-  /** 平均每次 Token 使用 */
-  avgTokensPerCall: number;
-
-  /** 超预算次数 */
-  exceededCount: number;
-
-  /** 超预算率 */
-  exceededRate: number;
-
-  /** 按任务统计 */
-  byTask?: Map<string, number>;
-
-  /** 按角色统计 */
-  byRole?: Map<string, number>;
-}

package/src/verification/CONTEXT.md

@@ -1,23 +0,0 @@
-# verification/
-
-## 职责
-验证引擎：基于规则的验证 + 循环验证(loop verification)。
-
-## 核心导出
-- `types.ts` — 验证类型定义
-- `rules-based.ts` — 基于规则的验证引擎
-- `loop.ts` — 循环验证引擎
-
-## 依赖关系
-- 依赖 `src/core/constraints/` 约束检查
-- 依赖 `src/core/validators/` 验证器
-- 经 `src/index.ts` 导出供外部调用方消费（无内置 CLI 命令）
-
-## 约定
-- 验证规则可配置
-- loop 验证用于持续监控场景
-- 验证结果包含 pass/fail + 详细信息
-
-## 注意事项
-- 与 core/validators 配合使用
-- loop 验证适用于长期运行的 Agent 会话

package/src/verification/__tests__/loop.test.ts

@@ -1,303 +0,0 @@
-/**
- * VerificationLoop 测试
- */
-
-import { VerificationLoop } from '../loop';
-import type { VerificationLoopConfig, GatherState } from '../types';
-
-describe('VerificationLoop', () => {
-  const baseConfig: VerificationLoopConfig = {
-    maxRetries: 3,
-    rules: [
-      {
-        id: 'test-rule',
-        type: 'custom',
-        name: 'Test Rule',
-        description: 'Test',
-        verify: async () => ({ passed: true, ruleId: 'test-rule', duration: 0 }),
-      },
-    ],
-  };
-
-  describe('run', () => {
-    it('应该在首次通过时返回 passed', async () => {
-      const loop = new VerificationLoop(baseConfig);
-      const gather = async (): Promise<GatherState> => ({
-        changedFiles: [],
-        metadata: {},
-      });
-
-      const snapshot = await loop.run({ projectRoot: '.' }, gather);
-      expect(snapshot.status).toBe('passed');
-      expect(snapshot.attempt).toBe(1);
-      expect(snapshot.results.every(r => r.passed)).toBe(true);
-    });
-
-    it('应该在验证失败时重试', async () => {
-      let callCount = 0;
-      const config: VerificationLoopConfig = {
-        maxRetries: 3,
-        rules: [
-          {
-            id: 'flaky',
-            type: 'custom',
-            name: 'Flaky',
-            description: '',
-            verify: async () => {
-              callCount++;
-              return {
-                passed: callCount >= 2,
-                ruleId: 'flaky',
-                message: callCount < 2 ? 'not yet' : 'ok',
-                duration: 0,
-              };
-            },
-          },
-        ],
-      };
-
-      const loop = new VerificationLoop(config);
-      const gather = async (): Promise<GatherState> => ({
-        changedFiles: [],
-        metadata: {},
-      });
-
-      const snapshot = await loop.run({ projectRoot: '.' }, gather);
-      expect(snapshot.status).toBe('passed');
-      expect(snapshot.attempt).toBe(2);
-    });
-
-    it('应该在达到最大重试次数后失败', async () => {
-      const config: VerificationLoopConfig = {
-        maxRetries: 2,
-        rules: [
-          {
-            id: 'always-fail',
-            type: 'custom',
-            name: 'Always Fail',
-            description: '',
-            verify: async () => ({
-              passed: false,
-              ruleId: 'always-fail',
-              message: 'nope',
-              duration: 0,
-            }),
-          },
-        ],
-      };
-
-      const loop = new VerificationLoop(config);
-      const gather = async (): Promise<GatherState> => ({
-        changedFiles: [],
-        metadata: {},
-      });
-
-      const snapshot = await loop.run({ projectRoot: '.' }, gather);
-      expect(snapshot.status).toBe('failed');
-      expect(snapshot.attempt).toBe(2);
-      expect(snapshot.lastError).toContain('最大重试次数');
-    });
-
-    it('failFast 应该在首次失败时立即停止', async () => {
-      let verifyCount = 0;
-      const config: VerificationLoopConfig = {
-        maxRetries: 5,
-        failFast: true,
-        rules: [
-          {
-            id: 'fail-fast-rule',
-            type: 'custom',
-            name: 'Fail Fast',
-            description: '',
-            verify: async () => {
-              verifyCount++;
-              return {
-                passed: false,
-                ruleId: 'fail-fast-rule',
-                duration: 0,
-              };
-            },
-          },
-        ],
-      };
-
-      const loop = new VerificationLoop(config);
-      const snapshot = await loop.run(
-        { projectRoot: '.' },
-        async () => ({ changedFiles: [], metadata: {} }),
-      );
-
-      expect(snapshot.status).toBe('failed');
-      expect(snapshot.attempt).toBe(1);
-      expect(verifyCount).toBe(1);
-    });
-
-    it('应该在 gather 失败时返回 failed', async () => {
-      const loop = new VerificationLoop(baseConfig);
-      const gather = async (): Promise<GatherState> => {
-        throw new Error('gather failed');
-      };
-
-      const snapshot = await loop.run({ projectRoot: '.' }, gather);
-      expect(snapshot.status).toBe('failed');
-      expect(snapshot.lastError).toContain('Gather 失败');
-    });
-
-    it('应该在 act 返回 abort 时中止', async () => {
-      let verifyCount = 0;
-      const config: VerificationLoopConfig = {
-        maxRetries: 3,
-        rules: [
-          {
-            id: 'fail-rule',
-            type: 'custom',
-            name: 'Fail',
-            description: '',
-            verify: async () => {
-              verifyCount++;
-              return { passed: false, ruleId: 'fail-rule', duration: 0 };
-            },
-          },
-        ],
-      };
-
-      const loop = new VerificationLoop(config);
-      const snapshot = await loop.run(
-        { projectRoot: '.' },
-        async () => ({ changedFiles: [], metadata: {} }),
-        async () => ({ type: 'abort', description: '无法修复' }),
-      );
-
-      expect(snapshot.status).toBe('failed');
-      expect(snapshot.lastError).toContain('中止');
-      // 只执行了 1 次 verify（第 2 轮 act 返回 abort 后未进入 verify）
-      expect(verifyCount).toBe(1);
-    });
-
-    it('应该在 act 返回 skip 时跳过', async () => {
-      const config: VerificationLoopConfig = {
-        maxRetries: 3,
-        rules: [
-          {
-            id: 'fail-rule',
-            type: 'custom',
-            name: 'Fail',
-            description: '',
-            verify: async () => ({ passed: false, ruleId: 'fail-rule', duration: 0 }),
-          },
-        ],
-      };
-
-      const loop = new VerificationLoop(config);
-      const snapshot = await loop.run(
-        { projectRoot: '.' },
-        async () => ({ changedFiles: [], metadata: {} }),
-        async () => ({ type: 'skip', description: '跳过' }),
-      );
-
-      expect(snapshot.status).toBe('passed');
-    });
-
-    it('第 1 轮不应该调用 act', async () => {
-      let actCalled = false;
-      const loop = new VerificationLoop(baseConfig);
-
-      const snapshot = await loop.run(
-        { projectRoot: '.' },
-        async () => ({ changedFiles: [], metadata: {} }),
-        async () => {
-          actCalled = true;
-          return { type: 'retry', description: 'retry' };
-        },
-      );
-
-      expect(snapshot.status).toBe('passed');
-      expect(actCalled).toBe(false);
-    });
-
-    it('应该在 act 抛出异常时返回 failed', async () => {
-      const config: VerificationLoopConfig = {
-        maxRetries: 3,
-        rules: [
-          {
-            id: 'fail-rule',
-            type: 'custom',
-            name: 'Fail',
-            description: '',
-            verify: async () => ({ passed: false, ruleId: 'fail-rule', duration: 0 }),
-          },
-        ],
-      };
-
-      const loop = new VerificationLoop(config);
-      const snapshot = await loop.run(
-        { projectRoot: '.' },
-        async () => ({ changedFiles: [], metadata: {} }),
-        async () => { throw new Error('act crashed'); },
-      );
-
-      expect(snapshot.status).toBe('failed');
-      expect(snapshot.lastError).toContain('Act 失败');
-      expect(snapshot.lastError).toContain('act crashed');
-    });
-
-    it('应该在 verify 函数抛出异常时视为失败并重试', async () => {
-      const config: VerificationLoopConfig = {
-        maxRetries: 2,
-        rules: [
-          {
-            id: 'throw-rule',
-            type: 'custom',
-            name: 'Throw',
-            description: '',
-            verify: async () => { throw new Error('verify crashed'); },
-          },
-        ],
-      };
-
-      const loop = new VerificationLoop(config);
-      const snapshot = await loop.run(
-        { projectRoot: '.' },
-        async () => ({ changedFiles: [], metadata: {} }),
-      );
-
-      // verifyRule 内部 catch 了异常，返回 passed: false
-      // 循环重试 maxRetries 次后失败
-      expect(snapshot.status).toBe('failed');
-      expect(snapshot.attempt).toBe(2);
-      expect(snapshot.results[0].message).toContain('verify crashed');
-    });
-  });
-
-  describe('snapshot', () => {
-    it('应该包含完整快照信息', async () => {
-      const loop = new VerificationLoop(baseConfig);
-      const snapshot = await loop.run(
-        { projectRoot: '.' },
-        async () => ({ changedFiles: [], metadata: {} }),
-      );
-
-      expect(snapshot.timestamp).toBeDefined();
-      expect(snapshot.maxRetries).toBe(3);
-      expect(Array.isArray(snapshot.results)).toBe(true);
-    });
-  });
-
-  describe('getters', () => {
-    it('应该返回当前状态', async () => {
-      const loop = new VerificationLoop(baseConfig);
-      expect(loop.getStatus()).toBe('idle');
-      expect(loop.getAttempt()).toBe(0);
-      expect(loop.getResults()).toEqual([]);
-
-      await loop.run(
-        { projectRoot: '.' },
-        async () => ({ changedFiles: [], metadata: {} }),
-      );
-
-      expect(loop.getStatus()).toBe('passed');
-      expect(loop.getAttempt()).toBe(1);
-      expect(loop.getResults().length).toBeGreaterThan(0);
-    });
-  });
-});