@thclouds/openclaw-channel-taidesk 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# openclaw-channel-taidesk
+
+OpenClaw 渠道插件：**Taidesk MQTT 入站**（订阅 `/open/{agentId}`）+ **HTTP 出站**。
+
+## 文档
+
+- [MQTT / HTTP 契约](docs/TAIDESK-WS-CONTRACT.zh-CN.md)
+- [四渠道对比与选型](docs/CHANNEL-COMPARISON.zh-CN.md)
+- [开发计划](docs/TAIDESK-PLUGIN-DEV-PLAN.zh-CN.md)
+
+## 依赖
+
+- Node.js >= 22
+- `openclaw` peer `>=2026.3.22`
+
+## 配置示例（`openclaw.json` 片段）
+
+```json
+{
+  "channels": {
+    "taidesk": {
+      "accounts": {
+        "default": {
+          "webhook": "https://console.taidesk.com/api/app-ai/ai/v1/agent/{id}/resp",
+          "mqttUrl": "https://console.taidesk.com/ws",
+          "agentId": "your-agent-id",
+          "apiKey": "your-agent-key",
+          "name": "your-agent-name",
+          "mqttUsername": "optional",
+          "mqttPassword": "optional"
+        }
+      }
+    }
+  }
+}
+```
+
+订阅 topic：**`/open/{agentId}`**。入站 JSON 见契约文档中的 `agent_msg` 示例。
+
+## 脚本
+
+| 命令 | 说明 |
+|------|------|
+| `npm run type-check` | TypeScript 检查 |
+| `npm test` | Vitest 单元测试 |
+
+## 许可
+
+MIT

package/index.ts

@@ -0,0 +1,14 @@
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
+
+import { taideskPlugin } from "./src/channel.js";
+import { setTaideskRuntime } from "./src/runtime.js";
+
+export { taideskPlugin, setTaideskRuntime };
+
+export default defineChannelPluginEntry({
+  id: "taidesk",
+  name: "Taidesk Channel",
+  description: "Taidesk WebSocket inbound + HTTP outbound",
+  plugin: taideskPlugin,
+  setRuntime: setTaideskRuntime,
+});

package/openclaw.plugin.json

@@ -0,0 +1,6 @@
+{
+  "id": "taidesk",
+  "name": "Taidesk Channel",
+  "description": "Taidesk WebSocket inbound + HTTP outbound",
+  "extensions": ["./index.ts"]
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@thclouds/openclaw-channel-taidesk",
+  "version": "0.1.0",
+  "description": "OpenClaw Taidesk channel plugin (MQTT inbound + HTTP outbound)",
+  "license": "MIT",
+  "type": "module",
+  "main": "index.ts",
+  "files": [
+    "index.ts",
+    "setup-entry.ts",
+    "src/**/*.ts",
+    "openclaw.plugin.json"
+  ],
+  "scripts": {
+    "type-check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run type-check && npm test"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "mqtt": "^5.10.0",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.22"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "openclaw": "2026.3.23",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "taidesk",
+      "label": "Taidesk",
+      "selectionLabel": "Taidesk (MQTT)",
+      "docsPath": "/channels/taidesk",
+      "docsLabel": "Taidesk",
+      "blurb": "Taidesk channel via MQTT inbound",
+      "order": 76
+    },
+    "install": {
+      "npmSpec": "@thclouds/openclaw-channel-taidesk",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.22"
+    }
+  }
+}

package/setup-entry.ts

@@ -0,0 +1,5 @@
+import { defineSetupPluginEntry } from "openclaw/plugin-sdk/core";
+
+import { taideskPlugin } from "./src/channel.js";
+
+export default defineSetupPluginEntry(taideskPlugin);

package/src/api/taidesk-outbound.ts

