@rlynicrisis/link 0.0.3 → 0.0.4

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,6 +1,6 @@
 {
   "name": "@rlynicrisis/link",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "type": "module",
   "description": "OpenClaw Link channel plugin",
   "files": [
@@ -41,6 +41,9 @@
       "label": "Link",
       "selectionLabel": "Link Messaging Service",
       "blurb": "Integration with Link messaging service.",
+      "onboarding": {
+        "kind": "manual"
+      },
       "order": 100
     },
     "install": {

package/src/onboarding.ts

@@ -16,12 +16,12 @@ export const linkOnboardingAdapter: ChannelOnboardingAdapter = {
   getStatus: async ({ cfg }) => {
     const linkCfg = getLinkConfig(cfg);
     const configured = Boolean(
-      linkCfg?.host && linkCfg?.port && linkCfg?.accessToken
+      linkCfg?.host && linkCfg?.accessToken
     );
 
     const statusLines: string[] = [];
     if (!configured) {
-      statusLines.push("Link: needs host, port, and accessToken");
+      statusLines.push("Link: needs host and accessToken");
     } else {
       statusLines.push(`Link: configured (host: ${linkCfg?.host})`);
     }
@@ -40,24 +40,14 @@ export const linkOnboardingAdapter: ChannelOnboardingAdapter = {
     const linkCfg = getLinkConfig(next) || {} as LinkConfig;
 
     const host = await prompter.text({
-      message: "Link Server Host",
+      message: "Link Server Host (host:port)",
       initialValue: linkCfg.host,
-      placeholder: "e.g. embtcpbeta.bingolink.biz",
+      placeholder: "e.g. embtcpbeta.bingolink.biz:20081",
       validate: (value) => (value?.trim() ? undefined : "Required"),
     });
 
-    const portStr = await prompter.text({
-      message: "Link Server Port",
-      initialValue: linkCfg.port ? String(linkCfg.port) : undefined,
-      placeholder: "e.g. 20081",
-      validate: (value) => {
-        if (!value?.trim()) return "Required";
-        const n = Number(value);
-        if (isNaN(n) || n <= 0) return "Must be a positive number";
-        return undefined;
-      },
-    });
-    const port = Number(portStr);
+    // Remove separate port prompt, as it is merged into host
+    // const portStr = ...
 
     const accessToken = await prompter.text({
       message: "User Access Token",
@@ -65,11 +55,24 @@ export const linkOnboardingAdapter: ChannelOnboardingAdapter = {
       validate: (value) => (value?.trim() ? undefined : "Required"),
     });
 
+    const refreshToken = await prompter.text({
+        message: "Refresh Token (Optional)",
+        initialValue: linkCfg.refreshToken,
+    });
+
+    const ssoUrl = await prompter.text({
+        message: "SSO URL (Optional, for refresh)",
+        initialValue: linkCfg.ssoUrl,
+        placeholder: "e.g. https://sso.example.com",
+    });
+
     const newLinkConfig: LinkConfig = {
       ...linkCfg,
       host: String(host).trim(),
-      port,
+      // port is now part of host string or handled internally
       accessToken: String(accessToken).trim(),
+      refreshToken: refreshToken ? String(refreshToken).trim() : undefined,
+      ssoUrl: ssoUrl ? String(ssoUrl).trim() : undefined,
     };
 
     next = {