keel

keel

面向 AI 编码 Agent 的可观测自主运行框架。 — 作者：TokenDrift

keel 是一个 MCP 服务，为你的编码 Agent（Claude Code、Cline 等）提供工具，让它能够端到端完成长任务——不偏离目标、不耍花招，也不丢失进度，同时记录它所做的一切，让你能够把控成本和质量。

你启动任务。Agent 自我约束。你回来时，就能看到里程碑报告。

名称由来：龙骨是船上看不见的部分——水线下的脊梁，能防止船被风吹得偏离航向。这就是它的作用。

---

问题

独自执行长任务的 Agent 往往会做出四件事，而你发现时通常为时已晚：

• 它会忘记上下文。 上下文被压缩后，早先的决策就会被遗忘，工作被重复执行或前后矛盾。
• 它会耍花招。 面对“让测试通过”这样的要求，Agent 会悄悄修改测试本身——这就是奖励劫持。测试套件变绿了，但实际上什么都没能正常工作。
• 它会丢失文件。 一次覆盖、一次糟糕的重构，就可能让一小时的工作付诸东流，而且没有任何检查点。
• 成本像个黑箱。 你不知道这次运行花了多少钱、哪个模型耗尽了预算，也不知道 Agent 是否在某一步循环了二十次。

keel 为每个问题都提供了一个工具，并由 Agent 自行调用——因为初始化时，规则会注入到它的 CLAUDE.md 中。每次调用都会生成一个事件，因此整个运行过程事后都清晰可查。

---

keel 实际运行

在一个临时的 calc-kit 项目上进行的一次真实运行——要求 Agent 按照 keel 协议实现 add(a, b)，使锁定的测试通过。以下是未经编辑的实际调用顺序：

1.  load_context      → project loaded, tests intact
2.  record_decision   → "add = a + b, minimal, no deps" logged
3.  (writes calc.py)
4.  save_progress     → state persisted
5.  verify            → green: 2 passed, tampered: false
6.  checkpoint        → commit fac81a4 — milestone CERTIFIED
7.  check_drift       → no drift
8.  log_usage         → sonnet, 4000/1200 tok → $0.03
9.  route_task        → (sensitive) recommends EU-hosted model;
                        US + CN clouds excluded
10. stats             → 1 verify / 100% pass, 1 certified milestone, 0 cheat alerts
11. report            → milestone report written to .keel/reports/

然后，为了证明反作弊机制确实有效——我们手动修改了一个锁定的测试文件（模拟 Agent 篡改测试以强行让它变绿），并运行了 verify：

{
  "tampered": true,
  "tests_changed": ["~ tests/test_calc.py (modified)"],
  "passed": true
}

tampered: true 和 passed: true 同时出现。keel 不会把“测试通过”与“测试未被篡改”混为一谈——它会分别报告这两个维度。Agent 可以通过篡改测试让测试套件变绿，而 keel 依然能发现。这种区分正是关键所在。

---

反作弊：证明机制，而非牢笼

任何可选工具运行环境都有一个棘手的问题：Agent 可以忽略 verify，直接在终端运行 pytest，绕过唯一能发现作弊的机制。在 CLAUDE.md 中写上一条礼貌的指示，只能影响 Agent 尝试做什么——并不能阻止任何行为。

keel 通过三层机制解决这个问题，遵循的原则是：没有任何单一层面是完美的，但三者结合后，不存在既轻松、无声又不留痕迹的绕过路径：

1. 劝导——CLAUDE.md 中的说明会明确告诉 Agent：verify 是唯一的裁判，禁止直接运行测试。应对最常见的情况：Agent 因疏忽而偏离流程，而非出于恶意。

2. 机械防护——init_project 会在项目的 .claude/settings.json 中安装一个 PreToolUse 钩子（keel-guard）。它会在 pytest、python -m pytest、npm test、yarn test、go test 执行前拦截这些命令并拒绝执行，引导 Agent 使用 verify。该机制运行于 Claude Code 运行环境中，超出模型的控制范围。在我们的配置下，即使在 --dangerously-skip-permissions 模式下也有效（绕过模式会跳过交互式确认，但不会跳过钩子——请在自己的机器上验证，参见 诚实的局限）。

3. 防篡改证明——对于任何漏网的情况，verify 都会生成其判定所依据的确切工作树状态的哈希值；只有在同一棵工作树上运行了通过验证且未被篡改的 verify，checkpoint 才会将里程碑标记为 certified。绕过机制会产生未经认证的里程碑——这会显示在 stats 和 report 中，而不是悄无声息地通过。

