@openclaw-channel/socket-chat 1.0.0

package/src/channel.ts

@@ -0,0 +1,395 @@
+import type {
+  ChannelAccountSnapshot,
+  ChannelPlugin,
+  ChannelStatusIssue,
+} from "openclaw/plugin-sdk";
+import {
+  buildBaseChannelStatusSummary,
+  buildBaseAccountStatusSnapshot,
+  collectStatusIssuesFromLastError,
+} from "openclaw/plugin-sdk";
+import {
+  DEFAULT_ACCOUNT_ID,
+  applySocketChatAccountConfig,
+  deleteSocketChatAccount,
+  isSocketChatAccountConfigured,
+  listSocketChatAccountIds,
+  normalizeAccountId,
+  resolveDefaultSocketChatAccountId,
+  resolveSocketChatAccount,
+  setSocketChatAccountEnabled,
+  type CoreConfig,
+  type ResolvedSocketChatAccount,
+} from "./config.js";
+import { probeSocketChatAccount } from "./probe.js";
+import {
+  buildTextPayload,
+  looksLikeSocketChatTargetId,
+  normalizeSocketChatTarget,
+  sendSocketChatMessage,
+  socketChatOutbound,
+} from "./outbound.js";
+import {
+  getActiveMqttClient,
+  getActiveMqttConfig,
+  monitorSocketChatProviderWithRegistry,
+} from "./mqtt-client.js";
+
+// ---------------------------------------------------------------------------
+// ChannelPlugin 实现
+// ---------------------------------------------------------------------------
+
+export const socketChatPlugin: ChannelPlugin<ResolvedSocketChatAccount> = {
+  // -------------------------------------------------------------------------
+  // 身份标识
+  // -------------------------------------------------------------------------
+  id: "socket-chat",
+
+  meta: {
+    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,
+    quickstartAllowFrom: true,
+  },
+
+  // -------------------------------------------------------------------------
+  // 能力声明
+  // -------------------------------------------------------------------------
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: true,       // 支持图片（type: 2）
+    reactions: false,
+    threads: false,
+    polls: false,
+    nativeCommands: false,
+    blockStreaming: true, // MQTT 不适合流式输出，等 AI 回复完整后再发
+  },
+
+  // -------------------------------------------------------------------------
+  // 配置 Schema
+  // -------------------------------------------------------------------------
+  configSchema: {
+    schema: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        apiKey: { type: "string" },
+        apiBaseUrl: { type: "string" },
+        name: { type: "string" },
+        enabled: { type: "boolean" },
+        dmPolicy: { type: "string", enum: ["pairing", "open", "allowlist"] },
+        allowFrom: { type: "array", items: { type: "string" } },
+        defaultTo: { type: "string" },
+        requireMention: { type: "boolean" },
+        mqttConfigTtlSec: { type: "number" },
+        maxReconnectAttempts: { type: "number" },
+        reconnectBaseDelayMs: { type: "number" },
+        useTls: { type: "boolean" },
+        accounts: {
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            properties: {
+              apiKey: { type: "string" },
+              apiBaseUrl: { type: "string" },
+              name: { type: "string" },
+              enabled: { type: "boolean" },
+              dmPolicy: { type: "string", enum: ["pairing", "open", "allowlist"] },
+              allowFrom: { type: "array", items: { type: "string" } },
+              defaultTo: { type: "string" },
+              requireMention: { type: "boolean" },
+              mqttConfigTtlSec: { type: "number" },
+              maxReconnectAttempts: { type: "number" },
+              reconnectBaseDelayMs: { type: "number" },
+              useTls: { type: "boolean" },
+            },
+          },
+        },
+      },
+    },
+    uiHints: {
+      apiKey: { label: "API Key", sensitive: true, help: "用于获取 MQTT 连接配置的 API Key" },
+      apiBaseUrl: { label: "API Base URL", help: "后端服务地址，留空使用默认值 https://api-bot.aibotk.com" },
+      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 },
+    },
+  },
+
+  // -------------------------------------------------------------------------
+  // 账号配置管理
+  // -------------------------------------------------------------------------
+  config: {
+    listAccountIds: (cfg) => listSocketChatAccountIds(cfg as CoreConfig),
+
+    resolveAccount: (cfg, accountId) =>
+      resolveSocketChatAccount(cfg as CoreConfig, accountId ?? DEFAULT_ACCOUNT_ID),
+
+    defaultAccountId: (cfg) => resolveDefaultSocketChatAccountId(cfg as CoreConfig),
+
+    isConfigured: (account) => isSocketChatAccountConfigured(account),
+
+    describeAccount: (account): ChannelAccountSnapshot => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: isSocketChatAccountConfigured(account),
+    }),
+
+    resolveAllowFrom: ({ cfg, accountId }) => {
+      const account = resolveSocketChatAccount(cfg as CoreConfig, accountId ?? DEFAULT_ACCOUNT_ID);
+      return account.config.allowFrom ?? [];
+    },
+
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((e) => String(e).trim())
+        .filter(Boolean)
+        .map((e) => e.replace(/^socket-chat:/i, "").toLowerCase()),
+
+    resolveDefaultTo: ({ cfg, accountId }) => {
+      const account = resolveSocketChatAccount(cfg as CoreConfig, accountId ?? DEFAULT_ACCOUNT_ID);
+      return account.config.defaultTo?.trim() || undefined;
+    },
+
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setSocketChatAccountEnabled({ cfg: cfg as CoreConfig, accountId, enabled }),
+
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteSocketChatAccount({ cfg: cfg as CoreConfig, accountId }),
+  },
+
+  // -------------------------------------------------------------------------
+  // 配对（pairing）
+  // -------------------------------------------------------------------------
+  pairing: {
+    idLabel: "socketChatUserId",
+    normalizeAllowEntry: (entry) => entry.replace(/^(socket-chat|sc):/i, ""),
+    notifyApproval: async ({ cfg, id }) => {
+      // 找到有活跃 MQTT 连接的账号发送配对批准通知
+      // 优先用 default 账号，fallback 到任意有活跃连接的账号
+      const accountIds = listSocketChatAccountIds(cfg as CoreConfig);
+      let targetAccountId = DEFAULT_ACCOUNT_ID;
+      for (const aid of accountIds) {
+        if (getActiveMqttClient(aid)) {
+          targetAccountId = aid;
+          break;
+        }
+      }
+      const client = getActiveMqttClient(targetAccountId);
+      const mqttConfig = getActiveMqttConfig(targetAccountId);
+      if (!client || !mqttConfig) return;
+      const payload = buildTextPayload(id, "You have been approved to chat with this assistant.");
+      await sendSocketChatMessage({ mqttClient: client, mqttConfig, payload });
+    },
+  },
+
+  // -------------------------------------------------------------------------
+  // 安全策略
+  // -------------------------------------------------------------------------
+  security: {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      const resolvedId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+      const usesAccountPath = Boolean(
+        (cfg as CoreConfig).channels?.["socket-chat"]?.accounts?.[resolvedId],
+      );
+      const basePath = usesAccountPath
+        ? `channels.socket-chat.accounts.${resolvedId}.`
+        : "channels.socket-chat.";
+      return {
+        policy: account.config.dmPolicy ?? "pairing",
+        allowFrom: account.config.allowFrom ?? [],
+        policyPath: `${basePath}dmPolicy`,
+        allowFromPath: basePath,
+        approveHint: `Run: openclaw channels pair socket-chat <userId>`,
+        normalizeEntry: (raw) => raw.replace(/^(socket-chat|sc):/i, ""),
+      };
+    },
+
+    collectWarnings: ({ account }) => {
+      const warnings: string[] = [];
+      if (!account.config.allowFrom?.length && account.config.dmPolicy === "open") {
+        warnings.push(
+          "- socket-chat: dmPolicy=\"open\" allows any sender to trigger AI. " +
+          "Consider setting dmPolicy=\"pairing\" or configuring allowFrom.",
+        );
+      }
+      return warnings;
+    },
+  },
+
+  // -------------------------------------------------------------------------
+  // 群组策略
+  // -------------------------------------------------------------------------
+  groups: {
+    resolveRequireMention: ({ cfg, accountId }) => {
+      const account = resolveSocketChatAccount(cfg as CoreConfig, accountId ?? DEFAULT_ACCOUNT_ID);
+      // 默认群消息需要 @提及才触发
+      return account.config.requireMention !== false;
+    },
+    resolveToolPolicy: () => undefined,
+  },
+
+  // -------------------------------------------------------------------------
+  // 消息目标规范化
+  // -------------------------------------------------------------------------
+  messaging: {
+    normalizeTarget: normalizeSocketChatTarget,
+    targetResolver: {
+      looksLikeId: looksLikeSocketChatTargetId,
+      hint: "<contactId|group:groupId|group:groupId@wxid_mention1,wxid_mention2>",
+    },
+  },
+
+  // -------------------------------------------------------------------------
+  // 出站发送
+  // -------------------------------------------------------------------------
+  outbound: socketChatOutbound,
+
+  // -------------------------------------------------------------------------
+  // 状态管理
+  // -------------------------------------------------------------------------
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      connected: false,
+      reconnectAttempts: 0,
+      lastConnectedAt: null,
+      lastDisconnect: null,
+      lastEventAt: null,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+      lastInboundAt: null,
+      lastOutboundAt: null,
+    },
+
+    collectStatusIssues: (snapshots): ChannelStatusIssue[] => {
+      const issues: ChannelStatusIssue[] = [];
+      for (const snap of snapshots) {
+        issues.push(...collectStatusIssuesFromLastError("socket-chat", [snap]));
+        if (!snap.configured) {
+          issues.push({
+            channel: "socket-chat",
+            accountId: snap.accountId,
+            kind: "config",
+            message: "socket-chat account is not configured (missing apiKey).",
+            fix: "Run: openclaw channels add socket-chat",
+          });
+        }
+      }
+      return issues;
+    },
+
+    buildChannelSummary: ({ snapshot }) =>
+      buildBaseChannelStatusSummary(snapshot),
+
+    probeAccount: async ({ account, timeoutMs }) =>
+      probeSocketChatAccount({ account, timeoutMs }),
+
+    buildAccountSnapshot: ({ account, runtime, probe }) => {
+      const configured = isSocketChatAccountConfigured(account);
+      const accountWithConfigured = { ...account, configured };
+      const base = buildBaseAccountStatusSnapshot({ account: accountWithConfigured, runtime, probe });
+      return {
+        ...base,
+        // 补充 probe 信息到 snapshot
+        probe,
+        ...(probe && typeof probe === "object" && "host" in probe
+          ? { baseUrl: `mqtt://${(probe as { host?: string }).host}:${(probe as { port?: string }).port}` }
+          : {}),
+        lastInboundAt: runtime?.lastInboundAt ?? null,
+        lastOutboundAt: runtime?.lastOutboundAt ?? null,
+      };
+    },
+  },
+
+  // -------------------------------------------------------------------------
+  // Gateway：启动 MQTT 监听
+  // -------------------------------------------------------------------------
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+
+      if (!isSocketChatAccountConfigured(account)) {
+        ctx.log?.error?.(
+          `[${account.accountId}] socket-chat not configured (missing apiKey)`,
+        );
+        return;
+      }
+
+      ctx.log?.info?.(`[${account.accountId}] starting socket-chat MQTT provider`);
+
+      return monitorSocketChatProviderWithRegistry({
+        account,
+        accountId: account.accountId,
+        ctx,
+        log: ctx.log ?? {
+          info: () => {},
+          warn: () => {},
+          error: () => {},
+        },
+      });
+    },
+
+    logoutAccount: async ({ accountId }) => {
+      const client = getActiveMqttClient(accountId);
+      client?.end(true);
+      return { cleared: true, loggedOut: true };
+    },
+  },
+
+  // -------------------------------------------------------------------------
+  // 配置变更热重载
+  // -------------------------------------------------------------------------
+  reload: {
+    configPrefixes: ["channels.socket-chat"],
+  },
+
+  // -------------------------------------------------------------------------
+  // CLI setup 向导
+  // -------------------------------------------------------------------------
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+      const apiKey = (input.token ?? "").trim();
+      const apiBaseUrl = (input.httpUrl ?? "").trim() || undefined;
+      return applySocketChatAccountConfig({
+        cfg: cfg as CoreConfig,
+        accountId,
+        apiKey,
+        apiBaseUrl,
+        name: input.name,
+      });
+    },
+
+    validateInput: ({ input }) => {
+      if (!input.token?.trim()) {
+        return "socket-chat requires --token <apiKey>";
+      }
+      return null;
+    },
+  },
+
+  // -------------------------------------------------------------------------
+  // Agent prompt 提示词（告诉 AI 如何使用该 channel）
+  // -------------------------------------------------------------------------
+  agentPrompt: {
+    messageToolHints: () => [
+      "- socket-chat: to send to a group, use target format `group:<groupId>`. " +
+        "To @mention users in a group: `group:<groupId>@<userId1>,<userId2>`.",
+      "- socket-chat: to send an image, provide a public HTTP URL as the media parameter.",
+      "- socket-chat: direct messages use the sender's contactId (e.g. `wxid_xxx`) as the target.",
+    ],
+  },
+};

