# HarnessToolKit 

RD Paradigm 3.0 流水线工具集 — 面向 AI-First 开发流程的 A2D（Architecture-to-Delivery）9-step 治理流水线、双层门禁（架构 envelope + 代码 gate）与多 Worker 协作工具包。
test

## 核心模块

| 模块 | 说明 |
|------|------|
| **Gate Engine** | 质量门禁引擎，支持四绑定点、五种规则类型、增量/全量双模式 |
| **Pipeline Runner** | 9-step 流水线执行器，依赖图驱动 + Skill 调度 + 人工 checkpoint |
| **Git Engine** | 分支策略与提交规范，声明式分支管理 |
| **Spec Compiler** | 规格文档编译器，将 Spec 自动编译为 Gate 规则 |
| **Team Engine** | 多 Worker 协作引擎，心跳检测、消息路由、审计日志 |

## 快速开始

### 发布包安装

对于普通用户，通过发布包的安装更方便，请移步release目录，查看QUICKSTART.MD


## 源码安装

```bash
git clone https://gitcode.com/SETools/HarnessToolKit.git
cd HarnessToolKit
npm install
npm run build
npm link

### 初始化项目

```bash
# 在当前目录生成脚手架
harness-rd-toolkit init

# 指定目标目录
harness-rd-toolkit init /path/to/project

# 强制覆盖已有文件
harness-rd-toolkit init --force

# 同时安装 Claude Code hooks（实现编辑时自动 Gate 检查）
harness-rd-toolkit init --install-hooks
```

初始化后会生成以下文件结构：

```
project/
├── pipeline.yaml              # 流水线定义
├── CONTEXT.md                 # 项目上下文（术语/ADR）
├── gates/
│   ├── rules/                 # Gate 规则文件
│   │   ├── security-design.yaml
│   │   ├── js-coding-style.yaml
│   │   ├── doc-structure.yaml
│   │   ├── language-style.yaml
│   │   └── content-elements.yaml
│   ├── bindings/              # 绑定点配置
│   │   ├── pre-edit.yaml
│   │   └── post-edit.yaml
├── pipeline-full.yaml         # 9-step 全流程 preset（可选）
├── pipeline-incremental.yaml  # 3-step 增量 preset（可选）
├── pipeline-lightweight.yaml  # 5-step 轻量 preset（可选）
├── .pipeline/                 # 流水线运行时状态
└── .claude/skills/            # Claude Code Skill 定义
    ├── harness-design/SKILL.md
    ├── harness-status/SKILL.md
    ├── compile-spec/SKILL.md
    ├── dev-start/SKILL.md
    ├── run-stack/                 # 全栈拉起与镜像重建（通用模板 + PROJECT_NOTES.md 机制）
    │   ├── SKILL.md
    │   ├── PROJECT_NOTES.md       # 项目特定拓扑/坑表/登录流程（消费项目填写）
    │   └── examples/agent-studio.md  # 实战样例
    ├── step-1-req-clarify/SKILL.md
    ├── step-2-code-scan/SKILL.md
    ├── step-3-envelope/SKILL.md
    ├── step-4-gate-derive/SKILL.md
    ├── step-5-slice/SKILL.md
    ├── step-6-implement/SKILL.md
    ├── step-7-reconcile/SKILL.md
    ├── step-8-baseline/SKILL.md
    ├── step-9-release/SKILL.md
    ├── gen-ui-testcases/             # 前端 Playwright E2E 用例生成 skill（5 阶段：静态推导→运行时探查→fixture→spec→自检）
    └── architecture-models-4plus1/   # 第三方 4+1 架构视图 skill（见末尾"第三方 Skill"）
```

### 查看状态

```bash
harness-rd-toolkit status          # 当前目录
harness-rd-toolkit status /path    # 指定目录
```

### 版本信息

```bash
harness-rd-toolkit version
```

## CLI 命令参考

```
harness-toolkit <command> [options]

Commands:
  version                         输出版本号
  init [dir]                      在目标目录初始化脚手架
    --force                       覆盖已有文件
    --install-hooks               安装 Claude Code hooks
  status [dir]                    查看流水线状态
  gate check --stdin              从 stdin 读取 JSON 执行 Gate 检查
  help                            输出帮助信息
