BuddingPlanted Tended 8 min read

kiln-orca 怎么让 Orca 里的 Agent 干 Kiln 的活

读 Kiln 的 AI 执行节点连接器 kiln-orca 的源码:它怎样从 Server 领任务、在 Orca 里启动 Codex 或 Claude Code、按每次 git 传输申请和吊销凭据,以及怎样靠 journal 在崩溃后接着做。

English version: How kiln-orca runs Kiln's work through agents in Orca · 前一篇:Kiln 怎么把一个 Issue 自动变成一次发布

上一篇讲了 Kiln 的整条自动化链:Issue 被 AI 开发、被另一个 Agent 审计,然后合并、打 tag、发布。那篇里 AI 的部分只说到「Server 把任务派给 AI 执行节点」。这篇往下看一层:执行节点上发生了什么,Kiln 怎么让 Orca 里的编程 Agent 替它干活,又怎么防它乱来。

读的是 kilnflow.dev 的 kiln-orca/ 目录(TypeScript,约 1.15 万行源码),commit e3bff51。只读源码和测试,没有安装,也没有运行;Orca 本身不开源,我只看了连接器怎么调用它的命令行,以及测试里录下的 Orca 输出。下文路径都相对于 kiln-orca/src/。

一句话:kiln-orca 是一个常驻的用户服务,夹在 Kiln Server 和 Orca 之间。它从 Server 领任务、在 Orca 里开一个一次性的工作区启动 Agent、把每一步写进本地 journal 以便崩溃后接着做;Agent 能做的事只有通过 kiln-orca task 命令问它,git 凭据也是它按每一次传输向 Server 要来、用完就还。

三方各管什么

Kiln Server派任务 · 发凭据 · 收结果
airunner.v2 长轮询
kiln-orca常驻用户服务
Orca 命令行
Orca工作区 · 终端 · 编排
Orca 启动 Agent
Codex / Claude Code在一次性的工作区里干活
↺ Agent 只经 kiln-orca task 回头找连接器(本机 unix socket)
连接器不自己跑 Agent,也不让 Agent 直接联系 Server:所有往外的请求都经过它。

Orca 是一个桌面应用,管 Agent 的工作区(git worktree)、终端和编排(run、dispatch、worker)。Orca 内部怎么分工、要不要拆子 Agent,是它自己的事,Kiln 不管。

kiln-orca 以 macOS LaunchAgent 或 Linux systemd --user 服务运行,一个数据目录就是一个节点。节点注册时用的令牌决定它是审计节点还是开发节点;一台装了 Codex 和 Claude Code 的机器可以同时注册两个节点,各用一个数据目录。

一个任务在节点上的一生

prepareclone · 工作区 · 工具链 · 测试服务
先记下请求 id
startorca worker-start
Agent 开始干
running等 worker_done · 每 5 秒心跳
Agent 发出 worker_done
finishing推 attempt 分支 · Complete
结果已提交
stopping / releasing停 Agent · 释放终端
都确认了
reclaiming删工作区 · 删 journal
这些阶段名就是 journal 记录里 stage 字段的取值;连接器每进一步先写 journal,重启后按它接着做。

1. 启动:先确认自己能干活,再去领

服务启动时,连接器读注册信息和私钥,拿单实例锁,在数据目录的 run/kiln-orca.sock 上开 socket,然后逐项检查:Orca 是否打开、版本是否不低于 1.4.258,Docker 和 Compose 能不能用,随包的 kiln-runner 能不能准备工具链,journal 能不能写,每个 Agent 的 --version,以及 kiln-task skill 是否已同步进 Agent 的 skill 目录。

这些状态连同协议版本(现在是 10)每次都随 Acquire 报给 Server。容量满了(默认 max_tasks: 2)、本机设了 drain、Orca 没就绪、journal 或 skill 有问题时,节点照样连着,但声明自己不接新任务。读不了的 journal 记录也按占一份容量算,因为里面可能有一个还在 Orca 中运行、连接器却不认识的 Agent。

host/run.ts:132 · core/node.ts:176,473,728 · core/orca.ts:306

2. 准备:clone、工作区、工具链、测试服务