@@ -0,0 +1,42 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+
+import { resolveTaideskAccount } from "../config.js";
+import type { TaideskAccountConfig } from "../types.js";
+
+function resolveTaideskWebhookUrl(config: TaideskAccountConfig): string {
+  return config.webhook.replaceAll("{id}", config.agentId);
+}
+
+export async function sendTaideskText(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  conversationId: string;
+  text: string;
+  log?: (m: string) => void;
+  errLog?: (m: string) => void;
+}): Promise<{ ok: boolean; status: number; body?: string }> {
+  const { cfg, accountId, conversationId, text } = params;
+  const log = params.log ?? (() => {});
+  const errLog = params.errLog ?? log;
+  const { config } = resolveTaideskAccount(cfg, accountId);
+  const url = resolveTaideskWebhookUrl(config);
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+  const bearer = config.apiKey ?? config.token;
+  if (bearer) {
+    headers.Authorization = `Bearer ${bearer}`;
+  }
+  const body = JSON.stringify({
+    conversationId,
+    text,
+  });
+  log(`taidesk outbound POST ${url.toString()} len=${body.length}`);
+  const res = await fetch(url, { method: "POST", headers, body });
+  const raw = await res.text();
+  if (!res.ok) {
+    errLog(`taidesk outbound HTTP ${res.status}: ${raw.slice(0, 500)}`);
+    return { ok: false, status: res.status, body: raw };
+  }
+  return { ok: true, status: res.status, body: raw };
+}

package/src/channel.ts

