keel-agent:一个带验证契约的 coding agent
前天晚上,把一个折腾了一个多月的个人项目推上了 GitHub。
仓库叫 keel-agent,中文名龙骨。推完时,star 数是 0,fork 数是 0,watcher 是我自己。
首发数据不好看,不过发布前两天补了测试、写了验证记录,也解决了十几个只有真机才会暴露的问题。
coding agent 已经很多了,为什么还要再写一个?因为现有的 agent 不会说「不」。
你让 agent 修个 bug,它改文件、跑命令,然后告诉你已经修复完成。你一跑测试,失败。
模型说完成,和实际完成,差距很大。
交互式场景还能接受,发现问题可以重新修改。但在 CI 里,在自动化代码维护里,这就致命了。流水线需要可靠的信号,口头承诺没有用。
keel 针对这个问题而写。它是一个 coding agent harness,有三个核心约定。
会话即事件流
keel 的会话是一条只能追加的事件日志,一个 jsonl 文件。LLM 的每次请求响应、每次策略判定、每次工具调用、每份验证证据,全部作为带序号的事件写入。对话历史、花费、会话状态都是对这条日志做纯推导得到的视图。上下文压缩只是换视图,日志本身不变。
这条日志衍生出三个命令。replay 只读回放完整执行轨迹,每一步的判定和成本都可见;fork 从任意事件分叉出新会话;cost 按模型按回合生成账单,精确到每次调用。
证据驱动的完成契约
只要会话使用了可能改文件的工具,模型想宣布完成就必须先调用 verify 跑验证,测试或构建通过的证据落盘存档。没有验证就想结束,打回,最多两次。还拿不出证据,以未验证状态结束,退出码 3。
退出码是给 CI 用的。流水线不关心模型说了什么,只看 0 还是 3。
策略先行
所有工具调用先经过声明式策略引擎再执行。路径黑名单拦截 .env 和私钥的读写,命令黑名单、人工审批、只读模式、会话花费超预算自动熔断。每个判定本身也作为事件记录,审计时可以看到每次放行和拒绝的理由。
零运行时依赖
整个项目三千七百行 TypeScript,npm 安装后没有运行时依赖。支持三种线协议,OpenAI、Anthropic、Responses。环境里 export 了哪家的 key 就用哪家,没有 key 的话,KEEL_MOCK=1 可以用内置的确定性 mock 模型跑通全流程。
对比 Apache Maka
前段时间研究了 Apache 孵化器里的 Maka 项目。Apache Maka,孵化中,五千七百颗星,定位是高性能 agent workspace。README 里有句话,保存着它做过的一切事情的完整记录。
它的设计哲学一行字就说完了,The log is the runtime。
日志即运行时。每个模型消息、每次工具调用、每个权限决定、每次终止,都是只能追加的 RuntimeEvent。界面、下一轮 prompt、崩溃恢复都是这条日志的投影。
这和 keel 的思路一致。events.jsonl、纯推导的视图、fork 和 replay,与这个有近五千个 commit 的 Apache 孵化项目的设计相同。两边都认为 agent 运行时的唯一真相源是那条只能追加的日志。
两个独立团队走到同一个设计,说明这个方向有共识,区别在于各自深耕的场景。
差别也很明显。
Maka 是完整的工作区,桌面端、终端、CLI、评测,全部是同一个执行核心的瘦客户端。它证明自己的方式是跑分。README 里说,每一次运行都公开发布,同样的模型、同样的官方验收器、完整的逐任务记录。harness 的好坏因此有了公开的成绩单。
keel 的方向不同。它不想成为工作区,只想确保一次任务的可信完成。证明方式也换了一个,运行时契约。会话的每次完成都必须有当场落盘的验证证据,否则退出码直接告诉 CI 未完成。
后续方向
keel 现在是 0.3.0,仓库里有验证记录,七十六个测试全绿,用 step-5-preview 真实模型把整套流程也跑通过一遍。但文档里明确写着,当前证据只支持受控试运行。自己敢用它跑小任务,不敢放进任何生产流水线。
接下来分两层。
keel 本身有三个方向。一是把完成契约打磨到可以默认开启,fork 之后证据失效、子进程清理这些边界已经补了回归,还需要真实负载检验。二是借鉴 Maka 的评测做法,把 keel 放进公开基准跟同行比。三是用起 fork,CI 重试不必从头开始,可以从失败事件分叉,既省 token,也方便归因。
另一层是 Maka。它是我今年主攻的 Apache 项目,打算从提 PR 做起。keel 对我也是一次练习:自己写过 harness,才清楚崩溃恢复为什么要区分已提交和未提交的日志,fork 为什么不能回滚工作目录,一个退出码背后要处理多少种中断。有了这些经验,给 Maka 提建议会更有针对性。
keel 在 GitHub 上,叫 keel-agent,MIT 协议。零依赖安装,没有 API key 也能试,KEEL_MOCK=1 一个环境变量,事件溯源、验证契约、回放分叉全流程都能体验,不花钱。

