@dommaker/harness 0.7.7 → 0.7.9

package/README.md

@@ -1,922 +1,339 @@
 # @dommaker/harness
 
-> 通用工程约束框架 - 铁律系统、门禁系统、检查点验证、拦截器
+> AI Agent 的工程约束框架 — 铁律系统、门禁系统、质量检查
 
-## 简介
+## 一句话
 
-`@dommaker/harness` 是一个通用的工程约束框架，帮助团队建立和强制执行代码质量标准。
+**harness 让 Agent 不会乱承诺、不会跳过验证、不会简化测试。**
 
-### 核心功能
-
-| 功能 | 说明 |
-|------|------|
-| **铁律系统** | 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
-```
+---
 
-## 快速开始
+## 快速上手
 
-### 1. 初始化项目
+### CLI 命令速查
 
 ```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 命令
+# 安装
+npm install @dommaker/harness
 
-```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 validate
 
 # 测试门控
 harness passes-gate
 
-# 生成报告
-harness report
+# Spec 验证
+harness spec
 
-# [已弃用] 请使用 harness status
-harness traces stats
-harness traces summary
-harness traces anomalies
+# 一键诊断
+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
+```
+开始开发
+    ↓
+harness check (检查铁律)
+    ↓
+写代码 + 写测试
+    ↓
+harness passes-gate (验证通过)
+    ↓
+提交
 ```
 
-### 5. Spec 验证
+---
 
-验证架构文档、模块定义、API 定义等 Spec 文件：
+## Agent 工作流程
 
-```bash
-# 验证所有 Spec 文件
-harness spec
+### 1. Session 启动检查
 
-# 验证暂存文件（pre-commit）
-harness spec --staged
+Agent 开始工作前，自动检查：
 
-# 验证指定文件
-harness spec --file ARCHITECTURE.md
+| 检查项 | 说明 |
+|--------|------|
+| 工作目录干净？ | 无未提交变更 |
+| Roadmap 存在？ | 知道要做什么 |
+| Spec 存在？ | 知道怎么做 |
+| 依赖满足？ | 前置任务完成 |
 
-# 使用自定义 Schema
-harness spec --schema ./my-specs/schemas
-
-# 列出支持的 Spec 类型
-harness spec list
+```bash
+harness status
 ```
 
-**项目自定义 Schema**：
+### 2. 开发中铁律检查
 
-项目可以定义自己的 Spec Schema，在 `src/specs/schemas/index.ts` 中导出 `validate` 函数：
+**Iron Laws（绝对禁止）**：
 
-```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
-}
+| ID | 规则 | Agent 不能做 |
+|---|------|-------------|
+| `no_bypass_checkpoint` | 禁止跳过检查点 | ❌ "先跳过验证" |
+| `no_self_approval` | 禁止自评通过 | ❌ "应该没问题" |
+| `no_completion_without_verification` | 完成必须有验证 | ❌ "任务完成了"（未测试）|
+| `no_test_simplification` | 禁止简化测试 | ❌ "测试太难，先删掉" |
+
+```bash
+harness check
 ```
 
-### 6. 在代码中使用
+### 3. 完成前验证
 
-```typescript
-import { 
-  IronLawChecker, 
-  CheckpointValidator, 
-  PassesGate,
-  SessionStartup,
-  CleanStateManager 
-} from '@dommaker/harness';
-
-// 检查铁律
-const checker = IronLawChecker.getInstance();
-const results = await checker.checkAll(context);
+Agent 声明完成前，必须通过门禁：
 
-// 验证检查点
-const validator = new CheckpointValidator();
-const result = await validator.validate(checkpoints, context);
+| 门禁 | 检查内容 |
+|------|---------|
+| PassesGate | 测试必须通过 |
+| ReviewGate | PR 必须有人审核 |
+| SecurityGate | 无高危漏洞 |
+| PerformanceGate | 性能达标 |
 