```

---

## Gate Engine — 质量门禁

### 绑定点（Binding Points）

Gate Engine 支持四个绑定点，覆盖从阶段到编辑的全粒度：

| 绑定点 | 触发时机 | 用途 |
|--------|----------|------|
| `pre-stage` | 阶段开始前 | 阶段前置条件检查 |
| `post-stage` | 阶段结束后 | 阶段产出验收 |
| `pre-edit` | 文件编辑前 | 增量内容预检 |
| `post-edit` | 文件编辑后 | 文件全量复检 |

### 规则类型

| type | 说明 | 关键字段 |
|------|------|----------|
| `regex-check` | 正则匹配检查 | `pattern`, `match_mode`, `includes`, `excludes` |
| `yaml-field-check` | YAML 字段检查 | `file`, `required_fields`, `field`, `value` |
| `section-check` | 文档章节检查 | `file`, `required_sections` |
| `exec` / `custom` | 执行命令检查 | `command` |

### regex-check 规则详解

这是最常用的规则类型，支持两种匹配模式：

- **`match_mode: absent`**（默认）— 禁止匹配，匹配到则不通过
- **`match_mode: present`** — 要求匹配，未匹配到则不通过

示例 — 禁止硬编码密钥：

```yaml
rules:
  - id: sec-no-hardcoded-key
    type: regex-check
    blocking: true
    severity: error
    scope: incremental
    message: "禁止在代码中硬编码密钥"
    pattern: "(?:password|secret|private_key|api_key)\\s*[:=]\\s*['\"][^'\"]+['\"]"
    match_mode: absent
    includes:
      - "**/*.ts"
      - "**/*.js"
    excludes:
      - "**/*.d.ts"
      - "**/*.test.*"
```

### 增量模式 vs 全量模式

- **增量模式**（`pre-edit` 有 `edit.content` 时）：仅对编辑内容片段做 regex 检查，跳过 `full-only` 规则
- **全量模式**（无 content 或 `post-stage`）：从磁盘读取文件做完整检查

### 规则属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `id` | string | 规则唯一标识 |
| `blocking` | boolean | 不通过时是否阻止操作 |
| `severity` | `error` / `warning` / `hint` | 严重程度 |
| `scope` | `incremental` / `full-only` | 增量模式下是否跳过 |
| `source` | string | 规则来源引用 |
| `message` | string | 不通过时的提示信息 |
| `includes` | string[] | 文件 glob 白名单（空=全部） |
| `excludes` | string[] | 文件 glob 黑名单 |

### Gate CLI

通过 stdin 传入 JSON 请求：

```bash
echo '{"binding":"pre-edit","rulesFile":"gates/rules/security-design.yaml","projectRoot":"/path","edit":{"filePath":"src/foo.ts","content":"..."}}' \
  | harness-rd-toolkit gate check --stdin
```

返回 JSON：

```json
{
  "binding": "pre-edit",
  "blocked": false,
  "warnings": 1,
  "results": [
    { "ruleId": "sec-no-hardcoded-key", "passed": true, "blocking": true, "severity": "error", "message": "..." },
    { "ruleId": "sec-no-insecure-hash", "passed": true, "blocking": true, "severity": "error", "message": "..." }
  ]
}
```

退出码：`0` = 通过，`1` = 被阻止，`2` = 输入错误。

### 内置 Gate 规则集

| 规则文件 | 说明 |
|----------|------|
| `security-design.yaml` | 安全规范（禁止硬编码密钥、不安全哈希、不安全协议、旧版 SSL/TLS） |
| `js-coding-style.yaml` | JS/TS 编码风格（var 禁用、== 禁用、console.log 禁用等） |
| `doc-structure.yaml` | 文档结构（标题标点、层级限制、口语化用词） |
| `language-style.yaml` | 语言风格规范 |
| `content-elements.yaml` | 内容要素检查 |

### 绑定文件（Bindings）

绑定文件将绑定点与规则文件关联：

```yaml
# gates/bindings/pre-edit.yaml
binding: pre-edit
rules_files:
  - rules/security-design.yaml
  - rules/js-coding-style.yaml
