内容
<!-- Clean-room project. No prior-employer or third-party source, data, or naming. See PROVENANCE.md. -->
<div align="center">
<img src="assets/logo.png" width="96" alt="Loopward" />
# Loopward
**将智能代理的工具链进行测试。** 查找路由和停止逻辑在您自己的工具中出现问题的地点，修改工具链，并通过确定性预言机证明修改后的工具链提高了性能。
[](./LICENSE)
[](https://nodejs.org)
[](https://www.npmjs.com/package/loopward)
[](https://github.com/plwslpld-arch/loopward/actions/workflows/ci.yml)
[](./package.json)
[](https://plwslpld-arch.github.io/loopward/)
简体中文 | [English](./README.md) · [**实时结果仪表盘 →**](https://plwslpld-arch.github.io/loopward/)
</div>
每个使用工具的智能代理都会重复调用同一个接口：*选择哪个工具*。Loopward 只测试这个决策，使用您自己的工具，通过确定性预言机进行评分（无需 LLM 评判）。它会审计易混淆的工具名称，以六种方式测试路由，提出并重新验证修复方案，比较循环策略，并将失败转化为可衡量的提升。每个设计智能循环的人都在做；但几乎没有人检查循环的*决策*是否成立。
> 十三个前沿模型在我们的测试套件中能够近乎完美地路由工具（大多数达到 100%，最低不低于 97%）。但是，只需添加一行注入代码，性能就会从 **~2 分**（Claude Opus-4-8 几乎没有变化）到 **100**（Gemini-3.1-pro 完全错误）不等。单次随机种子，n=42 —— 这是一个试点，而不是排名。详见 [`docs/findings.md`](./docs/findings.md)。
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/heatmap-dark.svg">
<img alt="模型 × 攻击路由鲁棒性热图：每个单元格代表该攻击导致的准确率下降（绿色表示保持，红色表示破坏）；单元格中的数字为准确率下降的百分比（色盲友好）。单次随机种子，n=42，确定性预言机 —— 这是一个试点，而不是判决。 [实时仪表盘](https://plwslpld-arch.github.io/loopward/) 提供悬停详情和双语切换。" src="assets/heatmap.svg" width="100%">
</picture>
<sub>每个攻击导致的路由准确率下降百分比。绿色表示保持，红色表示破坏；单元格中的数字代表准确率下降的百分比（色盲友好）。单次随机种子，n=42，确定性预言机 —— 这是一个试点，而不是判决。 [实时仪表盘](https://plwslpld-arch.github.io/loopward/) 提供悬停详情和双语切换。</sub>
## 快速开始
无需安装步骤。`npx` 运行已发布的构建版本；您的本地环境无需编译。需要 Node 24+。
```bash
# 1) 哪些工具会让路由混淆？确定性，无需 API 密钥，立即执行。
npx loopward audit --tools ./my-tools.json
# 2) 使用真实模型（6 种攻击 + 置信区间）测试路由鲁棒性。
OPENAI_API_KEY=sk-... npx loopward attack --tools ./my-tools.json --provider openai --model gpt-5.5
# 3) 提出修复方案并证明其有效。
OPENAI_API_KEY=sk-... npx loopward fix --tools ./my-tools.json --provider openai --model gpt-5.5
```
或者，运行 `npx loopward` 命令，无需指定子命令，即可进入引导式设置。
`--tools` 参数接受与模型相同的 schema —— OpenAI 的函数调用格式：
```json
{
"tools": [
{ "type": "function", "function": { "name": "get_status", "description": "获取服务的当前状态或作业状态。" } },
{ "type": "function", "function": { "name": "fetch_status", "description": "获取给定资源的最新状态。" } },
{ "type": "function", "function": { "name": "refund_payment", "description": "为已完成的支付发放退款。" } }
]
}
```
Anthropic 的 `{ name, description, input_schema }` 数组和纯粹的 `[{ name, description }]` 列表也支持。
## 命令
| 命令 | 功能 |
|---|---|
| `audit` | 标记路由可能混淆的工具名称（`get_status` vs `fetch_status`）。无需模型调用，毫秒级。 |
| `attack` | 将每个请求重写六种方式，并报告路由失败的程度，附带配对自举 95% 置信区间。 |
| `fix` | 提出更清晰的工具名称，并通过相同的预言机重新验证增量变化。 |
| `matrix` | 在固定的模型上运行相同的攻击，测试 *固定的* 模型 —— 测试工具链。 |
| `flywheel` | 将案例拆分，将失败转化为防护措施，并使用置信区间衡量路由提升。 |
| `multi` | 运行真实的多步骤循环，并评估单次路由无法看到的内容：过早停止、运行过多、成功。添加 `--stop-axis` 以探测 *停止* 决策。 |
| `gate` | 当路由性能相对于保存的基线下降时，CI 失败（退出 1）。 |
| `multiseed`| 运行 N 次随机种子，并报告跨种子传播的实际情况（种子是复制单位；案例对永远不会合并）。 |
| `mcp-tools`| 从运行的 MCP 服务器导入实时工具目录，通过 stdio 实现，零依赖。 |
| `coevo` | 将每次路由错误导出为 DPO 偏好对、验证奖励样本和 SFT 负面示例。 |
| `stats` | 使用单侧排列测试 + Holm 校正重新评估报告（适用于攻击 *和* 停止轴报告）。 |
| `verify` | 在离线环境下重新推导报告的确定性字段（哈希、准确性、种子置信区间），并检查它们是否一致。 |
使 Loopward 超过简单评估的三个功能：
- **`fix`** 将诊断转化为控制器。重命名是一个模型提出的 *建议*；重新测量证明它是一个严格确定的 —— 一个 LLM 评判的评估结构无法声称的功能。
- **`matrix`** 将工具链视为独立变量。相同的自我检查节点 *损害* deepseek-chat 在攻击下（-12pp），但对 GLM-5.2 *无影响*（≈0pp，置信区间包含 0）。循环升级是否有帮助或有害是模型和工具链对的性质，而不是工具链单独的性质。
- **`flywheel`** 关闭模型↔工具链的循环，并衡量保留的提升 —— 展示的协进化故事，而不是断言。它保持为演示版本（注入并重新测量），永远不是训练器。
## 建设诚实
通过固定基线预言机评分，而不是 LLM 评判。每次运行都带有来源清单（种子、工具 schema 哈希、预言机版本、模型 ID、git sha）。`loopward verify` 在离线环境下重新检查它；`npm run regenerate-all` 证明模拟管道逐字节重现；`stats` 应用 Holm 校正，以便“显著”徽章在六个同时比较中幸存。运行时防护措施使扰动失败大声响起，而不是悄悄改变正确答案。
## 模型和密钥
适用于任何 OpenAI 兼容的端点。第一方预设（`openai`, `deepseek`, `moonshot`, `dashscope`, `groq`, `together`, `siliconflow`）内置基础 URL；其他任意 URL 均可使用 `--provider openai --base-url <url>`。密钥来自环境，每个提供商一个变量，因此存储库中没有秘密。完整列表和示例见 [`docs/providers.md`](./docs/providers.md)。
## 从 MCP 服务器引入工具
将 Loopward 指向正在运行的 MCP 服务器，它会拉取服务器提供的确切工具目录（JSON-RPC over stdio，零依赖），这样您就可以审计真实的东西，而不是手动复制的 schema：
```bash
npx loopward mcp-tools --server "npx -y @modelcontextprotocol/server-everything" --out tools.json
npx loopward audit --tools tools.json
```
`--server` 执行您提供的命令，因此请仅从受信任的服务器导入。保存的 `tools/list` 响应也完全支持离线使用 `--from saved.json`。写入的文件带有 `_source` 来源块（服务器、协议版本、工具数量、哈希）—— MCP 目录是时间点快照，文件也说明了这一点。
## 在 CI 中进行防护
```bash
npx loopward audit --tools ./tools.json --fail-on-high # 快速，无需密钥
npx loopward attack --tools ./tools.json --provider openai --model gpt-5.5 --fail-under 70 --out cur.json
npx loopward gate --baseline baseline.json --report cur.json # 与基线相比是否下降？
```
`--fail-under` 是绝对下限；`gate` 是相对对应物 —— 只有当当前运行 *显著* 低于保存的基线（配对自举，Holm 校正）时，才会失败。因此，一个翻转的案例不会因为温度-0 的抖动而触发。还可以使用 `audit --sarif out.sarif` 生成 SARIF 以进行 GitHub 代码扫描，并将现成的 [`loopward-pr`](.github/workflows/loopward-pr.yml) 工作流放入以获取每个 PR 的稳健性评论。完整设置见 [`docs/ci.md`](./docs/ci.md)。
## 发现
13 个模型的重现结果见 [`docs/findings.md`](./docs/findings.md)。简而言之：路由鲁棒性特定于模型，不跟踪功能；实际起作用的攻击是枯燥的（简洁的请求，外观相似的名称），而不是看起来像对抗性的攻击；一个天真的自我检查循环会损害一个模型，而对另一个模型无影响；在多步骤循环中，将工具观察反馈回模型将任务成功率从 10% 提升到 60%。工具链的决策与模型一样重要。
## 这不是什么
不是排行榜，不是安全审计，也不是用于生产的循环 *运行器*。它是用于循环内部的路由和停止决策的诊断和修复工具。它并不声称是首个评估工具选择的工具。详见 [`RELATED-WORK.md`](./RELATED-WORK.md)，与 CATS/ToolCert、MetaTool 和 Harness-Bench 进行诚实的比较。
## 布局
```
packages/core 循环运行器 + 策略、路由预言机、提供商、多步骤、工具审计、清单、MCP + SARIF
packages/redteam 6 种攻击类、鲁棒性指标 + 自举 CI、修复、含义防护、停止轴探测
packages/eval 工具链矩阵、统计数据（Holm）、验证（报告检查）、防护（回归）、种子扫描（多种子）
packages/coevo 将失败导出为训练信号；微循环飞轮实验
packages/cli audit / attack / fix / matrix / flywheel / multi / gate / multiseed / mcp-tools / coevo / stats / verify
packages/ci 纯粹的 PR 评论 + shields 徽章渲染器（格式化报告；从不评分）
packages/dashboard 自包含的双语发现仪表盘（部署到 GitHub Pages）
harnesses 4 种循环策略作为“测试样本” + 每个策略的帮助/损害情况
datasets 路由、多步骤、工具模式和黄金标签套件
```
运行检查，使用 `npm test`（离线，无密钥）。设计笔记见 [`docs/`](./docs)。
## 来源和许可证
独立的清洁室实现。无先前雇主或第三方代码、数据或命名。详见 [`PROVENANCE.md`](./PROVENANCE.md)。Apache-2.0。
