@dommaker/harness 0.7.8 → 0.8.0

package/README.md

@@ -1,922 +1,271 @@
 # @dommaker/harness
 
-> 通用工程约束框架 - 铁律系统、门禁系统、检查点验证、拦截器
+> AI Agent 的工程约束框架 — 让 Agent 不会乱承诺、不会跳过验证、不会简化测试。
 
-## 简介
-
-`@dommaker/harness` 是一个通用的工程约束框架，帮助团队建立和强制执行代码质量标准。
-
-### 核心功能
+---
 
-| 功能 | 说明 |
-|------|------|
-| **铁律系统** | 16 条内置约束（4 Iron Laws + 10 Guidelines + 2 Tips） |
-| **门禁系统** | 7 种门禁（测试、审查、安全、性能、契约、检查点、验收标准） |
-| **检查点验证** | 验证工作流步骤的结果是否符合预期 |
-| **拦截器** | 抽象拦截框架，自动执行 enforcement |
-| **Session 管理** | 启动检查点 + 结束状态管理 |
-| **预设系统** | 提供 strict/standard/relaxed 三种预设 |
-| **Execution Trace** | 轻量记录约束检查，异常检测，诊断系统 |
-| **Performance Trace** | 性能日志收集，统计分析，异常检测（🆕） |
-| **Failure Classification** | 错误分类，失败记录，等级映射（🆕） |
-| **Spec 验证** | 验证架构文档、模块定义、API 定义 |
-| **项目级自定义约束** | 扩展/覆盖内置约束，无需 fork |
-| **CLI 工具** | 命令行工具执行检查 |
+## 🚀 快速开始
 
-## 安装
+### 安装
 
 ```bash
-npm install @dommaker/harness
+npm install -g @dommaker/harness
 ```
 
-## 快速开始
-
-### 1. 初始化项目
+### 最小工作流
 
 ```bash
-npx harness init --preset standard
-```
-
-这会创建：
-- `.harness/config.yml` - 预设配置
-- `.harness/checkpoints.yml` - 示例检查点
-- `CAPABILITIES.md` - 功能清单模板
-- `.git/hooks/pre-commit` - Git 钩子（可选）
-- `.github/workflows/harness-check.yml` - CI 检查（可选）
-
-### 2. CLI 命令
-
-```bash
-# 初始化项目配置
-harness init --preset standard
-
-# 输出配置代码片段（不创建文件）
-harness init --print-snippets
-
-# 检查铁律
+# 开发前
 harness check
 
-# 列出所有铁律
-harness check --list
-
-# 查看状态（统计、异常、建议）
-harness status
-
-# 查看详细状态
-harness status --detail
+# 开发 + 写测试
 
-# 只显示异常
-harness status --anomalies
-
-# 一键执行诊断+提案流程
-harness flow
+# 提交前
+harness passes-gate
+```
 
-# 验证检查点
-harness validate
+---
 
-# 测试门控
-harness passes-gate
+## 📋 CLI 命令
 
-# 生成报告
-harness report
+### 日常使用
 
-# [已弃用] 请使用 harness status
-harness traces stats
-harness traces summary
-harness traces anomalies
+```bash
+harness check           # 检查铁律（开发前后必用）
+harness passes-gate     # 测试门控（提交前验证）
+harness status          # 查看状态（异常、统计）
+harness flow            # 一键诊断 + 提案流程
 ```
 
-### 3. 在 CI 中使用
+### 项目初始化
 
-```yaml
-# .github/workflows/ci.yml
-jobs:
-  harness-check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - run: npm ci
-      - run: npx harness check
-      - run: npx harness passes-gate
+```bash
+harness init --preset standard    # 初始化配置
+harness init --print-snippets     # 输出代码片段
 ```
 
-### 5. Spec 验证
-
-验证架构文档、模块定义、API 定义等 Spec 文件：
+### 门禁检查
 
 ```bash
-# 验证所有 Spec 文件
-harness spec
+# 测试门控
+harness passes-gate                    # 运行测试
+harness passes-gate --coverage         # 检查覆盖率
+harness pg                              # 别名
 
-# 验证暂存文件（pre-commit）
-harness spec --staged
+# 验收标准
+harness acceptance --task-id TASK-001  # 检查指定任务
+harness acceptance --check-all         # 检查所有任务
+harness acceptance list                 # 列出验收标准
+harness acc                             # 别名
 