@@ -0,0 +1,160 @@
+import { randomUUID } from "node:crypto";
+
+import type { ChannelGatewayContext, ChannelPlugin } from "openclaw/plugin-sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+import { buildChannelConfigSchema } from "openclaw/plugin-sdk/core";
+
+import { TaideskChannelConfigSchema } from "./config-schema.js";
+import {
+  applyTaideskAccountDefaults,
+  getTaideskConfig,
+  isTaideskAccountConfigured,
+} from "./config.js";
+import { startTaideskMonitor } from "./monitor/taidesk-monitor.js";
+import { sendTaideskText } from "./api/taidesk-outbound.js";
+import type { TaideskAccountConfig } from "./types.js";
+
+export type ResolvedTaideskAccount = {
+  accountId: string;
+  config: TaideskAccountConfig;
+  enabled: boolean;
+  configured: boolean;
+  name?: string | null;
+};
+
+function mergeDefaults(account: TaideskAccountConfig | undefined): TaideskAccountConfig {
+  if (!account) {
+    throw new Error("taidesk: account config missing");
+  }
+  const merged = applyTaideskAccountDefaults(account);
+  return {
+    ...merged,
+    enabled: merged.enabled !== false,
+  };
+}
+
+export const taideskPlugin: ChannelPlugin<ResolvedTaideskAccount> = {
+  id: "taidesk",
+  meta: {
+    id: "taidesk",
+    label: "Taidesk",
+    selectionLabel: "Taidesk (MQTT)",
+    docsPath: "/channels/taidesk",
+    blurb: "Taidesk：MQTT 入站 `/open/{agentId}` + HTTP 出站",
+  },
+  configSchema: buildChannelConfigSchema(TaideskChannelConfigSchema),
+  reload: { configPrefixes: ["channels.taidesk"] },
+  capabilities: {
+    chatTypes: ["direct"],
+    reactions: false,
+    threads: false,
+    media: false,
+    nativeCommands: false,
+    blockStreaming: false,
+  },
+  config: {
+    listAccountIds: (cfg: OpenClawConfig): string[] => {
+      const { accounts } = getTaideskConfig(cfg);
+      const ids = Object.keys(accounts);
+      return ids.length > 0 ? ids : [];
+    },
+    resolveAccount: (cfg: OpenClawConfig, accountId?: string | null) => {
+      const { accounts } = getTaideskConfig(cfg);
+      const id = accountId?.trim() || "default";
+      const raw = accounts[id];
+      if (!raw) {
+        const empty: TaideskAccountConfig = {
+          mqttUrl: "",
+          agentId: "",
+          webhook: "",
+          apiKey: "",
+          name: "",
+        };
+        return {
+          accountId: id,
+          config: empty,
+          enabled: false,
+          configured: false,
+          name: null,
+        };
+      }
+      const config = mergeDefaults(raw);
+      const configured = isTaideskAccountConfigured(config);
+      return {
+        accountId: id,
+        config,
+        enabled: config.enabled !== false,
+        configured,
+        name: config.name ?? null,
+      };
+    },
+    defaultAccountId: () => "default",
+    isConfigured: (account: ResolvedTaideskAccount) => account.configured,
+    describeAccount: (account: ResolvedTaideskAccount) => ({
+      accountId: account.accountId,
+      name: account.config?.name ?? "Taidesk",
+      enabled: account.enabled,
+      configured: account.configured,
+    }),
+  },
+  security: {
+    resolveDmPolicy: () => ({
+      policy: "open",
+      allowFrom: [],
+      policyPath: "channels.taidesk.dmPolicy",
+      allowFromPath: "channels.taidesk.allowFrom",
+      approveHint: "Taidesk: 默认开放会话",
+    }),
+  },
+  outbound: {
+    deliveryMode: "direct",
+    resolveTarget: ({ to }: { to?: string }) => {
+      const trimmed = to?.trim();
+      if (!trimmed) {
+        return { ok: false as const, error: new Error("taidesk: --to <conversationId> required") };
+      }
+      return { ok: true as const, to: trimmed };
+    },
+    sendText: async (ctx) => {
+      const { cfg, to, text, accountId } = ctx;
+      const id = accountId ?? "default";
+      const result = await sendTaideskText({
+        cfg,
+        accountId: id,
+        conversationId: to,
+        text,
+        log: (m) => {
+          console.info(`[taidesk] ${m}`);
+        },
+        errLog: (m) => {
+          console.error(`[taidesk] ${m}`);
+        },
+      });
+      if (!result.ok) {
+        throw new Error(result.body ?? `HTTP ${result.status}`);
+      }
+      return {
+        channel: "taidesk",
+        messageId: randomUUID(),
+      };
+    },
+  },
+  gateway: {
+    startAccount: async (ctx: ChannelGatewayContext<ResolvedTaideskAccount>) => {
+      const { account, cfg, abortSignal, channelRuntime, log } = ctx;
+      if (!isTaideskAccountConfigured(account.config)) {
+        throw new Error("taidesk: mqttUrl、agentId、webhook、apiKey 为必填（且需替换默认占位 agentId/apiKey）");
+      }
+      const mon = startTaideskMonitor({
+        cfg,
+        accountId: account.accountId,
+        accountConfig: account.config,
+        channelRuntime,
+        abortSignal,
+        log: (m) => log?.info?.(m),
+        errLog: (m) => log?.error?.(m),
+      });
+      return { stop: () => mon.close() };
+    },
+  },
+};

package/src/config-schema.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+
+/** 单账号默认（OpenClaw 配置 schema 与运行时合并共用） */
+export const TAIDESK_ACCOUNT_DEFAULTS = {
+  webhook: "https://console.taidesk.com/api/app-ai/ai/v1/agent/{id}/resp",
+  mqttUrl: "https://console.taidesk.com/ws",
+  agentId: "your-agent-id",
+  apiKey: "your-agent-key",
+  name: "your-agent-name",
+} as const;
+
+const MqttUrlSchema = z
+  .string()
+  .min(1)
+  .refine(
+    (s) =>
+      s.startsWith("mqtt://") ||
+      s.startsWith("mqtts://") ||
+      s.startsWith("ws://") ||
+      s.startsWith("wss://") ||
+      s.startsWith("http://") ||
+      s.startsWith("https://"),
+    "mqttUrl must start with mqtt://, mqtts://, ws://, wss://, http:// or https://",
+  );
+
+const TaideskAccountSchema = z.object({
+  enabled: z.boolean().optional(),
+  name: z.string().default(TAIDESK_ACCOUNT_DEFAULTS.name),
+  mqttUrl: MqttUrlSchema.default(TAIDESK_ACCOUNT_DEFAULTS.mqttUrl),
+  agentId: z.string().min(1).default(TAIDESK_ACCOUNT_DEFAULTS.agentId),
+  webhook: z.string().min(1).default(TAIDESK_ACCOUNT_DEFAULTS.webhook),
+  apiKey: z.string().default(TAIDESK_ACCOUNT_DEFAULTS.apiKey),
+  mqttUsername: z.string().optional(),
+  mqttPassword: z.string().optional(),
+  mqttClientId: z.string().optional(),
+  token: z.string().optional(),
+});
+
+export const TaideskChannelConfigSchema = z.object({
+  enabled: z.boolean().optional(),
+  dmPolicy: z.string().optional(),
+  accounts: z.record(z.string(), TaideskAccountSchema).optional(),
+});
+
+export type TaideskChannelConfig = z.infer<typeof TaideskChannelConfigSchema>;