```

### 降级策略

当 Gate 检查失败时，通过 `blocking` + `severity` 组合决定降级行为：

- **blocking=true + error** → 阻止操作
- **blocking=true + warning** → 阻止但允许覆盖
- **blocking=false** → 警告但继续

---

## Pipeline Runner — 流水线

当前默认流水线为 **A2D 9-step**（Architecture-to-Delivery），由两层法律体系守护：架构层（envelope → drift-check + contract-check）+ 代码层（既有 gate 规则）。早期 6 阶段流水线（requirements-analysis / arch-roundtable / task-decomposition / tdd-cycle / integration-verify / release-pack）已退役为 legacy，不再随 `init` 下发，详见 [docs/PRD-a2d-fusion.md](docs/PRD-a2d-fusion.md)。

### 三套 preset

| 文件 | 步数 | 适用场景 |
|------|------|----------|
| `pipeline.yaml`（默认） | 9 | 全流程治理，含 envelope、漂移检测、和事 |
| `pipeline-incremental.yaml` | 3 | 已稳定需求的小幅改动，跳过 step-1 |
| `pipeline-lightweight.yaml` | 5 | 中等改动，去掉 step-4/5/8/9 |

### pipeline.yaml 结构（默认 9-step 摘录）

```yaml
pipeline:
  name: a2d-default
  dependencies:
    step-2-code-scan: ["step-1-req-clarify"]
    step-3-envelope: ["step-2-code-scan"]
    step-4-gate-derive: ["step-3-envelope"]
    step-5-slice: ["step-3-envelope"]
    step-6-implement: ["step-4-gate-derive", "step-5-slice"]
    step-7-reconcile: ["step-6-implement"]
    step-8-baseline: ["step-7-reconcile"]
    step-9-release: ["step-8-baseline"]
  stages:
    - name: step-1-req-clarify
      skill: step-1-req-clarify
      outputs: ["raw-intent.yaml", "version-requirements.yaml"]
      checkpoint: { type: human, id: H0, description: "Confirm clarified requirements" }
    # ...step-2..step-9
```

### 流水线步骤流程

```
step-1-req-clarify ──▶ step-2-code-scan ──▶ step-3-envelope ──┬──▶ step-4-gate-derive ──┐
   [H0 人工确认]            (auto)              [H1 人工确认]  │                         ├──▶ step-6-implement ──▶ step-7-reconcile ──▶ step-8-baseline ──▶ step-9-release (optional)
                                                              └──▶ step-5-slice ─────────┘                              [H3 人工确认]
```

依赖图在 `dependencies` 中声明，runner 据此支持回溯：vibe coding 用户从任意 step 进入时，若上游 artifact 缺失，会按依赖图反向触发 artifact resolver 回填。

### Skill 调度

Skill 定义在 `.claude/skills/<name>/SKILL.md`，包含 frontmatter 元数据和 workflow 正文。Pipeline Runner 通过 `skill-driver.ts` 加载描述符，解析 frontmatter，构建上下文变量插值后的 prompt。

### 核心步骤说明

| Step | Skill | 模式 | 产出 | 说明 |
|------|-------|------|------|------|
| 1 | `step-1-req-clarify` | direct | raw-intent.yaml, version-requirements.yaml | 需求澄清，H0 人工确认 |
| 2 | `step-2-code-scan` | auto | code-scan-evidence.yaml | 现状扫描，无需人工 |
| 3 | `step-3-envelope` | direct | architecture-envelope.yaml, review-packet.yaml | 架构包络生成，H1 人工确认开发边界 |
| 4 | `step-4-gate-derive` | auto | gate-derivation.yaml | 从 envelope 派生 drift-check / contract-check 规则 |
| 5 | `step-5-slice` | direct | delivery-projection.yaml | 垂直切片投映 |
| 6 | `step-6-implement` | team | implementation-evidence.yaml | 团队实现，每个 slice 后跑 drift-check |
| 7 | `step-7-reconcile` | auto | post-projection-check.yaml | 后置校验，H3 人工确认；两波：硬门 + 可视化 |
| 8 | `step-8-baseline` | direct | baseline-decision.yaml | 基线化，处理 L2/L3 升级 deferred 项 |
| 9 | `step-9-release` | auto | release-notes | 可选，无 release-bar 的项目跳过 |

> Step 6 仍由 `teams/tdd-team.yaml` 编排 implementer/reviewer/integrator 三角协作；其它 step 多为 `direct` 或 `auto` 模式。早期 6 阶段方案中的 `arch-roundtable`、`task-decomposition`、`integration-verify`、`release-pack` 四个 skill 与配套 gate/team 文件保留在仓库内供历史项目追溯，不再下发到新项目。

---

## Git Engine — 分支与提交

### git-strategy.yaml

```yaml
defaults:
  main_branch: main
  commit_prefix: true

