@qihoo/tuitui-openclaw-channel 1.0.12 → 1.0.13

package/index.ts

@@ -1,6 +1,7 @@
 import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
 import { emptyPluginConfigSchema } from 'openclaw/plugin-sdk';
 import { createTuiTuiChannelPlugin } from './src/channel';
+import { registerTuituiTools } from './src/tools';
 import { CHANNEL_ID, CHANNEL_NAME } from './src/const';
 import { id } from './openclaw.plugin.json';
 
@@ -12,6 +13,7 @@ const plugin = {
   register(api: OpenClawPluginApi) {
     console.log(`[${CHANNEL_ID}] Plugin.register Before.`);
     api.registerChannel({ plugin: createTuiTuiChannelPlugin(api.runtime) });
+    registerTuituiTools(api);
     console.log(`[${CHANNEL_ID}] Plugin.register After.`);
   },
 };

package/openclaw.plugin.json

@@ -1,6 +1,7 @@
 {
   "id": "tuitui-openclaw-channel",
   "channels": ["tuitui"],
+  "skills": ["./skills"],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qihoo/tuitui-openclaw-channel",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "maintainers": [
     {
       "name": "huzunjie",
@@ -18,6 +18,7 @@
   "description": "TuiTui channel plugin for OpenClaw",
   "type": "module",
   "dependencies": {
+    "@sinclair/typebox": "^0.34.48",
     "ws": "^8.13.0"
   },
   "openclaw": {

package/skills/tuitui-im-read/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: tuitui-im-read
+description: |
+  推推(tuitui) IM 消息读取工具使用指南
+
+  **当以下情况时使用此 Skill**:
+  (1) 需要获取群聊或单聊的历史消息
+  (2) 用户提到"聊天记录"、"消息"、"群里说了什么"
+  (3) 需要按时间范围过滤消息、分页获取更多消息
+---
+
+# 推推 IM 消息读取
+
+## 执行前必读
+
+- 该 Skill 中的所有消息读取工具均以机器人身份调用，只能读取机器人有权限的会话。
+
+---
+
+## 工具：tuitui_im_get_messages
+
+### 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `chatId` | string | ✅ | 聊天 ID。单聊填对方的 tuitui account，群聊填群 ID |
+| `chatType` | string | ✅ | 聊天类型：单聊填 `direct`，群聊填 `group` |
+| `relativeTime` | string | ❌ | 相对时间范围：today / yesterday / day_before_yesterday / this_week / last_week / this_month / last_month / last_{N}_{unit}（unit: minutes/hours/days）。与 `startTime`/`endTime` 互斥 |
+| `startTime` | string | ❌ | 起始时间，ISO 8601 格式，如 `2026-02-27T00:00:00+08:00`。不填默认从最早开始。与 `relativeTime` 互斥 |
+| `endTime` | string | ❌ | 结束时间，ISO 8601 格式，如 `2026-02-27T23:59:59+08:00`。不填默认到当前时间。与 `relativeTime` 互斥 |
+| `limit` | number | ❌ | 每页条数，范围 1~100，默认 100 |
+| `cursor` | string | ❌ | 分页游标，首次调用填 `"0"`，翻页时传上次返回的 `cursor` |
+| `orderAsc` | boolean | ❌ | 排序方向，`true` 正序（从旧到新），`false` 逆序（从新到旧，默认） |
+
+### 返回结构
+
+```json
+{
+  "errcode": 0,
+  "errmsg": "ok",
+  "cursor": "xxx",
+  "has_more": true,
+  "current_time": "2026-03-21 10:00:00",
+  "msgs": [
+    {
+      "user_account": "zhangsan",
+      "user_name": "张三",
+      "msg_time": "2026-01-03 15:42:44",
+      "msg_type": "text",
+      "text": "消息内容",
+      "images": [],
+      "group_id": "group_abc",
+      "group_name": "某群",
+      "at_me": false,
+      "ref": null
+    }
+  ]
+}
+```
+
+字段说明：
+
+| 字段 | 说明 |
+|------|------|
+| `current_time` | 当前服务器时间，格式 `YYYY-MM-DD HH:MM:SS`，辅助理解消息的相对时间 |
+| `has_more` | `true` 时说明还有更多数据，可用返回的 `cursor` 继续翻页 |
+| `msgs` | 消息列表，空数组表示该时间段内没有消息 |
+| `msgs[].user_account` | 发送者账号 |
+| `msgs[].user_name` | 发送者显示名称 |
+| `msgs[].msg_time` | 消息时间，格式 `YYYY-MM-DD HH:MM:SS` |
+| `msgs[].msg_type` | 消息类型：`text` / `image` / `mixed` / `voice` / `file` |
+| `msgs[].text` | 文本内容（`msg_type` 为 `text` / `mixed` 时有值） |
+| `msgs[].images` | 图片 URL 列表（`msg_type` 为 `image` / `mixed` 时有值） |
+| `msgs[].file` | 文件信息 `{ name, url, file_id }`（`msg_type` 为 `file` 时有值） |
+| `msgs[].at_me` | 是否 @ 了机器人（群聊） |
+| `msgs[].ref` | 引用/回复的原消息，无引用时为 `null` |
+
+---
+
+## 核心约束
+
+### 1. 时间范围：确保消息覆盖完整
+
+- 用户说"今天"、"最近"等相对时间时，自主推算对应的 `startTime` / `endTime`（ISO 8601，+08:00 时区）
+- 不确定范围时适当放宽，宁可多拉再过滤
+
+### 2. 分页：根据需要翻页获取更多结果
+
+- 返回结果中 `has_more=true` 时，将 `cursor` 传入下次调用继续获取下一页
+- 根据用户需求判断是否需要翻页：需要完整结果时继续翻页，浏览概览时第一页通常够用
+
+### 3. 排序方向
+
+- 默认 `orderAsc=false`（逆序），拉取最新消息
+- 需要按时间顺序阅读时，传 `orderAsc=true`
+
+---
+
+## 使用场景示例
+
+### 场景 1：获取群聊最新消息
+
+```json
+{
+  "chatId": "4511334567",
+  "chatType": "group"
+}
+```
+
+### 场景 2：获取某时间段内的单聊消息
+
+```json
+{
+  "chatId": "zhangsan",
+  "chatType": "direct",
+  "startTime": "2026-03-01T00:00:00+08:00",
+  "endTime": "2026-03-01T23:59:59+08:00",
+  "orderAsc": true
+}
+```
+
+### 场景 3：分页获取更多消息
+
+第一次调用返回 `has_more: true` 和 `cursor: "xxx"`，继续获取：
+
+```json
+{
+  "chatId": "4511334567",
+  "chatType": "group",
+  "cursor": "xxx"
+}
+```
+
+---
+
+## 常见错误与排查
+
+| 错误现象 | 根本原因 | 解决方案 |
+|---------|---------|---------|
+| 消息结果为空 | 时间范围不对或 chatId 有误 | 检查 `chatId`、`chatType`，适当放宽时间范围 |
+| 消息不完整 | 没有检查 `has_more` 并翻页 | `has_more=true` 时用返回的 `cursor` 继续翻页 |
+| 报错 invalid tuitui account | 账号未配置或未启用 | 确认 tuitui 账号已正确配置 |
+| 消息顺序不对 | `orderAsc` 方向有误 | 按需传 `orderAsc: true/false` |

package/src/accounts.ts

@@ -0,0 +1,25 @@
+import { parseAllowFroms } from './utils';
+import { capabilities, configSchema, baseFildsDefault } from './confs';
+import {  CHANNEL_ID,} from "./const";
+import {  DEFAULT_ACCOUNT_ID,} from 'openclaw/plugin-sdk';
+
+const isEnabled = (val: any) => val === undefined || !!val;
+
+export const resolveAccount = (cfg: any, accountId?: string | null) => {
+  const channelConfig = cfg?.channels?.[CHANNEL_ID] || {};
+  const targetId = accountId || DEFAULT_ACCOUNT_ID;
+  const acct = targetId === DEFAULT_ACCOUNT_ID ? channelConfig : channelConfig.accounts?.[targetId];
+  return {
+    accountId: targetId,
+    enabled: isEnabled(acct?.enabled),
+    appId: acct?.appId || '',
+    appSecret: acct?.appSecret || '',
+    dmPolicy: acct?.dmPolicy || baseFildsDefault.dmPolicy,
+    allowFrom: parseAllowFroms(acct?.allowFrom || baseFildsDefault.allowFrom),
+    // 群组策略与白名单、群组级覆盖
+    groupPolicy: acct?.groupPolic || baseFildsDefault.groupPolicy,
+    groupAllowFrom: parseAllowFroms(acct?.groupAllowFrom || baseFildsDefault.groupAllowFrom),
+    requireMention: isEnabled(acct?.requireMention ?? baseFildsDefault.requireMention),
+    channelContext: acct?.channelContext || baseFildsDefault.channelContext,
+  };
+};

package/src/channel.ts

@@ -11,7 +11,6 @@ import {
   deleteAccountFromConfigSection,
 } from 'openclaw/plugin-sdk';
 import { CHANNEL_ID, CHANNEL_NAME } from "./const";
-
 import {
   checkAccount,
   sendTextMsg,
@@ -19,31 +18,14 @@ import {
   sendMediaMsg,
   guessChatType,
 } from "./outbound";
-
 import { handleInboundMessage } from './inbound';
-
 import { capabilities, configSchema, baseFildsDefault } from './confs';
+import { resolveAccount } from "./accounts"
+
 
 const isEnabled = (val: any) => val === undefined || !!val;
 const isConfigured = (account: any)=> !!(account?.appId && account?.appSecret);
-const resolveAccount = (cfg: any, accountId?: string | null) => {
-  const channelConfig = cfg?.channels?.[CHANNEL_ID] || {};
-  const targetId = accountId || DEFAULT_ACCOUNT_ID;
-  const acct = targetId === DEFAULT_ACCOUNT_ID ? channelConfig : channelConfig.accounts?.[targetId];
-  return {
-    accountId: targetId,
-    enabled: isEnabled(acct?.enabled),
-    appId: acct?.appId as string | undefined,
-    appSecret: acct?.appSecret as string | undefined,
-    dmPolicy: acct?.dmPolicy || baseFildsDefault.dmPolicy,
-    allowFrom: acct?.allowFrom || baseFildsDefault.allowFrom,
-    // 群组策略与白名单、群组级覆盖
-    groupPolicy: (acct?.groupPolicy as string | undefined) || baseFildsDefault.groupPolicy,
-    groupAllowFrom: acct?.groupAllowFrom || baseFildsDefault.groupAllowFrom,
-    requireMention: isEnabled(acct?.requireMention),
-    channelContext: acct?.channelContext || baseFildsDefault.channelContext,
-  };
-};
+
 const wsReadyStates = ['CONNECTING', 'OPEN', 'CLOSING', 'CLOSED'] as const;
 let wsNumber = 0;
 
@@ -288,7 +270,7 @@ export function createTuiTuiChannelPlugin(apiRuntime: any) {
             const wsEvent = json?.body?.event;
             if (wsEvent === 'keepalive') return;
 
-            log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, WebSocket[${wsId}] Received message: ${wsData}`);
+            log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, WebSocket[${wsId}], Received event ${wsEvent}, body ${JSON.stringify(json?.body, null, 2)}`);
 
             if (!json?.header || !wsEvent || !json?.body?.data) {
               return log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, WebSocket[${wsId}] invalid message`);

package/src/inbound.ts

@@ -12,7 +12,6 @@
  */
 import type { TuiTuiInboundMessage, TuiTuiOutboundDeliverOptions } from './types';
 import { CHANNEL_ID } from './const';
-
 import {
   CHAT_TYPE_DIRECT,CHAT_TYPE_GROUP,CHAT_TYPE_CHANNEL,ChatType,
   buildMessageBody,
@@ -23,10 +22,7 @@ import {
   teamsBuildChatId,
   teamsParseChatId,
 } from "./outbound";
-
-const arrLowerCaseTrim = (arr: any[]) =>
-  arr.filter((v: any) => !!v).map((v: any) => String(v).toLowerCase().trim());
-
+import { parseAllowFroms } from './utils';
 
 /** 子函数共享的可变上下文，子函数直接修改字段，外层读取结果 */
 interface ChatPayload {
@@ -42,37 +38,32 @@ interface ChatPayload {
   tuituiUserName: string | undefined;
 }
 
+export interface InboundAccount {
+  accountId: string;
+  appId: string;
+  appSecret: string;
+  dmPolicy: string;
+  allowFrom: string[];
+  groupPolicy: string;
+  groupAllowFrom: string[];
+  requireMention: boolean;
+  channelContext: string;
+}
 export interface InboundHandlerOptions {
   json: any
-  account: {
-    accountId?: string;
-    appId?: string;
-    appSecret?: string;
-    dmPolicy?: string;
-    allowFrom?: any[];
-    groupPolicy?: string;
-    groupAllowFrom?: any[];
-    requireMention?: boolean;
-    channelContext?: string;
-  };
+  account: InboundAccount;
   apiRuntime: any;
   log: any;
 }
 
-function getSessionKey(
-  cfg: any,
-  payload: ChatPayload,
-  account: InboundHandlerOptions['account'],
-  apiRuntime: InboundHandlerOptions['apiRuntime']
-): string | undefined {
+function getSessionKey(cfg: any, payload: ChatPayload, account: InboundAccount, apiRuntime: any): string {
   const { chatId, chatType } = payload;
-  if (!chatId) return undefined;
   const { accountId, channelContext } = account;
   // 你自己只需要拼接与定义 peer.id
   // 关于 sessionKey 格式的解释: https://docs.openclaw.ai/channels/channel-routing#sessionkey-%E5%8F%82%E8%80%83%E6%A0%BC%E5%BC%8F
   let  id = chatId;
   if(chatType == CHAT_TYPE_CHANNEL) {
-    const { channel_id, parent_id } = teamsParseChatId(chatId);
+    const { channel_id, parent_id } = teamsParseChatId(chatId!);
     id = `${channel_id}`;
     if(channelContext == 'thread' && parent_id) {
        id += `:thread:${parent_id}`;
@@ -86,7 +77,7 @@ function getSessionKey(
     channel: CHANNEL_ID,
     peer: {  kind: chatType, id:    id },
   });
-  return sessionKey;
+  return String(sessionKey).replace(/\//g, '_');
 }
 
 function getMediaUrls({ msg_type, images, voice, file }: any): string[] | undefined {
@@ -100,131 +91,46 @@ function getMediaUrls({ msg_type, images, voice, file }: any): string[] | undefi
   return undefined;
 }
 
-/**
- * 处理长链接消息
- * account: 长连接初始化时，对应的Account配置信息
- * accountId: 长连接启动初始化，对应的配置ID
- */
-export async function handleInboundMessage({ json, account, apiRuntime, log }: InboundHandlerOptions) {
-    // Signature / AppId validation
-    const { accountId, appId, appSecret } = account;
-    if (appSecret && appId && json.header['X-Tuitui-Robot-Appid'] !== appId) {
-      log?.info?.(`[${CHANNEL_ID}] Invalid appId`);
-      return;
-    }
-
-    // Decode message
-    const msg = json.body as TuiTuiInboundMessage;
-    const msgData = msg.data;
-    const { ref } = msgData;
-    const payload: ChatPayload = {
-      chatType:     CHAT_TYPE_DIRECT,
-      chatId:       undefined, 
-      text:         undefined,
-      groupName:    undefined,
-      mediaUrls:    getMediaUrls(msgData),
-      replyToId:    ref?.is_me && ref?.msgid ? ref.msgid : undefined,
-      tuituiAccount: msg.user_account || "",
-      tuituiUid:     msg.uid || "",
-      tuituiUserName: msg.user_name || "",
-    };
-    const wsEvent = json.body.event;
-    // Event-type branching
-    if (wsEvent === 'single_chat') {
-      const valid = await parseSingleChat(payload, msgData, account, apiRuntime, log);
-      if (!valid) return;
-    } else if (wsEvent === 'group_chat') {
-      const valid = await parseGroupChat(payload, msgData, account, apiRuntime, log);
-      if (!valid) return;
-    } else if (wsEvent === 'teams_post_create') {
-      const valid = await parseTeamsPost(payload, msgData, account, apiRuntime, log);
-      if (!valid) return;
-    } else {
-      log?.info?.(`[${CHANNEL_ID}] ignore unknown event ${wsEvent}`);
-      return;
-    }
-    if (!payload.chatId || !payload.msgId) {
-      log?.info?.(`[${CHANNEL_ID}] ignore unknown mseeage, missing chatId or msgId`, payload);
-      return;
-    }
-
-    // 因为回复较慢，先回复一个表情
-    await tuituiEmojiReaction(account, payload.chatId, payload.chatType, payload.msgId, '收到');
-
-    // 路由判断
-    const routeSenderFrom = payload.tuituiAccount || payload.tuituiUid || 'unknown';
-
-    const cfg = await apiRuntime.config.loadConfig();
-    const sessionKey = getSessionKey(cfg, payload, account, apiRuntime);
-
-    console.log(`[${CHANNEL_ID}] AccountId: ${accountId}, chatType: ${payload.chatType}, chatId ${payload.chatId}, routeSenderFrom: ${routeSenderFrom}`);
-    console.log(`[${CHANNEL_ID}] AccountId: ${accountId}, dispatching to agent session=${sessionKey}`);
-
-    const ctx: any = {
-      Body:               payload.text! || ' ',
-      From:               String(routeSenderFrom),
-      To:                 CHANNEL_ID,
-      SessionId:          String(sessionKey).replace(/\//g, '_'),
-      SessionKey:         String(sessionKey).replace(/\//g, '_'),
-      AccountId:          accountId,
-      OriginatingChannel: CHANNEL_ID,
-      OriginatingTo:      payload.chatId,
-      ChatType:           payload.chatType!,
-      Surface:            CHANNEL_ID,
-      Provider:           CHANNEL_ID,
-      SenderName:         payload.tuituiUserName,
-      MsgUname:           payload.tuituiAccount,
-      UserAccount:        payload.tuituiAccount,
-      CommandAuthorized:  true,  // 允许 /new 等内置命令
-    };
-    if (payload.chatType == CHAT_TYPE_GROUP && payload.chatId) {
-      ctx.GroupSubject = payload.groupName;
-      ctx.GroupId      = payload.chatId;
-    }
-    if (payload.mediaUrls?.length)  ctx.MediaUrls  = payload.mediaUrls;
-    if (payload.replyToId)          ctx.ReplyToId  = payload.replyToId;
-
-    console.log(`[${CHANNEL_ID}] AccountId: ${accountId}, handleInboundMessage payload`, payload);
-
-
-    await apiRuntime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-      ctx,
-      cfg,
-      dispatcherOptions: {
-        deliver: async (outbound: TuiTuiOutboundDeliverOptions) => {
-          // Custom message (e.g. page)
-          if (outbound.custom) {
-            const { msgtype, page, tousers, togroups } = outbound.custom;
-            if (msgtype === 'page' && page) {
-              await sendPageMsg(account, payload.chatId, payload.chatType, page, 'tuitui.deliver.page', tousers, togroups);
-              return;
-            }
-            log?.warn?.(`[${CHANNEL_ID}] AccountId: ${accountId}, Unsupported custom message type: ${msgtype}`);
-            return;
-          }
-
-          // Media message
-          const mediaUrl = outbound.mediaUrl || outbound.mediaUrls?.[0];
-          if (mediaUrl) {
-            await sendMediaMsg(account, payload.chatId, payload.chatType, mediaUrl, 'tuitui.deliver.media', [payload.tuituiAccount]);
-            return;
-          }
-
-          // Text message
-          const replyText = outbound?.text || outbound?.body;
-          if (replyText) {
-            // 群消息回复时不再使用 reference_msgid 避免并发时引用错乱，依靠 @ 来提醒用户
-            await sendTextMsg(account, payload.chatId, payload.chatType, replyText, 'tuitui.deliver.text', [payload.tuituiAccount]);
+async function dispatchReply(ctx: any, cfg: any, account: InboundAccount, payload: ChatPayload, apiRuntime: any, log: any) {
+  const { accountId } = account;
+  await apiRuntime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx,
+    cfg,
+    dispatcherOptions: {
+      deliver: async (outbound: TuiTuiOutboundDeliverOptions) => {
+        // Custom message (e.g. page)
+        if (outbound.custom) {
+          const { msgtype, page, tousers, togroups } = outbound.custom;
+          if (msgtype === 'page' && page) {
+            await sendPageMsg(account, payload.chatId, payload.chatType, page, 'tuitui.deliver.page', tousers, togroups);
             return;
           }
-          log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, no_reply_content`);
-        },
+          log?.warn?.(`[${CHANNEL_ID}] AccountId: ${accountId}, Unsupported custom message type: ${msgtype}`);
+          return;
+        }
+
+        // Media message
+        const mediaUrl = outbound.mediaUrl || outbound.mediaUrls?.[0];
+        if (mediaUrl) {
+          await sendMediaMsg(account, payload.chatId, payload.chatType, mediaUrl, 'tuitui.deliver.media', [payload.tuituiAccount]);
+          return;
+        }
+
+        // Text message
+        const replyText = outbound?.text || outbound?.body;
+        if (replyText) {
+          // 群消息回复时不再使用 reference_msgid 避免并发时引用错乱，依靠 @ 来提醒用户
+          await sendTextMsg(account, payload.chatId, payload.chatType, replyText, 'tuitui.deliver.text', [payload.tuituiAccount]);
+          return;
+        }
+        log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, no_reply_content`);
+      },
 
-        onReplyStart: () => {
-          log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, Agent reply started for ${payload.tuituiAccount ?? payload.tuituiUid}`);
-        },
+      onReplyStart: () => {
+        log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, Agent reply started for ${payload.tuituiAccount ?? payload.tuituiUid}`);
       },
-    });
+    },
+  });
 }
 
 /***  配对节流映射 - 用于防止短时间内大量重复配对请求消息发出
@@ -262,188 +168,241 @@ async function sendSingleChatPairingMsg(account: any, payload: any, log: any, ap
 }
 
 /**
- * 处理单聊（single_chat）分支，直接修改 payload。
+ * 处理单聊（single_chat）、群聊、团队帖子分支，直接修改并校验 payload。
  * 返回 false 表示消息不合法，外层应提前 return；返回 true 表示校验通过，继续执行。
  */
-async function parseSingleChat(
-  payload:    ChatPayload,
-  msgData:    any,
-  account:    InboundHandlerOptions['account'],
-  apiRuntime: any,
-  log:        any,
-): Promise<boolean> {
-  const { accountId, dmPolicy } = account;
-  const chatId     = payload.tuituiAccount ? String(payload.tuituiAccount || '').toLowerCase().trim() : '';
-  if (dmPolicy === 'disabled') {  //['pairing', 'allowlist', 'open', 'disabled'],
-    log?.warn?.(`[${CHANNEL_ID}] AccountId: ${accountId}, DM disabled sender=${chatId}`);
-    return false;
-  }
+const parseAndVerifyPayload: Record<string, Function> = {
+  single_chat: async (payload: ChatPayload, msgData: any, account: InboundAccount, apiRuntime: any, log: any): Promise<boolean> => {
+    const { accountId, dmPolicy, allowFrom } = account;
+    const chatId     = payload.tuituiAccount ? String(payload.tuituiAccount || '').toLowerCase().trim() : '';
+    if (dmPolicy === 'disabled') {  //['pairing', 'allowlist', 'open', 'disabled'],
+      log?.warn?.(`[${CHANNEL_ID}] AccountId: ${accountId}, DM disabled sender=${chatId}`);
+      return false;
+    }
+
+    payload.chatType = CHAT_TYPE_DIRECT;
+    payload.chatId   = chatId;
+    payload.text     = buildMessageBody(msgData);
+    payload.msgId    = msgData.msgid;
+    log?.debug?.(
+      `[${CHANNEL_ID}] AccountId: ${accountId}, inbound single_chat:
+      userAccount=${chatId},
+      tuituiUid=${payload.tuituiUid},
+      tuituiUserName=${payload.tuituiUserName},
+      dmPolicy=${dmPolicy},
+      allowFrom=${JSON.stringify(allowFrom)}`);
+
+    if (!chatId && !payload.tuituiUid) {
+      log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, Missing user_account or uid in single_chat event`);
+      return false;
+    }
+
+    if (dmPolicy === 'open') return true;
 
