@dommaker/harness 0.7.9 → 0.8.1

package/README.md

@@ -1,240 +1,163 @@
 # @dommaker/harness
 
-> AI Agent 的工程约束框架 — 铁律系统、门禁系统、质量检查
-
-## 一句话
-
-**harness 让 Agent 不会乱承诺、不会跳过验证、不会简化测试。**
+> AI Agent 的工程约束框架 — 让 Agent 不会乱承诺、不会跳过验证、不会简化测试。
 
 ---
 
-## 快速上手
+## 🚀 快速开始
 
-### CLI 命令速查
+### 安装
 
 ```bash
-# 安装
-npm install @dommaker/harness
+npm install -g @dommaker/harness
+```
 
-# 初始化项目
-harness init --preset standard
+### 最小工作流
 
-# 检查铁律（开发前后必用）
+```bash
+# 开发前
 harness check
 
-# 查看状态（异常、统计）
-harness status
-
-# 验证检查点
-harness validate
+# 开发 + 写测试
 
-# 测试门控
+# 提交前
 harness passes-gate
-
-# Spec 验证
-harness spec
-
-# 一键诊断
-harness flow
-```
-
-### 最小工作流
-
-```
-开始开发
-    ↓
-harness check (检查铁律)
-    ↓
-写代码 + 写测试
-    ↓
-harness passes-gate (验证通过)
-    ↓
-提交
 ```
 
 ---
 
-## Agent 工作流程
+## 📋 CLI 命令
 
-### 1. Session 启动检查
+### 日常使用
 
-Agent 开始工作前，自动检查：
+```bash
+harness check           # 检查铁律（开发前后必用）
+harness passes-gate     # 测试门控（提交前验证）
+harness status          # 查看状态（异常、统计）
+harness flow            # 一键诊断 + 提案流程
+```
 
-| 检查项 | 说明 |
-|--------|------|
-| 工作目录干净？ | 无未提交变更 |
-| Roadmap 存在？ | 知道要做什么 |
-| Spec 存在？ | 知道怎么做 |
-| 依赖满足？ | 前置任务完成 |
+### 项目初始化
 
 ```bash
-harness status
+harness init --preset standard    # 初始化配置
+harness init --print-snippets     # 输出代码片段
 ```
 
-### 2. 开发中铁律检查
+### 门禁检查
 
-**Iron Laws（绝对禁止）**：
+```bash
+# 测试门控
+harness passes-gate                    # 运行测试
+harness passes-gate --coverage         # 检查覆盖率
+harness pg                              # 别名
+
+# 验收标准
+harness acceptance --task-id TASK-001  # 检查指定任务
+harness acceptance --check-all         # 检查所有任务
+harness acceptance list                 # 列出验收标准
+harness acc                             # 别名
+
+# 性能门控
+harness performance --coverage --coverage-threshold 85  # 覆盖率检查
+harness performance --bundle --bundle-threshold 300      # 打包大小检查
+harness perf                                              # 别名
+
+# 安全门控
+harness security                        # npm audit 检查
+harness security --severity critical    # 只显示 critical 级别
+harness security audit                  # 详细漏洞报告
+harness sec                             # 别名
+
+# API 契约
+harness contract                        # OpenAPI Schema 验证
+harness contract validate               # Schema 语法验证
+harness contract --contract-path api/openapi.yaml
+
+# 代码审查
+harness review                          # PR 审查状态检查
+harness review --min-reviewers 2        # 要求 2 个审批
+harness review status                   # PR 详情
+```
 
-| ID | 规则 | Agent 不能做 |
-|---|------|-------------|
-| `no_bypass_checkpoint` | 禁止跳过检查点 | ❌ "先跳过验证" |
-| `no_self_approval` | 禁止自评通过 | ❌ "应该没问题" |
-| `no_completion_without_verification` | 完成必须有验证 | ❌ "任务完成了"（未测试）|
-| `no_test_simplification` | 禁止简化测试 | ❌ "测试太难，先删掉" |
+### Spec 验证
 
 ```bash
-harness check
+harness spec            # 验证所有 Spec
+harness spec --staged   # 验证暂存文件
+harness spec list       # 支持的 Spec 类型
 ```
 