types:
  - name: feature
    prefix: feat/
    merge_to: main
  - name: bugfix
    prefix: fix/
    merge_to: main
  - name: architecture
    prefix: arch/
    merge_to: main
  - name: release
    prefix: release/
    merge_to: main
```

### 分支操作

```typescript
import { createBranch, getMergeTarget } from 'harness-toolkit/git-engine'

// 创建分支（如已存在则跳过）
const result = createBranch('feature', 'REQ-2026-001', strategy, cwd)
// result: { branchName: 'feat/REQ-2026-001', baseBranch: 'main', created: true, alreadyExisted: false }

// 获取合并目标
const target = getMergeTarget('feature', strategy) // 'main'
```

### Commit Hook

Git Engine 支持在提交时自动执行 commit message 规范校验，确保符合项目约定。

---

## Spec Compiler — 规格编译

将规格文档自动编译为 Gate 规则，实现"规格即规则"的闭环。

### 工作流程

```
规格文档 → parser.ts 解析 → compiler.ts 编译 → rules-registry.ts 分类 → Gate 规则文件
```

### 使用

```typescript
import { compileSpec, parseSpecDoc } from 'harness-toolkit/spec-compiler'

// 解析规格文档
const parsed = parseSpecDoc(specContent)

// 编译为 Gate 规则
const result = compileSpec(parsed, {
  outputPath: 'gates/rules/generated-from-spec.yaml',
  defaultSeverity: 'error',
  defaultBlocking: true,
})
```

### 规则模式（Rule Modes）

`rules-registry.ts` 定义了规则模式分类与默认属性，用于推断规则类型和范围：

- 根据 spec 条目的模式（禁止/要求/结构/执行）自动选择 `regex-check` / `yaml-field-check` / `section-check` / `exec`
- 自动推断 `includes` / `excludes` 文件范围

---

## Team Engine — 多 Worker 协作

### 团队配置

```yaml
# teams/tdd-team.yaml
team:
  name: tdd-team
  description: "TDD cycle execution team"

  params:
    max_rejections: 3

  members:
    - name: developer-1
      role: implementer
      provider: claude
      capabilities: [code-edit, testing, refactoring]

    - name: reviewer
      role: reviewer
      provider: claude
      capabilities: [code-review, testing, architecture]

    - name: integrator
      role: integrator
      provider: codex
      capabilities: [code-edit, refactoring, general]
```

### 核心模块

| 模块 | 说明 |
|------|------|
| `team-ops.ts` | 团队操作（注册/注销/查询） |
| `team-registration.ts` | 成员注册与发现 |
| `phase-controller.ts` | 阶段流转控制 |
| `worker-bridge.ts` | Worker 通信桥接 |
| `message-router.ts` | 消息路由（按角色分发） |
| `heartbeat.ts` | 心跳检测（判断 Worker 存活） |
| `task-file-ops.ts` | 任务文件读写 |
| `audit-log.ts` | 审计日志 |

### 心跳机制

Worker 定期写入心跳文件，系统根据 `maxAgeMs` 判断存活状态：

```typescript
import { isWorkerAlive } from 'harness-toolkit/team'