第二层让明显的绕过变得困难。第三层让每一次绕过都留下痕迹。keel 会认证它实际见证的内容；它不会声称能让规避行为变得不可能——而正是这种坦诚，让**“已认证里程碑百分比”**成为值得长期追踪的指标。

让这一机制奏效的黄金法则：测试由你编写，绝不交给 Agent。 verify 会运行你锁定的测试套件，并逐个文件检测其中的任何变更。如果你亲自修改了测试，请重新运行 lock_tests（由人工执行）。

---

安装

keel 是纯 Python 项目——只有一个依赖（MCP SDK，它会引入 FastMCP 和 pydantic），以及 git。它主要在 Windows 上开发并强化，也可在 macOS/Linux 上运行。

git clone https://github.com/tdalbanmoreynas/keel.git
cd keel
python -m venv .venv
pip install -r requirements.txt
python keel_server.py        # must start without error (Ctrl-C to quit)

在 Windows 上，虚拟环境的激活命令是 .venv\Scripts\activate；在 macOS/Linux 上则是 source .venv/bin/activate。如果直接让客户端使用虚拟环境中的 Python（见下文），则无需激活。

连接到 Claude Code

# from the keel folder, pointing at the venv's interpreter (absolute paths)
# macOS/Linux:
claude mcp add keel -- /absolute/path/to/keel/.venv/bin/python /absolute/path/to/keel/keel_server.py

Windows 示例：

claude mcp add keel -- "D:\path\to\keel\.venv\Scripts\python.exe" "D:\path\to\keel\keel_server.py"

或者将 mcp_config.example.json 中的代码块粘贴到客户端的配置中（Cline：cline_mcp_settings.json）。

以下两点可以帮你避免一次调试：

• 为 keel 的工具添加允许规则，在 Claude Code 设置中添加（mcp__keel__*），否则 Agent 首次调用 keel 时会卡住，等待不一定会显示的授权提示。
• 从项目根目录启动客户端。 keel-guard 钩子从当前目录的 .claude/settings.json 加载，不会回退到父目录——只有在 Claude Code 从项目所在目录运行时，它才会生效。

---

兼容性

keel 分为两个部分，它们的适用范围不同。

12 个 MCP 工具采用标准的 MCP — 可与任何兼容 MCP 的编码 Agent配合使用：Claude Code、Codex、Cursor、Cline、Windsurf、Zed、VS Code + Copilot、Continue、Goose，以及 Cline 的分支版本（Roo Code、Kilo Code）。记忆、检查点、防篡改的 verify、认证、决策日志、成本跟踪和 route_task 都可以在任何支持 MCP 的地方运行。

**keel-guard hook（第 2 层）**是 Claude Code 专用的。它是 .claude/settings.json 中的一个 PreToolUse hook — 这是 Claude Code 的机制，目前其他客户端都未实现。因此：

客户端	MCP 工具（第 1 层和第 3 层）	机械防护（第 2 层）
Claude Code	✅ 完整支持	✅ 支持 — keel-guard hook 会安装并触发
Codex、Cursor、Cline、Windsurf、Zed、Copilot、Continue、Goose	✅ 完整支持	⚠️ 未安装 — 没有 hook 系统

在非 Claude Code 客户端上，你仍可获得劝导层（注入的规则），以及至关重要的认证层：跳过 verify 的检查点在 stats 和 report 中仍会显示为未经认证。你失去了对直接运行测试的机械拦截，但没有失去可见性 — 绕过行为仍会被记录。这正是证明体系设计发挥作用之处：真正重要的保证（你始终可以判断某个里程碑是否经过验证）不依赖任何一个客户端的 hook 系统。

keel 在 Claude Code 上最为完整，也是在此开发和加固的。除第 2 层外，其他客户端对所有功能都享有一等支持。

---

工作流

1. 每个项目执行一次 — init_project：创建 .keel/，写入架构和不可变约束，锁定你的测试文件，初始化 git，安装 keel-guard hook，并将自主运行规则注入 CLAUDE.md。
2. 之后由 Agent 按照这些规则自行管理：每次会话开始时调用 load_context，每完成一步后调用 save_progress + checkpoint，通过 verify 进行验证，每次模型调用后调用 log_usage，每次做出架构选择时调用 record_decision，并在最后调用 report。

你只需在里程碑时回来，无需逐行跟进。

---

12 个工具

