@rlynicrisis/link 0.0.3 → 0.0.5

package/README.md

@@ -1,12 +1,19 @@
 # OpenClaw Link Channel Plugin
 
-这是一个 OpenClaw 的 Link 消息服务接入插件。
+这是一个 OpenClaw 的 Link 消息服务接入插件，支持通过 TCP 协议连接到 Link/EMB 服务器，实现消息的接收与发送。
 
-## 功能
-- 接入 Link 消息服务 (TCP 协议)
-- 支持接收文本消息
-- 支持回复文本消息
-- **安全限制**: 仅允许接收和回复自己账号的消息（Bot 自言自语模式）
+## 功能特性
+
+- **协议支持**: 基于 TCP 的私有协议 (EMB Protocol V3)，支持 Protobuf 消息序列化。
+- **消息类型**:
+  - ✅ 文本消息 (Text)
+  - ✅ 文件消息 (File) - *需配合文件上传服务使用*
+- **安全机制**:
+  - 🔒 **仅限己方消息**: 插件默认仅处理当前登录用户发送给自己的消息（即“文件传输助手”模式），忽略群聊和其他用户的私聊，确保数据安全。
+- **连接管理**:
+  - 💓 自动心跳保活
+  - 🔄 断线自动重连
+  - 🎫 **Token 自动刷新**: 支持配置 `refreshToken` 和 `ssoUrl`，在 Token 过期时自动通过 SSO 接口刷新并重连。
 
 ## 安装与配置
 
@@ -19,29 +26,32 @@ npm install
 npm run build
 ```
 
-这将生成 `dist` 目录。
+这将生成 `dist` 目录，包含编译后的插件代码。
 
 ### 2. 配置 OpenClaw
 
 在您的 OpenClaw 主配置文件（通常是 `config.yaml` 或 `config.json`）中，添加以下内容：
 
-#### 注册插件
-如果 OpenClaw 支持本地插件加载，请确保插件路径被包含在加载列表中，或者将本插件发布/链接到 `node_modules`。
+#### 频道配置 (Channel Config)
 
-#### 频道配置
 在 `channels` 部分添加 `link` 配置：
 
 ```yaml
 channels:
   link:
     enabled: true
-    # Link 服务地址
-    host: "embtcpbeta.bingolink.biz"
-    port: 20081
+    # Link 服务地址 (格式: host:port)
+    host: "embtcpbeta.bingolink.biz:20081"
+    
     # 鉴权信息 (必填)
-    accessToken: "your_access_token"
-    # 可选配置
-    # heartbeatIntervalMs: 30000
+    accessToken: "your_access_token_here"
+    
+    # Token 自动刷新配置 (可选，推荐配置)
+    refreshToken: "your_refresh_token_here"
+    ssoUrl: "https://sso.example.com" # SSO 服务地址
+    
+    # 高级配置 (可选)
+    # heartbeatIntervalMs: 30000 # 心跳间隔，默认 30秒
     # verifyInfo: # 如果需要覆盖默认生成的设备信息，可在此配置
     #   deviceName: "CustomBotName"
 ```
@@ -49,16 +59,36 @@ channels:
 > **注意**：
 > - `userId` 将自动从 `accessToken` (JWT) 中解析。
 > - `deviceUID` 将根据机器特征自动生成，确保同一设备上的稳定性。
-> - 其他参数如 `version`, `deviceToken` 等已内置默认值。
+> - `host` 参数现已支持 `host:port` 格式，无需单独配置 `port`。
+
+## 开发调试
 
-### 3. 启动 OpenClaw
+### 单元测试
 
-启动 OpenClaw 主程序，插件将自动连接 Link 服务。
+运行所有单元测试：
 
-## 开发调试
+```bash
+npm test
+```
+
+### 手动连接测试
 
-可以使用 `test/manual-connect.ts` 脚本单独测试连接：
+可以使用 `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` 中的安全过滤逻辑，确保发送者和接收者均为当前登录用户。

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@rlynicrisis/link",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "description": "OpenClaw Link channel plugin",
   "files": [
     "index.ts",
     "src/**/*.ts",
+    "src/**/*.js",
     "!src/**/__tests__/**",
     "!src/**/*.test.ts",
     "openclaw.plugin.json"
@@ -41,6 +42,9 @@
       "label": "Link",
       "selectionLabel": "Link Messaging Service",
       "blurb": "Integration with Link messaging service.",
+      "onboarding": {
+        "kind": "manual"
+      },
       "order": 100
     },
     "install": {