-  payload.chatType = CHAT_TYPE_DIRECT;
-  payload.chatId   = chatId;
-  payload.text     = buildMessageBody(msgData);
-  payload.msgId    = msgData.msgid;
-  log?.debug?.(
-    `[${CHANNEL_ID}] AccountId: ${accountId}, inbound single_chat user_account=${chatId} uid=${payload.tuituiUid} user_name=${payload.tuituiUserName}`,
-  );
+    let storeAllowFrom: string[] = [];
+    try {
+      storeAllowFrom = parseAllowFroms(
+        await apiRuntime?.channel?.pairing?.readAllowFromStore?.({ channel: CHANNEL_ID, accountId })
+      );
+    } catch {}
 
-  if (!chatId && !payload.tuituiUid) {
-    log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, Missing user_account or uid in single_chat event`);
+    if(chatId && [...allowFrom, ...storeAllowFrom].includes(chatId)) {
+      return true; // isAllowed：单聊目标存在于白名单或配对存储中
+    }
+
+    if (dmPolicy === 'pairing') {
+      sendSingleChatPairingMsg(account, payload, log, apiRuntime);
+      log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, pairing required`);
+      return false;
+    }
+    // allowlist
+    log?.warn?.(`[${CHANNEL_ID}] AccountId: ${accountId}, Blocked unauthorized sender (allowlist): sender=${chatId} allowFrom=${JSON.stringify(allowFrom)}`);
     return false;
