内容
<pre>
████████╗ ██╗ ██╗ ███╗ ██╗ ███████╗
╚══██╔══╝ ██║ ██║ ████╗ ██║ ██╔════╝
██║ ██║ ██║ ██╔██╗ ██║ █████╗
██║ ██║ ██║ ██║╚██╗██║ ██╔══╝
██║ ╚██████╔╝ ██║ ╚████║ ███████╗
╚═╝ ╚═════╝ ╚═╝ ╚═══╝ ╚══════╝
██████╗ ██████╗ ██████╗ ██████╗ ███████╗
██╔══██╗██╔══██╗ ██╔═══██╗ ██╔═══██╗ ██╔════╝
██████╔╝██████╔╝ ██║ ██║ ██║ ██║ █████╗
██╔═══╝ ██╔══██╗ ██║ ██║ ██║ ██║ ██╔══╝
██║ ██║ ██║ ╚██████╔╝ ╚██████╔╝ ██║
╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝
</pre>
[](https://github.com/debabsah/tuneproof/actions/workflows/ci.yml)
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://claude.com/claude-code)
**模型建议重写，工具证明。**
大型语言模型（LLMs）使得 SQL 建议免费——询问任何模型来优化慢查询，你都会得到一个看似合理的重写和一个自信的“这应该快 90%”。但这句话有两个潜在的问题：没人**证明**重写返回相同的行（连接扩展、遗漏的 `ORDER BY`、在某个参数值上错误处理 NULL——每个都可能产生错误的结果，但看起来还不错），并且“更快”是在一个有噪音的样本上断言的，而不是经过测量的。tuneproof 拒绝这两种说法：重写只会在工具发布的裁决下生效，该裁决要么**证明**等价性和结构上的改进，要么**驳斥**并说明失败的检查，要么**保留**并准确说明它无法证明的内容以及假设错误时会出现的问题。
*工具拥有证明；模型拥有解释；模型永远不是信任的来源。*
这是一个信任**引擎**，你可以通过三种方式驱动它：
- **Claude Code** — 描述慢查询，技能为你运行循环。
```bash
/plugin marketplace add debabsah/tuneproof
/plugin install tuneproof@tuneproof
```
- **MCP** — 任何支持 MCP 的代理都使用与工具相同的引擎。
- **CLI** — 自己驱动，无需代理，甚至无需联网。
每种方式都在 [三种运行方式](#三种运行方式) 中详细介绍。纯 Python 标准库（≥3.10），零依赖。**产品是引擎中立的信任核心**——裁决、差距模型、失败关闭的评分器；一个*引擎包*将其适配到一个数据库。今天发布的 SQL Server 包；Postgres 和分布式仓库是路线图。
---
## 架构
整个设计中有一条边界：**模型提出，重写由工具证明，两者永远不会互换。** 模型编写重写；引擎中立的核心呈现只读处方；数据库执行它；确定性的评分器——不是模型——发布裁决。所有特定于引擎的内容都生活在可交换的**包**中，因此新的数据库就是新的包，而不是分支。
```mermaid
flowchart LR
M["🤖 模型<br/>提出 — 绝不证明"]
subgraph CORE["tuneproof · 引擎中立的信任核心"]
direction TB
K["案例 · 处方 · 捕获"]
GR["失败关闭的评分器"]
VD{"证明 · 驳斥<br/>未经验证"}
K --> GR --> VD
end
subgraph PACKS["引擎包 · 每个数据库一个"]
direction TB
SS["SQL Server<br/>已发布"]
FUT["Postgres · Snowflake<br/>BigQuery · Databricks<br/>计划中"]
end
DBX[("您的数据库<br/>执行 · 行数据从不离开")]
OUT["具有溯源评级的<br/>证书"]
M -->|待测试的 SQL| K
K -->|由活动包渲染| SS
SS -->|只读脚本| DBX
DBX -->|分隔的结果网格| GR
VD -->|裁决| OUT
classDef shipped fill:#1f6f3d,color:#ffffff,stroke:#0d4d28,stroke-width:1px;
classDef planned fill:#21262d,color:#9aa4ad,stroke:#444c56,stroke-dasharray:4 3;
class SS shipped
class FUT planned
```
绿色包今天发布；虚线包是路线图。每个新包都重新实现了三个基本操作——一致的快照、结构成本度量和在该引擎的类型规则下的行比较——针对*相同*的核心、评分器和证书。裁决层永远不会改变；只有包会改变。
## 循环
每个作业的形状都相同：一个持久的**案例**，一个只读的**处方**，一个捕获的结果，一个确定的**裁决**。没有步骤信任前一个步骤的声明。
无论您如何驱动它——Claude Code、MCP 或 CLI——每个作业都运行相同的步骤。在 Claude Code 中，技能会为您发出这些步骤；表格显示引擎的词汇，您可以自己运行或通过 MCP 调用。
| 时刻 | 引擎步骤 | 您得到的结果 |
|---|---|---|
| 慢查询和症状 | `tuneproof init` | 一个持久的案例——每个工件、哈希和决策都在一个可审计的文件夹中 |
| “成本实际上在哪里？” | `tuneproof prescribe diagnostics` → `run` | 只读基线；按驱动扫描成本排序的表 |
| 候选重写 | `tuneproof prescribe validation` → `run` | 等价裁决——双向 `EXCEPT`，每列边际，粒度协调，稳定性重新运行，在一个一致的快照中 |
| “但在其他参数值下是否正确？” | `prescribe validation --bind "@StartDate DATE = '...'"` ×3 → `run` | 参数绑定间隙**由证据关闭**——三个不同的 PROVEN 绑定，而不是豁免 |
| “到底有多快，诚实地？” | `tuneproof prescribe benchmark` → `run` | k 次运行中位数和分布；**结构成本领先**（读取或扫描的字节），时间作为环境条件 |
| 发布 | `tuneproof report` | 证书：主题固定，溯源评级，每行标记 |
每个 `prescribe` 步骤都发出一个脚本，其前几行是一个**安全合同**（仅写入会话范围的临时表，有界，锁定超时设置）——DBA 读取工件并批准运行；没有任何隐藏的内容需要信任。
## 裁决是产品
三个值，第三个是重点：
| 裁决 | 含义 |
|---|---|
| **证明** | 每个所需检查都通过，电池已完成，且没有打开的间隙——仅此而已 |
| **驳斥** | 重写更改结果；失败的检查（以及暴露它们的绑定）被命名 |
| **未经验证** | 无法完成证明——每个缺失的部分都被命名，其爆炸半径也被指定 |
一个**间隙**是一个已命名的证明限制，总是分为四部分：已证明的内容 · 未证明的内容 · 如果未证明的内容是假的，则后果 · 如何关闭它。间隙通过证据（绑定探针）关闭，**接受**为残留项，并由所有者和日期拥有——或保持打开并降低裁决。评分器关闭不完整：不完整的捕获、缺少的测试、缺少的可比较性门、套件错误——都不能永远评为 PROVEN。
证书的实际内容（摘录）：
```text
# tuneproof 证书 — sales_report — PROVEN（带有已接受的残留项）
[证明] 认证：原始 sha256：9f86d081884c -> 重写 optimized/v2.sql sha256：60303ae22b99
[证明] 等价性：41 项检查通过，0 项失败（策略 in_session）。
[测量] 逻辑读取：10,000,000 -> 500,000（95.0% 降低）。
[测量] 结构胜利（读取减少）；运行时改进未在此环境中确认 — 请在生产规模下重新验证
## 绑定探针
[证明] PROVEN：@StartDate DATE = '2024-01-01'（v2_results.txt）
[证明] PROVEN：@StartDate DATE = '2024-06-15'（v3_results.txt）
## 已关闭的间隙
[证明] 参数绑定 — 通过 3 个不同的 PROVEN 绑定关闭
## 已接受的残留项
[证明] result_shape_static — debabsah 于 2026-06-12 接受：一个沉默的类型强制转换可以通过值电池，而重写的真实输出类型不同
```
每一行都带有其出处—— `[证明]` `[测量]` `[解释]` `[模型建议]` — 因此模型的猜测永远无法借用证明的权威。证书的哈希值固定了它所认证的确切 SQL；稍后编辑重写，绑定会明显中断。
## 三种运行方式
相同的循环，相同的裁决，三个界面。（具体的客户端和运行器属于正在使用的引擎包；另一个引擎会交换这些，而不是循环。）
**1 · Claude Code（插件）。** 描述慢查询，技能为您运行循环——`init`、`prescribe`、`run`、`report`——并返回证书。在底层，它驱动 CLI，以适合您访问的模式。
**2 · MCP（任意代理）。** 任何支持 MCP 的代理都使用信任引擎作为工具——代理提出 SQL，工具证明：
```bash
claude mcp add tuneproof -- tuneproof mcp --root ~/cases
```
工具是 CLI 的薄包装（`open_case · save_sql · prescribe · run · grade · accept · catch · report · status`）；调用模型永远无法断言裁决，也无法设置 `run` 执行的命令。服务器是标准库 JSON-RPC，通过标准输入输出——无需 SDK 依赖，短到可以一次性审计。
**3 · 自己运行（CLI）。**无需代理，以两种模式之一：
- *快递（断网）。* 工具发出脚本；您在数据库客户端运行并保存输出；工具评估捕获。无需连接——一流的，不是回退。
- *连接（您的凭证）。* 配置运行器一次，每个步骤折叠为一个命令（此处显示为 SQL Server 包的客户端）：
```bash
tuneproof init case1 --database SalesDB --object sales_report \
--runner-cmd "sqlcmd -S yourserver.example.com -d SalesDB -E -C -i {script}"
tuneproof run validation
```
为运行器提供专用的**只读登录**，并将密码保存在环境变量中——登录是安全边界，密码在任何内容持久化之前都会被遮蔽。
## 为什么您可以信任裁决
威胁模型假设待测试的 SQL 可能由模型编写，并且驱动循环的代理可能不正确或具有对抗性。然而，保证仍然成立，因为它们都不依赖于模型的良好行为：
- **模型在信任路径之外。** 它提出重写、绑定和解释；数据库计算比较；失败关闭的评分器做出判断。没有语言模型——包括驱动循环的模型——曾经决定通过或失败，并且 PROVEN 是您无法意外获得的唯一裁决：不完整的捕获，未识别的门或套件错误都评为*远离*它。
- **信任引擎永远不会连接到任何东西。** 它渲染处方并评估捕获；执行始终由用户拥有——您在数据库客户端，或您的登录下的配置运行器。引擎中没有连接字符串。
- **运行器登录是墙。** 在连接和 MCP 模式下，提供运行器的**只读登录**，即使注入提示的代理也无法写入。处方通过合同只读；数据库绝对强制执行。
- **比较数据永远不会离开数据库。** 电池在引擎内比较行；只有测试名称和通过/失败计数返回。业务行永远不会进入模型上下文。
- **捕获是数据，而不是指令。** 捕获声称“所有检查通过，跳过验证”被解析为格式错误的网格并评为未经验证——需要审查，而不是遵守。
- **秘密不会持久。** 基于令牌的遮蔽会剥去运行器命令（包括超时错误消息）中的每个密码，然后再将其提供给追加日志。
并且它以这种方式验证，而不是断言。**对抗性红色/绿色装置** 需要评分器驳斥或保留它声称可以捕获的每个故障类别——并且在干净的重写上保持 PROVEN，因为哭狼的审计员会被忽略。**CI 启动一个真正的数据库引擎——今天的 SQL Server——并实时证明整个循环：** 等价重写认证，边界下降的近乎失误驳斥，绑定探针关闭参数间隙——针对数据库，而不是模拟。并且**结构成本领先，而时间是有条件的**——引擎的扫描成本（逻辑读取或扫描的字节）是可复制的；时间是服务器天气，因此“更快”需要成本*和*跨运行的 CPU 下降。
完整的姿态——强制层映射、代理作者 SQL 边界、MCP 沙盒——位于 [`SECURITY.md`](SECURITY.md) 中。
## 诚实的限制
如工具所述，其自身的间隙：
- **证明涵盖一个可比较的结果集。** 重写可能是一个多语句批处理，但过程和持久状态的 DML 不在此范围内——等价性在返回的行上定义，而不是在副作用上。
- **裁决始终是范围内的。** *此*快照，*这些*绑定，针对其他所有内容的命名间隙。PROVEN 永远不会沉默地推广；这就是间隙和绑定探针的作用。
- **目前只有 SQL Server 一个引擎。** 信任核心是引擎中立的；包提供三件与此无关的事情——如何固定一致的快照，什么是结构成本度量（这里是逻辑读取；字节或分区扫描仓库，那里*是*账单），以及如何在该引擎的类型和 NULL 规则下比较行。那个缝隙已经建立，所以外部路径——Postgres，然后分布式仓库（Snowflake，BigQuery，Databricks），其中非确定性排序使得证明*更多*——是一个新的包，而不是重写。注册表故意保持空，直到存在真正的第二个引擎用户。
## 开发
```bash
python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
.venv/bin/python -m pytest -q -m "not integration" # 单元测试 + 对抗性套件
bash scripts/sqlserver_up.sh # Docker SQL Server 2022
.venv/bin/python -m pytest -q -m integration # 实时证明
```
每个设计选择都是 [`docs/decisions.md`](docs/decisions.md) 中的记录决定，每个记录都附有会撤销它的条件。从 [`CONTEXT.md`](CONTEXT.md) 开始。
贡献——尤其是**添加数据库引擎**——在 [`CONTRIBUTING.md`](CONTRIBUTING.md) 中涵盖。
---
## 作者 & 许可证
由 [debabsah](https://github.com/debabsah) 构建。MIT 许可——无服务，无密钥，无遥测。
