@spzhongwin/skill-logger-plugin 1.0.17 → 1.0.19

package/src/ws-client.test.ts

@@ -5,6 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import {
+  GatewayWsClient,
   normalizeAssistantUserId,
   normalizeCommandCode,
   enabledAgentIdsFromAccounts,
@@ -13,8 +14,155 @@ import {
   readCronJobsByAgentId,
   findInstalledExpertSkillsRoot,
   shouldSyncBuiltInTemplate,
+  resolveGatewaySkillTarget,
+  isGatewaySkillCommand,
 } from "./ws-client.ts";
 
+async function handleClientMessage(
+  client: GatewayWsClient,
+  message: Record<string, unknown>,
+): Promise<void> {
+  await (client as unknown as { handleMessage(value: Record<string, unknown>): Promise<void> }).handleMessage(message);
+}
+
+function createReplyingClient(gatewayId: string): { client: GatewayWsClient; replies: Record<string, unknown>[] } {
+  const replies: Record<string, unknown>[] = [];
+  const client = new GatewayWsClient({
+    serverUrl: "ws://localhost:1",
+    gatewayId,
+    updater: {} as never,
+  });
+  const socket = {
+    readyState: 1,
+    send(payload: string, callback?: (error?: Error) => void) {
+      replies.push(JSON.parse(payload) as Record<string, unknown>);
+      callback?.();
+    },
+  };
+  Object.assign(client as object, { ws: socket });
+  return { client, replies };
+}
+
+describe("LIST_FREE_SKILLS", () => {
+  it("通过 action 分发扫描当前 workspace，并返回来源明确的路径字段", async () => {
+    const workspace = fs.mkdtempSync(path.join(os.tmpdir(), "free-skill-ws-client-"));
+    try {
+      const skillPath = path.join(workspace, ".xg-platform", "demo");
+      fs.mkdirSync(skillPath, { recursive: true });
+      fs.writeFileSync(
+        path.join(skillPath, "SKILL.md"),
+        "---\nname: Demo\ndescription: local demo\nversion: 1.2.3\n---\n",
+      );
+
+      const { client, replies } = createReplyingClient("gateway-local-1");
+      Object.assign(client as object, {
+        resolveRegularSkillContext: async () => ({
+          skillsDir: path.join(workspace, "skills"),
+          localAgentId: "sales-agent",
+          workspace,
+        }),
+      });
+      await handleClientMessage(client, {
+        action: "LIST_FREE_SKILLS",
+        userId: "12345",
+        agentId: "injected-agent-must-be-ignored",
+        workspace: path.join(workspace, "..", "external-workspace"),
+        replyId: "free-1",
+      });
+
+      const hostSkillFilePath = fs.realpathSync(path.join(skillPath, "SKILL.md"));
+      assert.deepEqual(replies, [{
+        type: "REPLY",
+        replyId: "free-1",
+        success: true,
+        action: "LIST_FREE_SKILLS",
+        data: {
+          gatewayId: "gateway-local-1",
+          agentId: "sales-agent",
+          directoryPath: fs.realpathSync(path.join(workspace, ".xg-platform")),
+          skills: [{
+            code: "demo",
+            name: "Demo",
+            description: "local demo",
+            version: "1.2.3",
+            workspaceRelativePath: path.join(".xg-platform", "demo"),
+            skillFilePath: path.join(".xg-platform", "demo", "SKILL.md"),
+            hostSkillFilePath,
+          }],
+        },
+      }]);
+    } finally {
+      fs.rmSync(workspace, { recursive: true, force: true });
+    }
+  });
+
+  it("忽略请求注入的外部 workspace 和 agentId，只使用解析出的 Agent workspace", async () => {
+    const workspace = fs.mkdtempSync(path.join(os.tmpdir(), "free-skill-resolved-ws-"));
+    const externalWorkspace = fs.mkdtempSync(path.join(os.tmpdir(), "free-skill-injected-ws-"));
+    try {
+      const safeSkillPath = path.join(workspace, ".xg-platform", "safe");
+      fs.mkdirSync(safeSkillPath, { recursive: true });
+      fs.writeFileSync(path.join(safeSkillPath, "SKILL.md"), "---\nname: Safe\n---\n");
+
+      const externalSkillPath = path.join(externalWorkspace, ".xg-platform", "outside");
+      fs.mkdirSync(externalSkillPath, { recursive: true });
+      fs.writeFileSync(path.join(externalSkillPath, "SKILL.md"), "---\nname: Outside\n---\n");
+
+      const { client, replies } = createReplyingClient("gateway-local-2");
+      Object.assign(client as object, {
+        resolveRegularSkillContext: async () => ({
+          skillsDir: path.join(workspace, "skills"),
+          localAgentId: "resolved-agent",
+          workspace,
+        }),
+      });
+      await handleClientMessage(client, {
+        action: "LIST_FREE_SKILLS",
+        userId: "12345",
+        agentId: "injected-agent",
+        workspace: externalWorkspace,
+        workspacePath: externalWorkspace,
+        agentWorkspace: externalWorkspace,
+        replyId: "free-isolated",
+      });
+
+      const response = replies[0] as { data: Record<string, unknown> };
+      assert.equal(response.data.agentId, "resolved-agent");
+      assert.equal(response.data.directoryPath, fs.realpathSync(path.join(workspace, ".xg-platform")));
+      assert.deepEqual(response.data.skills, [{
+        code: "safe",
+        name: "Safe",
+        description: "",
+        version: "",
+        workspaceRelativePath: path.join(".xg-platform", "safe"),
+        skillFilePath: path.join(".xg-platform", "safe", "SKILL.md"),
+        hostSkillFilePath: fs.realpathSync(path.join(safeSkillPath, "SKILL.md")),
+      }]);
+    } finally {
+      fs.rmSync(workspace, { recursive: true, force: true });
+      fs.rmSync(externalWorkspace, { recursive: true, force: true });
+    }
+  });
+
+  it("缺少 userId 时返回明确错误，不静默丢弃新 action", async () => {
+    const { client, replies } = createReplyingClient("gateway-local-1");
+
+    await handleClientMessage(client, {
+      action: "LIST_FREE_SKILLS",
+      replyId: "free-missing-user",
+    });
+
+    assert.deepEqual(replies, [{
+      type: "REPLY",
+      replyId: "free-missing-user",
+      success: false,
+      error: "INVALID_REQUEST",
+      message: "Missing userId parameter",
+      action: "LIST_FREE_SKILLS",
+    }]);
+  });
+});
+
 describe("command code boundary", () => {
   it("只接受单一路径段，不静默改写路径穿越输入", () => {
     assert.equal(normalizeCommandCode("demo-skill"), "demo-skill");
@@ -156,6 +304,20 @@ describe("built-in template update boundary", () => {
   });
 });
 
+describe("Gateway 公共 Skill 安装边界", () => {
+  it("固定安装到 OpenClaw 顶层 skills，不接受指令传入任意目录", () => {
+    assert.equal(resolveGatewaySkillTarget("/var/openclaw"), "/var/openclaw/skills");
+  });
+
+  it("仅允许 Skill 安装、更新和卸载使用 gateway 作用域", () => {
+    assert.equal(isGatewaySkillCommand("INSTALL_SKILL", "gateway"), true);
+    assert.equal(isGatewaySkillCommand("UPDATE_SKILL", "gateway"), true);
+    assert.equal(isGatewaySkillCommand("UNINSTALL_SKILL", "gateway"), true);
+    assert.equal(isGatewaySkillCommand("LIST_SKILLS", "gateway"), false);
+    assert.equal(isGatewaySkillCommand("UPDATE_SKILL", "agent"), false);
+  });
+});
+
 describe("expert skill update target", () => {
   it("返回 .user/skills 父目录，由安装器统一追加 skill code", async () => {
     const root = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-expert-skill-"));

package/src/ws-client.ts

@@ -5,6 +5,7 @@ import { DatabaseSync } from "node:sqlite";
 import { SkillUpdater } from "./updater.ts";
 import { openclawHome } from "./paths.ts";
 import { readSkillVersion } from "./skill-version.ts";
+import { scanFreeSkillDirectory, type FreeSkill } from "./free-skill-directory.ts";
 
 const HEARTBEAT_INTERVAL_MS = 30_000;
 const HEARTBEAT_ACK_TIMEOUT_MS = 75_000;
@@ -140,6 +141,15 @@ export function shouldSyncBuiltInTemplate(action: string, isBuiltIn: unknown): b
   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,
@@ -175,6 +185,73 @@ export function readCronJobsByAgentId(
   }
 }
 
+export type FreeSkillDirectorySkill = Pick<FreeSkill, "code" | "name" | "description" | "version"> & {
+  workspaceRelativePath: string;
+  skillFilePath: string;
+  hostSkillFilePath: string;
+};
+
+export type FreeSkillDirectoryResponse = {
+  gatewayId: string;
+  agentId: string;
+  directoryPath: string;
+  skills: FreeSkillDirectorySkill[];
+};
+
+function isWithinPath(parent: string, candidate: string): boolean {
+  const relative = path.relative(parent, candidate);
+  return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+function relativeWorkspacePath(workspace: string, target: string): string {
+  const relative = path.relative(workspace, target);
+  return isWithinPath(workspace, target) ? relative : "";
+}
+
+async function resolveRealWorkspace(workspace: string): Promise<string> {
+  const resolved = path.resolve(workspace);
+  try {
+    return await fs.realpath(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+async function resolveFreeSkillDirectoryPath(workspace: string): Promise<string> {
+  const workspacePath = await resolveRealWorkspace(workspace);
+  const candidate = path.resolve(workspacePath, ".xg-platform");
+  try {
+    const directoryPath = await fs.realpath(candidate);
+    const stat = await fs.stat(directoryPath);
+    return stat.isDirectory() && isWithinPath(workspacePath, directoryPath) ? directoryPath : "";
+  } catch {
+    return "";
+  }
+}
+
+function buildFreeSkillDirectoryResponse(
+  gatewayId: string,
+  agentId: string,
+  workspacePath: string,
+  directoryPath: string,
+  skills: FreeSkill[],
+): FreeSkillDirectoryResponse {
+  return {
+    gatewayId,
+    agentId,
+    directoryPath,
+    skills: skills.map((skill) => ({
+      code: skill.code,
+      name: skill.name,
+      description: skill.description,
+      version: skill.version,
+      workspaceRelativePath: relativeWorkspacePath(workspacePath, skill.skillPath),
+      skillFilePath: relativeWorkspacePath(workspacePath, skill.skillFilePath),
+      hostSkillFilePath: skill.skillFilePath,
+    })),
+  };
+}
+
 export interface WsClientOptions {
   serverUrl: string;       // 例如: wss://api.aishuo.co/gateway/ws
   authToken?: string;      // 用于网关鉴权
@@ -230,16 +307,28 @@ export class GatewayWsClient {
     };
   }
 
-  /** 普通 Skill 的所有读写操作共用这一个配置驱动的寻址入口。 */
-  private async resolveRegularSkillTarget(userId: string): Promise<string> {
+  private async readOpenclawConfig(): Promise<unknown> {
     const configPath = path.join(openclawHome(), "openclaw.json");
-    let config: unknown;
     try {
-      config = JSON.parse(await fs.readFile(configPath, "utf-8"));
+      return 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;
+  }
+
+  private async resolveRegularSkillContext(userId: string): Promise<SkillInstallTarget & { workspace: string }> {
+    const target = resolveSkillInstallTarget(await this.readOpenclawConfig(), userId);
+    return { ...target, workspace: path.dirname(target.skillsDir) };
+  }
+
+  /** 普通 Skill 的所有读写操作共用这一个配置驱动的寻址入口。 */
+  private async resolveRegularSkillTarget(userId: string): Promise<string> {
+    return (await this.resolveRegularSkillContext(userId)).skillsDir;
+  }
+
+  private async resolveFreeSkillRequestContext(userId: string): Promise<{ workspace: string; agentId: string }> {
+    const target = await this.resolveRegularSkillContext(userId);
+    return { workspace: target.workspace, agentId: target.localAgentId };
   }
 
   constructor(options: WsClientOptions) {
@@ -505,6 +594,7 @@ export class GatewayWsClient {
       agentIds: Array.from(this.currentAgentIds),
       clientTime: Date.now(),
       supportsBatch: true,
+      supportsGatewaySkillScope: true,
     }, "Heartbeat");
   }
 
@@ -537,7 +627,7 @@ export class GatewayWsClient {
    * 核心指令分发中心：完全跳过沙盒，基于 userId 直接进行底层物理文件操作
    */
   private async handleMessage(msg: any) {
-    const { action, userId, code, url, force, version, replyId, isBuiltIn } = msg;
+    const { action, userId, code, url, force, version, replyId, isBuiltIn, installScope } = msg;
     this.appendLogToFile("INFO", "Command", `Received WS message`, {
       action,
       userId,
@@ -545,6 +635,7 @@ export class GatewayWsClient {
       version,
       replyId,
       isBuiltIn,
+      installScope,
       hasDirectUrl: Boolean(url),
     });
 
@@ -577,6 +668,14 @@ export class GatewayWsClient {
 
     if (!userId) {
       this.appendLogToFile("WARN", "Command", `Message dropped: missing userId`, msg);
+      if (action === "LIST_FREE_SKILLS") {
+        this.reply(replyId, {
+          success: false,
+          error: "INVALID_REQUEST",
+          message: "Missing userId parameter",
+          action,
+        });
+      }
       return;
     }
 
@@ -587,16 +686,19 @@ export class GatewayWsClient {
       return;
     }
 
-    // 100% 确定性安全寻址：userId 只接受纯数字或 assistant-数字，且数字至少 5 位。
-    const pureId = normalizeAssistantUserId(userId);
-    if (!pureId) {
+    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 = await this.resolveRegularSkillTarget(userId);
+        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({
@@ -607,113 +709,126 @@ export class GatewayWsClient {
           targetDir,
           trace: this.createInstallTrace({ action, replyId, userId, code: safeCode }),
         });
-        this.reply(replyId, { success: result.success, message: result.message, action });
+        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 = await this.resolveRegularSkillTarget(userId);
+        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 });
+        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 targetDir = await this.resolveRegularSkillTarget(userId);
-        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}`);
-        }
+      } else if (action === "LIST_FREE_SKILLS") {
+        const context = await this.resolveFreeSkillRequestContext(userId);
+        const workspacePath = await resolveRealWorkspace(context.workspace);
+        const scannedSkills = await scanFreeSkillDirectory(context.workspace);
+        const directoryPath = scannedSkills[0]?.directoryPath
+          || await resolveFreeSkillDirectoryPath(context.workspace);
+        const data = buildFreeSkillDirectoryResponse(
+          this.options.gatewayId,
+          context.agentId,
+          workspacePath,
+          directoryPath,
+          scannedSkills,
+        );
+        this.reply(replyId, { success: true, data, action });
 
-        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');
-          
+      } 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 {
-            const stat = await fs.stat(skillMdPath);
-            if (!stat.isFile()) continue;
-          } catch (err) {
-            continue;
+            entries = await fs.readdir(source.dir, {withFileTypes: true});
+          } catch (err: any) {
+            // 新用户的 Agent 私有目录尚未创建时，仍必须返回 Gateway 公共内置 Skill。
+            if (err?.code === "ENOENT") continue;
+            throw err;
           }
-          
-          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();
+          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;
             }
-          } 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;
+
+            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,
+              });
             }
-          } 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 });
+        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 = shouldSyncBuiltInTemplate(action, isBuiltIn);
+        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),
         });
@@ -721,13 +836,17 @@ export class GatewayWsClient {
         setTimeout(async () => {
           try {
             // 延时期间配置可能变化；在真正写盘前重新校验 enabled 与 workspace。
-            const targetDir = await this.resolveRegularSkillTarget(userId);
+            const targetDir = gatewaySkillCommand
+              ? resolveGatewaySkillTarget()
+              : await this.resolveRegularSkillTarget(userId);
             const additionalTargetDirs: string[] = syncBuiltInTemplate
               ? [path.join(openclawHome(), "workspace-xgjk-assistant-template", "skills")]
               : [];
 
             // 同步更新用户的 expert skill 目录
-            const userSkillRoot = await findInstalledExpertSkillsRoot(openclawHome(), pureId, safeCode);
+            const userSkillRoot = pureId
+              ? await findInstalledExpertSkillsRoot(openclawHome(), pureId, safeCode)
+              : undefined;
             if (userSkillRoot) additionalTargetDirs.push(userSkillRoot);
             const result = await this.options.updater.manualInstall({
               code: safeCode,
@@ -754,7 +873,10 @@ export class GatewayWsClient {
               syncBuiltInTemplate,
             });
             if (replyId) {
-              this.reply(replyId, { success: result.success, message: result.message, action });
+              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`, {
@@ -880,7 +1002,17 @@ export class GatewayWsClient {
       } 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 });
+        if (action === "LIST_FREE_SKILLS") {
+          this.reply(replyId, {
+            success: false,
+            unsupported: true,
+            error: "UNSUPPORTED_ACTION",
+            message: "LIST_FREE_SKILLS unsupported by this plugin",
+            action,
+          });
+        } else {
+          this.reply(replyId, { success: false, message: `Unknown action: ${action}`, action });
+        }
       }
     } catch (err: any) {
       this.appendLogToFile("ERROR", "Command", `Error executing action ${action}`, err);