@openclaw-channel/socket-chat 1.0.0

package/DEVNOTES.md

@@ -0,0 +1,219 @@
+# 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。

package/README.md

@@ -0,0 +1,215 @@
+# socket-chat OpenClaw Extension
+
+通过 **MQTT** 协议与自定义 IM 系统对接的 OpenClaw channel plugin。
+
+---
+
+## 工作原理
+
+```
+IM 平台 ──MQTT──► reciveTopic ──► socket-chat plugin ──► OpenClaw AI
+OpenClaw AI ──► socket-chat plugin ──MQTT──► sendTopic ──► IM 平台
+```
+
+1. 插件启动时，调用 `GET /api/openclaw/chat/config?apikey={apiKey}` 获取 MQTT 连接参数
+2. 建立 MQTT 连接，订阅 `reciveTopic`
+3. 收到消息后，通过 `channelRuntime` 派发给 AI agent
+4. AI 回复通过 `outbound.sendText/sendMedia` 向 `sendTopic` 发布
+
+---
+
+## 安装
+
+```bash
+# 从 npm 安装
+openclaw plugins add @openclaw-channel/socket-chat
+
+# 或者本地开发时从路径安装
+openclaw plugins add /path/to/socket-chat
+```
+
+---
+
+## 配置
+
+在 `~/.openclaw/config.yaml` 中添加：
+
+```yaml
+channels:
+  socket-chat:
+    apiKey: "your-api-key"
+    enabled: true
+    dmPolicy: "pairing"   # pairing | open | allowlist
+    allowFrom: []         # 允许触发 AI 的发送者 ID 白名单
+    requireMention: true  # 群组消息是否需要 @提及机器人
+```
+
+### 多账号配置
+
+```yaml
+channels:
+  socket-chat:
+    accounts:
+      work:
+        apiKey: "api-key"
+        enabled: true
+      personal:
+        apiKey: "api-key"
+        enabled: true
+```
+
+### 可选高级配置
+
+| 字段 | 默认值 | 说明 |
+|------|--------|------|
+| `mqttConfigTtlSec` | `300` | MQTT 配置缓存时间（秒） |
+| `maxReconnectAttempts` | `10` | MQTT 断线最大重连次数 |
+| `reconnectBaseDelayMs` | `2000` | 重连基础延迟（毫秒，指数退避） |
+| `useTls` | `false` | 是否使用 `mqtts://`（TLS） |
+
+---
+
+## 通过 CLI 添加账号
+
+```bash
+openclaw channels add socket-chat --token <apiKey>
+```
+
+---
+
+## 消息格式
+
+### 收到的 MQTT 消息（reciveTopic）
+
+文字消息：
+
+```json
+{
+  "content": "消息内容",
+  "robotId": "wxid_robot",
+  "senderId": "wxid_user123",
+  "senderName": "用户昵称",
+  "isGroup": false,
+  "groupId": "roomid_xxx",
+  "groupName": "群组名称",
+  "timestamp": 1234567890123,
+  "messageId": "uuid-xxx",
+  "type": "文字"
+}
+```
+
+图片 / 视频 / 文件消息（已上传 OSS）：
+
+```json
+{
+  "content": "【图片消息】\n文件名：img.jpg\n下载链接：https://oss.example.com/img.jpg",
+  "robotId": "wxid_robot",
+  "senderId": "wxid_user123",
+  "senderName": "用户昵称",
+  "isGroup": false,
+  "timestamp": 1234567890123,
+  "messageId": "uuid-xxx",
+  "type": "图片",
+  "url": "https://oss.example.com/img.jpg"
+}
+```
+
+> **说明**：`type` 枚举值包括 `文字`、`图片`、`视频`、`文件`、`语音`、`名片`、`h5链接`、`视频号`、`位置`、`历史记录`。
+>
+> 图片/视频等媒体消息会同时携带 `content`（格式化描述文字）和 `url`（资源链接）。若平台未配置 OSS，`url` 为 base64 字符串，插件会忽略 base64 内容，仅将 `content` 描述文字传给 AI agent。
+
+#### 媒体消息处理逻辑
+
+| 场景 | `content` | `url` | AI 收到的内容 |
+|------|-----------|-------|--------------|
+| 纯文字 | 消息文本 | — | 消息文本 |
+| 图片（有 OSS URL） | 包含下载链接的描述 | HTTP URL | 描述文字 + `MediaUrl` 字段 |
+| 图片（无 OSS，base64） | 包含 base64 的描述 | `data:image/...` | 仅描述文字（base64 被过滤） |
+| 仅有 URL、无 content | — | HTTP URL | `<media:图片>` placeholder |
+
+### 发送的 MQTT 消息（sendTopic）
+
+```json
+{
+  "isGroup": false,
+  "contactId": "wxid_user123",
+  "messages": [
+    { "type": 1, "content": "文字消息" }
+  ]
+}
+```
+
+群消息 + @提及：
+```json
+{
+  "isGroup": true,
+  "groupId": "roomid_xxx",
+  "mentionIds": ["wxid_a", "wxid_b"],
+  "messages": [
+    { "type": 1, "content": "回复内容" },
+    { "type": 2, "url": "https://example.com/image.jpg" }
+  ]
+}
+```
+
+---
+
+## 发消息目标格式（openclaw message send）
+
+| 格式 | 说明 |
+|------|------|
+| `wxid_xxx` | 私聊某用户 |
+| `group:roomid_xxx` | 发到群组 |
+| `group:roomid_xxx@wxid_a,wxid_b` | 发到群组并 @提及用户 |
+
+```bash
+openclaw message send "Hello" --channel socket-chat --to wxid_user123
+openclaw message send "Hello group" --channel socket-chat --to group:roomid_xxx
+```
+
+---
+
+## 项目结构
+
+```
+socket-chat/
+├── index.ts              # 插件入口（register）
+├── package.json          # 包配置，含 openclaw.extensions
+├── tsconfig.json
+└── src/
+    ├── types.ts          # MQTT 消息类型定义
+    ├── config-schema.ts  # Zod 配置 Schema
+    ├── config.ts         # 账号配置解析 + 写入工具
+    ├── api.ts            # GET /api/openclaw/chat/config 调用（带缓存）
+    ├── outbound.ts       # 发送消息（buildPayload + sendSocketChatMessage）
+    ├── inbound.ts        # 入站消息处理 → dispatch AI 回复
+    ├── mqtt-client.ts    # MQTT 连接管理 + 自动重连 monitor 循环
+    ├── probe.ts          # 账号连通性探测
+    ├── runtime.ts        # PluginRuntime 单例
+    └── channel.ts        # ChannelPlugin 主体（所有 adapter 实现）
+```
+
+---
+
+## API 接口要求
+
+后端需实现：
+
+### `GET /openapi/v1/openclaw/chat/config?apikey={apiKey}`
+
+**Response 200:**
+```json
+{
+  "host": "mqtt.example.com",
+  "port": "1883",
+  "username": "mqttuser",
+  "password": "mqttpass",
+  "clientId": "openclaw-bot-001",
+  "reciveTopic": "/im/botId/msg",
+  "sendTopic": "/im/botId/send",
+  "robotId": "wxid_bot",
+  "userId": "user123"
+}
+```
+
+所有字段均为必填字符串。