package/src/config-schema.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+import { SocketChatAccountConfigSchema, SocketChatTopLevelConfigSchema } from "./config-schema.js";
+
+describe("SocketChatAccountConfigSchema", () => {
+  it("accepts a fully specified config", () => {
+    const parsed = SocketChatAccountConfigSchema.parse({
+      apiKey: "key123",
+      apiBaseUrl: "https://example.com",
+      name: "My Bot",
+      enabled: true,
+      dmPolicy: "pairing",
+      allowFrom: ["wxid_alice", "wxid_bob"],
+      defaultTo: "wxid_alice",
+      requireMention: true,
+      mqttConfigTtlSec: 600,
+      maxReconnectAttempts: 5,
+      reconnectBaseDelayMs: 1000,
+      useTls: false,
+    });
+
+    expect(parsed.apiKey).toBe("key123");
+    expect(parsed.dmPolicy).toBe("pairing");
+    expect(parsed.allowFrom).toEqual(["wxid_alice", "wxid_bob"]);
+  });
+
+  it("accepts an empty config (all fields optional)", () => {
+    const parsed = SocketChatAccountConfigSchema.parse({});
+    expect(parsed).toBeDefined();
+    expect(parsed.apiKey).toBeUndefined();
+  });
+
+  it("validates dmPolicy enum values", () => {
+    expect(() =>
+      SocketChatAccountConfigSchema.parse({ dmPolicy: "invalid" }),
+    ).toThrow();
+  });
+
+  it("accepts all valid dmPolicy values", () => {
+    for (const policy of ["pairing", "open", "allowlist"] as const) {
+      const parsed = SocketChatAccountConfigSchema.parse({ dmPolicy: policy });
+      expect(parsed.dmPolicy).toBe(policy);
+    }
+  });
+
+  it("rejects non-boolean for enabled field", () => {
+    expect(() =>
+      SocketChatAccountConfigSchema.parse({ enabled: "yes" }),
+    ).toThrow();
+  });
+
+  it("accepts allowFrom as string array", () => {
+    const parsed = SocketChatAccountConfigSchema.parse({
+      allowFrom: ["wxid_abc", "wxid_def"],
+    });
+    expect(parsed.allowFrom).toEqual(["wxid_abc", "wxid_def"]);
+  });
+});
+
+describe("SocketChatTopLevelConfigSchema", () => {
+  it("accepts a multi-account config", () => {
+    const parsed = SocketChatTopLevelConfigSchema.parse({
+      accounts: {
+        default: { apiKey: "key-default", apiBaseUrl: "https://default.com" },
+        work: { apiKey: "key-work", apiBaseUrl: "https://work.com" },
+      },
+    });
+    expect(parsed.accounts?.["default"]?.apiKey).toBe("key-default");
+    expect(parsed.accounts?.["work"]?.apiKey).toBe("key-work");
+  });
+
+  it("accepts top-level fields alongside accounts map", () => {
+    const parsed = SocketChatTopLevelConfigSchema.parse({
+      apiKey: "top-key",
+      apiBaseUrl: "https://top.com",
+      accounts: {
+        work: { apiKey: "work-key", apiBaseUrl: "https://work.com" },
+      },
+    });
+    expect(parsed.apiKey).toBe("top-key");
+    expect(parsed.accounts?.["work"]?.apiKey).toBe("work-key");
+  });
+
+  it("accepts config without accounts map", () => {
+    const parsed = SocketChatTopLevelConfigSchema.parse({
+      apiKey: "k",
+      apiBaseUrl: "https://x.com",
+    });
+    expect(parsed.accounts).toBeUndefined();
+  });
+});