-// 测试门控
-const gate = new PassesGate({ requireEvidence: true });
-const testResult = await gate.setPasses(taskId, true, workDir);
-
-// 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 passes-gate
 ```
 
-### 7. 门禁系统
+### 4. Spec 验证
 
-harness 提供完整的门禁系统，支持多种门禁类型：
+验证架构文档、API 定义等 Spec 文件：
 
-| 门禁 | 类 | 说明 |
-|------|-----|------|
-| 测试门控 | `PassesGate` | 禁止自评通过，必须通过真实测试 |
-| 审查门禁 | `ReviewGate` | 检查 GitHub PR 审查状态 |
-| 安全门禁 | `SecurityGate` | npm audit 安全漏洞扫描 |
-| 性能门禁 | `PerformanceGate` | 响应时间、覆盖率、打包大小检查 |
-| 契约门禁 | `ContractGate` | OpenAPI 契约验证 |
-| 检查点验证 | `CheckpointValidator` | 验证工作流步骤结果 |
-| 验收标准门禁 | `SpecAcceptanceGate` | 验证任务是否满足验收标准 |
-
-**使用门禁**：
+```bash
+harness spec              # 验证所有 Spec
+harness spec --staged     # 验证暂存文件
+harness spec list         # 支持的 Spec 类型
+```
 
-```typescript
-import {
-  PassesGate,
-  ReviewGate,
-  SecurityGate,
-  PerformanceGate,
-  ContractGate,
-  CheckpointValidator,
-  SpecAcceptanceGate,
-} from '@dommaker/harness';
+---
 
-// 测试门控
-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 checkpointValidator = CheckpointValidator.getInstance();
-const checkpointResult = await checkpointValidator.validate(checkpoints, {
-  workdir: '/path/to/project',
-});
-```
+### 三层约束体系
 
-**门禁结果**：
+| 层级 | 名称 | 严重性 | 举例 |
+|------|------|:------:|------|
+| **Iron Law** | 铁律 | 🔴 error | 禁止跳过检查点 |
+| **Guideline** | 指导 | 🟡 warning | 写代码前写测试 |
+| **Tip** | 提示 | 🔵 info | 新模块要有 README |
 
-```typescript
-interface GateResult {
-  gate: string;           // 门禁类型
-  passed: boolean;        // 是否通过
-  message: string;        // 结果消息
-  details?: {             // 详细信息
-    metrics?: object;     // 性能指标
-    failures?: string[];  // 失败项
-    warnings?: string[];  // 警告项
-  };
-  timestamp: string;      // 时间戳
-  duration?: number;      // 执行时长（毫秒）
-}
-```
+### 16 条内置约束
 
-**PerformanceGate 超时配置**：
+**Iron Laws（4 条）**：
 
-```typescript
-const gate = new PerformanceGate({
-  thresholds: { minCoverage: 80 },
-  coverageTimeout: 60000,   // 覆盖率测试超时（毫秒）
-  benchmarkTimeout: 30000,  // 基准测试超时（毫秒）
-});
-
-// 动态设置超时
-gate.setTimeouts({ coverage: 120000 });
-```
+| ID | 规则 |
+|---|------|
+| `no_bypass_checkpoint` | 禁止跳过检查点 |
+| `no_self_approval` | 禁止自评通过 |
+| `no_completion_without_verification` | 完成必须验证 |
+| `no_test_simplification` | 禁止简化测试 |
 
-### 8. 使用拦截器
+**Guidelines（10 条）**：
 
-拦截器自动执行 enforcement，无需手动调用检查 API：
+| ID | 规则 |
+|---|------|
+| `no_fix_without_root_cause` | 修复前找根因 |
+| `no_code_without_test` | 先写测试 |
+| `no_any_type` | 禁止 any |
+| `simplest_solution_first` | 最简方案优先 |
+| `no_creation_without_reuse_check` | 创建前检查复用 |
+| `capability_sync` | 代码变更更新 CAPABILITIES |
+| `no_simplification_without_approval` | 禁止擅自简化 |
+| `no_skill_without_test` | 技能要有测试 |
+| `test_coverage_required` | 覆盖率达标 |
+| `design_decision_requires_discussion` | 设计决策先讨论 |
 
-```typescript
-import { 
-  interceptor, 
-  registerExecutor,
-  interceptOperation,
-  claimOperation,
-  type EnforcementExecutor,
-  type ConstraintContext,
-} from '@dommaker/harness';
+**Tips（2 条）**：
 
