From a2374c5bd4b983af6ff8de809072d93d7de304a6 Mon Sep 17 00:00:00 2001 From: root Date: Wed, 29 Jul 2026 00:14:40 +0800 Subject: [PATCH] =?UTF-8?q?docs(s16):=20fix=20protocol=20flowchart=20?= =?UTF-8?q?=E2=80=94=20separate=20shutdown=20and=20plan=20approval=20flows?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Split the single protocol row into two distinct flows: - Protocol A (yellow): shutdown, initiated by Lead via request_shutdown - Protocol B (blue): plan approval, initiated by Teammate via submit_plan request_plan is now shown as a plain message (grey dashed box/arrow), not a protocol action. review_plan is added to the diagram. All three language SVGs updated with the same layout. Closes #373 --- .../images/team-protocols-overview.en.svg | 158 +++++++++-------- .../images/team-protocols-overview.ja.svg | 162 ++++++++--------- .../images/team-protocols-overview.svg | 163 +++++++++--------- 3 files changed, 237 insertions(+), 246 deletions(-) diff --git a/s16_team_protocols/images/team-protocols-overview.en.svg b/s16_team_protocols/images/team-protocols-overview.en.svg index 7dd6b28c..36e335ba 100644 --- a/s16_team_protocols/images/team-protocols-overview.en.svg +++ b/s16_team_protocols/images/team-protocols-overview.en.svg @@ -1,4 +1,4 @@ - + @@ -9,9 +9,6 @@ - - - @@ -20,124 +17,125 @@ - + - Team Protocols — Request-Response + request_id Correlation + State Machine - s15 Preserved s16 New - + turn - - messages - - prompt - - LLM - - TOOL DISPATCH (core tool set) bash · read · write · task(4) · spawn · send · inbox ★ request_shutdown · request_plan · review_plan - - - - - Request-Response Protocol Flow (request_id throughout) + + + Protocol A: Shutdown (Lead initiates → Teammate responds) - - - ① Lead sends request - BUS.send("shutdown_request" - metadata={request_id}) + + ① Lead: request_shutdown + new_request_id() → ProtocolState - + - - - ② Teammate receives - dispatch_by_type(inbox) - → handler(type, metadata) + + ② Teammate: handle_shutdown + ack → shutdown_response - + - - - ③ Teammate responds - BUS.send("shutdown_response" - same request_id + approve) + + ③ Lead: consume_lead_inbox + match_response(request_id) → ✓ - + + + Protocol B: Plan Approval (Teammate initiates → Lead reviews) - - - ④ Lead receives - match_response(request_id) - → resolve/reject callback + + 0. Lead: request_plan + Plain message (msg_type="message") - - - - State Machine (same for both protocols) + - - pending + + ① Teammate: submit_plan + plan_approval_request + request_id - - approve + - - approved + + ② Lead: review_plan + plan_approval_response - - reject + - - rejected + + ③ Teammate: receives + [Plan approved/rejected] - - - pending_requests Storage - pending_requests: dict[str, ProtocolState] - request_id → {type, sender, status, created_at} - match_response: find request by request_id + request_plan is a plain message, not a protocol; submit_plan is the protocol entry point (creates ProtocolState on teammate side) - - - Two protocols, one mechanism: - - shutdown_request - and - - plan_approval_request - share the same pending→approved/rejected FSM - New protocol type = new msg_type, no new state machine. request_id links request and response. + + + State Machine (shared by both protocols) - - - - s15: MessageBus + spawn_teammate + inbox - - s16: request_id protocol + dispatch + pending_requests + state machine + + pending + + approve + + approved + + reject + + rejected + + + pending_requests Storage + pending_requests: dict[str, ProtocolState] + request_id → {type, sender, status, created_at} + match_response: find request by request_id + + + + Two protocols, one mechanism: + + shutdown_request + and + + plan_approval_request + Share the same pending → approved / rejected state machine. New protocol type = new msg_type, no new state machine needed. request_id links request and response. + + + + Note: + request_plan is a plain message (msg_type="message") sent by lead to prompt a plan submission. + submit_plan is the protocol entry point (msg_type="plan_approval_request"), initiated by teammate, carrying request_id into pending_requests. + + + + + s15: MessageBus + spawn_teammate + inbox + + s16: request_id protocol + dispatch + pending_requests + state machine diff --git a/s16_team_protocols/images/team-protocols-overview.ja.svg b/s16_team_protocols/images/team-protocols-overview.ja.svg index 28b368b9..f4a34f4e 100644 --- a/s16_team_protocols/images/team-protocols-overview.ja.svg +++ b/s16_team_protocols/images/team-protocols-overview.ja.svg @@ -1,4 +1,4 @@ - + @@ -9,9 +9,6 @@ - - - @@ -20,122 +17,125 @@ - + - Team Protocols — リクエスト・レスポンス + request_id 紐付け + 状態機械 - - s15 保持 - - s16 新規 + s15 維持 + + s16 新規 - + turn - - messages - - prompt - - LLM - - TOOL DISPATCH（コアツールセット） bash · read · write · task(4) · spawn · send · inbox ★ request_shutdown · request_plan · review_plan - - - - - リクエスト・レスポンスプロトコルフロー（request_id が全チェーンを貫通） + + + プロトコル A：shutdown フロー（Lead が開始 → チームメイトが応答） - - - ① Lead が要求送信 - BUS.send("shutdown_request" - metadata={request_id}) + + ① Lead: request_shutdown + new_request_id() → ProtocolState - + - - - ② チームメイト受信 - dispatch_by_type(inbox) - → handler(type, metadata) + + ② チームメイト: handle_shutdown + ack → shutdown_response - + - - - ③ チームメイト応答 - BUS.send("shutdown_response" - 同じ request_id + approve) + + ③ Lead: consume_lead_inbox + match_response(request_id) → ✓ - + + + プロトコル B：plan approval フロー（チームメイトが開始 → Lead が審査） - - - ④ Lead 応答受信 - match_response(request_id) - → resolve/reject callback + + 0. Lead: request_plan + 通常メッセージ（msg_type="message"） - - - 状態機械（2 つのプロトコルで共通） + - - pending + + ① チームメイト: submit_plan + plan_approval_request + request_id - - approve + - - approved + + ② Lead: review_plan + plan_approval_response - - reject + - - rejected + + ③ チームメイト: 受信 + [Plan approved/rejected] - - pending_requests ストレージ - pending_requests: dict[str, ProtocolState] - request_id → {type, sender, status, created_at} - match_response: request_id で要求を検索 + request_plan は通常メッセージでプロトコルではない。submit_plan がプロトコルエントリポイント（チームメイト側で ProtocolState を作成） - - - 2 つのプロトコル、1 つの仕組み： - - shutdown_request - と - - plan_approval_request - が pending→approved/rejected 状態機械を共有 - 新しいプロトコルタイプ = 新しい msg_type、新しい状態機械は不要。request_id が要求と応答を紐付け。 + + + 状態機械（両プロトコルで共用） - - - - s15: MessageBus + spawn_teammate + inbox - - s16: request_id プロトコル + dispatch + pending_requests + 状態機械 + + pending + + approve + + approved + + reject + + rejected + + + pending_requests ストレージ + pending_requests: dict[str, ProtocolState] + request_id → {type, sender, status, created_at} + match_response: request_id でリクエストを検索 + + + + 2つのプロトコル、1つのメカニズム： + + shutdown_request + と + + plan_approval_request + 同じ pending → approved / rejected 状態機械を共有。新しいプロトコルタイプ = 新しい msg_type、新しい状態機械は不要。request_id がリクエストとレスポンスを関連付ける。 + + + + 区別： + request_plan は通常メッセージ（msg_type="message"）で、lead がチームメイトに計画提出を促すために送信する。 + submit_plan がプロトコルエントリポイント（msg_type="plan_approval_request"）で、チームメイトが自発的に開始し、request_id を pending_requests に書き込む。 + + + + + s15: MessageBus + spawn_teammate + inbox + + s16: request_id プロトコル + dispatch + pending_requests + 状態機械 diff --git a/s16_team_protocols/images/team-protocols-overview.svg b/s16_team_protocols/images/team-protocols-overview.svg index 04a9a802..dcc53a0d 100644 --- a/s16_team_protocols/images/team-protocols-overview.svg +++ b/s16_team_protocols/images/team-protocols-overview.svg @@ -1,4 +1,4 @@ - + @@ -9,9 +9,6 @@ - - - @@ -20,129 +17,125 @@ - + - Team Protocols — 请求-响应协议 + request_id 关联 + 状态机 - s15 保留 s16 新增 - + turn - - messages - - prompt - - LLM - - TOOL DISPATCH（核心工具集） bash · read · write · task(4) · spawn · send · inbox ★ request_shutdown · request_plan · review_plan - - - - - 请求-响应协议流程（request_id 贯穿） + + + 协议 A：shutdown 流程（Lead 发起 → 队友响应） - - - ① Lead 发请求 - BUS.send("shutdown_request" - metadata={request_id}) + + ① Lead: request_shutdown + new_request_id() → ProtocolState - + - - - ② 队友收到 - dispatch_by_type(inbox) - → handler(type, metadata) + + ② 队友: handle_shutdown + ack → shutdown_response - + - - - ③ 队友回复 - BUS.send("shutdown_response" - 同 request_id + approve) + + ③ Lead: consume_lead_inbox + match_response(request_id) → ✓ - + + + 协议 B：plan approval 流程（队友发起 → Lead 审批） - - - ④ Lead 收响应 - match_response(request_id) - → resolve/reject callback + + 0. Lead: request_plan + 普通消息（msg_type="message"） - - - - 状态机（同一套，两种协议） + - - - pending + + ① 队友: submit_plan + plan_approval_request + request_id - - - approve + - - - approved + + ② Lead: review_plan + plan_approval_response - - - reject + - - - rejected + + ③ 队友: 收到结果 + [Plan approved/rejected] - - - pending_requests 存储 - pending_requests: dict[str, ProtocolState] - request_id → {type, sender, status, created_at} - match_response: 按 request_id 找回对应请求 + request_plan 是普通消息不是协议；submit_plan 才是协议入口（由队友端创建 ProtocolState） - - - 两种协议，同一套机制： - - shutdown_request - 和 - - plan_approval_request - 共用 pending→approved/rejected 状态机 - 新增协议类型 = 新的 msg_type，不需要新状态机。request_id 关联请求和响应。 + + + 状态机（同一套，两种协议共用） - - - - s15: MessageBus + spawn_teammate + inbox - - s16: request_id 协议 + dispatch + pending_requests + 状态机 + + pending + + approve + + approved + + reject + + rejected + + + pending_requests 存储 + pending_requests: dict[str, ProtocolState] + request_id → {type, sender, status, created_at} + match_response: 按 request_id 找回对应请求 + + + + 两种协议，同一套机制： + + shutdown_request + 和 + + plan_approval_request + 共用 pending → approved / rejected 状态机。新增协议类型 = 新的 msg_type，不需要新状态机。request_id 关联请求和响应。 + + + + 区分： + request_plan 是普通消息（msg_type="message"），由 lead 发送给队友提示去提交计划。 + submit_plan 才是协议入口（msg_type="plan_approval_request"），由队友主动发起，携带 request_id 写入 pending_requests。 + + + + + s15: MessageBus + spawn_teammate + inbox + + s16: request_id 协议 + dispatch + pending_requests + 状态机