Tiltmeter

Tiltmeter

为 AI Agent 依赖的第三方 API 提供早期预警，并通过拉取请求提交修复。 · tiltmeter.dev

火山学家会把倾斜仪固定在地面上，感知微小的地形变形，远早于火山喷发。Tiltmeter 也会监测 Agent 所依赖的 API。它从真实流量中学习 JSON 响应的结构，发现供应商重命名字段、开始发送 null，或将数字改为字符串时，就会在一切失控之前通知你、你的 CI 和 Agent。随后，tiltmeter fix 会将变更交给 Agent，让它调整读取该 API 的代码并创建拉取请求，而它无法确定的部分则留给人工处理。

当 API 变更时，类型化代码会立刻崩溃。Agent 却不会。它们会读取新的响应，靠猜测填补缺失信息，或者不断重试，直到预算耗尽。

亮点

• Agent 可以在行动前进行检查。 MCP 服务让 Claude Code、Cursor、LangChain 或任何 MCP 客户端在信任某个 API 前调用 has_drifted，并调用 get_schema 查看预期字段。
• 无需规范。 Tiltmeter 从真实响应中学习，因此适用于任何 JSON API，无论是否有文档。
• 一眼看出是破坏性变更还是无害变更。 每项变更都会被分类为破坏性变更、警告或信息；如果某个字段被移除，而附近出现了相似的新字段，就会将其标记为可能的重命名。
• 按需获取解释。 配置 Anthropic API 密钥后，Claude 会解释发生了什么变化、可能的原因以及应采取的措施。
• 还能修复。 tiltmeter fix 会将偏差交给 Agent，让它调整读取该 API 的代码、展示差异并创建拉取请求。你可以使用内置的 LangChain Deep Agent，也可以使用自己的 Claude Code 或 Codex 登录。
• 带警报的 CI 门禁。 遇到破坏性偏差时，退出码会使构建失败。只需一行配置即可启用 Slack 和 webhook 警报。
• 本地运行，保护隐私。 只需一个 SQLite 文件，无需账户。凭据会在请求时展开，绝不会存储。不会存储或发送响应正文，也不会发送给大模型，只处理其结构。

快速入门

pip install tiltmeter        # or: uv tool install tiltmeter
tiltmeter init               # writes tiltmeter.yaml with a public example API
tiltmeter check              # the first check records the baseline

已经在 Web 应用中调用 API？从浏览器的 DevTools（Network 选项卡中选择“Export HAR”）导出 HAR，让 Tiltmeter 根据页面发出的 JSON 调用生成配置。令牌和 Cookie 会转换为 ${VAR} 占位符：

tiltmeter init --from-har session.har --host api.example.com

从 cron 或 CI 再次运行 tiltmeter check，或者让 tiltmeter watch 持续运行。下面展示的是供应商将 phone 重命名，并把 balance 改为字符串时的结果：

$ tiltmeter check
✗ billing_customers  200 · 13 ms  BREAKING · 3 changes
    breaking  type_changed   $.data[*].balance       integer → string
    breaking  field_removed  $.data[*].phone         string → (absent)  possibly renamed to $.data[*].phone_number
    info      field_added    $.data[*].phone_number  (absent) → string  possibly replaces $.data[*].phone
1 endpoint checked · 1 breaking
$ echo $?
2

入门指南会在你的机器上针对一个模拟 API，完整演示这一场景，约需五分钟。

为你的 Agent 配备倾斜计

claude mcp add tiltmeter -- tiltmeter serve --config /absolute/path/to/tiltmeter.yaml

然后在 Agent 的指令中添加这样一行：

在依赖第三方 API 之前，先对它调用 has_drifted。如果它发生了漂移，请阅读 摘要并做出调整，然后再信任响应。