-# 验证指定文件
-harness spec --file ARCHITECTURE.md
+# 性能门控
+harness performance --coverage --coverage-threshold 85  # 覆盖率检查
+harness performance --bundle --bundle-threshold 300      # 打包大小检查
+harness perf                                              # 别名
 
-# 使用自定义 Schema
-harness spec --schema ./my-specs/schemas
+# 安全门控
+harness security                        # npm audit 检查
+harness security --severity critical    # 只显示 critical 级别
+harness security audit                  # 详细漏洞报告
+harness sec                             # 别名
 
-# 列出支持的 Spec 类型
-harness spec list
-```
+# API 契约
+harness contract                        # OpenAPI Schema 验证
+harness contract validate               # Schema 语法验证
+harness contract --contract-path api/openapi.yaml
 
-**项目自定义 Schema**：
+# 代码审查
+harness review                          # PR 审查状态检查
+harness review --min-reviewers 2        # 要求 2 个审批
+harness review status                   # PR 详情
+```
 
-项目可以定义自己的 Spec Schema，在 `src/specs/schemas/index.ts` 中导出 `validate` 函数：
+### Spec 验证
 
-```typescript
-// src/specs/schemas/index.ts
-import { z } from 'zod';
-
-export const ArchitectureSchema = z.object({
-  name: z.string(),
-  version: z.string(),
-  modules: z.array(z.string()),
-});
-
-export async function validate(content: string, filePath: string) {
-  // 解析并验证内容
-  // 返回 SpecValidationResult
-}
+```bash
+harness spec            # 验证所有 Spec
+harness spec --staged   # 验证暂存文件
+harness spec list       # 支持的 Spec 类型
 ```
 
-### 6. 在代码中使用
+### 检查点验证
 
-```typescript
-import { 
-  IronLawChecker, 
-  CheckpointValidator, 
-  PassesGate,
-  SessionStartup,
-  CleanStateManager 
-} from '@dommaker/harness';
-
-// 检查铁律
-const checker = IronLawChecker.getInstance();
-const results = await checker.checkAll(context);
+```bash
+harness validate                     # 验证检查点
+harness validate --strict            # 严格模式
+harness validate -f checkpoint.json  # 指定文件
+```
 
-// 验证检查点
-const validator = new CheckpointValidator();
-const result = await validator.validate(checkpoints, context);
+### 报告
 
-// 测试门控
-const gate = new PassesGate({ requireEvidence: true });
-const testResult = await gate.setPasses(taskId, true, workDir);
+```bash
+harness report                        # 生成 Markdown 报告
+harness report -f json                # JSON 格式
+harness report -o report.md           # 输出到文件
+```
 
-// Session 启动检查
-const startup = new SessionStartup(workDir, checkpoints);
-const { success, results } = await startup.run();
+### 诊断
 
-// Session 结束清理
-const cleaner = new CleanStateManager();
-const cleanResult = await cleaner.onSessionEnd(workDir, sessionInfo);
+```bash
+harness flow                          # 一键诊断 + 提案
+harness flow --auto-apply             # 自动应用低风险提案
 ```
 
-### 7. 门禁系统
+---
 
-harness 提供完整的门禁系统，支持多种门禁类型：
+## 🎯 核心概念
+
+### 三层约束体系
+
+| 层级 | 严重性 | 说明 |
+|------|:------:|------|
+| **Iron Law** | 🔴 error | 绝对禁止，无例外 |
+| **Guideline** | 🟡 warning | 推荐遵守，有例外 |
+| **Tip** | 🔵 info | 信息性提示 |
+
+### 7 条铁律
+
+| ID | 规则 |
+|---|------|
+| `no_bypass_checkpoint` | 禁止跳过检查点 |
+| `no_self_approval` | 禁止自评通过（必须测试）|
+| `no_completion_without_verification` | 完成必须验证 |
+| `no_test_simplification` | 禁止简化测试 |
+| `incremental_progress` | 单任务单会话 |
+| `verify_external_capability` | 外部能力先验证 |
+| `no_implementation_without_requirement_review` | 实现后对比需求 |
+
+### 7 种门禁（均有 CLI 命令）
+
+| 门禁 | CLI 命令 | 用途 |
+|------|:--------:|------|
+| PassesGate | `passes-gate` / `pg` | 测试门控 |
+| SpecAcceptanceGate | `acceptance` / `acc` | 验收标准检查 |
+| PerformanceGate | `performance` / `perf` | 性能门控 |
+| SecurityGate | `security` / `sec` | 安全检查 |
+| ContractGate | `contract` | API 契约验证 |
+| ReviewGate | `review` | PR 审核检查 |
+| CheckpointValidator | `validate` | 检查点验证 |
+| CheckpointValidator | 检查点验证 |
+| SpecAcceptanceGate | 验收标准检查 |
 
