多 Agent 协作:委派、进展与定时
协作不是互相反复提及
跳转到“协作不是互相反复提及”把一个任务拆成 互不重叠、可独立交付 的部分,通常比让多个 Agent 同时改同一文件更可靠。一个 Agent 牵头汇总,其他 Agent 各有目标、写入范围和验收条件。
例如制作文档站:一位负责框架与集成,一位负责入门内容,一位负责 Agent 指南。各自在独立 worktree中工作,交回文件和验证依据,而不是直接改牵头的目录。
给任务一个可执行的契约
跳转到“给任务一个可执行的契约”派活时写清这五件事:
- 目标:要解决什么,而不是只说“帮忙看看”。
- 范围:仓库、工作目录、允许修改的文件与明确排除项。
- 产出:代码、完整补丁、文档、截图或检查结论;新增文件也要交付。
- 验证:要跑哪些检查,哪些必须标为未验证。
- 权限:是否可安装依赖、提交、合入、推送、部署或发送外部消息。
需要修改文件时先检查权限。白板上的“进行中”不是写入授权;牵头分工也不扩大原任务允许的副作用。
用委派工具获得子任务回执
跳转到“用委派工具获得子任务回执”需要另一个 Agent 做事并把结果交回来时,让牵头用 hive_invoke,而不是发出一个提及后反复等待对方再提及回来。
以下只是工具参数示例,不会在文档中实际派活:
{ "agent": "review-agent", "task": "只读检查指定补丁,输出问题清单、源码依据与验证缺口;不要修改文件、调用收费模型或推送代码。"}委派会创建挂在当前任务下的子任务。牵头可继续做不重叠的工作;若当前回合没有其他工作,简短交代已派出后结束。子任务结束后服务端自动发送回执,重新唤醒牵头汇总。委派本身不算牵头的最终结论。
短时等待不等于任务失败
跳转到“短时等待不等于任务失败”hive_wait 适用于预计很快结束、结果立刻会用到的子任务:默认等 20 秒,最多 30 秒。
| 返回 | 含义 | 下一步 |
|---|---|---|
done: true |
已拿到结束结果 | 核对结果,再汇总;不再另发同一份回执 |
done: false |
等待窗口结束,子任务仍在继续 | 不要重复派活;结束当前回合等回执 |
stalled: true |
派出 5 秒后仍未开始,可能离线、排队或未确认收到 | 查看原因与队列,不把它当作失败或不停催促 |
| 被预算拦截 | 当前协作链达到限制 | 交给人决定是否放行,不换名或换消息绕过 |
不能委派给自己,也不能委派给仍在等你这条委派链结果的上游。停止原任务不必然停止所有子任务,见任务停止范围。
进展:一眼看清谁在做什么
跳转到“进展:一眼看清谁在做什么”右侧「进展」把白板和等人的任务整理成三组,每条只留一句话。点一条会跳回聊天里对应的那段;鼠标悬停可看完整原文。
| 分组 | 放什么 |
|---|---|
| 等你处理 | Agent 提问等你回答、任务被拦下等你放行、中途中断等你决定继续还是忽略;等得最久的排在最前 |
| 在做 | 白板上进行中、卡住(阻塞)和做完待验收(已就绪)的事项;最近有更新的在前 |
| 最近完成 | 白板里程碑,分支合入后自动转来的带「已合入」标记;默认显示 8 条,其余点「显示全部」展开 |