package/src/config.ts

@@ -0,0 +1,63 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+
+import { TAIDESK_ACCOUNT_DEFAULTS } from "./config-schema.js";
+import type { TaideskAccountConfig } from "./types.js";
+
+export function getTaideskSection(cfg: OpenClawConfig): Record<string, unknown> {
+  const ch = cfg.channels as Record<string, unknown> | undefined;
+  return (ch?.taidesk as Record<string, unknown>) ?? {};
+}
+
+export function getTaideskConfig(cfg: OpenClawConfig): {
+  accounts: Record<string, TaideskAccountConfig>;
+} {
+  const raw = getTaideskSection(cfg);
+  const accounts = (raw.accounts as Record<string, TaideskAccountConfig>) ?? {};
+  return { accounts };
+}
+
+export function resolveTaideskAccount(
+  cfg: OpenClawConfig,
+  accountId?: string | null,
+): { accountId: string; config: TaideskAccountConfig } {
+  const { accounts } = getTaideskConfig(cfg);
+  const id = accountId?.trim() || "default";
+  const acct = accounts[id];
+  if (!acct) {
+    throw new Error(`taidesk: unknown accountId=${id}`);
+  }
+  return { accountId: id, config: applyTaideskAccountDefaults(acct) };
+}
+
+export function applyTaideskAccountDefaults(
+  raw: Partial<TaideskAccountConfig> | Record<string, unknown>,
+): TaideskAccountConfig {
+  const r = raw as Partial<TaideskAccountConfig>;
+  return {
+    enabled: r.enabled,
+    name: r.name ?? TAIDESK_ACCOUNT_DEFAULTS.name,
+    mqttUrl: r.mqttUrl ?? TAIDESK_ACCOUNT_DEFAULTS.mqttUrl,
+    agentId: r.agentId ?? TAIDESK_ACCOUNT_DEFAULTS.agentId,
+    webhook: r.webhook ?? TAIDESK_ACCOUNT_DEFAULTS.webhook,
+    apiKey: r.apiKey ?? TAIDESK_ACCOUNT_DEFAULTS.apiKey,
+    mqttUsername: r.mqttUsername,
+    mqttPassword: r.mqttPassword,
+    mqttClientId: r.mqttClientId,
+    token: r.token,
+  };
+}
+
+export function isTaideskAccountConfigured(account: TaideskAccountConfig): boolean {
+  if (
+    !account.webhook?.trim() ||
+    !account.mqttUrl?.trim() ||
+    !account.agentId?.trim() ||
+    !account.apiKey?.trim()
+  ) {
+    return false;
+  }
+  const stillPlaceholderCreds =
+    account.agentId === TAIDESK_ACCOUNT_DEFAULTS.agentId ||
+    account.apiKey === TAIDESK_ACCOUNT_DEFAULTS.apiKey;
+  return !stillPlaceholderCreds;
+}

package/src/dedup.ts