-| 门禁 | 类 | 说明 |
-|------|-----|------|
-| 测试门控 | `PassesGate` | 禁止自评通过，必须通过真实测试 |
-| 审查门禁 | `ReviewGate` | 检查 GitHub PR 审查状态 |
-| 安全门禁 | `SecurityGate` | npm audit 安全漏洞扫描 |
-| 性能门禁 | `PerformanceGate` | 响应时间、覆盖率、打包大小检查 |
-| 契约门禁 | `ContractGate` | OpenAPI 契约验证 |
-| 检查点验证 | `CheckpointValidator` | 验证工作流步骤结果 |
-| 验收标准门禁 | `SpecAcceptanceGate` | 验证任务是否满足验收标准 |
+---
 
-**使用门禁**：
+## 🔧 代码集成
 
 ```typescript
 import {
+  IronLawChecker,
   PassesGate,
-  ReviewGate,
-  SecurityGate,
-  PerformanceGate,
-  ContractGate,
   CheckpointValidator,
-  SpecAcceptanceGate,
+  interceptOperation,
 } from '@dommaker/harness';
 
+// 铁律检查
+const checker = IronLawChecker.getInstance();
+const results = await checker.checkAll(context);
+
 // 测试门控
-const passesGate = new PassesGate({ requireEvidence: true });
-const testResult = await passesGate.runTests();
-
-// 审查门禁
-const reviewGate = new ReviewGate({ minReviewers: 2 });
-const reviewResult = await reviewGate.check({
-  projectId: 'my-project',
-  projectPath: '/path/to/project',
-  prNumber: 123,
-});
-
-// 安全门禁
-const securityGate = new SecurityGate({ severityThreshold: 'high' });
-const securityResult = await securityGate.scan({
-  projectId: 'my-project',
-  projectPath: '/path/to/project',
-});
-
-// 性能门禁（带超时）
-const performanceGate = new PerformanceGate({
-  thresholds: {
-    maxResponseTime: 500,
-    minCoverage: 80,
-    maxBundleSize: 1024,
-  },
-  coverageTimeout: 120000,  // 2分钟超时
-});
-const perfResult = await performanceGate.check({
-  projectId: 'my-project',
-  projectPath: '/path/to/project',
-});
-
-// 契约门禁
-const contractGate = new ContractGate({ strict: true });
-const contractResult = await contractGate.check({
-  projectId: 'my-project',
-  projectPath: '/path/to/project',
-  newContractPath: '/path/to/openapi.yaml',
-});
+const gate = new PassesGate({ requireEvidence: true });
+const passed = await gate.runTests();
 
 // 检查点验证
-const checkpointValidator = CheckpointValidator.getInstance();
-const checkpointResult = await checkpointValidator.validate(checkpoints, {
-  workdir: '/path/to/project',
-});
-```
-
-**门禁结果**：
+const validator = CheckpointValidator.getInstance();
+const result = await validator.validate(checkpoints, context);
 
-```typescript
-interface GateResult {
-  gate: string;           // 门禁类型
-  passed: boolean;        // 是否通过
-  message: string;        // 结果消息
-  details?: {             // 详细信息
-    metrics?: object;     // 性能指标
-    failures?: string[];  // 失败项
-    warnings?: string[];  // 警告项
-  };
-  timestamp: string;      // 时间戳
-  duration?: number;      // 执行时长（毫秒）
-}
+// 拦截器（自动执行 enforcement）
+await interceptOperation('task_completion_claim', context);
 ```
 
