cyning-harness

npx @cyning/harness@latest init --preset harness-only --ide cursor,agents
npx @cyning/harness verify

可 clone、可嵌入业务仓库的 Harness 纪律包（无业务代码，无内置 LLM）· MIT 开源。

设计哲学：用 本体论 定义「Track / Hat / Gate / Artifact」与 ICVO 四支柱（Inform · Constrain · Verify · Orchestrate），把 AI Coding 的上下文、规则与验收变成 可同步、可审计、不覆盖用户 task 的仓库真值。
公众连载 使用 ICV 三支柱（SDD 层）；Orchestrate 是对卷三过程编排的 产品化命名，见 docs/methodology/product/README.md · docs/methodology/AUDIT_doc_consistency_2026-06-15_zh.md。
方法论总指引：docs/methodology/README.md · 本体 docs/methodology/product/DESIGN_ONTOLOGY_v1_zh.md

是什么

cyning-harness 提供在任意软件项目中落地 AI 辅助研发纪律所需的 模板、读序与过程约定：

| 轨 | 目录 | 作用 | |----|------|------| | 图谱 | graph/ | 架构地图模板（docs/_tech_graph 嵌入用） | | Wiki | coding_wiki/ | LLM 读序（stable / context / volatile） | | 规范 | standards/ | L1/L2 编码规范模板 | | 过程 | harness/ | task、prompts、invoke 约定 | | 验证 | ci/ | CI 门禁样例 | | IDE | ide/ | Cursor / Claude Code / AGENTS 入口片段 | | 向导 | wizard/ | 安装与勾选式初始化 |

不提供： 业务实现代码、LLM API、Agent 编排 SDK（与 LangChain 等互补 · 见本体 §7.5）。

边界（S2）： sync 不覆盖 docs/tasks/、reviews/、invokes/by-task/ — 纪律层与业务数据分离。

Quick Start（npx · v1.0）

顶部三行即最小接入。须在 目标业务仓根 执行（勿在本产品仓根跑 npx，会报 harness: command not found）。
陌生人完整手册：docs/USER_GUIDE_v1.0_zh.md

维护者 · 在本仓库根验证 CLI（npm 不会为「当前包」链接 bin，npx 会报 harness: command not found）：

npm run harness -- check --target /tmp/foo
# 或
node bin/harness.js check --target /tmp/foo

维护者 / 离线（clone 路径）：

git clone [email protected]:Cyning12/cyning-harness.git && cd cyning-harness
/path/to/cyning-harness/wizard/install.sh --target /path/to/your-repo --preset harness-only --ide cursor,agents
/path/to/cyning-harness/wizard/harness-sync.sh apply --target /path/to/your-repo

P0 金样： examples/demo_checkout/README.md · 完整帽链见 docs/methodology/product/SDD_HAT_FLOW_v2_zh.md

Kimi Code fork： --preset oss-fork-meta 或 wizard/bootstrap-oss-fork-meta.sh · 过程轨不进上游 PR。

典型工作流（V2）

人 + 00 大纲 → 10-spec → 20-spec-audit + HG-SPEC-SIGNOFF
  → 00 起草 task → 10-task → 20-task-audit + HG-AUDIT-R1
  → 30（含 40 自检闭环）→ [50] → CLOSE

Starter 包：10-task · 20-task-audit · 30 · 40 · 30 前 npx @cyning/harness verify · HG-AUDIT-R1 = approved

1. 阅读 docs/ONBOARDING.md
2. npx @cyning/harness init 或 wizard/install.sh / adopt-existing.sh
3. 产品包更新：npx @cyning/harness upgrade 或 wizard/upgrade.sh / harness-sync.sh apply
4. IDE @ task + docs/harness/prompts/；30 前 npx @cyning/harness verify 或 npx @cyning/harness gate-check

ICVO 机械审计（v1.0+）

npx @cyning/harness verify 在 30 执行前聚合检查 ICVO 公理子集：

npx @cyning/harness verify --target /path/to/your-repo --task docs/tasks/active/task_xxx.md
npx @cyning/harness gate-check --target /path/to/your-repo --task docs/tasks/active/task_xxx.md
npx @cyning/harness audit --target /path/to/your-repo --task docs/tasks/active/task_xxx.md
npx @cyning/harness upgrade --gate-check       # upgrade 前自动 audit

• D3：gate-check 真值唯一来源，HG-AUDIT-R1 / HG-GRAPH-MODULES pending 时拒 30
• D5：test_strategy=required 任务须声明测试路径或 CI 引用
• S5：dirty 工作区 warn，apply 须 --force 明示

