From 9e44a1501b2a98525ea5a584c93447360a66cbb3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 16 Mar 2026 08:51:07 +0000 Subject: [PATCH 1/7] Initial plan From 986a14ddd19e22f4b518ccbef333597c2d09e497 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 16 Mar 2026 08:55:39 +0000 Subject: [PATCH 2/7] =?UTF-8?q?=E5=AE=8C=E5=96=84=20Protocol.v0.(zh-cn).md?= =?UTF-8?q?:=20=E6=B7=BB=E5=8A=A0=20cmd-resp=20=E6=8F=A1=E6=89=8B=E8=AF=B4?= =?UTF-8?q?=E6=98=8E=E5=92=8C=E9=80=9A=E4=BF=A1=E6=B5=81=E7=A8=8B=E5=9B=BE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: nevstop <8196752+nevstop@users.noreply.github.com> --- .doc/Protocol.v0.(zh-cn).md | 102 +++++++++++++++++++++++++++++++++++- 1 file changed, 100 insertions(+), 2 deletions(-) diff --git a/.doc/Protocol.v0.(zh-cn).md b/.doc/Protocol.v0.(zh-cn).md index 1812fd3..62a78a8 100644 --- a/.doc/Protocol.v0.(zh-cn).md +++ b/.doc/Protocol.v0.(zh-cn).md @@ -25,7 +25,7 @@ CSM-TCP-Router 中 TCP 数据包格式定义如下： - 错误数据包(error) - `0x01` - 指令数据包(cmd) - `0x02` - 指令响应数据包(cmd-resp) - `0x03` -- 同步响应数据包(resp) - `0x03` +- 同步响应数据包(resp) - `[待确认]` - 异步响应数据包(async-resp) - `0x04` - 订阅普通广播返回数据包(status) - `0x05` - 订阅中断广播返回数据包(interrupt) - `0x06` @@ -95,16 +95,114 @@ error 数据包的数据内容为错误信息内容，为纯文本格式，文 > 当 A 模块发出 Status 后，client 将自动收到 `status` 数据包 > +### 指令响应数据包(cmd-resp) + +所有的指令数据包(cmd)在被服务端接收并处理后，都会有一个握手返回： + +- **正常情况**：返回 `cmd-resp` 数据包，表示指令已被接受并触发执行。 +- **错误情况**：返回 `error` 数据包，表示指令执行出现错误。 + +> [!NOTE] +> `cmd-resp` 是对指令的握手确认，表示指令已被接受并开始执行，不包含业务响应数据。 +> 业务响应数据由 `resp` 或 `async-resp` 数据包返回。 +> + ### 同步响应数据包(resp) 当执行完毕同步消息指令后，tcp-router 将 response 返回给 client. ### 异步响应数据包(async-resp) -当执行完毕同步消息指令后，tcp-router 将 response 返回给 client. 格式为："`Response数据` <- `异步消息原文`" +当执行完毕异步消息指令后，tcp-router 将 response 返回给 client. 格式为："`Response数据` <- `异步消息原文`" ### 订阅返回数据包(status) Client 订阅了CSM模块的状态，当状态发生时，client 会自动收到此数据包。 数据包格式为 "状态名 >> `状态数据` <- 发送模块" + +## 通信流程 + +### 同步消息流程 (`-@`) + +客户端发送同步指令后，**必须等待**服务端依次返回 `cmd-resp`（握手确认）和 `resp`（同步业务响应数据）后，才算完成一次完整交互。若指令执行出错，则仅返回 `error` 数据包。 + +```mermaid +sequenceDiagram + participant C as Client + participant S as TCP-Router Server + + C->>S: cmd (同步消息 -@) + alt 指令执行成功 + S-->>C: cmd-resp (指令已接受) + S-->>C: resp (同步响应数据) + else 指令执行失败 + S-->>C: error (错误信息) + end +``` + +### 异步消息流程 (`->`) + +客户端发送异步指令后，服务端立即返回 `cmd-resp` 握手确认。客户端**无需等待**业务响应，可继续发送其他指令。业务处理完成后，服务端异步返回 `async-resp` 数据包。若指令执行出错，则仅返回 `error` 数据包。 + +```mermaid +sequenceDiagram + participant C as Client + participant S as TCP-Router Server + + C->>S: cmd (异步消息 ->) + alt 指令执行成功 + S-->>C: cmd-resp (指令已接受) + Note over S: 异步处理中... + S-->>C: async-resp (异步响应数据) + else 指令执行失败 + S-->>C: error (错误信息) + end +``` + +### 异步无返回消息流程 (`->|`) + +客户端发送异步无返回指令后，服务端立即返回 `cmd-resp` 握手确认。业务处理完成后**不会**返回业务响应数据包。若指令执行出错，则返回 `error` 数据包。 + +```mermaid +sequenceDiagram + participant C as Client + participant S as TCP-Router Server + + C->>S: cmd (异步无返回消息 ->|) + alt 指令执行成功 + S-->>C: cmd-resp (指令已接受) + else 指令执行失败 + S-->>C: error (错误信息) + end +``` + +### 订阅/注销流程 (`` / ``) + +客户端发送订阅或注销指令后，服务端返回 `cmd-resp` 握手确认。订阅成功后，每当被订阅模块发出状态，客户端会持续收到 `status` 数据包，直到取消订阅。 + +```mermaid +sequenceDiagram + participant C as Client + participant S as TCP-Router Server + participant M as CSM 模块 + + C->>S: cmd ( 订阅) + alt 订阅成功 + S-->>C: cmd-resp (订阅已接受) + Note over M,S: 模块状态变化时... + M->>S: 状态广播 + S-->>C: status (状态数据) + M->>S: 状态广播 + S-->>C: status (状态数据) + else 订阅失败 + S-->>C: error (错误信息) + end + + C->>S: cmd ( 取消订阅) + alt 取消成功 + S-->>C: cmd-resp (取消订阅已接受) + else 取消失败 + S-->>C: error (错误信息) + end +``` From fa813680cdad711f3ce25161ed79855d2a262da2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 16 Mar 2026 10:10:34 +0000 Subject: [PATCH 3/7] =?UTF-8?q?=E6=A0=B9=E6=8D=AE=E5=AE=A1=E6=9F=A5?= =?UTF-8?q?=E6=84=8F=E8=A7=81=E6=9B=B4=E6=96=B0=20Protocol.v0.(zh-cn).md?= =?UTF-8?q?=EF=BC=9A=E4=BF=AE=E6=AD=A3=E5=8C=85=E7=B1=BB=E5=9E=8B=E5=80=BC?= =?UTF-8?q?=E3=80=81=E5=90=8C=E6=AD=A5=E6=B5=81=E7=A8=8B=E5=92=8C=E5=BC=82?= =?UTF-8?q?=E6=AD=A5=E6=B5=81=E7=A8=8B=E5=9B=BE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: nevstop <8196752+nevstop@users.noreply.github.com> --- .doc/Protocol.v0.(zh-cn).md | 41 ++++++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 17 deletions(-) diff --git a/.doc/Protocol.v0.(zh-cn).md b/.doc/Protocol.v0.(zh-cn).md index 62a78a8..bb1a9f4 100644 --- a/.doc/Protocol.v0.(zh-cn).md +++ b/.doc/Protocol.v0.(zh-cn).md @@ -25,10 +25,10 @@ CSM-TCP-Router 中 TCP 数据包格式定义如下： - 错误数据包(error) - `0x01` - 指令数据包(cmd) - `0x02` - 指令响应数据包(cmd-resp) - `0x03` -- 同步响应数据包(resp) - `[待确认]` -- 异步响应数据包(async-resp) - `0x04` -- 订阅普通广播返回数据包(status) - `0x05` -- 订阅中断广播返回数据包(interrupt) - `0x06` +- 同步响应数据包(resp) - `0x04` +- 异步响应数据包(async-resp) - `0x05` +- 订阅普通广播返回数据包(status) - `0x06` +- 订阅中断广播返回数据包(interrupt) - `0x07` ### FLAG1类型(1字节) @@ -97,14 +97,16 @@ error 数据包的数据内容为错误信息内容，为纯文本格式，文 ### 指令响应数据包(cmd-resp) -所有的指令数据包(cmd)在被服务端接收并处理后，都会有一个握手返回： +除同步消息(-@)外，其他指令数据包(cmd)在被服务端接收并处理后，都会有一个握手返回： - **正常情况**：返回 `cmd-resp` 数据包，表示指令已被接受并触发执行。 - **错误情况**：返回 `error` 数据包，表示指令执行出现错误。 > [!NOTE] > `cmd-resp` 是对指令的握手确认，表示指令已被接受并开始执行，不包含业务响应数据。 -> 业务响应数据由 `resp` 或 `async-resp` 数据包返回。 +> 业务响应数据由 `async-resp` 数据包返回。 +> +> 同步消息(-@)没有 `cmd-resp` 握手，执行完成后直接返回 `resp` 或 `error`。 > ### 同步响应数据包(resp) @@ -125,7 +127,7 @@ Client 订阅了CSM模块的状态，当状态发生时，client 会自动收到 ### 同步消息流程 (`-@`) -客户端发送同步指令后，**必须等待**服务端依次返回 `cmd-resp`（握手确认）和 `resp`（同步业务响应数据）后，才算完成一次完整交互。若指令执行出错，则仅返回 `error` 数据包。 +客户端发送同步指令后，**必须等待**服务端返回 `resp`（同步业务响应数据）后，才算完成一次完整交互。同步消息没有 `cmd-resp` 握手包。若指令执行出错，则返回 `error` 数据包。 ```mermaid sequenceDiagram @@ -134,7 +136,6 @@ sequenceDiagram C->>S: cmd (同步消息 -@) alt 指令执行成功 - S-->>C: cmd-resp (指令已接受) S-->>C: resp (同步响应数据) else 指令执行失败 S-->>C: error (错误信息) @@ -143,7 +144,7 @@ sequenceDiagram ### 异步消息流程 (`->`) -客户端发送异步指令后，服务端立即返回 `cmd-resp` 握手确认。客户端**无需等待**业务响应，可继续发送其他指令。业务处理完成后，服务端异步返回 `async-resp` 数据包。若指令执行出错，则仅返回 `error` 数据包。 +客户端发送异步指令后，服务端立即返回 `cmd-resp` 握手确认。客户端**无需等待**业务响应，可继续发送其他指令。业务处理完成后，服务端异步返回 `async-resp` 数据包；若处理出错，则返回 `error` 数据包（不再返回 `async-resp`）。 ```mermaid sequenceDiagram @@ -151,11 +152,11 @@ sequenceDiagram participant S as TCP-Router Server C->>S: cmd (异步消息 ->) - alt 指令执行成功 - S-->>C: cmd-resp (指令已接受) - Note over S: 异步处理中... + S-->>C: cmd-resp (指令已接受) + Note over S: 异步处理中... + alt 执行成功 S-->>C: async-resp (异步响应数据) - else 指令执行失败 + else 执行出错 S-->>C: error (错误信息) end ``` @@ -179,7 +180,13 @@ sequenceDiagram ### 订阅/注销流程 (`` / ``) -客户端发送订阅或注销指令后，服务端返回 `cmd-resp` 握手确认。订阅成功后，每当被订阅模块发出状态，客户端会持续收到 `status` 数据包，直到取消订阅。 +客户端发送订阅或注销指令后，服务端返回 `cmd-resp` 握手确认。订阅成功后，每当被订阅模块发出状态，客户端会持续收到 `status` 数据包（普通广播）或 `interrupt` 数据包（中断广播），直到取消订阅。 + +> [!NOTE] +> `status` 和 `interrupt` 两种订阅广播类型均受支持： +> - `status`（`0x06`）：普通广播，订阅模块的常规状态变化 +> - `interrupt`（`0x07`）：中断广播，订阅模块触发的中断事件 +> ```mermaid sequenceDiagram @@ -191,10 +198,10 @@ sequenceDiagram alt 订阅成功 S-->>C: cmd-resp (订阅已接受) Note over M,S: 模块状态变化时... - M->>S: 状态广播 - S-->>C: status (状态数据) - M->>S: 状态广播 + M->>S: 普通状态广播 S-->>C: status (状态数据) + M->>S: 中断广播 + S-->>C: interrupt (中断数据) else 订阅失败 S-->>C: error (错误信息) end From 70ad5bd6db333e5dbdfea99db8041f0a79f6bca1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 16 Mar 2026 10:19:09 +0000 Subject: [PATCH 4/7] =?UTF-8?q?=E6=A0=B9=E6=8D=AE=E5=AE=A1=E6=9F=A5?= =?UTF-8?q?=E6=84=8F=E8=A7=81=E4=BF=AE=E6=AD=A3=20cmd-resp=20=E6=B3=A8?= =?UTF-8?q?=E9=87=8A=E3=80=81=E5=90=8C=E6=AD=A5=E6=B5=81=E7=A8=8B=E8=AF=B4?= =?UTF-8?q?=E6=98=8E=E5=8F=8A=E5=BC=82=E6=AD=A5=E6=B5=81=E7=A8=8B=E5=9B=BE?= =?UTF-8?q?=E9=80=BB=E8=BE=91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: nevstop <8196752+nevstop@users.noreply.github.com> --- .doc/Protocol.v0.(zh-cn).md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.doc/Protocol.v0.(zh-cn).md b/.doc/Protocol.v0.(zh-cn).md index bb1a9f4..c730498 100644 --- a/.doc/Protocol.v0.(zh-cn).md +++ b/.doc/Protocol.v0.(zh-cn).md @@ -104,7 +104,7 @@ error 数据包的数据内容为错误信息内容，为纯文本格式，文 > [!NOTE] > `cmd-resp` 是对指令的握手确认，表示指令已被接受并开始执行，不包含业务响应数据。 -> 业务响应数据由 `async-resp` 数据包返回。 +> 业务响应数据由 `resp` 或 `async-resp` 数据包返回。 > > 同步消息(-@)没有 `cmd-resp` 握手，执行完成后直接返回 `resp` 或 `error`。 > @@ -127,7 +127,7 @@ Client 订阅了CSM模块的状态，当状态发生时，client 会自动收到 ### 同步消息流程 (`-@`) -客户端发送同步指令后，**必须等待**服务端返回 `resp`（同步业务响应数据）后，才算完成一次完整交互。同步消息没有 `cmd-resp` 握手包。若指令执行出错，则返回 `error` 数据包。 +客户端发送同步指令后，**必须等待**服务端返回响应：要么收到 `resp`（同步业务响应数据），要么收到 `error`（错误信息）。同步消息没有 `cmd-resp` 握手包。 ```mermaid sequenceDiagram @@ -144,7 +144,7 @@ sequenceDiagram ### 异步消息流程 (`->`) -客户端发送异步指令后，服务端立即返回 `cmd-resp` 握手确认。客户端**无需等待**业务响应，可继续发送其他指令。业务处理完成后，服务端异步返回 `async-resp` 数据包；若处理出错，则返回 `error` 数据包（不再返回 `async-resp`）。 +客户端发送异步指令后，服务端首先返回确认包：要么是 `cmd-resp`（指令已接受），要么是 `error`（指令被拒绝）。若收到 `cmd-resp`，客户端**无需等待**业务响应，可继续发送其他指令；服务端异步处理完毕后，返回 `async-resp` 数据包。 ```mermaid sequenceDiagram @@ -152,11 +152,11 @@ sequenceDiagram participant S as TCP-Router Server C->>S: cmd (异步消息 ->) - S-->>C: cmd-resp (指令已接受) - Note over S: 异步处理中... - alt 执行成功 + alt 指令接受 + S-->>C: cmd-resp (指令已接受) + Note over S: 异步处理中... S-->>C: async-resp (异步响应数据) - else 执行出错 + else 指令被拒绝 S-->>C: error (错误信息) end ``` From 98de0c6ab73651d09380d813fde4d3546173caf2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 16 Mar 2026 10:37:19 +0000 Subject: [PATCH 5/7] =?UTF-8?q?=E7=BB=9F=E4=B8=80=20error=20=E5=8C=85?= =?UTF-8?q?=E6=8F=8F=E8=BF=B0=EF=BC=8C=E4=BF=AE=E6=AD=A3=E5=BC=82=E6=AD=A5?= =?UTF-8?q?=E6=97=A0=E8=BF=94=E5=9B=9E=E6=B5=81=E7=A8=8B=E6=96=87=E5=AD=97?= =?UTF-8?q?=E4=B8=8E=E5=9B=BE=E8=A1=A8=E4=B8=80=E8=87=B4=E6=80=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: nevstop <8196752+nevstop@users.noreply.github.com> --- .doc/Protocol.v0.(zh-cn).md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.doc/Protocol.v0.(zh-cn).md b/.doc/Protocol.v0.(zh-cn).md index c730498..9fca69d 100644 --- a/.doc/Protocol.v0.(zh-cn).md +++ b/.doc/Protocol.v0.(zh-cn).md @@ -100,7 +100,7 @@ error 数据包的数据内容为错误信息内容，为纯文本格式，文 除同步消息(-@)外，其他指令数据包(cmd)在被服务端接收并处理后，都会有一个握手返回： - **正常情况**：返回 `cmd-resp` 数据包，表示指令已被接受并触发执行。 -- **错误情况**：返回 `error` 数据包，表示指令执行出现错误。 +- **错误情况**：返回 `error` 数据包，表示指令未被接受或执行出现错误（如目标模块不存在、执行失败等）。 > [!NOTE] > `cmd-resp` 是对指令的握手确认，表示指令已被接受并开始执行，不包含业务响应数据。 @@ -144,7 +144,7 @@ sequenceDiagram ### 异步消息流程 (`->`) -客户端发送异步指令后，服务端首先返回确认包：要么是 `cmd-resp`（指令已接受），要么是 `error`（指令被拒绝）。若收到 `cmd-resp`，客户端**无需等待**业务响应，可继续发送其他指令；服务端异步处理完毕后，返回 `async-resp` 数据包。 +客户端发送异步指令后，服务端首先返回确认包：要么是 `cmd-resp`（指令已接受），要么是 `error`（指令未被接受或执行出现错误）。若收到 `cmd-resp`，客户端**无需等待**业务响应，可继续发送其他指令；服务端异步处理完毕后，返回 `async-resp` 数据包。 ```mermaid sequenceDiagram @@ -152,18 +152,18 @@ sequenceDiagram participant S as TCP-Router Server C->>S: cmd (异步消息 ->) - alt 指令接受 + alt 指令已接受 S-->>C: cmd-resp (指令已接受) Note over S: 异步处理中... S-->>C: async-resp (异步响应数据) - else 指令被拒绝 + else 未被接受或执行出错 S-->>C: error (错误信息) end ``` ### 异步无返回消息流程 (`->|`) -客户端发送异步无返回指令后，服务端立即返回 `cmd-resp` 握手确认。业务处理完成后**不会**返回业务响应数据包。若指令执行出错，则返回 `error` 数据包。 +客户端发送异步无返回指令后，服务端首先返回确认包：要么是 `cmd-resp`（指令已接受），要么是 `error`（指令未被接受或执行出现错误）。指令被接受后，业务处理完成后**不会**返回业务响应数据包。 ```mermaid sequenceDiagram @@ -171,9 +171,9 @@ sequenceDiagram participant S as TCP-Router Server C->>S: cmd (异步无返回消息 ->|) - alt 指令执行成功 + alt 指令已接受 S-->>C: cmd-resp (指令已接受) - else 指令执行失败 + else 未被接受或执行出错 S-->>C: error (错误信息) end ``` From c74bb567c9202788530c0663e93213a68aad43c7 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 16 Mar 2026 12:18:38 +0000 Subject: [PATCH 6/7] Add info packet documentation for connection/disconnection events Co-authored-by: nevstop <8196752+nevstop@users.noreply.github.com> --- .doc/Protocol.v0.(en).md | 16 ++++++++++++++++ .doc/Protocol.v0.(zh-cn).md | 16 ++++++++++++++++ README(zh-cn).md | 2 +- README.md | 2 +- 4 files changed, 34 insertions(+), 2 deletions(-) diff --git a/.doc/Protocol.v0.(en).md b/.doc/Protocol.v0.(en).md index 8d3c0e1..bc8119c 100644 --- a/.doc/Protocol.v0.(en).md +++ b/.doc/Protocol.v0.(en).md @@ -42,6 +42,22 @@ Similar to FLAG1, this field is reserved for future use to describe additional a The content of an information packet is plain text containing informational data. +The server sends an `info` packet to the client in two specific situations: + +- **On Connection**: When a client successfully connects to the server, the server sends a welcome `info` packet: + + ``` + Welcome to the CSM TCP Router Server + API: "list", "list api", "list states", "help" + type "bye" to close connection from Server side. + ``` + +- **On Disconnection**: When the connection is closed from the server side, the server sends a goodbye `info` packet: + + ``` + Good bye. + ``` + ### Error Packet (`error`) The content of an error packet is plain text describing an error, formatted as per the CSM Error format. diff --git a/.doc/Protocol.v0.(zh-cn).md b/.doc/Protocol.v0.(zh-cn).md index 9fca69d..e4f5321 100644 --- a/.doc/Protocol.v0.(zh-cn).md +++ b/.doc/Protocol.v0.(zh-cn).md @@ -44,6 +44,22 @@ FLAG2用于描述数据包的属性, 保留字段。 info 数据包的数据内容为提示信息内容，纯文本格式。 +服务端会在以下两种情况下向客户端发送 `info` 数据包： + +- **连接时**：客户端成功连接到服务器后，服务端发送欢迎 `info` 数据包： + + ``` + Welcome to the CSM TCP Router Server + API: "list", "list api", "list states", "help" + type "bye" to close connection from Server side. + ``` + +- **断开连接时**：当连接从服务端侧关闭时，服务端发送告别 `info` 数据包： + + ``` + Good bye. + ``` + ### 错误数据包(error) error 数据包的数据内容为错误信息内容，为纯文本格式，文本格式定为 CSM Error 格式。 diff --git a/README(zh-cn).md b/README(zh-cn).md index d5ee298..7ea7b3f 100644 --- a/README(zh-cn).md +++ b/README(zh-cn).md @@ -23,7 +23,7 @@ CSM-TCP-Router 中 TCP 数据包格式定义如下： 数据包类型用于描述数据包的内容，为枚举类型，目前支持的数据包类型有： -- 信息数据包(info) - `0x00` +- 信息数据包(info) - `0x00`：服务端在客户端连接时（欢迎消息）和连接关闭时（告别消息）发送 - 错误数据包(error) - `0x01` - 指令数据包(cmd) - `0x02` - 同步响应数据包(resp) - `0x03` diff --git a/README.md b/README.md index d7161ef..1e391a7 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ The TCP packet format used in the CSM-TCP-Router is defined as follows: This field defines the type of the data packet and is an enumerated value. The supported packet types are: -- Information Packet (`info`) - `0x00` +- Information Packet (`info`) - `0x00`: Sent by the server when a client connects (welcome message) and when the connection is closed (goodbye message) - Error Packet (`error`) - `0x01` - Command Packet (`cmd`) - `0x02` - Synchronous Response Packet (`resp`) - `0x03` From cd8b5bda2c05eaa217a990a3207688eca49be9fb Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 16 Mar 2026 12:51:51 +0000 Subject: [PATCH 7/7] Sync EN/ZH protocol and README files for consistency Co-authored-by: nevstop <8196752+nevstop@users.noreply.github.com> --- .doc/Protocol.v0.(en).md | 113 +++++++++++++++++++++++++++++++++++++-- README(zh-cn).md | 10 ++-- README.md | 8 +-- 3 files changed, 121 insertions(+), 10 deletions(-) diff --git a/.doc/Protocol.v0.(en).md b/.doc/Protocol.v0.(en).md index bc8119c..b19f110 100644 --- a/.doc/Protocol.v0.(en).md +++ b/.doc/Protocol.v0.(en).md @@ -24,9 +24,11 @@ This field defines the type of the data packet and is an enumerated value. The s - Information Packet (`info`) - `0x00` - Error Packet (`error`) - `0x01` - Command Packet (`cmd`) - `0x02` -- Synchronous Response Packet (`resp`) - `0x03` -- Asynchronous Response Packet (`async-resp`) - `0x04` -- Subscription Status Packet (`status`) - `0x05` +- Command Response Packet (`cmd-resp`) - `0x03` +- Synchronous Response Packet (`resp`) - `0x04` +- Asynchronous Response Packet (`async-resp`) - `0x05` +- Subscription Normal Broadcast Packet (`status`) - `0x06` +- Subscription Interrupt Broadcast Packet (`interrupt`) - `0x07` ### FLAG1 (1 Byte) @@ -105,6 +107,20 @@ The content of a command packet is a command in the CSM local command format. It > > When module `A` sends a `Status`, the client will automatically receive a `status` packet. +### Command Response Packet (`cmd-resp`) + +Except for synchronous messages (`-@`), all other command packets (`cmd`) receive a handshake response after being received and processed by the server: + +- **Normal case**: A `cmd-resp` packet is returned, indicating the command has been accepted and triggered for execution. +- **Error case**: An `error` packet is returned, indicating the command was not accepted or an error occurred during execution (e.g., the target module does not exist, execution failed, etc.). + +> [!NOTE] +> `cmd-resp` is a handshake acknowledgment of the command, indicating that the command has been accepted and execution has started. It does not contain business response data. +> Business response data is returned via `resp` or `async-resp` packets. +> +> Synchronous messages (`-@`) do not have a `cmd-resp` handshake; upon completion, they directly return `resp` or `error`. +> + ### Synchronous Response Packet (`resp`) After executing a synchronous command, the TCP router sends a response packet back to the client. @@ -118,3 +134,94 @@ After executing an asynchronous command, the TCP router sends a response packet When a client subscribes to the status of a CSM module, it will automatically receive this packet whenever the status changes. The packet format is: `Status Name >> Status Data <- Sending Module`. + +## Communication Flow + +### Synchronous Message Flow (`-@`) + +After the client sends a synchronous command, it **must wait** for the server to return a response: either a `resp` (synchronous response data) or an `error` (error message). Synchronous messages do not have a `cmd-resp` handshake packet. + +```mermaid +sequenceDiagram + participant C as Client + participant S as TCP-Router Server + + C->>S: cmd (synchronous message -@) + alt Command executed successfully + S-->>C: resp (synchronous response data) + else Command execution failed + S-->>C: error (error message) + end +``` + +### Asynchronous Message Flow (`->`) + +After the client sends an asynchronous command, the server first returns a confirmation packet: either `cmd-resp` (command accepted) or `error` (command not accepted or execution error). Upon receiving `cmd-resp`, the client **does not need to wait** for the business response and can continue sending other commands; after asynchronous processing is complete, the server returns an `async-resp` packet. + +```mermaid +sequenceDiagram + participant C as Client + participant S as TCP-Router Server + + C->>S: cmd (asynchronous message ->) + alt Command accepted + S-->>C: cmd-resp (command accepted) + Note over S: Processing asynchronously... + S-->>C: async-resp (asynchronous response data) + else Not accepted or execution error + S-->>C: error (error message) + end +``` + +### Asynchronous Without Return Flow (`->|`) + +After the client sends an asynchronous without return command, the server first returns a confirmation packet: either `cmd-resp` (command accepted) or `error` (command not accepted or execution error). Once the command is accepted, **no** business response packet will be returned after processing is complete. + +```mermaid +sequenceDiagram + participant C as Client + participant S as TCP-Router Server + + C->>S: cmd (asynchronous without return ->|) + alt Command accepted + S-->>C: cmd-resp (command accepted) + else Not accepted or execution error + S-->>C: error (error message) + end +``` + +### Subscribe/Unsubscribe Flow (`` / ``) + +After the client sends a subscribe or unsubscribe command, the server returns a `cmd-resp` handshake confirmation. Once subscribed, whenever the subscribed module emits a status, the client continuously receives `status` packets (normal broadcast) or `interrupt` packets (interrupt broadcast), until unsubscribed. + +> [!NOTE] +> Both `status` and `interrupt` subscription broadcast types are supported: +> - `status` (`0x06`): Normal broadcast, subscribes to regular status changes of the module +> - `interrupt` (`0x07`): Interrupt broadcast, subscribes to interrupt events triggered by the module +> + +```mermaid +sequenceDiagram + participant C as Client + participant S as TCP-Router Server + participant M as CSM Module + + C->>S: cmd ( subscribe) + alt Subscription successful + S-->>C: cmd-resp (subscription accepted) + Note over M,S: When module status changes... + M->>S: Normal status broadcast + S-->>C: status (status data) + M->>S: Interrupt broadcast + S-->>C: interrupt (interrupt data) + else Subscription failed + S-->>C: error (error message) + end + + C->>S: cmd ( unsubscribe) + alt Unsubscription successful + S-->>C: cmd-resp (unsubscription accepted) + else Unsubscription failed + S-->>C: error (error message) + end +``` diff --git a/README(zh-cn).md b/README(zh-cn).md index 7ea7b3f..bbceee0 100644 --- a/README(zh-cn).md +++ b/README(zh-cn).md @@ -17,7 +17,7 @@ CSM-TCP-Router 中 TCP 数据包格式定义如下： ``` -| 数据长度(4B) | 版本(1B) | FLAG1(1B) | FLAG2(1B) | TYPE(1B) | 文本数据 | +| 数据长度(4B) | 版本(1B) | TYPE(1B) | FLAG1(1B) | FLAG2(1B) | 文本数据 | ╰─────────────────────────── 包头 ──────────────────────────╯╰──── 数据长度字范围 ────╯ ``` @@ -26,9 +26,11 @@ CSM-TCP-Router 中 TCP 数据包格式定义如下： - 信息数据包(info) - `0x00`：服务端在客户端连接时（欢迎消息）和连接关闭时（告别消息）发送 - 错误数据包(error) - `0x01` - 指令数据包(cmd) - `0x02` -- 同步响应数据包(resp) - `0x03` -- 异步响应数据包(async-resp) - `0x04` -- 订阅返回数据包(status) - `0x05` +- 指令响应数据包(cmd-resp) - `0x03` +- 同步响应数据包(resp) - `0x04` +- 异步响应数据包(async-resp) - `0x05` +- 订阅普通广播返回数据包(status) - `0x06` +- 订阅中断广播返回数据包(interrupt) - `0x07` 详细的通讯协议定义, 见 [协议设计](.doc/Protocol.v0.(zh-cn).md) diff --git a/README.md b/README.md index 1e391a7..2a3a2c2 100644 --- a/README.md +++ b/README.md @@ -26,9 +26,11 @@ This field defines the type of the data packet and is an enumerated value. The s - Information Packet (`info`) - `0x00`: Sent by the server when a client connects (welcome message) and when the connection is closed (goodbye message) - Error Packet (`error`) - `0x01` - Command Packet (`cmd`) - `0x02` -- Synchronous Response Packet (`resp`) - `0x03` -- Asynchronous Response Packet (`async-resp`) - `0x04` -- Subscription Status Packet (`status`) - `0x05` +- Command Response Packet (`cmd-resp`) - `0x03` +- Synchronous Response Packet (`resp`) - `0x04` +- Asynchronous Response Packet (`async-resp`) - `0x05` +- Subscription Normal Broadcast Packet (`status`) - `0x06` +- Subscription Interrupt Broadcast Packet (`interrupt`) - `0x07` For detailed communication protocol definitions, see [Protocol Design](.doc/Protocol.v0.(en).md).