Agentflow

把 agent 串成一张能自己跑的图，在要紧的地方留给人拍板。

Agentflow 是什么

一张你画出来的图。每个节点是一个带 prompt 的 agent，或者一个等人拍板的审批节点。每条边是一个条件：前一个节点以什么结果结束。放一个做计划的节点、一个实现的节点、一个 review 的节点，再从 review 连一条边回到实现，用于不合格的时候，你就得到了一个能自己跑的循环。

一次 run 就是把这张图走一遍。它有自己的 worktree 和分支，每一步都提交成一个 checkpoint，你可以旁观、回话、亲手接管，或者从任意节点重跑。

一件事从头到尾

1. GitHub 上开了一个 issue，它成为一条 Task。
2. 一条 agentflow 接手。它的第一个节点监听 task.created，于是一次 run 在新的 worktree 上开始，issue 的正文就是第一条 prompt。
3. agent 们干活。计划节点写出计划；实现节点照着做；review 节点要么放行，要么带着修改意见打回。这条回边最多走三次。
4. 人来批准。审批节点让 run 停下，在节点卡片上放出 Approve 和 Reject。你会收到通知，配对了手机的话手机上也会收到。
5. 开 PR，由最后一个节点来开；你也可以自己按 task 上的 Open a pull request。
6. 你在 Task 页上合并它。issue 关闭，task 自己结束。

任何一步都可以换成你自己来。只用其中几种节点的 flow 也是 flow。

Agentflow 页

侧栏顶上的 Agentflows 打开这一页：左边是 flow 列表，右边铺满画布。

• 每条 flow 是一张卡片，带两颗按钮：电源按钮把它切到 Online 或 Offline，历史按钮把它的 run 记录在下面展开。第二行写着 Online · <project> 和最近一次运行的时间。右键卡片可以删除。
• 点卡片编辑 flow；点一条 run 在同一张画布上观察它。
• 检查器浮在右下角，跟着你选中的东西变：flow 自己的设置、某个节点，或者某条边。窗口太窄时它会收成一颗药丸。
• 编辑不会自动保存。有改动时页头是 Save 和 Revert，没有改动时是 Run once。离开这一页会丢掉未保存的改动。有未保存改动的 flow 不能上线也不能运行，因为 run 用的是已保存的版本，那就不是你眼前看到的东西了。

画布工具栏上的 Chat 打开一场和 agent 的对话，让它替你写 flow。描述你想要什么（它会问目的、入口、怎么拆分工作、在哪里跑），它就把图建出来。这个 agent 属于这条 flow：关掉对话框它会等着，删掉 flow 它也一起走。

Agentflow 只有在 Online 时才会响应事件和定时。新建的 flow 默认 Offline。Offline 的 flow 仍然可以手动运行。

节点

Agent：一段 prompt、由哪个 agent 来跑，以及可选的模型（留空就用那个 agent 上次用的）。它可以声明 outcome，也就是它可能得出的结论，比如 approved 或 needs-work，供边来路由。

节点里的 agent 是真正的 agent，但它的家是 run：它不出现在 AGENTS 列表里，也不开 tab。它的权限请求会自动批准，因为没人盯着它；这是 Kumo 唯一会替人批准的地方，而且是节点决定的，不看模式。提问和计划审阅仍然会让它停在 stuck，直到你回答。

审批：等一个人。产出 approved 或 rejected。

边

一条边说明下一个节点什么时候跑：

一个节点有多条入边，意味着任意一条都能触发它。路由发生在节点这一轮结束时，而不是跑的过程中：它这一轮里发出的所有东西会被收集起来，一次性过一遍出边。

回边指向链路里更早的一个节点。它让那个节点带着上下文再跑一轮，并且有预算，默认三轮；用完时，exhausted 让另一条边来接住。

Run 怎么开始

入口节点是没有正向入边的节点。一次 run 有四种开始方式：

