@rlynicrisis/link 0.1.1 → 0.1.2

package/README.md

@@ -7,13 +7,25 @@
 - **协议支持**: 基于 TCP 的私有协议 (EMB Protocol V3)，支持 Protobuf 消息序列化。
 - **消息类型**:
   - ✅ 文本消息 (Text)
-  - ✅ 文件消息 (File) - *需配合文件上传服务使用*
-- **安全机制**:
-  - 🔒 **仅限己方消息**: 插件默认仅处理当前登录用户发送给自己的消息（即“文件传输助手”模式），忽略群聊和其他用户的私聊，确保数据安全。
+- **接入模式**:
+  - 📁 **FileHelper 模式（默认）**: 仅处理当前登录用户发送给自己的消息，忽略群聊和其他私聊，确保数据安全。
+  - 👥 **群组模式**: 配置 `groupId` 后监听指定群的消息，由群机器人 Webhook（HTTP POST）回复。
 - **连接管理**:
   - 💓 自动心跳保活
   - 🔄 断线自动重连
-  - 🎫 **Token 自动刷新**: 支持配置 `refreshToken` 和 `ssoUrl`，在 Token 过期时自动通过 SSO 接口刷新并重连。
+  - 🎫 **Token 自动刷新**: 支持配置 `refreshToken`，在 Token 过期时自动通过 SSO 接口刷新并重连。
+
+## 默认值
+
+以下字段均有默认值，可以省略不填：
+
+| 字段 | 默认值 |
+|------|--------|
+| `host` | `embtcp.bingolink.biz:20081` |
+| `ssoUrl` | `https://www.bingolink.biz:443/sso` |
+| `notificationApiUrl` | `https://notificationapi.bingolink.biz:443/notificationapi` |
+
+**必填字段只有 `accessToken`**（群组模式还需额外填写 `groupId` 和 `botToken`）。
 
 ## 安装与配置
 
@@ -32,68 +44,65 @@ npm run build
 
 在您的 OpenClaw 主配置文件（通常是 `config.yaml` 或 `config.json`）中，添加以下内容：
 
-#### 频道配置 (Channel Config)
-
-在 `channels` 部分添加 `link` 配置：
+#### 最简配置（FileHelper 模式）
 
 ```yaml
 channels:
   link:
-    enabled: true
-    # Link 服务地址 (格式: host:port)
-    host: "embtcpbeta.bingolink.biz:20081"
-    
-    # 鉴权信息 (必填)
+    # 必填：鉴权 Token
     accessToken: "your_access_token_here"
-    
-    # Token 自动刷新配置 (可选，推荐配置)
-    refreshToken: "your_refresh_token_here"
-    ssoUrl: "https://sso.example.com" # SSO 服务地址
-    
-    # 高级配置 (可选)
-    # heartbeatIntervalMs: 30000 # 心跳间隔，默认 30秒
-    # verifyInfo: # 如果需要覆盖默认生成的设备信息，可在此配置
-    #   deviceName: "CustomBotName"
+
+    # 以下均可省略，使用默认值：
+    # host: "embtcp.bingolink.biz:20081"
+    # ssoUrl: "https://www.bingolink.biz:443/sso"
+
+    # Token 自动刷新（可选，推荐配置）
+    # refreshToken: "your_refresh_token_here"
+```
+
+#### 完整配置参考
+
+```yaml
+channels:
+  link:
+    host: "embtcp.bingolink.biz:20081"       # 消息服务地址，可省略
+    accessToken: "your_access_token_here"     # 必填
+    refreshToken: "your_refresh_token_here"   # 可选，用于 Token 自动刷新
+    ssoUrl: "https://www.bingolink.biz:443/sso"  # 可省略，刷新 Token 时使用
+    heartbeatIntervalMs: 30000               # 心跳间隔，默认 30 秒
 ```
 
 > **注意**：
 > - `userId` 将自动从 `accessToken` (JWT) 中解析。
-> - `deviceUID` 将根据机器特征自动生成，确保同一设备上的稳定性。
-> - `host` 参数现已支持 `host:port` 格式，无需单独配置 `port`。
+> - `deviceUID` 将根据机器特征自动生成。
+> - `host` 支持 `host:port` 格式，默认端口 `20081`。
 
 ## 接入 OpenClaw
 
 ### 1. 安装插件
 
-通过 OpenClaw CLI 安装本插件：
-
 ```bash
 openclaw plugins install @rlynicrisis/link
 ```
 
 ### 2. 配置频道
 
-使用 OpenClaw CLI 的交互式引导添加频道配置：
-
 ```bash
 openclaw channels add
 ```
 
-在引导过程中选择 **Link**，并按照提示输入以下信息：
-
-1.  **Link Server Host**: 输入消息服务地址（例如 `embtcpbeta.bingolink.biz:20081`）。
-2.  **User Access Token**: 输入初始的 Access Token。
-3.  **Refresh Token** (可选): 输入 Refresh Token，用于 Token 自动刷新。
-4.  **SSO URL** (可选): 输入 SSO 认证服务地址（例如 `https://sso.example.com`），用于 Token 刷新请求。
+在引导过程中选择 **Link**，按提示输入：
 