工具	用途
has_drifted(endpoint_id, since?)	最近的响应是否发生了警告级别或更严重的变化？返回摘要和变更内容。
get_schema(endpoint_id)	预期有哪些字段、类型和枚举值？以 JSON Schema 的形式返回。
get_changes(endpoint_id?, since?, min_severity?, limit?)	按时间倒序排列的变更历史。
list_endpoints()	正在监测哪些 API，以及它们上次检查的结果。
check_api(endpoint_id, explain?)	立即调用一个 API 并记录结果。
check_all(explain?)	立即调用所有 API。

Cursor、Claude Desktop 和 LangChain Agent 的配置说明见 Agent 指南。

让它修复你的代码

检查发现漂移时，tiltmeter fix 会将问题交给 Agent，由它找到读取该 API 的代码并进行调整、向你展示差异，然后创建拉取请求：

$ pip install "tiltmeter[fix]"            # or plain tiltmeter, then --agent claude-code or codex
$ tiltmeter fix 2 --repo ~/code/billing-service
✗ billing_customer  #2  200 · 10 ms  BREAKING · 3 changes
Working on a new branch, tiltmeter/fix-billing-customer-2, from main at 162dadd.
3 files changed  +5 -5
diff --git a/billing/client.py b/billing/client.py
-    return f"{customer['name']} <{customer['phone']}>"
+    return f"{customer['name']} <{customer['phone_number']}>"
...
Commit, push and open a pull request? [y/N]: y
✓ opened https://github.com/acme/billing-service/pull/41

• 绝不会改动你的工作副本。 Agent 会在新分支上的临时 git 工作树中工作；只有在你批准差异或传入 --yes 后，才会提交更改。
• 操作范围仅限工作树。 无法访问网络，且只能读取其中已跟踪的文件；.env 文件、密钥和 .git 均不可访问。内置 Agent 和 Claude Code 只能使用文件工具。Codex 保留其 shell，但会在操作系统沙箱中运行，并遵守相同限制。
• 说明无法完成的事项。 Tiltmeter 能看到类型，看不到值。当数字变成字符串时，Agent 会更新类型，并在拉取请求中将格式问题留给人工处理，而不是猜测如何转换。
• 使用你自己的 Agent。 已经在使用 Claude Code 或 Codex？运行 tiltmeter fix 2 --agent claude-code 或 --agent codex，即可使用你自己的登录凭据，无需 API 密钥，也无需额外安装。

--dry-run 会显示差异后将其丢弃，--no-pr 则会提交到本地分支。修复指南介绍了这些标志、模型可见的内容以及如何审查结果。

什么情况算作漂移

变更	示例	默认严重程度
field_removed	phone 曾出现在每个响应中，现在已消失	breaking
field_now_optional	email 以前总会出现，现在有些对象中缺失	breaking
type_changed	balance 从整数变成了字符串	breaking
nullable_introduced	phone 现在可以为 null	breaking
content_type_changed	JSON 正文变成了 HTML 错误页面	breaking
status_changed	200 变成 503 属于 breaking，404 变成 200 属于 info，200 变成 202 属于 warning	视情况而定
enum_value_added	status 除了返回 active 和 past_due，还返回了 suspended	warning
latency_regression	中位延迟超过基线的 3 倍，且至少慢了 250 ms	warning
field_added	新增了 phone_number 字段	info，或在 strict: true 时为 warning

可通过 severity_overrides 全局覆盖这些设置，也可针对单个端点进行覆盖。

在 CI 中使用

退出代码	含义
0	没有漂移。仅包含 info 级别的变更以及新基线都视为没有漂移。
1	warning 级别的漂移。
2	breaking 级别的漂移。
3	无法运行检查（网络错误、状态异常、JSON 无效），且没有发生破坏性变更。
4	用法或配置错误。

在 GitHub 上，Tiltmeter Action 会将基线保存在 Actions 缓存中，将变更写入作业摘要，并在发生漂移时使作业失败：

- uses: tiltmeter-dev/tiltmeter-action@v1
  env:
    STRIPE_API_KEY: ${{ secrets.STRIPE_API_KEY }}

在其他环境中，请在每次运行之间保留 .tiltmeter/。CI 指南提供了可直接复制的 GitHub Actions、GitLab CI 和 cron 作业配置。

工作原理