-### 3. 完成前验证
+### 检查点验证
 
-Agent 声明完成前，必须通过门禁：
+```bash
+harness validate                     # 验证检查点
+harness validate --strict            # 严格模式
+harness validate -f checkpoint.json  # 指定文件
+```
 
-| 门禁 | 检查内容 |
-|------|---------|
-| PassesGate | 测试必须通过 |
-| ReviewGate | PR 必须有人审核 |
-| SecurityGate | 无高危漏洞 |
-| PerformanceGate | 性能达标 |
+### 报告
 
 ```bash
-harness passes-gate
+harness report                        # 生成 Markdown 报告
+harness report -f json                # JSON 格式
+harness report -o report.md           # 输出到文件
 ```
 
-### 4. Spec 验证
-
-验证架构文档、API 定义等 Spec 文件：
+### 诊断
 
 ```bash
-harness spec              # 验证所有 Spec
-harness spec --staged     # 验证暂存文件
-harness spec list         # 支持的 Spec 类型
+harness flow                          # 一键诊断 + 提案
+harness flow --auto-apply             # 自动应用低风险提案
 ```
 
 ---
 
-## 核心概念
+## 🎯 核心概念
 
 ### 三层约束体系
 
-| 层级 | 名称 | 严重性 | 举例 |
-|------|------|:------:|------|
-| **Iron Law** | 铁律 | 🔴 error | 禁止跳过检查点 |
-| **Guideline** | 指导 | 🟡 warning | 写代码前写测试 |
-| **Tip** | 提示 | 🔵 info | 新模块要有 README |
-
-### 16 条内置约束
+| 层级 | 严重性 | 说明 |
+|------|:------:|------|
+| **Iron Law** | 🔴 error | 绝对禁止，无例外 |
+| **Guideline** | 🟡 warning | 推荐遵守，有例外 |
+| **Tip** | 🔵 info | 信息性提示 |
 
-**Iron Laws（4 条）**：
+### 7 条铁律
 
 | ID | 规则 |
 |---|------|
 | `no_bypass_checkpoint` | 禁止跳过检查点 |
-| `no_self_approval` | 禁止自评通过 |
+| `no_self_approval` | 禁止自评通过（必须测试）|
 | `no_completion_without_verification` | 完成必须验证 |
 | `no_test_simplification` | 禁止简化测试 |
-
-**Guidelines（10 条）**：
-
-| 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` | 设计决策先讨论 |
-
-**Tips（2 条）**：
-
-| ID | 规则 |
-|---|------|
-| `readme_required` | 新模块有 README |
-| `doc_required_for_public_api` | 公共 API 有文档 |
-
----
-
-## 7 种门禁
-
-| 门禁 | 类 | 用途 |
-|------|-----|------|
-| PassesGate | 测试门控 | 禁止自评通过 |
-| ReviewGate | 审查门控 | PR 审核检查 |
-| SecurityGate | 安全门控 | npm audit |
-| PerformanceGate | 性能门控 | 响应时间、覆盖率 |
-| ContractGate | 契约门控 | OpenAPI 验证 |
-| CheckpointValidator | 检查点验证 | 步骤结果验证 |
-| SpecAcceptanceGate | 验收门控 | 验收标准检查 |
+| `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 | 验收标准检查 |
 
 ---
 