领到任务后,连接器在 repos/<repo id>/<仓库名> 下准备这个仓库的 clone。需要的只读 token 向 Server 要(IssueCredential,带一个 op_id),经环境变量里的 http.<地址>.extraHeader 交给 git,不出现在命令行参数里;clone 完立刻 RevokeCredential。连接器自己的 git 不读全局和系统的 git 配置。

然后把仓库登记到 Orca,在 tasks/<attempt>/ 下写好任务文件(work.json、开发选题时的 candidates.json 等),按仓库的 .kiln/runtimes.lock 调用 kiln-runner toolchain ensure 准备 Go、Node、pnpm,仓库声明了测试服务时用 docker compose up -d --wait 拉起 Postgres 或 Redis。

core/attempt.ts:459,746 · core/git.ts:171,410 · core/credentials.ts:77 · core/toolchain.ts:167 · core/services.ts:305

3. 启动 Agent:绝不启动两次

启动前,连接器先把这次启动的请求 id 写进 journal,然后才调用:

orca orchestration worker-start --worktree new-top-level --name kiln-a<attempt>-e<epoch> --base-branch <commit> --comment kiln:attempt=…;epoch=…;task=…;kind=… --agent <agent> --spec <prompt>

Orca 新建一个顶层工作区、在里面启动 Agent。如果这次调用的结果不明(超时、连接断开),连接器不重试,而是用同一个请求 id 去 request-show 查 Orca 到底启动了没有。查不出来就以 infra.lost 结束,宁可失败也不让同一个任务跑出两个 Agent。工作区的名字和备注带着 attempt 和 epoch,后面回收时靠它们确认「这是我建的」。

core/attempt.ts:864,958 · core/orca.ts:611

4. 跟踪:邮箱、心跳、超时

Agent 结束时会发一条 worker_done。连接器在 Orca 里有一个自己的「邮箱」终端,持续执行 orchestration check --types worker_done,escalation,question,把收到的消息落成文件;Agent 中途提问时给它一个固定的回复,让它按任务说明自己判断。

任务进行中,连接器每 2 秒看一次邮箱,每 30 秒用 worker-show 兜底查一次 Agent 的状态,每 5 秒给 Server 发一次心跳(带上当前阶段)。心跳的回复里可能有取消请求;超过任务时限、和 Server 失联 10 分钟、epoch 已经过期、节点被吊销,都会让连接器停下这个 Agent。连接器自己重启时只是不再跟踪,Agent 在 Orca 里继续跑,重启后从 journal 接上。

core/mailbox.ts:585 · core/attempt.ts:118-123,1000,1358

5. Agent 的唯一入口:kiln-orca task

Agent 拿到的任务说明里有一条形如 node cli.js task --home <数据目录> --attempt <id> 的命令,用法写在随包分发、由连接器同步进 Agent 目录的 kiln-task skill 里。这个命令把请求经 unix socket 交给运行中的连接器,连接器再替它调用 Server。

子命令做什么谁来校验
info任务的基本信息本地
check-report审计:提交前先校验 report.jsonServer 的 ValidateReport;本地只查文件类型和 1 MiB 上限
claim开发:领取选中的 IssueServer 的 ValidateReport + ClaimDevIssues
deliver开发:交付报告Server 校验报告;本地查工作区干净、HEAD 包含交付的 commit、设计阶段只改 Markdown
ci查 PR 或 commit 最新的 CI 结果Server 的 GetVerification
doc读冻结的外部设计文档Server 按任务关系授权
exec用受管理的工具链跑命令,git 经连接器拿凭据见下一节
done结束这一轮:再校验一次,然后在 Agent 自己的进程里向 Orca 发 worker_done连接器

最后一条有个细节:worker_done 由 Agent 的进程发出,身份来自 Orca 给这个会话设置的环境,连接器不冒充 Agent 报结束。

host/socket.ts:295 · core/attempt.ts:1412-1649 · core/done.ts:138

6. task exec:每一次 git 传输一枚 token

Agent 的 git经 task exec 运行
git-remote-https 被换成包装
传输包装先查有没有别的凭据
开一个只读操作
连接器 → Server签发只覆盖这个仓库的 token
✓ 传输结束、连接关闭:立即吊销发现 netrc、extraHeader、URL 里带密码:拒绝这次传输
Agent 和工作区里都没有长期的 git 凭据;每一次 fetch 都单独申请、单独吊销。

