Issue 类型

在 Bonsai 里，项目的 issue 也是笔记，放在 <项目>/Issues/<编号>.md。看板上每张卡片就是这样一篇笔记。

一篇 issue 要经过哪些状态，到了某个状态该谁动手，新建时正文长什么样，这些不写在每篇 issue 里，而是由它的类型决定。一种类型就是一篇普通的 Markdown 笔记。你读得懂，AI 也照着它做。

现在能用到哪一步。 账户菜单里的「Issue 类型」页面管理你的类型：改状态，给 Agent’s turn 的每个状态选角色、执行端、next 和轮数上限，也能一键用内置模版建出 Goal、Feature、Bug、Task。issue 一进到轮到 agent 的状态，Bonsai 就按这张表把角色派到你自己的电脑上，做完交到下一步，见 自动推进。issue 页上的「按流程派发」仍然可以手动派一次。

三篇笔记，各管一件事

issue 因此很轻。它只记事实，不记「这次用哪个模型」「派到哪台机器」。想换模型，改角色笔记；想改流程，改类型笔记。所有同类型的 issue 一起跟着变。

一篇类型笔记长什么样

下面是内置的 Feature 类型，放在 7_Self/_Templates/Issue/Feature.md。文件名 Feature 就是 issue front matter 里 type: 写的那个值。

# Feature

## Workflow

| Todo | Agent's turn | Your turn | Closed |
| --- | --- | --- | --- |
| Backlog, Blocked, Ready | Developing, Reviewing, Revising, Deploying to Staging, Deploying to Production | Review PR, Verify Staging, Needs Decision | Done, Canceled, Duplicate |

## Automation

| state | action | runtime | next | limit |
| --- | --- | --- | --- | --- |
| Developing | writer | | Reviewing | |
| Reviewing | reviewer | | Review PR, Revising | 3 |
| Revising | writer | | Reviewing | |
| Deploying to Staging | deployer | | Verify Staging | |
| Deploying to Production | deployer | | Done | |
| Done | distill | | | |

## Template

## Description

<worker 必读的笔记链接：[[…]]>

### Goal

<要做什么，边界在哪>

...

三个小节，从上往下读。

Workflow：有哪些状态

一张只有一行的表。列头是四个内置的 Turn：Todo、Agent’s turn、Your turn、Closed，说的是这一步球在谁手里。格子里是这一类型在这个 Turn 下的状态，按先后用逗号隔开。

状态名随你起。Bug 的第一步可以叫 Triage，收尾可以叫 Won’t Fix。Turn 是看板对齐不同类型的那根轴：不管状态叫什么，看板都按这四个 Turn 分列，Your turn 在最左边。

Automation：每一步派谁

每一行说的是：issue 到了 state 这个状态，就派 action 这个角色去做。

上面那张表读出来就是：开始开发时派 writer 写代码、开 PR；进了 Reviewing 派 reviewer 审，最多三轮，审过了交给你审 PR，审出问题回到 writer 改。你合并之后，deployer 部署到 staging，等你验收，再部署到 production。完成之后派 distill 把值得留下的东西写回项目笔记。

Agent’s turn 的每个状态有一行；Todo 和 Your turn 的状态不能有行。到了 Your turn，AI 不再往下走，等你。 Closed 的状态可以有一行，比如 Done 派 distill，但它的 next 是空的：收尾之后不再去别处。

表里没有模型这一列。模型写在角色笔记里，因为角色才是「谁来做、怎么做」的那一份说明。

Template：新 issue 从哪里开始

## Template 往下到文末，是这类 issue 新建时的正文骨架。AI 用 create_issue 建一篇 Feature 时，没给正文就用它。这一节在笔记编辑器里改，「Issue 类型」页面只管上面两节。

内置的模版分四节：

• Description：必读笔记的链接、要做什么、为什么现在做，以及可测的验收标准。验收标准是你写给 AI 的 spec：reviewer 逐条对照，AI 不能自己改。
• Decisions：需要你拍板的事。一个决定一个小标题，下面是几个选项，AI 推荐的那个会标出来，最后永远有一个「其他」。你在 issue 页上点一个选项，就是拍板。
• You should know：AI 每次做完写给你的几行交代。值得留到这篇 issue 之后的，标上「值得记住」，distill 会把它写回项目笔记。
• Log：每一轮谁做了什么，只追加不改，review 的每一轮也记在这里。

角色

action 里的名字指向一篇角色笔记，比如 7_Self/_Agents/reviewer.md：

---
harness: codex
model: gpt-5.4
---

# reviewer

你审的是这篇 issue 的 PR。读 issue 和 PR 的 diff，在工作区跑测试，
逐条对照 Acceptance Criteria 给结论并附证据……

标题是角色名，正文就是给 AI 的指示，front matter 可以写用哪个 harness 和模型。Bonsai 内置 writer、reviewer、deployer、distill 四份模版：还没有角色时，在 issue 页的派发区点「用内置模版建角色」。建出来就是你自己的笔记，随便改，也可以再加新的角色。

写代码和审代码可以交给不同的模型，这只是两篇角色笔记里各写一行。

人一直在流程里

类型笔记让 AI 接手重复的步骤，但几件事始终留给你：

• 批准：一个 Goal 拆出来的计划，你批准了才开始。
• 审 PR 和验收：Review PR、Verify Staging 都在 Your turn。AI 写完、审完、部署到 staging，都要停下来等你看过。
• 拿主意：AI 遇到需要你决定的事，把它写进 Decisions，把 issue 改到 Needs Decision。writer 和 reviewer 几轮都谈不拢，到了 limit，这一步也不再派，等你决定。
• 收尾：流程从不替你把 issue 改成 Canceled 或 Duplicate。
• 改规则：类型笔记和角色笔记都在 _ 开头的文件夹里，AI 的任何授权都写不了它们，只有你在网页上能改。

issue 的负责人（owner）是一个人，一直不变；新建时没填，就用项目笔记的 owner。看板卡片上显示的「现在轮到谁」是算出来的：在 Agent’s turn 时是那一行的角色，在 Your turn 时就是负责人。

为什么放在你自己的空间

类型是全局的：你看到的每个项目和领域，不管是你自己的还是别人分享给你的，都按同一套类型来解释 issue。一种类型代表一种固定的做事方式，不该每个项目各抄一份。

它放在 7_Self 里，是因为里面指的东西本来就是你的：action 是你的角色，runtime 是你的电脑。

这也意味着，同一个共享项目里，两个人如果各有一套类型，各自看到的看板会按自己的那套来。

没有类型笔记时

还没建任何类型笔记时，Bonsai 先看项目的 Issues/Issues.md 里有没有 Workflow 表，再没有就用一套内置的默认状态。在「Issue 类型」页面点「用内置模版建类型」，就能建出 Goal、Feature、Bug、Task 四种，建好之后就是普通笔记。

更早写下的类型笔记如果还用 Backlog、Todo、In Progress、Done、Canceled 五列，Bonsai 读的时候会把它们对到四个 Turn 上，不用手改。

侧栏里看不到它们

issue、类型和角色都是当数据用的笔记，各有自己的入口：issue 在看板上，类型在「Issue 类型」页面，角色在 issue 页的派发区。所以左边的笔记树不列出项目和领域的 Issues/ 文件夹，也不列出任何模版，也就是路径里有一段以 _ 开头（7_Self/_Templates/、7_Self/_Agents/）或者文件名是 Template.md 的笔记。搜索和直接链接仍然能打开它们。