tanjianbin/lzwcai-terminal-worktool

Fork 0

Files

roger 1bb8c306e4 解决本地运行的问题

2026-03-23 15:33:09 +08:00

4.9 KiB

Raw Blame History

WorkTool 后端通信协议文档

本文档详细描述了 WorkTool 机器人（客户端）与后台服务器（服务端）之间的通信协议。

1. 连接方式

WorkTool 使用 WebSocket 协议与服务端进行长连接通信。

WebSocket URL: ws://<服务器IP>:<端口>/webserver/wework/<链接号>
- <链接号> (robotId): 机器人的唯一标识，由用户在 APP 端设置。
通信格式: JSON
心跳机制: 客户端每 5 秒发送一次心跳包 {"type": 11}，服务端可忽略或回复。

2. 数据包结构

所有的通信数据（发送和接收）都包裹在 WeworkMessageListBean 结构中。

2.1 外层包装 (WeworkMessageListBean)

服务端发送给客户端的 JSON 必须符合以下结构：

{
  "socketType": 2,          // 消息类型：2 表示下发指令列表
  "list": [                 // 指令列表，可包含多个指令
    {
      "type": 203,          // 具体指令类型 (例如 203=发送消息)
      "messageId": "uuid",  // 消息ID (可选，用于回调对应)
      ...                   // 指令参数 (详见下文)
    }
  ],
  "encryptType": 0          // 加密类型：0=不加密, 1=AES加密 (默认0)
}

2.2 消息确认

当客户端收到服务端消息后，会回复一个确认包（通常服务端不需要处理）：

{
    "socketType": 1,        // SOCKET_TYPE_MESSAGE_CONFIRM
    "messageId": "..."      // 收到的消息ID
}

3. 常用指令详解

以下列出常用的指令及其 JSON 参数示例。参数放在 list 数组的对象中。

3.1 发送文本消息 (SEND_MESSAGE)

Type: 203
说明: 在指定房间（群或好友）发送文本。

{
  "type": 203,
  "titleList": ["张三", "技术交流群"],  // 接收者名称列表 (群名或好友名)
  "receivedContent": "你好，这是测试消息", // 消息内容
  "at": "李四"                         // (可选) 需要 @ 的人昵称，仅在群聊有效
}

3.2 转发消息 (RELAY_MESSAGE)

Type: 205
说明: 将某人的消息转发给其他人。

{
  "type": 205,
  "titleList": ["来源群名"],           // 消息来源房间名
  "receivedName": "张三",             // 消息发送者昵称
  "originalContent": "原消息内容",     // 用于匹配消息内容
  "textType": 1,                      // 消息类型 (1=文本, 2=图片, 详见附录)
  "nameList": ["目标群1", "李四"],     // 转发目标列表
  "extraText": "这是转发的消息"         // (可选) 转发时的附加留言
}

3.3 推送文件/图片 (PUSH_FILE)

Type: 218
说明: 发送网络文件或图片。

{
  "type": 218,
  "titleList": ["张三"],
  "objectName": "文件名.jpg",         // 保存的文件名
  "fileUrl": "http://example.com/a.jpg", // 文件下载地址
  "fileType": "image",                // 文件类型 (image, video, file)
  "extraText": "请查收图片"            // (可选) 附加留言
}

3.4 推送链接 (PUSH_LINK)

Type: 224
说明: 发送卡片链接。

{
  "type": 224,
  "titleList": ["张三"],
  "objectName": "百度一下",           // 链接标题
  "receivedContent": "你就知道",       // 链接描述/副标题
  "originalContent": "https://www.baidu.com", // 跳转链接
  "fileUrl": "http://example.com/icon.png"    // 链接图标地址
}

3.5 获取最近聊天列表 (GET_RECENT_LIST)

Type: 505
说明: 获取消息列表首页的最近聊天记录。

{
  "type": 505
}

3.6 获取群信息 (GET_GROUP_INFO)

Type: 501
说明: 获取指定群的成员列表等信息。

{
  "type": 501,
  "selectList": ["技术交流群"]        // 要查询的群名列表
}

4. 执行结果回调

当机器人执行完指令后，会向服务端发送执行结果。

SocketType: 3 (SOCKET_TYPE_RAW_CONFIRM)
数据结构:

{
  "socketType": 3,
  "messageId": "原始指令的messageId",
  "list": [
    {
      "errorCode": 0,               // 0 表示成功，非 0 表示失败
      "errorReason": "",            // 失败原因
      "successList": ["张三"],       // 执行成功的对象列表
      "failList": [],               // 执行失败的对象列表
      "rawMsg": "{...}",            // 原始指令 JSON
      "runTime": 1670000000000,     // 开始执行时间戳
      "timeCost": 1.5               // 耗时 (秒)
    }
  ]
}

常见错误码 (ErrorCode)

0: 成功
201102: 发送消息失败
201104: 目标寻找失败 (未找到群或联系人)
501000: 其他未知错误

附录：消息类型定义 (textType)

1: 文本 (TEXT_TYPE_PLAIN)
2: 图片 (TEXT_TYPE_IMAGE)
3: 语音 (TEXT_TYPE_VOICE)
5: 视频 (TEXT_TYPE_VIDEO)
8: 链接 (TEXT_TYPE_LINK)
9: 文件 (TEXT_TYPE_FILE)
15: 引用回复 (TEXT_TYPE_REPLY)

4.9 KiB Raw Blame History Unescape Escape