@spzhongwin/skill-logger-plugin 1.0.18 → 1.0.19

package/openclaw.plugin.json

@@ -5,6 +5,11 @@
   "activation": {
     "onStartup": true
   },
+  "contracts": {
+    "tools": [
+      "skill_logger_create_free_skill"
+    ]
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spzhongwin/skill-logger-plugin",
-  "version": "1.0.18",
+  "version": "1.0.19",
   "type": "module",
   "exports": "./dist/index.js",
   "scripts": {

package/src/free-skill-directory.test.ts

@@ -0,0 +1,109 @@
+import { afterEach, beforeEach, describe, it } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { scanFreeSkillDirectory } from "./free-skill-directory.ts";
+
+let workspace: string;
+
+beforeEach(async () => {
+  workspace = await fs.mkdtemp(path.join(os.tmpdir(), "free-skill-directory-"));
+});
+
+afterEach(async () => {
+  await fs.rm(workspace, { recursive: true, force: true });
+});
+
+async function writeSkill(
+  skillPath: string,
+  metadata: { name?: string; description?: string; version?: string } = {},
+): Promise<void> {
+  const lines = ["---"];
+  if (metadata.name) lines.push(`name: ${metadata.name}`);
+  if (metadata.description) lines.push(`description: ${metadata.description}`);
+  if (metadata.version) lines.push(`version: ${metadata.version}`);
+  lines.push("---", "", "# Skill");
+  await fs.mkdir(skillPath, { recursive: true });
+  await fs.writeFile(path.join(skillPath, "SKILL.md"), `${lines.join("\n")}\n`);
+}
+
+describe("scanFreeSkillDirectory", () => {
+  it("扫描 .xg-platform 下一级 Skill，并返回元数据和真实路径", async () => {
+    const directoryPath = path.join(workspace, ".xg-platform");
+    const alphaPath = path.join(directoryPath, "alpha");
+    await writeSkill(alphaPath, { name: "Alpha", description: "alpha skill", version: "1.2.3" });
+    await writeSkill(path.join(alphaPath, "nested"), { name: "Nested" });
+    await fs.mkdir(path.join(directoryPath, "not-a-skill"), { recursive: true });
+    await fs.writeFile(path.join(directoryPath, "README.txt"), "ignored");
+
+    const result = await scanFreeSkillDirectory(path.join(workspace, "nested", ".."));
+
+    assert.deepEqual(result, [
+      {
+        code: "alpha",
+        name: "Alpha",
+        description: "alpha skill",
+        version: "1.2.3",
+        directoryPath: await fs.realpath(directoryPath),
+        skillPath: await fs.realpath(alphaPath),
+        skillFilePath: await fs.realpath(path.join(alphaPath, "SKILL.md")),
+      },
+    ]);
+  });
+
+  it("支持 .meta.json 元数据，并在缺省字段时使用稳定回退值", async () => {
+    const skillPath = path.join(workspace, ".xg-platform", "metadata-only");
+    await writeSkill(skillPath);
+    await fs.writeFile(
+      path.join(skillPath, ".meta.json"),
+      JSON.stringify({ metadata: { name: "Metadata Skill", description: "from meta" }, version: "2.0.0" }),
+    );
+
+    assert.deepEqual(await scanFreeSkillDirectory(workspace), [
+      {
+        code: "metadata-only",
+        name: "Metadata Skill",
+        description: "from meta",
+        version: "2.0.0",
+        directoryPath: await fs.realpath(path.join(workspace, ".xg-platform")),
+        skillPath: await fs.realpath(skillPath),
+        skillFilePath: await fs.realpath(path.join(skillPath, "SKILL.md")),
+      },
+    ]);
+  });
+
+  it("忽略指向 workspace 外部的 Skill 和 SKILL.md 符号链接", async (t) => {
+    if (process.platform === "win32") return t.skip("Windows 创建目录符号链接需要额外权限");
+
+    const directoryPath = path.join(workspace, ".xg-platform");
+    const externalRoot = await fs.mkdtemp(path.join(os.tmpdir(), "free-skill-external-"));
+    try {
+      const externalSkillPath = path.join(externalRoot, "external");
+      await writeSkill(externalSkillPath, { name: "External" });
+      await fs.mkdir(directoryPath, { recursive: true });
+      await fs.symlink(externalSkillPath, path.join(directoryPath, "linked-skill"), "dir");
+
+      const linkedFileSkillPath = path.join(directoryPath, "linked-file");
+      await fs.mkdir(linkedFileSkillPath, { recursive: true });
+      await fs.symlink(path.join(externalSkillPath, "SKILL.md"), path.join(linkedFileSkillPath, "SKILL.md"));
+
+      assert.deepEqual(await scanFreeSkillDirectory(workspace), []);
+    } finally {
+      await fs.rm(externalRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("拒绝 .xg-platform 本身通过符号链接越出 workspace", async (t) => {
+    if (process.platform === "win32") return t.skip("Windows 创建目录符号链接需要额外权限");
+
+    const externalRoot = await fs.mkdtemp(path.join(os.tmpdir(), "free-skill-directory-external-"));
+    try {
+      await writeSkill(path.join(externalRoot, "outside"), { name: "Outside" });
+      await fs.symlink(externalRoot, path.join(workspace, ".xg-platform"), "dir");
+      assert.deepEqual(await scanFreeSkillDirectory(workspace), []);
+    } finally {
+      await fs.rm(externalRoot, { recursive: true, force: true });
+    }
+  });
+});

package/src/free-skill-directory.ts

@@ -0,0 +1,188 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const FREE_SKILL_DIRECTORY_NAME = ".xg-platform";
+const SKILL_FILE_NAME = "SKILL.md";
+
+export type FreeSkillMetadata = {
+  code: string;
+  name: string;
+  description: string;
+  version: string;
+};
+
+export type FreeSkill = FreeSkillMetadata & {
+  /** `.xg-platform` 的真实路径。 */
+  directoryPath: string;
+  /** Skill 目录的真实路径。 */
+  skillPath: string;
+  /** `SKILL.md` 的真实路径。 */
+  skillFilePath: string;
+};
+
+type StringRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is StringRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isWithin(parent: string, candidate: string): boolean {
+  const relative = path.relative(parent, candidate);
+  return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+function asNonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function parseScalar(value: string): string {
+  const trimmed = value.trim().replace(/\s+#.*$/, "").trim();
+  if ((trimmed.startsWith("\"") && trimmed.endsWith("\"")) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+    return trimmed.slice(1, -1).trim();
+  }
+  return trimmed;
+}
+
+function parseFrontmatter(content: string): StringRecord {
+  const lines = content.replace(/^\uFEFF/, "").split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") return {};
+
+  const fields: StringRecord = {};
+  for (const line of lines.slice(1)) {
+    if (line.trim() === "---" || line.trim() === "...") break;
+    const match = /^\s*([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*?)\s*$/.exec(line);
+    if (match) fields[match[1]] = parseScalar(match[2]);
+  }
+  return fields;
+}
+
+async function realPathIfRegularFile(filePath: string): Promise<string | undefined> {
+  try {
+    const resolved = await fs.realpath(filePath);
+    const stats = await fs.stat(resolved);
+    return stats.isFile() ? resolved : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function readOptionalMetadata(skillPath: string, workspacePath: string): Promise<StringRecord> {
+  const candidate = path.resolve(skillPath, ".meta.json");
+  if (!isWithin(skillPath, candidate) || !isWithin(workspacePath, candidate)) return {};
+
+  const metadataPath = await realPathIfRegularFile(candidate);
+  if (!metadataPath || !isWithin(skillPath, metadataPath) || !isWithin(workspacePath, metadataPath)) return {};
+
+  try {
+    const parsed: unknown = JSON.parse(await fs.readFile(metadataPath, "utf8"));
+    if (!isRecord(parsed)) return {};
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+
+async function scanSkill(
+  directoryPath: string,
+  workspacePath: string,
+  entryName: string,
+): Promise<FreeSkill | undefined> {
+  const candidateSkillPath = path.resolve(directoryPath, entryName);
+  if (!isWithin(directoryPath, candidateSkillPath) || !isWithin(workspacePath, candidateSkillPath)) return undefined;
+
+  const skillPath = await realPathIfRegularFile(candidateSkillPath);
+  if (skillPath) return undefined;
+
+  let resolvedSkillPath: string;
+  try {
+    resolvedSkillPath = await fs.realpath(candidateSkillPath);
+    const stats = await fs.stat(resolvedSkillPath);
+    if (!stats.isDirectory()) return undefined;
+  } catch {
+    return undefined;
+  }
+  if (!isWithin(directoryPath, resolvedSkillPath) || !isWithin(workspacePath, resolvedSkillPath)) return undefined;
+
+  const candidateSkillFilePath = path.resolve(resolvedSkillPath, SKILL_FILE_NAME);
+  if (
+    !isWithin(resolvedSkillPath, candidateSkillFilePath) ||
+    !isWithin(workspacePath, candidateSkillFilePath)
+  ) {
+    return undefined;
+  }
+
+  const skillFilePath = await realPathIfRegularFile(candidateSkillFilePath);
+  if (!skillFilePath || !isWithin(resolvedSkillPath, skillFilePath) || !isWithin(workspacePath, skillFilePath)) {
+    return undefined;
+  }
+
+  let skillFileContent: string;
+  try {
+    skillFileContent = await fs.readFile(skillFilePath, "utf8");
+  } catch {
+    return undefined;
+  }
+
+  const frontmatter = parseFrontmatter(skillFileContent);
+  const meta = await readOptionalMetadata(resolvedSkillPath, workspacePath);
+  const nestedMetadata = isRecord(meta.metadata) ? meta.metadata : {};
+  const getValue = (...values: unknown[]): string | undefined => {
+    for (const value of values) {
+      const result = asNonEmptyString(value);
+      if (result) return result;
+    }
+    return undefined;
+  };
+
+  const code = entryName;
+  return {
+    code,
+    name: getValue(meta.name, nestedMetadata.name, frontmatter.name) ?? code,
+    description: getValue(meta.description, nestedMetadata.description, frontmatter.description) ?? "",
+    version: getValue(meta.version, nestedMetadata.version, frontmatter.version) ?? "",
+    directoryPath,
+    skillPath: resolvedSkillPath,
+    skillFilePath,
+  };
+}
+
+/** 扫描 workspace/.xg-platform 下的一级自由 Skill 目录。 */
+export async function scanFreeSkillDirectory(workspace: string): Promise<FreeSkill[]> {
+  const resolvedWorkspace = path.resolve(workspace);
+  let workspacePath: string;
+  try {
+    workspacePath = await fs.realpath(resolvedWorkspace);
+    const stats = await fs.stat(workspacePath);
+    if (!stats.isDirectory()) return [];
+  } catch {
+    return [];
+  }
+
+  const candidateDirectoryPath = path.resolve(workspacePath, FREE_SKILL_DIRECTORY_NAME);
+  if (!isWithin(workspacePath, candidateDirectoryPath)) return [];
+
+  let directoryPath: string;
+  try {
+    directoryPath = await fs.realpath(candidateDirectoryPath);
+    const stats = await fs.stat(directoryPath);
+    if (!stats.isDirectory()) return [];
+  } catch {
+    return [];
+  }
+  if (!isWithin(workspacePath, directoryPath)) return [];
+
+  let entries;
+  try {
+    entries = await fs.readdir(directoryPath, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const skills: FreeSkill[] = [];
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    if (!entry.isDirectory()) continue;
+    const skill = await scanSkill(directoryPath, workspacePath, entry.name);
+    if (skill) skills.push(skill);
+  }
+  return skills;
+}

package/src/free-skill-tool.test.ts

@@ -0,0 +1,68 @@
+import { afterEach, describe, it } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import {
+  createFreeSkillToolFactory,
+  FREE_SKILL_TOOL_NAME,
+} from "./free-skill-tool.ts";
+import { scanFreeSkillDirectory } from "./free-skill-directory.ts";
+
+const roots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true })));
+});
+
+function skillContent(name: string): string {
+  return `---\nname: ${name}\ndescription: test skill\n---\n\n# Test\n`;
+}
+
+describe("free skill tool", () => {
+  it("uses factory workspace context and returns relative plus actual paths", async () => {
+    const workspace = await fs.mkdtemp(path.join(os.tmpdir(), "free-skill-tool-"));
+    roots.push(workspace);
+    const tool = createFreeSkillToolFactory({ workspaceDir: workspace, agentId: "agent-a" });
+
+    assert.equal(tool.name, FREE_SKILL_TOOL_NAME);
+    const result = await tool.execute("call-1", {
+      skillName: "demo",
+      content: skillContent("demo"),
+      metadata: { source: "test" },
+    });
+
+    assert.equal(result.details.success, true);
+    assert.equal(result.details.agentId, "agent-a");
+    assert.equal(result.details.workspaceRelativePath, ".xg-platform/demo");
+    assert.equal(
+      result.details.skillFilePath,
+      await fs.realpath(path.join(workspace, ".xg-platform", "demo", "SKILL.md")),
+    );
+    assert.match(result.content[0].text, /\.xg-platform\/demo/);
+    assert.equal(
+      await fs.readFile(result.details.skillFilePath, "utf8"),
+      skillContent("demo"),
+    );
+    const discovered = await scanFreeSkillDirectory(workspace);
+    assert.equal(discovered.some((skill) => skill.code === "demo"), true);
+  });
+
+  it("rejects caller-supplied target/path and keeps workspace isolation", async () => {
+    const workspace = await fs.mkdtemp(path.join(os.tmpdir(), "free-skill-tool-safe-"));
+    const outside = await fs.mkdtemp(path.join(os.tmpdir(), "free-skill-tool-outside-"));
+    roots.push(workspace, outside);
+    const tool = createFreeSkillToolFactory({ workspaceDir: workspace, agentId: "agent-b" });
+
+    await assert.rejects(
+      tool.execute("call-2", {
+        skillName: "blocked",
+        content: skillContent("blocked"),
+        target: path.join(outside, "escape"),
+      }),
+      (error: unknown) => (error as { code?: string }).code === "INVALID_CONTENT",
+    );
+    await assert.rejects(fs.access(path.join(outside, "escape")));
+    await assert.rejects(fs.access(path.join(workspace, ".xg-platform", "blocked")));
+  });
+});

package/src/free-skill-tool.ts

@@ -0,0 +1,99 @@
+import path from "node:path";
+import {
+  FreeSkillWriterError,
+  writeFreeSkillOrThrow,
+  type FreeSkillWriteInput,
+} from "./free-skill-writer.ts";
+import {
+  resolveFreeSkillWorkspace,
+  type FreeSkillWorkspaceContext,
+} from "./free-skill-workspace.ts";
+
+export const FREE_SKILL_TOOL_NAME = "skill_logger_create_free_skill";
+
+type ToolParams = Record<string, unknown>;
+
+export type FreeSkillToolContext = FreeSkillWorkspaceContext & {
+  workspaceDir?: unknown;
+  agentId?: unknown;
+};
+
+export type FreeSkillToolDetails = {
+  success: true;
+  skillName: string;
+  workspaceRelativePath: string;
+  directoryPath: string;
+  skillFilePath: string;
+  agentId?: string;
+};
+
+export type FreeSkillTool = {
+  name: string;
+  label: string;
+  description: string;
+  parameters: Record<string, unknown>;
+  execute: (
+    toolCallId: string,
+    params: ToolParams,
+    signal?: AbortSignal,
+  ) => Promise<{ content: Array<{ type: "text"; text: string }>; details: FreeSkillToolDetails }>;
+};
+
+const parameters: Record<string, unknown> = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    skillName: { type: "string", description: "自由 Skill 的一级目录名" },
+    content: { type: "string", description: "完整的 SKILL.md 内容" },
+    metadata: { type: "object", description: "可选的 JSON 元数据" },
+  },
+  required: ["skillName", "content"],
+};
+
+function hasOwn(value: ToolParams, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+function asInput(params: ToolParams): FreeSkillWriteInput {
+  if (hasOwn(params, "target") || hasOwn(params, "path")) {
+    throw new FreeSkillWriterError(
+      "INVALID_CONTENT",
+      "自由 Skill 工具不接受 target/path，目标路径由当前 Agent workspace 决定",
+    );
+  }
+  return {
+    skillName: params.skillName ?? params.name,
+    content: params.content ?? params.skillContent,
+    metadata: params.metadata,
+  };
+}
+
+/**
+ * OpenClaw 2026.7.1-2 registerTool 使用的运行时工厂。
+ * workspace 只来自受信任的 factory context，绝不从模型参数读取。
+ */
+export function createFreeSkillToolFactory(context: FreeSkillToolContext): FreeSkillTool {
+  return {
+    name: FREE_SKILL_TOOL_NAME,
+    label: "Create free Skill",
+    description:
+      "Create a validated Skill in the current Agent workspace under .xg-platform. The target path is runtime controlled.",
+    parameters,
+    async execute(_toolCallId, params) {
+      const workspace = await resolveFreeSkillWorkspace(context);
+      const result = await writeFreeSkillOrThrow(asInput(params), workspace);
+      const workspaceRelativePath = path.posix.join(".xg-platform", result.skillName);
+      const details: FreeSkillToolDetails = {
+        success: true,
+        skillName: result.skillName,
+        workspaceRelativePath,
+        directoryPath: result.directoryPath,
+        skillFilePath: result.skillFilePath,
+        ...(workspace.agentId ? { agentId: workspace.agentId } : {}),
+      };
+      return {
+        content: [{ type: "text", text: `自由 Skill 已写入 ${workspaceRelativePath}` }],
+        details,
+      };
+    },
+  };
+}

package/src/free-skill-workspace.test.ts

@@ -0,0 +1,109 @@
+import { afterEach, beforeEach, describe, it } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import {
+  FreeSkillWorkspaceError,
+  resolveFreeSkillWorkspace,
+} from "./free-skill-workspace.ts";
+
+let root: string;
+
+beforeEach(async () => {
+  root = await fs.mkdtemp(path.join(os.tmpdir(), "free-skill-workspace-"));
+});
+afterEach(async () => {
+  await fs.rm(root, { recursive: true, force: true });
+});
+
+describe("resolveFreeSkillWorkspace", () => {
+  it("优先使用 registerTool 注入的 workspaceDir 和 agentId", async () => {
+    const workspace = path.join(root, "runtime-workspace");
+    await fs.mkdir(workspace);
+
+    const result = await resolveFreeSkillWorkspace(
+      {
+        agentId: "runtime-agent",
+        workspaceDir: workspace,
+        workspace: path.join(root, "ignored-workspace"),
+        directoryPath: path.join(root, "host-path-from-model"),
+      },
+      path.join(root, "fallback-workspace"),
+    );
+
+    assert.deepEqual(result, {
+      agentId: "runtime-agent",
+      workspacePath: await fs.realpath(workspace),
+      directoryPath: path.join(await fs.realpath(workspace), ".xg-platform"),
+      workspaceRelativePath: ".xg-platform",
+    });
+  });
+
+  it("兼容 workspace、ctx.workspaceDir 以及 fallbackWorkspace", async () => {
+    const workspace = path.join(root, "workspace");
+    const fallback = path.join(root, "fallback");
+    await fs.mkdir(workspace);
+    await fs.mkdir(fallback);
+
+    const directWorkspace = await resolveFreeSkillWorkspace({ workspace, agentId: "direct" });
+    assert.equal(directWorkspace.agentId, "direct");
+    assert.equal(directWorkspace.workspaceRelativePath, ".xg-platform");
+
+    const wrappedWorkspace = await resolveFreeSkillWorkspace({
+      ctx: { workspaceDir: workspace, agentId: "wrapped" },
+    });
+    assert.equal(wrappedWorkspace.agentId, "wrapped");
+    assert.equal(wrappedWorkspace.workspacePath, await fs.realpath(workspace));
+
+    const fallbackWorkspace = await resolveFreeSkillWorkspace(undefined, fallback);
+    assert.equal(fallbackWorkspace.workspacePath, await fs.realpath(fallback));
+    assert.equal(fallbackWorkspace.agentId, undefined);
+  });
+
+  it("缺失 workspace 或 workspace 不是目录时拒绝解析", async () => {
+    await assert.rejects(
+      resolveFreeSkillWorkspace({ agentId: "missing" }, path.join(root, "missing")),
+      (error: unknown) => error instanceof FreeSkillWorkspaceError && error.code === "WORKSPACE_MISSING",
+    );
+
+    const filePath = path.join(root, "workspace-file");
+    await fs.writeFile(filePath, "workspace");
+    await assert.rejects(
+      resolveFreeSkillWorkspace(undefined, filePath),
+      (error: unknown) => error instanceof FreeSkillWorkspaceError && error.code === "WORKSPACE_NOT_DIRECTORY",
+    );
+  });
+
+  it("拒绝 `.xg-platform` 符号链接越出 workspace", async (t) => {
+    if (process.platform === "win32") return t.skip("Windows 创建目录符号链接需要额外权限");
+
+    const workspace = path.join(root, "workspace");
+    const outside = path.join(root, "outside");
+    await fs.mkdir(workspace);
+    await fs.mkdir(outside);
+    await fs.symlink(outside, path.join(workspace, ".xg-platform"), "dir");
+
+    await assert.rejects(
+      resolveFreeSkillWorkspace({ workspaceDir: workspace, agentId: "runtime" }),
+      (error: unknown) => error instanceof FreeSkillWorkspaceError && error.code === "PLATFORM_DIRECTORY_ESCAPE",
+    );
+  });
+
+  it("忽略前端或模型注入的绝对 target/path，只返回固定相对目录", async () => {
+    const workspace = path.join(root, "workspace");
+    await fs.mkdir(workspace);
+
+    const result = await resolveFreeSkillWorkspace({
+      workspaceDir: workspace,
+      agentId: "runtime",
+      targetPath: "/outside/target",
+      absolutePath: "/outside/absolute",
+      directoryPath: "/outside/directory",
+    });
+
+    assert.equal(result.workspaceRelativePath, ".xg-platform");
+    assert.equal(path.isAbsolute(result.workspaceRelativePath), false);
+    assert.equal(result.directoryPath, path.join(await fs.realpath(workspace), ".xg-platform"));
+  });
+});