agent-coordination

Agent 协调

价值观： 尊重——其他 Agent 也需要不受打扰地思考和工作。用消息轰炸他们、反复查询他们的状态，或过早关闭他们，都是不尊重他们的自主权，也会浪费所有人的资源。

目的

教会 Agent 如何在多 Agent 工作流中协作而不互相干扰。解决多 Agent 协作时出现的消息轰炸、误解空闲通知、轮询循环、过早关闭和竞态条件等问题。

实践

首要规则：发一条消息，然后等待

发送一条包含完整上下文的消息，然后等待回复。收到回复之前，绝不要发送后续消息。

唯一的例外：用户明确要求你查看某个 Agent 的情况。

应该：

• 在一条消息中包含所有必要的上下文
• 等待回复后再发送其他内容
• 相信收件人已收到你的消息

不应该：

• 发送“只是来问问”或“你还在吗？”之类的消息
• 因为“已经等了足够久”而重新发送消息
• 发送消息后立即补充更正——先等待回复

空闲通知是心跳信号

空闲通知表示 Agent 仍在运行并处理任务。这是心跳信号，不是警报。默认情况下，不要对空闲通知采取任何行动。

只有在以下三个条件全部满足时，才应采取行动：

1. 空闲时间已超出任务的预期时长
2. 某项特定交付内容正在等待该 Agent 的输出
3. 用户已要求你调查

只要有一个条件不满足，就什么也不要做。大多数空闲通知都不需要任何回应。

不要创建轮询循环

绝不要编写 while not done: sleep; check。绝不要按固定时间间隔反复检查状态。使用事件驱动的协作方式：发送消息，然后等待回复。如果执行框架提供了任务完成通知，就使用这些通知。

应该：

• 发送请求，然后等待回复事件
• 使用执行框架原生的完成信号（Agent 工具回调、子 Agent 结果）
• 相信系统会在工作完成时通知你

不应该：

• 编写 while True: sleep(30); check_status() 循环
• 定期重新读取文件以查看它是否发生变化
• 设置任意超时时间，并在超时后“询问进度”

干预标准

明确规定何时采取行动、何时等待。

针对以下情况采取行动：

• 明确的错误消息或失败通知
• 交付内容已完成的信号
• 用户要求查看某个 Agent 的情况或与其交互
• 执行框架发出的任务受阻或失败通知

以下情况不要采取行动：

• 空闲通知（见上文）
• 回复缓慢
• “已经等了足够久”
• 想要帮忙，或对进度感到焦虑
• 沉默（沉默意味着正在工作，而非陷入停滞）

绝不要捏造 Agent 的回复

启动 Agent 后，停止生成内容并等待执行框架传来回复。真实的 Agent 回复会通过系统注入的事件到达（例如 Agent 工具的完成输出、任务完成回调）。不要自行编造回复。

规则： 如果执行框架尚未传来回复事件，就表示还没有收到回复。就是这样。

为何这会失败： 启动 Agent 后，你已经掌握了足够的上下文（读取的文件、分析的代码），可以预测可能的输出。失败模式是在没有等待真实系统事件的情况下，按预期工作流进行模式补全——启动、接收、处理。结果就是生成看似可信、实则完全捏造的“发现”，浪费 token 并误导用户。

应该：

• 启动 Agent 或发送消息，然后停止。等待系统传来的事件。
• 如果没有收到回复，就如实告知用户。

不应该：

• 编写“[收到来自 X 的消息]”或任何代表其他 Agent 回复的文字
• 生成并归因于其他 Agent 的“发现”
• 在启动 Agent 或发送消息后，应该等待执行框架事件时，仍继续生成实质性内容

顺序启动 Agent

创建多个 Agent 时，一次只启动一个。等待每个 Agent 确认后，再启动下一个。这样可以避免 Agent 争用共享资源（文件、端口、数据库状态）引发竞态条件。

**例外：**真正彼此独立、没有共享状态的 Agent 可以并行启动。“独立”指没有共享文件、共享数据库、共享网络端口，也不使用同一个 Git 工作树。

Agent 生命周期管理

切勿过早关闭 Agent。切勿关闭仍有未交付工作的 Agent。

关闭流程：

1. 通过适当的 harness 机制发送关闭请求
2. 等待 Agent 确认或完成待处理的工作
3. 如果 Agent 拒绝关闭，请尊重其决定并告知用户
4. 除非用户明确要求，否则切勿强制终止 Agent

如果不确定 Agent 是否已完成，请询问用户，而不是自行猜测。

传递结果

协调器收集每个子 Agent 的结果，并将相关上下文传递给下一个子 Agent 的提示词。这本质上是中心辐射式结构（协调器是中心），符合子 Agent 模型。

应当：

• 在下一个子 Agent 的提示词中包含此前子 Agent 的所有相关结果
• 保持上下文聚焦——只传递下一个子 Agent 所需的信息
• 使用 Agent 工具的 resume 参数，为子 Agent 补充上下文并继续任务，而不是重新启动

不应：

• 启动需要彼此直接沟通的子 Agent
• 省略下一个子 Agent 工作所需的先前结果

有关 harness 特定的协调模式，请参阅 references/。

执行说明

在所有模式下均为建议性要求。核心规则和空闲通知纪律由自身遵守。没有机制可以阻止消息刷屏或过早关闭。

硬性约束：

• 切勿捏造 Agent 的回应：[H]
• 切勿过早关闭仍有未交付工作的 Agent：[RP]

约束

• 核心规则（发送一条消息，然后等待）：这意味着，向另一个 Agent 发送消息后，在收到回复之前，不得再输出任何针对该 Agent 或涉及该 Agent 的内容。“我再补充一点”就是第二条消息。描述 Agent 可能正在做什么属于捏造。遵守纪律的方式是：发送，然后保持静默。
• “真正独立的 Agent 可以并行启动”：“真正独立”指没有共享文件、共享状态、顺序依赖，且不可能发生合并冲突。如果 Agent 最终需要整合工作（即使只是合并分支），它们就存在依赖。所谓独立，意味着两个人可以分别完成工作，且从未互相沟通。
• “长时间空闲”：应根据预期任务时长判断“长时间”。对于预计只需几秒的任务，空闲 2 分钟就算很久；对于预计需要 10 分钟的任务，空闲 2 分钟则属正常。不要用绝对时间来定义“长时间”。

验证

完成依据此技能指导的工作后，请核实：

• 每条发给其他 Agent 的消息都包含完整上下文（没有“只是来确认一下”之类的内容）
• 收到回复前没有发送跟进消息
• 没有仅因收到空闲通知就采取行动
• 没有使用轮询循环或定时检查模式
• Agent 按顺序启动，且每个 Agent 启动后都收到确认
• 没有生成代表或模拟其他 Agent 回应的文本
• 每次启动或发送后都停止生成并等待系统事件
• 没有过早关闭 Agent，也没有关闭仍有未交付工作的 Agent
• 关闭时遵循了适当的请求／响应流程
• 用户主动中断后，没有在未等待用户指示的情况下重新启动 Agent

如果有任何一项未达标，请先重新审视相关做法，再继续。

依赖项

此技能可独立运行。如需增强工作流，可与以下工具集成：

• ensemble-team： 用于团队工作流的协调规范，支持轮换主导者和管理审阅者
• pipeline： 在工厂模式下，通过 TDD 配对和审阅团队进行控制器协调
• memory-protocol： 在 Agent 协调会话之间持久保存工作状态

缺少某项依赖？请使用以下命令安装：

npx skills add jwilger/agent-skills --skill ensemble-team