内容
# 韵律
[](https://github.com/manehorizons/cadence/actions/workflows/ci.yml)
**韵律阻止AI代理交付他们声称但未完成的工作** — 一个草稿→构建→结算的循环，其质量门控重新检查验收标准，并在未通过时拒绝结算。
> **"您的持续集成是绿色的，但韵律仍然说不。"**
代理遇到一个失败的测试，破坏了断言，并留下了一个看似合理的借口（`// 某些平台上的浮点运算问题？暂时禁用`）。测试套件通过，任务被标记为完成。然后 `cadence settle run --auto` 仍然拒绝，指出特定的验收标准和特定的回避，退出状态码为1。真正修复了问题，恢复了断言，它就干净地结算了。实际输出，离线，模拟验证器，零npm依赖 — 自己运行： **[docs/DEMO.md →](https://github.com/manehorizons/cadence/blob/main/docs/DEMO.md)** （完整的4拍叙述）或 `examples/demo-test-gutting/run-demo.sh` （在本地重放）。
<details>
<summary>另见：100/3演示（算术错误，不是代理欺骗）</summary>
上面，总是触发的 `build-test-must-pass` 门控阻止了一个可能的丢失一分钱的错误，在一个分钱分割器中 — `$100.00` 分成3份，合计 `$99.99`。AI将任务标记为 **完成**；门控不同意，拒绝关闭循环。演示仓库将故事进行到阻塞之后 — 修复，然后在 `$100.00` 实际分成 `$100.00` 后进行干净的 **结算** — 带有真正的git历史和自行复制的步骤： **[cadence-demo-billsplit →](https://github.com/manehorizons/cadence-demo-billsplit)**
</details>
## 技术评审
韵律是一个开源的TypeScript开发者工具，用于AI辅助软件工作流。它使用带有可配置质量门控的草稿→构建→结算循环，以在工作被视为完成之前验证声明的验收标准。它可以从CLI、Claude Code、Codex或任何支持MCP的宿主通过其本地MCP服务器驱动。
**问题。** AI编码代理可以产生看似合理的工作，并在实际验证所需行为之前将任务标记为完成。
**解决方案。** 韵律将AI辅助开发包装在一个草稿→构建→结算循环中。工作从声明的验收标准开始，通过明确的任务，并在配置的门控重新检查工作状态之前无法结算。
**为什么它很重要。** 韵律为采用AI编码代理提供了一个实用的控制层，而不将代理的自我报告视为证据。
**架构概览。** 一个核心引擎通过CLI、宿主适配器（Claude Code、Codex）和MCP服务器公开。相同的循环和门控逻辑在每个表面保持权威。
```mermaid
flowchart LR
人类[人类操作员] --> 表面{入口表面}
代理[AI代理] --> 表面
表面 --> CLI[cadence CLI]
表面 --> 宿主["宿主适配器<br>Claude Code + Codex"]
表面 --> MCP[cadence mcp serve]
CLI --> 核心["核心引擎<br>草稿 → 构建 → 结算"]
宿主 --> 核心
MCP --> 核心
核心 --> 状态[(.cadence 状态 + 工件)]
核心 --> 门控[质量门控]
门控 --> 验收标准[验收标准]
门控 --> 测试[测试 / 验收证据]
门控 --> 验证器["验证器提供者<br>模拟 / 安斯罗皮克 / 本地 / 宿主-cli"]
门控 --> 拒绝[拒绝结算]
门控 --> 结算[结算阶段]
```
在 [GitHub Releases](https://github.com/manehorizons/cadence/releases) 上查看软件包变更日志、npm发布状态和发布验证说明。
## 为什么存在
韵律源于与 **GSD（Get Shit Done）** 的合作 — 一个产生真正有纪律的工作的规划框架，但代价高昂，耗时长，且需要不断的反复。我希望有这种纪律，但不要这种代价。
所以，韵律不是GSD-lite。它保留了质量门控 — 它们重新检查验收标准，并在未经验证的工作未通过时拒绝结算 — 但允许您为给定的更改选择触发哪些门控。复杂的、高风险的更改会经过完整的检查；一行修复不需要付出这么多。相同的严格性，但阻力要小得多。
## 一个引擎，三个表面类别
韵律有一个 **核心引擎和三个表面类别** — CLI、宿主适配器和MCP服务器 — 用于 **四个当前入口点**:
- **`cadence` CLI** 是引擎 — 它实现了草稿→构建→结算循环和所有质量门控。您在终端中运行它；人类操作员或AI代理可以驱动它。完全与宿主无关。
- **宿主适配器** 将同一个引擎连接到特定的编码代理的生命周期 — 目前有两个：
- **`cadence-host-claude-code install`** 适配器通过生命周期钩子和14个斜杠命令将Claude Code连接起来。Claude Code是 *环境* 编辑时门控（边界检查，异常检测）的 **参考适配器**。
- **`cadence init --host codex` / `cadence-host-codex install`** 路径通过生命周期钩子和全局提示命令将OpenAI Codex CLI连接起来。在第一次打开Codex之前运行引导程序，以便Codex在第一次有用会话时看到命令。它是宿主适配器合同的已发货一致性使用者，也支持通过其自己的钩子进行环境编辑时边界检查。
- **`cadence mcp serve`** 将引擎暴露为本地 [MCP](https://modelcontextprotocol.io) 服务器，通过stdio，使任何支持MCP的宿主（Claude Desktop，Cursor，其他代理）能够驱动循环，而无需定制的适配器。它仅覆盖命令边界门控（运行；环境编辑时门控需要宿主钩子）。参见 **[MCP服务器](./docs/mcp.md)**。
## 比较
韵律是一个验证层，而不是代理和CI服务。它的检查点是不同的：您为工作单元声明的特定的验收标准，从真实任务状态重新派生 — 而不仅仅是“构建是否保持绿色”。
| | 检查内容 | 韵律的不同之处 |
|---|---|---|
| **CI / 测试运行器** | 套件在分支上通过，在您推送后。 | CI不知道 *此任务* 承诺了什么。韵律在循环关闭之前重新检查每个声明的验收标准，并将套件运行为多个门控之一。 |
| **Linter / 预提交钩子** | 样式和静态规则在差异上。 | 它们从不询问“工作是否实际完成？”韵律将 *完成声明* 与标准对照，而不是格式化。 |
| **代理托管 / 框架** | 协调代理 *执行* 工作。 | 韵律对抗代理的自我报告。它是宿主无关的 — CLI位于任何代理（或没有）后面，拒绝接受未经验证的“完成”。 |
| **重量级规划框架（例如GSD）** | 对每个更改运行完整、固定的纪律。 | 韵律保持严格性，但使门控集可按更改配置（配置文件 × 层级） — 您只需为更改实际需要的门控付费。GSD的纪律而无需GSD的时钟成本。 |
核心原始 **拒绝在重新验证的声明标准上结算。**
代理不被相信；状态被相信。
> **关于默认验证器的提示。** 默认情况下，每个门控都使用 `mock`，一个确定性的离线 **占位符**，它只检查每个验收标准链接到测试 — 它不是真正的验证。运行 [`cadence activate`](./docs/providers.md) 以启用真正的AI验证器（Anthropic或本地模型）；`cadence doctor` 告诉您真正的验证是否已连接。
## 快速入门
无需安装，无需仓库写入 — 观看一个真实的循环运行，包括结算拒绝关闭一个阶段的时刻，而测试不支持，然后在支持后关闭：
```sh
npx -y @manehorizons/cadence-core tutorial
```
对于日常使用，请全局安装CLI（需要Node ≥ 20）：
```sh
npm install -g @manehorizons/cadence-core
```
韵律新手？运行 `cadence start` — 一个引导菜单，为您正在执行的操作选择正确的设置命令。（一旦您设置完成，`cadence quickstart` 就是您当前位置和下一步骤的只读映射。）
在您自己的仓库中查看循环运行的最快方法 — `--demo` 会播种一个准备好批准的阶段，因此无需手动编辑：
```sh
mkdir my-app && cd my-app
cadence init --demo # 零提示：名称和门控配置文件已派生
cadence draft approve 01-demo 01
cadence done T1
cadence settle run --ac AC-1=pass
```
`cadence init` 不会询问任何问题 — 它会派生项目名称（来自 `package.json` 或目录）和门控配置文件（来自git历史）。已经有 `ANTHROPIC_API_KEY`？添加 `--activate` 以在同一步骤中启用真正的验证（密钥永远不会存储）。在Claude Code工作区（`.claude/` 存在）中，添加 `--wire-host` 以在同一步骤中安装适配器。对于Codex，运行 `cadence init --host codex`，然后打开Codex，以便钩子、命令和 `AGENTS.md` 准备好进行第一个会话。
要驱动一个真实的阶段，而不是演示：
```sh
cadence init
cadence draft new --title "修复登录超时" --template bugfix
# 编辑生成的草稿：模板是脚手架，不是证明
cadence draft approve 01-fix-login-timeout 01
# ^ 非TTY（CI/代理）？添加 --no-approve — 参见下面的gate-profiles注释
cadence build task T1 --status=DONE
cadence settle run --auto
# ^ 韵律拒绝：AC-1没有测试。 这就是重点 — 它不会结算
# 未验证的工作。 作为操作员，您可以自己判定标准：
cadence settle run --ac AC-1=pass
```
从 **Claude Code** 驱动韵律？将适配器连接到项目：
```sh
npx @manehorizons/cadence-host-claude-code install
```
从另一个MCP宿主（Claude Desktop，Cursor，代理）驱动它？将宿主指向MCP服务器 — 无需适配器：
```jsonc
// .mcp.json
{ "mcpServers": { "cadence": { "command": "cadence", "args": ["mcp", "serve"] } } }
```
> **关于门控配置文件和 `approve` 的提示：** `cadence init` 根据仓库成熟度建议门控配置文件 — 具有 **≥20次提交** 的仓库获得 `standard`，较年轻的仓库获得 `auto`（使用 `--gate-profile` 覆盖）。配置文件设置了 `draft approve` 的严格程度：
> - **`auto`** — `approve` 非交互式运行（适用于单独和代理循环）。
> - **`standard` / `strict`** — `approve` 在 **交互式提示** 后被阻塞。在非TTY上下文（CI，代理）中，它 **拒绝** 除非您传递 `--no-approve`。
> **`--local` 编写机器绝对路径 — 请勿提交。** `cadence-host-claude-code install --local` 将此机器工作区的绝对路径写入设置文件中。将设置文件（例如 `.claude/settings.local.json`）添加到 `.gitignore`；其他克隆/机器无法解析这些路径。
## 完整用户指南
参见 **[docs/README.md](./docs/README.md)** 了解完整用户指南：
- [快速入门](./docs/quickstart.md) — 无安装演示，第一个真实模板和完整循环演练
- [概念](./docs/concepts.md) — 循环，门控，配置文件和双提交约定
- [CLI指南](./docs/cli.md) — 所有子命令和标志
- [Claude Code集成](./docs/claude-code.md) — 钩子和斜杠命令
- [MCP服务器](./docs/mcp.md) — 从任何MCP宿主驱动循环（`cadence mcp serve`）
- [提供者](./docs/providers.md) — OpenAI，Claude，Ollama和自定义LLM
- [命令参考](./docs/reference/commands.md) — 详尽的CLI参考
- [配置参考](./docs/reference/config.md) — 完整的 `.cadence/` 配置模式
- [发布流程](./docs/release.md) — 维护者检查清单，用于npm，标签和GitHub Release完整性
## 持续集成
`.github/workflows/ci.yml` 在每个PR和推送到 `main` 时运行 `lint → typecheck → test → build`，跨Node 20 + 22在Ubuntu上。
**强制门控。** 跟踪钩子 `.githooks/pre-push` （通过 `git config core.hooksPath .githooks` 连接）运行完整的 `pnpm turbo run lint typecheck test build` 在任何更新 `main` 的推送之前，并在失败时中止。故意绕过 `git push --no-verify`。
## 关于名称
**韵律** 以其核心循环的节奏命名 — 稳定的草稿→构建→结算节奏贯穿工作的每个阶段。早期草稿带有副词；它已被弃用为强迫适应。词语 — 节奏 — 是保持者。
## 许可证
MIT
