@zeyiy/openclaw-channel 0.3.5 → 0.3.7

package/README.md

@@ -14,6 +14,9 @@ Chinese documentation: [README.zh-CN.md](https://github.com/ZeyiY/openclaw-chann
 - Quote/reply message parsing for inbound context
 - Multi-account login via `channels.openim.accounts.<id>`
 - Group trigger policy with optional mention-only mode
+- Auto read-receipt for direct messages
+- Per-user session isolation (direct chat) / shared session (group chat)
+- Agent Portal Bridge — persistent WebSocket connection to agent-portal cloud service
 - Interactive setup command: `openclaw openim setup`
 
 ## Installation
@@ -58,7 +61,9 @@ openclaw openim setup
           "enabled": true,
           "token": "your_token",
           "wsAddr": "ws://127.0.0.1:10001",
-          "apiAddr": "http://127.0.0.1:10002"
+          "apiAddr": "http://127.0.0.1:10002",
+          "botId": "my-bot-001",
+          "portalWsAddr": "wss://portal.example.com/ws"
         }
       }
     }
@@ -75,6 +80,8 @@ If set, only these users can trigger processing:
 - direct messages to the account
 - group messages where they `@` the account
 
+`botId` and `portalWsAddr` are optional. When both are set, the plugin establishes a WebSocket connection to the agent-portal cloud service, enabling remote management of agents, files, and models.
+
 Single-account fallback (without `accounts`) is supported.
 
 Environment fallback is supported for the `default` account:
@@ -113,6 +120,27 @@ Optional env overrides:
   - `name` (optional): override filename for URL input
   - `accountId` (optional): select sending account
 
+## Agent Portal Bridge
+
+When `botId` and `portalWsAddr` are configured, the plugin connects to the agent-portal cloud service via WebSocket. The portal can remotely invoke the following methods:
+
+| Method | Description |
+|---|---|
+| `bot.agent.get` | Resolve the agentId bound to the current bot |
+| `models.list` | List available models from config |
+| `agents.list` | List all configured agents |
+| `agents.create` | Create a new agent with workspace |
+| `agents.files.list` | List workspace files for an agent |
+| `agents.files.get` | Read a single workspace file |
+| `agents.files.set` | Write a file to agent workspace |
+| `tools.catalog` | List available tools |
+| `skills.status` | List installed skills/plugins status |
+| `skills.search` | Search ClawHub for skills (placeholder) |
+| `skills.detail` | Get detail for a specific skill |
+| `cron.list` | List configured cron jobs |
+
+The connection features automatic reconnect with exponential backoff and heartbeat keepalive.
+
 ## Development
 
 ```bash

package/README.zh-CN.md

@@ -14,6 +14,9 @@ English documentation: [README.md](https://github.com/ZeyiY/openclaw-channel/blo
 - 支持引用消息解析（用于入站上下文）
 - 支持多账号并发（`channels.openim.accounts.<id>`）
 - 支持群聊仅 @ 触发
+- 私聊消息自动标记已读（已读回执）
+- 每用户独立会话（私聊）/ 同群共享会话（群聊）
+- Agent Portal Bridge — 与 agent-portal 云服务保持 WebSocket 长连接，支持远程管理
 - 提供交互式配置命令：`openclaw openim setup`
 
 ## 安装
@@ -58,7 +61,9 @@ openclaw openim setup
           "enabled": true,
           "token": "your_token",
           "wsAddr": "ws://127.0.0.1:10001",
-          "apiAddr": "http://127.0.0.1:10002"
+          "apiAddr": "http://127.0.0.1:10002",
+          "botId": "my-bot-001",
+          "portalWsAddr": "wss://portal.example.com/ws"
         }
       }
     }
@@ -74,6 +79,8 @@ openclaw openim setup
 - 给账号发单聊消息
 - 在群里 @ 账号的消息
 
+`botId` 和 `portalWsAddr` 为可选项。同时配置后，插件会与 agent-portal 云服务建立 WebSocket 连接，支持远程管理 agent、文件和模型。
+
 支持单账号兜底写法（不使用 `accounts`）。
 
 `default` 账号支持环境变量兜底：
@@ -112,6 +119,27 @@ openclaw openim setup
   - `name`（可选）：URL 输入时覆盖文件名
   - `accountId`（可选）：指定发送账号
 
+## Agent Portal Bridge
+
+配置 `botId` 和 `portalWsAddr` 后，插件会通过 WebSocket 连接到 agent-portal 云服务。Portal 可远程调用以下方法：
+
+| 方法 | 说明 |
+|---|---|
+| `bot.agent.get` | 获取当前 bot 绑定的 agentId |
+| `models.list` | 列出配置中的可用模型 |
+| `agents.list` | 列出所有已配置的 agent |
+| `agents.create` | 创建新 agent 及工作空间 |
+| `agents.files.list` | 列出 agent 工作空间文件 |
+| `agents.files.get` | 读取单个工作空间文件 |
+| `agents.files.set` | 写入文件到 agent 工作空间 |
+| `tools.catalog` | 列出可用工具 |
+| `skills.status` | 列出已安装技能/插件状态 |
+| `skills.search` | 搜索 ClawHub 技能（占位） |
+| `skills.detail` | 获取特定技能详情 |
+| `cron.list` | 列出已配置的定时任务 |
+
+连接支持指数退避自动重连和心跳保活。
+
 ## 开发
 
 ```bash