-  }
+  },
+  group_chat: async (payload: ChatPayload, msgData: any, account: InboundAccount, apiRuntime: any, log: any): Promise<boolean> => {
+    const { accountId, groupPolicy, groupAllowFrom } = account;
+    payload.chatType  = CHAT_TYPE_GROUP;
+    const chatId     = msgData.group_id ? String(msgData.group_id).toLowerCase().trim() : '';
+    payload.chatId   = chatId;
+    payload.groupName = msgData.group_name;
+    payload.msgId  = msgData.msgid;
+    log?.debug?.(
+      `[${CHANNEL_ID}] AccountId: ${accountId}, inbound group_chat:
+      tuituiAccount=${payload.tuituiAccount},
+      tuituiUid=${payload.tuituiUid},
+      tuituiUserName=${payload.tuituiUserName},
+      groupId=${chatId},
+      groupPolicy=${groupPolicy},
+      groupAllowFrom=${JSON.stringify(groupAllowFrom)},
+      at_me=${JSON.stringify(msgData.at_me)},
+      at=${JSON.stringify(msgData.at)}`);
+
+    if (groupPolicy === 'disabled') {
+      log?.info?.(`${CHANNEL_ID} AccountId: ${accountId}, groupPolicy disabled`);
+      return false;
+    }
 
-  const configuredAllowFrom = Array.isArray(account.allowFrom) ? account.allowFrom : [];
-  const normalizedAllowFrom = arrLowerCaseTrim(configuredAllowFrom);
-  log?.debug?.(
-    `[${CHANNEL_ID}] AccountId: ${accountId}, dmPolicy=${dmPolicy} userAccount=${chatId} tuituiUid=${payload.tuituiUid} chatId=${chatId} allowFrom=${JSON.stringify(normalizedAllowFrom)}`,
-  );
+    if (!payload.tuituiAccount || !chatId) {
+      log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, Missing tuituiAccount or chatId in group_chat event`);
+      return false;
+    }
 
-  if (dmPolicy === 'open') {
-    return true;
-  }
+    if (!msgData.at_me && account.requireMention) {
+      log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, ignore group message (not mentioned)`);
+      return false;
+    }
 