package/index.ts

@@ -0,0 +1,17 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { socketChatPlugin } from "./src/channel.js";
+import { setSocketChatRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "socket-chat",
+  name: "Socket Chat",
+  description: "Socket Chat channel plugin — MQTT-based IM bridge",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setSocketChatRuntime(api.runtime);
+    api.registerChannel({ plugin: socketChatPlugin });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "socket-chat",
+  "channels": ["socket-chat"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@openclaw-channel/socket-chat",
+  "version": "1.0.0",
+  "description": "OpenClaw Socket Chat channel plugin — MQTT-based IM bridge",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "mqtt": "^4.3.8",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.0.0"
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "socket-chat",
+      "label": "Socket Chat",
+      "selectionLabel": "Socket Chat (MQTT plugin)",
+      "docsPath": "/channels/socket-chat",
+      "docsLabel": "socket-chat",
+      "blurb": "MQTT-based IM bridge; configure an API key to connect.",
+      "order": 90
+    },
+    "install": {
+      "npmSpec": "@openclaw/socket-chat",
+      "localPath": ".",
+      "defaultChoice": "local"
+    }
+  }
+}

package/src/__sdk-stub__.ts

@@ -0,0 +1,12 @@
+/**
+ * Minimal openclaw/plugin-sdk stub for socket-chat unit tests.
+ *
+ * Only re-exports the symbols that socket-chat/src actually imports at runtime.
+ * This avoids pulling in the full SDK dependency tree (which includes modules
+ * like json5 that require the openclaw monorepo workspace to resolve).
+ */
+export { resolveAllowlistMatchByCandidates } from "../../openclaw/src/channels/allowlist-match.js";
+export { createNormalizedOutboundDeliverer } from "../../openclaw/src/plugin-sdk/reply-payload.js";
+
+// ---- type-only re-exports (erased at runtime) ----
+export type { ChannelGatewayContext } from "../../openclaw/src/plugin-sdk/index.js";