@@ -0,0 +1,17 @@
+/** 单进程内存去重，TTL 毫秒 */
+const seen = new Map<string, number>();
+
+export function shouldSkipDedup(key: string, ttlMs: number): boolean {
+  const now = Date.now();
+  const exp = seen.get(key);
+  if (exp !== undefined && exp > now) {
+    return true;
+  }
+  seen.set(key, now + ttlMs);
+  for (const [k, t] of seen) {
+    if (t < now) {
+      seen.delete(k);
+    }
+  }
+  return false;
+}

package/src/inbound-handler.ts

@@ -0,0 +1,88 @@
+import type { TaideskInboundEvent } from "./types.js";
+
+function parseTaideskCreateTimeMs(createTime: string): number {
+  if (!createTime.trim()) {
+    return Date.now();
+  }
+  const normalized = createTime.includes("T") ? createTime : createTime.replace(" ", "T");
+  const t = Date.parse(normalized);
+  return Number.isNaN(t) ? Date.now() : t;
+}
+
+/**
+ * Taidesk MQTT 载荷：`event: agent_msg`，`data` 为业务体。
+ * @see 用户约定示例
+ */
+function parseAgentMsgEnvelope(v: Record<string, unknown>): TaideskInboundEvent | null {
+  if (v.event !== "agent_msg") {
+    return null;
+  }
+  const data = v.data;
+  if (!data || typeof data !== "object") {
+    return null;
+  }
+  const d = data as Record<string, unknown>;
+  const eventId = d.id != null ? String(d.id) : "";
+  const sessionId = d.sessionId != null ? String(d.sessionId) : "";
+  const userId = d.userId != null ? String(d.userId) : "";
+  const content = d.content;
+  let text = "";
+  if (content && typeof content === "object") {
+    const c = content as Record<string, unknown>;
+    if (typeof c.text === "string") {
+      text = c.text;
+    }
+  }
+  const tenantId = typeof d.tenantId === "string" ? d.tenantId : undefined;
+  const createTime = typeof d.createTime === "string" ? d.createTime : "";
+  const timestamp = parseTaideskCreateTimeMs(createTime);
+  if (!eventId || !sessionId || !userId) {
+    return null;
+  }
+  return {
+    type: "agent_msg",
+    eventId,
+    conversationId: sessionId,
+    tenantId,
+    userId,
+    text,
+    timestamp,
+  };
+}
+
+/** 兼容旧版扁平 JSON（测试/迁移） */
+function parseLegacyFlat(v: Record<string, unknown>): TaideskInboundEvent | null {
+  if (v.type === "ping" || v.type === "pong") {
+    return null;
+  }
+  const eventId = typeof v.eventId === "string" ? v.eventId : "";
+  const conversationId = typeof v.conversationId === "string" ? v.conversationId : "";
+  const userId = typeof v.userId === "string" ? v.userId : "";
+  const text = typeof v.text === "string" ? v.text : "";
+  const timestamp = typeof v.timestamp === "number" ? v.timestamp : Date.now();
+  if (!eventId || !conversationId || !userId) {
+    return null;
+  }
+  return {
+    type: typeof v.type === "string" ? v.type : "message",
+    eventId,
+    conversationId,
+    tenantId: typeof v.tenantId === "string" ? v.tenantId : undefined,
+    userId,
+    text,
+    timestamp,
+  };
+}
+
+export function parseTaideskInboundJson(raw: string): TaideskInboundEvent | null {
+  try {
+    const v = JSON.parse(raw) as Record<string, unknown>;
+    const agent = parseAgentMsgEnvelope(v);
+    if (agent) {
+      return agent;
+    }
+    return parseLegacyFlat(v);
+  } catch {
+    return null;
+  }
+}

package/src/messaging/process-inbound.ts