Inform 图谱闸：npx @cyning/harness gate-check --graph --target /path/to/your-repo
Inform-YAML：npx @cyning/harness graph yaml compile|check --input docs/_tech_graph（v1.1+） HGM 过程轨：npx @cyning/harness graph ingest|snapshot|axioms check --target /path/to/your-repo（v2.0+）
Invoke 索引：npx @cyning/harness sync index --target /path/to/your-repo（不覆盖 S2 域）

Node 仓可选：npx @cyning/harness init --with-scripts → pnpm harness:verify。
详见 docs/USER_GUIDE_v1.0_zh.md · docs/ONBOARDING.md §2.2。

试点证据（B2）

冻结状态：2026-06-16 · 策略 A（3 字段未系统采集，标 N/A，不编造）
完整证据链：docs/methodology/execution/PILOT_EVIDENCE_B2_v1_zh.md

真实试点 retro（kimi-code-meta preset · 2026-06-10 → 2026-06-15）

| 指标 | 值 | 说明 | | --- | --- | --- | | sample_n | 6 | harness-only dogfood、文档修复、agent-core 改码等 | | upstream_pr_d6_clean | 3/3 = 100% | D6 双分支过程轨零泄漏（#622 / #630 / #708） | | ci_first_green_rate | 3/3 = 100% | 改码 task 首次 CI 绿（样本极小，禁止外推胜率） | | gate_block_count | 3+ | 30 前 gate-check 拦截样例已记录 | | failure_report_count | 1 | #94 越闸事件 → 修复 GATE_VERIFY 协议 | | audit_reject_rate | N/A | 策略 A：样本期未系统采集 22 R1 内容阻塞 | | audit_rounds_mean | N/A | 策略 A：同 audit_reject_rate | | wizard_adoption_days | N/A | 策略 A：install 日期未落盘，无法准确计算 |

SDD-Compliance micro-bench（可机械复现 · 不测 LLM 解题）

| 项 | 值 | | --- | --- | | 覆盖 | S1–S4（D2 HumanGate · D3 gate-check · S2 sync 域） | | 结果 | 4/4 = 100% | | 运行 | ./wizard/compliance-bench.sh --all · 说明 examples/compliance_bench/README.md |

免责声明：本表为 小样本机制证据，非胜率承诺；Part A 与 Terminal-Bench / SWE-bench 互补、不对标。

与通用 Agent 框架的差异（摘要）

| 维度 | cyning-harness | LangChain / Semantic Kernel 等 | | --- | --- | --- | | 定位 | 纪律包 · SDD 过程审计 | Agent 编排 / 工具链 SDK | | 过程落盘 | AuditReview · InvokeSnapshot · HumanGate | 通常无一等过程制品 | | 同步边界 | S2 · 不覆盖用户 Task | 不适用 |

完整对比：DESIGN_ONTOLOGY §7.5。

仓库结构

cyning-harness/
├── README.md
├── docs/
│   ├── README.md                  # 文档索引
│   ├── methodology/               # ★ 方法论总指引
│   │   ├── README.md
│   │   ├── DOCUMENT_MAP_v1_zh.md
│   │   ├── product/               # 产品设计本体
│   │   ├── graph/                 # HGM
│   │   ├── execution/             # P0 差距
│   │   └── pointers/              # 工作区 / 治理 POINTER
│   ├── ARCHITECTURE.md
│   └── ONBOARDING.md
├── examples/demo_checkout/
├── wizard/ · harness/ · graph/ …
└── golden/

版本与状态

| 项 | 值 | |----|-----| | 当前 | v2.0.0 — HGM G1 · graph ingest|snapshot|axioms · Inform-YAML · ICVO audit · invoke_index · gate-check --graph · B2 证据 | | 上一档 | v1.1.0 — Inform-YAML · graph yaml compile|check · ICVO audit · invoke_index · gate-check --graph · B2 证据 | | 许可 | MIT · LICENSE · Release docs/RELEASE_v1.0.0.md |

文档索引

| 优先级 | 文档 | | --- | --- | | 总指引 | methodology/README.md · 关系图 · 路线 ROADMAP | | 本体 | DESIGN_ONTOLOGY v1.2 | | 使用 | USER_GUIDE v1.0 · P0 差距 · 金样验收 · ETCLOVG 映射 | | 远期 | HGM 草案 | | 接入 | ONBOARDING · ARCHITECTURE |

根目录 docs/DESIGN_ONTOLOGY_v1_zh.md 等为 POINTER · 兼容旧链接。

变更与 Agent

• CHANGELOG.md
• AGENTS.md