s15 智能体团队：Agent Teams - Harness Engineering - 后端

# 三行速读

这章把 “一次性子任务” 升级为 “持久队友协作”。
队友有身份、状态、收件箱，可反复接活。
多 Agent 的第一步不是复杂框架，而是可追踪消息流。

# 先修知识

已理解 s04 的委派思想。
已掌握 s12/s13 的任务与运行时基础。

# 读完后你应该能做到（可检验清单）

启动两个队友并完成一次消息协作。
解释 inbox drain 语义对一致性的作用。
追踪一个队友从 idle 到 working 再回 idle 的完整过程。

# 本篇要解决什么

s04 的 subagent 是一次性委派，适合临时任务。s15 引入长期队友，让协作从 “临时分包” 升级到 “持续分工”。

核心目标：让多个有身份的 Agent 通过邮箱协作，且可反复接活。

# 用一个类比先理解

把它当小团队：

每个成员有姓名和角色；
每人有独立收件箱；
任务通过消息分派，完成后回信。

这比 “每次临时找外包” 稳定得多。

# 为什么这一步必须现在做

后续协议审批、自主认领都建立在 “队友长期存在” 前提上。没有持久身份，就很难做可追踪协作。

# 关键代码怎么读

# 1) 团队状态目录

1 2	TEAM_DIR = WORKDIR / ".team" INBOX_DIR = TEAM_DIR / "inbox"

目录结构本身就是系统边界：配置与消息分开管理。

# 2) MessageBus 的收发语义

class MessageBus:
    def send(...):
        ... # append json line
    def read_inbox(self, name: str) -> list:
        ...
        inbox_path.write_text("")

读取后清空（drain）是关键语义，避免重复消费同一消息。

# 3) TeammateManager 的持久生命周期

1
2
3

def spawn(self, name: str, role: str, prompt: str) -> str:
    ...
    thread = threading.Thread(target=self._teammate_loop, ...)

同名成员可多次唤醒，说明它是 “长期角色”，不是一次性实例。

# 4) 队友工具集包含沟通能力

def _teammate_tools(self) -> list:
    ...
    {"name": "send_message", ...},
    {"name": "read_inbox", ...},

队友不仅能改代码，还能协同沟通，这是团队系统的基础。

# 你可以怎么复现

创建两个队友（例如 coder、reviewer）。
让 coder 执行修改，reviewer 读取结果并回复。
观察 inbox 流转是否清晰。

# 常见误区

误区 1：把 teammate 当 subagent 的别名。
误区 2：没有消息类型约束，协作消息混乱。
误区 3：状态不持久，重启后角色丢失。

# 一句话总结

s15 让多 Agent 协作从 “概念” 落到 “有身份、有收件箱、有生命周期” 的工程实现。

# 补充解读：团队模型里最重要的三个状态

# A. 成员状态机

idle -> working -> idle ，以及特殊的 shutdown 。这比 “线程是否活着” 更接近业务语义。

# B. 消息类型约束

VALID_MSG_TYPES = {
    "message", "broadcast", "shutdown_request", "shutdown_response",
    "plan_approval", "plan_approval_response",
}

限制消息类型能显著降低协议漂移。

# C. `_teammate_loop` 的再入模型

队友不是一次运行到底，而是每轮先读 inbox，再进行工具执行，循环进入 “可再次分派” 状态。

# D. 为什么 JSONL inbox 很合适

追加写简单；
排查可读；
便于后续演进到消息总线。

# 进阶练习

给 inbox 增加消息去重 ID。
在队友线程加入 “空闲心跳”。
统计每个队友平均响应延迟。

# 再补一层：从单兵到团队时的设计取舍

# A. 为什么先用文件 inbox 而不是消息中间件

教学阶段选择 JSONL inbox 的核心优势：

易读可查；
本地可调试；
不引入额外基础设施复杂度。

先把协作语义跑通，再升级基础设施是更稳的路径。

# B. 队友状态建议增加 “最近活动时间”

只有 idle/working 有时不够，你还需要知道 “多久没动了”，便于发现僵尸线程或任务饿死问题。

# C. 广播消息要谨慎使用

广播很方便，但也容易制造噪音。建议只用于真正全员相关事件（比如策略更新、系统暂停通知）。

# D. 团队协作质量的三个基础指标

平均消息往返时延。
任务分派成功率。
队友空闲占比。

这些指标比 “看起来很聪明的回复” 更能反映系统真实效率。

# 统一术语口径（本章）

Teammate ：具有持久身份与状态的长期协作智能体。
Inbox ：队友的独立消息收件箱。
Message Bus ：队友之间收发消息的传输层。

# 章节衔接（从易到难）

本章解决 “团队基础协作”。
下一章 s16 进入 “关键动作如何协议化、可审计化”。

Harness Engineering