@@ -0,0 +1,103 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";
+import { createTypingCallbacks } from "openclaw/plugin-sdk/channel-runtime";
+import type { MsgContext } from "openclaw/plugin-sdk/reply-runtime";
+
+import { sendTaideskText } from "../api/taidesk-outbound.js";
+import type { TaideskInboundEvent } from "../types.js";
+
+export async function processTaideskInbound(params: {
+  event: TaideskInboundEvent;
+  cfg: OpenClawConfig;
+  accountId: string;
+  channelRuntime: PluginRuntime["channel"];
+  log?: (m: string) => void;
+  errLog?: (m: string) => void;
+}): Promise<void> {
+  const { event, cfg, accountId, channelRuntime } = params;
+  const log = params.log ?? (() => {});
+  const errLog = params.errLog ?? log;
+
+  const ctx: MsgContext = {
+    Body: event.text ?? "",
+    From: event.userId,
+    To: event.conversationId,
+    MessageSid: event.eventId,
+    Timestamp: event.timestamp,
+    OriginatingChannel: "taidesk",
+    OriginatingTo: event.conversationId,
+    AccountId: accountId,
+    ChatType: "direct",
+    NativeChannelId: event.conversationId,
+    CommandAuthorized: true,
+  };
+
+  const route = channelRuntime.routing.resolveAgentRoute({
+    cfg,
+    channel: "taidesk",
+    accountId,
+    peer: { kind: "direct", id: event.conversationId },
+  });
+
+  ctx.SessionKey = route.sessionKey;
+
+  const finalized = channelRuntime.reply.finalizeInboundContext(ctx);
+
+  const storePath = channelRuntime.session.resolveStorePath(cfg.session?.store, {
+    agentId: route.agentId,
+  });
+
+  await channelRuntime.session.recordInboundSession({
+    storePath,
+    sessionKey: route.sessionKey,
+    ctx: finalized as Parameters<typeof channelRuntime.session.recordInboundSession>[0]["ctx"],
+    updateLastRoute: {
+      sessionKey: route.mainSessionKey,
+      channel: "taidesk",
+      to: event.conversationId,
+      accountId,
+    },
+    onRecordError: (err) => errLog(`recordInboundSession: ${String(err)}`),
+  });
+
+  const humanDelay = channelRuntime.reply.resolveHumanDelayConfig(cfg, route.agentId);
+
+  const typingCallbacks = createTypingCallbacks({
+    start: async () => {},
+    stop: async () => {},
+    onStartError: () => {},
+    onStopError: () => {},
+  });
+
+  const { dispatcher, replyOptions, markDispatchIdle } =
+    channelRuntime.reply.createReplyDispatcherWithTyping({
+      humanDelay,
+      typingCallbacks,
+      deliver: async (payload) => {
+        const text = payload.text ?? "";
+        await sendTaideskText({
+          cfg,
+          accountId,
+          conversationId: event.conversationId,
+          text,
+          log,
+          errLog,
+        });
+      },
+      onError: (err, info) => {
+        errLog(`taidesk reply ${info.kind}: ${String(err)}`);
+      },
+    });
+
+  await channelRuntime.reply.withReplyDispatcher({
+    dispatcher,
+    run: () =>
+      channelRuntime.reply.dispatchReplyFromConfig({
+        ctx: finalized,
+        cfg,
+        dispatcher,
+        replyOptions: { ...replyOptions, disableBlockStreaming: false },
+      }),
+  });
+  markDispatchIdle();
+}

package/src/monitor/taidesk-monitor.ts

