1. 多智能体协作里为什么“关机”和“审批”最容易翻车如果你正在用 Claude Code Agent 搭多智能体团队大概率遇到过这种场面一个队友正在写auth.py你这边任务跑完了想收工直接 CtrlC 或者把线程 kill 掉结果文件写了一半、config.json停在中间状态下次启动直接报解析错误。更麻烦的是队友拿到任务二话不说就开始重构核心模块等你发现的时候线上配置已经被改得面目全非。这两个问题的本质是一样的队友之间没有统一的沟通规矩。s09 那版多智能体团队靠自由对话协作消息没有 ID请求和响应对不上号并发一多就乱套。到了 s10官方引入了“团队协作协议”核心就两件事——优雅关机握手和高风险计划审批两者共享同一套request-id关联加 FSM 状态机模式。这篇就围绕这两个协议把可复制的settings.json和config.toml配置骨架给你再走一遍验证关机信号和审批回执的实操动作。所有模型调用统一走 TaoToken 的 Key/API 通道团队里每个人用同一个入口省得各自配环境配出差异。适合谁看已经在跑 Claude Code Agent 多智能体、被脏数据和失控变更坑过、想把协作从“实验性”推到“生产可用”的团队。读完你能拿到一套能直接落地的协议配置以及排障时该看哪几个字段。2. 前置准备在 TaoToken 统一 Key/API 通道下搭好协议环境协议本身是应用层的事但它依赖一个稳定的模型调用通道。团队协作最怕的就是 A 同学用这个 Key、B 同学用那个 Key审批回执发出去结果模型侧限流了握手直接断在半路。所以第一步先把通道统一。TaoToken 在这里的角色是统一入口官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。你需要在控制台生成一个团队共用的 Key然后把它写进环境变量而不是硬编码进每个队友的脚本里。先拿 Key进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建一个项目级的 API Key。建议按“团队”维度建而不是按“个人”这样后面做 request-id 追踪时日志能归到一起。拿到 Key 之后写进 shell 环境export TAOTOKEN_API_KEYsk-你的团队Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Claude Code 这类需要 Anthropic 兼容端点的工具接入文档在这里 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。文档里有不同客户端的 base_url 填法照着改就行别自己猜路径。注意团队协作协议里的request-id是应用层生成的和 API Key 无关。但如果你把 Key 分散到多个账号审批回执的日志会散落在不同控制台排障时非常痛苦。统一 Key 是后面所有追踪动作的前提。环境就绪后确认一下通道能通curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY | head -c 300能返回模型列表就说明通道没问题。这一步别跳过我见过太多“协议写对了但请求根本没发出去”的案例最后查半天发现是 Key 没生效。3. 可复制配置settings.json 与 config.toml 协议骨架协议落地靠两个配置文件settings.json管工具注册和协议开关config.toml管团队拓扑和超时策略。下面这份骨架你可以直接抄改掉团队名和路径即可。3.1 settings.json注册协议工具与跟踪器{ team: { name: default, protocol: { shutdown: { enabled: true, require_approval: true, grace_period_sec: 30 }, plan_approval: { enabled: true, high_risk_keywords: [deploy, refactor, migrate, drop], auto_reject_timeout_sec: 120 } }, trackers: { shutdown_requests: {}, plan_requests: {} } }, tools: [ shutdown_request, shutdown_response, plan_approval ], api: { base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY } }这里的关键是trackers两个空对象它们对应代码里的shutdown_requests和plan_requests全局字典。grace_period_sec是队友收到关机请求后允许走完当前轮次的时间别设太短否则正在写文件的操作会被打断。3.2 config.toml团队拓扑与状态机参数[team] name default workdir ./workspace [team.protocol.shutdown] request_prefix shutdown response_type shutdown_response states [pending, approved, rejected] [team.protocol.plan] request_prefix plan response_type plan_approval_response states [pending, approved, rejected] [team.teammates.alice] role coder max_turns 50 submit_plan_before_major_work true [team.teammates.bob] role reviewer max_turns 50 submit_plan_before_major_work true [api] base_url https://taotoken.net/api timeout_sec 60states数组就是那个可复用的 FSMpending → approved/rejected。关机协议和审批协议共用同一套状态定义所以你在代码里只需要写一次状态流转逻辑。3.3 队友系统提示词把协议规则写进去配置只是骨架真正让队友遵守协议的是系统提示词。在TeammateManager里给每个队友注入sys_prompt ( fYou are {name}, role: {role}, at {WORKDIR}. fSubmit plans via plan_approval before major work. fRespond to shutdown_request with shutdown_response. )这两句话对应两个硬规则做重要工作前先提交计划审批收到关机请求必须用shutdown_response工具响应。少了这两句队友会继续按自由对话的方式干活协议形同虚设。4. 验证请求跑通关机信号与审批回执配置写完得验证协议真的在跑。分两条线一条验关机握手一条验计划审批。4.1 验证优雅关机信号领导侧发起关机请求代码逻辑是生成request_id、写入跟踪器、发消息def handle_shutdown_request(teammate: str) - str: req_id str(uuid.uuid4())[:8] with _tracker_lock: shutdown_requests[req_id] {target: teammate, status: pending} BUS.send( lead, teammate, Please shut down gracefully., shutdown_request, {request_id: req_id}, ) return fShutdown request {req_id} sent to {teammate} (status: pending)跑起来后你在终端应该看到类似输出s10 Request alice shutdown shutdown_request: Shutdown request def456 sent to alice (status: pending) [alice] shutdown_response: Shutdown approved s10 /team Team: default alice (coder): shutdown注意alice的状态从idle变成了shutdown这说明队友批准了关机并且安全退出了循环。队友侧的关键逻辑是should_exit标志if block.name shutdown_response and block.input.get(approve): should_exit True它不会立刻退出而是等当前轮次走完下次循环开头才break。这就是“优雅”的含义——不中断正在执行的操作。4.2 验证计划审批回执队友提交计划时自动生成request_idif 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} 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} req[status] approved if approve else rejected BUS.send( lead, req[from], feedback, plan_approval_response, {request_id: request_id, approve: approve, feedback: feedback}, ) return fPlan {req[status]} for {req[from]}实测下来完整流程长这样s10 Spawn alice as a coder with task to refactor auth module spawn_teammate: Spawned alice (role: coder) [alice] plan_approval: Plan submitted (request_idabc123). Waiting for lead approval. s10 /inbox [{type: plan_approval_response, from: alice, content: 重构计划1. 读现有auth代码 2. 抽离接口 3. 写测试 4. 替换旧实现, request_id: abc123}] s10 Approve plan abc123, feedback 注意保留兼容旧接口 plan_approval: Plan approved for alice [alice] write_file: ...开始执行重构...看到Plan approved for alice并且队友开始执行说明审批回执闭环了。这里request_idabc123是串联请求和响应的唯一线索并发多个计划时全靠它匹配。4.3 用模型对话快速验证协议消息格式如果你不想每次都起完整团队可以先用模型对话单独验证消息格式对不对。把shutdown_request和plan_approval_response的 JSON 结构丢进去让模型帮你检查字段是否齐全{ type: shutdown_response, request_id: def456, approve: true, reason: current task finished }模型对话入口 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。这一步能帮你提前发现字段名拼错、类型不对这类低级问题比在完整团队里调试快得多。5. 本篇常见错排查协议跑不起来八成是下面几个坑。request_id 对不上。最常见的是队友侧生成 ID 用了uuid.uuid4()全量领导侧查询时用了截断的[:8]两边格式不一致。统一用str(uuid.uuid4())[:8]别一处截一处不截。跟踪器状态没更新。如果你看到shutdown_requests里状态一直是pending检查_tracker_lock有没有正确加锁。多线程并发写字典不加锁状态更新会丢。代码里所有对shutdown_requests和plan_requests的读写都要包在with _tracker_lock:里。队友不响应关机请求。先看系统提示词里有没有Respond to shutdown_request with shutdown_response。没有这句模型不知道有这个工具自然不会调用。再看工具集里shutdown_response的input_schema是否把request_id和approve标成了required。审批回执发出去但队友没收到。检查BUS.send的接收方参数。领导审批时发给req[from]也就是提交计划的队友名别写成lead或者硬编码。名字对不上消息就进了别人的 inbox。关机后状态还是 idle。看member[status] shutdown if should_exit else idle这行有没有在循环结束后执行。如果should_exit被设成 True 但循环提前break跳过了状态更新状态就会停在旧值。API 侧超时导致握手断掉。团队协作里一次审批可能等几十秒如果timeout_sec设太短请求还没回来就断了。config.toml里建议设 60 秒以上长任务场景可以到 120。排障时优先看两个地方跟踪器字典的当前状态以及BUS的 JSONL 消息文件。前者告诉你协议走到哪一步后者告诉你消息有没有真的发出去。接入相关的细节如果拿不准翻接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。6. 长期跑编码任务把协议接进 Coding Plan单次验证通过不代表长期稳定。团队协作协议真正的价值在于长时间运行的编码任务——队友持续提交计划、领导持续审批、任务结束时优雅收尾。这种场景建议把协议接进 Coding Plan让 Key 管理、额度分配、协议日志都归到一处。Coding Plan 入口 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。接入后你可以按团队维度看每个request_id的完整生命周期从pending到approved再到队友状态变shutdown整条链路可追溯。API Key 管理在控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。建议给协议通道单独建一个 Key和日常对话的 Key 分开这样审批回执的调用量能单独统计出问题也好定位。如果你用的是 Claude Code 的 Anthropic 兼容模式接入参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。把base_url指向 TaoToken 的 API 端点协议层代码不用改只换通道。最后留一个我踩过的坑协议刚上线时别把grace_period_sec设太短。队友正在写一个大文件30 秒可能不够走完当前轮次结果关机请求批准了但文件还是写了一半。先设 60 秒跑一周观察实际轮次耗时再往下调。