-**PerformanceGate 超时配置**：
-
-```typescript
-const gate = new PerformanceGate({
-  thresholds: { minCoverage: 80 },
-  coverageTimeout: 60000,   // 覆盖率测试超时（毫秒）
-  benchmarkTimeout: 30000,  // 基准测试超时（毫秒）
-});
-
-// 动态设置超时
-gate.setTimeouts({ coverage: 120000 });
-```
-
-### 8. 使用拦截器
+---
 
-拦截器自动执行 enforcement，无需手动调用检查 API：
+## 📁 项目配置
 
-```typescript
-import { 
-  interceptor, 
-  registerExecutor,
-  interceptOperation,
-  claimOperation,
-  type EnforcementExecutor,
-  type ConstraintContext,
-} from '@dommaker/harness';
-
-// 1. 注册执行器（使用者实现具体逻辑）
-registerExecutor('verify-completion', {
-  description: '验证完成声明：运行测试命令',
-  supportedParams: ['command', 'timeout'],
-  async execute(context) {
-    // 使用者自定义验证逻辑
-    const result = await exec('npm test', { cwd: context.projectPath });
-    return {
-      passed: result.success,
-      evidence: result.stdout,
-    };
-  },
-});
-
-// 2. 在关键操作前拦截
-try {
-  // 拦截 task_completion_claim 操作
-  // 自动查找适用的约束并执行对应的 enforcement
-  await claimOperation('task_completion_claim', {
-    operation: 'task_completion_claim',
-    projectPath: '/path/to/project',
-    sessionId: 'session-123',
-  });
-  
-  // 拦截通过，可以宣布完成
-  await announceCompletion();
-} catch (e) {
-  // 拦截失败，铁律违规
-  console.error('必须先验证才能完成');
-}
-
-// 3. 查询拦截结果（不抛异常）
-const result = await interceptOperation('task_completion_claim', context);
-if (result.passed) {
-  console.log('✅ 通过拦截');
-} else {
-  console.log('❌ 约束违规:', result.violations);
-}
-```
-
-**拦截器 vs 手动检查**：
-
-| 方式 | 特点 |
-|------|------|
-| 手动检查 | `checkConstraints()` 需要手动调用 API |
-| 拦截器 | 自动执行 enforcement，抽象框架，使用者实现逻辑 |
-
-**内置 enforcement IDs**：
-
-| enforcement | 说明 |
-|-------------|------|
-| verify-completion | 验证完成声明：运行测试 |
-| verify-e2e | 验证端到端测试 |
-| debug-systematic | 系统性调试检查 |
-| reuse-first | 复用优先检查 |
-| update-capabilities | CAPABILITIES.md 同步检查 |
-| tdd-cycle | TDD 循环检查 |
-| passes-gate | 测试门控 |
-| checkpoint-required | 检查点必须通过 |
-| check-coverage | 覆盖率检查 |
-| require-discussion | 设计决策讨论检查 |
-
-## 内置约束（16 条）
-
-| ID | 规则 | 层级 | 严重性 |
-|---|------|------|:------:|
-| `no_bypass_checkpoint` | 禁止跳过检查点 | iron_law | 🔴 error |
-| `no_self_approval` | 禁止自评通过 | iron_law | 🔴 error |
-| `no_completion_without_verification` | 完成必须有验证证据 | iron_law | 🔴 error |
-| `no_test_simplification` | 禁止擅自简化测试 | iron_law | 🔴 error |
-| `no_fix_without_root_cause` | 修复前必须找到根因 | guideline | 🔴 error |
-| `no_code_without_test` | 写代码前必须有测试 | guideline | 🔴 error |
-| `no_any_type` | 禁止使用 any 类型 | guideline | 🟡 warning |
-| `simplest_solution_first` | 优先选择最简方案 | guideline | 🟡 warning |
-| `no_creation_without_reuse_check` | 创建前必须检查可复用 | guideline | 🟡 warning |
-| `capability_sync` | 代码变更必须更新 CAPABILITIES.md | guideline | 🟡 warning |
-| `no_simplification_without_approval` | 不能擅自简化逻辑 | guideline | 🟡 warning |
-| `no_skill_without_test` | 创建技能前必须有测试 | guideline | 🟡 warning |
-| `test_coverage_required` | 测试覆盖率必须达标 | guideline | 🟡 warning |
-| `design_decision_requires_discussion` | 设计决策必须先讨论 | guideline | 🟡 warning |
-| `readme_required` | 新模块必须有 README | tip | 🔵 info |
-| `doc_required_for_public_api` | 公共 API 必须有文档 | tip | 🔵 info |
-
-## 预设系统
-
-| 预设 | 说明 |
-|------|------|
-| `strict` | 严格模式，所有检查启用 |
-| `standard` | 标准模式，推荐使用 |
-| `relaxed` | 宽松模式，警告不阻止 |
-
-## 自定义约束（v0.4+）
-
-### 扩展例外（v0.6+）
-
-使用 `extend_exceptions` 追加例外，保留内置例外：
+### .harness/config.yml
 
 ```yaml
-# .harness/custom-constraints.yml
-custom_constraints:
-  no_fix_without_root_cause:
-    extend_exceptions:
-      - my_special_case_1
-      - my_special_case_2
-```
-
-结果：内置例外 + 新增例外
-
-### 完全覆盖
+preset: standard
 
