@openclaw-channel/socket-chat 1.0.0 → 1.0.1

package/README.md

@@ -65,7 +65,6 @@ channels:
 | `mqttConfigTtlSec` | `300` | MQTT 配置缓存时间（秒） |
 | `maxReconnectAttempts` | `10` | MQTT 断线最大重连次数 |
 | `reconnectBaseDelayMs` | `2000` | 重连基础延迟（毫秒，指数退避） |
-| `useTls` | `false` | 是否使用 `mqtts://`（TLS） |
 
 ---
 
@@ -81,7 +80,32 @@ openclaw channels add socket-chat --token <apiKey>
 
 ### 收到的 MQTT 消息（reciveTopic）
 
-文字消息：
+所有消息类型共有的字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `content` | string | 消息内容（文字消息为原文，媒体消息为格式化描述） |
+| `robotId` | string | 机器人微信 ID |
+| `senderId` | string | 发消息人微信 ID（wxid） |
+| `senderName` | string | 发消息人昵称 |
+| `isGroup` | boolean | 是否为群消息 |
+| `groupId` | string \| undefined | 群 ID（仅群消息） |
+| `groupName` | string \| undefined | 群名称（仅群消息） |
+| `isGroupMention` | boolean | 是否在群中 @了机器人 |
+| `timestamp` | number | 消息时间戳（13 位毫秒） |
+| `messageId` | string | 消息 ID |
+| `type` | string | 消息类型，见下方枚举 |
+| `conversionId` | string | 会话 ID（私聊为 senderId，群聊为 groupId） |
+| `conversionName` | string | 会话名称（私聊为昵称，群聊为群名） |
+| `chatAlias` | string \| undefined | 发消息人在机器人通讯录中的备注 |
+| `chatUserWeixin` | string | 发消息人的微信号（weixin 字段，可能为空） |
+| `isMyself` | boolean | 是否为机器人自己发的消息 |
+| `url` | string \| undefined | 媒体资源链接（OSS URL 或 base64，仅媒体消息携带） |
+| `mediaInfo` | object \| undefined | 结构化媒体信息（名片、视频号、h5 链接携带） |
+
+`type` 枚举值：`文字`、`图片`、`视频`、`文件`、`语音`、`名片`、`h5链接`、`视频号`、`位置`、`历史记录`。
+
+文字消息示例：
 
 ```json
 {
@@ -90,11 +114,38 @@ openclaw channels add socket-chat --token <apiKey>
   "senderId": "wxid_user123",
   "senderName": "用户昵称",
   "isGroup": false,
+  "isGroupMention": false,
+  "timestamp": 1234567890123,
+  "messageId": "uuid-xxx",
+  "type": "文字",
+  "conversionId": "wxid_user123",
+  "conversionName": "用户昵称",
+  "chatAlias": "同事小明",
+  "chatUserWeixin": "",
+  "isMyself": false
+}
+```
+
+群消息（@提及）示例：
+
+```json
+{
+  "content": "消息内容",
+  "robotId": "wxid_robot",
+  "senderId": "wxid_user123",
+  "senderName": "用户昵称",
+  "isGroup": true,
   "groupId": "roomid_xxx",
-  "groupName": "群组名称",
+  "groupName": "工作群",
+  "isGroupMention": true,
   "timestamp": 1234567890123,
   "messageId": "uuid-xxx",
-  "type": "文字"
+  "type": "文字",
+  "conversionId": "roomid_xxx",
+  "conversionName": "工作群",
+  "chatAlias": "",
+  "chatUserWeixin": "",
+  "isMyself": false
 }
 ```
 
@@ -107,15 +158,66 @@ openclaw channels add socket-chat --token <apiKey>
   "senderId": "wxid_user123",
   "senderName": "用户昵称",
   "isGroup": false,
+  "isGroupMention": false,
   "timestamp": 1234567890123,
   "messageId": "uuid-xxx",
   "type": "图片",
