@spzhongwin/skill-logger-plugin 1.0.16 → 1.0.18

package/src/ws-client.ts

@@ -1,805 +1,936 @@
-import WebSocket from "ws";
-import path from "path";
-import fs from "fs/promises";
-import { DatabaseSync } from "node:sqlite";
-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 normalizeCommandCode(code: unknown): string | undefined {
-  if (typeof code !== "string" || code.length === 0 || code === "." || code === "..") return undefined;
-  if (code.includes("/") || code.includes("\\") || code.includes("\0")) return undefined;
-  if (path.basename(code) !== code) return undefined;
-  return code;
-}
-
-export function shouldSyncBuiltInTemplate(action: string, isBuiltIn: unknown): boolean {
-  return action === "UPDATE_SKILL" && isBuiltIn === true;
-}
-
-export async function findInstalledExpertSkillsRoot(
-  rootPath: string,
-  pureId: string,
-  code: string
-): Promise<string | undefined> {
-  const skillsRoot = path.join(rootPath, `workspace-assistant-${pureId}`, ".user", "skills");
-  try {
-    const stat = await fs.stat(path.join(skillsRoot, code));
-    return stat.isDirectory() ? skillsRoot : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-export function defaultOpenclawSqlitePath(): string {
-  return path.join(openclawHome(), "state", "openclaw.sqlite");
-}
-
-export function readCronJobsByAgentId(
-  agentId: string,
-  sqlitePath = defaultOpenclawSqlitePath(),
-  onError?: (err: unknown) => void
-): any[] {
-  let db: DatabaseSync | undefined;
-  try {
-    db = new DatabaseSync(sqlitePath, { readOnly: true });
-    return db.prepare("SELECT * FROM cron_jobs WHERE agent_id = ?").all(agentId);
-  } catch (err) {
-    onError?.(err);
-    return [];
-  } finally {
-    db?.close();
-  }
-}
-
-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) {
-      this.appendLogToFile("WARN", "Command", `Message dropped: missing action`, msg);
-      return;
-    }
-
-    if (action === "GET_CRON_JOBS_BY_AGENT_ID") {
-      const agentId = typeof msg.agent_id === "string"
-        ? msg.agent_id
-        : typeof msg.agentId === "string"
-          ? msg.agentId
-          : userId;
-      if (!agentId) {
-        this.reply(replyId, { success: false, message: "Missing agent_id parameter", action });
-        return;
-      }
-      try {
-        const data = readCronJobsByAgentId(agentId, defaultOpenclawSqlitePath(), (err) => {
-          this.appendLogToFile("WARN", "Command", `GET_CRON_JOBS_BY_AGENT_ID sqlite lookup skipped`, err);
-        });
-        this.reply(replyId, { success: true, data, action });
-      } catch (err: any) {
-        this.appendLogToFile("ERROR", "Command", `GET_CRON_JOBS_BY_AGENT_ID threw`, err);
-        this.reply(replyId, { success: false, message: err.message, action });
-      }
-      return;
-    }
-
-    if (!userId) {
-      this.appendLogToFile("WARN", "Command", `Message dropped: missing userId`, msg);
-      return;
-    }
-
-    // code 必须是单一路径段；不允许通过 basename 静默改写恶意输入。
-    const safeCode = normalizeCommandCode(code);
-    if (code !== undefined && !safeCode) {
-      this.reply(replyId, { success: false, message: `Invalid code: ${String(code)}`, action });
-      return;
-    }
-
-    // 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: string[] = syncBuiltInTemplate
-              ? [path.join(openclawHome(), "workspace-xgjk-assistant-template", "skills")]
-              : [];
-
-            // 同步更新用户的 expert skill 目录
-            const userSkillRoot = await findInstalledExpertSkillsRoot(openclawHome(), pureId, safeCode);
-            if (userSkillRoot) additionalTargetDirs.push(userSkillRoot);
-            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.installExpertZipFromUrl(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) {
-            const skillCode = normalizeCommandCode(sk?.code);
-            if (!skillCode) {
-              skillResults.push(`${String(sk?.code || 'unknown')}: 失败 - 非法的 Skill code`);
-              continue;
-            }
-            if (!sk.downloadUrl) {
-              skillResults.push(`${skillCode}: 失败 - 缺少下载地址`);
-              continue;
-            }
-            try {
-              const result = await this.options.updater.manualInstall({
-                code: skillCode,
-                url: sk.downloadUrl,
-                version: sk.version,
-                force: true,
-                targetDir: skillTargetRoot,
-              });
-              skillResults.push(`${skillCode}: ${result.success ? '成功' : '失败 - ' + result.message}`);
-            } catch (e: any) {
-              skillResults.push(`${skillCode}: 失败 - ${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;
-    }
-  }
-}
+import WebSocket from "ws";
+import path from "path";
+import fs from "fs/promises";
+import { DatabaseSync } from "node:sqlite";
+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,}$/;
+
+type OpenClawAccount = {
+  agentId?: unknown;
+  enabled?: unknown;
+};
+
+type SkillInstallTarget = {
+  /** 普通 Skill 的安装根目录。 */
+  skillsDir: string;
+  /** 解析出的本地 OpenClaw agent，便于日志与后续专家链路复用。 */
+  localAgentId: string;
+};
+
+/**
+ * 从 `channels.xg_cwork_im.accounts` 提取应上报给中控的 agent ID。
+ *
+ * `enabled: false` 是唯一的禁用标识；旧配置未填写 enabled 时维持原有可用语义。
+ * 没有有效 agentId 的配置项（例如 default）不会被上报。
+ */
+export function enabledAgentIdsFromAccounts(config: unknown): string[] {
+  if (!config || typeof config !== "object") return [];
+
+  const channels = (config as { channels?: unknown }).channels;
+  if (!channels || typeof channels !== "object") return [];
+  const cworkConfig = (channels as { xg_cwork_im?: unknown }).xg_cwork_im;
+  if (!cworkConfig || typeof cworkConfig !== "object") return [];
+  const accounts = (cworkConfig as { accounts?: unknown }).accounts;
+  if (!accounts || typeof accounts !== "object" || Array.isArray(accounts)) return [];
+
+  const agentIds = new Set<string>();
+  for (const account of Object.values(accounts as Record<string, OpenClawAccount>)) {
+    if (!account || typeof account !== "object" || account.enabled === false) continue;
+    if (typeof account.agentId !== "string") continue;
+    const agentId = account.agentId.trim();
+    if (agentId) agentIds.add(agentId);
+  }
+  return [...agentIds];
+}
+
+/**
+ * 根据 OpenClaw 配置解析普通 Skill 的安装目录。
+ *
+ * 只有同时满足以下条件才返回目标目录：
+ * 1. xg_cwork_im 中存在 `agentId === userId` 的 account；
+ * 2. account 没有显式 disabled；
+ * 3. account（或它的 binding）映射到一个配置了 workspace 的本地 agent。
+ *
+ * 这里故意不回退到 `workspace-assistant-<id>` 命名规则。配置缺失时拒绝执行，
+ * 防止禁用或已迁移 workspace 的用户仍被写入历史目录。
+ */
+export function resolveSkillInstallTarget(config: unknown, userId: string): SkillInstallTarget {
+  if (!config || typeof config !== "object") throw new Error("openclaw.json 配置无效");
+  const root = config as {
+    channels?: { xg_cwork_im?: { accounts?: unknown } };
+    bindings?: unknown;
+    agents?: { defaults?: { workspace?: unknown }; list?: unknown };
+  };
+  const accounts = root.channels?.xg_cwork_im?.accounts;
+  if (!accounts || typeof accounts !== "object" || Array.isArray(accounts)) {
+    throw new Error(`未找到 userId=${userId} 的 xg_cwork_im account`);
+  }
+
+  const matched = Object.entries(accounts as Record<string, OpenClawAccount>)
+    .filter(([, account]) => account && typeof account === "object" && account.agentId === userId);
+  if (matched.length !== 1) {
+    throw new Error(matched.length > 1
+      ? `userId=${userId} 存在多个 xg_cwork_im account，无法确定安装目录`
+      : `未找到 userId=${userId} 的 xg_cwork_im account`);
+  }
+  const [accountId, account] = matched[0];
+  if (account.enabled === false) throw new Error(`userId=${userId} 对应 Agent 已禁用`);
+
+  // 规范配置以 binding 决定本地 agent；兼容历史配置中 account key/agentId 作为 accountId 的写法。
+  const bindingAccountIds = new Set([accountId, userId]);
+  const bindings = Array.isArray(root.bindings) ? root.bindings : [];
+  const binding = bindings.find((item): item is { agentId?: unknown; match?: { channel?: unknown; accountId?: unknown } } => {
+    if (!item || typeof item !== "object") return false;
+    const candidate = item as { agentId?: unknown; match?: { channel?: unknown; accountId?: unknown } };
+    return candidate.match?.channel === "xg_cwork_im"
+      && typeof candidate.match.accountId === "string"
+      && bindingAccountIds.has(candidate.match.accountId)
+      && typeof candidate.agentId === "string"
+      && candidate.agentId.length > 0;
+  });
+  const localAgentId = typeof binding?.agentId === "string" ? binding.agentId : userId;
+
+  const list = Array.isArray(root.agents?.list) ? root.agents.list : [];
+  const agent = list.find((item): item is { id?: unknown; workspace?: unknown } =>
+    Boolean(item) && typeof item === "object" && (item as { id?: unknown }).id === localAgentId,
+  );
+  if (!agent) throw new Error(`未找到本地 Agent 配置: ${localAgentId}`);
+  const workspace = typeof agent.workspace === "string"
+    ? agent.workspace
+    : root.agents?.defaults?.workspace;
+  if (typeof workspace !== "string" || !workspace.trim()) {
+    throw new Error(`本地 Agent ${localAgentId} 未配置 workspace`);
+  }
+  return { skillsDir: path.join(workspace, "skills"), localAgentId };
+}
+
+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 normalizeCommandCode(code: unknown): string | undefined {
+  if (typeof code !== "string" || code.length === 0 || code === "." || code === "..") return undefined;
+  if (code.includes("/") || code.includes("\\") || code.includes("\0")) return undefined;
+  if (path.basename(code) !== code) return undefined;
+  return code;
+}
+
+export function shouldSyncBuiltInTemplate(action: string, isBuiltIn: unknown): boolean {
+  return action === "UPDATE_SKILL" && isBuiltIn === true;
+}
+
+export function resolveGatewaySkillTarget(home = openclawHome()): string {
+  return path.join(home, "skills");
+}
+
+export function isGatewaySkillCommand(action: unknown, installScope: unknown): boolean {
+  return installScope === "gateway"
+    && ["INSTALL_SKILL", "UPDATE_SKILL", "UNINSTALL_SKILL"].includes(String(action || ""));
+}
+
+export async function findInstalledExpertSkillsRoot(
+  rootPath: string,
+  pureId: string,
+  code: string
+): Promise<string | undefined> {
+  const skillsRoot = path.join(rootPath, `workspace-assistant-${pureId}`, ".user", "skills");
+  try {
+    const stat = await fs.stat(path.join(skillsRoot, code));
+    return stat.isDirectory() ? skillsRoot : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function defaultOpenclawSqlitePath(): string {
+  return path.join(openclawHome(), "state", "openclaw.sqlite");
+}
+
+export function readCronJobsByAgentId(
+  agentId: string,
+  sqlitePath = defaultOpenclawSqlitePath(),
+  onError?: (err: unknown) => void
+): any[] {
+  let db: DatabaseSync | undefined;
+  try {
+    db = new DatabaseSync(sqlitePath, { readOnly: true });
+    return db.prepare("SELECT * FROM cron_jobs WHERE agent_id = ?").all(agentId);
+  } catch (err) {
+    onError?.(err);
+    return [];
+  } finally {
+    db?.close();
+  }
+}
+
+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,
+      });
+    };
+  }
+
+  /** 普通 Skill 的所有读写操作共用这一个配置驱动的寻址入口。 */
+  private async resolveRegularSkillTarget(userId: string): Promise<string> {
+    const configPath = path.join(openclawHome(), "openclaw.json");
+    let config: unknown;
+    try {
+      config = JSON.parse(await fs.readFile(configPath, "utf-8"));
+    } catch (err: any) {
+      throw new Error(`无法读取 openclaw.json: ${err?.message || String(err)}`);
+    }
+    return resolveSkillInstallTarget(config, userId).skillsDir;
+  }
+
+  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.json 的 xg_cwork_im accounts 读取当前启用的 agent。 */
+  private async scanAndReportAgents(isInitialReport: boolean) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+    
+    try {
+      const configPath = path.join(openclawHome(), "openclaw.json");
+      let rawConfig: string;
+      try {
+        rawConfig = await fs.readFile(configPath, "utf-8");
+      } catch (e) {
+        // 配置文件临时不可读时，保留上次成功读取的列表，避免把所有用户误报为离线。
+        this.appendLogToFile("WARN", "AgentScan", "OpenClaw config is not readable; skipping this scan cycle", e);
+        return;
+      }
+
+      let config: unknown;
+      try {
+        config = JSON.parse(rawConfig);
+      } catch (e) {
+        this.appendLogToFile("WARN", "AgentScan", "OpenClaw config is invalid JSON; skipping this scan cycle", e);
+        return;
+      }
+      const newAgentIds = new Set(enabledAgentIdsFromAccounts(config));
+
+      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,
+      supportsGatewaySkillScope: 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, installScope } = msg;
+    this.appendLogToFile("INFO", "Command", `Received WS message`, {
+      action,
+      userId,
+      code,
+      version,
+      replyId,
+      isBuiltIn,
+      installScope,
+      hasDirectUrl: Boolean(url),
+    });
+
+    if (!action) {
+      this.appendLogToFile("WARN", "Command", `Message dropped: missing action`, msg);
+      return;
+    }
+
+    if (action === "GET_CRON_JOBS_BY_AGENT_ID") {
+      const agentId = typeof msg.agent_id === "string"
+        ? msg.agent_id
+        : typeof msg.agentId === "string"
+          ? msg.agentId
+          : userId;
+      if (!agentId) {
+        this.reply(replyId, { success: false, message: "Missing agent_id parameter", action });
+        return;
+      }
+      try {
+        const data = readCronJobsByAgentId(agentId, defaultOpenclawSqlitePath(), (err) => {
+          this.appendLogToFile("WARN", "Command", `GET_CRON_JOBS_BY_AGENT_ID sqlite lookup skipped`, err);
+        });
+        this.reply(replyId, { success: true, data, action });
+      } catch (err: any) {
+        this.appendLogToFile("ERROR", "Command", `GET_CRON_JOBS_BY_AGENT_ID threw`, err);
+        this.reply(replyId, { success: false, message: err.message, action });
+      }
+      return;
+    }
+
+    if (!userId) {
+      this.appendLogToFile("WARN", "Command", `Message dropped: missing userId`, msg);
+      return;
+    }
+
+    // code 必须是单一路径段；不允许通过 basename 静默改写恶意输入。
+    const safeCode = normalizeCommandCode(code);
+    if (code !== undefined && !safeCode) {
+      this.reply(replyId, { success: false, message: `Invalid code: ${String(code)}`, action });
+      return;
+    }
+
+    const gatewaySkillCommand = isGatewaySkillCommand(action, installScope);
+    // Gateway 公共 Skill 命令不依赖 Agent。其余命令继续执行严格的用户目录寻址。
+    const pureId = gatewaySkillCommand ? undefined : normalizeAssistantUserId(userId);
+    if (!gatewaySkillCommand && !pureId) {
+      this.reply(replyId, { success: false, message: `Invalid userId: ${userId}`, action });
+      return;
+    }
+    try {
+      if (action === "INSTALL_SKILL") {
+        if (!safeCode) throw new Error("Missing code parameter");
+        const targetDir = gatewaySkillCommand
+          ? resolveGatewaySkillTarget()
+          : await this.resolveRegularSkillTarget(userId);
+        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,
+          data: {code: safeCode, version, installScope: gatewaySkillCommand ? "gateway" : "agent"},
+        });
+
+      } else if (action === "UNINSTALL_SKILL") {
+        if (!safeCode) throw new Error("Missing code parameter");
+        const targetDir = gatewaySkillCommand
+          ? resolveGatewaySkillTarget()
+          : await this.resolveRegularSkillTarget(userId);
+        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,
+          data: {code: safeCode, installScope: gatewaySkillCommand ? "gateway" : "agent", removed: true},
+        });
+
+      } else if (action === "LIST_SKILLS") {
+        const regularTargetDir = await this.resolveRegularSkillTarget(userId);
+
+        // 用户视角的有效 Skill = Agent workspace Skill + Gateway 顶层公共 Skill。
+        // 同 code 时公共内置版本后写覆盖，确保不会被快照差分误判为缺失。
+        const skillsByCode = new Map<string, any>();
+        const sources = [
+          {dir: regularTargetDir, gatewayBuiltIn: false},
+          {dir: resolveGatewaySkillTarget(), gatewayBuiltIn: true},
+        ];
+        for (const source of sources) {
+          let entries;
+          try {
+            entries = await fs.readdir(source.dir, {withFileTypes: true});
+          } catch (err: any) {
+            // 新用户的 Agent 私有目录尚未创建时，仍必须返回 Gateway 公共内置 Skill。
+            if (err?.code === "ENOENT") continue;
+            throw err;
+          }
+          const dirs = entries.filter(e => (e.isDirectory() || e.isSymbolicLink()) && !e.name.startsWith("."));
+          for (const e of dirs) {
+            const skillDir = path.join(source.dir, e.name);
+            const skillMdPath = path.join(skillDir, "SKILL.md");
+            try {
+              const stat = await fs.stat(skillMdPath);
+              if (!stat.isFile()) continue;
+            } catch {
+              continue;
+            }
+
+            const metaPath = path.join(skillDir, ".meta.json");
+            let isPlatform = source.gatewayBuiltIn;
+            let isBuiltIn = source.gatewayBuiltIn || 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?.[2]) description = descMatch[2].replace(/\n\s+/g, " ").trim();
+            } catch {}
+
+            try {
+              const parsed = JSON.parse(await fs.readFile(metaPath, "utf8"));
+              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 {}
+
+            const resolvedVersion = await readSkillVersion(skillDir);
+            if (resolvedVersion) skillVersion = resolvedVersion;
+
+            if (isPlatform) {
+              skillsByCode.set(e.name, {
+                code: e.name, isPlatform: true, isBuiltIn, version: skillVersion,
+                name, description, publishedAt: metaData?.publishedAt,
+              });
+            } else {
+              skillsByCode.set(e.name, {
+                code: e.name, isPlatform: false, isBuiltIn, version: skillVersion,
+                name, description,
+              });
+            }
+          }
+        }
+        this.reply(replyId, { success: true, data: [...skillsByCode.values()], action });
+
+      } else if (action === "UPDATE_SKILL") {
+        if (!safeCode) throw new Error("Missing code parameter");
+        // 更新可能是大批量广播，增加防阻塞的随机延时 (0~5秒)
+        const delayMs = Math.random() * 5000;
+        const syncBuiltInTemplate = !gatewaySkillCommand && 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,
+          installScope,
+          syncBuiltInTemplate,
+          delayMs: Math.round(delayMs),
+        });
+        
+        setTimeout(async () => {
+          try {
+            // 延时期间配置可能变化；在真正写盘前重新校验 enabled 与 workspace。
+            const targetDir = gatewaySkillCommand
+              ? resolveGatewaySkillTarget()
+              : await this.resolveRegularSkillTarget(userId);
+            const additionalTargetDirs: string[] = syncBuiltInTemplate
+              ? [path.join(openclawHome(), "workspace-xgjk-assistant-template", "skills")]
+              : [];
+
+            // 同步更新用户的 expert skill 目录
+            const userSkillRoot = pureId
+              ? await findInstalledExpertSkillsRoot(openclawHome(), pureId, safeCode)
+              : undefined;
+            if (userSkillRoot) additionalTargetDirs.push(userSkillRoot);
+            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,
+                data: {code: safeCode, version, installScope: gatewaySkillCommand ? "gateway" : "agent"},
+              });
+            }
+          } 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.installExpertZipFromUrl(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) {
+            const skillCode = normalizeCommandCode(sk?.code);
+            if (!skillCode) {
+              skillResults.push(`${String(sk?.code || 'unknown')}: 失败 - 非法的 Skill code`);
+              continue;
+            }
+            if (!sk.downloadUrl) {
+              skillResults.push(`${skillCode}: 失败 - 缺少下载地址`);
+              continue;
+            }
+            try {
+              const result = await this.options.updater.manualInstall({
+                code: skillCode,
+                url: sk.downloadUrl,
+                version: sk.version,
+                force: true,
+                targetDir: skillTargetRoot,
+              });
+              skillResults.push(`${skillCode}: ${result.success ? '成功' : '失败 - ' + result.message}`);
+            } catch (e: any) {
+              skillResults.push(`${skillCode}: 失败 - ${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;
+    }
+  }
+}