-// 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);
-}
-```
+| ID | 规则 |
+|---|------|
+| `readme_required` | 新模块有 README |
+| `doc_required_for_public_api` | 公共 API 有文档 |
 
-**拦截器 vs 手动检查**：
+---
 
-| 方式 | 特点 |
-|------|------|
-| 手动检查 | `checkConstraints()` 需要手动调用 API |
-| 拦截器 | 自动执行 enforcement，抽象框架，使用者实现逻辑 |
+## 7 种门禁
 
-**内置 enforcement IDs**：
+| 门禁 | 类 | 用途 |
+|------|-----|------|
+| PassesGate | 测试门控 | 禁止自评通过 |
+| ReviewGate | 审查门控 | PR 审核检查 |
+| SecurityGate | 安全门控 | npm audit |
+| PerformanceGate | 性能门控 | 响应时间、覆盖率 |
+| ContractGate | 契约门控 | OpenAPI 验证 |
+| CheckpointValidator | 检查点验证 | 步骤结果验证 |
+| SpecAcceptanceGate | 验收门控 | 验收标准检查 |
 
-| 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` | 宽松模式，警告不阻止 |
+| `strict` | 所有检查启用 |
+| `standard` | 推荐使用 |
+| `relaxed` | 警告不阻止 |
 
-## 自定义约束（v0.4+）
+```bash
+harness init --preset standard
+```
 
-### 扩展例外（v0.6+）
+---
 
-使用 `extend_exceptions` 追加例外，保留内置例外：
+## 高级功能
 
-```yaml
-# .harness/custom-constraints.yml
-custom_constraints:
-  no_fix_without_root_cause:
-    extend_exceptions:
-      - my_special_case_1
-      - my_special_case_2
-```
+### CLI 详细命令
 
-结果：内置例外 + 新增例外
+```bash
+# 初始化（输出代码片段）
+harness init --print-snippets
 
-### 完全覆盖
+# 铁律检查
+harness check --list      # 列出所有铁律
+harness check --json      # JSON 输出
 
-使用 `exceptions` 完全覆盖内置例外：
+# 状态查看
+harness status --detail   # 详细状态
+harness status --anomalies # 只显示异常
 
-```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
-```
+# Trace 分析（已弃用，用 status）
+harness traces stats      # 统计
+harness traces anomalies  # 异常检测
 
-结果：只使用自定义例外
-
-### 混合模式
+# 诊断流程
+harness diagnose run --hours 24 --save
+harness diagnose list
+harness propose generate --save
+harness propose review --diagnosis <id> --accept
+```
 
-同时使用 `exceptions` 和 `extend_exceptions`：
+### 项目自定义约束
 
 ```yaml
+# .harness/custom-constraints.yml
 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
-```
-
-## API 文档
-
-### IronLawChecker
-
-```typescript
-class IronLawChecker {
-  static getInstance(): IronLawChecker;
-  
-  checkAll(context: IronLawContext): Promise<IronLawResult[]>;
-  beforeExecution(context: IronLawContext): Promise<void>;
-  checkIronLaw(lawId: string, context: IronLawContext): Promise<IronLawResult>;
-}
-```
-
-### CheckpointValidator
-
-```typescript
-class CheckpointValidator {
-  validate(checkpoints: Checkpoint[], context: CheckpointContext): Promise<CheckpointResult>;
-}
-```
-
-### 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;
-}
+      - my_special_case
+    # 或完全覆盖
+    exceptions:
+      - my_only_exception
 ```
 
-### SecurityGate
+### 在代码中使用
 
 ```typescript