@@ -0,0 +1,78 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";
+
+import { shouldSkipDedup } from "../dedup.js";
+import { parseTaideskInboundJson } from "../inbound-handler.js";
+import { createTaideskMqttConnection } from "../mqtt/taidesk-mqtt-client.js";
+import { processTaideskInbound } from "../messaging/process-inbound.js";
+import { resolveTaideskChannelRuntime } from "../runtime.js";
+import type { TaideskAccountConfig } from "../types.js";
+
+export type MonitorTaideskOpts = {
+  cfg: OpenClawConfig;
+  accountId: string;
+  accountConfig: TaideskAccountConfig;
+  channelRuntime?: PluginRuntime["channel"];
+  abortSignal: AbortSignal;
+  log?: (m: string) => void;
+  errLog?: (m: string) => void;
+};
+
+/**
+ * 替代微信 `monitorWeixinProvider`：MQTT 订阅 `/open/{agentId}` → 单条处理。
+ */
+export function startTaideskMonitor(opts: MonitorTaideskOpts): { close: () => void } {
+  const log = opts.log ?? (() => {});
+  const errLog = opts.errLog ?? log;
+  const pwd = opts.accountConfig.mqttPassword ?? opts.accountConfig.apiKey ?? opts.accountConfig.token;
+
+  const conn = createTaideskMqttConnection({
+    mqttUrl: opts.accountConfig.mqttUrl,
+    agentId: opts.accountConfig.agentId,
+    mqttUsername: opts.accountConfig.mqttUsername,
+    mqttPassword: pwd,
+    clientId: opts.accountConfig.mqttClientId,
+    abortSignal: opts.abortSignal,
+    onConnect: () => {
+      log(
+        `taidesk mqtt connected account=${opts.accountId} topic=/open/${opts.accountConfig.agentId}`,
+      );
+    },
+    onMessage: (_topic, raw) => {
+      void (async () => {
+        const ev = parseTaideskInboundJson(raw);
+        if (!ev) {
+          return;
+        }
+        const dedupKey = `${opts.accountId}:${ev.eventId}`;
+        if (shouldSkipDedup(dedupKey, 120_000)) {
+          log(`taidesk dedup skip eventId=${ev.eventId}`);
+          return;
+        }
+        try {
+          const channelRuntime = await resolveTaideskChannelRuntime({
+            channelRuntime: opts.channelRuntime,
+          });
+          await processTaideskInbound({
+            event: ev,
+            cfg: opts.cfg,
+            accountId: opts.accountId,
+            channelRuntime,
+            log,
+            errLog,
+          });
+        } catch (e) {
+          errLog(`taidesk process inbound: ${String(e)}`);
+        }
+      })();
+    },
+    onClose: () => {
+      log(`taidesk mqtt close account=${opts.accountId}`);
+    },
+    onError: (err) => {
+      errLog(`taidesk mqtt error: ${err.message}`);
+    },
+  });
+
+  return conn;
+}

package/src/mqtt/taidesk-mqtt-client.ts

@@ -0,0 +1,77 @@
+import mqtt from "mqtt";
+
+/** Taidesk 控制台常用 https://host/ws，mqtt.js WebSocket 需 wss:// */
+export function normalizeMqttConnectUrl(mqttUrl: string): string {
+  if (mqttUrl.startsWith("https://")) {
+    return `wss://${mqttUrl.slice("https://".length)}`;
+  }
+  if (mqttUrl.startsWith("http://")) {
+    return `ws://${mqttUrl.slice("http://".length)}`;
+  }
+  return mqttUrl;
+}
+
+export type TaideskMqttClientOptions = {
+  /** 例如 mqtt://、mqtts://、ws://、wss://（MQTT over WebSocket）；https/http 会规范为 wss/ws */
+  mqttUrl: string;
+  /** 订阅 topic：`/open/{agentId}` */
+  agentId: string;
+  mqttUsername?: string;
+  mqttPassword?: string;
+  clientId?: string;
+  onMessage: (topic: string, payloadUtf8: string) => void;
+  onConnect?: () => void;
+  onClose?: () => void;
+  onError?: (err: Error) => void;
+  abortSignal?: AbortSignal;
+};
+
+/**
+ * Taidesk 入站：MQTT 订阅 `/open/{agentId}`。
+ * 重连由 mqtt.js 内置 `reconnectPeriod` 处理。
+ */
+export function createTaideskMqttConnection(opts: TaideskMqttClientOptions): { close: () => void } {
+  const topic = `/open/${opts.agentId}`;
+  const connectUrl = normalizeMqttConnectUrl(opts.mqttUrl);
+  const client = mqtt.connect(connectUrl, {
+    username: opts.mqttUsername,
+    password: opts.mqttPassword,
+    clientId: opts.clientId ?? `openclaw-taidesk-${Date.now()}`,
+    reconnectPeriod: 5_000,
+    connectTimeout: 30_000,
+  });
+
+  const onAbort = (): void => {
+    client.end(true);
+  };
+  opts.abortSignal?.addEventListener("abort", onAbort);
+
+  client.on("connect", () => {
+    client.subscribe(topic, { qos: 0 }, (err) => {
+      if (err) {
+        opts.onError?.(err);
+        return;
+      }
+      opts.onConnect?.();
+    });
+  });
+
+  client.on("message", (t, payload) => {
+    opts.onMessage(t, payload.toString("utf8"));
+  });
+
+  client.on("error", (err) => {
+    opts.onError?.(err);
+  });
+
+  client.on("close", () => {
+    opts.onClose?.();
+  });
+
+  return {
+    close: () => {
+      opts.abortSignal?.removeEventListener("abort", onAbort);
+      client.end(true);
+    },
+  };
+}

