palz-connector 0.0.1

package/openclaw.plugin.json

@@ -0,0 +1,14 @@
+{
+  "id": "palz-connector",
+  "name": "Palz Connector Channel",
+  "version": "0.0.1",
+  "description": "Palz IM 接入 OpenClaw",
+  "channels": ["palz-connector"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": { "type": "boolean", "default": true }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "palz-connector",
+  "version": "0.0.1",
+  "description": "Palz IM 接入 OpenClaw",
+  "main": "plugin.ts",
+  "type": "module",
+  "scripts": {
+    "build": "echo 'No build needed - jiti loads TS at runtime'"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "openclaw": {
+    "extensions": ["./plugin.ts"],
+    "channels": ["palz-connector"],
+    "installDependencies": true
+  }
+}

package/palz-connector.config.json

@@ -0,0 +1,6 @@
+{
+  "enabled": true,
+  "streamUrl": "ws://14.103.148.99:9090/ws/bot",
+  "apiBaseUrl": "http://14.103.148.99:9090/api",
+  "sessionTimeout": 1800000
+}

package/plugin.ts

@@ -0,0 +1,1152 @@
+/**
+ * Palz Connector Channel Plugin for OpenClaw
+ *
+ * Palz IM 接入 OpenClaw。
+ * 通过 WebSocket 接收 IM 消息，通过 Gateway WebSocket 获取 AI 回复，再通过 REST API 发送回 IM。
+ */
+
+import WebSocket from 'ws';
+import crypto from 'crypto';
+import fs, { readFileSync } from 'fs';
+import path, { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+
+// ============ 设备身份认证 (Ed25519) ============
+
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+
+function _derivePublicKeyRaw(publicKeyPem: string): Buffer {
+  const spki = crypto.createPublicKey(publicKeyPem).export({ type: 'spki', format: 'der' });
+  if (spki.length === ED25519_SPKI_PREFIX.length + 32 &&
+      spki.subarray(0, ED25519_SPKI_PREFIX.length).equals(ED25519_SPKI_PREFIX)) {
+    return spki.subarray(ED25519_SPKI_PREFIX.length);
+  }
+  return spki;
+}
+
+function _fingerprintPublicKey(publicKeyPem: string): string {
+  return crypto.createHash('sha256').update(_derivePublicKeyRaw(publicKeyPem)).digest('hex');
+}
+
+function _base64UrlEncode(buf: Buffer): string {
+  return buf.toString('base64').replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/g, '');
+}
+
+function _loadOrCreateDeviceIdentity(identityPath: string): { deviceId: string; publicKeyPem: string; privateKeyPem: string } {
+  try {
+    if (fs.existsSync(identityPath)) {
+      const parsed = JSON.parse(fs.readFileSync(identityPath, 'utf8'));
+      if (parsed?.version === 1 && parsed.deviceId && parsed.publicKeyPem && parsed.privateKeyPem) {
+        return parsed;
+      }
+    }
+  } catch { /* regenerate */ }
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+  const publicKeyPem = publicKey.export({ type: 'spki', format: 'pem' }).toString();
+  const privateKeyPem = privateKey.export({ type: 'pkcs8', format: 'pem' }).toString();
+  const identity = {
+    version: 1,
+    deviceId: _fingerprintPublicKey(publicKeyPem),
+    publicKeyPem,
+    privateKeyPem,
+    createdAtMs: Date.now(),
+  };
+  fs.mkdirSync(path.dirname(identityPath), { recursive: true });
+  fs.writeFileSync(identityPath, JSON.stringify(identity, null, 2) + '\n', { mode: 0o600 });
+  return identity;
+}
+
+function _buildDeviceAuth(
+  identity: { deviceId: string; publicKeyPem: string; privateKeyPem: string },
+  params: { clientId: string; clientMode: string; role: string; scopes: string[]; token: string; nonce: string },
+) {
+  const signedAt = Date.now();
+  const payload = [
+    'v2', identity.deviceId, params.clientId, params.clientMode,
+    params.role, params.scopes.join(','), String(signedAt),
+    params.token || '', params.nonce,
+  ].join('|');
+  const privateKey = crypto.createPrivateKey(identity.privateKeyPem);
+  const signature = _base64UrlEncode(crypto.sign(null, Buffer.from(payload, 'utf8'), privateKey) as unknown as Buffer);
+  const publicKeyB64Url = _base64UrlEncode(_derivePublicKeyRaw(identity.publicKeyPem));
+  return { id: identity.deviceId, publicKey: publicKeyB64Url, signature, signedAt, nonce: params.nonce };
+}
+
+// ============ 类型定义 ============
+
+type TextContentPart = { type: 'text'; text: string };
+type ImageUrlContentPart = { type: 'image_url'; image_url: { url: string; detail?: string } };
+type ContentPart = TextContentPart | ImageUrlContentPart;
+type OpenAIContent = string | ContentPart[];
+
+interface GatewayAttachment {
+  type: 'image';
+  mimeType: string;
+  content: string;
+}
+
+function extractPlainText(content: OpenAIContent): string {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .filter((p): p is TextContentPart => p.type === 'text')
+      .map(p => p.text)
+      .join('');
+  }
+  return '';
+}
+
+async function resolveImageAttachment(url: string, log?: any): Promise<GatewayAttachment | null> {
+  const dataUrlMatch = url.match(/^data:(image\/[^;]+);base64,(.+)$/);
+  if (dataUrlMatch) {
+    return { type: 'image', mimeType: dataUrlMatch[1], content: dataUrlMatch[2] };
+  }
+
+  if (url.startsWith('http://') || url.startsWith('https://')) {
+    log?.info?.(`[Palz][Attachment] 正在下载图片: ${url.slice(0, 200)}`);
+    try {
+      const response = await fetch(url);
+      if (!response.ok) {
+        log?.error?.(`[Palz][Attachment] 图片下载失败: ${response.status}`);
+        return null;
+      }
+      const contentType = response.headers.get('content-type') || 'image/png';
+      const mimeType = contentType.split(';')[0].trim();
+      const buffer = Buffer.from(await response.arrayBuffer());
+      return { type: 'image', mimeType, content: buffer.toString('base64') };
+    } catch (err: any) {
+      log?.error?.(`[Palz][Attachment] 图片下载异常: ${err.message}`);
+      return null;
+    }
+  }
+
+  log?.warn?.(`[Palz][Attachment] 不支持的图片 URL scheme: ${url.slice(0, 100)}`);
+  return null;
+}
+
+async function extractAttachments(content: OpenAIContent, log?: any): Promise<GatewayAttachment[]> {
+  if (typeof content === 'string' || !Array.isArray(content)) return [];
+
+  const attachments: GatewayAttachment[] = [];
+  for (const part of content) {
+    if (part.type === 'image_url' && part.image_url?.url) {
+      const attachment = await resolveImageAttachment(part.image_url.url, log);
+      if (attachment) attachments.push(attachment);
+    }
+  }
+  return attachments;
+}
+
+// ============ 常量 & 配置 ============
+
+export const id = 'palz-connector';
+
+const FALLBACK_ACCOUNT_ID = '__default__';
+
+const NEW_SESSION_COMMANDS = ['/new', '/reset', '/clear', '新会话', '重新开始', '清空对话'];
+
+let runtime: any = null;
+let pluginLogger: any = null;
+let _imConfig: any = null;
+
+function getPluginDir(): string {
+  try {
+    return dirname(fileURLToPath(import.meta.url));
+  } catch {
+    return __dirname;
+  }
+}
+
+function readGatewayToken(log?: any): string {
+  if (process.env.OPENCLAW_GATEWAY_TOKEN) {
+    log?.info?.('[Palz][Config] gatewayToken 从环境变量 OPENCLAW_GATEWAY_TOKEN 读取');
+    return process.env.OPENCLAW_GATEWAY_TOKEN;
+  }
+
+  log?.warn?.('[Palz][Config] gatewayToken 未配置（环境变量 OPENCLAW_GATEWAY_TOKEN 未设置）');
+  return '';
+}
+
+function loadIMConfig(log?: any, forceReload = false): any {
+  if (_imConfig && !forceReload) return _imConfig;
+
+  const configPath = resolve(getPluginDir(), 'palz-connector.config.json');
+  try {
+    _imConfig = JSON.parse(readFileSync(configPath, 'utf-8'));
+    log?.info?.(`[Palz][Config] 配置文件已加载: ${configPath}`);
+  } catch (err: any) {
+    if (!_imConfig) {
+      log?.error?.(`[Palz][Config] 配置加载失败(${configPath}): ${err.message}，使用默认配置`);
+      _imConfig = { enabled: false };
+    }
+  }
+  if (!process.env.botID) {
+    log?.error?.('[Palz][Config] 环境变量 botID 未设置，botId 将为空，插件将无法正常启动');
+  }
+  _imConfig.botId = process.env.botID || '';
+  _imConfig.gatewayToken = readGatewayToken(log);
+
+  const missing: string[] = [];
+  if (!_imConfig.botId) missing.push('botID(环境变量)');
+  if (!_imConfig.streamUrl) missing.push('streamUrl(配置文件)');
+  if (!_imConfig.apiBaseUrl) missing.push('apiBaseUrl(配置文件)');
+  if (missing.length > 0) {
+    log?.error?.(`[Palz][Config] 关键配置缺失: ${missing.join(', ')}，插件将无法正常工作`);
+  }
+
+  return _imConfig;
+}
+
+function getRuntime(): any {
+  if (!runtime) throw new Error('Palz runtime not initialized');
+  return runtime;
+}
+
+// ============ Session 管理 ============
+
+interface UserSession {
+  lastActivity: number;
+  sessionId: string;
+}
+
+const userSessions = new Map<string, UserSession>();
+
+const processedMessages = new Map<string, number>();
+const MESSAGE_DEDUP_TTL = 5 * 60 * 1000;
+
+function cleanupProcessedMessages(): void {
+  const now = Date.now();
+  for (const [msgId, ts] of processedMessages) {
+    if (now - ts > MESSAGE_DEDUP_TTL) processedMessages.delete(msgId);
+  }
+}
+
+function dedup(msgId: string): boolean {
+  if (!msgId) return false;
+  if (processedMessages.has(msgId)) return true;
+  processedMessages.set(msgId, Date.now());
+  if (processedMessages.size >= 100) cleanupProcessedMessages();
+  return false;
+}
+
+const userLocks = new Map<string, Promise<void>>();
+
+function withUserLock(senderId: string, fn: () => Promise<void>): void {
+  const prev = userLocks.get(senderId) ?? Promise.resolve();
+  const next = prev.then(fn, fn);
+  userLocks.set(senderId, next);
+  next.finally(() => {
+    if (userLocks.get(senderId) === next) userLocks.delete(senderId);
+  });
+}
+
+function isNewSessionCommand(text: string): boolean {
+  const trimmed = text.trim().toLowerCase();
+  return NEW_SESSION_COMMANDS.some(cmd => trimmed === cmd.toLowerCase());
+}
+
+function getSessionKey(
+  senderId: string,
+  conversationId: string,
+  forceNew: boolean,
+  log?: any,
+): { sessionKey: string; isNew: boolean } {
+  const sessionId = `palz:${senderId}:${conversationId}`;
+  const now = Date.now();
+
+  if (forceNew) {
+    userSessions.set(senderId, { lastActivity: now, sessionId });
+    log?.info?.(`[Palz][Session] 用户主动开启新会话: ${senderId}, conversation=${conversationId}`);
+    return { sessionKey: sessionId, isNew: true };
+  }
+
+  const existing = userSessions.get(senderId);
+  if (existing && existing.sessionId === sessionId) {
+    existing.lastActivity = now;
+    return { sessionKey: sessionId, isNew: false };
+  }
+
+  userSessions.set(senderId, { lastActivity: now, sessionId });
+  log?.info?.(`[Palz][Session] 新会话: ${senderId}, conversation=${conversationId}`);
+  return { sessionKey: sessionId, isNew: !existing };
+}
+
+// ============ Gateway WebSocket 客户端 ============
+
+const GW_WS_TIMEOUT = 120_000;
+
+interface GwWsStreamHandler {
+  reqId: string;
+  runId: string | null;
+  onChunk: (text: string) => void;
+  onDone: () => void;
+  onError: (err: Error) => void;
+}
+
+let gwWs: WebSocket | null = null;
+let gwWsReady = false;
+let gwWsConnecting = false;
+let gwWsReqSeq = 0;
+const gwWsActiveStreams = new Map<string, GwWsStreamHandler>();
+let gwWsPingInterval: ReturnType<typeof setInterval> | null = null;
+let gwWsClosed = false;
+
+function connectToGatewayWs(gatewayAuth: string, log?: any): Promise<void> {
+  if (gwWsReady) return Promise.resolve();
+  if (gwWsConnecting) {
+    return new Promise<void>((resolve, reject) => {
+      const check = setInterval(() => {
+        if (gwWsReady) { clearInterval(check); resolve(); }
+        else if (!gwWsConnecting) { clearInterval(check); reject(new Error('Gateway WS 连接失败')); }
+      }, 100);
+      setTimeout(() => { clearInterval(check); reject(new Error('等待 Gateway WS 连接超时')); }, 20_000);
+    });
+  }
+  gwWsConnecting = true;
+  gwWsClosed = false;
+
+  const rt = getRuntime();
+  const port = rt.gateway?.port || 18789;
+  const wsUrl = `ws://127.0.0.1:${port}`;
+
+  return new Promise<void>((resolveConnect, rejectConnect) => {
+    log?.info?.(`[Palz][GwWS] 正在连接 Gateway WebSocket: ${wsUrl}`);
+    const ws = new WebSocket(wsUrl);
+    gwWs = ws;
+
+    const connectTimeout = setTimeout(() => {
+      gwWsConnecting = false;
+      ws.close();
+      rejectConnect(new Error('Gateway WS 连接超时'));
+    }, 15_000);
+
+    ws.on('open', () => {
+      log?.info?.('[Palz][GwWS] WebSocket 已连接，等待 challenge...');
+    });
+
+    ws.on('message', (data: Buffer) => {
+      let frame: any;
+      try {
+        frame = JSON.parse(data.toString());
+      } catch {
+        log?.warn?.(`[Palz][GwWS] 无法解析帧: ${data.toString().slice(0, 200)}`);
+        return;
+      }
+
+      // 精简日志：streaming delta 只打 debug，其他事件打 info 摘要
+      if (frame.type === 'event' && frame.event === 'agent' && frame.payload?.stream === 'assistant') {
+        log?.debug?.(`[Palz][GwWS] <<< chunk delta, runId=${frame.payload?.runId}, len=${(frame.payload?.data?.delta || '').length}`);
+      } else if (frame.type === 'event' && frame.event === 'tick') {
+        // tick 心跳包静默
+      } else {
+        log?.info?.(`[Palz][GwWS] <<< ${frame.type}/${frame.event || frame.method || 'res'}: ${JSON.stringify(frame.payload || frame.error || {}).slice(0, 300)}`);
+      }
+
+      if (frame.type === 'event' && frame.event === 'connect.challenge') {
+        const nonce = frame.payload?.nonce ?? '';
+        log?.info?.(`[Palz][GwWS] 收到 challenge, nonce=${nonce.slice(0, 16)}...`);
+
+        const identityPath = resolve(getPluginDir(), 'device-identity.json');
+        const identity = _loadOrCreateDeviceIdentity(identityPath);
+        log?.info?.(`[Palz][GwWS] 设备身份: deviceId=${identity.deviceId.slice(0, 16)}...`);
+
+        const clientId = 'gateway-client';
+        const clientMode = 'backend';
+        const role = 'operator';
+        const scopes = ['operator.read', 'operator.write', 'operator.admin'];
+
+        const device = _buildDeviceAuth(identity, {
+          clientId, clientMode, role, scopes, token: gatewayAuth, nonce,
+        });
+
+        const connectReq = {
+          type: 'req',
+          id: `connect_${Date.now()}`,
+          method: 'connect',
+          params: {
+            minProtocol: 3,
+            maxProtocol: 3,
+            client: { id: clientId, version: '1.0.0', platform: process.platform, mode: clientMode },
+            role,
+            scopes,
+            device,
+            caps: ['tool-events'],
+            auth: { token: gatewayAuth },
+          },
+        };
+        log?.info?.('[Palz][GwWS] 发送 connect 请求 (device auth)');
+        ws.send(JSON.stringify(connectReq));
+        return;
+      }
+
+      if (frame.type === 'res') {
+        if (frame.payload?.type === 'hello-ok') {
+          clearTimeout(connectTimeout);
+          gwWsReady = true;
+          gwWsConnecting = false;
+          log?.info?.(`[Palz][GwWS] ✅ 握手成功, protocol=${frame.payload.protocol}`);
+
+          gwWsPingInterval = setInterval(() => {
+            if (gwWs?.readyState === WebSocket.OPEN) {
+              try { gwWs.ping(); } catch {}
+            }
+          }, 30_000);
+
+          resolveConnect();
+          return;
+        }
+
+        if (!frame.ok && !gwWsReady) {
+          clearTimeout(connectTimeout);
+          gwWsConnecting = false;
+          const errMsg = frame.error?.message || frame.error || JSON.stringify(frame);
+          log?.error?.(`[Palz][GwWS] ❌ 握手失败: ${errMsg}`);
+          ws.close();
+          rejectConnect(new Error(`Gateway WS 握手失败: ${errMsg}`));
+          return;
+        }
+
+        const handler = gwWsActiveStreams.get(frame.id);
+        if (handler) {
+          if (frame.ok) {
+            const runId = frame.payload?.runId;
+            if (runId) {
+              handler.runId = runId;
+              log?.info?.(`[Palz][GwWS] chat.send 已接受, reqId=${frame.id}, runId=${runId}`);
+            } else {
+              handler.onError(new Error('Gateway WS chat.send 响应缺少 runId'));
+            }
+          } else {
+            handler.onError(new Error(frame.error?.message || 'Gateway WS 请求失败'));
+          }
+        }
+        return;
+      }
+
+      if (frame.type === 'event' && gwWsReady) {
+        const payload = frame.payload;
+        const runId = payload?.runId;
+        if (!runId) return;
+
+        // 根据 runId 找到对应的 handler
+        let eventHandler: GwWsStreamHandler | null = null;
+        for (const h of gwWsActiveStreams.values()) {
+          if (h.runId && h.runId === runId) {
+            eventHandler = h;
+            break;
+          }
+        }
+        if (!eventHandler) return;
+
+        if (frame.event === 'agent' && payload?.stream === 'assistant') {
+          const delta = payload.data?.delta || '';
+          if (delta) {
+            eventHandler.onChunk(delta);
+          }
+        } else if (frame.event === 'agent' && payload?.stream === 'lifecycle') {
+          if (payload.data?.phase === 'end') {
+            log?.info?.(`[Palz][GwWS] lifecycle end, runId=${runId}`);
+            eventHandler.onDone();
+          }
+        }
+      }
+    });
+
+    ws.on('close', (code, reason) => {
+      const wasReady = gwWsReady;
+      gwWsReady = false;
+      gwWsConnecting = false;
+      gwWs = null;
+      clearTimeout(connectTimeout);
+      if (gwWsPingInterval) { clearInterval(gwWsPingInterval); gwWsPingInterval = null; }
+
+      for (const h of gwWsActiveStreams.values()) {
+        h.onError(new Error(`Gateway WS 连接断开 (code=${code})`));
+      }
+      gwWsActiveStreams.clear();
+
+      log?.warn?.(`[Palz][GwWS] 连接断开: code=${code}, reason=${reason?.toString()}, wasReady=${wasReady}`);
+      if (!wasReady) {
+        rejectConnect(new Error(`Gateway WS 连接断开: code=${code}`));
+      }
+    });
+
+    ws.on('error', (err) => {
+      log?.error?.(`[Palz][GwWS] 错误: ${err.message}`);
+    });
+  });
+}
+
+function contentToText(content: OpenAIContent): string {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content.map(part => {
+      if (part.type === 'text') return part.text;
+      if (part.type === 'image_url') return `![image](${part.image_url.url})`;
+      return '';
+    }).join('');
+  }
+  return '';
+}
+
+async function* streamFromGatewayWs(
+  userContent: OpenAIContent,
+  sessionKey: string,
+  gatewayAuth: string,
+  log?: any,
+  attachments?: GatewayAttachment[],
+): AsyncGenerator<string> {
+  if (!gwWsReady) {
+    await connectToGatewayWs(gatewayAuth, log);
+  }
+  if (!gwWs || !gwWsReady) {
+    throw new Error('Gateway WS 未就绪');
+  }
+
+  const reqId = `req_${++gwWsReqSeq}`;
+  const idempotencyKey = `idem-${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+  const requestStartTime = Date.now();
+
+  type QueueItem = { type: 'chunk'; text: string } | { type: 'done' } | { type: 'error'; error: Error };
+  const queue: QueueItem[] = [];
+  let waiter: (() => void) | null = null;
+
+  function enqueue(item: QueueItem) {
+    queue.push(item);
+    if (waiter) {
+      const w = waiter;
+      waiter = null;
+      w();
+    }
+  }
+
+  function waitForItem(): Promise<void> {
+    if (queue.length > 0) return Promise.resolve();
+    return new Promise(resolve => { waiter = resolve; });
+  }
+
+  const timer = setTimeout(() => {
+    enqueue({ type: 'error', error: new Error(`Gateway WS 请求超时 (${GW_WS_TIMEOUT}ms)`) });
+  }, GW_WS_TIMEOUT);
+
+  gwWsActiveStreams.set(reqId, {
+    reqId,
+    runId: null,
+    onChunk: (text: string) => enqueue({ type: 'chunk', text }),
+    onDone: () => { clearTimeout(timer); enqueue({ type: 'done' }); },
+    onError: (err: Error) => { clearTimeout(timer); enqueue({ type: 'error', error: err }); },
+  });
+
+  const hasAttachments = attachments && attachments.length > 0;
+  const messageText = hasAttachments ? extractPlainText(userContent) : contentToText(userContent);
+  const params: Record<string, unknown> = {
+    sessionKey,
+    message: messageText,
+    deliver: false,
+    idempotencyKey,
+  };
+  if (hasAttachments) {
+    params.attachments = attachments;
+  }
+  const req = { type: 'req', id: reqId, method: 'chat.send', params };
+
+  log?.info?.(`[Palz][GwWS] 发送请求: reqId=${reqId}, session=${sessionKey}, attachments=${hasAttachments ? attachments!.length : 0}, message=${messageText.slice(0, 200)}`);
+  gwWs!.send(JSON.stringify(req));
+
+  let chunkCount = 0;
+  let fullResponse = '';
+  let firstChunkTime = 0;
+
+  try {
+    while (true) {
+      await waitForItem();
+      while (queue.length > 0) {
+        const item = queue.shift()!;
+        if (item.type === 'chunk') {
+          chunkCount++;
+          if (chunkCount === 1) {
+            firstChunkTime = Date.now();
+            log?.info?.(`[Palz][GwWS] 首个chunk, TTFC=${firstChunkTime - requestStartTime}ms`);
+          }
+          fullResponse += item.text;
+          if (chunkCount <= 3 || chunkCount % 20 === 0) {
+            log?.info?.(`[Palz][GwWS] chunk #${chunkCount}: "${item.text.slice(0, 100)}", 累积长度=${fullResponse.length}`);
+          }
+          yield item.text;
+        } else if (item.type === 'done') {
+          const totalElapsed = Date.now() - requestStartTime;
+          const ttfc = firstChunkTime ? firstChunkTime - requestStartTime : -1;
+          const tail = fullResponse.slice(-200);
+          log?.info?.(`[Palz][GwWS] ✅ 完成, reqId=${reqId}, chunks=${chunkCount}, len=${fullResponse.length}, TTFC=${ttfc}ms, total=${totalElapsed}ms, tail="${tail}"`);
+          return;
+        } else if (item.type === 'error') {
+          const totalElapsed = Date.now() - requestStartTime;
+          log?.error?.(`[Palz][GwWS] ❌ 错误, reqId=${reqId}, chunks=${chunkCount}, len=${fullResponse.length}, total=${totalElapsed}ms: ${item.error.message}`);
+          throw item.error;
+        }
+      }
+    }
+  } finally {
+    clearTimeout(timer);
+    gwWsActiveStreams.delete(reqId);
+  }
+}
+
+function closeGatewayWs(log?: any) {
+  gwWsClosed = true;
+  if (gwWsPingInterval) { clearInterval(gwWsPingInterval); gwWsPingInterval = null; }
+  for (const h of gwWsActiveStreams.values()) {
+    h.onError(new Error('Gateway WS 关闭'));
+  }
+  gwWsActiveStreams.clear();
+  if (gwWs) {
+    gwWs.removeAllListeners();
+    gwWs.close();
+    gwWs = null;
+  }
+  gwWsReady = false;
+  gwWsConnecting = false;
+  log?.info?.('[Palz][GwWS] Gateway WebSocket 已关闭');
+}
+
+// ============ IM 消息发送 ============
+
+const STREAM_THROTTLE_MS = 200;
+
+interface StreamOpts {
+  streamId: string;
+  seq: number;
+  isFinal: boolean;
+  delta: string;
+}
+
+let msgSeq = 0;
+
+function nextMsgId(): string {
+  return `bot_reply_${Date.now()}_${++msgSeq}`;
+}
+
+async function sendToIM(
+  config: any,
+  conversationId: string,
+  content: OpenAIContent,
+  log?: any,
+  stream?: StreamOpts,
+  conversationType: string = 'direct',
+  msgId?: string,
+  senderId?: string,
+) {
+  const botId = config.botId;
+  const url = `${config.apiBaseUrl}/bot/send`;
+  const contentLength = typeof content === 'string' ? content.length : JSON.stringify(content).length;
+
+  const reqBody: Record<string, unknown> = {
+    bot_id: botId,
+    conversation_id: conversationId,
+    conversation_type: conversationType,
+    msg_id: msgId || nextMsgId(),
+    content,
+  };
+
+  if (senderId) {
+    reqBody.sender_id = senderId;
+  }
+
+  if (stream) {
+    reqBody.stream_id = stream.streamId;
+    reqBody.seq = stream.seq;
+    reqBody.is_final = stream.isFinal;
+    reqBody.delta = stream.delta;
+  }
+
+  log?.info?.(`[Palz][Send] POST ${url}, body=${JSON.stringify(reqBody)}`);
+
+  const sendStart = Date.now();
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(reqBody),
+    });
+  } catch (err: any) {
+    const sendElapsed = Date.now() - sendStart;
+    log?.error?.(`[Palz][Send] 发送请求异常: ${err.message}, 耗时=${sendElapsed}ms, msg_id=${reqBody.msg_id}`);
+    throw err;
+  }
+
+  const sendElapsed = Date.now() - sendStart;
+  const rawResponseText = await response.text().catch(() => '');
+  let body: any = null;
+  try {
+    body = JSON.parse(rawResponseText);
+  } catch {}
+
+  log?.info?.(`[Palz][Send] 响应: status=${response.status}, 耗时=${sendElapsed}ms, body=${rawResponseText}`);
+  if (!response.ok) {
+    log?.error?.(`[Palz][Send] 发送失败: ${response.status} ${rawResponseText}, 耗时=${sendElapsed}ms`);
+  } else if (sendElapsed > 3000) {
+    log?.warn?.(`[Palz][Send] 耗时较长: ${sendElapsed}ms, msg_id=${reqBody.msg_id}`);
+  }
+
+  return body;
+}
+
+/**
+ * 流式回复：边从 Gateway 读取边向 IM 发送，带节流控制。
+ * 每个片段同时携带 content（完整累积）和 delta（本次增量），
+ * IM 端可按需选择：用 delta 追加渲染（高效），或用 content 全量替换（可靠）。
+ */
+async function streamReplyToIM(
+  config: any,
+  conversationId: string,
+  gateway: AsyncGenerator<string>,
+  log?: any,
+  conversationType: string = 'direct',
+  msgId?: string,
+  senderId?: string,
+) {
+  const streamId = `stream_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+  const streamStartTime = Date.now();
+  let fullResponse = '';
+  let lastSentLength = 0;
+  let lastSendTime = 0;
+  let seq = 0;
+  let gatewayChunkCount = 0;
+  let sendCount = 0;
+
+  log?.info?.(`[Palz][Stream] 开始流式回复, streamId=${streamId}, conversation=${conversationId}`);
+
+  try {
+    for await (const chunk of gateway) {
+      gatewayChunkCount++;
+      fullResponse += chunk;
+
+      const now = Date.now();
+      if (now - lastSendTime >= STREAM_THROTTLE_MS) {
+        const delta = fullResponse.slice(lastSentLength);
+        sendCount++;
+        await sendToIM(config, conversationId, fullResponse, log, {
+          streamId, seq: seq++, isFinal: false, delta,
+        }, conversationType, msgId, senderId);
+        lastSentLength = fullResponse.length;
+        lastSendTime = now;
+      }
+    }
+
+    const finalDelta = fullResponse.slice(lastSentLength);
+    sendCount++;
+    await sendToIM(config, conversationId, fullResponse || '（无响应）', log, {
+      streamId, seq: seq++, isFinal: true, delta: finalDelta,
+    }, conversationType, msgId, senderId);
+
+    const totalElapsed = Date.now() - streamStartTime;
+    log?.info?.(`[Palz][Stream] 流式回复完成, streamId=${streamId}, gatewayChunks=${gatewayChunkCount}, sends=${sendCount}, 响应长度=${fullResponse.length}, 总耗时=${totalElapsed}ms`);
+  } catch (err: any) {
+    const totalElapsed = Date.now() - streamStartTime;
+    log?.error?.(`[Palz][Stream] 流式回复异常: ${err.message}, streamId=${streamId}, gatewayChunks=${gatewayChunkCount}, sends=${sendCount}, 已积累长度=${fullResponse.length}, 已耗时=${totalElapsed}ms`);
+    if (fullResponse) {
+      const errSuffix = `\n\n[错误: ${err.message}]`;
+      await sendToIM(config, conversationId, fullResponse + errSuffix, log, {
+        streamId, seq: seq++, isFinal: true, delta: fullResponse.slice(lastSentLength) + errSuffix,
+      }, conversationType, msgId, senderId).catch(() => {});
+    }
+    throw err;
+  }
+}
+
+// ============ 核心消息处理 ============
+
+function handleIMMessage(params: {
+  config: any;
+  msg: any;
+  log?: any;
+}) {
+  const { config, msg, log } = params;
+  const content: OpenAIContent = msg.content;
+  if (!content) return;
+
+  const plainText = extractPlainText(content).trim();
+  const hasImages = Array.isArray(content) && content.some(p => p.type === 'image_url');
+  if (!plainText && !hasImages) return;
+
+  if (dedup(msg.msg_id)) {
+    log?.info?.(`[Palz][Session] 跳过重复消息: msg_id=${msg.msg_id}`);
+    return;
+  }
+
+  const senderId = msg.sender_id;
+  const conversationId = msg.conversation_id;
+  const conversationType = msg.conversation_type || 'direct';
+  const useStream = msg.stream === true;
+  const msgSnapshot = Object.fromEntries(
+    Object.entries(msg).map(([k, v]) => {
+      const s = typeof v === 'string' ? v : JSON.stringify(v);
+      return [k, s.length > 300 ? s.slice(0, 300) + '...' : v];
+    }),
+  );
+  log?.info?.(`[Palz][Handle] 收到消息: ${JSON.stringify(msgSnapshot)}, stream=${useStream}`);
+
+  const msgReceivedTime = Date.now();
+
+  withUserLock(`${senderId}:${conversationId}`, async () => {
+    const lockAcquiredTime = Date.now();
+    const lockWait = lockAcquiredTime - msgReceivedTime;
+    if (lockWait > 100) {
+      log?.warn?.(`[Palz][Handle] 等待用户锁耗时: ${lockWait}ms, sender=${senderId}, msg_id=${msg.msg_id}`);
+    }
+    log?.info?.(`[Palz][Handle] 开始处理消息, msg_id=${msg.msg_id}, sender=${senderId}, 等锁=${lockWait}ms`);
+
+    if (isNewSessionCommand(plainText)) {
+      getSessionKey(senderId, conversationId, true, log);
+      await sendToIM(config, conversationId, '✨ 已开启新会话', log, undefined, conversationType, msg.msg_id, senderId);
+      log?.info?.(`[Palz][Handle] 新会话命令处理完成, 总耗时=${Date.now() - msgReceivedTime}ms`);
+      return;
+    }
+
+    const { sessionKey } = getSessionKey(senderId, conversationId, false, log);
+    const gatewayAuth = config.gatewayToken || '';
+
+    // 注入隐式上下文，让模型在使用 cron 工具时知道如何配置 delivery
+    const injectedContextText = `[系统隐式上下文: 当前所在渠道为 palz-connector，当前会话ID为 "${conversationId}"，发送者ID为 "${senderId}"。注意：若需使用 cron 工具创建定时任务，请务必在 delivery 配置中指定 channel="palz-connector" 且 to="${senderId}:${conversationId}"]\n\n`;
+
+    let wrappedContent: OpenAIContent;
+    if (typeof content === 'string') {
+      wrappedContent = injectedContextText + content;
+    } else if (Array.isArray(content)) {
+      wrappedContent = [{ type: 'text', text: injectedContextText }, ...content];
+    } else {
+      wrappedContent = content;
+    }
+
+    try {
+      const imageAttachments = await extractAttachments(wrappedContent, log);
+      if (imageAttachments.length > 0) {
+        log?.info?.(`[Palz][Handle] 提取到 ${imageAttachments.length} 个图片附件`);
+      }
+
+      log?.info?.(`[Palz][Handle] 开始调用 Gateway WS, session=${sessionKey}, mode=${useStream ? 'stream' : 'non-stream'}, attachments=${imageAttachments.length}`);
+      const gatewayStartTime = Date.now();
+      const gateway = streamFromGatewayWs(wrappedContent, sessionKey, gatewayAuth, log, imageAttachments.length > 0 ? imageAttachments : undefined);
+      if (useStream) {
+        await streamReplyToIM(config, conversationId, gateway, log, conversationType, msg.msg_id, senderId);
+      } else {
+        let fullResponse = '';
+        let chunkCount = 0;
+        for await (const chunk of gateway) {
+          chunkCount++;
+          fullResponse += chunk;
+        }
+        const gatewayElapsed = Date.now() - gatewayStartTime;
+        log?.info?.(`[Palz][Handle] Gateway 非流式读取完成, chunks=${chunkCount}, 响应长度=${fullResponse.length}, 耗时=${gatewayElapsed}ms`);
+        await sendToIM(config, conversationId, fullResponse || '（无响应）', log, undefined, conversationType, msg.msg_id, senderId);
+      }
+
+      const totalElapsed = Date.now() - msgReceivedTime;
+      log?.info?.(`[Palz][Handle] ✅ 消息处理完成, msg_id=${msg.msg_id}, 总耗时=${totalElapsed}ms (等锁=${lockWait}ms)`);
+    } catch (err: any) {
+      const totalElapsed = Date.now() - msgReceivedTime;
+      log?.error?.(`[Palz][Handle] ❌ Gateway 调用失败: ${err.message}, msg_id=${msg.msg_id}, 已耗时=${totalElapsed}ms`);
+      await sendToIM(config, conversationId, `抱歉，处理请求时出错: ${err.message}`, log, undefined, conversationType, msg.msg_id, senderId);
+    }
+  });
+}
+
+// ============ IM WebSocket 客户端 ============
+
+interface IMConnection {
+  close(): void;
+}
+
+function connectToIM(config: any, onMessage: (msg: any) => void, log?: any): IMConnection {
+  const botId = config.botId;
+  if (!botId) throw new Error('Palz botId is required');
+
+  const baseUrl = config.streamUrl.replace(/\/$/, '');
+  const separator = baseUrl.includes('?') ? '&' : '?';
+  const wsUrl = `${baseUrl}${separator}bot_id=${encodeURIComponent(botId)}`;
+  let reconnectDelay = 1000;
+  let closed = false;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let currentWs: WebSocket | null = null;
+  let consecutive4002 = 0;
+  const MAX_CONSECUTIVE_4002 = 5;
+  const REPLACED_RECONNECT_BASE_DELAY = 3000;
+
+  function connect() {
+    if (closed) return;
+    const ws = new WebSocket(wsUrl);
+    currentWs = ws;
+
+    let connectedAt = 0;
+
+    let pingInterval: ReturnType<typeof setInterval> | null = null;
+    let messageCount = 0;
+    let lastMessageTime = 0;
+
+    ws.on('open', () => {
+      log?.info?.(`[Palz][WS] 已连接, bot_id=${botId}, url=${wsUrl}`);
+      connectedAt = Date.now();
+      consecutive4002 = 0;
+
+      pingInterval = setInterval(() => {
+        if (ws.readyState === WebSocket.OPEN) {
+          const uptime = Math.round((Date.now() - connectedAt) / 1000);
+          const idleMs = lastMessageTime ? Date.now() - lastMessageTime : -1;
+          log?.info?.(`[Palz][WS] 心跳: 连接存活 ${uptime}s, 已收消息 ${messageCount} 条, 空闲 ${idleMs > 0 ? idleMs + 'ms' : 'N/A'}`);
+          try { ws.ping(); } catch {}
+        }
+      }, 60_000);
+    });
+
+    ws.on('pong', () => {
+      log?.info?.(`[Palz][WS] 收到 pong`);
+    });
+
+    ws.on('message', (data: Buffer) => {
+      log?.info?.(`[Palz][WS] <<< 收到WS包: ${data.toString().slice(0, 2000)}`);
+      try {
+        const msg = JSON.parse(data.toString());
+        if (msg.event !== 'message') {
+          log?.info?.(`[Palz][WS] 收到非 message 事件: event=${msg.event}, type=${msg.type || 'N/A'}`);
+          return;
+        }
+        messageCount++;
+        lastMessageTime = Date.now();
+        log?.info?.(`[Palz][WS] 收到第 ${messageCount} 条 message 事件, msg_id=${msg.msg_id || 'N/A'}`);
+        onMessage(msg);
+      } catch (err: any) {
+        log?.error?.(`[Palz][WS] 消息解析失败: ${err.message}, raw=${data.toString().slice(0, 500)}`);
+      }
+    });
+
+    ws.on('close', (code: number, reason: Buffer) => {
+      if (pingInterval) { clearInterval(pingInterval); pingInterval = null; }
+      if (closed) return;
+      const stableMs = Date.now() - connectedAt;
+      const reasonStr = reason?.toString() || '';
+
+      if (code === 4002) {
+        consecutive4002++;
+        if (consecutive4002 >= MAX_CONSECUTIVE_4002) {
+          log?.warn?.(`[Palz][WS] 连续 ${consecutive4002} 次被替代 (code=4002)，放弃重连`);
+          closed = true;
+          return;
+        }
+        const jitter = Math.floor(Math.random() * 2000);
+        const delay = REPLACED_RECONNECT_BASE_DELAY * consecutive4002 + jitter;
+        log?.warn?.(`[Palz][WS] 被新连接替代 (code=${code}, reason=${reasonStr}, 第${consecutive4002}次)，${delay}ms 后尝试重连`);
+        reconnectTimer = setTimeout(connect, delay);
+        return;
+      }
+
+      if (stableMs > 10_000) {
+        reconnectDelay = 1000;
+      }
+      log?.warn?.(`[Palz][WS] 断开 (code=${code}, reason=${reasonStr}, 连接维持${Math.round(stableMs / 1000)}s, 期间收到${messageCount}条消息)，${reconnectDelay}ms 后重连`);
+      reconnectTimer = setTimeout(connect, reconnectDelay);
+      reconnectDelay = Math.min(reconnectDelay * 2, 30000);
+    });
+
+    ws.on('error', (err) => {
+      log?.error?.(`[Palz][WS] 错误: ${err.message}, readyState=${ws.readyState}`);
+    });
+  }
+
+  connect();
+
+  return {
+    close() {
+      if (closed) return;
+      closed = true;
+      if (reconnectTimer) clearTimeout(reconnectTimer);
+      if (currentWs) {
+        currentWs.removeAllListeners();
+        currentWs.close();
+        currentWs = null;
+      }
+    },
+  };
+}
+
+// ============ 活跃连接追踪 ============
+
+const activeConnections = new Map<string, IMConnection>();
+
+// ============ 插件定义 ============
+
+const palzPlugin = {
+  id: 'palz-connector',
+  meta: {
+    id: 'palz-connector',
+    label: 'Palz Connector',
+    selectionLabel: 'Palz Connector (IM)',
+    blurb: 'Palz IM 接入 OpenClaw',
+  },
+  capabilities: { chatTypes: ['direct'] },
+  config: {
+    listAccountIds: () => {
+      const imCfg = loadIMConfig(pluginLogger);
+      if (!imCfg?.enabled) {
+        pluginLogger?.warn?.('[Palz][Config] 插件未启用 (enabled=false)，不会列出任何账号');
+        return [];
+      }
+      if (!imCfg.botId) {
+        pluginLogger?.error?.('[Palz][Config] botId 为空（环境变量 botID 未设置），无法列出账号');
+        return [];
+      }
+      return [imCfg.botId];
+    },
+    resolveAccount: (_cfg: any, accountId?: string) => {
+      const imCfg = loadIMConfig();
+      return {
+        accountId: accountId || imCfg?.botId || FALLBACK_ACCOUNT_ID,
+        config: imCfg,
+        enabled: imCfg.enabled !== false,
+      };
+    },
+    defaultAccountId: () => {
+      const imCfg = loadIMConfig();
+      return imCfg?.botId || FALLBACK_ACCOUNT_ID;
+    },
+    isConfigured: (account: any) => {
+      const configured = Boolean(account.config?.botId && account.config?.streamUrl && account.config?.apiBaseUrl);
+      if (!configured) {
+        const missing: string[] = [];
+        if (!account.config?.botId) missing.push('botId');
+        if (!account.config?.streamUrl) missing.push('streamUrl');
+        if (!account.config?.apiBaseUrl) missing.push('apiBaseUrl');
+        pluginLogger?.error?.(`[Palz][Config] 账号配置不完整，缺少: ${missing.join(', ')}，插件不会启动`);
+      }
+      return configured;
+    },
+    describeAccount: (account: any) => ({
+      accountId: account.accountId,
+      name: `Palz Connector (${account.config?.botId || 'unconfigured'})`,
+      enabled: account.enabled,
+      configured: Boolean(account.config?.botId && account.config?.streamUrl),
+    }),
+  },
+  messaging: {
+    normalizeTarget: (raw: string) => {
+      (pluginLogger || console).info?.(`[Palz][Messaging] normalizeTarget called, raw="${raw}"`);
+      if (!raw) return undefined;
+      const result = raw.trim().replace(/^(palz-connector|palz):/i, '');
+      (pluginLogger || console).info?.(`[Palz][Messaging] normalizeTarget result="${result}"`);
+      return result;
+    },
+    targetResolver: {
+      looksLikeId: (id: string) => {
+        const result = /^[\w:._-]+$/.test(id);
+        (pluginLogger || console).info?.(`[Palz][Messaging] looksLikeId called, id="${id}", result=${result}`);
+        return result;
+      },
+      hint: '<senderId>:<conversationId>',
+    },
+  },
+  outbound: {
+    deliveryMode: 'direct' as const,
+    sendText: async (ctx: any) => {
+      const { to, text } = ctx;
+      const log = ctx.log || pluginLogger || console;
+      const startTime = Date.now();
+      const parts = to.split(':');
+      const senderId = parts.length >= 2 ? parts[0] : undefined;
+      const conversationId = parts.length >= 2 ? parts.slice(1).join(':') : to;
+      log.info?.(`[Palz][Outbound] 发送文本消息, to="${to}", senderId="${senderId}", conversationId="${conversationId}", length=${text?.length || 0}`);
+      const config = loadIMConfig(log);
+      await sendToIM(config, conversationId, text, log, undefined, 'direct', undefined, senderId);
+      log.info?.(`[Palz][Outbound] 发送完成, to="${to}", 耗时=${Date.now() - startTime}ms`);
+      return { channel: 'palz-connector', messageId: Date.now().toString() };
+    },
+  },
+  gateway: {
+    startAccount: async (ctx: any) => {
+      const { account, abortSignal } = ctx;
+      const config = account.config;
+
+      if (!config.botId || !config.streamUrl || !config.apiBaseUrl) {
+        const missing: string[] = [];
+        if (!config.botId) missing.push('botId(环境变量 botID)');
+        if (!config.streamUrl) missing.push('streamUrl');
+        if (!config.apiBaseUrl) missing.push('apiBaseUrl');
+        const msg = `[Palz][Startup] 启动失败，关键配置缺失: ${missing.join(', ')}`;
+        ctx.log?.error?.(msg);
+        throw new Error(msg);
+      }
+
+      ctx.log?.info?.(`[Palz][Startup] 启动客户端, account=${account.accountId}, botId=${config.botId}`);
+
+      const gatewayAuth = config.gatewayToken || '';
+      try {
+        await connectToGatewayWs(gatewayAuth, ctx.log);
+        ctx.log?.info?.('[Palz][Startup] Gateway WebSocket 已连接');
+      } catch (err: any) {
+        ctx.log?.warn?.(`[Palz][Startup] Gateway WebSocket 预连接失败: ${err.message}，将在首次请求时重试`);
+      }
+
+      const connKey = config.botId;
+      const oldConn = activeConnections.get(connKey);
+      if (oldConn) {
+        ctx.log?.info?.(`[Palz][Startup] 关闭旧的 IM WebSocket 连接, account=${account.accountId}`);
+        oldConn.close();
+        activeConnections.delete(connKey);
+      }
+
+      const conn = connectToIM(config, (msg) => {
+        handleIMMessage({ config, msg, log: ctx.log });
+      }, ctx.log);
+
+      activeConnections.set(connKey, conn);
+      ctx.log?.info?.(`[Palz][Startup] IM WebSocket 客户端已启动, account=${account.accountId}, 活跃连接数=${activeConnections.size}`);
+
+      return new Promise<void>((resolve) => {
+        let stopped = false;
+        function shutdown() {
+          if (stopped) return;
+          stopped = true;
+          conn.close();
+          closeGatewayWs(ctx.log);
+          activeConnections.delete(connKey);
+          ctx.log?.info?.(`[Palz][Startup] Channel 已停止, account=${account.accountId}, 剩余活跃连接数=${activeConnections.size}`);
+          resolve();
+        }
+
+        if (abortSignal) {
+          if (abortSignal.aborted) {
+            shutdown();
+            return;
+          }
+          abortSignal.addEventListener('abort', shutdown);
+        }
+      });
+    },
+  },
+};
+
+// ============ 插件注册 ============
+
+let registered = false;
+
+const plugin = {
+  id: 'palz-connector',
+  name: 'Palz Connector Channel',
+  description: 'Palz IM 接入 OpenClaw',
+  register(api: any) {
+    runtime = api.runtime;
+    const log = api.logger;
+    pluginLogger = log;
+
+    log?.info?.(`[Palz][Startup] 开始注册插件... (已注册过=${registered})`);
+
+    const imCfg = loadIMConfig(log, true);
+    log?.info?.(`[Palz][Startup] 配置状态: enabled=${imCfg.enabled}, botId=${imCfg.botId || '(空)'}, streamUrl=${imCfg.streamUrl || '(空)'}, apiBaseUrl=${imCfg.apiBaseUrl || '(空)'}, gatewayToken=${imCfg.gatewayToken ? '(已设置)' : '(空)'}`);
+
+    api.registerChannel({ plugin: palzPlugin });
+    registered = true;
+    log?.info?.('[Palz][Startup] 插件注册完成');
+  },
+};
+
+export default plugin;