@rlynicrisis/link 0.0.9 → 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**，并按照提示输入以下信息：
+在引导过程中选择 **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 刷新请求。
-
-配置完成后，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,36 +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** 回复。
 
-运行所有单元测试：
+### 工作原理
 
-```bash
-npm test
+- **接收**：建立 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"
 ```
 
-### 手动连接测试
+### 配置字段说明
 
-可以使用 `test/manual-connect.ts` 脚本单独测试连接和基本消息收发：
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `groupId` | 群组模式必填 | 要监听的群 ID |
+| `botToken` | 群组模式必填 | 群机器人 Webhook Token |
+| `notificationApiUrl` | 可省略 | Webhook 服务基础地址，默认 `https://notificationapi.bingolink.biz:443/notificationapi` |
 
-```bash
-npx tsx test/manual-connect.ts
+> **说明**：`groupId` + `botToken` 同时存在时自动启用群组模式，否则退回到 FileHelper 模式。
+
+## 多账号支持
+
+插件支持在同一个 OpenClaw 实例中同时连接多个 Link 账号，每个账号独立维护连接和消息路由。
+
+### 配置格式
+
+```yaml
+channels:
+  link:
+    accounts:
+      # FileHelper 账号（最简配置）
+      default:
+        accessToken: "token_for_default_account"
+        refreshToken: "refresh_token_for_default"
+
+      # 群组账号
+      mygroup:
+        accessToken: "token_for_group_account"
+        groupId: "3ab33646-3a55-46fd-97ba-868d4bf29915"
+        botToken: "xxxxxxxxxxxxxxxx"
+
+bindings:
+  - agentId: "main"
+    match:
+      channel: "link"
+      accountId: "default"
+  - agentId: "group-agent"
+    match:
+      channel: "link"
+      accountId: "mygroup"
+```
+
+### 向后兼容
+
+**无需修改现有配置**。如果没有 `accounts` 字段，插件会将根级别的字段视为 `accountId = "default"` 的账号：
+
+```yaml
+# 旧配置格式，继续有效
+channels:
+  link:
+    accessToken: "your_token"
+    refreshToken: "your_refresh_token"
 ```
 
-### 发送文件消息测试
+> `accounts` 字段与根级别的 `accessToken` 互斥。当 `accounts` 存在时，根级别字段会被忽略。
 
-测试发送文件类型消息（构造虚拟文件信息）：
+## 开发调试
+
+### 单元测试
 
 ```bash
-npx tsx test/send-file.ts
+npm test
+```
+
+### 手动连接测试
+
+```bash
+npx tsx test/manual-connect.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,11 +8,31 @@
     "type": "object",
     "additionalProperties": false,
     "properties": {
-      "host": { "type": "string", "description": "Link Server Host (e.g. embtcpbeta.bingolink.biz:20081)" },
-      "ssoUrl": { "type": "string", "description": "SSO URL for refreshing token (e.g. https://sso.example.com)" },
       "accessToken": { "type": "string", "description": "User Access Token" },
       "refreshToken": { "type": "string", "description": "User Refresh Token (Optional)" },
-      "heartbeatIntervalMs": { "type": "number", "default": 30000 }
+      "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",
+        "description": "Multi-account configuration. Keys are accountIds.",
+        "additionalProperties": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["accessToken"],
+          "properties": {
+            "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" }
+          }
+        }
+      }
     }
   }
 }

package/package.json

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

package/src/bot.ts

@@ -2,29 +2,34 @@ import {
   type ClawdbotConfig,
   type RuntimeEnv,
 } from "openclaw/plugin-sdk";
-import { LinkConfig } from "./types.js";
-import { createLinkClient, getLinkClient } from "./client-manager.js";
+import { LinkConfig, LinkChannelConfig, resolveAccountConfig, applyLinkDefaults } from "./types.js";
+import { createLinkClient, getLinkClient, removeLinkClient } from "./client-manager.js";
 import { getLinkRuntime } from "./runtime.js";
 import { createLinkReplyDispatcher } from "./reply-dispatcher.js";
 import { EmbMessage } from "./link/types.js";
 import { MsgType, ParticipantType } from "./link/constants.js";
 