package/dist/config.js

@@ -62,6 +62,7 @@ function envDefaultAccount() {
         platformID,
         enabled: true,
         requireMention: true,
+        historyLimit: 20,
         botId,
         portalWsAddr,
     };
@@ -89,6 +90,7 @@ function normalizeAccount(accountId, raw) {
     const enabled = raw.enabled !== false;
     const requireMention = raw.requireMention !== false;
     const inboundWhitelist = normalizeInboundWhitelist(raw.inboundWhitelist);
+    const historyLimit = Math.max(1, Math.min(100, toFiniteNumber(raw.historyLimit, 20)));
     const botId = String(raw.botId ?? "").trim() || undefined;
     const portalWsAddr = String(raw.portalWsAddr ?? "").trim() || undefined;
     if (!userID)
@@ -103,6 +105,7 @@ function normalizeAccount(accountId, raw) {
         platformID,
         requireMention,
         inboundWhitelist,
+        historyLimit,
         botId,
         portalWsAddr,
     };

package/dist/inbound.d.ts

@@ -1,3 +1,5 @@
 import { type MessageItem } from "@openim/client-sdk";
-import type { OpenIMClientState } from "./types";
+import type { GroupInfoCacheEntry, GroupMemberCacheEntry, OpenIMClientState } from "./types";
+export declare function fetchGroupInfo(client: OpenIMClientState, groupID: string, logger?: any, forceRefresh?: boolean): Promise<GroupInfoCacheEntry | null>;
+export declare function fetchGroupMembers(client: OpenIMClientState, groupID: string, logger?: any, forceRefresh?: boolean): Promise<GroupMemberCacheEntry | null>;
 export declare function processInboundMessage(api: any, client: OpenIMClientState, msg: MessageItem): Promise<void>;

package/dist/inbound.js

@@ -1,4 +1,4 @@
-import { SessionType } from "@openim/client-sdk";
+import { GroupMemberFilter, SessionType } from "@openim/client-sdk";
 import { appendFileSync } from "node:fs";
 import { sendTextToTarget } from "./media";
 import { formatSdkError } from "./utils";
@@ -14,6 +14,106 @@ const inboundDedup = new Map();
 const INBOUND_DEDUP_TTL_MS = 5 * 60 * 1000;
 const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
 const IMAGE_FETCH_TIMEOUT_MS = 15000;
+// ── Group context caches ──────────────────────────────────────────────
+const groupInfoCache = new Map();
+const groupMemberCache = new Map();
+const groupHistories = new Map();
+const GROUP_CACHE_TTL = 60 * 60 * 1000; // 1 hour
+const DEFAULT_HISTORY_LIMIT = 20;
+const DEFAULT_HISTORY_PROMPT_TEMPLATE = `[Group Chat History] Below are messages from others since your last reply (sender is user ID, body is message content):\n\`\`\`json\n{messages}\n\`\`\`\nPlease respond to the current @mention based on this context.\n\n`;
+export async function fetchGroupInfo(client, groupID, logger, forceRefresh = false) {
+    const cached = groupInfoCache.get(groupID);
+    if (!forceRefresh && cached && Date.now() - cached.fetchedAt < GROUP_CACHE_TTL)
+        return cached;
+    try {
+        const res = await client.sdk.getSpecifiedGroupsInfo([groupID]);
+        const groups = res?.data;
+        if (!Array.isArray(groups) || groups.length === 0)
+            return cached ?? null;
+        const g = groups[0];
+        const entry = {
+            groupName: g.groupName ?? "",
+            notification: g.notification ?? "",
+            introduction: g.introduction ?? "",
+            memberCount: g.memberCount ?? 0,
+            fetchedAt: Date.now(),
+        };
+        groupInfoCache.set(groupID, entry);
+        logger?.info?.(`[openim] group info cached: ${groupID} name=${entry.groupName} members=${entry.memberCount}`);
+        return entry;
+    }
+    catch (e) {
+        logger?.warn?.(`[openim] fetchGroupInfo failed for ${groupID}: ${formatSdkError(e)}`);
+        return cached ?? null;
+    }
+}
+export async function fetchGroupMembers(client, groupID, logger, forceRefresh = false) {
+    const cached = groupMemberCache.get(groupID);
+    if (!forceRefresh && cached && Date.now() - cached.fetchedAt < GROUP_CACHE_TTL)
+        return cached;
+    try {
+        const uidToName = new Map();
+        let offset = 0;
+        const pageSize = 200;
+        // Paginate until we have all members
+        for (;;) {
+            const res = await client.sdk.getGroupMemberList({ groupID, filter: GroupMemberFilter.All, offset, count: pageSize });
+            const members = res?.data;
+            if (!Array.isArray(members) || members.length === 0)
+                break;
+            for (const m of members) {
+                if (m.userID) {
+                    uidToName.set(m.userID, m.nickname || m.userID);
+                }
+            }
+            if (members.length < pageSize)
+                break;
+            offset += pageSize;
+        }
+        if (uidToName.size === 0)
+            return cached ?? null;
+        const entry = { uidToName, fetchedAt: Date.now() };
+        groupMemberCache.set(groupID, entry);
+        logger?.info?.(`[openim] group members cached: ${groupID} count=${uidToName.size}`);
+        return entry;
+    }
+    catch (e) {
+        logger?.warn?.(`[openim] fetchGroupMembers failed for ${groupID}: ${formatSdkError(e)}`);
+        return cached ?? null;
+    }
+}
+function buildGroupSystemPrompt(info) {
+    const parts = [];
+    parts.push(`## 群聊上下文（Group Chat Context）\n`);
+    parts.push(`你当前在 OpenIM 群：\`${info.groupName}\`。`);
+    parts.push(`普通回复会自动发到该群，不需要额外操作。`);
+    parts.push(`只在需要对方回复你时才使用 @，仅仅提及某人时直接说名字即可。\n`);
+    if (info.notification) {
+        parts.push(`群公告：${info.notification}`);
+    }
+    if (info.introduction) {
+        parts.push(`群简介：${info.introduction}`);
+    }
+    return parts.join("\n");
+}
+function buildMemberListPrefix(uidToName) {
+    if (uidToName.size === 0)
+        return "";
+    const members = Array.from(uidToName.entries());
+    const memberLines = members
+        .map(([uid, name]) => `  ${name} (${uid})`)
+        .join("\n");
+    return `[Group Members]\n${memberLines}\n\nWhen mentioning a group member, use @userID (e.g. @${members[0][0]}). Do NOT use @displayName — only the numeric/alphanumeric userID works.\n\n`;
+}
+function buildHistoryPrefix(entries, uidToName) {
+    if (entries.length === 0)
+        return "";
+    const messagesJson = JSON.stringify(entries.map((e) => ({
+        sender: e.senderName ? `${e.senderName}(${e.sender})` : e.sender,
+        body: e.body,
+    })), null, 2);
+    return DEFAULT_HISTORY_PROMPT_TEMPLATE.replace("{messages}", messagesJson);
+}
 function normalizeImageMimeType(value) {
     const mime = String(value ?? "").trim().toLowerCase();
     return mime.startsWith("image/") ? mime : undefined;
@@ -340,9 +440,95 @@ export async function processInboundMessage(api, client, msg) {
             return;
         }
     }
-    else if (group && client.config.requireMention && !mentioned) {
-        api.logger?.debug?.(`[openim] ignore group message: requireMention=true but bot not mentioned, groupID=${msg.groupID}`);
-        return;
+    // ── Group context: fetch group info & members (cached) ────────────
+    let groupSystemPrompt;
+    let memberListPrefix = "";
+    let historyPrefix = "";
+    const historyLimit = client.config.historyLimit ?? DEFAULT_HISTORY_LIMIT;
+    if (group && msg.groupID) {
+        // Fetch group info → SystemPrompt (fire-and-forget-safe, uses cache)
+        const groupInfo = await fetchGroupInfo(client, msg.groupID, api.logger);
+        if (groupInfo) {
+            groupSystemPrompt = buildGroupSystemPrompt(groupInfo);
+        }
+        // Fetch group members → member list prefix (cached)
+        const memberData = await fetchGroupMembers(client, msg.groupID, api.logger);
+        if (memberData) {
+            memberListPrefix = buildMemberListPrefix(memberData.uidToName);
+        }
+    }
+    // ── requireMention history gating ─────────────────────────────────
+    if (group && client.config.requireMention) {
+        if (!mentioned) {
+            // Not @mentioned → cache message for later history injection, don't trigger LLM
+            const groupID = String(msg.groupID);
+            if (!groupHistories.has(groupID)) {
+                groupHistories.set(groupID, []);
+            }
+            const entries = groupHistories.get(groupID);
+            entries.push({
+                sender: String(msg.sendID),
+                senderName: String(msg.senderNickname || ""),
+                body: inbound.body,
+                timestamp: msg.sendTime || Date.now(),
+            });
+            // Sliding window
+            while (entries.length > historyLimit) {
+                entries.shift();
+            }
+            api.logger?.info?.(`[openim] [HISTORY] cached non-mention msg | group=${groupID} | sender=${msg.sendID} | cached=${entries.length}`);
+            return;
+        }
+        // @mentioned → build history prefix from cached + API messages
+        const groupID = String(msg.groupID);
+        let entries = groupHistories.get(groupID) ?? [];
+        // If cache is insufficient, supplement from API
+        const cacheInsufficient = entries.length < Math.ceil(historyLimit / 2);
+        if (cacheInsufficient) {
+            api.logger?.info?.(`[openim] [MENTION] cache insufficient (${entries.length}/${historyLimit}), fetching from API...`);
+            try {
+                const conversationID = `sg_${msg.groupID}`;
+                const res = await client.sdk.getAdvancedHistoryMessageList({
+                    conversationID,
+                    startClientMsgID: "",
+                    count: historyLimit,
+                });
+                const apiMessages = res?.data?.messageList;
+                if (Array.isArray(apiMessages) && apiMessages.length > 0) {
+                    // Filter out empty/meaningless messages
+                    const filtered = apiMessages
+                        .filter((m) => {
+                        const body = String(m.textElem?.content ?? m.atTextElem?.text ?? m.content ?? "").trim();
+                        return !!body;
+                    })
+                        .slice(-historyLimit);
+                    entries = filtered.map((m) => ({
+                        sender: String(m.sendID),
+                        senderName: String(m.senderNickname || ""),
+                        body: String(m.textElem?.content ?? m.atTextElem?.text ?? m.content ?? "[消息]").trim(),
+                        timestamp: m.sendTime || Date.now(),
+                    }));
+                    api.logger?.info?.(`[openim] [MENTION] fetched ${entries.length} history messages from API`);
+                }
+            }
+            catch (e) {
+                api.logger?.warn?.(`[openim] [MENTION] API history fetch failed: ${formatSdkError(e)}`);
+            }
+        }
+        // Take last N entries
+        if (entries.length > historyLimit) {
+            entries = entries.slice(-historyLimit);
+            groupHistories.set(groupID, entries);
+        }
+        const memberUidToName = groupMemberCache.get(groupID)?.uidToName ?? new Map();
+        historyPrefix = buildHistoryPrefix(entries, memberUidToName);
+        if (historyPrefix) {
+            api.logger?.info?.(`[openim] [MENTION] injected history context | ${entries.length} messages | ${historyPrefix.length} chars`);
+        }
+    }
+    else if (group && !client.config.requireMention && !mentioned) {
+        // requireMention=false: all messages trigger LLM, no history gating needed
+        // (no return, fall through to dispatch)
     }
     // 会话隔离：群聊按 groupID 分 session，私聊按发送者 ID 分 session
     const baseSessionKey = group ? `openim:group:${msg.groupID}`.toLowerCase() : `openim:dm:${msg.sendID}`.toLowerCase();
@@ -367,7 +553,12 @@ export async function processInboundMessage(api, client, msg) {
     const mediaResult = await materializeInboundMedia(inbound.media);
     const warningText = mediaResult.warnings.map((warning) => `[Media fetch failed] ${warning}`).join("\n");
     const rawBody = warningText ? `${inbound.body}\n${warningText}` : inbound.body;
-    const body = buildTextEnvelope(runtime, cfg, fromLabel, senderId, timestamp, rawBody, chatType);
+    // Envelope wraps only the raw message text (with sender prefix)
+    const envelopedBody = buildTextEnvelope(runtime, cfg, fromLabel, senderId, timestamp, rawBody, chatType);
+    // Prepend member list + history BEFORE the envelope so they appear cleanly above the sender line
+    const body = (memberListPrefix || historyPrefix)
+        ? (memberListPrefix + historyPrefix + envelopedBody)
+        : envelopedBody;
     if (mediaResult.warnings.length > 0) {
         for (const warning of mediaResult.warnings) {
             api.logger?.warn?.(`[openim] inbound media fetch failed: ${warning}`);
@@ -375,13 +566,14 @@ export async function processInboundMessage(api, client, msg) {
     }
     const ctxPayload = {
         Body: body,
+        BodyForAgent: body,
         RawBody: rawBody,
         From: group ? `openim:group:${msg.groupID}` : `openim:${msg.sendID}`,
         To: `openim:${client.config.userID}`,
         SessionKey: sessionKey,
         AccountId: client.config.accountId,
         ChatType: chatType,
-        ConversationLabel: group ? `openim:g-${msg.groupID}` : `openim:${senderId}`, // 会话标签：群聊用群ID，私聊用用户ID
+        ConversationLabel: group ? `openim:g-${msg.groupID}` : `openim:${senderId}`,
         SenderName: fromLabel,
         SenderId: senderId,
         Provider: "openim",
@@ -391,6 +583,7 @@ export async function processInboundMessage(api, client, msg) {
         OriginatingChannel: "openim",
         OriginatingTo: `openim:${client.config.userID}`,
         CommandAuthorized: true,
+        GroupSystemPrompt: groupSystemPrompt,
         _openim: {
             accountId: client.config.accountId,
             isGroup: group,

package/dist/media.js

@@ -78,8 +78,8 @@ export async function sendTextToTarget(client, target, text) {
     if (target.kind === "group") {
         // 统一 <@ID> 和 @ID 两种格式，收集去重后的被 @ 用户 ID
         const atIDs = new Set();
-        const normalizedText = text.replace(/<@(\d{6,})>/g, (_m, id) => { atIDs.add(id); return `@${id}`; });
-        for (const m of normalizedText.matchAll(/@(\d{6,})/g))
+        const normalizedText = text.replace(/<@([a-zA-Z0-9_]{4,})>/g, (_m, id) => { atIDs.add(id); return `@${id}`; });
+        for (const m of normalizedText.matchAll(/@([a-zA-Z0-9_]{4,})/g))
             atIDs.add(m[1]);
         if (atIDs.size > 0) {
             const atUserIDList = [...atIDs];