package/src/api.ts

@@ -0,0 +1,95 @@
+import type { SocketChatMqttConfig } from "./types.js";
+
+/**
+ * 调用后端 API 获取 MQTT 连接配置
+ * GET {apiBaseUrl}/api/openclaw/chat/config?apikey={apiKey}
+ */
+export async function fetchMqttConfig(params: {
+  apiBaseUrl: string;
+  apiKey: string;
+  timeoutMs?: number;
+}): Promise<SocketChatMqttConfig> {
+  const { apiBaseUrl, apiKey, timeoutMs = 10_000 } = params;
+  const url = `${apiBaseUrl.replace(/\/$/, "")}/openapi/v1/openclaw/chat/config?apiKey=${encodeURIComponent(apiKey)}`;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const res = await fetch(url, {
+      method: "GET",
+      headers: { Accept: "application/json" },
+      signal: controller.signal,
+    });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new Error(
+        `fetchMqttConfig: HTTP ${res.status} from ${url}${body ? ` — ${body.slice(0, 200)}` : ""}`,
+      );
+    }
+
+    const data = (await res.json()) as unknown;
+    validateMqttConfig(data);
+    return data as SocketChatMqttConfig;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function validateMqttConfig(data: unknown): asserts data is SocketChatMqttConfig {
+  if (!data || typeof data !== "object") {
+    throw new Error("fetchMqttConfig: response is not an object");
+  }
+  const d = data as Record<string, unknown>;
+  const required: (keyof SocketChatMqttConfig)[] = [
+    "host",
+    "port",
+    "username",
+    "password",
+    "clientId",
+    "reciveTopic",
+    "sendTopic",
+  ];
+  for (const key of required) {
+    if (!d[key]) {
+      throw new Error(`fetchMqttConfig: missing or invalid field "${key}" in response`);
+    }
+  }
+}
+
+/**
+ * 简单的 TTL 缓存，避免每次重连都重新请求 config
+ */
+type CacheEntry = {
+  config: SocketChatMqttConfig;
+  fetchedAt: number;
+};
+
+const configCache = new Map<string, CacheEntry>();
+
+export async function fetchMqttConfigCached(params: {
+  apiBaseUrl: string;
+  apiKey: string;
+  ttlMs?: number;
+  timeoutMs?: number;
+}): Promise<SocketChatMqttConfig> {
+  const { apiBaseUrl, apiKey, ttlMs = 300_000, timeoutMs } = params;
+  const cacheKey = `${apiBaseUrl}::${apiKey}`;
+  const cached = configCache.get(cacheKey);
+  if (cached && Date.now() - cached.fetchedAt < ttlMs) {
+    return cached.config;
+  }
+  const config = await fetchMqttConfig({ apiBaseUrl, apiKey, timeoutMs });
+  configCache.set(cacheKey, { config, fetchedAt: Date.now() });
+  return config;
+}
+
+/** 清除指定账号的缓存（例如重连时强制刷新） */
+export function invalidateMqttConfigCache(params: {
+  apiBaseUrl: string;
+  apiKey: string;
+}): void {
+  const cacheKey = `${params.apiBaseUrl}::${params.apiKey}`;
+  configCache.delete(cacheKey);
+}