-使用 `exceptions` 完全覆盖内置例外：
-
-```yaml
-# .harness/custom-constraints.yml
+# 自定义约束例外
 custom_constraints:
   no_fix_without_root_cause:
-    level: guideline
-    rule: Do not fix without root cause
-    message: 禁止没有根因分析就修复
-    trigger: bug_fix
-    exceptions:
-      - my_only_exception
-```
-
-结果：只使用自定义例外
-
-### 混合模式
-
-同时使用 `exceptions` 和 `extend_exceptions`：
-
-```yaml
-custom_constraints:
-  no_fix_without_root_cause:
-    exceptions:
-      - my_new_exception
     extend_exceptions:
-      - another_exception
-```
-
-结果：内置例外 + my_new_exception + another_exception
-
-## 项目模板
-
-提供多种项目模板：
-
-- `node-api` - Node.js API 项目
-- `nextjs-app` - Next.js 应用
-- `python-api` - Python API 项目
-
-```bash
-# 指定项目类型
-harness init --type node-api
+      - my_special_case
 ```
 
-## API 文档
-
-### IronLawChecker
+### CI 集成
 
-```typescript
-class IronLawChecker {
-  static getInstance(): IronLawChecker;
-  
-  checkAll(context: IronLawContext): Promise<IronLawResult[]>;
-  beforeExecution(context: IronLawContext): Promise<void>;
-  checkIronLaw(lawId: string, context: IronLawContext): Promise<IronLawResult>;
-}
+```yaml
+# .github/workflows/harness-check.yml
+jobs:
+  harness-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci
+      - run: harness check
+      - run: harness passes-gate
 ```
 
-### CheckpointValidator
+---
 
-```typescript
-class CheckpointValidator {
-  validate(checkpoints: Checkpoint[], context: CheckpointContext): Promise<CheckpointResult>;
-}
-```
+## 📊 Trace & 日志
 
-### PassesGate
+### 目录结构
 
-```typescript
-class PassesGate {
-  constructor(config: PassesGateConfig);
-  
-  setPasses(taskId: string, value: boolean, workDir: string): Promise<PassesGateResult>;
-  runTests(): Promise<TestResult>;
-}
 ```
-
-### ReviewGate
-
-```typescript
-class ReviewGate {
-  constructor(config: ReviewGateConfig);
-  
-  check(context: GateContext): Promise<GateResult>;
-  setMinReviewers(count: number): void;
-}
+.harness/
+├── traces/
+│   ├── execution.log      # 约束检查记录（JSON Lines）
+│   └── summary.json       # 统计汇总
+└── state.json             # Harness 状态
 ```
 
-### SecurityGate
-
-```typescript
-class SecurityGate {
-  constructor(config: SecurityGateConfig);
-  
-  scan(context: GateContext): Promise<GateResult>;
-}
-```
+### 查看日志
 
-### PerformanceGate
+```bash
+# 查看状态和统计
+harness status
 
-```typescript
-class PerformanceGate {
-  constructor(config: PerformanceGateConfig);
-  
-  check(context: GateContext): Promise<GateResult>;
-  runBenchmark(context: GateContext): Promise<BenchmarkResult>;
-  setThresholds(thresholds: Partial<PerformanceThresholds>): void;
-  setTimeouts(options: { coverage?: number; benchmark?: number }): void;
-}
-```
+# 查看详细统计
+harness status --detail
 
