From 36a70ca7ffe98ba6aafc4b88b98d57d4ea8b48a3 Mon Sep 17 00:00:00 2001 From: yyyytawa <116234899+yyyytawa@users.noreply.github.com> Date: Fri, 3 Jul 2026 20:33:02 +0800 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20=E6=A0=BC=E5=BC=8F=E5=8C=96+?= =?UTF-8?q?=E6=96=B0=E5=A2=9E=20API?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/api/v1/instruction.md | 55 +--- src/api/v1/misc.md | 7 + src/api/wss/chat-ws-go.jwzhd.com.md | 407 ++++------------------------ src/full.proto | 164 +++++++++-- 4 files changed, 210 insertions(+), 423 deletions(-) diff --git a/src/api/v1/instruction.md b/src/api/v1/instruction.md index d5ea2450..3f2c6ef2 100644 --- a/src/api/v1/instruction.md +++ b/src/api/v1/instruction.md @@ -177,61 +177,14 @@ POST /v1/instruction/list | ----- | ---- | ---- | | token | 是 | 无 | -请求体： +请求体 ```protobuf -id: "123123123" + ``` -::: details ProtoBuf 数据结构 - -```proto -message get_bot_instruction { - string id = 3; -} -``` - -::: - -响应体： +响应体 ```protobuf -status { - request_id: 123456 - code: 1 - msg: "success" -} -data { - command_id: 123 // 指令 id - bot_id： 123123123 // 机器人 id - command_name: "测试指令名称" // 指令名称 - instruction_type: 5 // 指令类型: 1-普通指令，2-直发指令，5-自定义输入指令 - command_defaultText: "测试默认输入文本" // 指令输入框默认文本 - command_settingsJso: "{}" // 指令设置 JSON（表单指令，自定义输入指令） -} + ``` - -::: details ProtoBuf 数据结构 - -```proto -message Status { - uint64 request_id = 1; - uint64 code = 2; - string msg = 3; -} - -message instruction_list { - Status status = 1; - Data data = 2; - message Data { - uint64 command_id = 1; // 指令 id - string bot_id = 2; // 机器人 id - string command_name = 3; // 指令名称 - uint64 instruction_type = 5; // 指令类型: 1-普通指令，2-直发指令，5-自定义输入指令 - string command_defaultText = 7; // 指令输入框默认文本 - string command_settingsJson = 10; // 指令设置 JSON（表单指令，自定义输入指令） - } -} -``` - -::: diff --git a/src/api/v1/misc.md b/src/api/v1/misc.md index 0a989eab..fa7d7abd 100644 --- a/src/api/v1/misc.md +++ b/src/api/v1/misc.md @@ -48,6 +48,13 @@ GET /v1/misc/configure-distribution 如果你的能力足够推荐使用分片上传 V2 版,支持断点续传,占用更小. ~~或者是直接用七牛 kodo 的 SDK.~~ +通过 access_key 和 bucket 获取上传 Host方法: +注意: 这不是七牛官方文档中的内容,但是确实是七牛官方 SDK 在用的 API. + +GET `https://api.qiniu.com/v4/query?ak=&bucket=` + +响应中 `up` 下的域名就是上传 Host. + ::: ## 获取图片上传token diff --git a/src/api/wss/chat-ws-go.jwzhd.com.md b/src/api/wss/chat-ws-go.jwzhd.com.md index da222b43..c3ba8c15 100644 --- a/src/api/wss/chat-ws-go.jwzhd.com.md +++ b/src/api/wss/chat-ws-go.jwzhd.com.md @@ -8,20 +8,29 @@ title: chat-ws-go.jwzhd.com 如果登录失败或未登录直接发送数据，会返回"数据不合法"或其二进制格式或无任何响应。 -本教程中未特别说明情况下 proto 的 INFO 均为以下部分: +本教程中未特别说明情况下 proto 的 WsInfo 均为以下部分: -```proto -message INFO { - string seq = 1; // 请求标识码 - string cmd = 2; // 操作类型 -} +```protobuf + +``` + +::: warning +请先在 proto 文件中添加 `import "google/protobuf/any.proto";` 以支持 Any 类型. +此处使用的是 Protobuf 的 Wrapper,解析时请务必注意!Wrapper 结构如下: + +```protobuf + ``` +下述 ws 的 proto 结构均为均为不带 Wrapper 的结构. + +::: + ## 登录云湖账号 -### 发送数据 +发送数据 -```JSONC +```JSON { "seq": "123123123123123123123", // 请求标识码，可以随便写 "cmd": "login", // 为login，代表登录 @@ -34,7 +43,7 @@ message INFO { } ``` -### 允许的平台 +允许的平台 注：**大小写敏感，填写错误会导致登录失败**. @@ -48,9 +57,9 @@ message INFO { ## 发送心跳包 -### 发送数据 +发送数据 -```JSONC +```JSON { "seq": "123123123123123123123", // 请求标识码，可以随便写 "cmd": "heartbeat", // 为heartbeat，代表心跳包 @@ -58,223 +67,57 @@ message INFO { } ``` -### 返回数据 +返回数据 -```ProtoBuf -data: { - seq: "123123123123123123123", // 请求标识码 - cmd: "heartbeat_ack" // 为heartbeat_ack，代表心跳包的返回 -} -``` - -::: details ProtoBuf数据结构 - -```proto +```protobuf // 心跳包返回信息 -message heartbeat_ack_info { - Data data = 1; //数据 - message Data { - string id = 1; // 请求标识码，可以随便写 - string cmd = 2; // 为heartbeat，代表心跳包 - } -} + ``` -::: - -## 发送草稿同步 +## 草稿同步 -### 发送数据 +发送草稿同步 -```JSONC +```JSON { "seq": "123123123123123123123", // 请求标识码，可以随便写 "cmd": "inputInfo", // 为inputInfo，代表发送草稿同步 "data": { "chatId": "872440499", // 对象 ID "input": "测试草稿同步", // 草稿同步内容,会直接覆盖原有的草稿 - "deviceId": "123" // 设备唯一识别码 + "deviceId": "123" // 设备 ID } } ``` -## 接收草稿同步 - -### 返回数据 - -```ProtoBuf -info { - seq: "abcdef" // 请求标识符 - cmd: "draft_input" // 操作类型 -} +接收草稿同步 -data { - any: "type.googleapis.com/proto.MsgInput" // ProtoBuf 的 any 字段 - draft { - chat_id: "8826687" // 聊天对象ID - input: "测试草稿同步" // 草稿内容,注意是覆盖不是追加 - } -} +```protobuf +// 接收草稿同步 + ``` -::: details ProtoBuf数据结构 - -```proto -// 草稿同步 -message draft_input { - INFO info = 1; - Data data = 2; - - message Data { - string any = 1; - Draft draft = 2; - - message Draft { - string chat_id = 1; // 对象ID - string input = 2; // 草稿内容 - } - } -} -``` - -::: - ## 推送消息 -### 返回数据 - -```ProtoBuf -info { - seq: "1234567abcd" // 请求标识码 - cmd: "push_message" // 推送消息 -} +返回数据 -data { - any: "type.googleapis.com/proto.PushMessage" // ProtoBuf 的 any 字段 - msg { - msg_id: "abcdef" // 消息ID - sender { - chat_id: "7357777" // 发送者ID - chat_type: 1 // 发送者类型,1-用户 3-机器人 - name: "测试" // 发送者名称 - avatar_url: "https://chat-img.jwznb.com/...." // 头像URL - tag_old: "测试成员" // 标签(旧版) - // ... - tag { - id: 123 // 标签id - text: "" // 标签文字 - color: "#FFFFFFFF" // 标签颜色 - } - // ... - } - recv_id: "7356666" // 接收者ID - chat_id: "big" // 会话的ID - chat_type: 2 // 会话的类型,1-用户 2-群组 3-机器人 - content { - text: "Feng的大手发力了" // 消息文字 - // 剩下的建议参考proto,太多不写了 - } - content_type: 1 // 消息类型 - timestamp: 123456789 // 时间戳(毫秒) - cmd { - id; 999 // 指令ID - name: "MAC地址查询" // 指令名称 - } - msg_seq: 1145 // 消息序列 - } -} +```protobuf + ``` -::: details ProtoBuf数据结构 +## 编辑消息接收 -```proto -// 共用区 +!!和推送消息可以共用.!! -// 标签 -message Tag { - uint64 id = 1; // 标签ID(貌似) - string text = 3; - string color = 4; -} -// 共用区结束 - -// ws推送消息 -message push_message { - INFO info = 1; - Data data = 2; - - message Data { - string any = 1; - Msg msg = 2; - - message Msg { - string msg_id = 1; - Sender sender = 2; - string recv_id = 3; // 接收者ID - string chat_id = 4; // 会话的ID - uint64 chat_type = 5; // 会话类型 - Content content = 6; // 消息内容 - uint64 content_type = 7; - uint64 timestamp = 8; // 时间戳(毫秒) - Cmd cmd = 9; // 指令 - uint64 delete_timestamp = 10; // 撤回消息时间,和8差别不大 - string quote_msg_id = 11; // 引用消息ID - uint64 msg_seq = 12; // 消息序列,在撤回时也是被撤回消息的序列 - - message Cmd { - uint64 id = 1; // 命令ID - string name = 2; // 命令名称 - } - - message Sender { - string chat_id = 1; - uint64 chat_type = 2; - string name = 3; - string avatar_url = 4; - repeated string tag_old = 6; - repeated Tag tag = 7; - } - - message Content { - string text = 1; // 消息内容 - string buttons = 2; // 按钮 - string image_url = 3; - string file_name = 4; - string file_url = 5; - string form = 7; // 表单消息 - string quote_msg_text = 8; // 引用消息文字 - string sticker_url = 9; // 表情URL - string post_id = 10; // 文章ID - string post_title = 11; // 文章标题 - string post_content = 12; // 文章内容 - string post_content_type = 13; // 文章类型 - string expression_id = 15; // 个人表情ID(不知道为啥为STR) - string quote_image_url = 16; // 引用图片直链,https://... - string quote_image_name = 17; // 引用图片文件名称 - uint64 file_size = 18; // 文件/图片大小(字节) - string video_url = 19; // 视频URL - string audio_url = 21; // 语音URL - uint64 audio_time = 22; // 语音时长 - string quote_video_url = 23; // 引用视频直链,https://... - uint64 quote_video_time = 24; // 引用视频时长 - uint64 sticker_item_id = 25; // 表情ID - uint64 sticker_pack_id = 26; // 表情包ID - string call_text = 29; // 语音通话文字 - string call_status_text = 32; // 语音通话状态文字 - uint64 width = 33; // 图片的宽度 - uint64 height = 34; // 图片的高度 - string tip = 37; // 提示信息 - } - } - } -} -``` +返回数据 -::: +```protobuf + +``` -## 推送超级文件分享 + ## 接受邀请消息 ::: tip 提示 -本项只提供了“有人邀请我”的这种状态，并没有提供相关信息，如邀请人、群聊ID等，建议配合邀请列表进行使用。 +本项只提供了“有人邀请我”的这种状态，并没有提供相关信息，如邀请人、群聊 ID 等，建议配合邀请列表进行使用。 ::: -### 返回数据 +返回数据 -```ProtoBuf -info { - seq: "123123123123123123123" // 请求标识码 - cmd: "invite_apply" // 邀请信息推送 -} -``` - -::: details ProtoBuf数据结构 - -```proto -message InviteApply { - INFO info = 1; -} +```protobuf + ``` -::: - ## 流式消息 ::: tip 流式消息第一个推送是 push_message,后续才是 stream_message,需要将 content 里面的内容追加到消息内容后面. ::: -### 返回数据 - -```ProtoBuf -info { - seq: "114aaaa" // 请求ID - cmd: "stream_message" -} +返回数据 -data { - any: "type.googleapis.com/proto.StreamMessage" // ProtoBuf 的 any 字段 - msg { - msgId: "11451419180" // 消息ID - recvId: "6666666" // 接受者ID - chatId: "26146395" // 发送者ID - content: "我是追加内容" // 要追加的内容 - } -} +```protobuf + ``` -::: details ProtoBuf数据结构 - -```proto -// 流式消息 -message stream_message { - INFO info = 1; - Data data = 2; - - message Data { - string any = 1; - StreamMsg msg = 2; - - message StreamMsg { - string msg_id = 1; - string recv_id = 2; - string chat_id = 3; // 似乎是会话ID - string content = 4; // 消息内容 - } - } -} -``` - -::: - ## 用户挂断语音 -### 返回数据 - -```ProtoBuf -info { - seq: "114aaaa" // 请求ID - cmd: "live_video_user_hang_up" -} +返回数据 -data { - any: "type.googleapis.com/proto.LiveMessage" // ProtoBuf 的 any 字段 - msg { - msgId: "11451419180" // 语音消息ID - cmd: "live_video_user_hang_up" // 用户挂断语音指令 - } -} +```protobuf + ``` -::: details ProtoBuf数据结构 +## 机器人看板更新推送 -```proto -// 用户挂起通话消息 -message live_video_user_hang_up { - INFO info = 1; - Data data = 2; - - message Data { - string any = 1; - UserHangUpMsg msg = 2; - - message UserHangUpMsMsg { - string msg_id = 1; // 语音消息id - string cmd = 5; // 指令 - } - } -} +返回数据 + +```protobuf + ``` diff --git a/src/full.proto b/src/full.proto index 01cde372..654ba217 100644 --- a/src/full.proto +++ b/src/full.proto @@ -4,6 +4,8 @@ syntax = "proto3"; // buf:lint:ignore PACKAGE_VERSION_SUFFIX package yh; +import "google/protobuf/any.proto"; + // 共用区 // 枚举 @@ -104,7 +106,7 @@ message MsgContent { string quote_image_url = 16; // 引用图片直链,https://... string quote_image_name = 17; // 引用图片文件名称 int64 file_size = 18; // 欲发送文件大小 - string video_url = 19; // 欲发送视频 key/url(123.mp4) + string video_url = 19; // 欲发送视频 key/url(123.mp4),也是视频 URL string audio_url = 21; // 语音 key/url(123.m4a) int64 audio_time = 22; // 语音时长(单位秒) string quote_video_url = 23; // 引用视频直链,https://... @@ -129,8 +131,8 @@ message Tag { // #endregion Tag // 看板数据 -// #region BoardData -message BoardData { +// #region BotBoardMessage +message BotBoardMessage { // 如果要是 WS 的话对应 cmd 为 bot_board_message string bot_id = 1; // 机器人 ID string chat_id = 2; // 对象 ID ChatType chat_type = 3; // 对象类别 @@ -139,7 +141,7 @@ message BoardData { int64 last_update_time = 6; // 最后更新时间戳 string bot_name = 7; // 设置看板机器人名称 } -// #endregion BoardData +// #endregion BotBoardMessage // 机器人信息 // #region BotData @@ -197,6 +199,30 @@ message GroupData { bool deny_members_upload_to_group_disk = 33; // 禁止群成员上传文件到群云盘（开启时为 1） } // #endregion GroupData + +// Sender 发送者信息 +// #region Sender +message Sender { + string chat_id = 1; // 发送者 ID + ChatType chat_type = 2; // 发送者类型 + string name = 3; // 发送者名称 + string avatar_url = 4; // 头像 URL + repeated string tag_old = 6; // 标签(旧版显示) + repeated Tag tag = 7; // 标签 +} +// #endregion Sender + +// 命令内容 +// #region Cmd +message Cmd { + uint64 cmd_id = 1; // 指令 ID + string name = 2; // 指令名 + uint64 type = 4; // 指令类型（1-普通指令, 2-直发指令, 5-自定义输入指令） +} +// #endregion Cmd + +// 这里不会有 WS 的共用内容 + // 共用区结束 // User 相关 @@ -284,7 +310,7 @@ message SendMsgRequest { string msg_id = 2; // 信息 ID string chat_id = 3; // 欲发送到的信息对象 ChatType chat_type = 4; // 欲发送到的信息对象的类别 - MsgContent msg_content = 5; // 消息内容 + MsgContent content = 5; // 消息内容 ContentType content_type = 6; // 消息类别 int64 command_id = 7; // 所使用命令 ID string quote_msg_id = 8; // 引用信息 ID @@ -324,29 +350,13 @@ message ListMsgResponse { Sender sender = 2; string direction = 3; // 消息位置,左边/右边 ContentType content_type = 4; - MsgContent msg_content = 5; + MsgContent content = 5; uint64 send_time = 6; // 时间戳(毫秒) Cmd cmd = 7; // 指令 uint64 recall_time = 8; // 消息撤回时间 string quote_msg_id = 9; // 引用消息 ID uint64 msg_seq = 10; uint64 edit_time = 12; // 最后编辑时间 - - message Cmd { - uint64 cmd_id = 1; // 指令 ID - string name = 2; // 指令名 - uint64 type = 4; // 指令类型（1-普通指令, 2-直发指令, 5-自定义输入指令） - } - - // 发送者信息 - message Sender { - string chat_id = 1; // 发送者 ID - ChatType chat_type = 2; // 发送者类型 - string name = 3; // 发送者名称 - string avatar_url = 4; // 头像 URL - repeated string tag_old = 6; // 标签(旧版显示) - repeated Tag tag = 7; // 标签 - } } } // #endregion ListMsgResponse @@ -432,7 +442,7 @@ message BoardRequest { // #region BoardResponse message BoardResponse { Status status = 1; - BoardData data = 2; + BotBoardMessage data = 2; } // #endregion BoardResponse @@ -786,3 +796,111 @@ message DismissGroupRequest { string group_id = 2; } // #endregion DismissGroupRequest + +// instruction +// 获取私聊指令 +// #region GetBotInstructionRequest +message GetBotInstructionRequest { + string bot_id = 3; +} +// #endregion GetBotInstructionRequest + +// #region GetBotInstructionResponse +message GetBotInstructionResponse { + Status status = 1; + Data data = 2; + message Data { + uint64 command_id = 1; // 指令 id + string bot_id = 2; // 机器人 id + string command_name = 3; // 指令名称 + uint64 instruction_type = 5; // 指令类型: 1-普通指令，2-直发指令，5-自定义输入指令 + string command_default_text = 7; // 指令输入框默认文本 + string command_settings_json = 10; // 指令设置 JSON（表单指令，自定义输入指令） + } +} +// #endregion GetBotInstructionResponse + +// chat-ws-go + +// chat-ws-go 共用区 + +// WsInfo +// #region WsInfo +message WsInfo { + string seq = 1; // 请求标识码,可以不管 + string cmd = 2; // 操作类型 +} +// #endregion WsInfo + +// WsWrapper +// 这里是 Ws 消息的外层 +// #region WsWrapper +message WsWrapper { + WsInfo info = 1; + google.protobuf.Any data = 2; // Any +} +// #endregion WsWrapper + +// chat-ws-go 共用区结束 + +// 心跳包响应 +// #region HeartbeatAckResponse +message HeartbeatAckResponse { + WsInfo info = 1; // 响应数据,info.cmd = heartbeat_ack +} +// #endregion HeartbeatAckResponse + +// MsgInput 实际上是草稿同步 +// #region MsgInput +message MsgInput { // 对应的 cmd: draft_input + string chat_id = 1; // 对象ID + string input = 2; // 草稿内容,注意是覆盖不是合并也不是追加 +} +// #endregion MsgInput + +// PushMessage +// #region PushMessage +message PushMessage { // 对应 cmd: push_message, edit_message + string msg_id = 1; + Sender sender = 2; // 发送者信息,编辑消息无此项 + string recv_id = 3; // 接收者 ID,不知道为啥到编辑这里就和4一样了 + string chat_id = 4; // 会话 ID + ChatType chat_type = 5; // 会话类型,编辑消息无此项 + MsgContent content = 6; // 消息内容,注意编辑消息的会话内容和发送消息可以共用但是编辑消息有缺失 + ContentType content_type = 7; + uint64 timestamp = 8; // 时间戳(毫秒),编辑消息无此项 + Cmd cmd = 9; // 指令,编辑消息无此项(客户端限制不让编辑指令消息) + uint64 delete_timestamp = 10; // 撤回消息时间,和8差别不大,编辑消息无此项 + string quote_msg_id = 11; // 引用消息ID + uint64 msg_seq = 12; // 消息序列,在撤回时也是被撤回消息的序列,注意撤回消息存在部分字段缺失 + uint64 edit_time = 14; // 编辑时间,只有编辑消息有此项 +} +// #endregion PushMessage + +// 有人邀请我 +// #region InviteApplyResponse +message InviteApplyResponse { + WsInfo info = 1; // info.cmd = invite_apply +} +// #endregion InviteApplyResponse + +// 流式消息 +// #region StreamMessage +message StreamMessage { // 对应 cmd: stream_message + string msg_id = 1; // 消息 ID + string recv_id = 2; // 接收者 ID,群聊的时为群聊的 ID,私聊是自己的 ID + string chat_id = 3; // 会话 ID + string content = 4; // 需要追加的消息内容 +} +// #endregion StreamMessage + +// 语音消息 +// #region LiveMessage +message LiveMessage { // 对应 cmd: live_video_user_hang_up + string msg_id = 1; // 语音消息 ID + string cmd = 5; // 指令,例如 live_video_user_hang_up +} +// #endregion LiveMessage + +// 机器人看板更新推送 +// 和 BotBoardMessage 相同 From a830415ab313f72fe73ad432cf1a54f44f6660e4 Mon Sep 17 00:00:00 2001 From: yyyytawa <116234899+yyyytawa@users.noreply.github.com> Date: Fri, 3 Jul 2026 20:39:34 +0800 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=20full.proto=20?= =?UTF-8?q?=E7=9A=84=E9=A1=B5=E9=9D=A2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/api/full_proto.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 src/api/full_proto.md diff --git a/src/api/full_proto.md b/src/api/full_proto.md new file mode 100644 index 00000000..c0c3fc04 --- /dev/null +++ b/src/api/full_proto.md @@ -0,0 +1,7 @@ +--- +title: 完整 proto +--- + +```protobuf + +``` \ No newline at end of file