package/src/config-schema.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+
+/**
+ * channels.socket-chat 账号配置 Schema
+ *
+ * 在 openclaw 配置文件（~/.openclaw/config.yaml）中对应：
+ *
+ * channels:
+ *   socket-chat:
+ *     apiKey: "your-api-key"
+ *     apiBaseUrl: "https://your-server.com"
+ *     enabled: true
+ *     dmPolicy: "pairing"  # pairing | open | allowlist
+ *     allowFrom: []
+ *
+ * 多账号：
+ *   channels:
+ *     socket-chat:
+ *       accounts:
+ *         work:
+ *           apiKey: "..."
+ *           apiBaseUrl: "..."
+ */
+export const SocketChatAccountConfigSchema = z.object({
+  /** API Key，用于获取 MQTT 连接信息 */
+  apiKey: z.string().optional(),
+  /** 后端服务 base URL，例如 https://example.com */
+  apiBaseUrl: z.string().optional(),
+  /** 账号显示名称 */
+  name: z.string().optional(),
+  /** 是否启用此账号 */
+  enabled: z.boolean().optional(),
+  /** DM 安全策略 */
+  dmPolicy: z.enum(["pairing", "open", "allowlist"]).optional(),
+  /** 允许触发 AI 的发送者 ID 列表 */
+  allowFrom: z.array(z.string()).optional(),
+  /** 默认发消息目标（contactId 或 group:groupId） */
+  defaultTo: z.string().optional(),
+  /** 群组消息是否需要 @提及 bot 才触发 */
+  requireMention: z.boolean().optional(),
+  /** MQTT 连接配置缓存 TTL（秒），默认 300 */
+  mqttConfigTtlSec: z.number().optional(),
+  /** MQTT 重连最大次数，默认 10 */
+  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>;
+
+/** 顶层 channels.socket-chat 配置（包含 accounts 多账号支持） */
+export const SocketChatTopLevelConfigSchema = SocketChatAccountConfigSchema.extend({
+  accounts: z.record(z.string(), SocketChatAccountConfigSchema).optional(),
+});
+
+export type SocketChatTopLevelConfig = z.infer<typeof SocketChatTopLevelConfigSchema>;