-### ContractGate
+# 只看异常
+harness status --anomalies
 
-```typescript
-class ContractGate {
-  constructor(config: ContractGateConfig);
-  
-  check(context: GateContext): Promise<GateResult>;
-}
+# 分析最近 N 小时
+harness status --hours 48
 ```
 
-### SpecAcceptanceGate
+### 日志格式
 
-验收标准门禁，用于验证任务是否满足验收标准：
-
-```typescript
-import { SpecAcceptanceGate } from '@dommaker/harness';
-
-// 创建验收门禁
-const acceptanceGate = new SpecAcceptanceGate({
-  tasksPath: './tasks.yml',
-  checkAllTasks: false,
-});
-
-// 检查单个任务
-const result = await acceptanceGate.check({
-  projectPath: '/path/to/project',
-  taskId: 'task-001',
-  tasksPath: './tasks.yml',
-});
-
-// 检查所有任务
-const allResults = await acceptanceGate.check({
-  projectPath: '/path/to/project',
-  checkAllTasks: true,
-});
-
-// 自定义验收条件
-const customGate = new SpecAcceptanceGate({
-  customAcceptanceCriteria: {
-    'has-tests': async (task) => {
-      // 自定义验证逻辑
-      return true;
-    },
-  },
-});
+**execution.log**（JSON Lines 格式）：
+```json
+{"timestamp":"2026-04-28T15:00:00Z","constraintId":"no_bypass_checkpoint","result":"passed","duration":12}
+{"timestamp":"2026-04-28T15:01:00Z","constraintId":"no_self_approval","result":"bypassed","reason":"hotfix"}
 ```
 
-**验收标准格式（tasks.yml）**：
-
-```yaml
-tasks:
-  - id: task-001
-    title: 实现用户登录
-    acceptance_criteria:
-      - id: ac-1
-        description: 用户可以使用邮箱登录
-        type: automated
-        required: true
-      - id: ac-2
-        description: 登录失败显示错误提示
-        type: manual
-        required: true
+**summary.json**：
+```json
+{"totalChecks":150,"passRate":0.92,"bypassRate":0.08,"anomalies":2}
 ```
 
-### SessionStartup
-
-```typescript
-class SessionStartup {
-  constructor(workDir: string, checkpoints: StartupCheckpoints);
-  
-  run(): Promise<{ success: boolean; results: StartupCheckpointResult[] }>;
-  getCurrentTask(): Promise<{ task: any; index: number } | null>;
-  generateReport(results: StartupCheckpointResult[]): string;
-}
-```
+### 异常检测
 
-### CleanStateManager
+当 `harness status --anomalies` 发现异常时，运行 `harness flow` 进行诊断和优化提案。
 
-```typescript
-class CleanStateManager {
-  constructor(config: CleanStateConfig);
-  
-  onSessionEnd(workDir: string, sessionInfo: SessionInfo): Promise<CleanStateResult>;
-}
-```
+---
 
-## 开发
+## 🔧 开发
 
 ```bash
-# 安装依赖
 npm install
-
-# 构建
 npm run build
-
-# 测试
 npm test
 ```
 