-  let storeAllowFrom: string[] = [];
-  try {
-    const res = await apiRuntime?.channel?.pairing?.readAllowFromStore?.({ channel: CHANNEL_ID, accountId });
-    if (Array.isArray(res)) storeAllowFrom = arrLowerCaseTrim(res);
-  } catch {}
+    if (!groupAllowFrom.includes(chatId)) {
+      if (needPairingThrottle(accountId, chatId)) {
+        log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, group pairing throttled for groupId=${chatId}`);
+        return false;
+      }
+      await sendTextMsg(
+        account,
+        chatId,
+        payload.chatType,
+        `当前openclaw（AccountId: ${accountId}）群聊策略为白名单，需要主人在群白名单(Group Allow From)增加当前群ID：\n${chatId}`,
+        'tuitui.groupPolicy.reply',
+      );
+      return false;
+    }
 
-  const allowSet  = new Set([...normalizedAllowFrom, ...storeAllowFrom]);
-  const isAllowed = chatId ? allowSet.has(chatId) : false;
-  if(isAllowed) return true;
+    payload.text = buildMessageBody(msgData);
 
-  if (dmPolicy === 'pairing') {
-    sendSingleChatPairingMsg(account, payload, log, apiRuntime);
-    log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, pairing required`);
-    return false;
-  } else { // allowlist
-    log?.warn?.(
-      `[${CHANNEL_ID}] AccountId: ${accountId}, Blocked unauthorized sender (allowlist): sender=${chatId} allowFrom=${JSON.stringify(normalizedAllowFrom)}`,
+    return true;
+  },
+  teams_post_create: async (payload: ChatPayload, msgData: any, account: InboundAccount, apiRuntime: any, log: any): Promise<boolean> => {
+    const { accountId, groupPolicy, groupAllowFrom } = account;
+    payload.chatType  = CHAT_TYPE_CHANNEL;
+    const { team_id, channel_id, parent_id, post_id, content } = msgData;
+    const thread_id   = (parent_id && parent_id != "0")?parent_id: post_id;
+    const chatId      = teamsBuildChatId(team_id, channel_id, thread_id);
+    payload.chatId    = chatId;
+    payload.msgId     = post_id;
+    payload.text      = content;
+    payload.replyToId = "";
+    log?.debug?.(
+      `[${CHANNEL_ID}] AccountId: ${accountId}, inbound teams:
+      tuituiAccount=${payload.tuituiAccount},
+      tuituiUid=${payload.tuituiUid},
+      tuituiUserName=${payload.tuituiUserName},
+      chatId=${chatId},
+      groupPolicy=${groupPolicy},
+      groupAllowFrom=${JSON.stringify(groupAllowFrom)},
+      at_me=${JSON.stringify(msgData.at_me)},
+      at=${JSON.stringify(msgData.at)}`,
     );
-    return false;
-  }
-}
 