-配置完成后，OpenClaw 将自动连接并开始监听消息。
+1. **User Access Token**（必填）
+2. **Refresh Token**（可选，推荐填写，用于 Token 自动刷新）
+3. 其余字段均有默认值，直接回车跳过即可
 
 ### 3. 获取 Token 示例
 
-您可以使用以下命令通过账号密码获取初始的 Access Token 和 Refresh Token：
+通过账号密码获取 Access Token 和 Refresh Token：
 
 ```bash
-curl --location --request POST 'https://www.bingolink.biz/sso/oauth2/token' \
+curl --location --request POST 'https://www.bingolink.biz:443/sso/oauth2/token' \
 --header 'Authorization: Basic Y2xpZW50SWQ6Y2xpZW50U2VjcmV0' \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data-urlencode 'grant_type=password' \
@@ -101,121 +110,114 @@ curl --location --request POST 'https://www.bingolink.biz/sso/oauth2/token' \
 --data-urlencode 'password=个人密码'
 ```
 
-> **提示**: 请将 `username` 和 `password` 替换为您的实际账号信息。响应结果将包含 `access_token` 和 `refresh_token`。
+响应结果中的 `access_token` 和 `refresh_token` 即为所需的 Token。
+
+## 群组接入模式
+
+在 FileHelper 模式之外，插件还支持监听指定群的消息，并通过**群机器人 Webhook** 回复。
+
+### 工作原理
 
-## 多账号支持 (Multi-Account Support)
+- **接收**：建立 TCP 长连接，过滤出发往 `groupId` 的群消息，触发 OpenClaw 的 Agent 处理流程。
+- **发送**：Agent 回复内容通过 HTTP POST 发送到群机器人 Webhook 地址，而非 TCP 自发自收。
+
+### 配置示例
+
+```yaml
+channels:
+  link:
+    accounts:
+      mygroup:
+        accessToken: "your_access_token_here"
+        refreshToken: "your_refresh_token_here"  # 可选
+
+        # 群组接入配置
+        groupId: "3ab33646-3a55-46fd-97ba-868d4bf29915"  # 要监听的群 ID
+        botToken: "xxxxxxxxxxxxxxxx"                        # 群机器人 Webhook Token
+
+        # notificationApiUrl 可省略，默认：
+        # https://notificationapi.bingolink.biz:443/notificationapi
+
+bindings:
+  - agentId: "group-agent"
+    match:
+      channel: "link"
+      accountId: "mygroup"
+```
+
+### 配置字段说明
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `groupId` | 群组模式必填 | 要监听的群 ID |
+| `botToken` | 群组模式必填 | 群机器人 Webhook Token |
+| `notificationApiUrl` | 可省略 | Webhook 服务基础地址，默认 `https://notificationapi.bingolink.biz:443/notificationapi` |
+
+> **说明**：`groupId` + `botToken` 同时存在时自动启用群组模式，否则退回到 FileHelper 模式。
+
+## 多账号支持
 
 插件支持在同一个 OpenClaw 实例中同时连接多个 Link 账号，每个账号独立维护连接和消息路由。
 
 ### 配置格式
 
-在 `channels.link` 下添加 `accounts` 字段，以账号 ID 为键，每个账号独立配置：
-
 ```yaml
 channels:
   link:
     accounts:
+      # FileHelper 账号（最简配置）
       default:
-        host: "embtcp.bingolink.biz:20081"
         accessToken: "token_for_default_account"
         refreshToken: "refresh_token_for_default"
-        ssoUrl: "https://www.bingolink.biz/sso"
-      work:
-        host: "embtcp.bingolink.biz:20081"
-        accessToken: "token_for_work_account"
-        refreshToken: "refresh_token_for_work"
-        ssoUrl: "https://www.bingolink.biz/sso"
-```
-
-### 绑定配置
 
-使用 `bindings` 将不同账号路由到不同的 Agent：
+      # 群组账号
+      mygroup:
+        accessToken: "token_for_group_account"
+        groupId: "3ab33646-3a55-46fd-97ba-868d4bf29915"
+        botToken: "xxxxxxxxxxxxxxxx"
 
-```yaml
 bindings:
   - agentId: "main"
     match:
       channel: "link"
       accountId: "default"
-  - agentId: "work-agent"
+  - agentId: "group-agent"
     match:
       channel: "link"
-      accountId: "work"
+      accountId: "mygroup"
 ```
 
-### JSON 格式示例
-
-```json
-{
-  "channels": {
-    "link": {
-      "accounts": {
-        "default": {
-          "host": "embtcp.bingolink.biz:20081",
-          "accessToken": "xxx",
-          "refreshToken": "xxx",
-          "ssoUrl": "https://www.bingolink.biz/sso"
-        },
-        "work": {
-          "host": "embtcp.bingolink.biz:20081",
-          "accessToken": "yyy",
-          "refreshToken": "yyy",
-          "ssoUrl": "https://www.bingolink.biz/sso"
-        }
-      }
-    }
-  },
-  "bindings": [
-    { "agentId": "main", "match": { "channel": "link", "accountId": "default" } },
-    { "agentId": "work-agent", "match": { "channel": "link", "accountId": "work" } }
-  ]
-}
-```
-
-### 向后兼容 (Backward Compatibility)
+### 向后兼容
 