-## 许可证
-
-MIT © dommaker
-
----
-
-## Execution Trace 系统（v0.3+）
-
-### 概念
-
-Execution Trace 是约束检查的轻量记录，用于：
-- 统计约束触发频率
-- 检测异常模式（高频绕过、失败率上升）
-- 为 Agent 诊断提供数据基础
-
-### 设计原则
-
-| 原则 | 说明 |
-|------|------|
-| **零 Token 成本** | 记录和统计都不调用 LLM |
-| **轻量记录** | 只记录核心字段，不记录代码片段 |
-| **异步分析** | 统计每小时执行，异常检测每日执行 |
-| **按需诊断** | Agent 仅在检测到异常时才介入 |
-
-### Trace 数据结构
-
-```typescript
-interface ExecutionTrace {
-  constraintId: string;     // 约束 ID
-  level: 'iron_law' | 'guideline' | 'tip';
-  timestamp: number;        // Unix timestamp
-  result: 'pass' | 'fail' | 'bypassed';
-  operation?: string;       // 触发条件
-  exceptionApplied?: string; // 例外类型
-}
-```
-
-### 自动记录
-
-约束检查时自动记录：
-
-```typescript
-import { checkConstraints } from '@dommaker/harness';
-
-// 每次检查都会自动记录 trace
-const result = await checkConstraints(context);
-// Trace 已写入 .harness/traces/execution.log
-```
-
-### Trace 文件位置
-
-```
-.harness/traces/
-├── execution.log           # 当前 trace 文件
-├── execution-2026-04-05.log  # 滚动备份（超出 10MB 时）
-├── summary.json            # 统计汇总
-```
-
-### 统计汇总
-
-每小时自动执行：
-
-```typescript
-import { TraceAnalyzer } from '@dommaker/harness';
-
-const analyzer = new TraceAnalyzer();
-const summaries = analyzer.runHourlySummary();
-
-// 输出：
-// [
-//   { constraintId: 'no_fix_without_root_cause', passRate: 0.7, bypassRate: 0.1 },
-//   { constraintId: 'no_code_without_test', passRate: 0.9, bypassRate: 0 },
-// ]
-```
-
-### 异常检测
-
-每日自动执行：
-
-```typescript
-const anomalies = analyzer.runDailyAnomalyCheck();
-
-// 检测类型：
-// - high_bypass_rate：绕过率 > 30%
-// - rising_fail_rate：失败率上升趋势
-// - exception_overuse：例外使用率 > 40%
-```
-
-### CLI 使用
-
-```bash
-# 查看 trace 文件统计
-harness traces stats
-
-# 查看最近 24 小时的约束汇总
-harness traces summary --hours 24
-
-# 检测异常
-harness traces anomalies
-
-# JSON 格式输出
-harness traces summary --format json
-
-# 运行诊断
-harness diagnose run --hours 24 --save
-
-# 查看诊断列表
-harness diagnose list
-
-# 生成提案
-harness propose generate --save
-
-# 审核提案
-harness propose review --diagnosis <id> --accept
-
-# 查看实施指导
-harness propose implement --diagnosis <id>
-```
-
-### 成本控制
-
-| 活动 | 频率 | Token 成本 |
-|------|------|:----------:|
-| Trace 记录 | 每次检查 | 0 |
-| 统计汇总 | 每小时 | 0 |
-| 异常检测 | 每日 | 0（未触发）~500（触发） |
-| Agent 诊断 | 按需 | ~2000 |
-
-**对比 Meta-Harness**：百万级 vs 5500/周，成本降低 **180 倍**。
-
 ---
 
-## Performance Trace 系统（v0.4+）
-
-### 概念
-
-Performance Trace 是性能数据的轻量记录，用于：
-- 监控关键操作耗时
-- 检测性能异常（慢操作、超阈值）
-- 统计 Token 使用和上下文大小
-- 为性能优化提供数据基础
-
-### 设计原则
-
-| 原则 | 说明 |
-|------|------|
-| **零 Token 成本** | 记录和统计都不调用 LLM |
-| **文件存储** | 追加写入，单行 JSON 格式 |
-| **异步分析** | 统计每小时执行，异常检测每日执行 |
-| **可配置阈值** | 按操作类型设置不同的性能阈值 |
-
-### Trace 数据结构
-
-```typescript
-interface PerformanceTrace {
-  operation: string;        // 操作名称
-  startTime: number;        // 开始时间戳
-  duration: number;         // 耗时（毫秒）
-  status: 'ok' | 'exceeded' | 'error';
-  threshold?: number;       // 配置的阈值
-  metadata?: Record<string, unknown>;
-}
-```
-
-### API 使用
-
-```typescript
-import { PerformanceCollector, PerformanceAnalyzer } from '@dommaker/harness';
-
-// 创建收集器
-const collector = new PerformanceCollector({
-  logFile: '.harness/logs/performance.log',
-  thresholds: {
-    extract: 1000,    // 提取操作阈值 1s
-    transform: 500,   // 转换操作阈值 500ms
-    invoke: 10000,    // 调用操作阈值 10s
-  },
-});
-
-// 记录操作
-await collector.recordOk('extract', 150, { contextSize: 5000 });
-await collector.recordExceeded('invoke', 12000, 10000, { agent: 'skill-agent' });
-
-// 分析统计
-const analyzer = new PerformanceAnalyzer();
-const summaries = analyzer.summarize(traces);
-const anomalies = analyzer.detectAnomalies(traces);
-
-// 生成报告
-const report = analyzer.generateReport(summaries, anomalies);
-```
+## 📝 License
 
