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

源码安装

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"）

查看状态

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

版本信息

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 — 要求匹配，未匹配到则不通过

示例 — 禁止硬编码密钥：

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 请求：

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：

{
  "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）

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

# 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。

三套 preset

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

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

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

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

分支操作

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 规则文件

使用

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 协作

团队配置

# 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 判断存活状态：

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 检查：

# 安装 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）

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

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）

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

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 哈希、时间戳）

开发

构建

npm run build

测试

npm test

代码检查

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 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.