-export async function startLinkBot(cfg: ClawdbotConfig, runtime: RuntimeEnv) {
-  const linkCfg = cfg.channels?.link as LinkConfig | undefined;
-  
-  // Basic validation
-  if (!linkCfg) {
-    // Channel not enabled or configured
+export async function startLinkBot(cfg: ClawdbotConfig, runtime: RuntimeEnv, accountId: string = "default") {
+  const channelCfg = cfg.channels?.link as LinkChannelConfig | undefined;
+
+  if (!channelCfg) {
     return;
   }
-  
+
+  const rawCfg = resolveAccountConfig(channelCfg, accountId);
+
+  if (!rawCfg) {
+    runtime.log?.(`Link: no config found for accountId=${accountId}`);
+    return;
+  }
+
+  const linkCfg = applyLinkDefaults(rawCfg);
+
   if (!linkCfg.accessToken) {
-    runtime.log?.("Link channel configured but missing accessToken");
+    runtime.log?.(`Link channel configured but missing accessToken for accountId=${accountId}`);
     return;
   }
-  
-  const accountId = "default"; // For now single account support
-  
+
   let client = getLinkClient(accountId);
   if (!client) {
     client = createLinkClient(accountId, linkCfg);
@@ -51,8 +56,8 @@ export async function startLinkBot(cfg: ClawdbotConfig, runtime: RuntimeEnv) {
   }
 }
 
-export async function stopLinkBot() {
-  // Implement cleanup if needed
+export async function stopLinkBot(accountId: string = "default") {
+  removeLinkClient(accountId);
 }
 
 async function handleLinkMessage(params: {
@@ -75,15 +80,17 @@ async function handleLinkMessage(params: {
 
   const senderId = msg.fromId || "unknown";
   
-  // SECURITY: Only process messages sent by the bot user itself AND sent to itself (FileHelper/Self)
-  // Note: userId is populated in client.ts into verifyInfo during connection
   const allowedUserId = linkCfg.verifyInfo?.userId;
   const receiverId = msg.toId || "unknown";
 
-  console.log(`[LinkBot] allowedUserId=${allowedUserId}, senderId=${senderId}, receiverId=${receiverId}`);
+  console.log(`[LinkBot] allowedUserId=${allowedUserId}, senderId=${senderId}, receiverId=${receiverId}, toType=${msg.toType}`);
 
-  if (!allowedUserId || senderId !== allowedUserId || receiverId !== allowedUserId) {
-    return;
+  if (linkCfg.groupId) {
+    // Group mode: only accept messages sent to the configured group
+    if (msg.toId !== linkCfg.groupId || msg.toType !== ParticipantType.GROUP) return;
+  } else {
+    // FileHelper mode: only accept self-messages (sender == receiver == self)
+    if (!allowedUserId || senderId !== allowedUserId || receiverId !== allowedUserId) return;
   }
 
   // Convert content to string if it's a buffer

package/src/channel.ts

@@ -1,6 +1,7 @@
 import type { ChannelPlugin } from "openclaw/plugin-sdk";
 import { startLinkBot, stopLinkBot } from "./bot.js";
 import { linkOnboardingAdapter } from "./onboarding.js";
+import { LinkChannelConfig } from "./types.js";
 
 export const linkPlugin: ChannelPlugin<any> = {
   id: "link",
@@ -51,17 +52,21 @@ export const linkPlugin: ChannelPlugin<any> = {
   },
   config: {
     listAccountIds: (cfg) => {
-        // Return default account if channel is configured
-        if (cfg?.channels?.link?.accessToken) { return ["default"]; }
-        return []; 
+      const linkCfg = cfg?.channels?.link as LinkChannelConfig | undefined;
+      if (!linkCfg) return [];
+      if (linkCfg.accounts) {
+        return Object.keys(linkCfg.accounts);
+      }
+      // Backward compat: single-account root config
+      if (linkCfg.accessToken) return ["default"];
+      return [];
     },
     resolveAccount: (cfg, accountId) => {
-      // Return dummy account for now
       return {
         accountId,
         enabled: true,
         configured: true,
-        name: "Link Bot",
+        name: `Link Bot (${accountId})`,
       } as any;
     },
     defaultAccountId: (cfg) => "default",
@@ -77,11 +82,11 @@ export const linkPlugin: ChannelPlugin<any> = {
   },
   gateway: {
     startAccount: async (ctx) => {
-      await startLinkBot(ctx.cfg, ctx.runtime);
-      
+      await startLinkBot(ctx.cfg, ctx.runtime, ctx.accountId);
+
       return new Promise((resolve) => {
         ctx.abortSignal.addEventListener("abort", () => {
-          stopLinkBot();
+          stopLinkBot(ctx.accountId);
           resolve(undefined);
         });
       });

package/src/client-manager.ts

@@ -1,5 +1,5 @@
 import { LinkClient } from "./link/client.js";
-import { LinkConfig } from "./types.js";
+import { LinkConfig, LINK_DEFAULTS } from "./types.js";
 
 const clients = new Map<string, LinkClient>();
 
@@ -14,7 +14,7 @@ export function createLinkClient(accountId: string, config: LinkConfig): LinkCli
   }
   
   // Parse host:port
-  const parts = config.host.split(':');
+  const parts = (config.host || LINK_DEFAULTS.host).split(':');
   let host = parts[0];
   let port = 20081; // Default port
   

package/src/link/client.ts

@@ -13,6 +13,7 @@ export class LinkClient extends EventEmitter {
   private heartbeatInterval: NodeJS.Timeout | null = null;
   private reconnectTimeout: NodeJS.Timeout | null = null;
   private isConnected = false;
+  private immediateReconnect = false;
   
   constructor(
     public readonly config: {
@@ -181,11 +182,13 @@ export class LinkClient extends EventEmitter {
 
   private scheduleReconnect() {
     if (this.reconnectTimeout) return;
+    const delay = this.immediateReconnect ? 0 : 5000;
+    this.immediateReconnect = false;
     this.reconnectTimeout = setTimeout(() => {
       this.reconnectTimeout = null;
       console.log('Reconnecting...');
       this.connect();
-    }, 5000);
+    }, delay);
   }
 
   private processBuffer() {
@@ -250,6 +253,7 @@ export class LinkClient extends EventEmitter {
         if (body) {
           try {
             const msg = decodeMessage(body);
+            this.sendReceipt(msg.id);
             this.emit('message', msg);
           } catch (e) {
             console.error('Failed to decode message:', e);
@@ -278,11 +282,22 @@ export class LinkClient extends EventEmitter {
         // Ignore for now or log
         // console.log(`Received cmd: 0x${cmdCode.toString(16)}, body: ${body}`);
         break;
+      case CmdCodes.FORCE_RECONNECT_DOWN:
+        console.log('Server signaled session reset (0x6b), will reconnect immediately on disconnect');
+        this.immediateReconnect = true;
+        break;
       default:
          console.log(`Received unknown cmd: 0x${cmdCode.toString(16)}, body: ${body}`);
     }
   }
 
+  private sendReceipt(msgId: unknown) {
+    if (!this.socket || !this.isConnected) return;
+    console.log('Sending receipt for message:', msgId);
+    const packet = encodePacket(CmdCodes.SEND_MSG_RECEIPT, String(msgId));
+    this.socket.write(packet);
+  }
+
   private async refreshAccessToken() {
     if (!this.config.refreshToken || !this.config.ssoUrl) {
       console.error('Cannot refresh token: Missing refreshToken or ssoUrl in config');

package/src/link/constants.ts

@@ -19,6 +19,7 @@ export const CmdCodes = {
   SERVICE_TOKEN_UP: 0x10,
   SERVICE_TOKEN_DOWN: 0x11,
   CLEAR_DEVICE_OFFMSG: 0x14,
+  FORCE_RECONNECT_DOWN: 0x6b,   // Server signals session reset / connection cycling
 } as const;
 
 export enum MsgType {

package/src/link/message.js

@@ -1,5 +1,6 @@
 /*eslint-disable block-scoped-var, id-length, no-control-regex, no-magic-numbers, no-prototype-builtins, no-redeclare, no-shadow, no-var, sort-vars*/
-import * as $protobuf from "protobufjs/minimal.js";
+import * as $protobufNs from "protobufjs/minimal.js";
+const $protobuf = $protobufNs.default || $protobufNs;
 
 // Common aliases
 const $Reader = $protobuf.Reader, $Writer = $protobuf.Writer, $util = $protobuf.util;

package/src/send.ts

@@ -8,32 +8,48 @@ export async function sendMessageLink(params: {
   to: string;
   text: string;
   accountId?: string;
-  cfg: LinkConfig; // Might need config for some context
+  cfg: LinkConfig;
 }): Promise<void> {
+  const { cfg } = params;
+
+  // Group bot mode: send via HTTP webhook
+  if (cfg.groupId && cfg.botToken && cfg.notificationApiUrl) {
+    const url = `${cfg.notificationApiUrl}/hook/send?token=${cfg.botToken}`;
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        msgType: 'text',
+        content: { text: params.text }
+      })
+    });
+    if (!res.ok) {
+      throw new Error(`Group bot webhook failed: ${res.status} ${res.statusText}`);
+    }
+    return;
+  }
+
+  // FileHelper mode: send via TCP self-message
   const accountId = params.accountId || "default";
   const client = getLinkClient(accountId);
-  
+
   if (!client) {
     throw new Error(`Link client not found for account ${accountId}`);
   }
 
-  // SECURITY: Only allow sending messages to self
-  // Note: verifyInfo.userId is populated in client.ts
+  // SECURITY: Only allow sending messages to self in non-group mode
   const allowedUserId = client.config.verifyInfo?.userId;
   if (!allowedUserId || params.to !== allowedUserId) {
-    // console.warn(`Link: Blocked outgoing message to ${params.to}. Only self-messages are allowed.`);
-    // Silently fail or throw? Throwing might cause retries or errors in logs.
-    // Let's throw for now to make it explicit.
-    throw new Error(`Link: Sending messages to others (${params.to}) is restricted. Only self-messages allowed.`);
+    throw new Error(`Link: Sending messages to others (${params.to}) is restricted. Only self-messages allowed in non-group mode.`);
   }
 
   const msg: EmbMessage = {
     id: randomUUID(),
     type: MsgType.TEXT,
     content: params.text,
-    fromType: ParticipantType.USER, // Or SYSTEM? Using USER for bot acting as user
+    fromType: ParticipantType.USER,
     fromId: allowedUserId,
-    toType: ParticipantType.USER,  
+    toType: ParticipantType.USER,
     toId: params.to,
     sendTime: Date.now(),
     read: false

package/src/types.ts

@@ -1,18 +1,63 @@
 import type { ClawdbotConfig } from "openclaw/plugin-sdk";
 import { ClientVerifyInfo } from "./link/types.js";
 
+export const LINK_DEFAULTS = {
+  host: 'embtcp.bingolink.biz:20081',
+  ssoUrl: 'https://www.bingolink.biz:443/sso',
+  notificationApiUrl: 'https://notificationapi.bingolink.biz:443/notificationapi',
+} as const;
+
 export interface LinkConfig {
-  host: string;
+  host?: string;                 // Default: embtcp.bingolink.biz:20081
   // port: number; // merged into host
   accessToken: string;
   refreshToken?: string;
-  ssoUrl?: string;
+  ssoUrl?: string;               // Default: https://www.bingolink.biz:443/sso
   verifyInfo?: Partial<ClientVerifyInfo>;
   heartbeatIntervalMs?: number;
   protocol?: "tcp" | "ws"; // Default tcp
+  // Group bot config
+  groupId?: string;              // Group ID to monitor
+  botToken?: string;             // Group bot webhook token
+  notificationApiUrl?: string;   // Default: https://notificationapi.bingolink.biz:443/notificationapi
+}
+
+/** Fill in default values for optional fields that have known defaults. */
+export function applyLinkDefaults(cfg: LinkConfig): LinkConfig {
+  return {
+    ...cfg,
+    host: cfg.host || LINK_DEFAULTS.host,
+    ssoUrl: cfg.ssoUrl || LINK_DEFAULTS.ssoUrl,
+    notificationApiUrl: cfg.notificationApiUrl || LINK_DEFAULTS.notificationApiUrl,
+  };
 }
 
 export interface LinkAccountConfig {
   accountId?: string;
   config: LinkConfig;
 }
+
+/** Top-level channels.link config — supports both single-account and multi-account */
+export interface LinkChannelConfig extends Partial<LinkConfig> {
+  accounts?: Record<string, LinkConfig>;
+}
+
+/**
+ * Resolve the LinkConfig for a given accountId.
+ * When `accounts` is present, looks up the named entry.
+ * Otherwise falls back to the root config (backward-compat single-account "default").
+ */
+export function resolveAccountConfig(
+  channelCfg: LinkChannelConfig,
+  accountId: string
+): LinkConfig | undefined {
+  if (channelCfg.accounts) {
+    return channelCfg.accounts[accountId];
+  }
+  // Backward compat: treat root-level fields as the "default" account
+  if (accountId === "default" && channelCfg.host && channelCfg.accessToken) {
+    const { accounts, ...rest } = channelCfg as any;
+    return rest as LinkConfig;
+  }
+  return undefined;
+}