-### 文件位置
-
-```
-.harness/logs/
-├── performance.log          # 性能日志
-├── performance-summary.json # 统计汇总
-└── tokens.log               # Token 使用日志
-```
-
-### 与 TraceCollector 对比
-
-| 能力 | TraceCollector | PerformanceCollector |
-|------|----------------|---------------------|
-| **监控目标** | 约束检查结果 | 操作耗时 |
-| **监控"什么"** | 对不对 | 快不快 |
-| **异常类型** | 高绕过率、失败率上升 | 慢操作、超阈值 |
-| **存储路径** | `.harness/logs/traces.log` | `.harness/logs/performance.log` |
-
----
-
-## Failure Classification 系统（v0.4+）
-
-### 概念
-
-Failure Classification 提供通用的错误分类和记录能力，用于：
-- 统一错误分类标准
-- 分级处理失败（L1-L4）
-- 记录失败历史供分析
-
-### 设计原则
-
-| 原则 | 说明 |
-|------|------|
-| **零业务逻辑** | 只提供类型 + 分类 + 记录能力 |
-| **可扩展规则** | 支持自定义分类规则 |
-| **文件存储** | 追加写入，单行 JSON 格式 |
-
-### 错误类型
-
-```typescript
-enum ErrorType {
-  TEST_FAILED = 'TEST_FAILED',       // 测试失败
-  GATE_FAILED = 'GATE_FAILED',       // 门禁检查失败
-  DEPENDENCY_BLOCKED = 'DEPENDENCY_BLOCKED', // 依赖阻塞
-  CONTEXT_OVERFLOW = 'CONTEXT_OVERFLOW',     // 上下文溢出
-  TIMEOUT = 'TIMEOUT',               // 超时
-  NETWORK_ERROR = 'NETWORK_ERROR',   // 网络错误
-  AGENT_ERROR = 'AGENT_ERROR',       // Agent 错误
-  TOOL_ERROR = 'TOOL_ERROR',         // 工具错误
-  VALIDATION_ERROR = 'VALIDATION_ERROR', // 验证错误
-  UNKNOWN = 'UNKNOWN',               // 未知错误
-}
-```
-
-### 失败等级
-
-| 等级 | 说明 | 处理策略 |
-|------|------|---------|
-| L1 | 自动重试 | 重试、降级 |
-| L2 | 需要干预 | 人工审核 |
-| L3 | 严重问题 | 开会讨论 |
-| L4 | 致命错误 | 回滚 |
-
-### API 使用
-
-```typescript
-import {
-  ErrorClassifier,
-  FailureRecorder,
-  ErrorType,
-  FailureLevel,
-  classifyError,
-} from '@dommaker/harness';
-
-// 快速分类
-const type = classifyError(new Error('test failed'));
-// type === ErrorType.TEST_FAILED
-
-// 完整分类器
-const classifier = new ErrorClassifier({
-  rules: [
-    {
-      type: ErrorType.CUSTOM_ERROR,
-      keywords: ['custom', 'specific'],
-      level: FailureLevel.L2,
-    },
-  ],
-});
-
-const result = classifier.classify(new Error('custom error'));
-// result.type, result.level, result.matchedRule
-
-// 失败记录
-const recorder = new FailureRecorder({
-  logFile: '.harness/logs/failures.log',
-});
-
-await recorder.record({
-  type: ErrorType.TEST_FAILED,
-  level: FailureLevel.L1,
-  message: 'Test failed',
-  timestamp: Date.now(),
-});
-
-// 获取统计
-const stats = await recorder.getStats();
-// { total, byType, byLevel }
-```
-
-### 与 PerformanceCollector 对比
-
-| 能力 | PerformanceCollector | FailureRecorder |
-|------|---------------------|-----------------|
-| **监控目标** | 操作耗时 | 错误分类 |
-| **存储内容** | 性能指标 | 失败记录 |
-| **分析维度** | 慢操作、超阈值 | 错误类型分布、失败等级 |
+MIT © dommaker