-/**
- * 处理群聊（group_chat）分支
- * 返回消息合法
- */
-async function parseGroupChat(
-  payload:    ChatPayload,
-  msgData:    any,
-  account:    InboundHandlerOptions['account'],
-  apiRuntime: any,
-  log:        any,
-): Promise<boolean> {
-  const { accountId } = account;
-  payload.chatType  = CHAT_TYPE_GROUP;
-  const chatId     = msgData.group_id ? String(msgData.group_id).toLowerCase().trim() : '';
-  payload.chatId   = chatId;
-  payload.groupName = msgData.group_name;
-  payload.msgId  = msgData.msgid;
-  log?.debug?.(
-    `[${CHANNEL_ID}] AccountId: ${accountId}, inbound group_chat tuituiAccount=${payload.tuituiAccount} tuituiUid=${payload.tuituiUid} tuituiUserName=${payload.tuituiUserName} group_id=${payload.chatId}`,
-  );
-
-  const groupPolicy              = String(account.groupPolicy ?? 'allowlist').toLowerCase();
-  const groupAllowFromRaw        = Array.isArray(account.groupAllowFrom) ? account.groupAllowFrom : [];
-  const normalizedGroupAllowFrom = arrLowerCaseTrim(groupAllowFromRaw);
-  log?.debug?.(
-    `[${CHANNEL_ID}] AccountId: ${accountId}, groupPolicy=${groupPolicy} groupId=${chatId} groupAllowFrom=${JSON.stringify(normalizedGroupAllowFrom)} at_me=${JSON.stringify(msgData.at_me)} at=${JSON.stringify(msgData.at)}`,
-  );
-
-  if (groupPolicy === 'disabled') {
-    log?.info?.(`${CHANNEL_ID} AccountId: ${accountId}, groupPolicy disabled`);
-    return false;
-  }
-
-  if (!payload.tuituiAccount || !chatId) {
-    log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, Missing tuituiAccount or chatId in group_chat event`);
-    return false;
-  }
+    if (groupPolicy === 'disabled') {
+      log?.info?.(`${CHANNEL_ID} AccountId: ${accountId}, groupPolicy disabled`);
+      return false;
+    }
 
-  if (!msgData.at_me && account.requireMention) {
-    log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, ignore (not mentioned)`);
-    return false;
-  }
+    if (!payload.tuituiAccount) {
+      log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, Missing tuituiAccount or chatId in event`);
+      return false;
+    }
 
-  payload.text = buildMessageBody(msgData);
+    if (!msgData.at_me && account.requireMention) {
+      log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, ignore teams post (not mentioned)`);
+      return false;
+    }
 
-  if (!normalizedGroupAllowFrom.includes(String(chatId))) {
-    if (needPairingThrottle(accountId, chatId)) {
-      log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, group pairing throttled for groupId=${chatId}`);
+    if (!groupAllowFrom.includes(String(team_id))) {
+      if (needPairingThrottle(accountId, chatId)) {
+        log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, teams pairing throttled for teamsChatId=${chatId}`);
+        return false;
+      }
+      await sendTextMsg(
+        account,
+        chatId,
+        payload.chatType,
+        `当前openclaw（AccountId: ${accountId}）群聊/团队策略为白名单，需要主人在群白名单(Group Allow From)增加当前团队ID：\n${team_id}`,
+        'tuitui.groupPolicy.reply',
+      );
       return false;
     }
-    await sendTextMsg(
-      account,
-      chatId,
-      payload.chatType,
-      `当前openclaw（AccountId: ${accountId}）群聊策略为白名单，需要主人在群白名单(Group Allow From)增加当前群ID：\n${chatId}`,
-      'tuitui.groupPolicy.reply',
-    );
-    return false;
-  }
 
-  return true;
-}
+    return true;
+  },
+} as const;
 