const alive = isWorkerAlive('tdd-team', 'developer-1', cwd, 60000) // 60s 超时
```

### Provider 适配

| Provider | deliveryMethod | 说明 |
|----------|---------------|------|
| `claude` | `sendmessage` | Claude 原生成员，通过 SendMessage 通信 |
| `codex` | CLI | 通过命令行启动 |
| `gemini` | API | 通过 API 调用 |

---

## Claude Code Hooks

安装 hooks 后，每次使用 Claude Code 编辑文件都会自动触发 Gate 检查：

```bash
# 安装 hooks
harness-rd-toolkit init --install-hooks
```

Hook 工作流：

```
Edit/Write 工具调用 → PreToolUse hook (pre-edit gate) → 执行编辑 → PostToolUse hook (post-edit gate)
```

- **pre-edit hook**：在编辑前检查内容片段（增量模式），阻止不合规修改
- **post-edit hook**：在编辑后检查文件全量，验证最终状态

所有 hook 都通过 `node "scripts/hooks/*.mjs"` 调用，跨 Windows / WSL / Linux / macOS，不需要 bash 或 POSIX 工具链。从旧版本升级的用户请重跑 `harness-rd-toolkit init --install-hooks --force` 刷新 `.claude/settings.local.json`。

---

## 集成验证（integration-verify）

特性合并状态追踪与集成测试验证：

```typescript
import { mergeFeature, runIntegrationVerify } from 'harness-toolkit/pipeline'

// 合并特性分支
const status = mergeFeature('REQ-2026-001', 'feat/REQ-2026-001', 'main', cwd)
// status: 'merged' | 'partially-merged' | 'not-merged'

// 执行集成验证
const result = runIntegrationVerify(input, cwd)
```

---

## 发布打包（release-pack）

预发布检查 → 发布笔记生成 → 产物打包：

```typescript
import { runReleasePack } from 'harness-toolkit/pipeline'