package/src/persistence-store.ts

@@ -0,0 +1,5 @@
+/**
+ * 预留：会话游标 / 持久化（多实例时需 Redis 等）。
+ * 首期仅占位，避免与微信 sync-buf 强绑定。
+ */
+export const persistenceNamespace = "taidesk";

package/src/runtime.ts

@@ -0,0 +1,41 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";
+
+let pluginRuntime: PluginRuntime | null = null;
+
+export function setTaideskRuntime(next: PluginRuntime): void {
+  pluginRuntime = next;
+}
+
+export function getTaideskRuntime(): PluginRuntime {
+  if (!pluginRuntime) {
+    throw new Error("Taidesk runtime not initialized");
+  }
+  return pluginRuntime;
+}
+
+const WAIT_INTERVAL_MS = 100;
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+export async function waitForTaideskRuntime(timeoutMs = DEFAULT_TIMEOUT_MS): Promise<PluginRuntime> {
+  const start = Date.now();
+  while (!pluginRuntime) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error("Taidesk runtime initialization timeout");
+    }
+    await new Promise((resolve) => setTimeout(resolve, WAIT_INTERVAL_MS));
+  }
+  return pluginRuntime;
+}
+
+export type TaideskChannelRuntime = PluginRuntime["channel"];
+
+export async function resolveTaideskChannelRuntime(params: {
+  channelRuntime?: TaideskChannelRuntime;
+  waitTimeoutMs?: number;
+}): Promise<TaideskChannelRuntime> {
+  if (params.channelRuntime) {
+    return params.channelRuntime;
+  }
+  const pr = await waitForTaideskRuntime(params.waitTimeoutMs ?? DEFAULT_TIMEOUT_MS);
+  return pr.channel;
+}

package/src/types.ts

@@ -0,0 +1,29 @@
+/**
+ * Taidesk ↔ 插件入站载荷（MQTT JSON，见 docs/TAIDESK-WS-CONTRACT.zh-CN.md）。
+ */
+export type TaideskInboundEvent = {
+  type: string;
+  eventId: string;
+  conversationId: string;
+  tenantId?: string;
+  userId: string;
+  text?: string;
+  timestamp: number;
+};
+
+export type TaideskAccountConfig = {
+  enabled?: boolean;
+  name?: string;
+  /** MQTT Broker，如 mqtts://host:8883、wss://host/mqtt；https:// 会在连接前规范为 wss:// */
+  mqttUrl: string;
+  /** 订阅 topic `/open/{agentId}` */
+  agentId: string;
+  /** 出站 Webhook 完整 URL；可用 `{id}` 占位，发送前替换为 agentId */
+  webhook: string;
+  apiKey: string;
+  mqttUsername?: string;
+  mqttPassword?: string;
+  mqttClientId?: string;
+  /** HTTP 出站 Bearer；若未设 mqttPassword 也可作 MQTT 密码 */
+  token?: string;
+};