Bonsai
文档目录
概念
文档

自动推进

Issue 类型 的 Automation 表写的是「到了这个状态派谁」。自动推进就是照这张表办事的那一部分：你不用每一步都点「按流程派发」，issue 一进到轮到 agent 的状态，Bonsai 就把那一行的角色派到你的电脑上；角色做完，issue 被交到下一个状态，再派下一个。直到它到了 Your turn，停下来等你。

开始之前

自动推进要三样东西，缺一样它就不会动：

  • 类型笔记：issue 的 type: 对得上 7_Self/_Templates/Issue/ 里的一篇类型笔记，那里面要有 Automation 表。在账户菜单的「Issue 类型」页面点「用内置模版建类型」就有 Goal、Feature、Bug、Task 四种。
  • 角色笔记：Automation 表里 action 写的每个名字，都要在 7_Self/_Agents/ 里有一篇。一篇都没有时，issue 页的派发区会提示「还没有角色」，点「用内置模版建角色」就建出 writer、reviewer、deployer、distill 四个。这两个文件夹只有你在网页上能写，AI 建不了。
  • 执行端：一台连上的电脑，上面有这个项目的仓库。个人空间能用它上面的全部项目；别的空间要先在执行端页面上为那个空间启用它。

什么时候会派

只有两件事会让 Bonsai 看一眼要不要派下一步：

  1. 你改了状态：在看板上拖卡片、在 issue 页改状态，或者回答了一个决定。
  2. 一个 run 结束了：执行端报告这篇 issue 上的 run 已经停下。

每次看的规则都一样：

  • 这篇 issue 还有 run 没结束 → 不动。同一篇 issue 同一时间只有一个 run，因为两个 agent 不能同时写一个工作区。
  • 现在的状态轮到 agent，而且 Automation 表里有它这一行 → 派那一行的角色。
  • 你刚把 issue 拨进 Closed 里有一行的状态（比如 Done 派 distill）→ 派它，把值得留下的写回项目笔记。
  • 别的情况（Todo、Your turn、没有那一行、没有类型笔记）→ 不动，等人。

在网页上改状态（看板卡片，或 issue 页顶部的字段）会马上按上面的规则看一次。在对话里让 AI 用 update_issue 改状态，不会触发派发。批准、交回这类事只认你在网页上的那一下。

做完、做歪、做不完

一个 run 结束后，Bonsai 只看结果状态，不判断写得好不好：

run 的结果接下来
做完了，把 issue 交到了这一行 next 里的某个状态照新状态的规则继续：轮到 agent 就再派，轮到你就停
做完了，但 issue 还停在原来的状态交给人：issue 挪到 Needs Decision，Log 里记一行原因
做完了，但把 issue 挪到了 next 之外的 agent 状态同上，交给人
这一步已经派到了 limit 轮同上，交给人决定还要不要再来
失败了，或者被停掉原地不动。收件箱 里会出现一张「Run 失败」卡，点「重新派发」再来一次

「交给人」挪到的是这个类型 Your turn 里叫 Needs Decision 的状态，没有就找 Needs Human，再没有就用 Your turn 的第一个。原因写在 issue ## Log 的最后一行。这一行是 Bonsai 替你写进 issue 的，所以它和 AI 的其他改动一样，摘要会出现在 issue 顶上和 收件箱 的「值得知道」里，等你点「知道了」。

自动派和你手动点「按流程派发」走的是同一条路：同样的角色、同样的轮数计数，run 记录里看得出是谁派的。

Goal 带着子 issue 走

一个 Goal 下面挂着若干子 issue（子 issue 的 front matter 写着 goal: <Goal 的编号>）。Goal 自己不写代码，自动推进替它做三件事：

  1. 批准之后开工。 Goal 离开它类型的第一个状态（内置 Goal 是从 Draft 到 Approved），就算批准了。Goal 随即挪到 In Progress。
  2. 开工没被挡着的子 issue。 Todo 里的子 issue，blocked_by 列出的 issue 都已关闭，就挪到它类型的第一个 agent 状态（Feature 是 Developing），并派出角色。按编号从小往大，同时最多 max_parallel 个子 issue 轮到 agent，默认 2 个。之后每有一个子 issue 往前走，Bonsai 就再看一遍还能不能多开一个。
  3. 子 issue 全关了，Goal 也关。 Goal 挪到它的第一个 Closed 状态（Done）。

几条细节：

  • 停在叫 Blocked 的状态里的子 issue，表示被项目外的事挡着，自动推进不会替你拨走它。
  • blocked_by 写成逗号分隔的编号：blocked_by: 21, 22。指向一篇找不到的 issue，就当它还挡着。
  • max_parallel 写在项目 Issues/Issues.md 的 Settings 表里：
## Settings

| key | value |
| --- | --- |
| max_parallel | 3 |

怎么把一个 Goal 拆成子 issue，见 Planner。

人在哪里插手

自动推进只在 agent 的回合里往前走。它不会：

  • 替你批准一个 Goal；
  • 把 issue 从 Your turn 挪走（审 PR、验收 staging、拿主意都是你的）；
  • 把 issue 改成 Canceled 或 Duplicate；
  • 在 run 失败后自己重试。

这些都会以一条事项出现在 收件箱 里，或者直接留在看板最左边的 Your turn 那一列。