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 要来、用完就还。
三方各管什么
Orca 是一个桌面应用,管 Agent 的工作区(git worktree)、终端和编排(run、dispatch、worker)。Orca 内部怎么分工、要不要拆子 Agent,是它自己的事,Kiln 不管。
kiln-orca 以 macOS LaunchAgent 或 Linux systemd --user 服务运行,一个数据目录就是一个节点。节点注册时用的令牌决定它是审计节点还是开发节点;一台装了 Codex 和 Claude Code 的机器可以同时注册两个节点,各用一个数据目录。
一个任务在节点上的一生
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.json | Server 的 ValidateReport;本地只查文件类型和 1 MiB 上限 |
claim | 开发:领取选中的 Issue | Server 的 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
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.fetch | core/git.ts:50,412 |
共享 clone 自己的 .git/config 和 hooks 仍然生效 | 上一轮的开发 Agent 留下的代理或 hook,会作用到后面任务里带 token 的 git | core/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;每个外部命令都有超时。