作者逆境不可逃技术永无止境希望我的内容可以帮助到你大家吼 ! 我是 逆境不可逃 今天给大家带来文章《【与我学 ClaudeCode】协作篇 之 Team Protocols 结构化请求 - 响应协作协议》.Learn-Claude-Code 官方地址 :shareAI-lab/learn-claude-code: Bash is all you need - A nano claude code–like 「agent harness」, built from 0 to 1上一篇文章【与我学 ClaudeCode】协作篇 之Agent Teams 持久化队友与文件邮箱-CSDN博客Team Protocols 是迭代的第 10 个版本s10核心解决多 Agent 团队协作中无结构化通信的混乱问题。它在 s09 文件邮箱的基础上构建了基于request_id关联的请求 - 响应协议框架实现了优雅关机和计划审批两种关键协作流程让队友之间的沟通有了统一的 “规矩”。一、问题根源为什么无结构化通信撑不起团队协作s09 中队友能干活、能通信但缺少结构化协调导致两个关键场景存在风险关机混乱直接杀线程会留下写了一半的文件和过期的config.json队友无法优雅收尾数据完整性无法保证计划失控队友收到指令后立刻开干高风险变更如重构核心模块没有审批流程容易导致不可逆的错误这两个场景本质上都是「请求 - 响应」模式一方发起请求另一方处理并返回结果。没有统一的协议框架通信就像 “无信号的对讲机”容易出现请求丢失、响应错配、状态不一致等问题。二、三大核心设计决策Team Protocols 通过三个关键设计构建了一个简单、可靠、可扩展的多 Agent 通信协议体系。1. JSONL 收件箱文件而非共享内存核心设计每个队友都有自己的收件箱文件团队目录中的 JSONL 文件。发送消息意味着向接收者的收件箱文件追加一行 JSON读取消息意味着读取收件箱文件并追踪上次读到的行。JSONL 天然是仅追加的这意味着并发写入不会破坏彼此的数据追加到不同的文件位置。它在无需共享内存、互斥锁或 IPC 机制的情况下跨进程工作也是崩溃安全的如果写入者在追加中途崩溃最坏情况是一行不完整的数据读取者可以跳过。替代方案的致命缺陷共享内存如 Python multiprocessing.Queue速度更快但无法在独立启动的进程中工作消息代理Redis、RabbitMQ提供健壮的发布 / 订阅功能但会增加基础设施依赖Unix 域套接字可以工作但难以调试没有人类可读的消息日志。JSONL 文件是最简单的提供持久化、跨进程通信和可调试性的方法。2. 恰好五种消息类型覆盖所有协调模式核心设计消息系统支持五种类型映射到基本协调模式message两个 Agent 间的点对点通信broadcast全团队公告shutdown_request优雅终止请求shutdown_response终止确认响应plan_approval_response组长审批或拒绝队友的计划这五种类型覆盖了直接通信、广播、生命周期管理和审批流程每种类型都有清晰明确的用途。替代方案的致命缺陷单个通用消息类型带元数据字段会更灵活但难以强制协议正确性更多类型10会提供更细粒度的语义但会增加模型的决策负担。五种类型是兼顾灵活性和清晰度的平衡点。3. 每次 LLM 调用前检查收件箱核心设计队友在每次 Agent 循环迭代的顶部、调用 LLM API 之前检查收件箱文件。这确保了对传入消息的最大响应性一个终止请求会在一个循环迭代内被看到通常几秒钟而非在当前任务完成后可能数分钟。收件箱检查成本很低读取小文件检查是否有新行相比 LLM 调用秒级延迟、数千 token微不足道。这个位置还意味着传入消息可以影响下一次 LLM 调用 —— 一条 “停止 X转去做 Y” 的消息会立即生效。替代方案的致命缺陷在每次工具执行后检查收件箱响应性更好但会给每个工具调用增加开销单独的观察器线程可以持续监控收件箱但会增加线程复杂度。每次 LLM 调用前检查是务实的平衡点足够响应性以满足协调需求又足够便宜不影响性能。三、系统整体架构与工作原理1. 核心协议框架请求 - 响应模式两种关键协议共享相同的request_id关联模式Shutdown Protocol Plan Approval Protocol Lead Teammate Teammate Lead | | | | |--shutdown_req--| |--plan_req------| | {req_id:abc} | | {req_id:xyz} | | | | | |--shutdown_resp-| |--plan_resp-----| | {req_id:abc, | | {req_id:xyz, | | approve:true} | | approve:true} |发起方生成唯一request_id发送请求消息接收方处理请求返回带相同request_id的响应消息发起方通过request_id关联请求和响应更新状态机2. 共享状态机FSM两种协议使用相同的状态机[pending] --approve-- [approved] [pending] --reject--- [rejected]pending请求已发送等待响应approved请求被同意执行对应操作如关机、执行计划rejected请求被拒绝放弃对应操作3. 关键组件与实现细节(1) 请求跟踪器关联请求与响应# 全局请求跟踪器线程安全 shutdown_requests {} plan_requests {} _tracker_lock threading.Lock()shutdown_requests存储关机请求键为request_id值包含目标队友和状态plan_requests存储计划审批请求键为request_id值包含发起队友、计划内容和状态(2) 优雅关机协议实现组长发起关机请求def handle_shutdown_request(teammate: str) - str: req_id str(uuid.uuid4())[:8] with _tracker_lock: shutdown_requests[req_id] {target: teammate, status: pending} # 发送 shutdown_request 消息给队友 BUS.send( lead, teammate, Please shut down gracefully., shutdown_request, {request_id: req_id}, ) return fShutdown request {req_id} sent to {teammate} (status: pending)队友处理关机请求并响应# 队友的 shutdown_response 工具处理 if tool_name shutdown_response: req_id args[request_id] approve args[approve] # 更新请求状态 with _tracker_lock: if req_id in shutdown_requests: shutdown_requests[req_id][status] approved if approve else rejected # 发送 shutdown_response 消息给组长 BUS.send( sender, lead, args.get(reason, ), shutdown_response, {request_id: req_id, approve: approve}, ) return fShutdown {approved if approve else rejected}队友根据响应决定是否退出def _teammate_loop(self, name: str, role: str, prompt: str): # ... should_exit False for _ in range(50): # ... 处理收件箱和工具调用 ... if block.name shutdown_response and block.input.get(approve): should_exit True # 循环结束后更新状态 member self._find_member(name) if member: member[status] shutdown if should_exit else idle self._save_config()(3) 计划审批协议实现队友提交计划审批请求# 队友的 plan_approval 工具处理 if tool_name plan_approval: plan_text args.get(plan, ) req_id str(uuid.uuid4())[:8] with _tracker_lock: plan_requests[req_id] {from: sender, plan: plan_text, status: pending} # 发送 plan_approval_response 消息给组长 BUS.send( sender, lead, plan_text, plan_approval_response, {request_id: req_id, plan: plan_text}, ) return fPlan submitted (request_id{req_id}). Waiting for lead approval.组长审批计划def handle_plan_review(request_id: str, approve: bool, feedback: str ) - str: with _tracker_lock: req plan_requests.get(request_id) if not req: return fError: Unknown plan request_id {request_id} # 更新请求状态 with _tracker_lock: req[status] approved if approve else rejected # 发送 plan_approval_response 消息给队友 BUS.send( lead, req[from], feedback, plan_approval_response, {request_id: request_id, approve: approve, feedback: feedback}, ) return fPlan {req[status]} for {req[from]}(4) 队友工具集扩展def _teammate_tools(self) - list: return [ # 基础工具bash、read_file等 {name: bash, ...}, {name: read_file, ...}, {name: write_file, ...}, {name: edit_file, ...}, # 通信工具 {name: send_message, ...}, {name: read_inbox, ...}, # 新增协议工具 {name: shutdown_response, description: Respond to a shutdown request. Approve to shut down, reject to keep working., input_schema: {type: object, properties: {request_id: {type: string}, approve: {type: boolean}, reason: {type: string}}, required: [request_id, approve]}}, {name: plan_approval, description: Submit a plan for lead approval. Provide plan text., input_schema: {type: object, properties: {plan: {type: string}}, required: [plan]}}, ](5) 执行流程四、与 Agent Teamss09的关键变更对比组件之前s09 Agent Teams之后s10 Team Protocols工具集9 个工具12 个工具新增shutdown_request/response、plan_approval关机机制仅自然退出或强制杀线程请求 - 响应握手优雅关机计划审批无提交 / 审查与审批流程消息关联无纯文本消息每个请求一个request_id关联请求与响应状态机无pending - approved/rejected共享 FSM通信模式纯文本点对点 / 广播结构化请求 - 响应协议五、核心优势与创新点结构化通信避免混乱基于request_id的关联模式确保请求和响应一一对应解决了无结构化通信的错配问题优雅关机数据安全关机请求需要队友确认队友可以在退出前完成收尾工作如关闭文件、保存状态避免数据损坏计划审批风险可控高风险变更需要组长审批防止队友擅自执行不可逆操作提升团队协作的安全性统一协议框架可扩展同一个请求 - 响应模式可以套用到更多协作场景如资源申请、任务移交为后续扩展打下基础低侵入式实现兼容旧系统基于 JSONL 文件邮箱实现无需修改 s09 的通信基础仅新增消息类型和工具即可实现协议六、运行示例场景 1优雅关机流程组长判断任务完成调用shutdown_request(teammatecoder)生成request_idabc123队友coder收到shutdown_request消息决定是否批准关机如任务已完成则批准如正在处理关键文件则拒绝队友调用shutdown_response(request_idabc123, approveTrue)发送响应消息组长收到响应更新shutdown_requests[abc123]状态为approved队友在循环结束后将状态更新为shutdown线程安全退出场景 2计划审批流程队友coder需要重构认证模块调用plan_approval(plan重构认证模块步骤1: 修改auth.py步骤2: 更新测试用例)生成request_idxyz789组长收到plan_approval_response消息审查计划是否合理、是否符合项目规范组长调用plan_approval(request_idxyz789, approveTrue, feedback计划合理按步骤执行即可)发送审批响应队友收到批准消息开始执行重构计划七、可扩展方向更多协议类型扩展协议框架实现任务移交、资源申请、错误报告等请求 - 响应流程协议超时与重试为请求添加超时机制未收到响应时自动重试或标记为失败协议日志与审计将所有协议消息单独归档便于事后审计和问题排查协议权限控制为不同角色的 Agent 分配不同的协议权限如普通队友不能发起关机请求协议自动生成基于配置文件自动生成协议工具和状态机降低新增协议的开发成本