1. 观察。 检查会调用端点，并将 JSON 响应体转换为 形状：对于每条路径，记录出现过哪些 JSON 类型、有多少对象包含每个字段，以及对于看起来具有类别特征的字段（active、past_due、USD），记录见过哪些值。
2. 比较。 基线由最近 20 次成功检查的形状合并而成。Tiltmeter 只报告与基线矛盾的内容：缺少可选字段没关系，但如果某个字段曾出现在每个对象中，现在却消失了，就会报告。
3. 只报告一次。 新形状会加入基线，因此发现变化的那次检查会报告变化；之后它就成为新的常态。

graph TD;
  start([start]) --> observe
  observe -. fetch failed .-> persist
  observe --> load_baseline --> compare
  compare -. drift worth explaining .-> explain --> persist
  compare --> persist
  persist -. a notifier wants it .-> notify --> finish([end])
  persist --> finish

该流程是一个小型 LangGraph 图，只负责按顺序执行各个步骤。差异比较本身是纯粹、确定性的 Python 代码，不涉及大模型。工作原理介绍了详细信息。

配置

endpoints:
  - id: stripe_customers
    url: https://api.stripe.com/v1/customers
    params:
      limit: 10
    headers:
      Authorization: Bearer ${STRIPE_API_KEY}   # expanded from the environment at request time
    ignore_paths:
      - $.data[*].metadata                      # free-form, changes all the time

notify:
  - type: slack
    webhook_url: ${SLACK_WEBHOOK_URL}

配置参考介绍了每个选项，而 examples/ 中有一份可直接运行的配置。

对比

• OpenAPI 差异比较工具，例如 oasdiff，会比较两个版本的规范。如果供应商发布并维护规范，这类工具就很合适；但它们无法发现供应商未记录的变化。
• 契约测试，例如 Pact，需要提供方运行你的契约，而第三方供应商不会这样做。
• 正常运行时间和合成监控可以告知 API 是否正常运行，但响应断言需要你自行编写和维护。
• Tiltmeter 从真实响应中学习契约，因此不需要供应商提供任何内容，也能捕获未记录的变化。它还会将学到的内容交给你的 Agent。

隐私与安全

• ${VAR} 占位符会在发送请求或通知前立即展开。其值绝不会写入磁盘、发送给大模型或保存在 LangGraph 状态中，并且会从错误消息中清除。
• 历史记录存储形状、状态码、延迟和变化，除非设置 store_samples: true，否则绝不存储响应体。
• Agent 只能检查配置中指定的端点，无法让 Tiltmeter 调用任意 URL。
• tiltmeter fix 会将变化列表和 Agent 打开的文件发送给 Anthropic。它绝不会看到响应值、${VAR} 的值或 .env 等未跟踪文件，并且会阻止匹配 fix.ignore 的路径。

SECURITY.md 介绍了完整的威胁模型以及如何报告漏洞。

路线图

• 在 CI 和通过 MCP 修复。 定期检查发现偏差时，从 GitHub Action 运行 tiltmeter fix，并允许 Agent 通过 MCP 工具请求修复。
• 提供方模式。 API 供应商只需宣布一次变化，所有客户都会收到拉取请求。
• 规范和变更日志感知。 将供应商的 OpenAPI 规范和变更日志与观测到的响应一并进行差异比较。
• 托管检查和团队仪表板。

文档

• 快速入门：在你的机器上用五分钟快速了解。
• 配置参考：所有选项、占位符和忽略模式。
• Agent 和 MCP：Claude Code、Cursor、Claude Desktop 和 LangChain。
• CI 和定时任务：GitHub Actions、GitLab CI 和 cron。
• 修复代码：tiltmeter fix、Agent 以及如何审查其拉取请求。
• 工作原理：形状、基线、差异规则和流程。
• 常见问题与故障排查。

贡献

欢迎提交错误报告、想法和拉取请求。CONTRIBUTING.md 说明了如何设置项目，以及什么样的改动才是好的。所有参与者都应遵守行为准则。

许可证

MIT