• 手动：页头的 Run once，触发所有入口节点。
• 定时：在入口节点上写一行 cron。
• 事件：入口节点监听某个 topic。task.created、task.updated、task.done 和 task.deleted 来自 Task，其中 task.updated 还能限定阶段（task 进入 ready 时开始）或限定改了什么。GitHub 事件（github.issue.opened、github.pr.merged……）和 agent emit 的任何事件也都可以。flow 只听得到自己 project 里的事件。
• 从 task 启动：Task 页或 Task 面板上的 Run flow ▾。Offline 时也能用，因为是你按的。

一条 task，一次 run。如果这条 flow 已经有某条 task 的 run 还在跑，同一条 task 的新事件会先等着，等那次 run 结束后再重新考虑，而不是在上面再叠一次 run。Run flow 会提示 That task is already running in this flow.

从 task 启动的 run，task 名下已有 Workspace 就在它上面跑，没有就在 task 名下新建一个。

Run 在哪里干活

在 flow 自己的设置里定：

• Worktree（常用）：每次 run 新建一个 worktree 和分支，kumo/run-<id>。
• 固定目录：每次 run 都在你选定的一个目录里，一次一个。对于根本不涉及仓库的 flow，托管 project 是个好去处。

默认一条 flow 最多同时跑三次 run，多的排队。一次 run 总共最多执行 50 个节点；超出时节点显示 blocked，而不是悄悄消失。

扇出与汇合

如果一个节点在一条边上产出了多个匹配的结果（比如一个排查节点找到三个 bug），run 就会扇出：每个结果在自己的 worktree 分支上开一条链路，下一个节点按链路各跑一次。节点卡片上显示 ×3 和一行 2 done · 1 running 这样的统计。

选中一个节点，检查器会按链路列出它的每次执行：状态、为什么被阻塞，以及每条链路的 Approve / Reject、Cancel 和 Rerun。取消一条链路，其他的照常跑。一条 joined 边会等整次扇出全部完成，并拿到每条链路的结果。

真正相互独立的工作，更好的做法是拆成几条 task（kumo task new），让每条各自有一次 run。

观察一次 run

在历史里点一条 run。正在跑的节点在画布上呼吸，通向它的边会脉动。什么都不选时，检查器是这次 run 的时间线，按节点分段。选中一个节点就能读它的对话；如果它是 stuck，就在那里回答它，它会接着跑。审批节点的按钮直接长在卡片上。run 进行中时，页头有 Cancel run。

失败的节点如果有 on: failed 的边接着，就算处理过了。没人接住的失败会让整次 run 失败并发出通知。stuck 不算失败。

Checkpoint 与重跑

run 开始时会复制一份 flow 定义，所以之后再改 flow 不会影响正在跑的 run。每个节点这一轮结束时都有一次提交，[kumo] checkpoint after <node>，所以你可以 Rerun from a node…：目录重置到那个节点开始时的提交，run 从那里接着跑。还没结束的 run 会就地重跑那条链路。

一次 run 如果没产出任何 checkpoint、工作区也是干净的，结束时会连 worktree 带分支一起清掉，所以每半小时检查一次的 flow 不会把 ~/worktrees 堆满。

亲手接管

run 卡住了，或者你想自己来下一步时，run 页上的 Open in project 会把这次 run 的目录变成树上一个普通的 Workspace。什么都不复制。board 顶上会出现一条横幅，写着这是哪条 flow 的哪次 run、现在什么状态；有节点在等你时带一颗 Reply ›。run 还在跑的话，你的改动会进到它的下一个 checkpoint。

从那以后目录归你。run 结束时 Kumo 不会把它清掉，有未提交改动时 Rerun from a node… 也会拒绝重置它。

你在那里开的 agent 都是普通 agent。它们可以跑 kumo run，看这个目录属于哪条 flow 的哪次 run、哪个节点卡住了、每一步做了什么。

给 agent 用的

kumo emit <topic> 发出一个 flow 可以监听的事件。kumo flow list / get / put 读写 flow 定义（Chat 里那个 agent 就是这样建图的）。kumo run 打印当前目录所属的那次 run。见多 agent 协作。