@spzhongwin/skill-logger-plugin 1.0.18 → 1.0.19

package/src/free-skill-workspace.ts

@@ -0,0 +1,223 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const FREE_SKILL_DIRECTORY_NAME = ".xg-platform";
+
+export type FreeSkillWorkspaceContext = {
+  agentId?: unknown;
+  workspaceDir?: unknown;
+  workspace?: unknown;
+  agent?: { id?: unknown } | unknown;
+  ctx?: {
+    agentId?: unknown;
+    workspaceDir?: unknown;
+    workspace?: unknown;
+    agent?: { id?: unknown } | unknown;
+  } | unknown;
+  /** Compatibility for OpenClaw registerTool contexts wrapped by adapters. */
+  context?: FreeSkillWorkspaceContext | unknown;
+};
+
+export type FreeSkillWorkspace = {
+  agentId?: string;
+  /** Canonical real path of the active Agent workspace. */
+  workspacePath: string;
+  /** Canonical path when `.xg-platform` exists; lexical child path otherwise. */
+  directoryPath: string;
+  /** Stable model-facing path; this value is deliberately always relative. */
+  workspaceRelativePath: ".xg-platform";
+};
+
+export class FreeSkillWorkspaceError extends Error {
+  public readonly code:
+    | "WORKSPACE_MISSING"
+    | "WORKSPACE_NOT_DIRECTORY"
+    | "PLATFORM_DIRECTORY_ESCAPE"
+    | "PLATFORM_DIRECTORY_NOT_DIRECTORY"
+    | "PLATFORM_DIRECTORY_BROKEN_LINK";
+
+  constructor(
+    code:
+      | "WORKSPACE_MISSING"
+      | "WORKSPACE_NOT_DIRECTORY"
+      | "PLATFORM_DIRECTORY_ESCAPE"
+      | "PLATFORM_DIRECTORY_NOT_DIRECTORY"
+      | "PLATFORM_DIRECTORY_BROKEN_LINK",
+    message: string,
+  ) {
+    super(message);
+    this.code = code;
+    this.name = "FreeSkillWorkspaceError";
+  }
+}
+
+type UnknownRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is UnknownRecord {
+  return typeof value === "object" && value !== null;
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function isWithin(parent: string, candidate: string): boolean {
+  const relative = path.relative(parent, candidate);
+  return relative === ""
+    || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+function nestedRecord(value: unknown, key: string): UnknownRecord | undefined {
+  if (!isRecord(value)) return undefined;
+  const nested = value[key];
+  return isRecord(nested) ? nested : undefined;
+}
+
+function firstWorkspaceValue(context: unknown): string | undefined {
+  if (!isRecord(context)) return undefined;
+
+  const wrapped = nestedRecord(context, "ctx");
+  const nestedContext = nestedRecord(context, "context");
+  const candidates = [
+    context.workspaceDir,
+    context.workspace,
+    wrapped?.workspaceDir,
+    wrapped?.workspace,
+    nestedContext?.workspaceDir,
+    nestedContext?.workspace,
+  ];
+  return candidates.map(nonEmptyString).find((value): value is string => Boolean(value));
+}
+
+function firstAgentIdValue(context: unknown): string | undefined {
+  if (!isRecord(context)) return undefined;
+
+  const wrapped = nestedRecord(context, "ctx");
+  const nestedContext = nestedRecord(context, "context");
+  const agent = isRecord(context.agent) ? context.agent.id : undefined;
+  const wrappedAgent = isRecord(wrapped?.agent) ? wrapped?.agent.id : undefined;
+  const nestedContextAgent = isRecord(nestedContext?.agent) ? nestedContext?.agent.id : undefined;
+  const candidates = [
+    context.agentId,
+    agent,
+    wrapped?.agentId,
+    wrappedAgent,
+    nestedContext?.agentId,
+    nestedContextAgent,
+  ];
+  return candidates.map(nonEmptyString).find((value): value is string => Boolean(value));
+}
+
+async function resolveWorkspacePath(workspaceInput: string): Promise<string> {
+  let workspacePath: string;
+  try {
+    workspacePath = await fs.realpath(path.resolve(workspaceInput));
+  } catch {
+    throw new FreeSkillWorkspaceError(
+      "WORKSPACE_MISSING",
+      `Agent workspace 不存在或不可访问: ${workspaceInput}`,
+    );
+  }
+
+  try {
+    const stat = await fs.stat(workspacePath);
+    if (!stat.isDirectory()) {
+      throw new FreeSkillWorkspaceError(
+        "WORKSPACE_NOT_DIRECTORY",
+        `Agent workspace 不是目录: ${workspaceInput}`,
+      );
+    }
+  } catch (error) {
+    if (error instanceof FreeSkillWorkspaceError) throw error;
+    throw new FreeSkillWorkspaceError(
+      "WORKSPACE_MISSING",
+      `Agent workspace 不存在或不可访问: ${workspaceInput}`,
+    );
+  }
+  return workspacePath;
+}
+
+async function resolvePlatformDirectory(workspacePath: string): Promise<string> {
+  const candidate = path.resolve(workspacePath, FREE_SKILL_DIRECTORY_NAME);
+  if (!isWithin(workspacePath, candidate)) {
+    throw new FreeSkillWorkspaceError(
+      "PLATFORM_DIRECTORY_ESCAPE",
+      "`.xg-platform` 不在 Agent workspace 内",
+    );
+  }
+
+  let entry;
+  try {
+    entry = await fs.lstat(candidate);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === "ENOENT") return candidate;
+    throw new FreeSkillWorkspaceError(
+      "PLATFORM_DIRECTORY_BROKEN_LINK",
+      "无法检查 Agent workspace 下的 `.xg-platform`",
+    );
+  }
+
+  let resolved = candidate;
+  if (entry.isSymbolicLink()) {
+    try {
+      resolved = await fs.realpath(candidate);
+    } catch {
+      throw new FreeSkillWorkspaceError(
+        "PLATFORM_DIRECTORY_BROKEN_LINK",
+        "`.xg-platform` 是失效符号链接",
+      );
+    }
+    if (!isWithin(workspacePath, resolved)) {
+      throw new FreeSkillWorkspaceError(
+        "PLATFORM_DIRECTORY_ESCAPE",
+        "`.xg-platform` 符号链接越出 Agent workspace",
+      );
+    }
+  }
+
+  try {
+    const stat = await fs.stat(resolved);
+    if (!stat.isDirectory()) {
+      throw new FreeSkillWorkspaceError(
+        "PLATFORM_DIRECTORY_NOT_DIRECTORY",
+        "Agent workspace 下的 `.xg-platform` 不是目录",
+      );
+    }
+  } catch (error) {
+    if (error instanceof FreeSkillWorkspaceError) throw error;
+    throw new FreeSkillWorkspaceError(
+      "PLATFORM_DIRECTORY_BROKEN_LINK",
+      "无法访问 Agent workspace 下的 `.xg-platform`",
+    );
+  }
+  return resolved;
+}
+
+/**
+ * Resolve the current Agent's private free-Skill directory.
+ *
+ * Only runtime-injected workspace fields are considered. Arbitrary target/path
+ * fields are intentionally ignored so model or frontend input cannot select a
+ * host path. `fallbackWorkspace` is an internal compatibility fallback.
+ */
+export async function resolveFreeSkillWorkspace(
+  context?: FreeSkillWorkspaceContext | unknown,
+  fallbackWorkspace?: string,
+): Promise<FreeSkillWorkspace> {
+  const workspaceInput = firstWorkspaceValue(context) ?? nonEmptyString(fallbackWorkspace);
+  if (!workspaceInput) {
+    throw new FreeSkillWorkspaceError(
+      "WORKSPACE_MISSING",
+      "未提供当前 Agent workspace",
+    );
+  }
+
+  const workspacePath = await resolveWorkspacePath(workspaceInput);
+  const directoryPath = await resolvePlatformDirectory(workspacePath);
+  return {
+    agentId: firstAgentIdValue(context),
+    workspacePath,
+    directoryPath,
+    workspaceRelativePath: FREE_SKILL_DIRECTORY_NAME,
+  };
+}

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

@@ -0,0 +1,105 @@
+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 { resolveFreeSkillWorkspace } from "./free-skill-workspace.ts";
+import { writeFreeSkill } from "./free-skill-writer.ts";
+
+let workspaceRoot: string;
+
+beforeEach(async () => {
+  workspaceRoot = await fs.mkdtemp(path.join(os.tmpdir(), "free-skill-writer-"));
+});
+afterEach(async () => {
+  await fs.rm(workspaceRoot, { recursive: true, force: true });
+});
+
+function skillContent(description = "A free skill"): string {
+  return `---\nname: Demo Skill\ndescription: ${description}\n---\n\n# Demo\n\nUse this skill.\n`;
+}
+
+describe("writeFreeSkill", () => {
+  it("通过最小校验后原子写入 SKILL.md 和 metadata，并拒绝重复覆盖", async () => {
+    const workspace = await resolveFreeSkillWorkspace({ workspaceDir: workspaceRoot, agentId: "agent-1" });
+    const first = await writeFreeSkill(
+      { skillName: "demo", content: skillContent(), metadata: { version: "1.0.0", source: "test" } },
+      workspace,
+    );
+
+    assert.equal(first.success, true);
+    if (!first.success) return;
+    assert.equal(await fs.readFile(first.skillFilePath, "utf8"), skillContent());
+    assert.deepEqual(JSON.parse(await fs.readFile(first.metadataFilePath!, "utf8")), {
+      version: "1.0.0",
+      source: "test",
+    });
+
+    const duplicate = await writeFreeSkill(
+      { skillName: "demo", content: skillContent("replacement") },
+      workspace,
+    );
+    assert.deepEqual(duplicate, {
+      success: false,
+      code: "SKILL_EXISTS",
+      message: "Skill 已存在: demo",
+    });
+    assert.equal(await fs.readFile(first.skillFilePath, "utf8"), skillContent());
+  });
+
+  it("对非法 frontmatter、空正文和路径穿越返回稳定错误码", async () => {
+    const workspace = await resolveFreeSkillWorkspace({ workspaceDir: workspaceRoot });
+    const invalidFrontmatter = await writeFreeSkill(
+      { skillName: "invalid", content: "---\nname: Demo\ndescription: [broken\n---\n\n# Body\n" },
+      workspace,
+    );
+    assert.equal(invalidFrontmatter.success, false);
+    if (!invalidFrontmatter.success) assert.equal(invalidFrontmatter.code, "INVALID_FRONTMATTER");
+
+    const emptyBody = await writeFreeSkill(
+      { skillName: "empty-body", content: "---\nname: Demo\ndescription: desc\n---\n\n" },
+      workspace,
+    );
+    assert.equal(emptyBody.success, false);
+    if (!emptyBody.success) assert.equal(emptyBody.code, "EMPTY_BODY");
+
+    const traversal = await writeFreeSkill(
+      { skillName: "../outside", content: skillContent(), targetPath: path.join(workspaceRoot, "outside") } as never,
+      workspace,
+    );
+    assert.equal(traversal.success, false);
+    if (!traversal.success) assert.equal(traversal.code, "INVALID_SKILL_NAME");
+    await assert.rejects(fs.access(path.join(workspaceRoot, "outside")));
+  });
+
+  it("拒绝符号链接目标，并在 rename 失败时清理新目录", async (t) => {
+    if (process.platform === "win32") return t.skip("Windows 创建目录符号链接需要额外权限");
+
+    const workspace = await resolveFreeSkillWorkspace({ workspaceDir: workspaceRoot });
+    await fs.mkdir(workspace.directoryPath, { recursive: true });
+    const external = await fs.mkdtemp(path.join(os.tmpdir(), "free-skill-writer-external-"));
+    try {
+      await fs.symlink(external, path.join(workspace.directoryPath, "linked"), "dir");
+      const linked = await writeFreeSkill({ skillName: "linked", content: skillContent() }, workspace);
+      assert.equal(linked.success, false);
+      if (!linked.success) assert.equal(linked.code, "TARGET_SYMLINK");
+
+      const failed = await writeFreeSkill(
+        { skillName: "rename-fails", content: skillContent() },
+        workspace,
+        {
+          fileSystem: {
+            rename: async () => {
+              throw new Error("injected rename failure");
+            },
+          },
+        },
+      );
+      assert.equal(failed.success, false);
+      if (!failed.success) assert.equal(failed.code, "ATOMIC_WRITE_FAILED");
+      await assert.rejects(fs.access(path.join(workspace.directoryPath, "rename-fails")));
+    } finally {
+      await fs.rm(external, { recursive: true, force: true });
+    }
+  });
+});