-## 预设系统
-
-| 预设 | 说明 |
-|------|------|
-| `strict` | 所有检查启用 |
-| `standard` | 推荐使用 |
-| `relaxed` | 警告不阻止 |
-
-```bash
-harness init --preset standard
-```
-
----
-
-## 高级功能
-
-### CLI 详细命令
-
-```bash
-# 初始化（输出代码片段）
-harness init --print-snippets
-
-# 铁律检查
-harness check --list      # 列出所有铁律
-harness check --json      # JSON 输出
-
-# 状态查看
-harness status --detail   # 详细状态
-harness status --anomalies # 只显示异常
-
-# 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
-```
-
-### 项目自定义约束
-
-```yaml
-# .harness/custom-constraints.yml
-custom_constraints:
-  no_fix_without_root_cause:
-    # 追加例外（保留内置）
-    extend_exceptions:
-      - my_special_case
-    # 或完全覆盖
-    exceptions:
-      - my_only_exception
-```
-
-### 在代码中使用
+## 🔧 代码集成
 
 ```typescript
 import {
   IronLawChecker,
   PassesGate,
   CheckpointValidator,
-  SessionStartup,
   interceptOperation,
 } from '@dommaker/harness';
 
@@ -254,22 +177,23 @@ const result = await validator.validate(checkpoints, context);
 await interceptOperation('task_completion_claim', context);
 ```
 
-### 拦截器 Enforcement IDs
+---
 
-| enforcement | 说明 |
-|-------------|------|
-| `verify-completion` | 验证完成：运行测试 |
-| `verify-e2e` | E2E 测试验证 |
-| `debug-systematic` | 系统性调试 |
-| `reuse-first` | 复用优先检查 |
-| `update-capabilities` | CAPABILITIES 同步 |
-| `tdd-cycle` | TDD 循环检查 |
-| `passes-gate` | 测试门控 |
-| `checkpoint-required` | 检查点必须通过 |
+## 📁 项目配置
 
----
+### .harness/config.yml
+
+```yaml
+preset: standard
 
-## CI 配置
+# 自定义约束例外
+custom_constraints:
+  no_fix_without_root_cause:
+    extend_exceptions:
+      - my_special_case
+```
+
+### CI 集成
 
 ```yaml
 # .github/workflows/harness-check.yml
@@ -279,52 +203,60 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - run: npm ci
-      - run: npx harness check
-      - run: npx harness passes-gate
+      - run: harness check
+      - run: harness passes-gate
 ```
 
 ---
 
-## Trace 系统
-
-### Execution Trace
+## 📊 Trace & 日志
 
-记录约束检查结果，用于：
-- 统计触发频率
-- 检测异常（高绕过率、失败上升）
+### 目录结构
 
 ```
-.harness/traces/
-├── execution.log      # 当前 trace
-├── summary.json       # 统计汇总
+.harness/
+├── traces/
+│   ├── execution.log      # 约束检查记录（JSON Lines）
+│   └── summary.json       # 统计汇总
+└── state.json             # Harness 状态
 ```
 
-### Performance Trace
+### 查看日志
+
+```bash
+# 查看状态和统计
+harness status
 
-记录操作耗时，用于：
-- 监控慢操作
-- 检测超阈值
+# 查看详细统计
+harness status --detail
 
+# 只看异常
+harness status --anomalies
+
+# 分析最近 N 小时
+harness status --hours 48
 ```
-.harness/logs/
-├── performance.log    # 性能日志
-├── tokens.log         # Token 使用
+
+### 日志格式
+
+**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"}
 ```
 
-### Failure Classification
+**summary.json**：
+```json
+{"totalChecks":150,"passRate":0.92,"bypassRate":0.08,"anomalies":2}
+```
 
-错误分级（L1-L4）：
+### 异常检测
 
-| 等级 | 处理 |
-|------|------|
-| L1 | 自动重试 |
-| L2 | 人工审核 |
-| L3 | 开会讨论 |
-| L4 | 回滚 |
+当 `harness status --anomalies` 发现异常时，运行 `harness flow` 进行诊断和优化提案。
 
 ---
 
-## 开发
+## 🔧 开发
 
 ```bash
 npm install
@@ -334,6 +266,6 @@ npm test
 
 ---
 
-## 许可证
+## 📝 License
 
-MIT © dommaker
+MIT © dommaker