@spzhongwin/skill-logger-plugin 1.0.11 → 1.0.13

package/src/ws-client.ts

@@ -1,642 +1,717 @@
-import WebSocket from "ws";
-import path from "path";
-import fs from "fs/promises";
-import { SkillUpdater } from "./updater.ts";
-import { openclawHome } from "./paths.ts";
-import { readSkillVersion } from "./skill-version.ts";
-
-const HEARTBEAT_INTERVAL_MS = 30_000;
-const HEARTBEAT_ACK_TIMEOUT_MS = 75_000;
-const AGENT_SCAN_INTERVAL_MS = 3 * 60 * 1000;
-const ASSISTANT_WORKSPACE_PREFIX = "workspace-assistant-";
-const ASSISTANT_AGENT_PREFIX = "assistant-";
-const ASSISTANT_WORKSPACE_ID_RE = /^\d{5,}$/;
-
-export function parseAssistantWorkspaceAgentId(entryName: string): string | undefined {
-  if (!entryName.startsWith(ASSISTANT_WORKSPACE_PREFIX)) return undefined;
-  const suffix = entryName.slice(ASSISTANT_WORKSPACE_PREFIX.length);
-  if (!ASSISTANT_WORKSPACE_ID_RE.test(suffix)) return undefined;
-  return `${ASSISTANT_AGENT_PREFIX}${suffix}`;
-}
-
-export function normalizeAssistantUserId(userId: string): string | undefined {
-  const safeUserId = path.basename(userId);
-  if (safeUserId !== userId) return undefined;
-  const pureId = safeUserId.startsWith(ASSISTANT_AGENT_PREFIX)
-    ? safeUserId.slice(ASSISTANT_AGENT_PREFIX.length)
-    : safeUserId;
-  if (!ASSISTANT_WORKSPACE_ID_RE.test(pureId)) return undefined;
-  return pureId;
-}
-
-export interface WsClientOptions {
-  serverUrl: string;       // 例如: wss://api.aishuo.co/gateway/ws
-  authToken?: string;      // 用于网关鉴权
-  gatewayId: string;       // 当前网关宿主的标识，方便中控做集群分发
-  updater: SkillUpdater;   // 传入原来已有的 updater 实例
-  enableFileLog?: boolean; // 文件日志开关
-}
-
-export class GatewayWsClient {
-  private ws: WebSocket | null = null;
-  private options: WsClientOptions;
-  private reconnectTimer: NodeJS.Timeout | null = null;
-  private agentScanTimer: NodeJS.Timeout | null = null;
-  private pingTimer: NodeJS.Timeout | null = null;
-  private connectTimeoutTimer: NodeJS.Timeout | null = null;
-  private lastServerAckAt = 0;
-  private reconnectAttempts = 0;
-  private isDestroyed = false;
-  
-  // 本地缓存的 agent ID 列表
-  private currentAgentIds = new Set<string>();
-
-  private appendLogToFile(level: string, category: string, message: string, payload?: any) {
-    if (!this.options.enableFileLog) return;
-    try {
-      const ts = new Date().toISOString();
-      let logLine = `[${ts}] [${level}] [${category}] ${message}`;
-      if (payload !== undefined && payload !== null) {
-        // 如果是 Error 对象，主动提取 stack
-        if (payload instanceof Error) {
-          logLine += `\n  Stack: ${payload.stack || payload.message}`;
-        } else {
-          logLine += ` | Data: ${typeof payload === 'object' ? JSON.stringify(payload) : payload}`;
-        }
-      }
-      logLine += '\n';
-      const logsDir = path.join(openclawHome(), "logs");
-      fs.mkdir(logsDir, { recursive: true }).then(() => {
-        const logPath = path.join(logsDir, "skill-logger.err");
-        fs.appendFile(logPath, logLine).catch(()=>{});
-      }).catch(()=>{});
-    } catch (e) {
-      // ignore
-    }
-  }
-
-  constructor(options: WsClientOptions) {
-    this.options = options;
-  }
-
-  public connect() {
-    if (this.isDestroyed) return;
-    if (this.ws && (
-      this.ws.readyState === WebSocket.OPEN ||
-      this.ws.readyState === WebSocket.CONNECTING
-    )) {
-      this.appendLogToFile("INFO", "Connection", "Connect skipped: websocket already active", { readyState: this.ws.readyState });
-      return;
-    }
-
-    this.clearConnectTimeout();
-
-    const msgConnect = `Connecting to Central Service: ${this.options.serverUrl}`;
-    console.log(`[skill-logger-plugin][WS] ${msgConnect}`);
-    this.appendLogToFile("INFO", "Connection", msgConnect);
-
-    const headers: Record<string, string> = {
-      "X-Gateway-Id": this.options.gatewayId,
-    };
-    if (this.options.authToken) {
-      headers["Authorization"] = this.options.authToken;
-    }
-
-    try {
-      const ws = new WebSocket(this.options.serverUrl, { headers });
-      this.ws = ws;
-      this.connectTimeoutTimer = setTimeout(() => {
-        if (this.ws === ws && ws.readyState === WebSocket.CONNECTING) {
-          this.appendLogToFile("WARN", "Connection", "Connection timed out before open; terminating socket.");
-          ws.terminate();
-        }
-      }, 15000);
-    } catch (err: any) {
-      console.error(`[skill-logger-plugin][WS] Sync init error:`, err);
-      this.appendLogToFile("ERROR", "Connection", "Sync initialization error", err);
-      this.scheduleReconnect();
-      return;
-    }
-
-    const ws = this.ws;
-
-    ws.on("open", async () => {
-      if (this.ws !== ws) return;
-      console.log(`[skill-logger-plugin][WS] Connected successfully!`);
-      this.appendLogToFile("INFO", "Connection", "Connected successfully!");
-      this.clearConnectTimeout();
-      this.reconnectAttempts = 0;
-      this.lastServerAckAt = Date.now();
-      this.clearReconnectTimer();
-      
-      // 首次连接，全量扫描并上报，同时进行应用层握手，确保服务端能把 DB 在线态刷新成真实状态。
-      await this.scanAndReportAgents(true);
-      this.sendGatewayHello();
-      this.startHeartbeat();
-      
-      // 开启 3 分钟定期的自动扫码增量同步
-      if (!this.agentScanTimer) {
-        this.agentScanTimer = setInterval(() => {
-          this.scanAndReportAgents(true);
-        }, AGENT_SCAN_INTERVAL_MS);
-      }
-    });
-
-    ws.on("pong", () => {
-      this.lastServerAckAt = Date.now();
-    });
-
-    ws.on("message", async (data) => {
-      if (this.ws !== ws) return;
-      try {
-        const msg = JSON.parse(data.toString());
-        if (msg?.type === "GATEWAY_HELLO_ACK" || msg?.type === "HEARTBEAT_ACK") {
-          this.lastServerAckAt = Date.now();
-          this.appendLogToFile("INFO", "Heartbeat", "Server heartbeat acknowledged", { type: msg.type, connectionId: msg.connectionId });
-          return;
-        }
-        if (msg?.type === "BATCH_COMMAND" && Array.isArray(msg.commands)) {
-          const { commands, type, ...shared } = msg;
-          for (const cmd of commands) {
-            await this.handleMessage({ ...shared, userId: cmd.userId, replyId: cmd.replyId });
-          }
-          return;
-        }
-        await this.handleMessage(msg);
-      } catch (err) {
-        console.error(`[skill-logger-plugin][WS] Failed to parse/handle message:`, err);
-      }
-    });
-
-    ws.on("close", () => {
-      console.warn(`[skill-logger-plugin][WS] Connection closed.`);
-      this.appendLogToFile("WARN", "Connection", "Connection closed. Starting reconnect timer.");
-      if (this.ws === ws) {
-        this.ws = null;
-        this.clearConnectTimeout();
-        this.clearAgentScanTimer();
-        this.clearHeartbeat();
-        this.scheduleReconnect();
-      }
-    });
-
-    ws.on("error", (err) => {
-      console.error(`[skill-logger-plugin][WS] Connection error:`, err);
-      this.appendLogToFile("ERROR", "Connection", "Connection error", err);
-      if (this.ws === ws) {
-        ws.close(); // 触发 close 事件进行重连
-      }
-    });
-  }
-
-  /**
-   * 扫描 OpenClaw 根目录下的 workspace-assistant-{userId} 目录。
-   * userId 必须是至少 5 位数字。
-   */
-  private async scanAndReportAgents(isInitialReport: boolean) {
-    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
-    
-    try {
-      const rootPath = openclawHome();
-      let entries: string[] = [];
-      try {
-        entries = await fs.readdir(rootPath);
-      } catch (e) {
-        // 读目录失败通常是瞬时性的（磁盘抖动/权限/句柄耗尽等），不代表这台机器真的没有用户了。
-        // 跳过本轮上报、保留上次已知状态，等下一次扫描自然重试，避免把瞬时故障放大成
-        // "全部用户离线"（服务端收到空列表会把这台网关下所有用户标记 OFFLINE）。
-        this.appendLogToFile("WARN", "AgentScan", "OpenClaw home is not readable; skipping this scan cycle", e);
-        return;
-      }
-
-      const newAgentIds = new Set<string>();
-      for (const entry of entries) {
-        const agentId = parseAssistantWorkspaceAgentId(entry);
-        if (agentId) newAgentIds.add(agentId);
-      }
-
-      let changed = false;
-      if (newAgentIds.size !== this.currentAgentIds.size) {
-        changed = true;
-      } else {
-        for (const id of newAgentIds) {
-          if (!this.currentAgentIds.has(id)) {
-            changed = true;
-            break;
-          }
-        }
-      }
-
-      this.currentAgentIds = newAgentIds;
-
-      if (isInitialReport) {
-        this.appendLogToFile("INFO", "AgentScan", `Reporting full agent list`, { count: this.currentAgentIds.size, agents: Array.from(this.currentAgentIds) });
-        this.sendAgentListReport("AGENT_LIST_REPORT");
-      } else if (changed) {
-        this.appendLogToFile("INFO", "AgentScan", `Syncing changed agent list`, { count: this.currentAgentIds.size, agents: Array.from(this.currentAgentIds) });
-        this.sendAgentListReport("AGENT_LIST_SYNC");
-      }
-
-    } catch (err: any) {
-      console.error(`[skill-logger-plugin][WS] Failed to scan agents:`, err);
-      this.appendLogToFile("ERROR", "AgentScan", `Failed to scan agents`, err);
-    }
-  }
-
-  private startHeartbeat() {
-    this.clearHeartbeat();
-    this.pingTimer = setInterval(() => {
-      const ws = this.ws;
-      if (!ws || ws.readyState !== WebSocket.OPEN) return;
-
-      const ackAge = Date.now() - this.lastServerAckAt;
-      if (ackAge > HEARTBEAT_ACK_TIMEOUT_MS) {
-        this.appendLogToFile("WARN", "Heartbeat", "Server heartbeat ACK timed out; terminating socket for reconnect", { ackAge });
-        ws.terminate();
-        return;
-      }
-
-      ws.ping();
-      this.sendClientHeartbeat();
-    }, HEARTBEAT_INTERVAL_MS);
-    this.sendClientHeartbeat();
-  }
-
-  private clearHeartbeat() {
-    if (this.pingTimer) {
-      clearInterval(this.pingTimer);
-      this.pingTimer = null;
-    }
-  }
-
-  private scheduleReconnect() {
-    if (this.isDestroyed || this.reconnectTimer) return;
-    
-    // 闭环完善：引入随机 Jitter 抖动，打散服务端重启时可能引发的瞬间重连风暴
-    const jitter = Math.floor(Math.random() * 5000);
-    const baseDelay = Math.min(30000, 2000 * Math.max(1, 2 ** this.reconnectAttempts));
-    const delay = baseDelay + jitter;
-    this.reconnectAttempts += 1;
-    
-    console.log(`[skill-logger-plugin][WS] Reconnecting in ${delay}ms...`);
-    this.appendLogToFile("INFO", "Connection", "Reconnect scheduled", { delay, attempt: this.reconnectAttempts });
-    this.reconnectTimer = setTimeout(() => {
-      this.reconnectTimer = null;
-      this.connect();
-    }, delay);
-  }
-
-  private clearReconnectTimer() {
-    if (this.reconnectTimer) {
-      clearTimeout(this.reconnectTimer);
-      this.reconnectTimer = null;
-    }
-  }
-
-  private clearConnectTimeout() {
-    if (this.connectTimeoutTimer) {
-      clearTimeout(this.connectTimeoutTimer);
-      this.connectTimeoutTimer = null;
-    }
-  }
-
-  private terminateCurrentSocket(reason: string, payload?: any) {
-    const ws = this.ws;
-    if (!ws) return;
-    this.appendLogToFile("WARN", "Connection", `Terminating websocket: ${reason}`, payload);
-    try {
-      ws.terminate();
-    } catch (err) {
-      this.appendLogToFile("WARN", "Connection", "Terminate websocket failed", err);
-    }
-  }
-
-  private sendJson(payload: any, category: string) {
-    const ws = this.ws;
-    if (!ws || ws.readyState !== WebSocket.OPEN) return false;
-
-    try {
-      ws.send(JSON.stringify(payload), (err) => {
-        if (!err) return;
-        this.appendLogToFile("WARN", category, "WebSocket send failed", err);
-        if (this.ws === ws) {
-          this.terminateCurrentSocket("send_failed", { category, message: err.message });
-        }
-      });
-      return true;
-    } catch (err) {
-      this.appendLogToFile("WARN", category, "WebSocket send threw", err);
-      if (this.ws === ws) {
-        this.terminateCurrentSocket("send_threw", err);
-      }
-      return false;
-    }
-  }
-
-  private sendGatewayHello() {
-    this.sendJson({
-      type: "GATEWAY_HELLO",
-      gatewayId: this.options.gatewayId,
-      agentIds: Array.from(this.currentAgentIds),
-      clientTime: Date.now(),
-      supportsBatch: true,
-    }, "Heartbeat");
-  }
-
-  private sendClientHeartbeat() {
-    this.sendJson({
-      type: "CLIENT_HEARTBEAT",
-      gatewayId: this.options.gatewayId,
-      agentIds: Array.from(this.currentAgentIds),
-      clientTime: Date.now(),
-    }, "Heartbeat");
-  }
-
-  private sendAgentListReport(type: "AGENT_LIST_REPORT" | "AGENT_LIST_SYNC") {
-    this.sendJson({
-      type,
-      gatewayId: this.options.gatewayId,
-      agentIds: Array.from(this.currentAgentIds),
-      clientTime: Date.now(),
-    }, "AgentScan");
-  }
-  
-  private clearAgentScanTimer() {
-    if (this.agentScanTimer) {
-      clearInterval(this.agentScanTimer);
-      this.agentScanTimer = null;
-    }
-  }
-
-  /**
-   * 核心指令分发中心：完全跳过沙盒，基于 userId 直接进行底层物理文件操作
-   */
-  private async handleMessage(msg: any) {
-    const { action, userId, code, url, force, version, replyId } = msg;
-    this.appendLogToFile("INFO", "Command", `Received WS message`, { action, userId, code, version, replyId });
-
-    if (!action || !userId) {
-      this.appendLogToFile("WARN", "Command", `Message dropped: missing action or userId`, msg);
-      return;
-    }
-
-    // 闭环完善：清理 code，并严格校验 userId，防止恶意指令通过 '../' 引发宿主机目录穿越攻击
-    const safeCode = code ? path.basename(code) : undefined;
-
-    // 100% 确定性安全寻址：userId 只接受纯数字或 assistant-数字，且数字至少 5 位。
-    const pureId = normalizeAssistantUserId(userId);
-    if (!pureId) {
-      this.reply(replyId, { success: false, message: `Invalid userId: ${userId}`, action });
-      return;
-    }
-    const targetDir = path.join(openclawHome(), `workspace-assistant-${pureId}`, "skills");
-
-    try {
-      if (action === "INSTALL_SKILL") {
-        if (!safeCode) throw new Error("Missing code parameter");
-        console.log(`[skill-logger-plugin][WS] Executing INSTALL for user ${userId}, code: ${safeCode}`);
-        this.appendLogToFile("INFO", "Command", `INSTALL_SKILL received`, { userId, code: safeCode, version });
-        const result = await this.options.updater.manualInstall({
-          code: safeCode, url, version, force: force !== false, targetDir
-        });
-        this.reply(replyId, { success: result.success, message: result.message, action });
-
-      } else if (action === "UNINSTALL_SKILL") {
-        if (!safeCode) throw new Error("Missing code parameter");
-        console.log(`[skill-logger-plugin][WS] Executing UNINSTALL for user ${userId}, code: ${safeCode}`);
-        this.appendLogToFile("INFO", "Command", `UNINSTALL_SKILL received`, { userId, code: safeCode });
-        const skillPath = path.join(targetDir, safeCode);
-        await fs.rm(skillPath, { recursive: true, force: true });
-        this.reply(replyId, { success: true, message: `Skill ${safeCode} removed`, action });
-
-      } else if (action === "LIST_SKILLS") {
-        let list: any[] = [];
-        let targetDirExists = false;
-        try {
-          const targetStat = await fs.stat(targetDir);
-          targetDirExists = targetStat.isDirectory();
-        } catch (err: any) {
-          if (err?.code !== "ENOENT") throw err;
-        }
-        if (!targetDirExists) {
-          throw new Error(`Target skills directory does not exist: ${targetDir}`);
-        }
-
-        const entries = await fs.readdir(targetDir, { withFileTypes: true });
-        
-        const dirs = entries.filter(e => (e.isDirectory() || e.isSymbolicLink()) && !e.name.startsWith("."));
-        
-        for (const e of dirs) {
-          const skillDir = path.join(targetDir, e.name);
-          const skillMdPath = path.join(skillDir, 'SKILL.md');
-          
-          try {
-            const stat = await fs.stat(skillMdPath);
-            if (!stat.isFile()) continue;
-          } catch (err) {
-            continue;
-          }
-          
-          const metaPath = path.join(skillDir, '.meta.json');
-          let isPlatform = false;
-          let isBuiltIn = e.isSymbolicLink();
-          let metaData: any = null;
-          let name = e.name;
-          let description = "";
-          let skillVersion = "";
-
-          try {
-            const mdContent = await fs.readFile(skillMdPath, 'utf8');
-            const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(mdContent)?.[1] ?? "";
-            const parsedName = /(^|\n)name:\s*(.+)/.exec(fm)?.[2]?.trim();
-            if (parsedName) name = parsedName;
-
-            const descMatch = /(^|\n)description:\s*(?:>\s*\n\s*)?(.*?)(?=\n[a-z]+:|\n---|$)/is.exec(fm);
-            if (descMatch && descMatch[2]) {
-               description = descMatch[2].replace(/\n\s+/g, ' ').trim();
-            }
-          } catch (err) {}
-          
-          try {
-            const metaContent = await fs.readFile(metaPath, 'utf8');
-            const parsed = JSON.parse(metaContent);
-            if (parsed) {
-              if (parsed.ownerId === 'CMS' || parsed.ownerId === 'CMS_COMPAT') isPlatform = true;
-              if (parsed.isBuiltIn === true || parsed.ownerId === 'built-in') isBuiltIn = true;
-              metaData = parsed;
-            }
-          } catch (err) {}
-
-          const resolvedVersion = await readSkillVersion(skillDir);
-          if (resolvedVersion) skillVersion = resolvedVersion;
-          
-          if (isPlatform) {
-            list.push({
-              code: e.name,
-              isPlatform: true,
-              isBuiltIn: isBuiltIn,
-              version: skillVersion,
-              name,
-              description,
-              publishedAt: metaData?.publishedAt
-            });
-          } else {
-            list.push({
-              code: e.name,
-              isPlatform: false,
-              isBuiltIn: isBuiltIn,
-              version: skillVersion,
-              name: name,
-              description: description
-            });
-          }
-        }
-        this.reply(replyId, { success: true, data: list, action });
-
-      } else if (action === "UPDATE_SKILL") {
-        if (!safeCode) throw new Error("Missing code parameter");
-        // 更新可能是大批量广播，增加防阻塞的随机延时 (0~5秒)
-        const delayMs = Math.random() * 5000;
-        console.log(`[skill-logger-plugin][WS] Scheduled UPDATE for user ${userId}, code: ${safeCode} in ${Math.round(delayMs)}ms`);
-        this.appendLogToFile("INFO", "Command", `Scheduled UPDATE_SKILL`, { userId, code: safeCode, version, delayMs: Math.round(delayMs) });
-        
-        setTimeout(async () => {
-          try {
-            await this.options.updater.manualInstall({
-              code: safeCode, url, version, force: true, targetDir
-            });
-            // 广播更新一般无需强阻塞等待 replyId，若有需要也可以回传
-            if (replyId) {
-              this.reply(replyId, { success: true, message: `Skill ${safeCode} updated successfully`, action });
-            }
-          } catch (e: any) {
-            if (replyId) this.reply(replyId, { success: false, message: e.message, action });
-          }
-        }, delayMs);
-
-      } else if (action === "INSTALL_EXPERT") {
-        if (!safeCode) throw new Error("Missing code parameter");
-        const { name, version, downloadUrl, skills } = msg;
-        console.log(`[skill-logger-plugin][WS] Executing INSTALL_EXPERT for user ${userId}, code: ${safeCode}`);
-        this.appendLogToFile("INFO", "Command", `INSTALL_EXPERT received`, { userId, code: safeCode, version, downloadUrl });
-
-        const userSkillRoot = path.join(openclawHome(), `workspace-assistant-${pureId}`, ".user");
-
-        // 1. 安装专家本身
-        const expertTarget = path.join(userSkillRoot, "experts", safeCode);
-        await fs.mkdir(path.dirname(expertTarget), { recursive: true });
-        const expertResult = await this.options.updater.installZipFromUrl(downloadUrl, expertTarget);
-        if (!expertResult.success) {
-          throw new Error(`专家安装失败: ${expertResult.message}`);
-        }
-
-        // 2. 安装依赖的 skills
-        const skillTargetRoot = path.join(userSkillRoot, "skills");
-        await fs.mkdir(skillTargetRoot, { recursive: true });
-        const skillResults: string[] = [];
-        if (Array.isArray(skills)) {
-          for (const sk of skills) {
-            if (!sk.code || !sk.downloadUrl) {
-              skillResults.push(`${sk.code || 'unknown'}: 缺少下载地址`);
-              continue;
-            }
-            try {
-              const skTarget = path.join(skillTargetRoot, sk.code);
-              const result = await this.options.updater.installZipFromUrl(sk.downloadUrl, skTarget);
-              skillResults.push(`${sk.code}: ${result.success ? '成功' : '失败 - ' + result.message}`);
-            } catch (e: any) {
-              skillResults.push(`${sk.code}: 失败 - ${e.message}`);
-            }
-          }
-        }
-
-        this.reply(replyId, {
-          success: true,
-          message: `专家 ${safeCode} 安装完成`,
-          action,
-          data: { expertCode: safeCode, skills: skillResults },
-        });
-
-      } else if (action === "GET_EXPERT_REGISTRY") {
-        console.log(`[skill-logger-plugin][WS] Executing GET_EXPERT_REGISTRY for user ${userId}`);
-        this.appendLogToFile("INFO", "Command", `GET_EXPERT_REGISTRY received`, { userId });
-        
-        const registryFilePath = path.join(openclawHome(), `workspace-assistant-${pureId}`, ".user", "expert-registry.yaml");
-        let content = "";
-        let fileExists = false;
-        try {
-          const stat = await fs.stat(registryFilePath);
-          fileExists = stat.isFile();
-        } catch (err: any) {
-          if (err?.code !== "ENOENT") throw err;
-        }
-
-        if (fileExists) {
-           content = await fs.readFile(registryFilePath, "utf8");
-           
-           // 解析 YAML 提取需要的字段
-           const expertsList: any[] = [];
-           const lines = content.split('\n');
-           let currentExpert: any = null;
-           
-           for (const line of lines) {
-             const trimmed = line.trim();
-             if (trimmed.startsWith('#')) continue;
-
-             const idMatch = line.match(/^\s*-\s*id:\s*(.+)$/);
-             if (idMatch) {
-               if (currentExpert && currentExpert.id) expertsList.push(currentExpert);
-               currentExpert = { id: idMatch[1].trim() };
-               continue;
-             }
-
-             if (currentExpert) {
-               const nameMatch = line.match(/^\s*name:\s*(.+)$/);
-               if (nameMatch) {
-                 currentExpert.name = nameMatch[1].trim();
-               }
-               const descMatch = line.match(/^\s*description:\s*(.+)$/);
-               if (descMatch) {
-                 currentExpert.description = descMatch[1].trim();
-               }
-             }
-           }
-           if (currentExpert && currentExpert.id) expertsList.push(currentExpert);
-
-           this.reply(replyId, { success: true, data: expertsList, action });
-        } else {
-           this.reply(replyId, { success: false, message: `未找到用户技能配置文件，可能尚未注册或文件已丢失`, action });
-        }
-
-      } else {
-        console.warn(`[skill-logger-plugin][WS] Unknown action: ${action}`);
-        this.appendLogToFile("WARN", "Command", `Unknown action: ${action}`);
-        this.reply(replyId, { success: false, message: `Unknown action: ${action}`, action });
-      }
-    } catch (err: any) {
-      this.appendLogToFile("ERROR", "Command", `Error executing action ${action}`, err);
-      this.reply(replyId, { success: false, message: err.message, action });
-    }
-  }
-
-  private reply(replyId: string, payload: any) {
-    this.appendLogToFile("INFO", "Command", `Replying to command`, { replyId, payload });
-    if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !replyId) {
-      this.appendLogToFile("WARN", "Command", `Cannot reply: WS closed or missing replyId`, { replyId });
-      return;
-    }
-    this.ws.send(JSON.stringify({ type: "REPLY", replyId, ...payload }));
-  }
-
-  public destroy() {
-    this.isDestroyed = true;
-    this.clearReconnectTimer();
-    this.clearAgentScanTimer();
-    this.clearHeartbeat();
-    this.clearConnectTimeout();
-    if (this.ws) {
-      this.ws.terminate(); // 强行销毁，斩断半开连接残留
-      this.ws = null;
-    }
-  }
-}
+import WebSocket from "ws";
+import path from "path";
+import fs from "fs/promises";
+import { SkillUpdater } from "./updater.ts";
+import { openclawHome } from "./paths.ts";
+import { readSkillVersion } from "./skill-version.ts";
+
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const HEARTBEAT_ACK_TIMEOUT_MS = 75_000;
+const AGENT_SCAN_INTERVAL_MS = 3 * 60 * 1000;
+const ASSISTANT_WORKSPACE_PREFIX = "workspace-assistant-";
+const ASSISTANT_AGENT_PREFIX = "assistant-";
+const ASSISTANT_WORKSPACE_ID_RE = /^\d{5,}$/;
+
+export function parseAssistantWorkspaceAgentId(entryName: string): string | undefined {
+  if (!entryName.startsWith(ASSISTANT_WORKSPACE_PREFIX)) return undefined;
+  const suffix = entryName.slice(ASSISTANT_WORKSPACE_PREFIX.length);
+  if (!ASSISTANT_WORKSPACE_ID_RE.test(suffix)) return undefined;
+  return `${ASSISTANT_AGENT_PREFIX}${suffix}`;
+}
+
+export function normalizeAssistantUserId(userId: string): string | undefined {
+  const safeUserId = path.basename(userId);
+  if (safeUserId !== userId) return undefined;
+  const pureId = safeUserId.startsWith(ASSISTANT_AGENT_PREFIX)
+    ? safeUserId.slice(ASSISTANT_AGENT_PREFIX.length)
+    : safeUserId;
+  if (!ASSISTANT_WORKSPACE_ID_RE.test(pureId)) return undefined;
+  return pureId;
+}
+
+export function shouldSyncBuiltInTemplate(action: string, isBuiltIn: unknown): boolean {
+  return action === "UPDATE_SKILL" && isBuiltIn === true;
+}
+
+export interface WsClientOptions {
+  serverUrl: string;       // 例如: wss://api.aishuo.co/gateway/ws
+  authToken?: string;      // 用于网关鉴权
+  gatewayId: string;       // 当前网关宿主的标识，方便中控做集群分发
+  updater: SkillUpdater;   // 传入原来已有的 updater 实例
+  enableFileLog?: boolean; // 文件日志开关
+}
+
+export class GatewayWsClient {
+  private ws: WebSocket | null = null;
+  private options: WsClientOptions;
+  private reconnectTimer: NodeJS.Timeout | null = null;
+  private agentScanTimer: NodeJS.Timeout | null = null;
+  private pingTimer: NodeJS.Timeout | null = null;
+  private connectTimeoutTimer: NodeJS.Timeout | null = null;
+  private lastServerAckAt = 0;
+  private reconnectAttempts = 0;
+  private isDestroyed = false;
+  
+  // 本地缓存的 agent ID 列表
+  private currentAgentIds = new Set<string>();
+
+  private appendLogToFile(level: string, category: string, message: string, payload?: any) {
+    if (!this.options.enableFileLog) return;
+    try {
+      const ts = new Date().toISOString();
+      let logLine = `[${ts}] [${level}] [${category}] ${message}`;
+      if (payload !== undefined && payload !== null) {
+        // 如果是 Error 对象，主动提取 stack
+        if (payload instanceof Error) {
+          logLine += `\n  Stack: ${payload.stack || payload.message}`;
+        } else {
+          logLine += ` | Data: ${typeof payload === 'object' ? JSON.stringify(payload) : payload}`;
+        }
+      }
+      logLine += '\n';
+      const logsDir = path.join(openclawHome(), "logs");
+      fs.mkdir(logsDir, { recursive: true }).then(() => {
+        const logPath = path.join(logsDir, "skill-logger.err");
+        fs.appendFile(logPath, logLine).catch(()=>{});
+      }).catch(()=>{});
+    } catch (e) {
+      // ignore
+    }
+  }
+
+  private createInstallTrace(context: Record<string, unknown>) {
+    return (stage: string, data?: Record<string, unknown>) => {
+      this.appendLogToFile(stage === "install.failed" ? "ERROR" : "INFO", "Install", stage, {
+        ...context,
+        ...data,
+      });
+    };
+  }
+
+  constructor(options: WsClientOptions) {
+    this.options = options;
+  }
+
+  public connect() {
+    if (this.isDestroyed) return;
+    if (this.ws && (
+      this.ws.readyState === WebSocket.OPEN ||
+      this.ws.readyState === WebSocket.CONNECTING
+    )) {
+      this.appendLogToFile("INFO", "Connection", "Connect skipped: websocket already active", { readyState: this.ws.readyState });
+      return;
+    }
+
+    this.clearConnectTimeout();
+
+    const msgConnect = `Connecting to Central Service: ${this.options.serverUrl}`;
+    console.log(`[skill-logger-plugin][WS] ${msgConnect}`);
+    this.appendLogToFile("INFO", "Connection", msgConnect);
+
+    const headers: Record<string, string> = {
+      "X-Gateway-Id": this.options.gatewayId,
+    };
+    if (this.options.authToken) {
+      headers["Authorization"] = this.options.authToken;
+    }
+
+    try {
+      const ws = new WebSocket(this.options.serverUrl, { headers });
+      this.ws = ws;
+      this.connectTimeoutTimer = setTimeout(() => {
+        if (this.ws === ws && ws.readyState === WebSocket.CONNECTING) {
+          this.appendLogToFile("WARN", "Connection", "Connection timed out before open; terminating socket.");
+          ws.terminate();
+        }
+      }, 15000);
+    } catch (err: any) {
+      console.error(`[skill-logger-plugin][WS] Sync init error:`, err);
+      this.appendLogToFile("ERROR", "Connection", "Sync initialization error", err);
+      this.scheduleReconnect();
+      return;
+    }
+
+    const ws = this.ws;
+
+    ws.on("open", async () => {
+      if (this.ws !== ws) return;
+      console.log(`[skill-logger-plugin][WS] Connected successfully!`);
+      this.appendLogToFile("INFO", "Connection", "Connected successfully!");
+      this.clearConnectTimeout();
+      this.reconnectAttempts = 0;
+      this.lastServerAckAt = Date.now();
+      this.clearReconnectTimer();
+      
+      // 首次连接，全量扫描并上报，同时进行应用层握手，确保服务端能把 DB 在线态刷新成真实状态。
+      await this.scanAndReportAgents(true);
+      this.sendGatewayHello();
+      this.startHeartbeat();
+      
+      // 开启 3 分钟定期的自动扫码增量同步
+      if (!this.agentScanTimer) {
+        this.agentScanTimer = setInterval(() => {
+          this.scanAndReportAgents(true);
+        }, AGENT_SCAN_INTERVAL_MS);
+      }
+    });
+
+    ws.on("pong", () => {
+      this.lastServerAckAt = Date.now();
+    });
+
+    ws.on("message", async (data) => {
+      if (this.ws !== ws) return;
+      try {
+        const msg = JSON.parse(data.toString());
+        if (msg?.type === "GATEWAY_HELLO_ACK" || msg?.type === "HEARTBEAT_ACK") {
+          this.lastServerAckAt = Date.now();
+          this.appendLogToFile("INFO", "Heartbeat", "Server heartbeat acknowledged", { type: msg.type, connectionId: msg.connectionId });
+          return;
+        }
+        if (msg?.type === "BATCH_COMMAND" && Array.isArray(msg.commands)) {
+          const { commands, type, ...shared } = msg;
+          for (const cmd of commands) {
+            await this.handleMessage({ ...shared, userId: cmd.userId, replyId: cmd.replyId });
+          }
+          return;
+        }
+        await this.handleMessage(msg);
+      } catch (err) {
+        console.error(`[skill-logger-plugin][WS] Failed to parse/handle message:`, err);
+      }
+    });
+
+    ws.on("close", () => {
+      console.warn(`[skill-logger-plugin][WS] Connection closed.`);
+      this.appendLogToFile("WARN", "Connection", "Connection closed. Starting reconnect timer.");
+      if (this.ws === ws) {
+        this.ws = null;
+        this.clearConnectTimeout();
+        this.clearAgentScanTimer();
+        this.clearHeartbeat();
+        this.scheduleReconnect();
+      }
+    });
+
+    ws.on("error", (err) => {
+      console.error(`[skill-logger-plugin][WS] Connection error:`, err);
+      this.appendLogToFile("ERROR", "Connection", "Connection error", err);
+      if (this.ws === ws) {
+        ws.close(); // 触发 close 事件进行重连
+      }
+    });
+  }
+
+  /**
+   * 扫描 OpenClaw 根目录下的 workspace-assistant-{userId} 目录。
+   * userId 必须是至少 5 位数字。
+   */
+  private async scanAndReportAgents(isInitialReport: boolean) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+    
+    try {
+      const rootPath = openclawHome();
+      let entries: string[] = [];
+      try {
+        entries = await fs.readdir(rootPath);
+      } catch (e) {
+        // 读目录失败通常是瞬时性的（磁盘抖动/权限/句柄耗尽等），不代表这台机器真的没有用户了。
+        // 跳过本轮上报、保留上次已知状态，等下一次扫描自然重试，避免把瞬时故障放大成
+        // "全部用户离线"（服务端收到空列表会把这台网关下所有用户标记 OFFLINE）。
+        this.appendLogToFile("WARN", "AgentScan", "OpenClaw home is not readable; skipping this scan cycle", e);
+        return;
+      }
+
+      const newAgentIds = new Set<string>();
+      for (const entry of entries) {
+        const agentId = parseAssistantWorkspaceAgentId(entry);
+        if (agentId) newAgentIds.add(agentId);
+      }
+
+      let changed = false;
+      if (newAgentIds.size !== this.currentAgentIds.size) {
+        changed = true;
+      } else {
+        for (const id of newAgentIds) {
+          if (!this.currentAgentIds.has(id)) {
+            changed = true;
+            break;
+          }
+        }
+      }
+
+      this.currentAgentIds = newAgentIds;
+
+      if (isInitialReport) {
+        this.appendLogToFile("INFO", "AgentScan", `Reporting full agent list`, { count: this.currentAgentIds.size, agents: Array.from(this.currentAgentIds) });
+        this.sendAgentListReport("AGENT_LIST_REPORT");
+      } else if (changed) {
+        this.appendLogToFile("INFO", "AgentScan", `Syncing changed agent list`, { count: this.currentAgentIds.size, agents: Array.from(this.currentAgentIds) });
+        this.sendAgentListReport("AGENT_LIST_SYNC");
+      }
+
+    } catch (err: any) {
+      console.error(`[skill-logger-plugin][WS] Failed to scan agents:`, err);
+      this.appendLogToFile("ERROR", "AgentScan", `Failed to scan agents`, err);
+    }
+  }
+
+  private startHeartbeat() {
+    this.clearHeartbeat();
+    this.pingTimer = setInterval(() => {
+      const ws = this.ws;
+      if (!ws || ws.readyState !== WebSocket.OPEN) return;
+
+      const ackAge = Date.now() - this.lastServerAckAt;
+      if (ackAge > HEARTBEAT_ACK_TIMEOUT_MS) {
+        this.appendLogToFile("WARN", "Heartbeat", "Server heartbeat ACK timed out; terminating socket for reconnect", { ackAge });
+        ws.terminate();
+        return;
+      }
+
+      ws.ping();
+      this.sendClientHeartbeat();
+    }, HEARTBEAT_INTERVAL_MS);
+    this.sendClientHeartbeat();
+  }
+
+  private clearHeartbeat() {
+    if (this.pingTimer) {
+      clearInterval(this.pingTimer);
+      this.pingTimer = null;
+    }
+  }
+
+  private scheduleReconnect() {
+    if (this.isDestroyed || this.reconnectTimer) return;
+    
+    // 闭环完善：引入随机 Jitter 抖动，打散服务端重启时可能引发的瞬间重连风暴
+    const jitter = Math.floor(Math.random() * 5000);
+    const baseDelay = Math.min(30000, 2000 * Math.max(1, 2 ** this.reconnectAttempts));
+    const delay = baseDelay + jitter;
+    this.reconnectAttempts += 1;
+    
+    console.log(`[skill-logger-plugin][WS] Reconnecting in ${delay}ms...`);
+    this.appendLogToFile("INFO", "Connection", "Reconnect scheduled", { delay, attempt: this.reconnectAttempts });
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, delay);
+  }
+
+  private clearReconnectTimer() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+
+  private clearConnectTimeout() {
+    if (this.connectTimeoutTimer) {
+      clearTimeout(this.connectTimeoutTimer);
+      this.connectTimeoutTimer = null;
+    }
+  }
+
+  private terminateCurrentSocket(reason: string, payload?: any) {
+    const ws = this.ws;
+    if (!ws) return;
+    this.appendLogToFile("WARN", "Connection", `Terminating websocket: ${reason}`, payload);
+    try {
+      ws.terminate();
+    } catch (err) {
+      this.appendLogToFile("WARN", "Connection", "Terminate websocket failed", err);
+    }
+  }
+
+  private sendJson(payload: any, category: string) {
+    const ws = this.ws;
+    if (!ws || ws.readyState !== WebSocket.OPEN) return false;
+
+    try {
+      ws.send(JSON.stringify(payload), (err) => {
+        if (!err) return;
+        this.appendLogToFile("WARN", category, "WebSocket send failed", err);
+        if (this.ws === ws) {
+          this.terminateCurrentSocket("send_failed", { category, message: err.message });
+        }
+      });
+      return true;
+    } catch (err) {
+      this.appendLogToFile("WARN", category, "WebSocket send threw", err);
+      if (this.ws === ws) {
+        this.terminateCurrentSocket("send_threw", err);
+      }
+      return false;
+    }
+  }
+
+  private sendGatewayHello() {
+    this.sendJson({
+      type: "GATEWAY_HELLO",
+      gatewayId: this.options.gatewayId,
+      agentIds: Array.from(this.currentAgentIds),
+      clientTime: Date.now(),
+      supportsBatch: true,
+    }, "Heartbeat");
+  }
+
+  private sendClientHeartbeat() {
+    this.sendJson({
+      type: "CLIENT_HEARTBEAT",
+      gatewayId: this.options.gatewayId,
+      agentIds: Array.from(this.currentAgentIds),
+      clientTime: Date.now(),
+    }, "Heartbeat");
+  }
+
+  private sendAgentListReport(type: "AGENT_LIST_REPORT" | "AGENT_LIST_SYNC") {
+    this.sendJson({
+      type,
+      gatewayId: this.options.gatewayId,
+      agentIds: Array.from(this.currentAgentIds),
+      clientTime: Date.now(),
+    }, "AgentScan");
+  }
+  
+  private clearAgentScanTimer() {
+    if (this.agentScanTimer) {
+      clearInterval(this.agentScanTimer);
+      this.agentScanTimer = null;
+    }
+  }
+
+  /**
+   * 核心指令分发中心：完全跳过沙盒，基于 userId 直接进行底层物理文件操作
+   */
+  private async handleMessage(msg: any) {
+    const { action, userId, code, url, force, version, replyId, isBuiltIn } = msg;
+    this.appendLogToFile("INFO", "Command", `Received WS message`, {
+      action,
+      userId,
+      code,
+      version,
+      replyId,
+      isBuiltIn,
+      hasDirectUrl: Boolean(url),
+    });
+
+    if (!action || !userId) {
+      this.appendLogToFile("WARN", "Command", `Message dropped: missing action or userId`, msg);
+      return;
+    }
+
+    // 闭环完善：清理 code，并严格校验 userId，防止恶意指令通过 '../' 引发宿主机目录穿越攻击
+    const safeCode = code ? path.basename(code) : undefined;
+
+    // 100% 确定性安全寻址：userId 只接受纯数字或 assistant-数字，且数字至少 5 位。
+    const pureId = normalizeAssistantUserId(userId);
+    if (!pureId) {
+      this.reply(replyId, { success: false, message: `Invalid userId: ${userId}`, action });
+      return;
+    }
+    const targetDir = path.join(openclawHome(), `workspace-assistant-${pureId}`, "skills");
+
+    try {
+      if (action === "INSTALL_SKILL") {
+        if (!safeCode) throw new Error("Missing code parameter");
+        console.log(`[skill-logger-plugin][WS] Executing INSTALL for user ${userId}, code: ${safeCode}`);
+        this.appendLogToFile("INFO", "Command", `INSTALL_SKILL received`, { userId, code: safeCode, version });
+        const result = await this.options.updater.manualInstall({
+          code: safeCode,
+          url,
+          version,
+          force: force !== false,
+          targetDir,
+          trace: this.createInstallTrace({ action, replyId, userId, code: safeCode }),
+        });
+        this.reply(replyId, { success: result.success, message: result.message, action });
+
+      } else if (action === "UNINSTALL_SKILL") {
+        if (!safeCode) throw new Error("Missing code parameter");
+        console.log(`[skill-logger-plugin][WS] Executing UNINSTALL for user ${userId}, code: ${safeCode}`);
+        this.appendLogToFile("INFO", "Command", `UNINSTALL_SKILL received`, { userId, code: safeCode });
+        const skillPath = path.join(targetDir, safeCode);
+        await fs.rm(skillPath, { recursive: true, force: true });
+        this.reply(replyId, { success: true, message: `Skill ${safeCode} removed`, action });
+
+      } else if (action === "LIST_SKILLS") {
+        let list: any[] = [];
+        let targetDirExists = false;
+        try {
+          const targetStat = await fs.stat(targetDir);
+          targetDirExists = targetStat.isDirectory();
+        } catch (err: any) {
+          if (err?.code !== "ENOENT") throw err;
+        }
+        if (!targetDirExists) {
+          throw new Error(`Target skills directory does not exist: ${targetDir}`);
+        }
+
+        const entries = await fs.readdir(targetDir, { withFileTypes: true });
+        
+        const dirs = entries.filter(e => (e.isDirectory() || e.isSymbolicLink()) && !e.name.startsWith("."));
+        
+        for (const e of dirs) {
+          const skillDir = path.join(targetDir, e.name);
+          const skillMdPath = path.join(skillDir, 'SKILL.md');
+          
+          try {
+            const stat = await fs.stat(skillMdPath);
+            if (!stat.isFile()) continue;
+          } catch (err) {
+            continue;
+          }
+          
+          const metaPath = path.join(skillDir, '.meta.json');
+          let isPlatform = false;
+          let isBuiltIn = e.isSymbolicLink();
+          let metaData: any = null;
+          let name = e.name;
+          let description = "";
+          let skillVersion = "";
+
+          try {
+            const mdContent = await fs.readFile(skillMdPath, 'utf8');
+            const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(mdContent)?.[1] ?? "";
+            const parsedName = /(^|\n)name:\s*(.+)/.exec(fm)?.[2]?.trim();
+            if (parsedName) name = parsedName;
+
+            const descMatch = /(^|\n)description:\s*(?:>\s*\n\s*)?(.*?)(?=\n[a-z]+:|\n---|$)/is.exec(fm);
+            if (descMatch && descMatch[2]) {
+               description = descMatch[2].replace(/\n\s+/g, ' ').trim();
+            }
+          } catch (err) {}
+          
+          try {
+            const metaContent = await fs.readFile(metaPath, 'utf8');
+            const parsed = JSON.parse(metaContent);
+            if (parsed) {
+              if (parsed.ownerId === 'CMS' || parsed.ownerId === 'CMS_COMPAT') isPlatform = true;
+              if (parsed.isBuiltIn === true || parsed.ownerId === 'built-in') isBuiltIn = true;
+              metaData = parsed;
+            }
+          } catch (err) {}
+
+          const resolvedVersion = await readSkillVersion(skillDir);
+          if (resolvedVersion) skillVersion = resolvedVersion;
+          
+          if (isPlatform) {
+            list.push({
+              code: e.name,
+              isPlatform: true,
+              isBuiltIn: isBuiltIn,
+              version: skillVersion,
+              name,
+              description,
+              publishedAt: metaData?.publishedAt
+            });
+          } else {
+            list.push({
+              code: e.name,
+              isPlatform: false,
+              isBuiltIn: isBuiltIn,
+              version: skillVersion,
+              name: name,
+              description: description
+            });
+          }
+        }
+        this.reply(replyId, { success: true, data: list, action });
+
+      } else if (action === "UPDATE_SKILL") {
+        if (!safeCode) throw new Error("Missing code parameter");
+        // 更新可能是大批量广播，增加防阻塞的随机延时 (0~5秒)
+        const delayMs = Math.random() * 5000;
+        const syncBuiltInTemplate = shouldSyncBuiltInTemplate(action, isBuiltIn);
+        console.log(`[skill-logger-plugin][WS] Scheduled UPDATE for user ${userId}, code: ${safeCode} in ${Math.round(delayMs)}ms`);
+        this.appendLogToFile("INFO", "Command", `Scheduled UPDATE_SKILL`, {
+          userId,
+          code: safeCode,
+          version,
+          isBuiltIn,
+          syncBuiltInTemplate,
+          delayMs: Math.round(delayMs),
+        });
+        
+        setTimeout(async () => {
+          try {
+            const additionalTargetDirs = syncBuiltInTemplate
+              ? [path.join(openclawHome(), "workspace-xgjk-assistant-template", "skills")]
+              : [];
+            const result = await this.options.updater.manualInstall({
+              code: safeCode,
+              url,
+              version,
+              force: true,
+              targetDir,
+              additionalTargetDirs,
+              trace: this.createInstallTrace({
+                action,
+                replyId,
+                userId,
+                code: safeCode,
+                isBuiltIn,
+                syncBuiltInTemplate,
+              }),
+            });
+            this.appendLogToFile(result.success ? "INFO" : "ERROR", "Command", `UPDATE_SKILL completed`, {
+              userId,
+              code: safeCode,
+              replyId,
+              success: result.success,
+              message: result.message,
+              syncBuiltInTemplate,
+            });
+            if (replyId) {
+              this.reply(replyId, { success: result.success, message: result.message, action });
+            }
+          } catch (e: any) {
+            this.appendLogToFile("ERROR", "Command", `UPDATE_SKILL threw`, {
+              userId,
+              code: safeCode,
+              replyId,
+              message: e?.message || String(e),
+              stack: e?.stack,
+            });
+            if (replyId) this.reply(replyId, { success: false, message: e.message, action });
+          }
+        }, delayMs);
+
+      } else if (action === "INSTALL_EXPERT") {
+        if (!safeCode) throw new Error("Missing code parameter");
+        const { name, version, downloadUrl, skills } = msg;
+        console.log(`[skill-logger-plugin][WS] Executing INSTALL_EXPERT for user ${userId}, code: ${safeCode}`);
+        this.appendLogToFile("INFO", "Command", `INSTALL_EXPERT received`, { userId, code: safeCode, version, downloadUrl });
+
+        const userSkillRoot = path.join(openclawHome(), `workspace-assistant-${pureId}`, ".user");
+
+        // 1. 检查当前版本，同版本跳过
+        const expertTarget = path.join(userSkillRoot, "experts", safeCode);
+        let skipInstall = false;
+        const metaPath = path.join(expertTarget, ".meta.json");
+        try {
+          const raw = await fs.readFile(metaPath, "utf-8");
+          const existing = JSON.parse(raw);
+          if (existing.version && existing.version === (version || '1.0.0')) {
+            skipInstall = true;
+          }
+        } catch {}
+
+        if (!skipInstall) {
+          await fs.mkdir(path.dirname(expertTarget), { recursive: true });
+          const expertResult = await this.options.updater.installZipFromUrl(downloadUrl, expertTarget);
+          if (!expertResult.success) {
+            throw new Error(`专家安装失败: ${expertResult.message}`);
+          }
+        }
+
+        // 写入/更新版本信息
+        const meta = { code: safeCode, name, version: version || '1.0.0', installedAt: Date.now() };
+        await fs.writeFile(metaPath, JSON.stringify(meta, null, 2));
+
+        // 2. 安装依赖的 skills
+        const skillTargetRoot = path.join(userSkillRoot, "skills");
+        await fs.mkdir(skillTargetRoot, { recursive: true });
+        const skillResults: string[] = [];
+        if (Array.isArray(skills)) {
+          for (const sk of skills) {
+            if (!sk.code || !sk.downloadUrl) {
+              skillResults.push(`${sk.code || 'unknown'}: 缺少下载地址`);
+              continue;
+            }
+            try {
+              const skTarget = path.join(skillTargetRoot, sk.code);
+              const result = await this.options.updater.installZipFromUrl(sk.downloadUrl, skTarget);
+              skillResults.push(`${sk.code}: ${result.success ? '成功' : '失败 - ' + result.message}`);
+            } catch (e: any) {
+              skillResults.push(`${sk.code}: 失败 - ${e.message}`);
+            }
+          }
+        }
+
+        this.reply(replyId, {
+          success: true,
+          message: `专家 ${safeCode} 安装完成`,
+          action,
+          data: { expertCode: safeCode, skills: skillResults },
+        });
+
+      } else if (action === "UNINSTALL_EXPERT") {
+        if (!safeCode) throw new Error("Missing code parameter");
+        console.log(`[skill-logger-plugin][WS] Executing UNINSTALL_EXPERT for user ${userId}, code: ${safeCode}`);
+        this.appendLogToFile("INFO", "Command", `UNINSTALL_EXPERT received`, { userId, code: safeCode });
+
+        const expertPath = path.join(openclawHome(), `workspace-assistant-${pureId}`, ".user", "experts", safeCode);
+        await fs.rm(expertPath, { recursive: true, force: true });
+
+        this.reply(replyId, { success: true, message: `专家 ${safeCode} 已卸载`, action });
+
+      } else if (action === "LIST_EXPERTS") {
+        console.log(`[skill-logger-plugin][WS] Executing LIST_EXPERTS for user ${userId}`);
+        this.appendLogToFile("INFO", "Command", `LIST_EXPERTS received`, { userId });
+
+        const expertsDir = path.join(openclawHome(), `workspace-assistant-${pureId}`, ".user", "experts");
+        const list: any[] = [];
+        try {
+          const stat = await fs.stat(expertsDir);
+          if (stat.isDirectory()) {
+            const entries = await fs.readdir(expertsDir, { withFileTypes: true });
+            for (const e of entries) {
+              if (!e.isDirectory()) continue;
+              const metaPath = path.join(expertsDir, e.name, ".meta.json");
+              try {
+                const raw = await fs.readFile(metaPath, "utf-8");
+                const meta = JSON.parse(raw);
+                list.push({
+                  code: meta.code || e.name,
+                  name: meta.name || e.name,
+                  version: meta.version || '',
+                  installedAt: meta.installedAt,
+                });
+              } catch {
+                list.push({ code: e.name, name: e.name, version: '' });
+              }
+            }
+          }
+        } catch {}
+        this.reply(replyId, { success: true, data: list, action });
+
+      } else {
+        console.warn(`[skill-logger-plugin][WS] Unknown action: ${action}`);
+        this.appendLogToFile("WARN", "Command", `Unknown action: ${action}`);
+        this.reply(replyId, { success: false, message: `Unknown action: ${action}`, action });
+      }
+    } catch (err: any) {
+      this.appendLogToFile("ERROR", "Command", `Error executing action ${action}`, err);
+      this.reply(replyId, { success: false, message: err.message, action });
+    }
+  }
+
+  private reply(replyId: string, payload: any) {
+    this.appendLogToFile("INFO", "Command", `Replying to command`, { replyId, payload });
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !replyId) {
+      this.appendLogToFile("WARN", "Command", `Cannot reply: WS closed or missing replyId`, { replyId });
+      return;
+    }
+    this.ws.send(JSON.stringify({ type: "REPLY", replyId, ...payload }), (err) => {
+      if (err) {
+        this.appendLogToFile("ERROR", "Command", `Reply send failed`, { replyId, message: err.message });
+        return;
+      }
+      this.appendLogToFile("INFO", "Command", `Reply sent`, { replyId });
+    });
+  }
+
+  public destroy() {
+    this.isDestroyed = true;
+    this.clearReconnectTimer();
+    this.clearAgentScanTimer();
+    this.clearHeartbeat();
+    this.clearConnectTimeout();
+    if (this.ws) {
+      this.ws.terminate(); // 强行销毁，斩断半开连接残留
+      this.ws = null;
+    }
+  }
+}