@zmice/zc 0.2.6 → 0.2.8

package/dist/cli/__tests__/platform.test.js

@@ -1,5 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+const abs = (path) => resolve(path);
 const platformMocks = vi.hoisted(() => ({
     ArtifactConflictError: class ArtifactConflictError extends Error {
         conflicts;
@@ -224,15 +226,15 @@ describe("platform CLI", () => {
             root: options.dir ?? options.cwd ?? process.cwd(),
             source: options.dir ? "explicit" : "cwd",
         }));
-        platformMocks.resolvePlatformInstallReceiptPath.mockImplementation((plan) => (`${plan.destinationRoot}/.zc/platform-state/${plan.platform}.install-receipt.json`));
+        platformMocks.resolvePlatformInstallReceiptPath.mockImplementation((plan) => (join(plan.destinationRoot, ".zc", "platform-state", `${plan.platform}.install-receipt.json`)));
         platformMocks.resolvePlatformInstallStatus.mockResolvedValue({
             kind: "up-to-date",
             platform: "codex",
-            receiptPath: "/tmp/install/.zc/platform-state/codex.install-receipt.json",
+            receiptPath: join(abs("/tmp/install"), ".zc", "platform-state", "codex.install-receipt.json"),
             receipt: {
                 schemaVersion: 1,
                 platform: "codex",
-                destinationRoot: "/tmp/install",
+                destinationRoot: abs("/tmp/install"),
                 manifestSource: "/repo/packages/toolkit/src/content",
                 overwrite: "error",
                 installedAt: "2026-04-19T12:00:00.000Z",
@@ -264,18 +266,18 @@ describe("platform CLI", () => {
         platformMocks.deletePlatformInstallReceipt.mockResolvedValue(undefined);
         platformMocks.writePlatformInstallReceiptForPlan.mockResolvedValue({});
         platformMocks.syncQwenOfficialCliSourceBundle.mockResolvedValue({
-            sourceDir: "/tmp/qwen-source",
+            sourceDir: abs("/tmp/qwen-source"),
             extensionName: "zc-toolkit",
             artifactCount: 1,
         });
         platformMocks.syncQwenOfficialCliReleaseBundle.mockResolvedValue({
-            bundleDir: "/tmp/qwen-release",
+            bundleDir: abs("/tmp/qwen-release"),
             extensionName: "zc-toolkit",
             artifactCount: 1,
         });
         platformMocks.toQwenOfficialCliReleaseArtifacts.mockImplementation((_plan, bundleDir) => [
-            { path: `${bundleDir}/QWEN.md`, content: "# context" },
-            { path: `${bundleDir}/commands/zc/start.md`, content: "# start" },
+            { path: join(bundleDir, "QWEN.md"), content: "# context" },
+            { path: join(bundleDir, "commands/zc/start.md"), content: "# start" },
         ]);
         platformMocks.installQwenExtensionFromOfficialRepoWithCli.mockResolvedValue(undefined);
         platformMocks.installQwenExtensionWithOfficialCli.mockResolvedValue(undefined);
@@ -284,6 +286,7 @@ describe("platform CLI", () => {
         platformMocks.relinkQwenExtensionWithOfficialCli.mockResolvedValue(undefined);
     });
     it("uses safe overwrite defaults for platform generate writes", async () => {
+        const outputRoot = abs("/tmp/out");
         platformMocks.createQwenGenerationPlan.mockReturnValue(createGenerationPlan([{ path: "QWEN.md", content: "# context" }]));
         platformMocks.writeArtifacts.mockResolvedValue({
             created: 1,
@@ -293,9 +296,10 @@ describe("platform CLI", () => {
             dryRun: false,
         });
         await runPlatformGenerate("qwen", { dir: "/tmp/out" });
-        expect(platformMocks.writeArtifacts).toHaveBeenCalledWith([{ path: "/tmp/out/QWEN.md", content: "# context" }], { dryRun: false, overwrite: "error" });
+        expect(platformMocks.writeArtifacts).toHaveBeenCalledWith([{ path: join(outputRoot, "QWEN.md"), content: "# context" }], { dryRun: false, overwrite: "error" });
     });
     it("prints a JSON plan without writing files when generate uses --plan", async () => {
+        const outputRoot = abs("/tmp/out");
         platformMocks.createQwenGenerationPlan.mockReturnValue(createGenerationPlan([{ path: "QWEN.md", content: "# context" }]));
         const logSpy = vi.spyOn(console, "log").mockImplementation(() => { });
         await runPlatformGenerate("qwen", { dir: "/tmp/out", plan: true, json: true });
@@ -305,17 +309,18 @@ describe("platform CLI", () => {
             mode: "plan",
             action: "generate",
             target: "qwen",
-            root: "/tmp/out",
+            root: outputRoot,
             artifactCount: 1,
-            artifacts: [{ path: "/tmp/out/QWEN.md", content: "# context" }],
+            artifacts: [{ path: join(outputRoot, "QWEN.md"), content: "# context" }],
         }));
         logSpy.mockRestore();
     });
     it("exports a standalone qwen release bundle during generate", async () => {
+        const bundleRoot = abs("/tmp/zc-toolkit");
         platformMocks.createQwenGenerationPlan.mockReturnValue(createGenerationPlan([{ path: "QWEN.md", content: "# context" }]));
-        platformMocks.createQwenInstallPlan.mockReturnValue(createQwenInstallPlan("/tmp/zc-toolkit", [
-            { path: "/tmp/zc-toolkit/extensions/zc-toolkit/QWEN.md", content: "# context" },
-            { path: "/tmp/zc-toolkit/extensions/zc-toolkit/commands/zc/start.md", content: "# start" },
+        platformMocks.createQwenInstallPlan.mockReturnValue(createQwenInstallPlan(bundleRoot, [
+            { path: join(bundleRoot, "extensions/zc-toolkit/QWEN.md"), content: "# context" },
+            { path: join(bundleRoot, "extensions/zc-toolkit/commands/zc/start.md"), content: "# start" },
         ]));
         platformMocks.writeArtifacts.mockResolvedValue({
             created: 2,
@@ -326,15 +331,16 @@ describe("platform CLI", () => {
         });
         await runPlatformGenerate("qwen", { dir: "/tmp/zc-toolkit", bundle: "release-bundle" });
         expect(platformMocks.writeArtifacts).toHaveBeenCalledWith([
-            { path: "/tmp/zc-toolkit/QWEN.md", content: "# context" },
-            { path: "/tmp/zc-toolkit/commands/zc/start.md", content: "# start" },
+            { path: join(bundleRoot, "QWEN.md"), content: "# context" },
+            { path: join(bundleRoot, "commands/zc/start.md"), content: "# start" },
         ], { dryRun: false, overwrite: "error" });
     });
     it("prints qwen release bundle plan paths without native extension nesting", async () => {
+        const bundleRoot = abs("/tmp/zc-toolkit");
         platformMocks.createQwenGenerationPlan.mockReturnValue(createGenerationPlan([{ path: "QWEN.md", content: "# context" }]));
-        platformMocks.createQwenInstallPlan.mockReturnValue(createQwenInstallPlan("/tmp/zc-toolkit", [
-            { path: "/tmp/zc-toolkit/extensions/zc-toolkit/QWEN.md", content: "# context" },
-            { path: "/tmp/zc-toolkit/extensions/zc-toolkit/commands/zc/start.md", content: "# start" },
+        platformMocks.createQwenInstallPlan.mockReturnValue(createQwenInstallPlan(bundleRoot, [
+            { path: join(bundleRoot, "extensions/zc-toolkit/QWEN.md"), content: "# context" },
+            { path: join(bundleRoot, "extensions/zc-toolkit/commands/zc/start.md"), content: "# start" },
         ]));
         const logSpy = vi.spyOn(console, "log").mockImplementation(() => { });
         await runPlatformGenerate("qwen", {
@@ -348,12 +354,12 @@ describe("platform CLI", () => {
             mode: "plan",
             action: "generate",
             target: "qwen",
-            root: "/tmp/zc-toolkit",
+            root: bundleRoot,
             bundleType: "release-bundle",
-            bundlePath: "/tmp/zc-toolkit",
+            bundlePath: bundleRoot,
             artifacts: [
-                { path: "/tmp/zc-toolkit/QWEN.md", content: "# context" },
-                { path: "/tmp/zc-toolkit/commands/zc/start.md", content: "# start" },
+                { path: join(bundleRoot, "QWEN.md"), content: "# context" },
+                { path: join(bundleRoot, "commands/zc/start.md"), content: "# start" },
             ],
         }));
         logSpy.mockRestore();
@@ -373,21 +379,22 @@ describe("platform CLI", () => {
             matchedAssets: [],
             capability: {
                 namespace: "zc",
-                surfaces: ["plugin-dir", "skills-dir", "agents-dir"],
-                entryFile: null,
+                surfaces: ["entry-file", "plugin-dir", "skills-dir", "agents-dir"],
+                entryFile: ".codex/AGENTS.md",
                 commandsDir: null,
-                skillsDir: "skills",
+                skillsDir: ".codex/plugins/zc-toolkit/skills",
                 agentsDir: ".codex/agents",
                 extensionDir: null,
             },
             artifacts: [
                 { path: ".agents/plugins/marketplace.json", content: "{}" },
+                { path: ".codex/AGENTS.md", content: "# plugin entry" },
                 { path: ".codex/plugins/zc-toolkit/.codex-plugin/plugin.json", content: "{}" },
                 { path: ".codex/agents/zc-code-reviewer.toml", content: "name = \"zc_code_reviewer\"\n" },
             ],
         });
         platformMocks.writeArtifacts.mockResolvedValue({
-            created: 3,
+            created: 4,
             overwritten: 0,
             unchanged: 0,
             skipped: 0,
@@ -399,12 +406,14 @@ describe("platform CLI", () => {
         });
         expect(platformMocks.createCodexMarketplaceGenerationPlan).toHaveBeenCalledWith(expect.any(Object), expect.objectContaining({ scope: "global" }));
         expect(platformMocks.writeArtifacts).toHaveBeenCalledWith([
-            { path: `${homedir()}/.agents/plugins/marketplace.json`, content: "{}" },
-            { path: `${homedir()}/.codex/plugins/zc-toolkit/.codex-plugin/plugin.json`, content: "{}" },
-            { path: `${homedir()}/.codex/agents/zc-code-reviewer.toml`, content: "name = \"zc_code_reviewer\"\n" },
+            { path: join(homedir(), ".agents/plugins/marketplace.json"), content: "{}" },
+            { path: join(homedir(), ".codex/AGENTS.md"), content: "# plugin entry" },
+            { path: join(homedir(), ".codex/plugins/zc-toolkit/.codex-plugin/plugin.json"), content: "{}" },
+            { path: join(homedir(), ".codex/agents/zc-code-reviewer.toml"), content: "name = \"zc_code_reviewer\"\n" },
         ], { dryRun: false, overwrite: "error" });
     });
     it("exports codex marketplace to the resolved project root with --project", async () => {
+        const projectRoot = join("/repo", "project");
         platformMocks.resolveInstallTarget.mockResolvedValue({
             root: "/repo/project",
             source: "project-root",
@@ -424,11 +433,12 @@ describe("platform CLI", () => {
             matchedAssets: [],
             artifacts: [
                 { path: ".agents/plugins/marketplace.json", content: "{}" },
-                { path: ".codex/plugins/zc-toolkit/.codex-plugin/plugin.json", content: "{}" },
+                { path: "AGENTS.md", content: "# plugin entry" },
+                { path: "plugins/zc-toolkit/.codex-plugin/plugin.json", content: "{}" },
             ],
         });
         platformMocks.writeArtifacts.mockResolvedValue({
-            created: 2,
+            created: 3,
             overwritten: 0,
             unchanged: 0,
             skipped: 0,
@@ -441,11 +451,13 @@ describe("platform CLI", () => {
         expect(platformMocks.resolveInstallTarget).toHaveBeenCalledWith("codex", { project: true });
         expect(platformMocks.createCodexMarketplaceGenerationPlan).toHaveBeenCalledWith(expect.any(Object), expect.objectContaining({ scope: "project" }));
         expect(platformMocks.writeArtifacts).toHaveBeenCalledWith([
-            { path: "/repo/project/.agents/plugins/marketplace.json", content: "{}" },
-            { path: "/repo/project/.codex/plugins/zc-toolkit/.codex-plugin/plugin.json", content: "{}" },
+            { path: join(projectRoot, ".agents/plugins/marketplace.json"), content: "{}" },
+            { path: join(projectRoot, "AGENTS.md"), content: "# plugin entry" },
+            { path: join(projectRoot, "plugins/zc-toolkit/.codex-plugin/plugin.json"), content: "{}" },
         ], { dryRun: false, overwrite: "error" });
     });
     it("uses a short codex plugin command for the project marketplace by default", async () => {
+        const projectRoot = join("/repo", "project");
         platformMocks.resolveInstallTarget.mockResolvedValue({
             root: "/repo/project",
             source: "project-root",
@@ -465,11 +477,12 @@ describe("platform CLI", () => {
             matchedAssets: [],
             artifacts: [
                 { path: ".agents/plugins/marketplace.json", content: "{}" },
-                { path: ".codex/plugins/zc-toolkit/.codex-plugin/plugin.json", content: "{}" },
+                { path: "AGENTS.md", content: "# plugin entry" },
+                { path: "plugins/zc-toolkit/.codex-plugin/plugin.json", content: "{}" },
             ],
         });
         platformMocks.writeArtifacts.mockResolvedValue({
-            created: 2,
+            created: 3,
             overwritten: 0,
             unchanged: 0,
             skipped: 0,
@@ -479,8 +492,9 @@ describe("platform CLI", () => {
         expect(platformMocks.resolveInstallTarget).toHaveBeenCalledWith("codex", { project: true });
         expect(platformMocks.createCodexMarketplaceGenerationPlan).toHaveBeenCalledWith(expect.any(Object), expect.objectContaining({ scope: "project" }));
         expect(platformMocks.writeArtifacts).toHaveBeenCalledWith([
-            { path: "/repo/project/.agents/plugins/marketplace.json", content: "{}" },
-            { path: "/repo/project/.codex/plugins/zc-toolkit/.codex-plugin/plugin.json", content: "{}" },
+            { path: join(projectRoot, ".agents/plugins/marketplace.json"), content: "{}" },
+            { path: join(projectRoot, "AGENTS.md"), content: "# plugin entry" },
+            { path: join(projectRoot, "plugins/zc-toolkit/.codex-plugin/plugin.json"), content: "{}" },
         ], { dryRun: false, overwrite: "error" });
     });
     it("uses the personal marketplace for codex plugin when --global is explicit", async () => {
@@ -498,11 +512,12 @@ describe("platform CLI", () => {
             matchedAssets: [],
             artifacts: [
                 { path: ".agents/plugins/marketplace.json", content: "{}" },
+                { path: ".codex/AGENTS.md", content: "# plugin entry" },
                 { path: ".codex/plugins/zc-toolkit/.codex-plugin/plugin.json", content: "{}" },
             ],
         });
         platformMocks.writeArtifacts.mockResolvedValue({
-            created: 2,
+            created: 3,
             overwritten: 0,
             unchanged: 0,
             skipped: 0,
@@ -512,12 +527,52 @@ describe("platform CLI", () => {
         expect(platformMocks.resolveInstallTarget).not.toHaveBeenCalled();
         expect(platformMocks.createCodexMarketplaceGenerationPlan).toHaveBeenCalledWith(expect.any(Object), expect.objectContaining({ scope: "global" }));
         expect(platformMocks.writeArtifacts).toHaveBeenCalledWith([
-            { path: `${homedir()}/.agents/plugins/marketplace.json`, content: "{}" },
-            { path: `${homedir()}/.codex/plugins/zc-toolkit/.codex-plugin/plugin.json`, content: "{}" },
+            { path: join(homedir(), ".agents/plugins/marketplace.json"), content: "{}" },
+            { path: join(homedir(), ".codex/AGENTS.md"), content: "# plugin entry" },
+            { path: join(homedir(), ".codex/plugins/zc-toolkit/.codex-plugin/plugin.json"), content: "{}" },
         ], { dryRun: false, overwrite: "error" });
     });
+    it("cleans the generated Codex plugin skills directory on force writes", async () => {
+        platformMocks.createCodexGenerationPlan.mockReturnValue({
+            platform: "codex",
+            packageName: "@zmice/platform-codex",
+            manifestSource: "/repo/packages/toolkit/src/content#generatedAt=2026-04-19T12:00:00.000Z",
+            matchedAssets: [],
+            artifacts: [],
+        });
+        platformMocks.createCodexMarketplaceGenerationPlan.mockReturnValue({
+            platform: "codex",
+            packageName: "@zmice/platform-codex",
+            manifestSource: "/repo/packages/toolkit/src/content#generatedAt=2026-04-19T12:00:00.000Z",
+            matchedAssets: [],
+            artifacts: [
+                { path: ".agents/plugins/marketplace.json", content: "{}" },
+                { path: ".codex/AGENTS.md", content: "# plugin entry" },
+                { path: ".codex/plugins/zc-toolkit/.codex-plugin/plugin.json", content: "{}" },
+                { path: ".codex/plugins/zc-toolkit/skills/start/SKILL.md", content: "# start" },
+            ],
+        });
+        platformMocks.writeArtifacts.mockResolvedValue({
+            created: 4,
+            overwritten: 0,
+            unchanged: 0,
+            skipped: 0,
+            dryRun: false,
+        });
+        await runPlatformPlugin("codex", { global: true, force: true });
+        expect(platformMocks.removeManagedPaths).toHaveBeenCalledWith([
+            join(homedir(), ".codex/plugins/zc-toolkit/skills"),
+        ]);
+        expect(platformMocks.writeArtifacts).toHaveBeenCalledWith([
+            { path: join(homedir(), ".agents/plugins/marketplace.json"), content: "{}" },
+            { path: join(homedir(), ".codex/AGENTS.md"), content: "# plugin entry" },
+            { path: join(homedir(), ".codex/plugins/zc-toolkit/.codex-plugin/plugin.json"), content: "{}" },
+            { path: join(homedir(), ".codex/plugins/zc-toolkit/skills/start/SKILL.md"), content: "# start" },
+        ], { dryRun: false, overwrite: "force" });
+    });
     it("uses safe overwrite defaults for platform install and writes a receipt", async () => {
-        platformMocks.createCodexInstallPlan.mockReturnValue(createInstallPlan("codex", "/tmp/install", [{ path: "/tmp/install/AGENTS.md", content: "# agents" }]));
+        const installRoot = abs("/tmp/install");
+        platformMocks.createCodexInstallPlan.mockReturnValue(createInstallPlan("codex", installRoot, [{ path: join(installRoot, "AGENTS.md"), content: "# agents" }]));
         platformMocks.writeArtifacts.mockResolvedValue({
             created: 1,
             overwritten: 0,
@@ -527,19 +582,20 @@ describe("platform CLI", () => {
         });
         await runPlatformInstall("codex", { dir: "/tmp/install" });
         expect(platformMocks.createCodexInstallPlan).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({
-            destinationRoot: "/tmp/install",
+            destinationRoot: installRoot,
             scope: "dir",
             overwrite: "error",
         }));
-        expect(platformMocks.writeArtifacts).toHaveBeenCalledWith([{ path: "/tmp/install/AGENTS.md", content: "# agents" }], { dryRun: false, overwrite: "error" });
+        expect(platformMocks.writeArtifacts).toHaveBeenCalledWith([{ path: join(installRoot, "AGENTS.md"), content: "# agents" }], { dryRun: false, overwrite: "error" });
         expect(platformMocks.writePlatformInstallReceiptForPlan).toHaveBeenCalledWith(expect.objectContaining({
-            destinationRoot: "/tmp/install",
+            destinationRoot: installRoot,
         }), expect.objectContaining({
             zcVersion: expect.any(String),
         }));
     });
     it("forwards force installs to artifact writes", async () => {
-        platformMocks.createCodexInstallPlan.mockReturnValue(createInstallPlan("codex", "/tmp/install", [{ path: "/tmp/install/AGENTS.md", content: "# agents" }]));
+        const installRoot = abs("/tmp/install");
+        platformMocks.createCodexInstallPlan.mockReturnValue(createInstallPlan("codex", installRoot, [{ path: join(installRoot, "AGENTS.md"), content: "# agents" }]));
         platformMocks.writeArtifacts.mockResolvedValue({
             created: 0,
             overwritten: 1,
@@ -548,10 +604,11 @@ describe("platform CLI", () => {
             dryRun: false,
         });
         await runPlatformInstall("codex", { dir: "/tmp/install", force: true });
-        expect(platformMocks.writeArtifacts).toHaveBeenCalledWith([{ path: "/tmp/install/AGENTS.md", content: "# agents" }], { dryRun: false, overwrite: "force" });
+        expect(platformMocks.writeArtifacts).toHaveBeenCalledWith([{ path: join(installRoot, "AGENTS.md"), content: "# agents" }], { dryRun: false, overwrite: "force" });
     });
     it("uses the resolved project root when install target is omitted", async () => {
-        platformMocks.createCodexInstallPlan.mockReturnValue(createInstallPlan("codex", "/workspace/project", [{ path: "/workspace/project/AGENTS.md", content: "# agents" }]));
+        const projectRoot = abs("/workspace/project");
+        platformMocks.createCodexInstallPlan.mockReturnValue(createInstallPlan("codex", projectRoot, [{ path: join(projectRoot, "AGENTS.md"), content: "# agents" }]));
         platformMocks.writeArtifacts.mockResolvedValue({
             created: 1,
             overwritten: 0,
@@ -573,14 +630,15 @@ describe("platform CLI", () => {
             global: undefined,
         });
         expect(platformMocks.createCodexInstallPlan).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({
-            destinationRoot: "/workspace/project",
+            destinationRoot: projectRoot,
             scope: "project",
         }));
         expect(logSpy).toHaveBeenCalledWith(expect.stringContaining("安装目录自动解析（project-root）"));
         logSpy.mockRestore();
     });
     it("prints a JSON install plan without writing files when install uses --plan", async () => {
-        platformMocks.createCodexInstallPlan.mockReturnValue(createInstallPlan("codex", "/tmp/install", [{ path: "/tmp/install/AGENTS.md", content: "# agents" }], "dir", "error"));
+        const installRoot = abs("/tmp/install");
+        platformMocks.createCodexInstallPlan.mockReturnValue(createInstallPlan("codex", installRoot, [{ path: join(installRoot, "AGENTS.md"), content: "# agents" }], "dir", "error"));
         const logSpy = vi.spyOn(console, "log").mockImplementation(() => { });
         await runPlatformInstall("codex", { dir: "/tmp/install", plan: true, json: true });
         expect(platformMocks.writeArtifacts).not.toHaveBeenCalled();
@@ -589,14 +647,14 @@ describe("platform CLI", () => {
             mode: "plan",
             action: "install",
             target: "codex",
-            root: "/tmp/install",
+            root: installRoot,
             scope: "dir",
             rootSource: "explicit",
             artifactCount: 1,
             overwrite: "error",
             artifacts: expect.arrayContaining([
                 expect.objectContaining({
-                    path: "/tmp/install/AGENTS.md",
+                    path: join(installRoot, "AGENTS.md"),
                     content: "# agents",
                 }),
             ]),
@@ -604,21 +662,22 @@ describe("platform CLI", () => {
         logSpy.mockRestore();
     });
     it("prints platform status from receipt and current plan", async () => {
+        const installRoot = abs("/tmp/install");
         const logSpy = vi.spyOn(console, "log").mockImplementation(() => { });
         platformMocks.resolveInstallTarget.mockResolvedValue({
             root: "/tmp/install",
             source: "explicit",
         });
-        platformMocks.createCodexInstallPlan.mockReturnValue(createInstallPlan("codex", "/tmp/install", [{ path: "/tmp/install/AGENTS.md", content: "# agents" }]));
+        platformMocks.createCodexInstallPlan.mockReturnValue(createInstallPlan("codex", installRoot, [{ path: join(installRoot, "AGENTS.md"), content: "# agents" }]));
         await runPlatformStatus("codex", { dir: "/tmp/install", json: true });
         expect(platformMocks.resolvePlatformInstallStatus).toHaveBeenCalledWith(expect.objectContaining({
-            destinationRoot: "/tmp/install",
+            destinationRoot: installRoot,
         }));
         const payload = JSON.parse(logSpy.mock.calls[0]?.[0] ?? "{}");
         expect(payload).toEqual(expect.objectContaining({
             mode: "status",
             target: "codex",
-            root: "/tmp/install",
+            root: installRoot,
             status: "up-to-date",
             installedContentFingerprint: "installed-fingerprint",
             contentFingerprint: "current-fingerprint",
@@ -626,32 +685,34 @@ describe("platform CLI", () => {
         logSpy.mockRestore();
     });
     it("prints qwen platform status json with installed metadata from receipt", async () => {
+        const qwenRoot = abs("/home/test/.qwen");
+        const qwenBundleRoot = abs("/tmp/qwen-release/zc-toolkit");
         const logSpy = vi.spyOn(console, "log").mockImplementation(() => { });
         platformMocks.resolveInstallTarget.mockResolvedValue({
             root: "/home/test/.qwen",
             source: "official-global",
             hint: "Qwen 官方文档定义用户级配置目录为 `~/.qwen`。",
         });
-        platformMocks.createQwenInstallPlan.mockReturnValue(createQwenInstallPlan("/home/test/.qwen", [{ path: "/home/test/.qwen/extensions/zc-toolkit/QWEN.md", content: "# context" }], "global"));
+        platformMocks.createQwenInstallPlan.mockReturnValue(createQwenInstallPlan(qwenRoot, [{ path: join(qwenRoot, "extensions/zc-toolkit/QWEN.md"), content: "# context" }], "global"));
         platformMocks.resolvePlatformInstallStatus.mockResolvedValue({
             kind: "up-to-date",
             platform: "qwen",
-            receiptPath: "/home/test/.qwen/.zc/platform-state/qwen.install-receipt.json",
+            receiptPath: join(qwenRoot, ".zc/platform-state/qwen.install-receipt.json"),
             receipt: {
                 schemaVersion: 1,
                 platform: "qwen",
-                destinationRoot: "/home/test/.qwen",
+                destinationRoot: qwenRoot,
                 manifestSource: "/repo/packages/toolkit/src/content",
                 overwrite: "error",
                 installedAt: "2026-04-19T12:00:00.000Z",
                 installMethod: "filesystem",
                 installSource: "local-bundle",
-                sourceRef: "/tmp/qwen-release/zc-toolkit",
+                sourceRef: qwenBundleRoot,
                 bundleType: "release-bundle",
-                bundlePath: "/tmp/qwen-release/zc-toolkit",
+                bundlePath: qwenBundleRoot,
                 artifacts: [
                     {
-                        path: "/home/test/.qwen/extensions/zc-toolkit/QWEN.md",
+                        path: join(qwenRoot, "extensions/zc-toolkit/QWEN.md"),
                         sha256: "sha",
                         bytes: 9,
                     },
@@ -672,26 +733,27 @@ describe("platform CLI", () => {
         expect(payload).toEqual(expect.objectContaining({
             mode: "status",
             target: "qwen",
-            root: "/home/test/.qwen",
+            root: qwenRoot,
             installMethod: "filesystem",
             installSource: "local-bundle",
-            sourceRef: "/tmp/qwen-release/zc-toolkit",
+            sourceRef: qwenBundleRoot,
             bundleType: "release-bundle",
-            bundlePath: "/tmp/qwen-release/zc-toolkit",
+            bundlePath: qwenBundleRoot,
             recommendedInstallMethod: "qwen-cli",
             recommendedInstallSource: "github-repo",
             recommendedSourceRef: "https://github.com/zmice/zc-qwen-extension.git",
             recommendedBundleType: "release-bundle",
-            recommendedBundlePath: "/home/test/.qwen/.zc/platform-bundles/qwen/zc-toolkit",
+            recommendedBundlePath: expect.stringContaining("zc-toolkit"),
         }));
         logSpy.mockRestore();
     });
     it("prints update plan when status shows update-available", async () => {
+        const installRoot = abs("/tmp/install");
         const logSpy = vi.spyOn(console, "log").mockImplementation(() => { });
         platformMocks.resolvePlatformInstallStatus.mockResolvedValue({
             kind: "update-available",
             platform: "codex",
-            receiptPath: "/tmp/install/.zc/platform-state/codex.install-receipt.json",
+            receiptPath: join(installRoot, ".zc/platform-state/codex.install-receipt.json"),
             receipt: null,
             contentFingerprint: "current-fingerprint",
             installedContentFingerprint: "installed-fingerprint",
@@ -703,7 +765,7 @@ describe("platform CLI", () => {
             },
             artifacts: [],
         });
-        platformMocks.createCodexInstallPlan.mockReturnValue(createInstallPlan("codex", "/tmp/install", [{ path: "/tmp/install/AGENTS.md", content: "# agents v2" }], "dir", "error"));
+        platformMocks.createCodexInstallPlan.mockReturnValue(createInstallPlan("codex", installRoot, [{ path: join(installRoot, "AGENTS.md"), content: "# agents v2" }], "dir", "error"));
         await runPlatformUpdate("codex", { dir: "/tmp/install", plan: true, json: true });
         expect(platformMocks.writeArtifacts).not.toHaveBeenCalled();
         const payload = JSON.parse(logSpy.mock.calls[0]?.[0] ?? "{}");
@@ -712,15 +774,16 @@ describe("platform CLI", () => {
             action: "update",
             target: "codex",
             status: "update-available",
-            root: "/tmp/install",
+            root: installRoot,
         }));
         logSpy.mockRestore();
     });
     it("treats update-available as managed overwrite and refreshes the receipt", async () => {
+        const installRoot = abs("/tmp/install");
         platformMocks.resolvePlatformInstallStatus.mockResolvedValue({
             kind: "update-available",
             platform: "codex",
-            receiptPath: "/tmp/install/.zc/platform-state/codex.install-receipt.json",
+            receiptPath: join(installRoot, ".zc/platform-state/codex.install-receipt.json"),
             receipt: null,
             contentFingerprint: "current-fingerprint",
             installedContentFingerprint: "installed-fingerprint",
@@ -732,7 +795,7 @@ describe("platform CLI", () => {
             },
             artifacts: [],
         });
-        platformMocks.createCodexInstallPlan.mockReturnValue(createInstallPlan("codex", "/tmp/install", [{ path: "/tmp/install/AGENTS.md", content: "# agents v2" }], "dir", "error"));
+        platformMocks.createCodexInstallPlan.mockReturnValue(createInstallPlan("codex", installRoot, [{ path: join(installRoot, "AGENTS.md"), content: "# agents v2" }], "dir", "error"));
         platformMocks.writeArtifacts.mockResolvedValue({
             created: 0,
             overwritten: 1,
@@ -742,10 +805,10 @@ describe("platform CLI", () => {
         });
         await runPlatformUpdate("codex", { dir: "/tmp/install" });
         expect(platformMocks.createCodexInstallPlan).toHaveBeenLastCalledWith(expect.anything(), expect.objectContaining({
-            destinationRoot: "/tmp/install",
+            destinationRoot: installRoot,
             overwrite: "force",
         }));
-        expect(platformMocks.writeArtifacts).toHaveBeenCalledWith([{ path: "/tmp/install/AGENTS.md", content: "# agents v2" }], { dryRun: false, overwrite: "force" });
+        expect(platformMocks.writeArtifacts).toHaveBeenCalledWith([{ path: join(installRoot, "AGENTS.md"), content: "# agents v2" }], { dryRun: false, overwrite: "force" });
         expect(platformMocks.writePlatformInstallReceiptForPlan).toHaveBeenCalled();
     });
     it("reports a no-op update when the installation is already up-to-date", async () => {
@@ -811,7 +874,8 @@ describe("platform CLI", () => {
         errorSpy.mockRestore();
     });
     it("passes global scope through install target resolution and exposes official path hints", async () => {
-        platformMocks.createClaudeInstallPlan.mockReturnValue(createInstallPlan("claude", "/home/test/.claude", [{ path: "/home/test/.claude/CLAUDE.md", content: "# claude" }]));
+        const claudeRoot = abs("/home/test/.claude");
+        platformMocks.createClaudeInstallPlan.mockReturnValue(createInstallPlan("claude", claudeRoot, [{ path: join(claudeRoot, "CLAUDE.md"), content: "# claude" }]));
         platformMocks.writeArtifacts.mockResolvedValue({
             created: 1,
             overwritten: 0,
@@ -833,14 +897,15 @@ describe("platform CLI", () => {
             global: true,
         });
         expect(platformMocks.createClaudeInstallPlan).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({
-            destinationRoot: "/home/test/.claude",
+            destinationRoot: claudeRoot,
             scope: "global",
         }));
         expect(logSpy).toHaveBeenCalledWith(expect.stringContaining("提示：Claude Code 官方文档定义用户级 memory 文件位于 `~/.claude/CLAUDE.md`。"));
         logSpy.mockRestore();
     });
     it("prefers the official qwen extensions CLI for global installs", async () => {
-        platformMocks.createQwenInstallPlan.mockReturnValue(createQwenInstallPlan("/home/test/.qwen", [{ path: "/home/test/.qwen/extensions/zc-toolkit/QWEN.md", content: "# context" }], "global"));
+        const qwenRoot = abs("/home/test/.qwen");
+        platformMocks.createQwenInstallPlan.mockReturnValue(createQwenInstallPlan(qwenRoot, [{ path: join(qwenRoot, "extensions/zc-toolkit/QWEN.md"), content: "# context" }], "global"));
         platformMocks.resolveInstallTarget.mockResolvedValue({
             root: "/home/test/.qwen",
             source: "official-global",
@@ -849,7 +914,7 @@ describe("platform CLI", () => {
         platformMocks.resolvePlatformInstallStatus.mockResolvedValue({
             kind: "not-installed",
             platform: "qwen",
-            receiptPath: "/home/test/.qwen/.zc/platform-state/qwen.install-receipt.json",
+            receiptPath: join(qwenRoot, ".zc/platform-state/qwen.install-receipt.json"),
             receipt: null,
             contentFingerprint: "current-fingerprint",
             installedContentFingerprint: undefined,
@@ -869,7 +934,8 @@ describe("platform CLI", () => {
         expect(platformMocks.writeArtifacts).not.toHaveBeenCalled();
     });
     it("prints a JSON install plan with scope metadata", async () => {
-        platformMocks.createCodexInstallPlan.mockReturnValue(createInstallPlan("codex", "/home/test/.codex", [{ path: "/home/test/.codex/AGENTS.md", content: "# agents" }], "global", "error"));
+        const codexRoot = abs("/home/test/.codex");
+        platformMocks.createCodexInstallPlan.mockReturnValue(createInstallPlan("codex", codexRoot, [{ path: join(codexRoot, "AGENTS.md"), content: "# agents" }], "global", "error"));
         platformMocks.resolveInstallTarget.mockResolvedValue({
             root: "/home/test/.codex",
             source: "official-global",
@@ -883,7 +949,7 @@ describe("platform CLI", () => {
             action: "install",
             target: "codex",
             scope: "global",
-            root: "/home/test/.codex",
+            root: codexRoot,
             rootSource: "official-global",
             hint: "Codex 官方文档将 Codex home（默认 `~/.codex`）定义为全局级 `AGENTS.md` 的位置。",
         }));
@@ -1008,22 +1074,23 @@ describe("platform CLI", () => {
         expect(platformMocks.deletePlatformInstallReceipt).toHaveBeenCalledWith("/home/test/.qwen/.zc/platform-state/qwen.install-receipt.json");
     });
     it("repairs drifted filesystem installs by rewriting managed artifacts", async () => {
-        platformMocks.createCodexInstallPlan.mockReturnValue(createInstallPlan("codex", "/tmp/install", [{ path: "/tmp/install/AGENTS.md", content: "# agents repaired" }]));
+        const installRoot = abs("/tmp/install");
+        platformMocks.createCodexInstallPlan.mockReturnValue(createInstallPlan("codex", installRoot, [{ path: join(installRoot, "AGENTS.md"), content: "# agents repaired" }]));
         platformMocks.resolvePlatformInstallStatus.mockResolvedValue({
             kind: "drifted",
             platform: "codex",
-            receiptPath: "/tmp/install/.zc/platform-state/codex.install-receipt.json",
+            receiptPath: join(installRoot, ".zc/platform-state/codex.install-receipt.json"),
             receipt: {
                 schemaVersion: 1,
                 platform: "codex",
-                destinationRoot: "/tmp/install",
+                destinationRoot: installRoot,
                 manifestSource: "/repo/packages/toolkit/src/content",
                 overwrite: "error",
                 installedAt: "2026-04-19T12:00:00.000Z",
                 installMethod: "filesystem",
                 artifacts: [
                     {
-                        path: "/tmp/install/AGENTS.md",
+                        path: join(installRoot, "AGENTS.md"),
                         sha256: "old-sha",
                         bytes: 8,
                     },
@@ -1039,7 +1106,7 @@ describe("platform CLI", () => {
             },
             artifacts: [
                 {
-                    path: "/tmp/install/AGENTS.md",
+                    path: join(installRoot, "AGENTS.md"),
                     receiptSha256: "old-sha",
                     actualSha256: "drifted-sha",
                     plannedSha256: "new-sha",
@@ -1057,10 +1124,10 @@ describe("platform CLI", () => {
         });
         await runPlatformRepair("codex", { dir: "/tmp/install" });
         expect(platformMocks.createCodexInstallPlan).toHaveBeenLastCalledWith(expect.anything(), expect.objectContaining({
-            destinationRoot: "/tmp/install",
+            destinationRoot: installRoot,
             overwrite: "force",
         }));
-        expect(platformMocks.writeArtifacts).toHaveBeenCalledWith([{ path: "/tmp/install/AGENTS.md", content: "# agents repaired" }], { dryRun: false, overwrite: "force" });
+        expect(platformMocks.writeArtifacts).toHaveBeenCalledWith([{ path: join(installRoot, "AGENTS.md"), content: "# agents repaired" }], { dryRun: false, overwrite: "force" });
         expect(platformMocks.writePlatformInstallReceiptForPlan).toHaveBeenCalled();
     });
     it("prints platform doctor health and issues", async () => {
@@ -1119,7 +1186,8 @@ describe("platform CLI", () => {
         logSpy.mockRestore();
     });
     it("prints resolved install targets via platform where", async () => {
-        platformMocks.createCodexInstallPlan.mockReturnValue(createInstallPlan("codex", "/home/test/.codex", [{ path: "/home/test/.codex/AGENTS.md", content: "# agents" }], "global"));
+        const codexRoot = abs("/home/test/.codex");
+        platformMocks.createCodexInstallPlan.mockReturnValue(createInstallPlan("codex", codexRoot, [{ path: join(codexRoot, "AGENTS.md"), content: "# agents" }], "global"));
         platformMocks.resolveInstallTarget.mockResolvedValue({
             root: "/home/test/.codex",
             source: "official-global",
@@ -1138,7 +1206,7 @@ describe("platform CLI", () => {
             mode: "where",
             target: "codex",
             scope: "global",
-            root: "/home/test/.codex",
+            root: codexRoot,
             rootSource: "official-global",
             capability: expect.objectContaining({
                 namespace: "zc",
@@ -1148,12 +1216,13 @@ describe("platform CLI", () => {
         logSpy.mockRestore();
     });
     it("resolves qwen global scope to the user-level ~/.qwen directory", async () => {
+        const qwenRoot = abs("/home/test/.qwen");
         platformMocks.createQwenInstallPlan.mockReturnValue({
             platform: "qwen",
             packageName: "@zmice/platform-qwen",
             manifestSource: "/repo/packages/toolkit/src/content#generatedAt=2026-04-19T12:00:00.000Z",
             matchedAssets: [],
-            destinationRoot: "/home/test/.qwen",
+            destinationRoot: qwenRoot,
             scope: "global",
             overwrite: "error",
             capability: {
@@ -1165,7 +1234,7 @@ describe("platform CLI", () => {
                 agentsDir: "agents",
                 extensionDir: "extensions/zc-toolkit",
             },
-            artifacts: [{ path: "/home/test/.qwen/extensions/zc-toolkit/QWEN.md", content: "# context" }],
+            artifacts: [{ path: join(qwenRoot, "extensions/zc-toolkit/QWEN.md"), content: "# context" }],
         });
         platformMocks.resolveInstallTarget.mockResolvedValue({
             root: "/home/test/.qwen",
@@ -1179,7 +1248,7 @@ describe("platform CLI", () => {
             mode: "where",
             target: "qwen",
             scope: "global",
-            root: "/home/test/.qwen",
+            root: qwenRoot,
             rootSource: "official-global",
             hint: "Qwen 官方文档定义用户级配置目录为 `~/.qwen`，并在官方帮助文档中给出 Qwen CLI 的用户级 `QWEN.md` 位置为 `~/.qwen/QWEN.md`。",
         }));