工具	作用	防范对象
init_project	搭建运行框架（架构、约束、测试锁定、git、hook、CLAUDE.md）	—
load_context	在会话开始时提供恢复工作所需的简报	上下文丢失
save_progress	将已完成 / 正在进行 / 待办事项写入磁盘	上下文丢失
record_decision	以仅追加方式记录架构选择	架构偏移
checkpoint	提交当前步骤的 Git 提交，并附带认证	文件丢失
verify	运行已锁定的测试并检测篡改	欺骗（奖励操纵）
lock_tests	重新锁定测试（由人执行）	—
check_drift	回顾约束，标记尚未保存的工作	偏移
route_task	为子任务选择最具成本效益的模型	成本 / 数据主权
log_usage	记录模型调用的实际花费	成本可观测性
stats	汇总指标（成本、欺骗、认证、速度）	引导
report	面向人的 Markdown 里程碑报告	引导

---

keel 记录的内容

每个工具都会向 .keel/events.jsonl 写入一个事件（保存在本地，仅对你的仓库可见）。keel 会持续根据这些记录推导出：会话、检查点、已认证与未经认证的里程碑、verify 通过率、欺骗警报、每个模型的实际成本以及速度。这些记录让 Agent 运行过程清晰可见 — 也是下方资助层所需的原始材料。

---

开源核心 — keel 是免费的传感器

keel 是由两个部分组成的一款产品。这个仓库——本地传感器——永久免费，采用 MIT 许可证。 它完全在你的机器上运行：监控你的 Agent、捕捉篡改行为、追踪浪费和成本，并将所有内容写入不会离开你的仓库的本地 events.jsonl。独立开发者不需要其他任何东西。

获得资金支持的部分是面向工程团队的云端仪表板（由 TokenDrift 提供），计划基于同一传感器构建。免费层回答的是*“我的 Agent 表现如何？”，团队仪表板回答的则是“随着时间推移，我的整个团队表现如何？”——它会汇总团队中每位开发者传感器的数据：Agent 总支出和可挽回的浪费、经诚实认证（而不仅仅是显示绿色）的里程碑占比、预算或作弊率飙升时的实时警报，以及与其他团队进行匿名基准比较（“你的 Agent 篡改行为比中位数高 3 倍”*）。

这种划分是有意为之：传感器免费，因为本地二进制文件可以被克隆，无法出售——它的作用是提供价值并广泛传播。付费价值在于团队级网络和汇总数据，而单个本地安装从结构上就无法生成这些数据。这与 Langfuse、PostHog 和 Sentry 的模式相同：个人用户可以免费使用完整功能；当你成为需要整体视图的团队时，才需要付费。

隐私保护内置于这种划分之中：传感器只发送元数据——绝不发送你的代码或提示词。 作弊检测在本地运行；只有判定结果（已认证／可疑）可能会离开你的机器。

---

关于 route_task 和价格的说明

模型价格（keel_core.py 中的 MODELS 常量）是 2026 年 6 月的估算值——请替换为你的实际费率。route_task 会计入 Agent 式消耗（成本 = token 数 × 迭代次数 × 低效系数），并在 sensitive=True 时排除非欧盟云服务，因此上方运行中的敏感子任务被路由到了托管在欧盟的模型。

---

诚实说明限制

keel 的设计原则是如实说明它能保证什么、不能保证什么——这种诚实就是产品的一部分，而非免责声明。

• 防护机制能捕捉规范的测试调用，但无法涵盖所有可能形式。 使用别名的运行器、隐藏在 shell 脚本中的测试（bash run_tests.sh），或不符合匹配模式的特殊调用，都可能绕过第 2 层。模式列表可以扩展；但无法声称其完整无缺。这正是第 3 层存在的原因：任何绕过检测的情况仍会被记录为未认证的里程碑。
• 绕过模式取决于环境。 在 --dangerously-skip-permissions 下钩子是否会触发，各方说法不一，也可能因 Claude Code 版本而异。对于 keel 针对其加固的配置，它确实仍会触发——但请在自己的机器上进行测试，不要盲目信任。无论如何，第 3 层都会将绕过情况捕捉为 no_verify。
• lock_tests 按惯例是由人工执行的操作。 没有任何机制能阻止 Agent 调用它——但若调用它来掩盖被篡改的测试，这会显示在跟踪记录中。请留意作弊警报；在检查点查看 git diff。

这些都不会破坏 keel。它们只是明确划定了证明机制的边界：它会认证自己见证的内容，并让其余情况清晰可见。

---

许可证

MIT — 参见 LICENSE。© 2026 Tristan Dalban Moreynas。