@thclouds/openclaw-channel-taidesk 0.1.2 → 0.1.3

package/README.md

@@ -2,11 +2,9 @@
 
 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)
+- [MQTT / HTTP 契约与字段说明](docs/TAIDESK-WS-CONTRACT.zh-CN.md)
 
 ## 依赖
 
@@ -35,13 +33,43 @@ OpenClaw 渠道插件：**Taidesk MQTT 入站**（订阅 **`/open` + agentId**
 }
 ```
 
+**MQTT 鉴权**：未配置 `mqttUsername` 且未显式配置 `mqttPassword` 时为**匿名连接**（`apiKey` 仅用于 HTTP 出站，不会当作 MQTT 密码）。若 Broker 要求用户名/密码，请配置 `mqttUsername` 或 `mqttPassword`。
+
 订阅 topic：**`/open` + `agentId`**（例：`agentId` 为 `2014147198056767490` 时 topic 为 `/open2014147198056767490`）。入站 JSON 见契约文档中的 `agent_msg` 示例。
 
+## 本地 MQTT 自测（连接 + 可选触发下行）
+
+联调脚本位于 **`tests/live/taidesk-mqtt-smoke.ts`**（与 `tests/unit` 同属 `tests/`，目录说明见 [`tests/README.md`](tests/README.md)）。脚本会：
+
+1. 用与线上一致的参数连接 MQTT、订阅 `/open`+`agentId`；
+2. 若设置 **`TAIDESK_TEST_BEARER`**，在连接成功后 **GET** `TAIDESK_TEST_GET_URL`（默认  
+   `https://demo.devlake.thclouds.com:17443/api/app-console/ai/v1/agent/<agentId>/test`），由控制台经 MQTT 下发测试消息，脚本打印收到的 payload；
+3. 默认运行 **120s**（`TAIDESK_SMOKE_MS` 可改）。
+
+仅连 MQTT、不调用 HTTP（例如只等自然消息）：
+
+```bash
+npm run smoke:mqtt
+```
+
+连接 + 触发测试接口（Bearer **不要提交到仓库**，只在本地或 CI 密钥里配置）：
+
+```powershell
+$env:TAIDESK_MQTT_TLS_INSECURE='1'
+$env:TAIDESK_TEST_BEARER='你的BearerToken'
+npm run smoke:mqtt
+```
+
+若 Node 报错 **`certificate has expired`**，说明 HTTPS/MQTT 的 TLS 证书已过期；`TAIDESK_MQTT_TLS_INSECURE=1` 会同时作用于 **MQTT 与上述测试 GET**（**仅开发**）。OpenClaw 网关跑插件时也可设该变量；**根治**请更换服务端证书。
+
+可用 `TAIDESK_MQTT_URL`、`TAIDESK_AGENT_ID`、`TAIDESK_TEST_GET_URL` 等覆盖；`TAIDESK_SKIP_HTTP_TEST=1` 只测 MQTT、不发 GET。
+
 ## 脚本
 
 | 命令 | 说明 |
 |------|------|
 | `npm run type-check` | TypeScript 检查 |
+| `npm run smoke:mqtt` | 实连 MQTT，收消息冒烟 |
 | `npm test` | Vitest 单元测试 |
 
 ## 许可

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thclouds/openclaw-channel-taidesk",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "OpenClaw Taidesk channel plugin (MQTT inbound + HTTP outbound)",
   "license": "MIT",
   "author": "thclouds",
@@ -17,6 +17,7 @@
     "type-check": "tsc -p tsconfig.json --noEmit",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
