@dommaker/harness 0.8.1 → 0.9.0

package/README.md

@@ -1,199 +1,171 @@
 # @dommaker/harness
 
-> AI Agent 的工程约束框架 — 让 Agent 不会乱承诺、不会跳过验证、不会简化测试。
+> AI Agent 工程约束框架 — 从代码质量约束到知识积累引擎
 
----
-
-## 🚀 快速开始
+[![npm version](https://img.shields.io/npm/v/@dommaker/harness)](https://www.npmjs.com/package/@dommaker/harness)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-### 安装
+## 定位
 
-```bash
-npm install -g @dommaker/harness
 ```
-
-### 最小工作流
-
-```bash
-# 开发前
-harness check
-
-# 开发 + 写测试
-
-# 提交前
-harness passes-gate
+代码质量约束（补偿模型弱点）
+        ↓
+知识积累基础设施（模型做不到的事）
++ 最小安全护栏（模型无关的底线）
 ```
 
----
-
-## 📋 CLI 命令
-
-### 日常使用
-
-```bash
-harness check           # 检查铁律（开发前后必用）
-harness passes-gate     # 测试门控（提交前验证）
-harness status          # 查看状态（异常、统计）
-harness flow            # 一键诊断 + 提案流程
-```
+**核心理念：Harness 不是目的，知识才是护城河。**
 
-### 项目初始化
+Skill、Agent、工具链会随模型迭代更新，但领域知识是永恒的。
 
-```bash
-harness init --preset standard    # 初始化配置
-harness init --print-snippets     # 输出代码片段
-```
+---
 
-### 门禁检查
+## 安装
 
 ```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 详情
+npm install @dommaker/harness
 ```
 
-### Spec 验证
+### CLI
 
 ```bash
-harness spec            # 验证所有 Spec
-harness spec --staged   # 验证暂存文件
-harness spec list       # 支持的 Spec 类型
+harness check                # 检查约束（开发前后）
+harness passes-gate          # 测试门控（提交前）
+harness status               # 查看状态和异常
+harness flow                 # 一键诊断 + 优化提案
+harness init --preset standard  # 初始化配置
 ```
 
-### 检查点验证
+### 作为库使用
 
-```bash
-harness validate                     # 验证检查点
-harness validate --strict            # 严格模式
-harness validate -f checkpoint.json  # 指定文件
-```
+```typescript
+import {
+  // 约束系统
+  checkConstraints,
+  checkBeforeExecution,
+  interceptOperation,
+  // 知识引擎
+  KnowledgeService,
+  // 安全护栏
+  SafetyService,
+  // 上下文管理
+  ContextService,
+  // Agent 生命周期
+  AgentService,
+} from '@dommaker/harness';
 
-### 报告
+// 约束检查
+const result = await checkConstraints(context);
+if (!result.passed) {
+  console.error(result.ironLaws.filter(r => !r.passed));
+}
 
-```bash
-harness report                        # 生成 Markdown 报告
-harness report -f json                # JSON 格式
-harness report -o report.md           # 输出到文件
-```
+// 知识查询
+const knowledge = KnowledgeService.getInstance();
+const docs = await knowledge.getQuery().search('architecture decisions');
 
-### 诊断
+// 安全护栏
+const safety = SafetyService.getInstance();
+const guardrail = safety.getInputGuardrail();
+await guardrail.check(userInput);
 
-```bash
-harness flow                          # 一键诊断 + 提案
-harness flow --auto-apply             # 自动应用低风险提案
+// Token 预算
+const ctx = ContextService.getInstance();
+const budget = ctx.getBudget();
+budget.allocate('system', 2000);
+budget.allocate('user', 4000);
 ```
 
 ---
 
-## 🎯 核心概念
+## 核心架构
 
 ### 三层约束体系
 
 | 层级 | 严重性 | 说明 |
 |------|:------:|------|
-| **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 | 验收标准检查 |
+| **Iron Law** | error | 绝对禁止，无例外（7 条） |
+| **Guideline** | warning | 推荐遵守，有例外（9 条） |
+| **Tip** | info | 信息性提示（2 条） |
+
+### 子系统
+
+| 模块 | 目录 | 说明 |
+|------|------|------|
+| **约束引擎** | `core/`, `constraints/` | 三层约束检查、拦截器、自定义约束配置 |
+| **知识引擎** | `knowledge/` | 存储、查询、引用追踪、质量检查、生命周期（draft→canonical→archived） |
+| **上下文管理** | `context/` | Token 预算、会话压缩、渐进式加载、知识注入 |
+| **安全护栏** | `safety/` | 输入/输出/工具调用安全检查、沙箱（L1-L4） |
+| **验证循环** | `verification/` | 规则引擎 + 推理验证，支持检查点恢复 |
+| **门禁系统** | `gates/` | 8 种门禁：测试/验收/性能/安全/契约/审查/命令/检查点 |
+| **监控** | `monitoring/` | Trace 收集分析、约束诊断/进化、知识诊断/进化 |
+| **Agent 管理** | `agents/` | Agent 生命周期状态机（init→running→completed） |
+| **LLM 集成** | `llm/` | LLM 适配层，支持多 provider |
+| **失败处理** | `failure/` | 错误分类、失败记录 |
+| **Dashboard** | `dashboard/` | 统计面板、状态展示 |
+| **架构约束** | `architecture/` | 架构级约束检查、跨项目依赖检查 |
+| **Spec 检查** | `spec/` | 代码注解中的 Spec 验证 |
 
 ---
 
-## 🔧 代码集成
+## CLI 命令
 
-```typescript
-import {
-  IronLawChecker,
-  PassesGate,
-  CheckpointValidator,
-  interceptOperation,
-} from '@dommaker/harness';
+### 日常
 
-// 铁律检查
-const checker = IronLawChecker.getInstance();
-const results = await checker.checkAll(context);
+```bash
+harness check                    # 约束检查
+harness passes-gate [options]    # 测试门控（别名: pg）
+harness status [--anomalies]     # 状态查看
+harness flow [--auto-apply]      # 诊断 + 提案
+```
 
-// 测试门控
-const gate = new PassesGate({ requireEvidence: true });
-const passed = await gate.runTests();
+### 门禁
 
-// 检查点验证
-const validator = CheckpointValidator.getInstance();
-const result = await validator.validate(checkpoints, context);
+```bash
+harness acceptance [--task-id ID] [--check-all]  # 验收标准（别名: acc）
+harness performance [--coverage] [--bundle]       # 性能门控（别名: perf）
+harness security [--severity level]               # 安全检查（别名: sec）
+harness contract [--contract-path path]           # API 契约验证
+harness review [--min-reviewers N]                # PR 审查检查
+harness command "command string"                  # 命令黑名单（别名: cmd）
+```
 
-// 拦截器（自动执行 enforcement）
-await interceptOperation('task_completion_claim', context);
+### 其他
+
+```bash
+harness init [--preset standard|strict|relaxed]  # 初始化
+harness validate [--strict]                       # 检查点验证
+harness spec [--staged]                           # Spec 验证
+harness report [-f json|markdown] [-o file]       # 报告生成
 ```
 
 ---
 
-## 📁 项目配置
+## 配置
 
 ### .harness/config.yml
 
 ```yaml
-preset: standard
+preset: standard  # standard | strict | relaxed
 
 # 自定义约束例外
 custom_constraints:
   no_fix_without_root_cause:
     extend_exceptions:
-      - my_special_case
+      - hotfix_branch
 ```
 
-### CI 集成
+### Presets
+
+| Preset | 说明 |
+|--------|------|
+| `strict` | 全部约束启用（Iron Laws + Guidelines + Tips） |
+| `standard` | Iron Laws + Guidelines（默认） |
+| `relaxed` | 仅 Iron Laws |
+
+---
+
+## CI 集成
 
 ```yaml
 # .github/workflows/harness-check.yml
@@ -209,63 +181,34 @@ jobs:
 
 ---
 
-## 📊 Trace & 日志
+## 日志与诊断
 
-### 目录结构
+运行时状态存储在 `.harness/` 目录：
 
 ```
 .harness/
-├── traces/
-│   ├── execution.log      # 约束检查记录（JSON Lines）
-│   └── summary.json       # 统计汇总
-└── state.json             # Harness 状态
+├── traces/           # 约束检查记录（JSON Lines）
+├── failures/         # 失败记录
+└── state.json        # 运行状态
 ```
 
-### 查看日志
-
 ```bash
-# 查看状态和统计
-harness status
-
-# 查看详细统计
-harness status --detail
-
-# 只看异常
-harness status --anomalies
-
-# 分析最近 N 小时
-harness status --hours 48
-```
-
-### 日志格式
-
-**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"}
+harness status --anomalies    # 查看异常
+harness status --hours 48     # 最近 48 小时统计
+harness flow --auto-apply     # 诊断 + 自动应用低风险提案
 ```
 
-**summary.json**：
-```json
-{"totalChecks":150,"passRate":0.92,"bypassRate":0.08,"anomalies":2}
-```
-
-### 异常检测
-
-当 `harness status --anomalies` 发现异常时，运行 `harness flow` 进行诊断和优化提案。
-
 ---
 
-## 🔧 开发
+## 开发
 
 ```bash
 npm install
-npm run build
-npm test
+npm run build          # 编译 TypeScript
+npm test               # 运行测试（覆盖率阈值 50%）
+npm run lint           # ESLint
 ```
 
----
-
-## 📝 License
+## 许可证
 
-MIT © dommaker
+MIT

package/bin/harness.js

@@ -7,13 +7,14 @@
  */
 
 const { Command } = require('commander');
-const { 
-  check, 
-  listLaws, 
-  validate, 
-  runPassesGate, 
+const { version } = require('../package.json');
+const {
+  check,
+  listLaws,
+  validate,
+  runPassesGate,
   checkCoverage,
-  init, 
+  init,
   report,
   status,
   flow,
@@ -27,7 +28,8 @@ const {
   contract,
   validateSchema,
   review,
-  reviewStatus
+  reviewStatus,
+  executeCommand,
 } = require('../dist/cli/commands/index');
 
 const program = new Command();
@@ -35,7 +37,7 @@ const program = new Command();
 program
   .name('harness')
   .description('通用工程约束框架 - 铁律系统、检查点验证、测试门控、执行追踪')
-  .version('0.8.0');
+  .version(version);
 
 // ========================================
 // harness check
@@ -116,7 +118,7 @@ program
   .command('report')
   .description('生成检查报告')
   .option('-o, --output <path>', '输出文件路径')
-  .option('-f, --format <format>', '输出格式 (json/markdown)', 'markdown')
+  .option('-f, --format <format>', '输出格式 (json/markdown/html)', 'markdown')
   .option('-p, --project-path <path>', '项目路径')
   .action(async (options) => {
     await report(options);
@@ -260,7 +262,7 @@ program
   .description('API 契约门控，检查 OpenAPI Schema')
   .option('-p, --project-path <path>', '项目路径')
   .option('--contract-path <path>', '契约文件路径', 'openapi.yaml')
-  .option('--strict', '严格模式', true)
+  .option('--no-strict', '关闭严格模式')
   .option('--allow-breaking', '允许破坏性变更', false)
   .action(async (subcommand, options, command) => {
     if (subcommand === 'validate') {
@@ -278,8 +280,8 @@ program
   .description('代码审查门控，检查审查状态')
   .option('-p, --project-path <path>', '项目路径')
   .option('--min-reviewers <n>', '最少审查人数', '1')
-  .option('--require-approval', '要求审批', true)
-  .option('--block-on-changes', '阻止变更请求', true)
+  .option('--no-require-approval', '不要求审批')
+  .option('--no-block-on-changes', '不阻止变更请求')
   .option('--allowed-reviewers <list>', '允许的审查者（逗号分隔）')
   .action(async (subcommand, options, command) => {
     if (subcommand === 'status') {
@@ -295,5 +297,20 @@ program
     }
   });
 
+// ========================================
+// harness command
+// ========================================
+program
+  .command('command [cmd]')
+  .description('检查命令是否在黑名单中')
+  .alias('cmd')
+  .option('-l, --level', '显示风险等级')
+  .option('--list', '列出所有黑名单规则')
+  .option('--json', 'JSON 格式输出')
+  .option('--strict', '严格模式（warn 也阻止）')
+  .action(async (cmd, options) => {
+    await executeCommand(cmd, options);
+  });
+
 // 解析命令行参数
 program.parse();

package/dist/agents/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './lifecycle';
+//# sourceMappingURL=index.d.ts.map

package/dist/agents/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC"}

package/dist/agents/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./lifecycle"), exports);
+//# sourceMappingURL=index.js.map

package/dist/agents/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,8CAA4B"}

package/dist/agents/lifecycle.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Agent 生命周期管理
+ *
+ * 管理 Agent 的启动、监控、回退、终止
+ */
+import type { AgentConfig, AgentState, AgentStatus, AgentEvent, FallbackStrategy } from './types';
+export type EventHandler = (event: AgentEvent) => void;
+export declare class AgentLifecycle {
+    private agents;
+    private configs;
+    private strategies;
+    private eventHandlers;
+    constructor();
+    /**
+     * 注册 Agent
+     */
+    register(config: AgentConfig): AgentState;
+    /**
+     * 启动 Agent
+     */
+    start(id: string): AgentState | undefined;
+    /**
+     * 完成 Agent
+     */
+    complete(id: string, metadata?: Record<string, unknown>): AgentState | undefined;
+    /**
+     * 标记失败
+     */
+    fail(id: string, error: string): AgentState | undefined;
+    /**
+     * 终止 Agent
+     */
+    terminate(id: string): AgentState | undefined;
+    /**
+     * 获取 Agent 状态
+     */
+    getState(id: string): AgentState | undefined;
+    /**
+     * 获取所有 Agent 状态
+     */
+    getAllStates(): AgentState[];
+    /**
+     * 按状态过滤
+     */
+    getByStatus(status: AgentStatus): AgentState[];
+    /**
+     * 注册回退策略
+     */
+    addFallbackStrategy(strategy: FallbackStrategy): void;
+    /**
+     * 注册事件处理器
+     */
+    onEvent(handler: EventHandler): void;
+    /**
+     * 应用回退策略
+     */
+    private applyFallbackStrategies;
+    private emit;
+    /**
+     * 移除 Agent
+     */
+    remove(id: string): boolean;
+    /**
+     * 清空所有 Agent
+     */
+    clear(): void;
+}
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/agents/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/agents/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,UAAU,EACV,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAEjB,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;AAEvD,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,aAAa,CAAiB;;IAStC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU;IAYzC;;OAEG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAUzC;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,GAAG,SAAS;IAWhF;;OAEG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAavD;;OAEG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAU7C;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI5C;;OAEG;IACH,YAAY,IAAI,UAAU,EAAE;IAI5B;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,EAAE;IAI9C;;OAEG;IACH,mBAAmB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAIrD;;OAEG;IACH,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAIpC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAqC/B,OAAO,CAAC,IAAI;IAUZ;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAK3B;;OAEG;IACH,KAAK,IAAI,IAAI;CAId"}