-**无需修改现有配置**。如果没有 `accounts` 字段，插件会将根级别的 `host`、`accessToken` 等字段视为 `accountId = "default"` 的账号，行为与之前完全一致：
+**无需修改现有配置**。如果没有 `accounts` 字段，插件会将根级别的字段视为 `accountId = "default"` 的账号：
 
 ```yaml
 # 旧配置格式，继续有效
 channels:
   link:
-    host: "embtcp.bingolink.biz:20081"
     accessToken: "your_token"
     refreshToken: "your_refresh_token"
-    ssoUrl: "https://www.bingolink.biz/sso"
 ```
 
-> **注意**: `accounts` 字段与根级别的 `host`/`accessToken` 互斥。当 `accounts` 存在时，根级别字段会被忽略。
+> `accounts` 字段与根级别的 `accessToken` 互斥。当 `accounts` 存在时，根级别字段会被忽略。
 
 ## 开发调试
 
 ### 单元测试
 
-运行所有单元测试：
-
 ```bash
 npm test
 ```
 
 ### 手动连接测试
 
-可以使用 `test/manual-connect.ts` 脚本单独测试连接和基本消息收发：
-
 ```bash
 npx tsx test/manual-connect.ts
 ```
 
-### 发送文件消息测试
-
-测试发送文件类型消息（构造虚拟文件信息）：
-
-```bash
-npx tsx test/send-file.ts
-```
-
 ## 常见问题
 
-- **消息发送失败 (Protobuf Error)**: 确保服务端支持 V3 协议，且 `MsgType` 枚举值与服务端定义一致（如 File=3）。
-- **Token 过期**: 如果配置了 `refreshToken` 和 `ssoUrl`，插件会自动尝试刷新。否则需手动更新配置文件中的 `accessToken`。
-- **无法收到消息**: 检查 `bot.ts` 中的安全过滤逻辑，确保发送者和接收者均为当前登录用户。
+- **Token 过期**: 配置了 `refreshToken` 后，插件会在收到服务端刷新信号时自动续期。否则需手动更新 `accessToken`。
+- **收不到群消息**: 确认 `groupId` 和 `botToken` 均已配置，且 `groupId` 与实际群 ID 一致。
+- **Webhook 调用失败**: 检查 `notificationApiUrl` 是否可访问，以及 `botToken` 是否有效。
+- **FileHelper 模式收不到消息**: 发送者和接收者必须均为当前登录用户自身（自发自收）。

package/openclaw.plugin.json

@@ -8,12 +8,12 @@
     "type": "object",
     "additionalProperties": false,
     "properties": {
-      "host": { "type": "string", "description": "Link Server Host", "default": "embtcp.bingolink.biz:20081" },
-      "ssoUrl": { "type": "string", "description": "SSO URL for refreshing token", "default": "https://www.bingolink.biz:443/sso" },
       "accessToken": { "type": "string", "description": "User Access Token" },
       "refreshToken": { "type": "string", "description": "User Refresh Token (Optional)" },
       "groupId": { "type": "string", "description": "Group ID to monitor (enables group bot mode)" },
       "botToken": { "type": "string", "description": "Group bot webhook token" },
+      "host": { "type": "string", "description": "Link Server Host", "default": "embtcp.bingolink.biz:20081" },
+      "ssoUrl": { "type": "string", "description": "SSO URL for refreshing token", "default": "https://www.bingolink.biz:443/sso" },
       "notificationApiUrl": { "type": "string", "description": "Webhook base URL", "default": "https://notificationapi.bingolink.biz:443/notificationapi" },
       "accounts": {
         "type": "object",
@@ -23,12 +23,12 @@
           "additionalProperties": false,
           "required": ["accessToken"],
           "properties": {
-            "host": { "type": "string", "description": "Link Server Host", "default": "embtcp.bingolink.biz:20081" },
             "accessToken": { "type": "string", "description": "User Access Token" },
             "refreshToken": { "type": "string", "description": "User Refresh Token (Optional)" },
-            "ssoUrl": { "type": "string", "description": "SSO URL for refreshing token", "default": "https://www.bingolink.biz:443/sso" },
             "groupId": { "type": "string", "description": "Group ID to monitor (enables group bot mode)" },
             "botToken": { "type": "string", "description": "Group bot webhook token" },
+            "host": { "type": "string", "description": "Link Server Host", "default": "embtcp.bingolink.biz:20081" },
+            "ssoUrl": { "type": "string", "description": "SSO URL for refreshing token", "default": "https://www.bingolink.biz:443/sso" },
             "notificationApiUrl": { "type": "string", "description": "Webhook base URL", "default": "https://notificationapi.bingolink.biz:443/notificationapi" }
           }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rlynicrisis/link",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "OpenClaw Link channel plugin",
   "files": [