-async function parseTeamsPost(
-  payload:    ChatPayload,
-  msgData:    any,
-  account:    InboundHandlerOptions['account'],
-  apiRuntime: any,
-  log:        any,
-): Promise<boolean> {
-  const { accountId } = account;
-  payload.chatType  = CHAT_TYPE_CHANNEL;
-  const { team_id, channel_id, parent_id, post_id, content } = msgData;
-  const thread_id   = (parent_id && parent_id != "0")?parent_id: post_id;
-  const chatId      = teamsBuildChatId(team_id, channel_id, thread_id);
-  payload.chatId    = chatId;
-  payload.msgId     = post_id;
-  payload.text      = content;
-  payload.replyToId = "";
-  log?.debug?.(
-    `[${CHANNEL_ID}] inbound teams tuituiAccount=${payload.tuituiAccount} tuituiUid=${payload.tuituiUid} tuituiUserName=${payload.tuituiUserName} chatId=${chatId}`,
-  );
-
-  // 暂时白名单先用这个，后面拆出来
-  const groupPolicy              = String(account.groupPolicy ?? 'allowlist').toLowerCase();
-  const groupAllowFromRaw        = Array.isArray(account.groupAllowFrom) ? account.groupAllowFrom : [];
-  const normalizedGroupAllowFrom = arrLowerCaseTrim(groupAllowFromRaw);
-  log?.debug?.(
-    `[${CHANNEL_ID}] AccountId: ${accountId} groupPolicy=${groupPolicy} groupId=${chatId} groupAllowFrom=${JSON.stringify(normalizedGroupAllowFrom)} at_me=${JSON.stringify(msgData.at_me)} at=${JSON.stringify(msgData.at)}`,
-  );
-
-  if (groupPolicy === 'disabled') {
-    log?.info?.(`${CHANNEL_ID} AccountId: ${accountId}, groupPolicy disabled`);
-    return false;
+/**
+ * 处理长链接消息
+ * account: 长连接初始化时，对应的Account配置信息
+ * accountId: 长连接启动初始化，对应的配置ID
+ */
+export async function handleInboundMessage({ json, account, apiRuntime, log }: InboundHandlerOptions) {
+  // Signature / AppId validation
+  const { accountId, appId, appSecret } = account;
+  if (appSecret && appId && json.header['X-Tuitui-Robot-Appid'] !== appId) {
+    log?.info?.(`[${CHANNEL_ID}] Invalid appId`);
+    return;
   }
 
-  if (!payload.tuituiAccount || !chatId) {
-    log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, Missing tuituiAccount or chatId in event`);
-    return false;
+  // Decode message
+  const msg = json.body as TuiTuiInboundMessage;
+  const msgData = msg.data;
+  const { ref } = msgData;
+  const payload: ChatPayload = {
+    chatType:     CHAT_TYPE_DIRECT,
+    chatId:       undefined, 
+    text:         undefined,
+    groupName:    undefined,
+    mediaUrls:    getMediaUrls(msgData),
+    replyToId:    ref?.is_me && ref?.msgid ? ref.msgid : undefined,
+    tuituiAccount: msg.user_account || "",
+    tuituiUid:     msg.uid || "",
+    tuituiUserName: msg.user_name || "",
+  };
+  const wsEvent = json.body.event;
+  // 按event类型，标准化并校验基础数据
+  const parseAndVerifyPayloadFun = parseAndVerifyPayload[wsEvent] as Function | undefined;
+  if (!parseAndVerifyPayloadFun) {
+    log?.info?.(`[${CHANNEL_ID}] ignore unknown event ${wsEvent}`);
+    return;
   }
+  if (!(await parseAndVerifyPayloadFun(payload, msgData, account, apiRuntime, log))) return;
 
-  if (!msgData.at_me && account.requireMention) {
-    log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, ignore (not mentioned)`);
-    return false;
+  if (!payload.chatId || !payload.msgId) {
+    log?.info?.(`[${CHANNEL_ID}] ignore unknown mseeage, missing chatId or msgId`, payload);
+    return;
   }
 
-  if (!normalizedGroupAllowFrom.includes(String(team_id))) {
-    if (needPairingThrottle(accountId, chatId)) {
-      log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, teams pairing throttled for teamsChatId=${chatId}`);
-      return false;
-    }
-    await sendTextMsg(
-      account,
-      chatId,
-      payload.chatType,
-      `当前openclaw（AccountId: ${accountId}）群聊/团队策略为白名单，需要主人在群白名单(Group Allow From)增加当前团队ID：\n${team_id}`,
-      'tuitui.groupPolicy.reply',
-    );
-    return false;
+  // 因为回复较慢，先回复一个表情
+  await tuituiEmojiReaction(account, payload.chatId, payload.chatType, payload.msgId, '收到');
+
+  // 路由判断
+  const routeSenderFrom = payload.tuituiAccount || payload.tuituiUid || 'unknown';
+
+  const cfg = await apiRuntime.config.loadConfig();
+  const sessionKey = getSessionKey(cfg, payload, account, apiRuntime);
+  log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, dispatching to agent session=${sessionKey}, chatType: ${payload.chatType}, chatId ${payload.chatId}, routeSenderFrom: ${routeSenderFrom}`);
+
+  const ctx: any = {
+    Body:               payload.text! || ' ',
+    From:               String(routeSenderFrom),
+    To:                 CHANNEL_ID,
+    SessionId:          sessionKey,
+    SessionKey:         sessionKey,
+    AccountId:          accountId,
+    OriginatingChannel: CHANNEL_ID,
+    OriginatingTo:      payload.chatId,
+    ChatType:           payload.chatType!,
+    Surface:            CHANNEL_ID,
+    Provider:           CHANNEL_ID,
+    SenderName:         payload.tuituiUserName,
+    MsgUname:           payload.tuituiAccount,
+    UserAccount:        payload.tuituiAccount,
+    CommandAuthorized:  true,  // 允许 /new 等内置命令
+  };
+  if (payload.chatType == CHAT_TYPE_GROUP && payload.chatId) {
+    ctx.GroupSubject = payload.groupName;
+    ctx.GroupId      = payload.chatId;
   }
+  if (payload.mediaUrls?.length)  ctx.MediaUrls  = payload.mediaUrls;
+  if (payload.replyToId)          ctx.ReplyToId  = payload.replyToId;
 
-  return true;
+  log?.info?.(`[${CHANNEL_ID}] AccountId: ${accountId}, handleInboundMessage dispatchReply payload:`, JSON.stringify(payload, null, '  '));
+  dispatchReply(ctx, cfg, account, payload, apiRuntime, log);
 }

package/src/outbound.ts

@@ -1,10 +1,7 @@
 import { readFileSync, existsSync, statSync } from 'node:fs';
 import { basename } from 'node:path';
 import { fetchWithSsrFGuard } from 'openclaw/plugin-sdk';
-
-import {
-  CHANNEL_ID,
-} from "./const";
+import { CHANNEL_ID } from "./const";
 
 import type { 
   TuiTuiMessageData,
@@ -23,7 +20,6 @@ import type {
 /* 一些常量配置 */
 export const TUITUI_SSRF_POLICY = { allowedHostnames: ['im.live.360.cn'] } as const;
 
-
 // ChatType定义与SessionKey定义一致，不可随意修改
 // https://docs.openclaw.ai/channels/channel-routing#session-key-shapes-examples
 export const CHAT_TYPE_DIRECT = 'direct' as const;
@@ -31,14 +27,10 @@ export const CHAT_TYPE_GROUP  = 'group'  as const;
 export const CHAT_TYPE_CHANNEL  = 'channel'  as const;
 export type ChatType = typeof CHAT_TYPE_DIRECT | typeof CHAT_TYPE_GROUP | typeof CHAT_TYPE_CHANNEL;
 
-export function guessChatType(chatId: string) {
-  if (chatId.startsWith("teams_")) {
-    return CHAT_TYPE_CHANNEL;
-  } else if (/^\d+$/.test(chatId)) {
-    return CHAT_TYPE_GROUP;
-  } else {
-    return CHAT_TYPE_DIRECT;
-  }
+export function guessChatType(chatId: string): ChatType {
+  if (chatId.startsWith("teams_")) return CHAT_TYPE_CHANNEL;
+  if (/^\d+$/.test(chatId)) return CHAT_TYPE_GROUP;
+  return CHAT_TYPE_DIRECT;
 }
 
 export function addParams2Url(urlStr: string, params: any) {
@@ -372,22 +364,14 @@ export function teamsParseChatId(chatId: string): TuiTuiTeamsTarget {
   return { team_id, channel_id, parent_id} as TuiTuiTeamsTarget;
 }
 
-function getTargets(chatId: string, chatType: ChatType): any {
-  if (chatType == CHAT_TYPE_DIRECT) {
-    const tousers: string[] = [];
-    tousers.push(chatId);
-    return { tousers };
-  } else if (chatType == CHAT_TYPE_GROUP) {
-    const togroups: string[] = [];
-    togroups.push(chatId);
-    return { togroups };
-  } else if (chatType == CHAT_TYPE_CHANNEL) {
-    const toteams: TuiTuiTeamsTarget[] = [];
-    toteams.push(teamsParseChatId(chatId));
-    return { toteams };
-  } else {
-    return {};
-  }
+interface TuiTuiToTargets { tousers?: string[], togroups?: string[], toteams?: TuiTuiTeamsTarget[] }
+
+function getTargets(chatId: string, chatType: ChatType): TuiTuiToTargets {
+  const ret = {} as TuiTuiToTargets;
+  if (chatType == CHAT_TYPE_DIRECT) ret.tousers = [chatId] as string[];
+  if (chatType == CHAT_TYPE_GROUP) ret.togroups = [chatId] as string[];
+  if (chatType == CHAT_TYPE_CHANNEL) ret.toteams = [teamsParseChatId(chatId)] as TuiTuiTeamsTarget[];
+  return ret;
 }
 
 function replaceSingleNewlines(content: string): string {
@@ -404,48 +388,31 @@ function replaceSingleNewlines(content: string): string {
 输入：你好 @张三 @李四 你吃了吗
 输出数组：["张三"，"李四"]
 */
-
-function getMentionsRegex(): RegExp {
-  // 正则表达式解释：
-  // (?<=^|[\s\r\n\u3000\u3001\u3002\uFF0C\uFF01\uFF1F\u2026])  
-  // - 正向向后查找，确保@前面是：
-  //   ^              - 字符串开头
-  //   [\s\r\n]       - 空格、回车、换行
-  //   \u3000         - 中文全角空格
-  //   \u3001         - 中文顿号（、）
-  //   \u3002         - 中文句号（。）
-  //   \uFF0C         - 中文逗号（，）
-  //   \uFF01         - 中文感叹号（！）
-  //   \uFF1F         - 中文问号（？）
-  //   \u2026         - 中文省略号（…）
-  // @                - 匹配@符号
-  // ([^\s]+)         - 捕获组，匹配一个或多个非空白字符
-  const regex = /(?<=^|[\s\r\n\u3000\u3001\u3002\uFF0C\uFF01\uFF1F\u2026])@([^\s]+)/g;
-  return regex
-}
-
+// 正则表达式解释：
+// (?<=^|[\s\r\n\u3000\u3001\u3002\uFF0C\uFF01\uFF1F\u2026])  
+// - 正向向后查找，确保@前面是：
+//   ^              - 字符串开头
+//   [\s\r\n]       - 空格、回车、换行
+//   \u3000         - 中文全角空格
+//   \u3001         - 中文顿号（、）
+//   \u3002         - 中文句号（。）
+//   \uFF0C         - 中文逗号（，）
+//   \uFF01         - 中文感叹号（！）
+//   \uFF1F         - 中文问号（？）
+//   \u2026         - 中文省略号（…）
+// @                - 匹配@符号
+// ([^\s]+)         - 捕获组，匹配一个或多个非空白字符
+const mentionsRegex = /(?<=^|[\s\r\n\u3000\u3001\u3002\uFF0C\uFF01\uFF1F\u2026])@([^\s]+)/g;
 function extractMentions(text: string): string[] {
-  const mentions: string[] = [];
-  
-  const regex = getMentionsRegex();  
-  let match;
-  while ((match = regex.exec(text)) !== null) {
-    const mention = match[1];
-    if (!mentions.includes(mention)) {
-      mentions.push(mention);
-    }
-  }
-  
-  return mentions;
+  const mentionsSet = new Set<string>();
+  const arr = text.match(mentionsRegex);
+  if (arr) arr.forEach((str) => mentionsSet.add(str.substring(1)));
+  return Array.from(mentionsSet);
 }
-
 function replaceMentions(text: string): string {
-  const regex = getMentionsRegex();  
-  return text.replace(regex, (match, mention) => {
-    // match: 完整的匹配字符串（例如 "@username"）
-    // mention: 捕获组中的内容（例如 "username"）
-    return `{{tuitui_at "${mention}"}}`;
-  });
+  // match: 完整的匹配字符串（例如 "@username"）
+  // mention: 捕获组中的内容（例如 "username"）
+  return text.replace(mentionsRegex, (match, mention) => `{{tuitui_at "${mention}"}}`);
 }
 
 export async function sendTextMsg(
@@ -565,3 +532,145 @@ export async function sendMediaMsg(
     await postTuituiMsg(account, msg, auditCtx);
   }
 }
+
+
+export interface TuiTuiChatRecordMessage {
+  msgid: string;
+  cid: string;
+  uid: string;
+  user_account: string;
+  user_name: string;
+  timestamp: string;
+  data: TuiTuiMessageData;
+}
+
+export interface TuiTuiChatRecordResponse {
+  errcode: number;
+  errmsg: string;
+  cursor: string;
+  has_more: boolean;
+  time: string;
+  msgs: TuiTuiChatRecordMessage[];
+}
+
+
+export interface TuiTuiMessageDataClean extends TuiTuiMessageData{
+  // 对模型不需要理解的字段不进大模型上下文，避免注意力涣散
+  user_account: string;
+  user_name: string;
+  msg_time: string;
+}
+
+export interface TuiTuiChatRecordResponseClean {
+  errcode: number;
+  errmsg: string;
+  cursor: string;
+  has_more: boolean;
+  current_time: string; // 辅助大模型理解当前时间
+  msgs: TuiTuiMessageDataClean[];
+}
+
+export interface GetChatRecordOptions {
+  startTime?: string;   // 格式：%Y-%m-%dT%H:%M:%S+08:00，示例：2026-03-17T15:13:48+08:00
+  endTime?: string;     // 格式同 startTime
+  relativeTime?: string; // 相对时间范围：today / yesterday / day_before_yesterday / this_week / last_week / this_month / last_month / last_{N}_{unit}（unit: minutes/hours/days）。与 startTime/endTime 互斥，指定后 startTime/endTime 将被忽略
+  limit?: number;       // 1~100，默认100
+  cursor?: string;      // 游标，第一次填 "0"
+  orderAsc?: boolean;   // 是否正序，默认 false（逆序）
+}
+
+/**
+ * 拉取群聊消息记录（分页）。
+ * 目前仅支持 group 类型（CHAT_TYPE_GROUP）。
+ *
+ * @param account   - TuiTui 账号，含 appId / appSecret
+ * @param chatId    - 群 ID
+ * @param chatType  - 会话类型，当前仅支持 CHAT_TYPE_GROUP
+ * @param options   - 可选参数：时间范围、分页游标、每页条数、是否正序
+ * @returns         - 接口原始响应，包含 messages 列表与下一页 cursor；chatType 不支持时返回 undefined
+ */
+export async function getChatRecord(
+  account: any,
+  chatId: string | undefined,
+  chatType: ChatType,
+  options: GetChatRecordOptions = {},
+): Promise<TuiTuiChatRecordResponseClean | undefined> {
+  if (!chatId) {
+    console.log(`[${CHANNEL_ID}] getChatRecord: Missing "chatId"`);
+    return undefined;
+  }
+
+  checkAccount(account, 'getChatRecord');
+
+  let baseurl = "";
+  if (chatType == CHAT_TYPE_DIRECT) {
+    baseurl = "https://im.live.360.cn:8282/robot/message/single/sync";
+  } else if (chatType == CHAT_TYPE_GROUP){
+    baseurl = "https://im.live.360.cn:8282/robot/message/group/sync";
+  } else {
+    console.log(`[${CHANNEL_ID}] getChatRecord: chatType "${chatType}" is not supported`);
+    return undefined;
+  }
+
+  const body: Record<string, any> = {
+    cursor : "0",
+  };
+  if (chatType == CHAT_TYPE_DIRECT) body.user = chatId;
+  if (chatType == CHAT_TYPE_GROUP) body.group_id = chatId;
+  if (options.relativeTime) {
+    body.relative_time = options.relativeTime;
+  } else {
+    if (options.startTime) body.start_time = options.startTime;
+    if (options.endTime)   body.end_time   = options.endTime;
+  }
+  if (options.cursor) body.cursor = options.cursor;
+  if (options.limit) body.limit = options.limit;
+  if (typeof options.orderAsc === 'boolean') body.order_asc = options.orderAsc;
+
+  const { appId: appid, appSecret: secret } = account;
+
+  const url = addParams2Url(baseurl, { appid, secret });
+
+  console.log(`[${CHANNEL_ID}] getChatRecord request `, body);
+
+  const { response, release } = await _fetchJson(url, body, 'tuitui.chat.record');
+  try {
+    const bodyText = await response.text();
+    //console.log(`[${CHANNEL_ID}] getChatRecord response ${bodyText}`);
+
+    if (!response.ok) {
+      throw new Error(`getChatRecord failed (response.ok unexpected): ${response.status} ${response.statusText}; body=${bodyText}`);
+    }
+
+    const parsed: TuiTuiChatRecordResponse = JSON.parse(bodyText);
+    if (Number(parsed?.errcode) !== 0) {
+      throw new Error(`getChatRecord failed (errcode unexpected): errcode=${parsed.errcode} errmsg=${parsed.errmsg ?? 'Unknown error'}`);
+    }
+
+    const clean: TuiTuiChatRecordResponseClean = {
+      errcode:  parsed.errcode,
+      errmsg:   parsed.errmsg,
+      cursor:   parsed.cursor,
+      has_more: parsed.has_more,
+      current_time: parsed.time,
+      msgs: (parsed.msgs ?? []).map(({ user_account, user_name, timestamp, data }) => {
+        const { at, msgid, group_id, group_name, ...restData } = data;  // 排除一些字段，减少大模型上下文大小
+        return {
+          ...restData,  // 使用排除 at 后的数据
+          user_account,
+          user_name,
+          msg_time: new Date(Number(timestamp) * 1000).toLocaleString('sv-SE', { hour12: false }).replace('T', ' '),
+        };
+      }),
+    };
+
+    console.log(`[${CHANNEL_ID}] getChatRecord result(cleaned)`, JSON.stringify(clean, null, 2));
+
+    return clean;
+  } catch (err) {
+    console.error(`[${CHANNEL_ID}] getChatRecord error:`, err);
+    return undefined;
+  } finally {
+    await release();
+  }
+}

package/src/tools.ts

@@ -0,0 +1,88 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import type { OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+import {  DEFAULT_ACCOUNT_ID} from 'openclaw/plugin-sdk';
+import { CHANNEL_ID} from "./const";
+import { resolveAccount } from "./accounts"
+import { Type, type Static } from "@sinclair/typebox";
+
+import {CHAT_TYPE_DIRECT,CHAT_TYPE_GROUP,CHAT_TYPE_CHANNEL,ChatType, getChatRecord} from "./outbound"
+  
+
+
+export const tuitui_im_get_messages_schema = Type.Object(
+  {
+    chatId: Type.String({ description: "聊天ID，单聊指tuitui用户的account，群聊是群ID" }),
+    chatType: Type.String({ description: `聊天类型。 单聊:${CHAT_TYPE_DIRECT}   群聊:${CHAT_TYPE_GROUP}`}),
+    relativeTime: Type.Optional(Type.String({ description: `相对时间范围：today / yesterday / day_before_yesterday / this_week / last_week / this_month / last_month / last_{N}_{unit}（unit: minutes/hours/days）。与 startTime/endTime 互斥`})),
+    startTime: Type.Optional(Type.String({ description: `起始时间（ISO 8601 格式，如 2026-02-27T00:00:00+08:00），非必填，默认指2000年代表。与 relativeTime 互斥`})),
+    endTime: Type.Optional(Type.String({ description: `结束时间（ISO 8601 格式，如 2026-02-27T00:00:00+08:00），非必填，默认当前时间。与 relativeTime 互斥`})),
+    limit: Type.Optional(Type.Number({ description: `每页条数，1~100，默认 100`})),
+    cursor: Type.Optional(Type.String({ description: `游标首次调用填 "0"，返回结果中has_more为true时代表可以获取下一页，如果你需要下一页，可以传返回结果的cursor代表继续拉取下一页`})),
+    orderAsc: Type.Optional(Type.Boolean({ description: `返回数据是否按时间正序排序，默认 false（按时间逆序，即从最新的开始拉取）`})),
+  },
+  { additionalProperties: false },
+);
+
+function tool_errmsg(str:string) {
+  const ret = `tuitui_im_get_messages() error: ${str}`
+  console.log(ret);
+  return ret;
+}
+
+async function tuitui_im_get_messages(config: any, agentAccountId:string, params:any) {
+  const account = resolveAccount(config, agentAccountId);
+  if(!account || !account.enabled || !account.appId || !account.appSecret) {
+    return tool_errmsg(`invalid tuitui account ${agentAccountId}`);
+  }
+
+  const chatType = params?.chatType || "";
+  const chatId = params?.chatId || "";
+  if(!chatId || !chatType) {
+    return tool_errmsg(`chatType or chatId empty`);
+  }
+
+  if(chatType == CHAT_TYPE_DIRECT || chatType == CHAT_TYPE_GROUP) {
+    return await getChatRecord(account, chatId, chatType, {
+      startTime: params?.startTime,
+      endTime:   params?.endTime,
+      relativeTime: params?.relativeTime,
+      limit:     params?.limit,
+      cursor:    params?.cursor,
+      orderAsc:  params?.orderAsc,
+    });
+  } else {
+    return tool_errmsg(`unknown chatType: ${chatType}`);
+  }  
+}
+
+const tuituiToolFactory = (ctx: OpenClawPluginToolContext) => {
+  const agentAccountId  = ctx.agentAccountId;
+  const messageChannel   = ctx.messageChannel;
+  const sessionKey = ctx.sessionKey;
+  const config = ctx.config;
+
+  return {
+    name: "tuitui_im_get_messages",
+    label: "tuitui IM",
+    description: "推推(tuitui) 聊天记录获取，可查询群聊和私聊的聊天记录。\n\n",
+    parameters: tuitui_im_get_messages_schema,
+    execute: async (_toolCallId, params) => {
+      if(messageChannel != CHANNEL_ID) {
+        console.log(`tuitui_im_get_messages(): bad channel ${messageChannel}`);
+        return
+      }
+      console.log(`tuitui_im_get_messages(): agentAccountId: ${agentAccountId}, sessionKey: ${sessionKey}`, params);
+      return await tuitui_im_get_messages(config, agentAccountId, params);
+    },
+  };
+};
+
+export function registerTuituiTools(api: OpenClawPluginApi) {
+  if (!api.config) {
+    api.logger.debug?.("tuitui: Registered tool: No config available");
+    return;
+  }
+  
+  api.registerTool(tuituiToolFactory);
+  api.logger.info?.(`tuitui: Registered tool`);
+}

package/src/types.ts

@@ -13,7 +13,7 @@ export interface TuiTuiInboundMessage {
 }
 
 export interface TuiTuiMessageData {
-  msgid: string;
+  msgid?: string;
   msg_type: 'text' | 'image' | 'mixed' | 'voice' | 'file';
   text?: string;
   images?: string[];
@@ -46,16 +46,16 @@ export interface TuiTuiMessageData {
 }
 
 export interface TuiTuiOutboundTextMessage {
-  tousers: string[];
-  togroups: string[];
+  tousers?: string[];
+  togroups?: string[];
   at: string[];
   msgtype: string;
   text: { content: string; reference_msgid?: string };
 }
 
 export interface TuiTuiOutboundTeamsMarkdownMessage {
-  toteams: TuiTuiTeamsTarget[];
-  at: string[];
+  toteams?: TuiTuiTeamsTarget[];
+  at?: string[];
   msgtype: string;
   richtext: { markdown: string; delims_left: string; delims_right: string};
 }

package/src/utils.ts

@@ -0,0 +1,5 @@
+/* 格式化allowFrom配置项，确保其为小写字符串数组 */
+export const parseAllowFroms = (allowFrom: any) : string[] => {
+  const arr = Array.isArray(allowFrom) ? allowFrom : [];
+  return arr.filter((v: any) => !!v).map((v: any) => String(v).toLowerCase().trim());
+}