+  "conversionId": "wxid_user123",
+  "conversionName": "用户昵称",
+  "chatAlias": "",
+  "chatUserWeixin": "",
+  "isMyself": false,
   "url": "https://oss.example.com/img.jpg"
 }
 ```
 
-> **说明**：`type` 枚举值包括 `文字`、`图片`、`视频`、`文件`、`语音`、`名片`、`h5链接`、`视频号`、`位置`、`历史记录`。
->
+名片消息（携带 `mediaInfo`）：
+
+```json
+{
+  "content": "【名片消息】\n联系人昵称：张三\n联系人ID：wxid_zhangsan",
+  "type": "名片",
+  "mediaInfo": {
+    "name": "张三",
+    "avatar": "https://...",
+    "wxid": "wxid_zhangsan"
+  }
+}
+```
+
+视频号消息（携带 `mediaInfo`）：
+
+```json
+{
+  "content": "【视频号消息】\n视频号昵称：xxx\n视频号简介：...\n视频号链接：https://...",
+  "type": "视频号",
+  "mediaInfo": {
+    "nickname": "xxx",
+    "coverUrl": "https://...",
+    "avatar": "https://...",
+    "desc": "视频号简介",
+    "url": "https://...",
+    "objectId": "...",
+    "objectNonceId": "..."
+  }
+}
+```
+
+h5 链接消息（携带 `mediaInfo`）：
+
+```json
+{
+  "content": "【链接消息】\n链接标题：xxx\n链接描述：...\n链接地址：https://...",
+  "type": "h5链接",
+  "mediaInfo": {
+    "url": "https://...",
+    "description": "链接描述",
+    "imageUrl": "https://thumbnail...",
+    "title": "链接标题"
+  }
+}
+```
+
 > 图片/视频等媒体消息会同时携带 `content`（格式化描述文字）和 `url`（资源链接）。若平台未配置 OSS，`url` 为 base64 字符串，插件会忽略 base64 内容，仅将 `content` 描述文字传给 AI agent。
 
 #### 媒体消息处理逻辑
@@ -127,6 +229,8 @@ openclaw channels add socket-chat --token <apiKey>
 | 图片（无 OSS，base64） | 包含 base64 的描述 | `data:image/...` | 仅描述文字（base64 被过滤） |
 | 仅有 URL、无 content | — | HTTP URL | `<media:图片>` placeholder |
 
+---
+
 ### 发送的 MQTT 消息（sendTopic）
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw-channel/socket-chat",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "OpenClaw Socket Chat channel plugin — MQTT-based IM bridge",
   "type": "module",
   "publishConfig": {

package/src/channel.ts

@@ -88,7 +88,6 @@ export const socketChatPlugin: ChannelPlugin<ResolvedSocketChatAccount> = {
         mqttConfigTtlSec: { type: "number" },
         maxReconnectAttempts: { type: "number" },
         reconnectBaseDelayMs: { type: "number" },
-        useTls: { type: "boolean" },
         accounts: {
           type: "object",
           additionalProperties: {
@@ -105,7 +104,6 @@ export const socketChatPlugin: ChannelPlugin<ResolvedSocketChatAccount> = {
               mqttConfigTtlSec: { type: "number" },
               maxReconnectAttempts: { type: "number" },
               reconnectBaseDelayMs: { type: "number" },
-              useTls: { type: "boolean" },
             },
           },
         },
@@ -117,7 +115,6 @@ export const socketChatPlugin: ChannelPlugin<ResolvedSocketChatAccount> = {
       dmPolicy: { label: "私信策略", help: "pairing=需配对, open=任意人, allowlist=白名单" },
       allowFrom: { label: "允许来源", help: "允许触发 AI 的发送者 ID 列表" },
       requireMention: { label: "群消息需@提及", help: "群组消息是否必须@提及机器人才触发" },
-      useTls: { label: "使用 TLS（mqtts://）", advanced: true },
       mqttConfigTtlSec: { label: "MQTT 配置缓存时间（秒）", advanced: true },
       maxReconnectAttempts: { label: "最大重连次数", advanced: true },
       reconnectBaseDelayMs: { label: "重连基础延迟（毫秒）", advanced: true },
@@ -305,7 +302,7 @@ export const socketChatPlugin: ChannelPlugin<ResolvedSocketChatAccount> = {
         // 补充 probe 信息到 snapshot
         probe,
         ...(probe && typeof probe === "object" && "host" in probe
-          ? { baseUrl: `mqtt://${(probe as { host?: string }).host}:${(probe as { port?: string }).port}` }
+          ? { baseUrl: `${(probe as { host?: string }).host}:${(probe as { port?: string }).port}` }
           : {}),
         lastInboundAt: runtime?.lastInboundAt ?? null,
         lastOutboundAt: runtime?.lastOutboundAt ?? null,

package/src/config-schema.test.ts

@@ -15,7 +15,6 @@ describe("SocketChatAccountConfigSchema", () => {
       mqttConfigTtlSec: 600,
       maxReconnectAttempts: 5,
       reconnectBaseDelayMs: 1000,
-      useTls: false,
     });
 
     expect(parsed.apiKey).toBe("key123");

package/src/config-schema.ts