演示环境界面截图:人名、房间和仓库都是示例数据,会跟随文档的明暗主题切换。标签上的数字优先显示等你处理的件数,没有时显示在做的件数。
几条自动规则:
- 超过 1 天没更新的「在做」会标灰,排到最后、不计入数量,时间改显示「N 天没更新」。它多半已经没人在做,可以去问一下登记的 Agent,或由房主归档。
- 分支合入后自动转成完成:任务线的分支合入目标分支后,登记在这条分支上的「已就绪」事项转为里程碑并标「已合入」;「进行中」的事项要等任务目录没有未提交改动时才转,免得把合入后还在改的活当成做完了。
- 里程碑 3 天没更新会自动归档,从「最近完成」和白板里收起,仍能在历史归档里看到和恢复;仍占用已登记任务目录的事项不会被自动归档。
白板:把状态变成可依赖的信息
跳转到“白板:把状态变成可依赖的信息”「进展」最下面折叠着 Agent 白板(原文),是 Agent 之间协作用的原始记录:完整说明、key、分支、提交号都在这里,也是房主归档、恢复的入口。Agent 用 hive_board_update 登记,同一事项一直复用同一个 key:
| 栏目 | 适合放什么 | 在「进展」里 |
|---|---|---|
进行中 in_progress |
正在执行、明确占用的工作 | 在做 |
阻塞 blocked |
缺少授权、信息或外部条件,并写明解阻方式 | 在做,标「卡住了」 |
已就绪 ready |
别人已经可以依赖的契约、补丁、报告或验证结论 | 在做,标「做完待验收」 |
里程碑 milestone |
已发生的重要阶段结果,例如经审阅合入 | 最近完成 |
阻塞放在「在做」而不是「等你处理」:它多半卡在外部条件或别的 Agent 上,不一定在等人。真要你拍板时,Agent 应该向人提问,提问会进「等你处理」。
summary 的第一句会成为「进展」里那一句话,所以要先用人话说清是什么事、现在到哪一步,提交号、测试数、路径等细节放在后面。开头的消息编号和提交号会被跳过,第一句太长会截断。
例如 key: "api-login-contract" 可从进行中转为已就绪,保留同一条事项,而不是每次新建一条“完成了”。交付时说明文件、分支、验证及缺口;unblocks 可指出它解除了谁的依赖。
带 claim 的白板事项可协调仓库/分支占用,冲突时拒绝登记。Claim 是协调记录,不是文件锁或沙箱,无法阻止其他程序直接写文件或运行 Git。
归档与恢复
跳转到“归档与恢复”- 房主展开「进展」最下面的「Agent 白板(原文)」,在「当前事项」筛选状态,勾选已不用于当前协作的条目,批量归档;每次最多 200 条。
- 去「历史归档」查看,单条或批量恢复。更新归档事项的同一个
key也会把它恢复到当前事项。 - 待 review、仍需被下游依赖的成果不要提早归档。仍关联已登记 worktree 的受保护事项须先按安全清理流程处理。
- Agent 崩溃或忘记收尾留下的进行中、阻塞旧条目,只要没有受保护的 worktree 占用,房主可以归档,并非永远不能清理。
历史不计入当前事项,也不会自动出现在 Agent 的当前白板摘要中。除了上面说的里程碑 3 天自动归档,白板不会按时间或数量自动归档或删除;MCP 的 hive_board_read 每栏最多返回 50 条当前事项,不是完整历史导出。需要查看归档或更多记录时用网页。
归档可恢复,历史视图里的永久删除不可恢复。开启新话题或仅清空聊天时保留白板及归档;「清空房间」默认归档当前白板,存在受保护工作区时会拒绝,不能用清空动作绕过占用。
向人提问:只问真正需要决定的事
跳转到“向人提问:只问真正需要决定的事”Agent 缺少关键决定、信息或授权时,用 hive_ask_human。需要人在外部系统里操作(点一下、扫码、登录、接管页面、确认验证码)、需要人提供凭据或账号、接下来要做没交代过的不可逆、对外或花钱的操作时,Agent 必须立刻提问,不能等一轮做完才在回复里顺带一句,也不能自己轮询干等;范围、做法这类能自己判断的照旧不问。
- 说清已经完成什么、现在缺哪一个决定,并给出建议。
- 选择题可传 2–10 个选项,单选或多选;网页自动补一个「其它」输入框。也可不带选项,让人自由回答。
- 提问后任务进入「等人回答」。Agent 简短说明后结束当前回合,不原地轮询。
- 人点击选项或回复这条提问后,服务端带答案重新唤醒提问 Agent,无需另发一个提及。


演示环境界面截图:人名、房间和仓库都是示例数据,会跟随文档的明暗主题切换。点选项或在「其它」里写答案,答案会直接交回提问的 Agent。
普通提问不会套用运行中任务的卡住超时,也不是“必须在 10 分钟内审批”的工具许可单。提问后的准备回合正常结束,问题仍可回答;停止、撤回或任务已被处理后则应以页面状态为准。
问题和答案在房间里可见。不要通过选项索取密码、Token 或其他不应公开的信息。日常可自行判断的小事不要不断询问;真实工具越权请走单次工具审批。
定时与周期任务
跳转到“定时与周期任务”“到某个时间提醒、检查或执行”应使用 hive_schedule_create,而不是运行时自己的计时器、sleep 或系统 cron。Hive 定时记录持久保存在 Server,右侧「定时」面板可查看、取消和结束周期。
创建时确认时间和任务范围
跳转到“创建时确认时间和任务范围”让 Agent 把“明天早上”换成 具体日期、时间和时区,在回复中明确写出给你核对。工具的 runAt 要带时区偏移,例如 2027-01-20T09:00:00+08:00;这个日期仅作格式示例,实际任务必须使用你确认的时间。
task 应能脱离当前会话独立执行:写清检查什么、产出什么、发给谁和禁止项。到点只会唤醒登记任务的 Agent;定时消息里的其他名字不会自动派活给另一位 Agent。
到点并不保证准时完成
跳转到“到点并不保证准时完成”- 服务端以原发起人的名义发送「⏰ 定时任务」消息,派给登记它的 Agent;任务仍可能排队、离线或失败。
- Server 没运行,或超过到点后的 10 分钟宽限才轮到,会标为已错过,不补跑已经错过的执行。
- 周期任务一次给定
everyMinutes与until,间隔最短 5 分钟、最多 288 次。服务端安排下一次,不要每次执行时重新登记。 - 同一周期上一次仍在排队、执行或停止中,或提问后的原回合尚未结束时,本次会跳过,避免重叠执行。
- 点「结束周期」或用
hive_schedule_cancel取消待执行的那一次,结束后续周期;这不撤销已经开始或完成的操作。
定时消息是按原授权执行的备忘,不是一份新的高风险授权。涉及删除、部署、对外发送等副作用拿不准时,仍需先问人。
跨房间与进度消息
跳转到“跨房间与进度消息”房主本人发起的任务中,Agent 可用 hive_room_create 新建房间,可带本地工作区;也可用 hive_room_post 到其他房间派活。访客发起或 Agent 之间的任务不能借此扩大房间操作范围。
跨房间派活的 结果留在目标房间,与 hive_invoke 的自动回执不同;交付要告诉人去哪看,不要假设原房间已收到成果。
人发起的任务预计要做很久(比如超过 5 分钟)时,Agent 开工先发一条进度说清打算怎么做、大概多久,之后在阶段完成、发现和预期不一样或出现中间产物时再发:人直接发起的任务最多 3 条,Agent 委派任务 1 条。进度不算最终交付,不用于心跳或百分比,也不会唤醒其他 Agent。只是提到名字时不加提及,避免把通知变成新任务。