+    "smoke:mqtt": "tsx tests/live/taidesk-mqtt-smoke.ts",
     "prepublishOnly": "npm run typecheck && npm test"
   },
   "publishConfig": {
@@ -36,6 +37,7 @@
   "devDependencies": {
     "@types/node": "^22.10.0",
     "openclaw": "2026.3.23",
+    "tsx": "^4.19.0",
     "typescript": "^5.8.0",
     "vitest": "^3.1.0"
   },

package/src/api/api.ts

@@ -10,12 +10,12 @@ function resolveTaideskWebhookUrl(config: TaideskAccountConfig): string {
 export async function sendTaideskText(params: {
   cfg: OpenClawConfig;
   accountId: string;
-  conversationId: string;
+  sessionId: 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 { cfg, accountId, sessionId, text } = params;
   const log = params.log ?? (() => {});
   const errLog = params.errLog ?? log;
   const { config } = resolveTaideskAccount(cfg, accountId);
@@ -28,7 +28,7 @@ export async function sendTaideskText(params: {
     headers.Authorization = `Bearer ${bearer}`;
   }
   const body = JSON.stringify({
-    conversationId,
+    sessionId,
     text,
   });
   log(`taidesk outbound POST ${url.toString()} len=${body.length}`);

package/src/channel.ts

@@ -117,7 +117,7 @@ export const taideskPlugin: ChannelPlugin<ResolvedTaideskAccount> = {
     resolveTarget: ({ to }: { to?: string }) => {
       const trimmed = to?.trim();
       if (!trimmed) {
-        return { ok: false as const, error: new Error("taidesk: --to <conversationId> required") };
+        return { ok: false as const, error: new Error("taidesk: --to <sessionId> required") };
       }
       return { ok: true as const, to: trimmed };
     },
@@ -127,7 +127,7 @@ export const taideskPlugin: ChannelPlugin<ResolvedTaideskAccount> = {
       const result = await sendTaideskText({
         cfg,
         accountId: id,
-        conversationId: to,
+        sessionId: to,
         text,
         log: (m) => {
           console.info(`[taidesk] ${m}`);

package/src/inbound-handler.ts

@@ -1,5 +1,11 @@
+import { createHash } from "node:crypto";
+
 import type { TaideskInboundEvent } from "./types.js";
 
+function stableEventIdFromRawPayload(raw: string): string {
+  return createHash("sha256").update(raw, "utf8").digest("hex").slice(0, 32);
+}
+
 function parseTaideskCreateTimeMs(createTime: string): number {
   if (!createTime.trim()) {
     return Date.now();
@@ -11,9 +17,9 @@ function parseTaideskCreateTimeMs(createTime: string): number {
 
 /**
  * Taidesk MQTT 载荷：`event: agent_msg`，`data` 为业务体。
- * @see 用户约定示例
+ * 完整形态含 `data.id` / `sessionId` / `userId`；根级发送方回退为 **`agentId`**（兼容旧版根级 `userId`）；精简形态仅根级 `agentId` 作会话路由，不作发送方。
  */
-function parseAgentMsgEnvelope(v: Record<string, unknown>): TaideskInboundEvent | null {
+function parseAgentMsgEnvelope(v: Record<string, unknown>, raw: string): TaideskInboundEvent | null {
   if (v.event !== "agent_msg") {
     return null;
   }
@@ -22,9 +28,32 @@ function parseAgentMsgEnvelope(v: Record<string, unknown>): TaideskInboundEvent
     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 idStr = d.id != null ? String(d.id).trim() : "";
+  const eventId = idStr !== "" ? idStr : stableEventIdFromRawPayload(raw);
+
+  const sessionStr = d.sessionId != null ? String(d.sessionId).trim() : "";
+  const rootAgent =
+    v.agentId != null && String(v.agentId).trim() !== "" ? String(v.agentId).trim() : "";
+  /** 会话维度：优先 `data.sessionId`，否则根级 `agentId`（控制台精简推送无 sessionId 时）。 */
+  const sessionId = sessionStr !== "" ? sessionStr : rootAgent;
+  if (!sessionId) {
+    return null;
+  }
+
+  const fromData = d.userId != null ? String(d.userId).trim() : "";
+  /** 有 `data.sessionId` 时根级 `agentId` 表示发送方回退；无 `data.sessionId` 时根级 `agentId` 已用于会话路由，发送方仅认根级 `userId`（兼容）。 */
+  let fromRoot = "";
+  if (sessionStr !== "") {
+    const rootAgentId =
+      v.agentId != null && String(v.agentId).trim() !== "" ? String(v.agentId).trim() : "";
+    const rootUserId =
+      typeof v.userId === "string" && v.userId.trim() !== "" ? v.userId.trim() : "";
+    fromRoot = rootAgentId !== "" ? rootAgentId : rootUserId;
+  } else {
+    fromRoot = typeof v.userId === "string" && v.userId.trim() !== "" ? v.userId.trim() : "";
+  }
+  const userId = fromData !== "" ? fromData : fromRoot !== "" ? fromRoot : "0";
+
   const content = d.content;
   let text = "";
   if (content && typeof content === "object") {
@@ -35,14 +64,11 @@ function parseAgentMsgEnvelope(v: Record<string, unknown>): TaideskInboundEvent
   }
   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;
-  }
+  const timestamp = createTime ? parseTaideskCreateTimeMs(createTime) : Date.now();
   return {
     type: "agent_msg",
     eventId,
-    conversationId: sessionId,
+    sessionId,
     tenantId,
     userId,
     text,
@@ -50,23 +76,29 @@ function parseAgentMsgEnvelope(v: Record<string, unknown>): TaideskInboundEvent
   };
 }
 
-/** 兼容旧版扁平 JSON（测试/迁移） */
+/** 兼容旧版扁平 JSON（测试/迁移）；会话字段优先 `sessionId`，否则 `conversationId`。 */
 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 sessionIdFromSession =
+    typeof v.sessionId === "string" && v.sessionId.trim() !== "" ? v.sessionId.trim() : "";
+  const sessionIdFromConv =
+    typeof v.conversationId === "string" && v.conversationId.trim() !== ""
+      ? v.conversationId.trim()
+      : "";
+  const sessionId = sessionIdFromSession !== "" ? sessionIdFromSession : sessionIdFromConv;
   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) {
+  if (!eventId || !sessionId || !userId) {
     return null;
   }
   return {
     type: typeof v.type === "string" ? v.type : "message",
     eventId,
-    conversationId,
+    sessionId,
     tenantId: typeof v.tenantId === "string" ? v.tenantId : undefined,
     userId,
     text,
@@ -77,7 +109,7 @@ function parseLegacyFlat(v: Record<string, unknown>): TaideskInboundEvent | null
 export function parseTaideskInboundJson(raw: string): TaideskInboundEvent | null {
   try {
     const v = JSON.parse(raw) as Record<string, unknown>;
-    const agent = parseAgentMsgEnvelope(v);
+    const agent = parseAgentMsgEnvelope(v, raw);
     if (agent) {
       return agent;
     }

package/src/messaging/process-message.ts

@@ -21,14 +21,14 @@ export async function processTaideskInbound(params: {
   const ctx: MsgContext = {
     Body: event.text ?? "",
     From: event.userId,
-    To: event.conversationId,
+    To: event.sessionId,
     MessageSid: event.eventId,
     Timestamp: event.timestamp,
     OriginatingChannel: "taidesk",
-    OriginatingTo: event.conversationId,
+    OriginatingTo: event.sessionId,
     AccountId: accountId,
     ChatType: "direct",
-    NativeChannelId: event.conversationId,
+    NativeChannelId: event.sessionId,
     CommandAuthorized: true,
   };
 
@@ -36,7 +36,7 @@ export async function processTaideskInbound(params: {
     cfg,
     channel: "taidesk",
     accountId,
-    peer: { kind: "direct", id: event.conversationId },
+    peer: { kind: "direct", id: event.sessionId },
   });
 
   ctx.SessionKey = route.sessionKey;
@@ -54,7 +54,7 @@ export async function processTaideskInbound(params: {
     updateLastRoute: {
       sessionKey: route.mainSessionKey,
       channel: "taidesk",
-      to: event.conversationId,
+      to: event.sessionId,
       accountId,
     },
     onRecordError: (err) => errLog(`recordInboundSession: ${String(err)}`),
@@ -78,7 +78,7 @@ export async function processTaideskInbound(params: {
         await sendTaideskText({
           cfg,
           accountId,
-          conversationId: event.conversationId,
+          sessionId: event.sessionId,
           text,
           log,
           errLog,

package/src/monitor/monitor.ts

@@ -3,7 +3,10 @@ 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 {
+  buildMqttConnectAuth,
+  createTaideskMqttConnection,
+} from "../mqtt/taidesk-mqtt-client.js";
 import { processTaideskInbound } from "../messaging/process-message.js";
 import { resolveTaideskChannelRuntime } from "../runtime.js";
 import type { TaideskAccountConfig } from "../types.js";
@@ -24,13 +27,16 @@ export type MonitorTaideskOpts = {
 export function monitorTaideskProvider(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 mqttAuth = buildMqttConnectAuth(opts.accountConfig);
+  log(
+    `taidesk mqtt connecting account=${opts.accountId} topic=/open${opts.accountConfig.agentId} auth=${mqttAuth.mode}`,
+  );
 
   const conn = createTaideskMqttConnection({
     mqttUrl: opts.accountConfig.mqttUrl,
     agentId: opts.accountConfig.agentId,
-    mqttUsername: opts.accountConfig.mqttUsername,
-    mqttPassword: pwd,
+    mqttUsername: mqttAuth.username,
+    mqttPassword: mqttAuth.password,
     clientId: opts.accountConfig.mqttClientId,
     abortSignal: opts.abortSignal,
     onConnect: () => {

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

@@ -1,4 +1,46 @@
-import mqtt from "mqtt";
+import mqtt, { type IClientOptions } from "mqtt";
+
+export type MqttConnectAuthMode = "none" | "password-only" | "user-pass";
+
+export type MqttConnectAuth = {
+  mode: MqttConnectAuthMode;
+  username?: string;
+  password?: string;
+};
+
+/**
+ * 从账号配置推导 MQTT CONNECT 鉴权。
+ * 多数 Taidesk/DevLake Broker 为**匿名**：不要把 HTTP 的 apiKey 默认当作 MQTT 密码，否则会被服务端断开。
+ * - 未配置 mqttUsername 且未显式配置 mqttPassword → 不传用户名/密码
+ * - 配置了 mqttUsername → 密码为 mqttPassword ?? apiKey ?? token
+ * - 仅显式配置 mqttPassword（非空）且无 username → 仅密码（password-only）
+ * - mqttPassword 为空字符串 → 不传密码（可与 mqttUsername 组合表示「只要用户名」）
+ */
+export function buildMqttConnectAuth(account: {
+  mqttUsername?: string;
+  mqttPassword?: string;
+  apiKey?: string;
+  token?: string;
+}): MqttConnectAuth {
+  const user = account.mqttUsername?.trim();
+  const explicitPwd = account.mqttPassword;
+
+  if (explicitPwd !== undefined) {
+    if (explicitPwd === "") {
+      if (user) return { mode: "user-pass", username: user };
+      return { mode: "none" };
+    }
+    if (user) return { mode: "user-pass", username: user, password: explicitPwd };
+    return { mode: "password-only", password: explicitPwd };
+  }
+
+  if (user) {
+    const password = account.apiKey ?? account.token ?? "";
+    return { mode: "user-pass", username: user, password };
+  }
+
+  return { mode: "none" };
+}
 
 /** Taidesk 控制台常用 https://host/ws，mqtt.js WebSocket 需 wss:// */
 export function normalizeMqttConnectUrl(mqttUrl: string): string {
@@ -16,6 +58,7 @@ export type TaideskMqttClientOptions = {
   mqttUrl: string;
   /** 订阅 topic：`/open` + agentId（与 Taidesk Broker 一致，中间无 `/`） */
   agentId: string;
+  /** 已由 buildMqttConnectAuth 解析；未设置时不要传 apiKey 作为默认密码 */
   mqttUsername?: string;
   mqttPassword?: string;
   clientId?: string;
@@ -24,6 +67,11 @@ export type TaideskMqttClientOptions = {
   onClose?: () => void;
   onError?: (err: Error) => void;
   abortSignal?: AbortSignal;
+  /**
+   * 默认遵循 Node TLS 校验。设为 `false` 仅用于自签/过期证书的开发环境（勿用于生产）。
+   * 也可设置环境变量 `TAIDESK_MQTT_TLS_INSECURE=1`（在 options 未传时生效）。
+   */
+  rejectUnauthorized?: boolean;
 };
 
 /**
@@ -33,13 +81,25 @@ export type TaideskMqttClientOptions = {
 export function createTaideskMqttConnection(opts: TaideskMqttClientOptions): { close: () => void } {
   const topic = `/open${opts.agentId.trim()}`;
   const connectUrl = normalizeMqttConnectUrl(opts.mqttUrl);
-  const client = mqtt.connect(connectUrl, {
-    username: opts.mqttUsername,
-    password: opts.mqttPassword,
+  const clientOpts: IClientOptions = {
+    protocolVersion: 4,
+    clean: true,
     clientId: opts.clientId ?? `openclaw-taidesk-${Date.now()}`,
     reconnectPeriod: 5_000,
     connectTimeout: 30_000,
-  });
+  };
+  if (opts.mqttUsername !== undefined && opts.mqttUsername !== "") {
+    clientOpts.username = opts.mqttUsername;
+  }
+  if (opts.mqttPassword !== undefined && opts.mqttPassword !== "") {
+    clientOpts.password = opts.mqttPassword;
+  }
+  const tlsInsecure =
+    opts.rejectUnauthorized === false || process.env.TAIDESK_MQTT_TLS_INSECURE === "1";
+  if (tlsInsecure) {
+    clientOpts.rejectUnauthorized = false;
+  }
+  const client = mqtt.connect(connectUrl, clientOpts);
 
   const onAbort = (): void => {
     client.end(true);
@@ -49,7 +109,7 @@ export function createTaideskMqttConnection(opts: TaideskMqttClientOptions): { c
   client.on("connect", () => {
     client.subscribe(topic, { qos: 0 }, (err) => {
       if (err) {
-        opts.onError?.(err);
+        opts.onError?.(err instanceof Error ? err : new Error(String(err)));
         return;
       }
       opts.onConnect?.();

package/src/types.ts

@@ -4,7 +4,8 @@
 export type TaideskInboundEvent = {
   type: string;
   eventId: string;
-  conversationId: string;
+  /** Taidesk 会话：`data.sessionId`；无则根级 `agentId`（精简推送）。用于 peer 路由与出站 HTTP。 */
+  sessionId: string;
   tenantId?: string;
   userId: string;
   text?: string;
@@ -21,9 +22,11 @@ export type TaideskAccountConfig = {
   /** 出站 Webhook 完整 URL；可用 `{id}` 占位，发送前替换为 agentId */
   webhook: string;
   apiKey: string;
+  /** 若设置：MQTT 密码为 mqttPassword ?? apiKey ?? token */
   mqttUsername?: string;
+  /** 显式 MQTT 密码；与 mqttUsername 均未配置时**不会**把 apiKey 当作 MQTT 密码（匿名连接） */
   mqttPassword?: string;
   mqttClientId?: string;
-  /** HTTP 出站 Bearer；若未设 mqttPassword 也可作 MQTT 密码 */
+  /** HTTP 出站 Bearer；在已配置 mqttUsername 时可作为 MQTT 密码后备 */
   token?: string;
 };