@@ -44,8 +44,6 @@ export const SocketChatAccountConfigSchema = z.object({
   maxReconnectAttempts: z.number().optional(),
   /** MQTT 重连基础延迟（毫秒），默认 2000，指数退避 */
   reconnectBaseDelayMs: z.number().optional(),
-  /** MQTT over TLS，默认 false */
-  useTls: z.boolean().optional(),
 });
 
 export type SocketChatAccountConfig = z.infer<typeof SocketChatAccountConfigSchema>;

package/src/inbound.test.ts

@@ -321,6 +321,66 @@ describe("handleInboundMessage — dmPolicy=allowlist", () => {
 // ---------------------------------------------------------------------------
 
 describe("handleInboundMessage — group messages", () => {
+  it("dispatches AI reply for group message with isGroupMention=true (no @text needed)", async () => {
+    const runtime = makeMockRuntime();
+
+    const ctx = makeCtx(runtime, {
+      channels: {
+        "socket-chat": {
+          apiKey: "k",
+          apiBaseUrl: "https://x.com",
+          requireMention: true,
+        },
+      },
+    });
+
+    await handleInboundMessage({
+      msg: makeMsg({
+        isGroup: true,
+        groupId: "roomid_group1",
+        robotId: "robot_abc",
+        isGroupMention: true,
+        content: "hello group (no @text in content)",
+      }),
+      accountId: "default",
+      ctx: ctx as never,
+      log: ctx.log,
+      sendReply: vi.fn(async () => {}),
+    });
+
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+  });
+
+  it("skips group message when isGroupMention=false and no @text", async () => {
+    const runtime = makeMockRuntime();
+
+    const ctx = makeCtx(runtime, {
+      channels: {
+        "socket-chat": {
+          apiKey: "k",
+          apiBaseUrl: "https://x.com",
+          requireMention: true,
+        },
+      },
+    });
+
+    await handleInboundMessage({
+      msg: makeMsg({
+        isGroup: true,
+        groupId: "roomid_group1",
+        robotId: "robot_abc",
+        isGroupMention: false,
+        content: "just chatting",
+      }),
+      accountId: "default",
+      ctx: ctx as never,
+      log: ctx.log,
+      sendReply: vi.fn(async () => {}),
+    });
+
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+  });
+
   it("dispatches AI reply for group message mentioning robotId", async () => {
     const runtime = makeMockRuntime();
 

package/src/inbound.ts

@@ -136,10 +136,11 @@ function checkGroupMention(params: {
   const requireMention = account.config.requireMention !== false; // 默认 true
   if (!requireMention) return true;
 
-  // 检测消息中是否包含 robotId（简单 @提及）
+  // 优先使用平台传来的精确判断（on-claw-message.js 已计算好 isMention）
+  // fallback：检查消息内容中是否包含 @robotId（不做宽泛的 content.includes(robotId) 以避免误判）
   const mentioned =
-    msg.content.includes(`@${robotId}`) ||
-    msg.content.includes(robotId);
+    msg.isGroupMention === true ||
+    msg.content.includes(`@${robotId}`);
 
   if (!mentioned) {
     log.debug?.(

package/src/mqtt-client.ts

@@ -46,9 +46,8 @@ export function clearActiveMqttSession(accountId: string): void {
 // 工具函数
 // ---------------------------------------------------------------------------
 
-function buildMqttUrl(mqttConfig: SocketChatMqttConfig, useTls: boolean): string {
-  const protocol = useTls ? "mqtts" : "mqtt";
-  return `${protocol}://${mqttConfig.host}:${mqttConfig.port}`;
+function buildMqttUrl(mqttConfig: SocketChatMqttConfig): string {
+  return `${mqttConfig.host}:${mqttConfig.port}`;
 }
 
 function parseInboundMessage(raw: Buffer | string): SocketChatInboundMessage | null {
@@ -117,7 +116,6 @@ export async function monitorSocketChatProviderWithRegistry(params: {
   const { abortSignal } = ctx;
   const maxReconnects = account.config.maxReconnectAttempts ?? MAX_RECONNECT_ATTEMPTS_DEFAULT;
   const reconnectBaseMs = account.config.reconnectBaseDelayMs ?? RECONNECT_BASE_DELAY_MS_DEFAULT;
-  const useTls = account.config.useTls ?? false;
   const mqttConfigTtlMs = (account.config.mqttConfigTtlSec ?? 300) * 1000;
 
   let reconnectAttempts = 0;
@@ -155,7 +153,7 @@ export async function monitorSocketChatProviderWithRegistry(params: {
       }
 
       // 2. 建立 MQTT 连接
-      const mqttUrl = buildMqttUrl(mqttConfig, useTls);
+      const mqttUrl = buildMqttUrl(mqttConfig);
       log.info(`[${accountId}] connecting to ${mqttUrl} (clientId=${mqttConfig.clientId})`);
 
       const client = mqtt.connect(mqttUrl, {

package/src/types.ts

@@ -18,6 +18,8 @@ export type SocketChatInboundMessage = {
   groupId?: string;
   /** 群名称（isGroup=true 时存在） */
   groupName?: string;
+  /** 是否在群中 @了机器人（由平台精确计算，优先于文本匹配） */
+  isGroupMention?: boolean;
   /** 11 位时间戳（毫秒） */
   timestamp: number;
   /** 消息唯一 ID */

package/DEVNOTES.md

@@ -1,219 +0,0 @@
-# socket-chat 开发经验与注意事项
-
-## 1. openclaw plugin-sdk API 签名
-
-### status-helpers
-
-这三个函数的签名容易踩坑，必须对照源码：
-
-```ts
-// ✅ 正确
-buildBaseChannelStatusSummary(snapshot)
-// ❌ 错误（没有 options 参数）
-buildBaseChannelStatusSummary({ snapshot, includeMode: false })
-
-// ✅ 正确：configured 必须挂在 account 上，不能作为顶层参数
-const accountWithConfigured = { ...account, configured };
-buildBaseAccountStatusSnapshot({ account: accountWithConfigured, runtime, probe })
-
-// ✅ 正确：channel 在前，accounts 数组在后
-collectStatusIssuesFromLastError("socket-chat", [snap])
-// ❌ 错误（参数顺序反了）
-collectStatusIssuesFromLastError(snap, "socket-chat")
-```
-
-### ChannelOutboundAdapter
-
-feishu / matrix 把 outbound 提取到独立的 `outbound.ts` 文件并导出类型化对象，不要在 `ChannelPlugin` 里内联写匿名对象：
-
-```ts
-// outbound.ts
-export const socketChatOutbound: ChannelOutboundAdapter = { ... };
-
-// channel.ts
-import { socketChatOutbound } from "./outbound.js";
-export const socketChatPlugin: ChannelPlugin = {
-  outbound: socketChatOutbound,  // 一行引用
-};
-```
-
-`ChannelPlugin` 没有 `inspectAccount` 字段，不要添加。
-
----
-
-## 2. Zod v4 的 z.record() 行为变化
-
-Zod v4 中 `z.record(Schema)` 把 Schema 当作 **key** 的校验，而不是 value：
-
-```ts
-// ❌ Zod v4 中 key 校验会失败
-z.record(SocketChatAccountConfigSchema)
-
-// ✅ 必须显式传两个参数
-z.record(z.string(), SocketChatAccountConfigSchema)
-```
-
----
-
-## 3. aedes MQTT broker 的 CJS 兼容
-
-aedes 是 CJS 模块，ESM 项目中具名导入会报找不到：
-
-```ts
-// ❌ 报错：createBroker is not exported
-import { createBroker } from "aedes";
-
-// ✅ 用默认导入，再调用方法
-import aedesModule from "aedes";
-const broker = aedesModule.createBroker();
-```
-
-`@types/aedes` 包不存在，aedes 自带类型定义，直接用即可。
-
----
-
-## 4. plugin 安装顺序
-
-openclaw 启动时会校验 `channels.*` 中的 channel id 是否已注册。**必须先装插件，再写 channel 配置**，否则会报 `unknown channel id` 并阻塞所有 CLI 命令：
-
-```
-# 正确顺序
-1. 创建 openclaw.plugin.json（id、channels、configSchema）
-2. openclaw plugins install --link <path>
-3. 重启 gateway
-4. 再往 openclaw.json 写 channels.socket-chat 配置
-```
-
-`openclaw.plugin.json` 是 `plugins install` 的必要条件，缺少会报找不到 manifest。
-
----
-
-## 5. default 账号的配置结构
-
-socket-chat 的 `default` 账号直接读取 `channels.socket-chat` 顶层字段，**不是** `channels.socket-chat.accounts.default`：
-
-```jsonc
-// ✅ 正确：apiKey/apiBaseUrl 放顶层
-"channels": {
-  "socket-chat": {
-    "apiKey": "mytest-key-001",
-    "apiBaseUrl": "http://localhost:3000",
-    "dmPolicy": "open",
-    "allowFrom": ["*"]
-  }
-}
-
-// ❌ 错误：放在 accounts.default 下 default 账号读不到
-"channels": {
-  "socket-chat": {
-    "accounts": {
-      "default": { "apiKey": "..." }
-    }
-  }
-}
-```
-
----
-
-## 6. vitest 中避免拉取完整 plugin-sdk
-
-`openclaw/plugin-sdk` 依赖链包含 `json5` 等在测试环境下无法加载的模块。在 `vitest.config.ts` 中用 alias 指向轻量 stub：
-
-```ts
-// vitest.config.ts
-resolve: {
-  alias: [
-    {
-      find: "openclaw/plugin-sdk",
-      replacement: path.join(dir, "src", "__sdk-stub__.ts"),
-    },
-  ],
-},
-```
-
-stub 只重新导出测试实际用到的内容：
-
-```ts
-// __sdk-stub__.ts
-export { resolveAllowlistMatchByCandidates } from "../../openclaw/src/channels/allowlist-match.js";
-export type { ChannelGatewayContext } from "../../openclaw/src/plugin-sdk/index.js";
-```
-
----
-
-## 7. 集成测试的隔离策略
-
-集成测试用独立端口（`HTTP_PORT=13100`、`MQTT_PORT=11883`）启动 socket-server 子进程，与本地开发端口（3000/1883）完全隔离：
-
-```ts
-serverProcess = spawn("npx", ["tsx", serverEntry], {
-  env: { ...process.env, HTTP_PORT: "13100", MQTT_PORT: "11883", SEED_API_KEY: "integration-test-key", ... },
-});
-await waitForServer(`http://localhost:13100/health`);
-```
-
-`waitForServer` 轮询 `/health`，避免 race condition。
-
----
-
-## 8. dmPolicy 配置
-
-| 值          | 行为                                   |
-|-------------|---------------------------------------|
-| `pairing`   | 需先执行 `openclaw channels pair` 配对 |
-| `open`      | 任意发送者都能触发 AI                  |
-| `allowlist` | 只有 `allowFrom` 列表中的 ID 能触发   |
-
-本地调试推荐用 `dmPolicy: "open"` + `allowFrom: ["*"]`，省去配对步骤。
-
----
-
-## 9. 入站媒体消息处理
-
-wechaty-web-panel 在 `publishClawMessage` 中把处理好的媒体数据通过 MQTT 发给插件，payload 携带三个额外字段：
-
-| 字段 | 说明 |
-|------|------|
-| `type` | 消息类型字符串：`文字` / `图片` / `视频` / `文件` / `语音` 等 |
-| `url` | 媒体资源链接（已上传 OSS 时为 HTTP URL，未配置 OSS 时为 base64） |
-| `mediaInfo` | 视频号/名片/h5链接等结构化元数据 |
-
-### 处理规则（inbound.ts）
-
-1. **跳过判断**：`!msg.content?.trim() && !msg.url` — 有 url 时不能跳过（图片消息 content 可能为空）
-2. **base64 过滤**：`msg.url?.startsWith("data:")` 时不注入 `MediaUrl`，避免超长 token 爆炸
-3. **MediaUrl 注入**：仅 HTTP URL 时写入 `MediaUrl`/`MediaUrls`/`MediaPath`/`MediaType`
-4. **body 优先级**：`content`（已格式化的描述文字） > `<media:${type}>` placeholder
-
-```ts
-const mediaUrl = msg.url && !msg.url.startsWith("data:") ? msg.url : undefined;
-const body = msg.content?.trim() || (isMediaMsg ? `<media:${msg.type}>` : "");
-
-...(mediaUrl ? {
-  MediaUrl: mediaUrl,
-  MediaUrls: [mediaUrl],
-  MediaPath: mediaUrl,
-  MediaType: msg.type === "图片" ? "image/jpeg" : msg.type === "视频" ? "video/mp4" : undefined,
-} : {}),
-```
-
-### 场景对照
-
-| 场景 | `content` | `url` | AI 收到 |
-|------|-----------|-------|---------|
-| 纯文字 | 消息文本 | — | 消息文本 |
-| 图片（有 OSS） | 包含链接的描述 | HTTP URL | 描述文字 + `MediaUrl` |
-| 图片（无 OSS） | 含 base64 的描述 | `data:image/...` | 仅描述文字，base64 被过滤 |
-| 空 content + URL | — | HTTP URL | `<media:图片>` placeholder |
-
----
-
-## 10. 测试工具链
-
-```
-socket-server/   — npm run dev     自动加载 .env，预置测试账号
-socket-client/   — npm start       交互式终端，输入消息→看 AI 回复
-socket-chat/     — npx vitest run src/integration.test.ts
-```
-
-三个目录各自有 `.env`（被 `.gitignore` 忽略），`.env.example` 作为模板提交到 git。