内容
# Loopbreaker
**一个本地规划和评审图表，允许代理在代码准备好发布之前停止评审。**
Loopbreaker是从[Rordi](https://github.com/rordi-ai)中提取的小型公共演示，它存储了问题的形状决策、规划健康状况、独立规划批准、验收行为、可归因证据、发现、有界评审通过和人工豁免在本地SQLite中；通过MCP向代理暴露相同的底层；并将有序的门户渲染为实时工作流图表。
它背后的经验教训是：**评审收敛性和发布准备是不同的事实**。评审者可以在仍缺乏与生产相关的证明的情况下完成检查修复程序。将这些事实混淆会导致评审循环无限增长。第二个经验教训是：验证门户无法挽救一个范围、工作所有权、证明计划、生产连接或回滚从未明确的问题。Loopbreaker使得明确的权限明确：形状、结构规划健康状况、语义规划批准、实现评审和发布准备。
它现在将完整的工作流打包为五个可重用的代理技能：
- `shape-strategy` — 框架需求、逆转性、最小切片和成功。
- `plan-feature` — 冻结强制行为并实现健康的规划。
- `review-planning` — 独立批准或重定向形状和规划，最多三次通过。
- `implement-feature` — 仅构建规划准备好的合同并记录证据。
- `review-invariants` — 强制规划预检、两次加一评审和发布权限。
## 尝试事件
需要 Node.js 22.5+ 和 pnpm。
```sh
git clone https://github.com/rordi-ai/loopbreaker.git
cd loopbreaker
pnpm install
pnpm build
node dist/cli.js demo
node dist/cli.js
node dist/cli.js substrate DEMO-1
node dist/cli.js serve
```
打开 <http://127.0.0.1:7331>。种子事件从这里开始：
- 一次综合通过压缩了十三次遗留评审迭代。
- 规划健康状况为100/100，无硬性障碍。
- 三个强制行为中有两个得到验证。
- 第三个行为存在单元测试，但连接的回放证明不存在。
- 评审的下一步是修复验证；发布被阻止。
使用 **记录修复通过**。评审完成，但发布仍然被阻止。然后使用 **添加连接证明**。行为得到验证，处置更改为发布。两个决策永远不会相互覆盖。
图表是可检查的，但故意只读：平移、缩放、聚焦和选择节点以跟踪合同、证明、发现、评审预算和发布决策。WebSocket 将另一个 CLI 或 MCP 进程所做的更改带入打开的图表。如果连接断开，状态徽章更改为 **轮询恢复**，客户端通过间隔轮询继续收敛。在您希望显式使用此恢复路径时，请使用 `?transport=poll`。
CLI 标准输出使用 [TOON](https://toonformat.dev/)，因此代理收到紧凑、定期的数据。数据库默认为 `.loopbreaker/loopbreaker.db`；使用 `--db PATH` 或 `LOOPBREAKER_DB` 覆盖它。
## 作为 Codex 插件安装
存储库是一个完整的插件：[.codex-plugin/plugin.json](.codex-plugin/plugin.json) 注册了五个技能，[.mcp.json](.mcp.json) 启动了捆绑的本地 MCP 服务器。存储库构建后，不需要 TypeScript 运行时。
```sh
pnpm install
pnpm build
```
生成的 `mcp/server.bundle.mjs` 是插件的入口点。在 MCP 环境中设置 `LOOPBREAKER_DB` 以指定显式数据库路径；否则，服务器在工作目录下使用 `.loopbreaker/loopbreaker.db`。
## 作为 Claude Code 插件安装
同一个存储库也是一个 Claude Code 插件：[.claude-plugin/plugin.json](.claude-plugin/plugin.json) 启动了捆绑的 MCP 服务器（数据库位于当前项目下的 `.loopbreaker/loopbreaker.db`），并且 [skills/](skills/) 下的五个技能被自动发现为 `/loopbreaker:<skill-name>`。
```sh
pnpm install && pnpm build
claude --plugin-dir /path/to/loopbreaker
```
或者，从 GitHub 永久安装：
```text
/plugin marketplace add rordi-ai/loopbreaker
/plugin install loopbreaker@loopbreaker
```
在此存储库中工作不需要任何安装：项目范围内的 [.mcp.json](.mcp.json) 直接加载相同的捆绑服务器。
## 与任何 MCP 客户端一起使用
构建存储库，然后将此本地_stdio_服务器添加到您的 MCP 客户端配置中：
```json
{
"mcpServers": {
"loopbreaker": {
"command": "node",
"args": [
"/absolute/path/to/loopbreaker/dist/cli.js",
"mcp",
"--db",
"/absolute/path/to/review.db"
]
}
}
}
```
服务器告诉代理在实施或评审之前读取有序交付权限，加载底层，并单独检查发布状态。它公开了十五种聚焦工具：
| 工具 | 目的 |
| --- | --- |
| `review_import_contract` | 导入行为子项；强制除显式建议外的其他项 |
| `shape_record` | 持久化显式继续、尖峰、停车或拒绝形状决策 |
| `planning_record` | 记录部分或完整的预评审规划配置文件 |
| `planning_health` | 读取分数、五个维度、障碍和准备情况 |
| `delivery_readiness` | 读取形状 → 规划 → 规划评审 → 实现 → 发布权限 |
| `planning_review_upsert_finding` | 保存稳定的语义形状/规划发现 |
| `planning_review_record_pass` | 记录下一个独立的规划评审通过，限制为 1-3 |
| `review_list_issues` | 列出派生的评审和发布状态 |
| `review_substrate` | 读取完整的冻结评审表面 |
| `review_upsert_finding` | 保存每个评审根本原因的一行稳定数据 |
| `review_record_pass` | 记录下一个通过，限制为 1-3 |
| `review_record_evidence` | 附加单元、连接或实时证明 |
| `review_verify_behavior` | 使用附加的通过证据验证行为 |
| `review_create_waiver` | 接受命名债务和批准者及理由 |
| `review_ship_status` | 读取权威发布处置 |
MCP 结果是 TOON 文本块。使用以下命令运行真正的客户端/服务器握手：
```sh
pnpm verify:mcp
```
## 导入您自己的问题
从 [examples/issue-contract.json](examples/issue-contract.json) 开始：
```sh
node dist/cli.js import examples/issue-contract.json --db my-review.db
node dist/cli.js shape APP-42 examples/shape.json --db my-review.db
node dist/cli.js health APP-42 --db my-review.db
node dist/cli.js readiness APP-42 --db my-review.db
node dist/cli.js substrate APP-42 --db my-review.db
```
默认情况下，每个行为都是强制的。仅当行为确实不是发布门的一部分时，才设置 `"advisory": true`。一旦记录了第一个评审通过，改变合同将被拒绝：父上下文可以解释行为子项，但不能在评审中途添加要求。
规划健康状况是确定性的，并且故意是联合的。分数涵盖范围、合同质量、工作单元可追溯性、证明设计和可操作性。准备情况需要至少 80 分和零个硬性障碍。缺少行为所有权、连接/实时证明、生产连接或回滚不能被平均消除。接受部分配置文件，以便工具可以返回可行的障碍；`loopbreaker health ISSUE` 是结构表面，`loopbreaker readiness ISSUE` 是有序的准入表面。100/100 的计划仍然不能在独立的有界规划评审记录 `approved` 之前允许实施。
## 决策模型
规划评审和实现评审都绑定到两个加一预算：
1. **综合** — 找到与冻结合同一致的问题集。
2. **修复验证** — 检查允许的修复和修复回归。
3. **仅决策** — 发布、发布债务、拆分/范围调整或因一个命名的重要风险而搁置。
没有自动的第四次通过。通过可以提前完成评审。两种情况都不允许发布。
发布是通过有序权限得出的：
- 形状 `hold`：显式形状缺失、不完整或不是 `proceed`；
- 规划 `hold`：结构规划健康状况不准备就绪；
- 规划评审 `hold`：语义评审未独立批准实施；
- 验证 `hold`：早期门户准备就绪，但强制行为未解决；
- `ship`：所有早期门户准备就绪，所有强制行为得到验证；
- `ship_with_debt`：所有早期门户准备就绪，所有未验证的强制行为都有显式豁免。
这将评审者的裁决作为证据支持验收合同，而不是创建隐藏的并行门户。
## 架构
```text
CLI (TOON) ─┐
├── 有序权限 + 域规则 ── SQLite/WAL
MCP (stdio) ┤ │
└── HTTP API ── 数据版本监视器 ── WebSocket
│ │
└──────── React Flow 工作流画布
```
该项目故意为每个接口使用一个域层。浏览器不能调用比 MCP 服务器更宽容的突变，代理不能通过更低级别的端点制造第四次通过。UI 是使用 React Flow 和从 [Vercel AI Elements 工作流组合](https://elements.ai-sdk.dev/examples/workflow) 适配的小型本地组件构建的 Vite 捆绑应用。Node 的 HTTP 模块提供生产捆绑包并将 `/events` 升级为 WebSocket；SQLite `PRAGMA data_version` 在不引入云依赖的情况下检测其他本地进程的提交。
## 命令
```text
loopbreaker 实时问题仪表板
loopbreaker init 初始化 SQLite
loopbreaker demo 播种综合事件
loopbreaker import FILE 导入行为合同
loopbreaker shape ISSUE FILE 记录显式形状决策
loopbreaker plan ISSUE FILE 记录规划配置文件
loopbreaker health ISSUE 检查紧凑的规划健康状况
loopbreaker readiness ISSUE 检查有序交付权限
loopbreaker plan-pass ISSUE ... 记录规划评审通过 1、2 或 3
loopbreaker plan-finding ISSUE ... 保存一个稳定的规划发现
loopbreaker substrate ISSUE 检查完整的底层
loopbreaker pass ISSUE ... 记录通过 1、2 或 3
loopbreaker evidence ISSUE ... 附加比例证明
loopbreaker verify BEHAVIOR ... 使用附加证据验证
loopbreaker waive ISSUE ... 接受命名债务
loopbreaker serve 运行视觉视图
loopbreaker mcp 运行_stdio_ MCP 服务器
```
运行 `loopbreaker help COMMAND` 以获取确切的标志。命令是非交互的，在实践中是幂等的，并返回结构化错误。
## 验证
```sh
pnpm verify
```
这运行严格的 TypeScript 检查、域测试、生产前端和服务器构建、插件验证、MCP 工具发现以及实际的 `review_ship_status` 调用，以及实时表面检查。实时检查启动一个临时服务器，通过单独的构建 CLI 进程修改其数据库，并需要在两秒内匹配 WebSocket 事件和更新的 API 状态。
## 范围
Loopbreaker 是一个有意的参考实现，而不是完整 Rordi 实体图或生产同步层。SQLite 镜像重要的评审语义，以便构建者可以检查、重用和挑战模式，而无需建立 Rordi 的 Postgres 服务。
MIT 许可。