-class SecurityGate {
-  constructor(config: SecurityGateConfig);
-  
-  scan(context: GateContext): Promise<GateResult>;
-}
-```
+import {
+  IronLawChecker,
+  PassesGate,
+  CheckpointValidator,
+  SessionStartup,
+  interceptOperation,
+} from '@dommaker/harness';
 
-### PerformanceGate
+// 铁律检查
+const checker = IronLawChecker.getInstance();
+const results = await checker.checkAll(context);
 
-```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;
-}
-```
+// 测试门控
+const gate = new PassesGate({ requireEvidence: true });
+const passed = await gate.runTests();
 
-### ContractGate
+// 检查点验证
+const validator = CheckpointValidator.getInstance();
+const result = await validator.validate(checkpoints, context);
 
-```typescript
-class ContractGate {
-  constructor(config: ContractGateConfig);
-  
-  check(context: GateContext): Promise<GateResult>;
-}
+// 拦截器（自动执行 enforcement）
+await interceptOperation('task_completion_claim', context);
 ```
 
-### SpecAcceptanceGate
+### 拦截器 Enforcement IDs
 
-验收标准门禁，用于验证任务是否满足验收标准：
+| enforcement | 说明 |
+|-------------|------|
+| `verify-completion` | 验证完成：运行测试 |
+| `verify-e2e` | E2E 测试验证 |
+| `debug-systematic` | 系统性调试 |
+| `reuse-first` | 复用优先检查 |
+| `update-capabilities` | CAPABILITIES 同步 |
+| `tdd-cycle` | TDD 循环检查 |
+| `passes-gate` | 测试门控 |
+| `checkpoint-required` | 检查点必须通过 |
 
-```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;
-    },
-  },
-});
-```
+---
 
-**验收标准格式（tasks.yml）**：
+## CI 配置
 
 ```yaml
-tasks:
-  - id: task-001
-    title: 实现用户登录
-    acceptance_criteria:
-      - id: ac-1
-        description: 用户可以使用邮箱登录
-        type: automated
-        required: true
-      - id: ac-2
-        description: 登录失败显示错误提示
-        type: manual
-        required: true
-```
-
-### 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
-
-```typescript
-class CleanStateManager {
-  constructor(config: CleanStateConfig);
-  
-  onSessionEnd(workDir: string, sessionInfo: SessionInfo): Promise<CleanStateResult>;
-}
-```
-
-## 开发
-
-```bash
-# 安装依赖
-npm install
-
-# 构建
-npm run build
-
-# 测试
-npm test
+# .github/workflows/harness-check.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
 ```
 
-## 许可证
-
-MIT © dommaker
-
 ---
 
-## Execution Trace 系统（v0.3+）
+## Trace 系统
 
-### 概念
+### Execution Trace
 
-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 },
-// ]
+├── execution.log      # 当前 trace
+├── summary.json       # 统计汇总
 ```
 
-### 异常检测
+### Performance Trace
 
-每日自动执行：
+记录操作耗时，用于：
+- 监控慢操作
+- 检测超阈值
 
-```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>
+.harness/logs/
+├── performance.log    # 性能日志
+├── tokens.log         # Token 使用
 ```
 
-### 成本控制
-
-| 活动 | 频率 | Token 成本 |
-|------|------|:----------:|
-| Trace 记录 | 每次检查 | 0 |
-| 统计汇总 | 每小时 | 0 |
-| 异常检测 | 每日 | 0（未触发）~500（触发） |
-| Agent 诊断 | 按需 | ~2000 |
+### Failure Classification
 
-**对比 Meta-Harness**：百万级 vs 5500/周，成本降低 **180 倍**。
-
----
+错误分级（L1-L4）：
 
-## 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);
-```
-
-### 文件位置
-
-```
-.harness/logs/
-├── performance.log          # 性能日志
-├── performance-summary.json # 统计汇总
-└── tokens.log               # Token 使用日志
-```
-
-### 与 TraceCollector 对比
-
-| 能力 | TraceCollector | PerformanceCollector |
-|------|----------------|---------------------|
-| **监控目标** | 约束检查结果 | 操作耗时 |
-| **监控"什么"** | 对不对 | 快不快 |
-| **异常类型** | 高绕过率、失败率上升 | 慢操作、超阈值 |
-| **存储路径** | `.harness/logs/traces.log` | `.harness/logs/performance.log` |
+| L1 | 自动重试 |
+| L2 | 人工审核 |
+| L3 | 开会讨论 |
+| L4 | 回滚 |
 
 ---
 
-## 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',               // 未知错误
-}
+```bash
+npm install
+npm run build
+npm test
 ```
 
-### 失败等级
-
-| 等级 | 说明 | 处理策略 |
-|------|------|---------|
-| 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