task exec -- <命令> 把工具链放到 PATH 最前面,再用 GIT_EXEC_PATH 指向一个镜像目录,其中 git-remote-http(s) 换成了连接器的包装程序,并给任务仓库的主机配上连接器的 credential helper。

每次 git 走 HTTP(S) 时,包装程序先检查这次传输会不会带上别的凭据:地址里有用户名或密码、对这个地址生效的 http.extraHeader、netrc 里出现这个主机或 default,或者这些查不了。有任何一项就拒绝这次传输。都没有时,它经 socket 向连接器开一个只读操作,连接器只在地址正好是任务仓库或声明过的依赖仓库时才向 Server 要 token;连接一断,token 立即吊销。

写权限只在交付时用:连接器自己推 attempt 分支时单独申请一枚写 token,推完就还。Agent 拿不到写凭据。

host/cli.ts:306,365 · core/gitexec.ts:45,109 · core/credentials.ts:246,362 · core/attempt.ts:1468,1490

7. 收尾:先确认结果,再删东西

Agent 结束后,连接器先把结论写进 journal(阶段 finishing)。开发任务交付了的,用写 token 把交付的 commit 推到 kiln/attempt-<id>,再用 ls-remote 确认;没交付的,把现有改动作为 checkpoint 推到同一个分支,下一轮可以换一台机器接着做。然后 Complete,失败就重试,最长 30 分钟。

结果确认之后才清理:停掉测试服务,确认 Agent 已停、终端已释放,经 Orca 删除工作区、检出和本地分支,再核对 Orca、git 和磁盘上都没有了,最后删掉 journal 记录。删除前会核对名字、备注、路径和 git 登记,不是连接器建的一律不动。回收没完成就每分钟重试,12 小时后放弃并在日志里写明怎么手工处理。

core/attempt.ts:1159,1223,1256,1297 · core/git.ts:558 · core/reclaim.ts:185-411

崩溃了怎么办

整套设计的重点在这里。每一个会改变外部状态的动作之前,连接器都先在 journal/<attempt>.json 里记下要做什么:启动请求 id、结论、要不要推送、Complete 的内容。重启后逐条读 journal:

  • 记了 Complete 的,重发;
  • 记了结论还没推送的,重做推送;
  • 停在 stopping、releasing、reclaiming 的,每分钟再试一次;
  • 读不了的记录不跳过、不删除:节点停止接新任务,在日志、doctor 和 Dashboard 上写明哪个文件、什么原因,等人处理。

测试也是按这个思路写的:约 580 个用例,用真实的 git、本地的 git HTTP 服务、真实的 unix socket 和多进程抢锁,还有大量「在某一步中途 epoch 过期 / 进程崩溃」的用例。

读到的问题

没有找到高危问题。值得改的几处,大多只在「Agent 和连接器是同一个用户」这个前提被当成安全边界时才要紧;Kiln 的文档自己也说这些是护栏,不是边界。

问题会怎样在哪
socket 只按 attempt id 区分调用方同时跑两个任务时,一个 Agent 可以冒充另一个任务领凭据、领 Issue、读文档。给任务命令加一个随机的每任务密钥就能补上host/run.ts:202
git 固定 10 分钟超时,clone 是完整 clone大仓库或慢网络下 clone 超时,下一次又从零开始,可能一直 infra.fetchcore/git.ts:50,412
共享 clone 自己的 .git/config 和 hooks 仍然生效上一轮的开发 Agent 留下的代理或 hook,会作用到后面任务里带 token 的 gitcore/git.ts:183
journal、状态文件写入后不 fsync断电后记录可能是空的;空的 journal 会让节点停止接活,直到有人删掉它core/journal.ts:215
clone 路径由 Server 给的仓库名拼出,删除前不检查是否在根目录内只有 Server 出错或被攻破时才会触发;回收代码里已经有这类检查,这里没有core/attempt.ts:428
报告文件超过 1 MiB 时,告诉 Agent 的是「可以稍后重试」Agent 可能反复重试直到超时core/attempt.ts:1534

做得好的地方也很明显:所有子进程都用参数数组启动,没有 shell: true;token 不出现在命令行参数、journal 和日志里,日志只记指纹;外部输入都按 unknown 解析再校验,源码里没有一处 as any;每个外部命令都有超时。