const result = runReleasePack('REQ-2026-001', '1.2.0', {
  mergeStatus: { 'REQ-2026-001': 'merged' },
  testResults: { totalPassed: 42, totalFailed: 0 },
  openDefects: 0,
  features: [{ id: 'REQ-2026-001', name: 'New Feature', tasks: [], mergeStatus: 'merged' }],
  adrs: ['ADR-001: Use event sourcing'],
  dfxBudget: 'Performance: 20ms p99 latency reduction',
}, cwd)
```

发布检查项：
- 所有特性必须 `merged`（不允许 `partially-merged` 或 `not-merged`）
- 测试零失败
- 零开放缺陷

通过后生成：
- `.pipeline/release-notes-<requestId>.md` — 发布笔记
- `.pipeline/release-manifest.json` — 发布清单（含版本、SHA256 哈希、时间戳）

---

## 开发

### 构建

```bash
npm run build
```

### 测试

```bash
npm test
```

### 代码检查

```bash
npm run lint
```

### 项目技术栈

- **语言**: TypeScript
- **构建**: tsup
- **测试**: Vitest
- **运行时**: Node.js 18+
- **包管理**: npm

---

## 项目结构

```
src/
├── cli.ts                      # CLI 入口
├── index.ts                    # 库导出
├── version.ts                  # 版本常量
├── commands/
│   └── init.ts                 # init 命令实现（脚手架生成 + hooks 安装）
├── gate-engine/
│   ├── index.ts                # Gate 核心引擎（规则加载、执行、报告）
│   ├── types.ts                # 类型定义
│   └── degradation.ts          # 降级策略
├── git-engine/
│   ├── index.ts                # Git Engine 导出
│   ├── types.ts                # 分支策略类型
│   ├── strategy.ts             # 策略加载
│   ├── branch.ts               # 分支操作
│   └── commit-hook.ts          # Commit hook
├── pipeline/
│   ├── index.ts                # Pipeline 导出
│   ├── runner.ts               # 流水线执行器
│   ├── skill-driver.ts         # Skill 加载与状态查询
│   ├── skill-dispatch.ts       # Skill prompt 构建
│   ├── dev-start.ts            # 开发启动
│   ├── task-decomposition.ts   # 任务分解
│   ├── tdd-cycle.ts            # TDD 循环
│   ├── roundtable-exec.ts      # 架构圆桌执行
│   ├── integration-verify.ts   # 集成验证
│   └── release-pack.ts         # 发布打包
├── spec-compiler/
│   ├── index.ts                # Spec Compiler 导出
│   ├── types.ts                # 编译类型
│   ├── parser.ts               # 规格文档解析器
│   ├── compiler.ts             # 规则编译器
│   └── rules-registry.ts       # 规则模式注册表
├── team/
│   ├── team-ops.ts             # 团队操作
│   ├── team-registration.ts    # 成员注册
│   ├── types.ts                # 团队类型
│   ├── phase-controller.ts     # 阶段控制器
│   ├── worker-bridge.ts        # Worker 桥接
│   ├── message-router.ts       # 消息路由
│   ├── heartbeat.ts            # 心跳检测
│   ├── task-file-ops.ts        # 任务文件操作
│   ├── audit-log.ts            # 审计日志
│   ├── capabilities.ts         # 能力定义
│   ├── state-paths.ts          # 状态文件路径
│   └── fs-utils.ts             # 文件系统工具
├── providers/
│   ├── index.ts                # Provider 导出
│   ├── types.ts                # 适配器接口
│   ├── claude-adapter.ts       # Claude 适配器
│   ├── codex-adapter.ts        # Codex 适配器
│   └── gemini-adapter.ts       # Gemini 适配器
gates/                          # Gate 规则与绑定
docs/                           # 文档（PRD、ADR、Issues）
teams/                          # 团队配置
scripts/                        # 构建与 hooks 脚本
tests/                          # 测试文件
.pipeline/                      # 流水线运行时状态
```

## 第三方 Skill

本仓库内置以下第三方 Skill，由 `harness init` / `harness update` 默认安装到目标项目的 `.claude/skills/`：

| Skill | 来源仓库 | 用途 | 许可 |
|-------|---------|------|------|
| `architecture-models-4plus1` | [MarieLynneBlock/arcanum-artifex](https://github.com/MarieLynneBlock/arcanum-artifex) `skills/architecture/architecture-models-4plus1/` | 产出 Philippe Kruchten 4+1 架构视图文档（逻辑/进程/开发/物理 + 场景），主用 Mermaid、PlantUML 为部署视图回退，并为每个视图生成 Miro RISEN 提示。支持零输入/访谈/部分视图三种模式，可按受众切换记法（UML / BPMN 泳道 / 简化 C4）。触发词：`4+1`、`architecture views`、`logical view`、`process view`、`development view`、`physical view`、`deployment view` 等。 | 上游仓库未声明 LICENSE（`license` 字段为 null），默认保留所有权利。本仓库以源码原样集成供内部使用；若需对外再分发，请先向上游确认授权。 |
| `diagnose` | Matt Pocock Standalone Skills（`~/.agents/skills/diagnose`） | 定位并修复难复现/难定位的 bug 或性能回归。独立 debug skill，不绑流水线，按需触发。触发词：`diagnose this` / `debug this`、报告 bug、说"坏了/报错/失败"、描述性能回归。 | 上游未声明 LICENSE，默认保留所有权利。本仓库以源码原样集成供内部使用；若需对外再分发，请先向上游确认授权。 |

以上 Skill 的文件位于目标项目的 `.claude/skills/<skill-name>/`，不在本仓库自定义 Skill 列表内，不参与 Pipeline Runner 调度，由用户在 Claude Code 会话中按需触发。

### diagnose 详解 （问题定位与修复）

**触发时机**：碰到难复现、难定位的 bug（时好时坏、复现不稳定），或性能出现非预期回归时，在任意支持 skill 的 agent 会话里触发 `/diagnose`。

**调用示例**：`/diagnose 这个接口偶发返回 500，本地复现不出来`

**六步定位法**（每步都要做，跳过必须有明确理由）：

1. **先造一个能跑的复现信号**。这是最关键的一步——找一个又快又稳定、agent 能自动跑的"通过/失败"判定器。常见做法：失败的测试、curl 打接口、CLI 对比输出、Playwright 驱动浏览器、trace 回放、最小 harness、fuzz 一千次、git bisect、新旧版本差分，最后才是 HITL 脚本让人工点击。**有了它，bug 90% 已经解决了**。

2. **把复现案例压到最小**。砍掉一切无关的输入和步骤，让 bug 用最短路径暴露——小到能一眼看完。

3. **写下根因假设**。不是"我觉得可能是 X"，而是"如果根因是 X，改 Y 应该会让 bug 消失"——要能被证伪。

4. **埋点验证假设**。在假设指向的位置加日志、计数器、断点，跑一遍复现信号，看数据对不对得上。

5. **最小改动修复**。只改验证过的根因，不顺手重构、不扩大改动面。

6. **固化为回归测试**。把复现案例变成自动化测试，确保这个 bug 不会再悄悄回来。

## 许可证

Private — All rights reserved.