---
title: "Holon 的 WorkItem 架构：把工作状态从对话中分离"
summary: "从新版接口上线到旧版下线，解释 WorkItem 与 Goal、Loop 的侧重点：把跨发布周期的目标、进度、外部依赖和交付归入一项持续负责的工作。"
order: 20
---
# Holon 的 WorkItem 架构：把工作状态从对话中分离
> 文中的接口迁移与双 PR 流程是设计示例，不是真实运行记录。
## 河水流过，工作留下什么
把 LLM 不断读入和生成的 token 想成一条河。问题、推理、命令输出和修正意见依次流过；其中有些只在当时有用，有些决定了下一步还能不能做对。
对需要等待别人推进的工作，这个问题尤其明显。以负责代码审阅的 Agent（下文称 reviewer）为例：它读完几千行 diff，发现了权限检查缺失，接下来要等作者修复。在此期间，它还会审阅其他 PR。等原来的 PR 更新时，最初的分析可能已不在模型的上下文窗口里。即使聊天记录还在，也不适合每次都从头读一遍。
WorkItem 像漂在河上的一条船。值得留下的东西需要被打捞上来：这次审阅的范围、发现的问题、对应的提交、还缺什么证据，以及什么时候回来。河水继续流，承载这项工作的记录仍然在。
下次回来，Agent 需要知道这项工作做到哪里，并找到继续审阅所需的材料。一轮执行结束后，系统该怎样保留这些依据，又在什么时候安排它继续？
## 从持续执行到跨周期负责
这不是 Holon 独有的问题。业界已经从几个方向探索怎样让 Agent 不止回答一次，而是把事情继续做下去。
**Ralph Loop：没有达到完成条件，就继续迭代。** 以 Claude Code 的 Ralph Wiggum 插件为例，它在 Agent 尝试结束时重新送入任务提示，让 Agent 根据已经修改的文件和测试结果再做一轮。完成条件和迭代上限约束这个循环。它适合“实现、测试、修正”这类可以接连推进的工作。[1]
**Codex Goal：让目标在一轮结束后仍然有效。** Codex 的 Goal 扩展把目标作为可持久保存的线程级状态，并结合预算约束，在空闲时判断是否继续推进。目标不再只是一条早先的用户消息，而成为后续执行的依据。这里讨论的是所查源码中的机制，不把它等同于所有版本默认开放的产品入口。[2]
**Claude Code `/loop`：隔一段时间，再检查一次。** 这条路径适合跟进部署、构建或 PR：把检查交给调度，不必每次都由人提醒。它与 Ralph 的连续迭代不同，重点是何时再次执行；官方文档也区分了会话内循环、事件接入和独立于会话的调度方式。[3]
这些机制帮助 Agent 在一轮之后继续推进。但有些工作的下一步，并不取决于 Agent 能不能再试一次。
### 代码写完了，接口迁移还没结束
假设你把一项接口迁移交给 Agent：开发新版接口，跟进服务端发布和客户端升级，直到旧版接口可以按约定下线。验收目标是完成迁移，而不只是提交一份通过测试的代码。
- **开发新版接口。** Agent 修改实现、运行测试、修正问题。这一阶段可以靠连续迭代推进。
- **等待服务端发布。** 代码已合并，但发布窗口还没到。Agent 留下待发布的版本、验证结果和发布后的检查项，转去处理其他工作；收到发布通知后，再确认新版接口已可用。
- **跟进客户端升级。** 服务端上线后，客户端团队还要适配、发布，用户也需要时间升级。Agent 保留各客户端的迁移进度和未满足的条件，在版本发布或约定的回查时间到来时继续跟进。
- **确认旧版下线。** 到达约定的观察期后，核对旧版调用情况、迁移验收标准和下线批准，再按授权执行或交付下线建议。客户端发了新版，并不等于所有调用方都已迁走。
这项工作可能跨越数周，包含多次执行，也包含长时间没有可执行动作的等待。多跑几轮模型，既不能让发布窗口提前，也不能代替客户端团队完成升级。只保留“完成接口迁移”这个目标，又不足以说明每个阶段已经验证了什么、还依赖谁、下一次应该在什么条件下回来。
定时 Loop 可以承担其中的回查。但要把整个迁移过程托付出去，还需要保存阶段进度、关联外部事件、区分等待与完成，并在回来时找到对应的工作。**WorkItem 把这些信息组织成一项独立于单轮执行的持久工作，由运行时管理它的等待、恢复和完成。**
在这个例子中，需要接好发布通知和升级状态查询，并约定回查时间。等待期间，迁移工作仍然存在，同一个 Agent 可以处理别的委托；恢复时，它沿着原来的目标和记录继续，不必让用户重新说明“我们还在等哪一个客户端”。
因此，Loop 主要安排如何反复执行，Goal 保留要追求的目标，WorkItem 则承载一项工作从接受委托到验收交付的生命周期。实现与测试阶段可以用 Loop，整项迁移始终有目标，而各阶段的进度、依赖和交付都归到这项工作上。
## 把负责人、工作和每次执行拆开
接着用代码审阅来说明这三者的关系。先看负责人：在 Holon 中，每个 Agent 都有独立的 AgentHome，保存自己的职责约定、记忆和材料。其中的 `AGENTS.md` 记录长期角色：负责什么、遵循哪些工作原则，以及已有授权的边界。
对 reviewer 来说，这些约定可以是检查代码风险、依据测试和修改记录给出结论，以及在什么情况下需要人工确认。它们不会随着某个 PR 的结束而失效。
在这个长期角色之下，再交给它一项具体委托：审阅一个 PR，跟进修订与 CI，满足约定条件后交付结论。如果事先授予了合并权限，合并也可以属于这项委托。
这个 PR 结束后，reviewer 还会接手下一项审阅；对应的 WorkItem 则在交付后结束。一项 WorkItem 可以经过多轮执行：先读 diff，等待修订，再复查代码和测试结果。
测试进程结束，不等于审阅完成；Agent 本轮停止，也不等于可以放下这项委托。只有约定的目标已经验收，工作才应结束。
一个 WorkItem 需要让后续执行能够回答四个问题：
| 问题 | 审阅中的例子 |
| --- | --- |
| 要交付什么？ | 检查指定 PR，并按授权范围给出结论或完成合并 |
| 做到哪里了？ | 已检查鉴权路径，发现导出接口缺少权限检查 |
| 下一步为什么还不能做？ | 等作者提交修订，或等当前提交的 CI 结果 |
| 回来后从哪里接上？ | 读取审阅记录，核对新提交，复查原问题 |
这些信息不必塞进同一个文件，更不必复制整段聊天和全部日志。关键是它们归属于同一项工作，并能在恢复时找到。
粒度也由此确定：另一个 PR 有独立的审阅目标，适合另建工作项；“再读一个文件”只是当前工作的一个动作。本轮就能回答的问题或完成的小修改，通常不需要额外建立 WorkItem。
## 模型判断下一步，运行时记住如何继续
如果 Agent 只在回复里说“等作者修好后再看”，人能理解，系统却未必知道何时再安排执行。Agent 需要向运行时登记：哪项工作在等什么，什么条件下可以继续。
*图 1：工作记录跨轮保留。下方是等待后的恢复路径；能继续的工作不必先等外部信号。*
Agent 理解目标、分析证据，决定还需要做什么；运行时保存工作状态，依据等待条件和到达的信号安排后续执行。再次运行时，Agent 读取记录，重新核对事实。
**工作还没完成，不代表现在就应该运行。** 等 CI 的工作仍然有效，但在结果到来之前，重复调用模型未必有用。同样，打开一个工作项查看进度，不应自动解除它的等待。
**收到信号，也不代表目标已经达成。** 新提交通知只说明值得复查，不说明权限问题已修好。什么时候可以回来，由等待与调度机制处理；回来后是否满足验收条件，仍要由 Agent 根据证据判断。
## 按工作记录恢复上下文
假设 reviewer 最近一直在处理 PR #102，此时 PR #101 更新了。只读取最近几轮对话，就容易带回 #102 的细节，反而漏掉 #101 尚未解决的权限问题。
恢复 #101 时，Agent 先读这项 WorkItem 的记录，确认目标、授权和未解决的问题，再按需取回相关证据。一次审阅留下的记录可以很短：
> **目标**：跟进 PR #101，按约定条件完成审阅与交付。
>
> **进度**：已检查接口入口和鉴权路径；导出接口缺少租户权限检查。
>
> **依据**：已审提交、对应评论，以及回归测试结果。
>
> **回来后**：查询最新提交，复查增量和原权限问题，再确认检查结果。
Agent 把关键发现和材料的查找入口写进记录，完整 diff、日志和测试报告按需读取。记录还要说明哪些判断仍然有效、哪些事实必须重查：旧提交的测试通过，不能代替新提交的验证。
## 一个 reviewer，两个交错的 PR
每个 PR 对应一个 WorkItem：A 负责 PR #101 的审阅，B 负责 PR #102 的审阅。假设已经接好 PR 更新通知和测试结果，下图展示其中一种处理顺序。
*图 2：同一个 reviewer 在 A、B 之间切换。上方是唤醒事件，下方是各项工作的等待记录。*
reviewer 通过选择或切换 WorkItem（`PickWorkItem`）确定当前工作焦点，即 current WorkItem；运行时也可以在唤醒时选择可继续的工作。**当前 WorkItem 表示聚焦哪项工作，不等于这项工作正在运行**：它也可能处于等待中。切换焦点不会清除另一项工作的进度与等待条件。
### A 等修订，Agent 先处理 B
reviewer 在 A 中发现权限问题，写下发现与复查入口，登记等待作者修订。A 还没有完成，但暂时没有下一步可做。此时 reviewer 可以接手 B，不必守在 A 的对话里反复确认“是否有新提交”。
### A 有更新，不等于丢下 B
处理 B 期间，A 的更新通知到了。在这个例子中，reviewer 先完成 B 当前这段分析，启动测试并保存进度，再等待 B 的测试结果。调度条件允许后，它回到 A。
A 和 B 的等待各自归属自己的工作：A 等的是修订，B 等的是测试。A 的通知不会替 B 结束测试等待，切换工作也不会把 B 自动标成完成。
这里的并发首先是同一个 Agent 持有多项未完成工作。外部 CI 或后台测试可以并行进行，不意味着同一个 Agent 同时运行两个模型轮次。
### 回到 A，重新核对，再交付
reviewer 读取 A 的记录，查询当前提交，复查原问题并核对 CI。如果条件仍未满足，就更新记录，继续等待；如果已经满足，就按委托范围交付。事先授权了合并的，可以在复核通过后合并；没有这项授权的，交付审阅结论即可。
A 结束后，B 的记录和等待仍然存在。等 B 的测试结果到达，再恢复 B。
## 完成要有交付，继续要有依据
一项工作的结束，应该同时回答“目标是否达成”和“交付了什么”。对审阅来说，是检查了哪个提交、问题是否处理、验证结果如何，以及按授权做了什么。只改成“已完成”，不足以让人接手。
如果报告仍然写着“后续继续跟进”，就需要检查原目标是否真的结束。尚未履行的责任，应当保留在未完成的工作中，或有明确的后续安排。
每次恢复，Agent 都要核对当前版本和外部进度，更新已经变化的计划；对可能漏掉的通知，安排回查。交付时，把验收依据、结果和仍需处理的事项写清楚，让接手的人能判断这项委托是否已经完成。
---
### 资料与继续阅读
业界探索按 2026-09-12 查阅的资料概括，聚焦机制，不作完整产品能力比较：
1. [Ralph Wiggum 插件说明](https://github.com/anthropics/claude-code/blob/main/plugins/ralph-wiggum/README.md)：停止时继续迭代、完成条件与迭代上限。
2. [Codex Goal 扩展源码](https://github.com/openai/codex/tree/95637f7056835fea66bdd0044414af480fc0fd74/codex-rs/ext/goal)：以固定提交为依据，说明线程级目标、持久记录与空闲续跑。
3. [Claude Code 定时任务文档](https://code.claude.com/docs/en/scheduled-tasks)：`/loop`、会话范围与其他调度方式。
Holon 的具体接口与行为见[工作项契约](/spec/work-items)和[等待与唤醒](/spec/wake-and-continuation)。下一篇[一个 PR，一个工作项](./one-pr-one-work-item)转向 reviewer 的实际配置与操作流程。