内容
<p align="center">
<img src="https://raw.githubusercontent.com/qualixar/bounded-loops/main/assets/bounded-loops-logo.svg" alt="bounded-loops logo" width="170"/>
</p>
<h1 align="center">有界循环</h1>
<p align="center"><strong>您可以实际运行的循环工程 — 每个安全边界都在引擎代码中强制执行，而不是在检查清单中描述。</strong></p>
<p align="center"><em>跨越十二个行业的 63 个可运行的 AI 代理循环 — 无需密钥，离线，并通过门户验证。<br/>Karpathy、Steinberger、Cherny、Osmani 和 Berman 定义的循环工程的可运行引擎层。</em></p>
<p align="center">
<a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-3b82f6?style=for-the-badge" alt="许可证：Apache-2.0"/></a>
<img src="https://img.shields.io/badge/tests-619_passing-22c55e?style=for-the-badge" alt="619 测试通过"/>
<img src="https://img.shields.io/badge/runnable_loops-63-e2725b?style=for-the-badge" alt="63 个可运行循环"/>
<img src="https://img.shields.io/badge/setup-keyless_%C2%B7_offline-0a0a0a?style=for-the-badge" alt="无需密钥且离线"/>
<img src="https://img.shields.io/badge/safety-9_bounds_%2B_kill_switch-ff6b35?style=for-the-badge" alt="九个边界加上终止开关"/>
</p>
---
克隆此仓库，并在大约 30 秒内 — 无需 API 密钥，完全离线 — 观看 AI 代理循环**失败**而不受其门户的约束（它自信地声称完成，但漏洞仍然存在），然后观看同一个循环**干净地停止**，门户强制执行。每个循环都是一个真正的可运行文件夹：一个**运行者**（代理）提出更改，一个**独立门户**（pytest、JSON-Schema 检查、命令、真正的安全扫描器）验证它，并且一个小型引擎在**九个强制边界**和**终止开关**下重复，直到门户通过或边界触发。
> “循环工程”是一种由社区在 2026 年命名的实践 — **“停止提示您的代理；设计提示它的循环。”** 该仓库不声称该术语；它提供了其他人描述但不运行的部分：**可运行的、强制执行的实现** — **跨越十二个行业的 63 个可运行循环文件夹**，以及一个更广泛的[循环配方目录](catalog/README.md)。下方有完整的致谢。
## 灵感来自循环工程社区 — 我们在此基础上建设，而不是对抗
有界循环并没有发明循环工程。它是循环工程实践的可运行引擎层，该实践首先由杰出的人们定义，并且它旨在**补充他们的工作，而不是与之竞争**。
- **Andrej Karpathy** ([@karpathy](https://x.com/karpathy)) 提出了“循环时代” — 新的技能是设计保持有用工作流动的循环 — 并命名了这个项目围绕的精确约束：*您只能在循环结果易于评估时安全地自动化它。* 有界循环将其转化为代码：**门户**是可评估的指标，并且在它通过之前没有任何内容是“完成”的。
- **Peter Steinberger** 点燃了火花：*“停止提示您的代理；设计提示它们的循环。”*
- **Boris Cherny** （Claude Code, Anthropic）：*“我的工作是编写循环。”*
- **Addy Osmani** 在他的 [*循环工程*](https://addyosmani.com/blog/loop-engineering/) 论文中命名了该实践并给出了其解剖结构。
- **Matthew Berman 的循环库** ([Loop Library](https://github.com/Forward-Future/loopy)) —精选的循环即提示目录，我们将其扩展为可运行的、门控的文件夹。
- **proof-loop**、**repo-task-proof-loop** 和 **agentops** 开创了可运行的新验证循环；有界循环添加了完整的安全边界和按行业划分的库。
有界循环为所有这些添加的内容：每个循环都是一个**真正的运行到 `✓ [完成]` 的文件夹，具有九个强制边界** — 跨越金融、法律、医疗保健、零售、运营、企业/ERP、安全、测试、内容、研究和商业，不仅仅是软件。如果我们误解或遗漏了您的循环项目，[请开启一个问题](../../issues) — 这个空间通过相互构建而增长。
## 三种使用方式
1. **作为 CLI** — 克隆，`pip install -e .`，然后 `bl list` / `bl run loops/<name> --yes`。原始引擎；请参见下面的[快速入门](#快速入门-无需密钥-30秒)。
2. **作为 MCP 服务器** — `bounded-loops-mcp` 命令将 `bl_run` / `bl_lint` / `bl_list` 公开给任何 MCP 客户端（Claude Code、Cursor、Codex、Antigravity ...）。
3. **作为代理插件** — [`plugins/`](plugins/) 提供了一个可以直接安装到 **Claude Code**、**Codex** 和 **Antigravity** 的软件包，每个软件包都有一个技能、一个 `/bl-run` 命令、MCP 接线和一个验证停止的钩子。在您的代理内部，您可以获得**门户验证的“完成”**，而不是代理声称完成。参见 [MCP 服务器和 IDE 插件](#mcp-服务器和ide插件)。
## 仓库布局
```
bounded-loops/
├── bounded_loops/ 引擎（Python 包）
│ ├── domain/ 纯规则 + 数据类型，无 I/O — 端口（缝隙）位于此处
│ ├── application/ 循环算法（run_loop.py）+ 边界强制执行 + 清单加载器
│ ├── adapters/ 具体的运行者（stub、shell、claude-code、codex、...）和
│ │ 门户（命令、pytest、jsonschema、osv、checkov）
│ ├── composition.py 唯一一个将适配器连接到引擎的文件（组成根）
│ ├── cli.py `bl` 命令
│ ├── mcp_server.py `bounded-loops-mcp` 服务器（bl_run / bl_lint / bl_list）
│ └── hooks/ 验证停止的钩子
├── loops/ 67 个可运行的循环文件夹 — 库（每个 = 种子 + 门户 + 录音带）
├── catalog/ 配方目录 — 浏览的循环创意菜单，跨行业
├── docs/ 引擎的工作原理 — 架构，九个边界，编写循环（SVG 图表）
├── plugins/ 安装到 Claude Code / Codex / Antigravity 的软件包（技能、命令、钩子）
├── tests/ 619 个测试
└── README.md · CONTRIBUTING.md · LICENSE · pyproject.toml
```
`docs/` 解释了**机器的工作原理**；`catalog/` 列出了**您可以运行的循环** — 不同的作业，而不是重复项。其他顶级条目（`.venv/`、`__pycache__/`、`.*_cache/` 目录）是本地构建产物，已被 `.gitignore` 排除在仓库之外。
## 安装
引擎是 **Python 3.11+** 包。以适合您堆栈的方式安装：
**pip — 原生，推荐**
```bash
pip install bounded-loops # 从 PyPI
bl list
```
```bash
# … 或从源码开始：
git clone https://github.com/qualixar/bounded-loops
cd bounded-loops && pip install -e .
```
**npx — Node 便捷包装器** （仍需要 PATH 上的 Python 3.11+）
```bash
npx bounded-loops list
npx bounded-loops run loops/bug-fix-red-green --yes
```
npm 包是一个**薄启动器**：在第一次运行它会找到 Python 3.11+，安装引擎，然后移交给真正的 CLI。它不重新实现 Node 中的工具 — Python 是引擎，npm 只是一个便捷的入口。
## 快速入门（无需密钥，~30 秒）
```bash
pip install -e .
bl run loops/bug-fix-red-green --yes # 无需密钥的 stub 运行者 + 真实的 pytest 门户
```
```
✓ [完成] 门户通过（圈数：1） 账本：loops/bug-fix-red-green/.ledger.jsonl
```
查看使其成立的对比 — 相同的循环，无门控，相信谎言：
```bash
cd loops/bug-fix-red-green && ./wreck.sh # 退出 1: “谎言确认”
```
并浏览每个循环及其角色、运行级别和门户：
```bash
bl list
```
## 九个边界（+ 终止开关）
每个循环的 `bounds.yaml` 映射到九个边界，在引擎层强制执行 — 不是一个文件中九个平面布尔值：
| # | 边界 | 强制执行者 |
|---|---|---|
| 1 | 迭代控制 — 硬性圈数上限 + 无进展检测 | `bounds.max_iterations` / `bounds.no_progress_window`，在 `run_loop.py` 中 |
| 2 | 沙盒 — 代理在 `seed/` 的隔离**副本**中操作，永远不会是源目录；拒绝符号链接 | `bounds.sandbox` + `composition._make_scratch_workspace` |
| 3 | 输入隔离 — 带有秘密的文件（`.env*`、`.ssh`、`.aws`、`*.pem`/`*.key`、`id_rsa`、`credentials`、`.git`）**从沙盒副本中排除**，因此共享循环无法走私或渗出凭证 | `bounds.quarantine_inputs`（在 `_make_scratch_workspace` 中激活） |
| 4 | 输出模式验证 | `bounds.schema`，由 `JsonSchemaGate` 消费，当循环选择加入时 |
| 5 | 跟踪 — 每个圈数一个 OTel 跨度，或者当未安装 `otel` 额外时是一个 no-op 追踪器 | `bounds.trace` + `TracerPort` |
| 6 | 回归评估 — 由循环的**门户选择**（pytest / 命令 / jsonschema / osv / checkov）满足，不是一个 `Bounds` 字段 | 门户适配器选择循环 |
| 7 | 令牌预算 — 从 `claude-code` 的 `usage` 解析的真实令牌计数，由 `BudgetMeter` 累积和强制执行。（`shell`/`codex`/`antigravity` 报告 0 个令牌 — 一个诚实的工具限制，而不是沉默的差距；`stub`/`python_callable` 从录音带/胶水提供计数。） | `bounds.max_tokens` + `BudgetMeter` |
| 8 | 人工审批门控 | `bounds.require_approval`（根据 `rung` 未设置时：L1 → 无，L2/L3 → 需要） |
| 9 | 墙时钟超时 — `max_wallclock_s: null` 表示“使用保守的 1 小时默认值”，**不是**“无限制”。它是**圈间**上限（在每个圈数检查前）；**圈内**防止单个长时间回合的保护是运行者和门户自己的子进程 `timeout_s` | `bounds.max_wallclock_s` + `BudgetMeter`; 运行者/门户 `timeout_s` |
在所有九个边界之上，一个环境变量终止开关（`BOUNDED_LOOPS_KILL`）每圈数轮询一次，在任何其他操作之前 — 优先级最高的停止。并且一个冻结的不变式贯穿所有这些：**引擎永远不会信任代理自己的“完成”声明**。运行者的 `agent_claimed_done` 标志被记录，但从未取代真正的门户通过。
## 运行者和门户
运行者（每个循环提出更改）：
| 运行者 | 它做什么 | 需要 |
|---|---|---|
| `stub` | 重放代理的录制录音 — 完全确定，无外部调用。包括 `osv`/`checkov` 循环的快速路径：录音带 *模拟* 代理的修复，以便循环离线运行。安装工具并使用 `--runner` 或非 stub 录音带 | 无（无需密钥） |
| `shell` | 将循环的提示通过 stdin 发送到任何 CLI 命令 | 您指向的 CLI |
| `python_callable` | 在具有清理的环境的隔离子进程中调用 `run_turn(prompt, workspace) -> dict` | 实现该契约的 Python 模块 |
| `claude-code` | `claude -p --output-format json --bare`; 解析真实的 `total_cost_usd` + `usage` 令牌 | `claude` CLI **和 `ANTHROPIC_API_KEY`/`apiKeyHelper`** — `--bare` 从不读取 OAuth/密钥链（确认对抗真实二进制） |
| `codex` | `codex exec --json`，根据运行级别派生的沙盒模式 | `codex` CLI（JSON 模式尚未针对真实二进制进行烟雾测试 — 参见已知限制） |
| `antigravity` | `agy -p`，根据运行级别的审批策略 | `agy` CLI |
门户（决定一个循环是否完成）：
| 门户 | 检查 | 需要 |
|---|---|---|
| `command` | 任意命令（标记化，无 shell — 无 `\|`/`&&` 链接）；退出 0 = 通过。仅通过 **退出代码**验证 — 对于真正的输出验证，请使用下面的类型化门户。门户需要 shell 功能的循环文件夹会提供一个包装器脚本 | 您配置的命令 |
| `pytest` | `pytest -q` 在工作空间中 | `pytest` |
| `jsonschema` | 工作空间/ `output.json` 对 JSON 模式（路径来自 `bounds.schema`） | 除了核心依赖项（无需密钥） |
| `osv` | `osv-scanner` 报告零已知漏洞（失败 **关闭** 空/垃圾报告） | [`osv-scanner`](https://github.com/google/osv-scanner) 二进制 **+ 网络**（获取 OSV.dev 咨询数据库） |
| `checkov` | `checkov` 报告零个失败的 IaC 检查（失败 **关闭** 在不可解释的输出） | [`checkov`](https://www.checkov.io/) |
额外的门户适配器可以通过组合根进行可插拔安装；默认安装仅提供通用、无需密钥的第一组 — 任何已发货循环的默认清单不要求付费产品。
## 可运行循环（67 文件夹，跨 12 个行业）
每个都是一个真正的运行到 `✓ [完成]` 的文件夹 — 破坏的种子、机械门控、九个边界、 `L1`/`L2`/`L3` 等级和 `forbid:` 保护措施，所以代理无法重写门控以作弊。 **67 个循环中有 63 个达到 `✓ [完成] 门控通过**（无需设置）| 63 个循环）| 7 | `secret-scan-keyless`, `dependency-pinning`, `dockerfile-no-root`, `cors-not-wildcard`, `jwt-alg-not-none`, `osv-scanner-example` |
|`* |
| 16 | `citation-existence-check`, `contract-clause-extraction`, `nda-required-clauses`, `gdpr-dpa-terms`, `contract-defined-terms` |
| 6 | `content-fact-gate`, `frontmatter-schema`, `broken-internal-links`, `alt-text-present`, `reading-level-gate`, `seo-meta-limits` |
| 5 | `product-feed-schema`, `price-margin-floor`, `inventory-nonnegative`, `gtin-checkdigit`, `catalog-required-fields` |
| 5 | `runbook-completeness`, `oncall-coverage`, `slo-error-budget`, `conventional-commits`, `alert-runbook-link` |
| 5 | `idoc-xml-schema`, `transport-request-manifest`, `cds-view-annotations`, `bapi-payload-contract`, `material-master-completeness` |
| 5 | `okr-measurable`, `prd-acceptance-criteria`, `rfc-decision-recorded`, `roadmap-field-contract`, `meeting-action-items` |
| 4 | `test-naming-contract`, `assertion-density`, `no-hardcoded-sleep`, `test-presence-per-module` |
| 4 | `claim-source-mapping`, `dataset-license-allowed`, `reproducibility-manifest`, `bibliography-completeness` |
| 2 | `clinical-note-completeness`, `a11y` |
旗舰项目是“AI 可靠性”，是法律中单一最有文档记录的 AI 失败案例 — 捏造的案例引用（截至 2026 年中旬已编目 1600+ 个制裁案例） — 门户失败，直到每个引用的案例解析为真实案例。
每个循环的 README 都显示了“证明门户真正失败在未修复的种子上，然后在修复后真正通过”的演练，并附有 **实际捕获的输出** — 运行，而不是断言。 更广泛的 [配方目录](catalog/README.md) 列出了跨这些相同行业的更多循环配方（每个配方都命名一个真正的门户），以便下一步安装。
关于可访问性的具体信息：`axe-core`/Lighthouse 需要一个正在运行的浏览器，而没有无密钥的通用 a11y 工具 — 因此 `a11y` 循环提供了一个小型的依赖性免费静态检查工具（缺少 `alt`，缺少 `lang`，未标记输入）。它是诚实的，只能捕捉静态 WCAG 子集，而不是渲染的 DOM 问题。
## 搭建自己的循环
```bash
bl new --list # pytest-basic, jest-basic, go-test-basic,
# cargo-test-basic, rspec-basic, junit-basic
bl new pytest-basic my-loop # <template> <destination> (positional)
```
## MCP 服务器和 IDE 插件
`bounded-loops-mcp` 将 `bl_run`/`bl_lint`/`bl_list` 公开为 MCP 工具 — 一个薄薄的壳层，覆盖 CLI 使用的同一个引擎。 `bl_run` 的 `confirm` 是一个真正的服务器端强制门控：它绑定完整的运行身份（门控 **+ 运行者 + 圈数上限**），所以调用者无法预览一个安全的 `shell` 运行者，然后确认一个凭证的运行者；需要交互式批准的循环在被电线连接之前被拒绝。 `plugins/{claude-code,codex,antigravity}/` 每个都提供 MCP 配置 + 一个 `AGENTS.md` 片段 + 一个验证停止的钩子。
## 已知限制（明确说明，而不是隐藏）
- `codex` 运行者的真实二进制 JSON 模式尚未经过烟雾测试（构建时没有 `codex` 安装）；其令牌计数报告为 0，直到验证。
- `langgraph-example` 的胶水硬编码 `changed: True` — 其无进展边界无法为该示例触发；真正的集成应在使用前后差异。
- 两个门户 **不是** 离线的，需要在检查时联网：
`content-fact-gate`（链接活跃度）和 `osv` 门户（`osv-scanner` 获取 OSV.dev 咨询数据库）。 "~30 秒，无 API 密钥，完全离线" 快速启动仅指特定的 `bug-fix-red-green` 循环（stub 运行者 + pytest 门户），它不需要网络或密钥。 无密钥优先集 — stub/shell 运行者带有 pytest/jsonschema/command 门户 — 是离线的；安全扫描器门户（`osv`，`checkov`）会带来自己的二进制和 `osv` 的网络获取。
- `python_callable` 始终生成子进程并清理子环境到一个小的允许列表 — 按设计，但您的可调用项的导入副作用在干净的环境中运行。
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md) — `bl new` 一个模板，替换种子，证明您的门户真正失败然后真正通过，并开启一个 PR。 目录配方或循环的门槛：一个 **真实的** 门户和一个 **可测试的** 完成条件，永远不是“LLM 决定”。
## 引用
bounded-loops 是 Qualixar AI 可靠性工程计划的研究级软件。 如果它对您的工作有帮助，请引用它 — GitHub 的“引用此仓库”按钮读取 [`CITATION.cff`](CITATION.cff)：
```bibtex
@software{bhardwaj_bounded_loops_2026,
author = {Bhardwaj, Varun Pratap},
title = {bounded-loops: 可运行的、边界限定的 AI 代理循环},
year = {2026},
publisher = {Qualixar},
version = {0.1.0},
url = {https://github.com/qualixar/bounded-loops}
}
```
## 安全
发现了一种方法来欺骗网关或逃脱绑定？这是我们能得到的价值最高的错误 — 请根据 [安全.md](SECURITY.md) 私密地报告。
## 许可证
[Apache-2.0](LICENSE). 版权所有 © 2026 Varun Pratap Bhardwaj / Qualixar.
---
## Qualixar AI 可靠性工程计划的一部分
bounded-loops 是 [Qualixar](https://qualixar.com) 开源平台中的一款产品，旨在使 AI 代理可靠：
| 产品 | 目的 | 安装 |
|---|---|---|
| **[SuperLocalMemory](https://github.com/qualixar/superlocalmemory)** | 优先本地的代理内存 + 学习 | `npm install superlocalmemory` |
| **[Qualixar OS](https://github.com/qualixar/qualixar-os)** | 通用代理运行时 | `npx qualixar-os` |
| **[SLM Mesh](https://github.com/qualixar/slm-mesh)** | 跨会话的 P2P 协调 | `npm i slm-mesh` |
| **[SLM MCP Hub](https://github.com/qualixar/slm-mcp-hub)** | 联邦 430+ MCP 工具 | `pip install slm-mcp-hub` |
| **[AgentAssay](https://github.com/qualixar/agentassay)** | 代币高效的代理测试 | `pip install agentassay` |
| **[AgentAssert](https://github.com/qualixar/agentassert-abc)** | 行为合约 + 漂移检测 | `pip install agentassert` |
| **[SkillFortify](https://github.com/qualixar/skillfortify)** | 代理技能的形式化验证 | `pip install skillfortify` |
| **[Agent Amplifier](https://github.com/qualixar/agent-amplifier)** | 运行时放大钩子 | `pip install agent-amplifier` |
| **bounded-loops** *(此仓库)* | 可运行、网关验证的代理循环 | `pip install bounded-loops` |
**优先本地。诚实地描述运行情况。构建来补充生态系统，而不是隔离它。**
从这里开始 → **[qualixar.com](https://qualixar.com)** · 作者： **[Varun Pratap Bhardwaj](https://qualixar.com)** — Qualixar 创始人。
---
<p align="center">
如果 bounded-loops 帮助您摆脱了一个声称已完成的代理的困扰，<br/>
<a href="https://github.com/qualixar/bounded-loops">⭐ 在 GitHub 上<strong>点赞</strong></a> — 它帮助其他开发者找到它。
</p>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器