Beans 与待办事项
TR
本页面生成自 content/docs/beans-and-todos/ — 下方每个小节都链接至其自身的源文件。
✎ Edit TR
Beans 是给智能体用的。待办事项（todos）是给人用的。 它们在日常用语中借用了同一个词，除此以外别无共同之处；将二者混为一谈，就会导致工作计划中混杂了两种需要不同处理方式的事物。
bean 是智能体在执行工作时维护的过程状态：在开始前先认领，以避免同胞会话（sibling session）重复处理；随着工作的推进保持最新状态；并在关闭时记录下所做的变更。存储位置为 beans/，已提交至版本控制，因此即使容器被回收也能留存下来，并且对所有其他会话均可见。
待办事项（todo） 则是人类个人的备忘提醒——即他们接下来打算查看的内容。创建、重新排序和舍弃完全由他们自行决定，依照其自定的节奏进行，智能体的任何流程都不应擅自决定它何时完成。
本页面对前者作了全面阐述。后者尚未构建，页面中也明确标明了这一点。
共用同一个词的两件事物
✎ Edit TR
这种区别并非仅仅是术语层面的。两者有着不同的所有者、不同的生命周期以及不同的失效模式。
| Bean | 待办事项（Todo） | |
|---|---|---|
| 所有者 | 智能体会话 | 个人 |
| 目的 | 进行中工作的过程状态 | 意图的备忘提醒 |
| 存储位置 | beans/，已提交且共享 | 尚未定义 |
| 创建者 | 智能体，在经过精确标题检查后创建 | 个人，随时随地 |
| 关闭者 | 完成该工作的智能体，附带摘要 | 个人，依自身判断 |
| 可见范围 | 所有同胞会话 | 主要是个人 |
| 失效模式 | 重复创建，或被错误的会话关闭 | 被遗忘 |
正是不同的失效模式使得保持这种划分极具价值。 重复的 bean 会使工作计划丧失有效信号——在某个 folio 中，一次未加防范的重复运行产生了 14,688 个重复项，占该仓库所有未关闭 bean 的 92%。而被遗忘的待办事项只会给一个人带来不便。为前者量身打造的机制用在后者身上就是多余的繁文缛节，而为后者设计的机制用于前者则远远不够。
智能体 bean 生命周期
✎ Edit TR
上面的图表展示了整个周期，其中有三条路径尤为值得细读。
第一步是搜索，而不是创建。 beans create 并不是幂等的：它在每次调用时都会生成一个全新的标识符，且不做任何去重处理；因此重新进入某个步骤会导致工作计划中产生重复项，而不是什么都不做。精确标题检查正是阻隔在重复的工作流步骤与海量近乎相同的 bean 之间的防线。
所有权是一个网关，而不是一种礼节。 另一个会话已认领的 bean 绝不由你来解决、废弃或删除。认领机制是为了避免两个会话拾取同一个事项；而关闭属于他人的事项，则会导致其中一个会话丢失尚未汇报完毕的工作成果。
“已阻塞”并不等同于“不需要”。 一个被阻塞的 bean 会退回到 todo 状态，同时记录其阻塞因素并说明解除阻塞所需的条件。将它留在 in-progress 状态比这两种情况都要糟糕：一个无人推进的事项在所有其他会话看来，都显示为正在活跃进行的工作。
Bean 绝不删除
✎ Edit TR
CLI 中存在 beans delete 命令。请勿使用它。
最终证明不需要的工作应被废弃——即 status: scrapped，并附带一个章节说明原因。这就是此处“禁用”的含义；CLI 中没有 disabled 状态，其词汇体系仅包含 draft、todo、in-progress、completed、scrapped。
这样做的原因并非出于洁癖。一个被废弃的 bean 记录了某件事曾被考虑过但被否决，以及否决的依据——这对下一个智能体而言，与已完成工作的记录同样宝贵，因为正是它阻止了再次走入相同的死胡同。被删除的 bean 会让同胞会话无法分辨这是故意放弃还是意外遗失，并使下一个智能体完全有可能重新做一遍你已经排除的事情。
这条禁令之所以写在这里以及流程图自身的文档中，恰恰是因为工具提供了该操作。依赖于没人注意到某条命令的规则根本称不上规则。
引擎操作不是 CLI 调用
✎ Edit TR
有两种不同的机制可以修改 bean，如果某个步骤混淆了它们，就会宣称产生其实际并不具备的效果。
工作流引擎会在标有 <cat-harness.processes:bean op="…"/> 的步骤完成时，对流程实例自身的 bean 执行 claim、note 和 resolve。claim 会设置 in-progress 状态且是幂等的；note 用于追加记录；resolve 则仅在实例本身完成后才会完成该 bean，因为工作是否完成是一种主观判断，bean 绝不能单凭他人的说辞就被关闭。
智能体则通过 beans CLI 完成所有其他操作：创建、废弃、重命名标题、设置阻塞因素。引擎对这些操作概不支持。
这绝非凭空假设的区别。CRDM 图中的某个活动曾带有 <cat-harness.processes:bean action="create"/>——引擎读取的是 op，而它写的却是 action——因此被解析为根本没有任何操作。该步骤声称签发会生成 bean，实际上什么都没执行，并且在有人查阅解析器代码之前一直静默无声。
当你添加带有 bean 标记的步骤时，请使用引擎实现的这三种操作之一，并在该步骤的文档中说明哪些部分是智能体自身的 CLI 调用。bun run cat check:workflow-refs 能够捕获无法解析的技能引用；但它无法捕获一个引擎从未读取、看似合理的属性。
人类待办事项——尚未构建
✎ Edit TR
尚未构建，在此明确说明，而不是留下一片空白等待别人去发觉。
人类的待办事项需要其自身的生命周期，而目前这一切尚不存在：
- 何时展示待办事项。 在每次对话轮次中呈现所有未完成事项是噪音；一个都不呈现则会导致清单无人问津。无论未来的规则是什么，它都不同于智能体在会话启动时获得的工作计划引导。
- 人类何时可以创建待办事项，以及通过何种方式创建——聊天、命令、还是会话启动界面。
- 如何注销待办事项。 某人放弃一个备忘提醒是很平常的事，不需要填写“废弃原因”章节；bean 的规则并不适用于此。
在完成相关设计之前，切勿将 beans 挪用于此目的。 对于一个只想随意丢弃且无需繁文缛节的提醒而言，一个条目必须由会话认领、在关闭时附带变更摘要且绝不删除的存储机制完全不合身——并且将二者混在一起会向智能体工作计划中注入任何智能体都不应介入的事项。
工作计划当前包含的内容
✎ Edit QA TR
本页面的其余部分阐述了 bean 是什么。本节则说明了存储区当前包含的内容——实时读取自 /assets/beans/index.json，即 gen-docs-pages.ts 在每次构建时从 beans/defs/ 生成的投影，与其早已发布的 todo 索引并列。
在 2026-09-20 之前，这里无物可放。todos/ 拥有读取器、公开发布的索引以及基于它的看板；而 beans/ 这三者皆无，尽管后者的存储规模要大上两个数量级。一个无人能查阅的工作计划，就是一个无人会去核验的计划。
仪表盘展示的内容，以及为何每个面板呈现在其当前形态。 计数是核心概要，因此直接以数字呈现，而不是用四根表达相同含义的柱状图。史诗（epic）分布展示的是带有长名称的各个标识的量级，因此采用横向条形图。发现项只有三四行，因此采用列表形式——每一行都带有图标和标签，因为仅凭状态颜色永远无法独自传达含义。
各项发现仅根据已提交的数据计算得出，且其中特意缺少了一项。 陈旧的 in-progress 检测器必须读取时钟，而投影受精确内容的门禁控制——任何根据时钟计算的内容都会在每次构建时更改文件，从而导致陈旧度门禁永久触发。因此，投影仅将每个 bean 的 updated_at 作为事实发布，并在你打开页面时由页面计算其存在时长。这样一来，时长随时间推移而变化，却无需文件发生变动，这才是合理的运作方式。
这里还提供了更完整的视图，且可供浏览。 每个已声明的状态图都会在当前实例用于该图的路径下拥有专属的可视化器——/beans/、/todos/ 以及其他每个状态图各自对应的路径。该路由并非本页面的凭空创造：bean o7eq 记录了所有者的裁定，即渲染后的资产应以其实例的名称加上已声明的图作为路径段来寻址，而当前实例省略了自身的名称，因为本站提供的正是其 docs/ 内容，且 harness-requirements 技能将该精确 URL 规定为必须履行的义务——“要求它们提供可在 <base-url>/beans 访问的可视化器”。在它们之上没有上级索引，因为 / 归文档站点所有，所以每个页面都会列出其同胞页面。
未提供投影的图会明确说明这一点。 qa、health、issue-marks 和 uploads 都是已声明的状态图，但目前尚无任何机制为它们发布投影。它们的仪表盘会如实说明此情况并指出 bean 2krx，而不是为一个无人读取的存储区渲染一堆零——打开时显示为零的仪表盘与一个空无一物的存储区无法区分，而这二者是完全相反的事实。
这些页面上的每个标识符都是一个链接。 bean id 解析为该 bean 的文件，issue 或 pull request 编号解析为代码托管平台（forge），每条发现项都带有铅笔图标，指向实际进行写入的地方。无法解析的引用则保持为纯文本，这构成了“顺此追踪”与“此项指向了我无法到达之处”之间的显式区别。
此处尚未包含的内容。 即 bean 在 BPMN 流程中所处的位置，这是 bean v49e 的另一半。该关联需要 beans/workflows/（即声明的 workflow-state 图），而它目前是空的——因此位置视图会为存储区中的每个 bean 报告“无处所在”。它正等待实例状态的建立。
实时工作计划仪表盘需要 JavaScript。其读取的投影是 一个纯 JSON 文件，可以直接读取。