@zhuoyuezs/ml-platform 0.2.1 → 0.2.2-alpha.1

package/scripts/lib.js

@@ -1,12 +1,11 @@
 "use strict";
-
+Object.defineProperty(exports, "__esModule", { value: true });
 const crypto = require("crypto");
 const fs = require("fs");
 const os = require("os");
 const path = require("path");
 const { spawnSync } = require("child_process");
 const RELEASE_POLICY = require("../release-policy.json");
-
 const PACKAGE_CONFIG = require("../package.json");
 const PACKAGE_NAME = PACKAGE_CONFIG.name;
 const PACKAGE_VERSION = PACKAGE_CONFIG.version;
@@ -14,1111 +13,1420 @@ const CLI_NAME = "ml-platform";
 const SKILL_NAME = "feature-management";
 const RELEASE_SCHEMA = "data_platform.ml_platform_release/v2";
 const CHECKSUM_SCHEMA = "data_platform.ml_platform_checksums/v1";
-const RECORD_SCHEMA = "data_platform.ml_platform_installation/v2";
-const RUNTIME_RECORD_SCHEMA = "data_platform.ml_platform_runtime_installation/v1";
+const RECORD_SCHEMA = "data_platform.ml_platform_installation/v3";
+const LEGACY_RECORD_SCHEMA = "data_platform.ml_platform_installation/v2";
+const RUNTIME_RECORD_SCHEMA = "data_platform.ml_platform_runtime_installation/v2";
+const LEGACY_RUNTIME_RECORD_SCHEMA = "data_platform.ml_platform_runtime_installation/v1";
+const REGISTRY_SCHEMA = "data_platform.ml_platform_installation_registry/v1";
 const PACKAGE_ROOT = path.resolve(__dirname, "..");
 const SKILL_TOP_LEVEL = new Set(["SKILL.md", "agents", "assets", "references"]);
 const CLIENT_TOP_LEVEL = new Set(["package.json", "package-lock.json", "README.md", "src"]);
 if (RELEASE_POLICY.schema_version !== "data_platform.ml_platform_release_policy/v1") {
-  throw new Error("不支持的 release policy schema");
+    throw new Error("不支持的 release policy schema");
 }
 const FORBIDDEN_DIRECTORIES = new Set(RELEASE_POLICY.forbidden_directories);
 const FORBIDDEN_FILES = new Set(RELEASE_POLICY.forbidden_files);
 const FORBIDDEN_SUFFIXES = new Set(RELEASE_POLICY.forbidden_suffixes);
 const FORBIDDEN_CONTENT_PATTERNS = (RELEASE_POLICY.forbidden_content_patterns || []).map((item) => {
-  if (!item || typeof item.name !== "string" || typeof item.pattern !== "string") {
-    throw new Error("release policy 包含无效内容规则");
-  }
-  return { name: item.name, pattern: new RegExp(item.pattern, "i") };
+    if (!item || typeof item.name !== "string" || typeof item.pattern !== "string") {
+        throw new Error("release policy 包含无效内容规则");
+    }
+    return { name: item.name, pattern: new RegExp(item.pattern, "i") };
 });
-
 function parseOptions(args) {
-  const options = {
-    agent: "codex",
-    scope: "user",
-    upgrade: false,
-    allowDowngrade: false,
-    prewarm: true,
-    backupUnmanaged: false,
-    summary: true,
-  };
-  let outputFlag = null;
-  const valueFlags = new Map([
-    ["--agent", "agent"],
-    ["--scope", "scope"],
-    ["--skills-dir", "skillsDir"],
-    ["--project-dir", "projectDir"],
-    ["--state-dir", "stateDir"],
-    ["--bin-dir", "binDir"],
-    ["--api-url", "apiUrl"],
-  ]);
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-    if (valueFlags.has(arg)) {
-      const value = args[index + 1];
-      if (!value || value.startsWith("--")) throw new Error(`${arg} 缺少值`);
-      options[valueFlags.get(arg)] = value;
-      index += 1;
-    } else if (arg === "--upgrade") {
-      options.upgrade = true;
-    } else if (arg === "--allow-downgrade") {
-      options.allowDowngrade = true;
-    } else if (arg === "--no-prewarm") {
-      options.prewarm = false;
-    } else if (arg === "--backup-unmanaged") {
-      options.backupUnmanaged = true;
-    } else if (arg === "--summary") {
-      if (outputFlag === "json") throw new Error("--summary 与 --json 不能同时使用");
-      outputFlag = "summary";
-      options.summary = true;
-    } else if (arg === "--json") {
-      if (outputFlag === "summary") throw new Error("--summary 与 --json 不能同时使用");
-      outputFlag = "json";
-      options.summary = false;
-    } else {
-      throw new Error(`未知参数: ${arg}`);
-    }
-  }
-  return options;
-}
-
+    const options = {
+        agent: "codex",
+        scope: "user",
+        upgrade: false,
+        allowDowngrade: false,
+        prewarm: true,
+        backupUnmanaged: false,
+        summary: true,
+    };
+    let outputFlag = null;
+    const valueFlags = new Map([
+        ["--agent", "agent"],
+        ["--scope", "scope"],
+        ["--skills-dir", "skillsDir"],
+        ["--project-dir", "projectDir"],
+        ["--state-dir", "stateDir"],
+        ["--bin-dir", "binDir"],
+        ["--api-url", "apiUrl"],
+    ]);
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (valueFlags.has(arg)) {
+            const value = args[index + 1];
+            if (!value || value.startsWith("--"))
+                throw new Error(`${arg} 缺少值`);
+            options[valueFlags.get(arg)] = value;
+            index += 1;
+        }
+        else if (arg === "--upgrade") {
+            options.upgrade = true;
+        }
+        else if (arg === "--allow-downgrade") {
+            options.allowDowngrade = true;
+        }
+        else if (arg === "--no-prewarm") {
+            options.prewarm = false;
+        }
+        else if (arg === "--backup-unmanaged") {
+            options.backupUnmanaged = true;
+        }
+        else if (arg === "--summary") {
+            if (outputFlag === "json")
+                throw new Error("--summary 与 --json 不能同时使用");
+            outputFlag = "summary";
+            options.summary = true;
+        }
+        else if (arg === "--json") {
+            if (outputFlag === "summary")
+                throw new Error("--summary 与 --json 不能同时使用");
+            outputFlag = "json";
+            options.summary = false;
+        }
+        else {
+            throw new Error(`未知参数: ${arg}`);
+        }
+    }
+    return options;
+}
 function resolveInstallPaths(options = {}) {
-  const agent = options.agent || "codex";
-  const scope = options.scope || "user";
-  if (!["codex", "pi", "custom"].includes(agent)) throw new Error(`不支持的 Agent: ${agent}`);
-  if (!["user", "project"].includes(scope)) throw new Error(`不支持的安装作用域: ${scope}`);
-
-  let skillsDir;
-  let projectDir = null;
-  if (options.skillsDir) {
-    skillsDir = path.resolve(expandHome(options.skillsDir));
-  } else if (agent === "codex" && scope === "user") {
-    const codexHome = process.env.CODEX_HOME
-      ? path.resolve(expandHome(process.env.CODEX_HOME))
-      : path.join(os.homedir(), ".codex");
-    skillsDir = path.join(codexHome, "skills");
-  } else if (agent === "codex" && scope === "project") {
-    projectDir = path.resolve(expandHome(options.projectDir || process.cwd()));
-    if (!fs.existsSync(projectDir)) throw new Error(`Codex 项目目录不存在: ${projectDir}`);
-    if (!fs.statSync(projectDir).isDirectory()) throw new Error(`Codex 项目路径不是目录: ${projectDir}`);
-    skillsDir = path.join(projectDir, ".agents", "skills");
-  } else {
-    throw new Error(`${agent} 安装必须显式提供 --skills-dir`);
-  }
-
-  const defaultDataRoot = process.env.XDG_DATA_HOME
-    ? path.join(path.resolve(expandHome(process.env.XDG_DATA_HOME)), "ml-platform")
-    : path.join(os.homedir(), ".local", "share", "ml-platform");
-  const stateDir = path.resolve(expandHome(
-    options.stateDir || process.env.ML_PLATFORM_HOME || defaultDataRoot,
-  ));
-  const binDir = path.resolve(expandHome(
-    options.binDir || process.env.ML_PLATFORM_BIN_DIR || path.join(os.homedir(), ".local", "bin"),
-  ));
-  const installRoot = path.join(stateDir, "current");
-  const target = path.join(skillsDir, SKILL_NAME);
-  return {
-    agent,
-    scope,
-    projectDir,
-    skillsDir,
-    target,
-    record: path.join(skillsDir, `.${SKILL_NAME}.ml-platform.json`),
-    stateDir,
-    installRoot,
-    clientRoot: path.join(installRoot, "runtime", "business-client"),
-    dispatcher: path.join(installRoot, "scripts", "main.js"),
-    runtimeRecord: path.join(installRoot, "ownership.json"),
-    lock: path.join(stateDir, ".install.lock"),
-    binDir,
-    shim: path.join(binDir, CLI_NAME),
-  };
-}
-
+    const agent = options.agent || "codex";
+    const scope = options.scope || "user";
+    if (!["codex", "pi", "custom"].includes(agent))
+        throw new Error(`不支持的 Agent: ${agent}`);
+    if (!["user", "project"].includes(scope))
+        throw new Error(`不支持的安装作用域: ${scope}`);
+    let skillsDir;
+    let projectDir = null;
+    if (options.skillsDir) {
+        skillsDir = path.resolve(expandHome(options.skillsDir));
+    }
+    else if (agent === "codex" && scope === "user") {
+        const codexHome = process.env.CODEX_HOME
+            ? path.resolve(expandHome(process.env.CODEX_HOME))
+            : path.join(os.homedir(), ".codex");
+        skillsDir = path.join(codexHome, "skills");
+    }
+    else if (agent === "codex" && scope === "project") {
+        projectDir = path.resolve(expandHome(options.projectDir || process.cwd()));
+        if (!fs.existsSync(projectDir))
+            throw new Error(`Codex 项目目录不存在: ${projectDir}`);
+        if (!fs.statSync(projectDir).isDirectory())
+            throw new Error(`Codex 项目路径不是目录: ${projectDir}`);
+        skillsDir = path.join(projectDir, ".agents", "skills");
+    }
+    else {
+        throw new Error(`${agent} 安装必须显式提供 --skills-dir`);
+    }
+    const defaultDataRoot = process.env.XDG_DATA_HOME
+        ? path.join(path.resolve(expandHome(process.env.XDG_DATA_HOME)), "ml-platform")
+        : path.join(os.homedir(), ".local", "share", "ml-platform");
+    const stateDir = path.resolve(expandHome(options.stateDir || process.env.ML_PLATFORM_HOME || defaultDataRoot));
+    const binDir = path.resolve(expandHome(options.binDir || process.env.ML_PLATFORM_BIN_DIR || path.join(os.homedir(), ".local", "bin")));
+    const installRoot = path.join(stateDir, "current");
+    const target = path.join(skillsDir, SKILL_NAME);
+    return {
+        agent,
+        scope,
+        projectDir,
+        skillsDir,
+        target,
+        record: path.join(skillsDir, `.${SKILL_NAME}.ml-platform.json`),
+        stateDir,
+        installRoot,
+        clientRoot: path.join(installRoot, "runtime", "business-client"),
+        dispatcher: path.join(installRoot, "scripts", "main.js"),
+        runtimeRecord: path.join(installRoot, "ownership.json"),
+        registry: path.join(stateDir, "installations.json"),
+        lock: path.join(stateDir, ".install.lock"),
+        binDir,
+        shim: path.join(binDir, CLI_NAME),
+    };
+}
 function loadRelease(packageRoot = PACKAGE_ROOT) {
-  const release = readJson(path.join(packageRoot, "release.json"), "release manifest");
-  if (release.schema_version !== RELEASE_SCHEMA) {
-    throw new Error(`不支持的 release schema: ${release.schema_version}`);
-  }
-  const policyPath = path.join(packageRoot, "release-policy.json");
-  if (!isSha256(release.policy_sha256) || !fs.existsSync(policyPath)
-      || sha256File(policyPath) !== release.policy_sha256) {
-    throw new Error("release policy 摘要与 release manifest 不匹配");
-  }
-  if (!isSemver(release.release_version)) throw new Error("release_version 不是有效 SemVer");
-  const requirements = release.runtime_requirements;
-  if (!requirements || requirements.node !== ">=18"
-      || !Array.isArray(requirements.os)
-      || requirements.os.join(",") !== "darwin,linux") {
-    throw new Error("release manifest 缺少有效 runtime requirements");
-  }
-  const skills = release.skills;
-  const skill = skills && skills[SKILL_NAME];
-  if (!skill || Object.keys(skills).length < 1) {
-    throw new Error("release manifest 缺少有效 Skill 信息");
-  }
-  for (const [name, item] of Object.entries(skills)) {
-    if (item.path !== `skills/${name}` || !isSha256(item.sha256)
-        || !isSemver(item.revision) || typeof item.requires_cli !== "string") throw new Error("release manifest 缺少有效 Skill 信息");
-  }
-  const cli = release.cli;
-  if (!cli || cli.name !== CLI_NAME || cli.path !== "runtime/business-client"
-      || !isSemver(cli.version) || !isSha256(cli.sha256) || cli.entrypoint !== "src/cli.js") {
-    throw new Error("release manifest 缺少有效 JavaScript CLI 信息");
-  }
-  for (const item of Object.values(skills)) if (!versionSatisfies(cli.version, item.requires_cli)) throw new Error("Skill requires_cli 与 release CLI version 不兼容");
-  return release;
-}
-
+    const release = readJson(path.join(packageRoot, "release.json"), "release manifest");
+    if (release.schema_version !== RELEASE_SCHEMA) {
+        throw new Error(`不支持的 release schema: ${release.schema_version}`);
+    }
+    const policyPath = path.join(packageRoot, "release-policy.json");
+    if (!isSha256(release.policy_sha256) || !fs.existsSync(policyPath)
+        || sha256File(policyPath) !== release.policy_sha256) {
+        throw new Error("release policy 摘要与 release manifest 不匹配");
+    }
+    if (!isSemver(release.release_version))
+        throw new Error("release_version 不是有效 SemVer");
+    const requirements = release.runtime_requirements;
+    if (!requirements || requirements.node !== ">=18"
+        || !Array.isArray(requirements.os)
+        || requirements.os.join(",") !== "darwin,linux") {
+        throw new Error("release manifest 缺少有效 runtime requirements");
+    }
+    const skills = release.skills;
+    const skill = skills && skills[SKILL_NAME];
+    if (!skill || Object.keys(skills).length < 1) {
+        throw new Error("release manifest 缺少有效 Skill 信息");
+    }
+    for (const [name, item] of Object.entries(skills)) {
+        if (item.path !== `skills/${name}` || !isSha256(item.sha256)
+            || !isSemver(item.revision) || typeof item.requires_cli !== "string")
+            throw new Error("release manifest 缺少有效 Skill 信息");
+    }
+    const cli = release.cli;
+    if (!cli || cli.name !== CLI_NAME || cli.path !== "runtime/business-client"
+        || !isSemver(cli.version) || !isSha256(cli.sha256) || cli.entrypoint !== "src/cli.js") {
+        throw new Error("release manifest 缺少有效 JavaScript CLI 信息");
+    }
+    for (const item of Object.values(skills))
+        if (!versionSatisfies(cli.version, item.requires_cli))
+            throw new Error("Skill requires_cli 与 release CLI version 不兼容");
+    return release;
+}
 function verifyPackage(packageRoot = PACKAGE_ROOT) {
-  packageRoot = path.resolve(packageRoot);
-  const release = loadRelease(packageRoot);
-  const manifest = readJson(path.join(packageRoot, "checksums.json"), "checksums manifest");
-  if (manifest.schema_version !== CHECKSUM_SCHEMA || !Array.isArray(manifest.files)) {
-    throw new Error("checksums manifest 格式无效");
-  }
-  const seen = new Set();
-  for (const item of manifest.files) {
-    if (!item || typeof item.path !== "string" || !isSha256(item.sha256)
-        || !Number.isSafeInteger(item.size_bytes) || item.size_bytes < 0) {
-      throw new Error("checksums manifest 包含无效条目");
-    }
-    const relative = normalizeRelative(item.path);
-    if (!relative.startsWith("runtime/") && !relative.startsWith("skills/")) {
-      throw new Error(`checksum 路径不属于 runtime 或 skills: ${relative}`);
-    }
-    if (seen.has(relative)) throw new Error(`checksums manifest 路径重复: ${relative}`);
-    seen.add(relative);
-    const file = resolveInside(packageRoot, relative);
-    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) throw new Error(`发布文件不是普通文件: ${relative}`);
-    if (fs.statSync(file).size !== item.size_bytes) throw new Error(`发布文件大小不匹配: ${relative}`);
-    if (sha256File(file) !== item.sha256) throw new Error(`发布文件 SHA-256 不匹配: ${relative}`);
-  }
-
-  const releaseRoots = [path.join(packageRoot, "runtime"), path.join(packageRoot, "skills")];
-  const actualFiles = releaseRoots.flatMap((root) => listFiles(root))
-    .map((file) => path.relative(packageRoot, file).split(path.sep).join("/"));
-  if (actualFiles.length !== seen.size || actualFiles.some((file) => !seen.has(file))) {
-    throw new Error("runtime/skills 文件集合与 checksums manifest 不一致");
-  }
-
-  assertTopLevel(path.join(packageRoot, "runtime"), new Set(["business-client"]), "runtime");
-  assertTopLevel(path.join(packageRoot, "skills"), new Set(Object.keys(release.skills)), "skills");
-  const skillRoot = resolveInside(packageRoot, release.skills[SKILL_NAME].path);
-  const clientRoot = resolveInside(packageRoot, release.cli.path);
-  assertTopLevel(skillRoot, SKILL_TOP_LEVEL, "Skill");
-  assertAllowedClient(clientRoot);
-  rejectForbiddenTree(skillRoot, "Skill");
-  rejectForbiddenTree(clientRoot, "business client");
-  rejectForbiddenContent([
-    ...listFiles(skillRoot),
-    ...listFiles(clientRoot),
-    ...["README.md", "DEVELOPMENT.md"]
-      .map((name) => path.join(packageRoot, name))
-      .filter((file) => fs.existsSync(file)),
-  ], "release payload");
-  if (fs.existsSync(path.join(skillRoot, "runtime")) || fs.existsSync(path.join(skillRoot, "scripts"))) {
-    throw new Error("Skill 不得包含 CLI runtime 或 wrapper");
-  }
-  const cliEntries = releaseRoots.flatMap((root) => listFiles(root))
-    .filter((file) => path.basename(file) === "cli.js");
-  const expectedEntry = path.join(clientRoot, release.cli.entrypoint);
-  if (cliEntries.length !== 1 || cliEntries[0] !== expectedEntry) {
-    throw new Error("release 必须且只能包含一份 JavaScript business CLI");
-  }
-  const packageFiles = releaseRoots.flatMap((root) => listFiles(root))
-    .filter((file) => path.basename(file) === "package.json");
-  if (packageFiles.length !== 1 || packageFiles[0] !== path.join(clientRoot, "package.json")) {
-    throw new Error("release 包含第二份 CLI 或未知 npm package");
-  }
-  if (treeDigest(skillRoot) !== release.skills[SKILL_NAME].sha256) {
-    throw new Error("Skill 目录摘要与 release manifest 不一致");
-  }
-  for (const [name, item] of Object.entries(release.skills)) {
-    const root = resolveInside(packageRoot, item.path);
-    const actual = new Set(fs.readdirSync(root));
-    if (!actual.has("SKILL.md") || !actual.has("agents") || [...actual].some((entry) => !SKILL_TOP_LEVEL.has(entry))) throw new Error(`Skill ${name} 目录结构无效`);
-    rejectForbiddenTree(root, `Skill ${name}`);
-    if (treeDigest(root) !== item.sha256) throw new Error(`Skill ${name} 目录摘要与 release manifest 不一致`);
-  }
-  if (treeDigest(clientRoot) !== release.cli.sha256) {
-    throw new Error("JavaScript CLI 摘要与 release manifest 不一致");
-  }
-  if (!fs.existsSync(expectedEntry)) throw new Error("JavaScript CLI 入口不存在");
-  return { release, skillRoot, skillRoots: Object.fromEntries(Object.entries(release.skills).map(([name, item]) => [name, resolveInside(packageRoot, item.path)])), clientRoot };
-}
-
+    packageRoot = path.resolve(packageRoot);
+    const release = loadRelease(packageRoot);
+    const manifest = readJson(path.join(packageRoot, "checksums.json"), "checksums manifest");
+    if (manifest.schema_version !== CHECKSUM_SCHEMA || !Array.isArray(manifest.files)) {
+        throw new Error("checksums manifest 格式无效");
+    }
+    const seen = new Set();
+    for (const item of manifest.files) {
+        if (!item || typeof item.path !== "string" || !isSha256(item.sha256)
+            || !Number.isSafeInteger(item.size_bytes) || item.size_bytes < 0) {
+            throw new Error("checksums manifest 包含无效条目");
+        }
+        const relative = normalizeRelative(item.path);
+        if (!relative.startsWith("runtime/") && !relative.startsWith("skills/")) {
+            throw new Error(`checksum 路径不属于 runtime 或 skills: ${relative}`);
+        }
+        if (seen.has(relative))
+            throw new Error(`checksums manifest 路径重复: ${relative}`);
+        seen.add(relative);
+        const file = resolveInside(packageRoot, relative);
+        if (!fs.existsSync(file) || !fs.statSync(file).isFile())
+            throw new Error(`发布文件不是普通文件: ${relative}`);
+        if (fs.statSync(file).size !== item.size_bytes)
+            throw new Error(`发布文件大小不匹配: ${relative}`);
+        if (sha256File(file) !== item.sha256)
+            throw new Error(`发布文件 SHA-256 不匹配: ${relative}`);
+    }
+    const releaseRoots = [path.join(packageRoot, "runtime"), path.join(packageRoot, "skills")];
+    const actualFiles = releaseRoots.flatMap((root) => listFiles(root))
+        .map((file) => path.relative(packageRoot, file).split(path.sep).join("/"));
+    if (actualFiles.length !== seen.size || actualFiles.some((file) => !seen.has(file))) {
+        throw new Error("runtime/skills 文件集合与 checksums manifest 不一致");
+    }
+    assertTopLevel(path.join(packageRoot, "runtime"), new Set(["business-client"]), "runtime");
+    assertTopLevel(path.join(packageRoot, "skills"), new Set(Object.keys(release.skills)), "skills");
+    const skillRoot = resolveInside(packageRoot, release.skills[SKILL_NAME].path);
+    const clientRoot = resolveInside(packageRoot, release.cli.path);
+    assertTopLevel(skillRoot, SKILL_TOP_LEVEL, "Skill");
+    assertAllowedClient(clientRoot);
+    rejectForbiddenTree(skillRoot, "Skill");
+    rejectForbiddenTree(clientRoot, "business client");
+    rejectForbiddenContent([
+        ...listFiles(skillRoot),
+        ...listFiles(clientRoot),
+        ...["README.md", "DEVELOPMENT.md"]
+            .map((name) => path.join(packageRoot, name))
+            .filter((file) => fs.existsSync(file)),
+    ], "release payload");
+    if (fs.existsSync(path.join(skillRoot, "runtime")) || fs.existsSync(path.join(skillRoot, "scripts"))) {
+        throw new Error("Skill 不得包含 CLI runtime 或 wrapper");
+    }
+    const cliEntries = releaseRoots.flatMap((root) => listFiles(root))
+        .filter((file) => path.basename(file) === "cli.js");
+    const expectedEntry = path.join(clientRoot, release.cli.entrypoint);
+    if (cliEntries.length !== 1 || cliEntries[0] !== expectedEntry) {
+        throw new Error("release 必须且只能包含一份 JavaScript business CLI");
+    }
+    const packageFiles = releaseRoots.flatMap((root) => listFiles(root))
+        .filter((file) => path.basename(file) === "package.json");
+    if (packageFiles.length !== 1 || packageFiles[0] !== path.join(clientRoot, "package.json")) {
+        throw new Error("release 包含第二份 CLI 或未知 npm package");
+    }
+    if (treeDigest(skillRoot) !== release.skills[SKILL_NAME].sha256) {
+        throw new Error("Skill 目录摘要与 release manifest 不一致");
+    }
+    for (const [name, item] of Object.entries(release.skills)) {
+        const root = resolveInside(packageRoot, item.path);
+        const actual = new Set(fs.readdirSync(root));
+        if (!actual.has("SKILL.md") || !actual.has("agents") || [...actual].some((entry) => !SKILL_TOP_LEVEL.has(entry)))
+            throw new Error(`Skill ${name} 目录结构无效`);
+        rejectForbiddenTree(root, `Skill ${name}`);
+        if (treeDigest(root) !== item.sha256)
+            throw new Error(`Skill ${name} 目录摘要与 release manifest 不一致`);
+    }
+    if (treeDigest(clientRoot) !== release.cli.sha256) {
+        throw new Error("JavaScript CLI 摘要与 release manifest 不一致");
+    }
+    if (!fs.existsSync(expectedEntry))
+        throw new Error("JavaScript CLI 入口不存在");
+    return { release, skillRoot, skillRoots: Object.fromEntries(Object.entries(release.skills).map(([name, item]) => [name, resolveInside(packageRoot, item.path)])), clientRoot };
+}
 function status(options = {}, packageRoot = PACKAGE_ROOT) {
-  const paths = resolveInstallPaths(options);
-  let record = null;
-  let recordError = null;
-  if (fs.existsSync(paths.record)) {
+    const paths = resolveInstallPaths(options);
+    let record = null;
+    let recordError = null;
+    if (fs.existsSync(paths.record)) {
+        try {
+            record = readInstallationRecord(paths.record, paths);
+        }
+        catch (error) {
+            recordError = error.message;
+        }
+    }
+    let packageRelease = null;
+    try {
+        packageRelease = loadRelease(packageRoot).release_version;
+    }
+    catch (_) {
+        // A source checkout has no generated release until the builder runs.
+    }
+    const runtime = safeReadRuntimeRecord(paths.runtimeRecord);
+    const runtimeHealthy = runtimeMatchesRuntimeRecord(paths, runtime);
+    const skillsInstalled = Boolean(record)
+        && Object.values(record.skills).every((skill) => digestEquals(skill.path, skill.sha256));
+    let registryError = null;
+    let registeredScope = false;
     try {
-      record = readInstallationRecord(paths.record, paths);
-    } catch (error) {
-      recordError = error.message;
-    }
-  }
-  let packageRelease = null;
-  try {
-    packageRelease = loadRelease(packageRoot).release_version;
-  } catch (_) {
-    // A source checkout has no generated release until the builder runs.
-  }
-  const installed = Boolean(record)
-    && fs.existsSync(paths.target)
-    && fs.existsSync(paths.clientRoot)
-    && fs.existsSync(paths.dispatcher)
-    && fs.existsSync(paths.shim);
-  return {
-    ok: installed && !recordError,
-    installed,
-    owner: record ? record.owner.package : null,
-    agent: paths.agent,
-    scope: paths.scope,
-    installation_record: paths.record,
-    installed_release: record ? record.release_version : null,
-    package_release: packageRelease,
-    cli: record ? record.cli : { name: CLI_NAME, path: paths.clientRoot, version: null, sha256: null },
-    skill: record ? record.skill : { name: SKILL_NAME, path: paths.target, revision: null, sha256: null },
-    shim: record ? record.shim : { path: paths.shim, sha256: null },
-    record_error: recordError,
-  };
-}
-
+        const registry = readInstallationRegistry(paths);
+        registeredScope = registry.installations[installationId(paths)] !== undefined;
+    }
+    catch (error) {
+        registryError = error.message;
+    }
+    const installed = Boolean(record)
+        && Boolean(runtime)
+        && skillsInstalled
+        && fs.existsSync(paths.dispatcher)
+        && fs.existsSync(paths.shim);
+    return {
+        ok: installed && runtimeHealthy && !recordError,
+        installed,
+        owner: record ? record.owner.package : null,
+        agent: paths.agent,
+        scope: paths.scope,
+        installation_record: paths.record,
+        installed_release: record ? record.release_version : null,
+        runtime_release: runtime ? runtime.release_version : null,
+        package_release: packageRelease,
+        cli: runtime
+            ? { name: CLI_NAME, path: paths.clientRoot, version: runtime.cli_version, sha256: runtime.cli_sha256 }
+            : { name: CLI_NAME, path: paths.clientRoot, version: null, sha256: null },
+        skill: record ? record.skill : { name: SKILL_NAME, path: paths.target, revision: null, sha256: null },
+        skills: record ? record.skills : {},
+        shim: record ? record.shim : { path: paths.shim, sha256: null },
+        registered_scope: registeredScope,
+        registry_error: registryError,
+        record_error: recordError,
+    };
+}
 function doctor(options = {}, packageRoot = PACKAGE_ROOT) {
-  const paths = resolveInstallPaths(options);
-  const checks = [];
-  let expectedRelease = null;
-  const hasCompletePackage = fs.existsSync(path.join(packageRoot, "checksums.json"))
-    && fs.existsSync(path.join(packageRoot, "skills", SKILL_NAME));
-
-  // Check for legacy Python Skill before proceeding
-  if (!fs.existsSync(paths.record)) {
-    const legacy = detectLegacySkill(paths.target);
-    if (legacy) {
-      const markers = Object.entries(legacy).filter(([_, v]) => v).map(([k]) => k).join(", ");
-      return {
-        ok: false,
-        error: `检测到旧 Python Skill (${markers})`,
-        remediation: buildInstallCommand(
-          paths,
-          options,
-          "install",
-          packageVersion(packageRoot),
-          ["--backup-unmanaged"],
-        ),
-        legacy_skill_detected: true,
-        legacy_markers: legacy,
-        skill_root: paths.target,
-      };
-    }
-  }
-
-  try {
-    if (hasCompletePackage) {
-      expectedRelease = verifyPackage(packageRoot).release;
-      checks.push({ name: "package_payload", ok: true });
-    } else {
-      expectedRelease = loadRelease(paths.installRoot);
-      checks.push({ name: "installed_release_metadata", ok: true });
-    }
-  } catch (error) {
-    checks.push({
-      name: hasCompletePackage ? "package_payload" : "installed_release_metadata",
-      ok: false,
-      error: error.message,
-    });
-  }
-
-  let record = null;
-  try {
-    record = readInstallationRecord(paths.record, paths);
-    const expectedOk = !expectedRelease
-      || (record.release_version === expectedRelease.release_version
-        && record.cli.sha256 === expectedRelease.cli.sha256
-        && record.skill.sha256 === expectedRelease.skills[SKILL_NAME].sha256);
-    checks.push({ name: "installation_record", ok: expectedOk });
-  } catch (error) {
-    checks.push({ name: "installation_record", ok: false, error: error.message });
-  }
-
-  checkTree(checks, "installed_cli", paths.clientRoot, record && record.cli.sha256);
-  checkTree(checks, "installed_skill", paths.target, record && record.skill.sha256);
-  checkFile(checks, "installed_shim", paths.shim, record && record.shim.sha256);
-  if (record) {
-    checkTree(checks, "installed_manager", path.join(paths.installRoot, "scripts"), record.manager_sha256);
-    checkFile(checks, "installed_release_manifest", path.join(paths.installRoot, "release.json"), record.release_sha256);
-    checkFile(checks, "installed_release_policy", path.join(paths.installRoot, "release-policy.json"), record.policy_sha256);
-  }
-
-  const runtime = runCliRuntime(paths.dispatcher, ["version"], false);
-  checks.push({ name: "cli_runtime", ok: runtime.ok, detail: runtime.detail });
-  const pathMatches = findAllOnPath(CLI_NAME);
-  const matchingShim = pathMatches.find((candidate) => sameFileOrContent(candidate, paths.shim));
-  const pathOk = matchingShim !== undefined;
-  checks.push({
-    name: "path_visibility",
-    ok: pathOk,
-    expected: paths.shim,
-    actual: matchingShim ?? pathMatches[0] ?? null,
-    remediation: pathOk ? null : `将 ${paths.binDir} 加入 PATH，然后重启 Agent 会话`,
-  });
-  const apiTarget = resolveEffectiveApiTarget(options, paths.dispatcher);
-  if (apiTarget.error) {
+    const paths = resolveInstallPaths(options);
+    const checks = [];
+    let expectedRelease = null;
+    const hasCompletePackage = fs.existsSync(path.join(packageRoot, "checksums.json"))
+        && fs.existsSync(path.join(packageRoot, "skills", SKILL_NAME));
+    // Check for legacy Python Skill before proceeding
+    if (!fs.existsSync(paths.record)) {
+        const legacy = detectLegacySkill(paths.target);
+        if (legacy) {
+            const markers = Object.entries(legacy).filter(([_, v]) => v).map(([k]) => k).join(", ");
+            return {
+                ok: false,
+                error: `检测到旧 Python Skill (${markers})`,
+                remediation: buildInstallCommand(paths, options, "install", packageVersion(packageRoot), ["--backup-unmanaged"]),
+                legacy_skill_detected: true,
+                legacy_markers: legacy,
+                skill_root: paths.target,
+            };
+        }
+    }
+    try {
+        if (hasCompletePackage) {
+            expectedRelease = verifyPackage(packageRoot).release;
+            checks.push({ name: "package_payload", ok: true });
+        }
+        else {
+            expectedRelease = loadRelease(paths.installRoot);
+            checks.push({ name: "installed_release_metadata", ok: true });
+        }
+    }
+    catch (error) {
+        checks.push({
+            name: hasCompletePackage ? "package_payload" : "installed_release_metadata",
+            ok: false,
+            error: error.message,
+        });
+    }
+    let record = null;
+    try {
+        record = readInstallationRecord(paths.record, paths);
+        checks.push({ name: "installation_record", ok: true });
+    }
+    catch (error) {
+        checks.push({ name: "installation_record", ok: false, error: error.message });
+    }
+    const runtimeRecord = safeReadRuntimeRecord(paths.runtimeRecord);
     checks.push({
-      name: "platform_api",
-      ok: false,
-      source: apiTarget.source,
-      detail: apiTarget.error,
+        name: "runtime_installation_record",
+        ok: Boolean(runtimeRecord) && !runtimeRecord.legacy,
+        error: runtimeRecord?.legacy ? "持久 CLI ownership record 需要通过 install/upgrade 升级" : undefined,
     });
-  } else if (apiTarget.apiUrl) {
-    const apiHealth = runApiHealth(paths.dispatcher, apiTarget.apiUrl);
+    checkTree(checks, "installed_cli", paths.clientRoot, runtimeRecord && runtimeRecord.cli_sha256);
+    if (record) {
+        for (const [name, skill] of Object.entries(record.skills)) {
+            checkTree(checks, name === SKILL_NAME ? "installed_skill" : `installed_skill_${name}`, skill.path, skill.sha256);
+        }
+    }
+    else {
+        checkTree(checks, "installed_skill", paths.target, null);
+    }
+    checkFile(checks, "installed_shim", paths.shim, record && record.shim.sha256);
+    checkTree(checks, "installed_manager", path.join(paths.installRoot, "scripts"), runtimeRecord && runtimeRecord.manager_sha256);
+    checkFile(checks, "installed_release_manifest", path.join(paths.installRoot, "release.json"), runtimeRecord && runtimeRecord.release_sha256);
+    checkFile(checks, "installed_release_policy", path.join(paths.installRoot, "release-policy.json"), runtimeRecord && runtimeRecord.policy_sha256);
     checks.push({
-      name: "platform_api",
-      ok: apiHealth.ok,
-      source: apiTarget.source,
-      api_url: apiTarget.apiUrl,
-      detail: apiHealth.detail,
+        name: "scope_cli_compatibility",
+        ok: Boolean(record && runtimeRecord && Object.values(record.skills)
+            .every((skill) => versionSatisfies(runtimeRecord.cli_version, skill.requires_cli))),
+        cli_version: runtimeRecord?.cli_version ?? null,
     });
-  } else {
+    try {
+        const registry = readInstallationRegistry(paths);
+        checks.push({
+            name: "installation_registry",
+            ok: registryContainsScope(registry, paths),
+            registry: paths.registry,
+        });
+    }
+    catch (error) {
+        checks.push({ name: "installation_registry", ok: false, error: error.message });
+    }
+    const runtime = runCliRuntime(paths.dispatcher, ["version"], false);
+    checks.push({ name: "cli_runtime", ok: runtime.ok, detail: runtime.detail });
+    const pathMatches = findAllOnPath(CLI_NAME);
+    const matchingShim = pathMatches.find((candidate) => sameFileOrContent(candidate, paths.shim));
+    const pathOk = matchingShim !== undefined;
     checks.push({
-      name: "platform_api",
-      ok: null,
-      skipped: true,
-      source: null,
-      reason: "未通过 --api-url、ML_PLATFORM_API_URL 或 configure 配置 API 地址",
+        name: "path_visibility",
+        ok: pathOk,
+        expected: paths.shim,
+        actual: matchingShim ?? pathMatches[0] ?? null,
+        remediation: pathOk ? null : `将 ${paths.binDir} 加入 PATH，然后重启 Agent 会话`,
     });
-  }
-  return {
-    ok: checks.every((check) => check.ok !== false),
-    release_version: record ? record.release_version : expectedRelease && expectedRelease.release_version,
-    cli_version: record ? record.cli.version : expectedRelease && expectedRelease.cli.version,
-    skill_root: paths.target,
-    checks,
-  };
-}
-
+    const apiTarget = resolveEffectiveApiTarget(options, paths.dispatcher);
+    if (apiTarget.error) {
+        checks.push({
+            name: "platform_api",
+            ok: false,
+            source: apiTarget.source,
+            detail: apiTarget.error,
+        });
+    }
+    else if (apiTarget.apiUrl) {
+        const apiHealth = runApiHealth(paths.dispatcher, apiTarget.apiUrl);
+        checks.push({
+            name: "platform_api",
+            ok: apiHealth.ok,
+            source: apiTarget.source,
+            api_url: apiTarget.apiUrl,
+            detail: apiHealth.detail,
+        });
+    }
+    else {
+        checks.push({
+            name: "platform_api",
+            ok: null,
+            skipped: true,
+            source: null,
+            reason: "未通过 --api-url、ML_PLATFORM_API_URL 或 configure 配置 API 地址",
+        });
+    }
+    return {
+        ok: checks.every((check) => check.ok !== false),
+        release_version: record ? record.release_version : expectedRelease && expectedRelease.release_version,
+        cli_version: runtimeRecord ? runtimeRecord.cli_version : expectedRelease && expectedRelease.cli.version,
+        skill_root: paths.target,
+        checks,
+    };
+}
 function install(options = {}, packageRoot = PACKAGE_ROOT) {
-  const verified = verifyPackage(packageRoot);
-  const paths = resolveInstallPaths(options);
-  fs.mkdirSync(paths.skillsDir, { recursive: true, mode: 0o700 });
-  fs.mkdirSync(paths.stateDir, { recursive: true, mode: 0o700 });
-  fs.mkdirSync(paths.binDir, { recursive: true, mode: 0o755 });
-  return withInstallLock(paths.lock, () => installLocked(options, packageRoot, verified, paths));
-}
-
+    const verified = verifyPackage(packageRoot);
+    const paths = resolveInstallPaths(options);
+    fs.mkdirSync(paths.skillsDir, { recursive: true, mode: 0o700 });
+    fs.mkdirSync(paths.stateDir, { recursive: true, mode: 0o700 });
+    fs.mkdirSync(paths.binDir, { recursive: true, mode: 0o755 });
+    return withInstallLock(paths.lock, () => installLocked(options, packageRoot, verified, paths));
+}
 function detectLegacySkill(skillPath) {
-  if (!pathEntryExists(skillPath) || !fs.lstatSync(skillPath).isDirectory()) return null;
-  const markers = {
-    pythonWheel: fs.existsSync(path.join(skillPath, "assets", "wheels"))
-      && fs.readdirSync(path.join(skillPath, "assets", "wheels")).some(f => f.endsWith(".whl")),
-    runtimeJson: fs.existsSync(path.join(skillPath, "assets", "wheels", "runtime.json")),
-    bootstrapScript: fs.existsSync(path.join(skillPath, "scripts", "bootstrap.py")),
-    installScript: fs.existsSync(path.join(skillPath, "scripts", "install.py")),
-    oldLauncher: fs.existsSync(path.join(skillPath, "scripts", "data-platform-demo"))
-      || fs.existsSync(path.join(skillPath, "scripts", "ml-platform")),
-  };
-  const hasAnyMarker = Object.values(markers).some(Boolean);
-  return hasAnyMarker ? markers : null;
-}
-
+    if (!pathEntryExists(skillPath) || !fs.lstatSync(skillPath).isDirectory())
+        return null;
+    const markers = {
+        pythonWheel: fs.existsSync(path.join(skillPath, "assets", "wheels"))
+            && fs.readdirSync(path.join(skillPath, "assets", "wheels")).some(f => f.endsWith(".whl")),
+        runtimeJson: fs.existsSync(path.join(skillPath, "assets", "wheels", "runtime.json")),
+        bootstrapScript: fs.existsSync(path.join(skillPath, "scripts", "bootstrap.py")),
+        installScript: fs.existsSync(path.join(skillPath, "scripts", "install.py")),
+        oldLauncher: fs.existsSync(path.join(skillPath, "scripts", "data-platform-demo"))
+            || fs.existsSync(path.join(skillPath, "scripts", "ml-platform")),
+    };
+    const hasAnyMarker = Object.values(markers).some(Boolean);
+    return hasAnyMarker ? markers : null;
+}
 function backupUnmanagedSkill(skillPath, skillsDir, legacy) {
-  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-  let suffix = 0;
-  let backupPath;
-  do {
-    const kind = legacy ? "legacy-backup" : "unmanaged-backup";
-    const backupName = `.${SKILL_NAME}.${kind}.${timestamp}${suffix ? `-${suffix}` : ""}`;
-    backupPath = path.join(skillsDir, backupName);
-    suffix += 1;
-  } while (pathEntryExists(backupPath));
-  fs.renameSync(skillPath, backupPath);
-  return backupPath;
-}
-
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    let suffix = 0;
+    let backupPath;
+    do {
+        const kind = legacy ? "legacy-backup" : "unmanaged-backup";
+        const backupName = `.${SKILL_NAME}.${kind}.${timestamp}${suffix ? `-${suffix}` : ""}`;
+        backupPath = path.join(skillsDir, backupName);
+        suffix += 1;
+    } while (pathEntryExists(backupPath));
+    fs.renameSync(skillPath, backupPath);
+    return backupPath;
+}
 function installLocked(options, packageRoot, verified, paths) {
-  const previousRecord = fs.existsSync(paths.record) ? fs.readFileSync(paths.record) : null;
-  const current = safeReadInstallationRecord(paths.record, paths);
-  const targetExists = pathEntryExists(paths.target);
-  const legacy = targetExists && !current ? detectLegacySkill(paths.target) : null;
-  const backingUpUnmanaged = Boolean(targetExists && !current && options.backupUnmanaged);
-
-  if (options.migrateLegacy && !legacy) {
-    throw new Error(`目标 Skill 不是旧 Python Skill 或不存在: ${paths.target}`);
-  }
-
-  if (targetExists && !current && !backingUpUnmanaged) {
-    if (legacy && !options.backupUnmanaged) {
-      const markers = Object.entries(legacy).filter(([_, v]) => v).map(([k]) => k).join(", ");
-      throw new Error(
-        `目标 Skill 包含旧 Python runtime 标记 (${markers})，拒绝覆盖: ${paths.target}\n` +
-        `  迁移方法: 使用 --backup-unmanaged 或运行 'ml-platform migrate' 先备份旧 Skill`
-      );
-    } else if (fs.lstatSync(paths.target).isSymbolicLink()) {
-      throw new Error(
-        `目标 Skill 路径是未托管的符号链接，拒绝覆盖: ${paths.target}\n` +
-        "  处理方法: 确认后使用 --backup-unmanaged 备份该链接并安装正式 Skill"
-      );
-    } else if (!legacy) {
-      throw new Error(
-        `目标 Skill 不受 ${PACKAGE_NAME} 管理，拒绝覆盖: ${paths.target}\n` +
-        "  处理方法: 确认后使用 --backup-unmanaged 备份原目录"
-      );
-    }
-  }
-  const sharedRuntime = safeReadRuntimeRecord(paths.runtimeRecord);
-  if (pathEntryExists(paths.installRoot) && !sharedRuntime) {
-    throw new Error(`持久 CLI 目录不受 ${PACKAGE_NAME} 管理，拒绝覆盖: ${paths.installRoot}`);
-  }
-  if (pathEntryExists(paths.shim) && (!current || sha256File(paths.shim) !== current.shim.sha256)
-      && (!sharedRuntime || !shimTargetsDispatcher(paths.shim, paths.dispatcher))) {
-    throw new Error(`CLI shim 不受 ${PACKAGE_NAME} 管理，拒绝覆盖: ${paths.shim}`);
-  }
-
-  const sharedRuntimeMatches = sharedRuntime
-    && sharedRuntime.release_version === verified.release.release_version
-    && sharedRuntime.cli_version === verified.release.cli.version
-    && sharedRuntime.cli_sha256 === verified.release.cli.sha256
-    && digestEquals(paths.clientRoot, verified.release.cli.sha256)
-    && fs.existsSync(paths.shim)
-    && shimTargetsDispatcher(paths.shim, paths.dispatcher);
-
-  const currentComplete = current
-    && current.release_version === verified.release.release_version
-    && current.cli.sha256 === verified.release.cli.sha256
-    && current.skill.sha256 === verified.release.skills[SKILL_NAME].sha256
-    && digestEquals(paths.clientRoot, current.cli.sha256)
-    && digestEquals(paths.target, current.skill.sha256)
-    && fs.existsSync(paths.shim)
-    && sha256File(paths.shim) === current.shim.sha256
-    && digestEquals(path.join(paths.installRoot, "scripts"), current.manager_sha256)
-    && fs.existsSync(path.join(paths.installRoot, "release.json"))
-    && sha256File(path.join(paths.installRoot, "release.json")) === current.release_sha256;
-  if (currentComplete && !options.upgrade) {
-    if (options.prewarm !== false) assertRuntime(paths.dispatcher);
-    return installationResult("unchanged", paths, verified.release, current);
-  }
-
-  if (((targetExists && !backingUpUnmanaged) || (sharedRuntime && !sharedRuntimeMatches)) && !options.upgrade) {
-    throw new Error("已存在不同版本或摘要；升级时请使用 upgrade 或 install --upgrade");
-  }
-  const installedVersion = current ? current.release_version : sharedRuntime && sharedRuntime.release_version;
-  if (installedVersion && !options.allowDowngrade
-      && compareSemver(verified.release.release_version, installedVersion) < 0) {
-    throw new Error("目标版本低于已安装版本；确认回滚时请添加 --allow-downgrade");
-  }
-
-  const stateStaging = fs.mkdtempSync(path.join(paths.stateDir, ".install."));
-  const stagedInstall = path.join(stateStaging, "current");
-  const skillStaging = fs.mkdtempSync(path.join(paths.skillsDir, `.${SKILL_NAME}.install.`));
-  const stagedSkill = path.join(skillStaging, SKILL_NAME);
-  const shimTemporary = path.join(paths.binDir, `.${CLI_NAME}.${process.pid}.${Date.now()}.tmp`);
-  const stateBackup = path.join(paths.stateDir, `.backup.${process.pid}.${Date.now()}`);
-  const skillBackup = path.join(paths.skillsDir, `.${SKILL_NAME}.backup.${process.pid}.${Date.now()}`);
-  const shimBackup = path.join(paths.binDir, `.${CLI_NAME}.backup.${process.pid}.${Date.now()}`);
-  let stateMoved = false;
-  let skillMoved = false;
-  let shimMoved = false;
-  let hadState = false;
-  let hadSkill = false;
-  let hadShim = false;
-  let legacyBackupPath = null;
-  let legacyMoved = false;
-  const additionalSkills = Object.keys(verified.release.skills).filter((name) => name !== SKILL_NAME);
-  const additionalBackups = [];
-  const installedAdditional = [];
-  try {
-    stagePersistentInstall(stagedInstall, packageRoot, verified);
-    fs.cpSync(verified.skillRoot, stagedSkill, { recursive: true, errorOnExist: true });
-    if (treeDigest(stagedSkill) !== verified.release.skills[SKILL_NAME].sha256) {
-      throw new Error("staged Skill 摘要不匹配");
-    }
-    writeShim(shimTemporary, paths.dispatcher);
-
-    if (backingUpUnmanaged) {
-      legacyBackupPath = backupUnmanagedSkill(paths.target, paths.skillsDir, Boolean(legacy));
-      legacyMoved = true;
-    }
-    if (pathEntryExists(paths.installRoot)) {
-      fs.renameSync(paths.installRoot, stateBackup);
-      hadState = true;
-    }
-    fs.renameSync(stagedInstall, paths.installRoot);
-    stateMoved = true;
-    if (pathEntryExists(paths.target)) {
-      fs.renameSync(paths.target, skillBackup);
-      hadSkill = true;
-    }
-    fs.renameSync(stagedSkill, paths.target);
-    skillMoved = true;
-    for (const name of additionalSkills) {
-      const target = path.join(paths.skillsDir, name);
-      const backup = path.join(paths.skillsDir, `.${name}.backup.${process.pid}.${Date.now()}`);
-      if (pathEntryExists(target)) {
-        if (!current?.skills?.[name] || current.skills[name].path !== target) throw new Error(`拒绝覆盖未托管 Skill: ${name}`);
-        fs.renameSync(target, backup);
-        additionalBackups.push({ target, backup });
-      }
-      fs.cpSync(verified.skillRoots[name], target, { recursive: true, errorOnExist: true });
-      installedAdditional.push(target);
-    }
-    if (pathEntryExists(paths.shim)) {
-      fs.renameSync(paths.shim, shimBackup);
-      hadShim = true;
-    }
-    fs.renameSync(shimTemporary, paths.shim);
-    shimMoved = true;
-
-    const record = buildInstallationRecord(paths, verified.release);
-    writeJsonAtomic(paths.record, record);
-    assertInstalledState(paths, record, options.prewarm !== false);
-
-    removeOwnedDirectory(stateStaging, paths.stateDir, ".install.");
-    removeOwnedDirectory(skillStaging, paths.skillsDir, `.${SKILL_NAME}.install.`);
-    if (hadState) removeOwnedDirectory(stateBackup, paths.stateDir, ".backup.");
-    if (hadSkill) removeOwnedDirectory(skillBackup, paths.skillsDir, `.${SKILL_NAME}.backup.`);
-    for (const { backup } of additionalBackups) fs.rmSync(backup, { recursive: true, force: true });
-    if (hadShim) fs.rmSync(shimBackup, { force: true });
-    const result = installationResult(
-      options.migrateLegacy ? "migrated" : (current || (targetExists && !backingUpUnmanaged) ? "upgraded" : "installed"),
-      paths,
-      verified.release,
-      record,
-    );
-    if (legacyBackupPath) {
-      if (legacy) result.legacy_skill_backup = legacyBackupPath;
-      else result.unmanaged_skill_backup = legacyBackupPath;
+    const previousRecord = fs.existsSync(paths.record) ? fs.readFileSync(paths.record) : null;
+    const previousRegistry = fs.existsSync(paths.registry) ? fs.readFileSync(paths.registry) : null;
+    const current = safeReadInstallationRecord(paths.record, paths);
+    const targetExists = pathEntryExists(paths.target);
+    const legacy = targetExists && !current ? detectLegacySkill(paths.target) : null;
+    const backingUpUnmanaged = Boolean(targetExists && !current && options.backupUnmanaged);
+    if (options.migrateLegacy && !legacy) {
+        throw new Error(`目标 Skill 不是旧 Python Skill 或不存在: ${paths.target}`);
     }
-    return result;
-  } catch (error) {
-    if (shimMoved && pathEntryExists(paths.shim)) fs.rmSync(paths.shim, { force: true });
-    if (hadShim && pathEntryExists(shimBackup)) fs.renameSync(shimBackup, paths.shim);
-    if (skillMoved && pathEntryExists(paths.target)) removeOwnedDirectory(paths.target, paths.skillsDir, SKILL_NAME);
-    if (hadSkill && pathEntryExists(skillBackup)) fs.renameSync(skillBackup, paths.target);
-    for (const target of installedAdditional.reverse()) fs.rmSync(target, { recursive: true, force: true });
-    for (const { target, backup } of additionalBackups.reverse()) if (pathEntryExists(backup)) fs.renameSync(backup, target);
-    if (legacyMoved && legacyBackupPath && pathEntryExists(legacyBackupPath) && !pathEntryExists(paths.target)) {
-      fs.renameSync(legacyBackupPath, paths.target);
-    }
-    if (stateMoved && pathEntryExists(paths.installRoot)) removeOwnedDirectory(paths.installRoot, paths.stateDir, "current");
-    if (hadState && pathEntryExists(stateBackup)) fs.renameSync(stateBackup, paths.installRoot);
-    if (previousRecord === null) fs.rmSync(paths.record, { force: true });
-    else fs.writeFileSync(paths.record, previousRecord);
-    if (pathEntryExists(shimTemporary)) fs.rmSync(shimTemporary, { force: true });
-    if (pathEntryExists(stateStaging)) removeOwnedDirectory(stateStaging, paths.stateDir, ".install.");
-    if (pathEntryExists(skillStaging)) removeOwnedDirectory(skillStaging, paths.skillsDir, `.${SKILL_NAME}.install.`);
-    throw error;
-  }
-}
-
+    if (targetExists && !current && !backingUpUnmanaged) {
+        if (legacy) {
+            const markers = Object.entries(legacy).filter(([_, value]) => value).map(([name]) => name).join(", ");
+            throw new Error(`目标 Skill 包含旧 Python runtime 标记 (${markers})，拒绝覆盖: ${paths.target}\n` +
+                `  迁移方法: 使用 --backup-unmanaged 或运行 'ml-platform migrate' 先备份旧 Skill`);
+        }
+        if (fs.lstatSync(paths.target).isSymbolicLink()) {
+            throw new Error(`目标 Skill 路径是未托管的符号链接，拒绝覆盖: ${paths.target}\n` +
+                "  处理方法: 确认后使用 --backup-unmanaged 备份该链接并安装正式 Skill");
+        }
+        throw new Error(`目标 Skill 不受 ${PACKAGE_NAME} 管理，拒绝覆盖: ${paths.target}\n` +
+            "  处理方法: 确认后使用 --backup-unmanaged 备份原目录");
+    }
+    for (const name of Object.keys(verified.release.skills)) {
+        if (name === SKILL_NAME)
+            continue;
+        const target = path.join(paths.skillsDir, name);
+        if (pathEntryExists(target) && (!current?.skills?.[name] || current.skills[name].path !== target)) {
+            throw new Error(`拒绝覆盖未托管 Skill: ${name}`);
+        }
+    }
+    const sharedRuntime = safeReadRuntimeRecord(paths.runtimeRecord);
+    if (pathEntryExists(paths.installRoot) && !sharedRuntime) {
+        throw new Error(`持久 CLI 目录不受 ${PACKAGE_NAME} 管理，拒绝覆盖: ${paths.installRoot}`);
+    }
+    if (pathEntryExists(paths.shim) && (!current || sha256File(paths.shim) !== current.shim.sha256)
+        && (!sharedRuntime || !shimTargetsDispatcher(paths.shim, paths.dispatcher))) {
+        throw new Error(`CLI shim 不受 ${PACKAGE_NAME} 管理，拒绝覆盖: ${paths.shim}`);
+    }
+    const { registry, scopes, staleIds } = collectRegisteredScopes(paths);
+    const runtimeHealthy = runtimeMatchesRuntimeRecord(paths, sharedRuntime);
+    const scopeMatches = current && scopeSkillsMatchRelease(current, verified.release);
+    const scopeNeedsRepair = Boolean(current && scopeMatches && !scopeSkillsInstalled(current));
+    const currentComplete = Boolean(current && scopeMatches && runtimeHealthy
+        && scopeSkillsInstalled(current)
+        && shimMatchesRecord(paths, current)
+        && runtimeSupportsSkills(sharedRuntime, current.skills));
+    if (currentComplete && !options.upgrade) {
+        if (options.prewarm !== false)
+            assertRuntime(paths.dispatcher);
+        return installationResult("unchanged", paths, verified.release, current, sharedRuntime);
+    }
+    const scopeNeedsReplacement = !scopeMatches;
+    if (current && scopeNeedsReplacement && !options.upgrade) {
+        throw new Error("当前 scope 已安装不同版本或摘要；升级时请使用 upgrade 或 install --upgrade");
+    }
+    let stageRuntime = false;
+    if (!sharedRuntime) {
+        stageRuntime = true;
+    }
+    else if (!runtimeHealthy) {
+        if (!options.upgrade
+            && !runtimeIdentityMatchesRelease(sharedRuntime, packageRoot, verified.release)) {
+            throw new Error("共享 CLI 已损坏，但当前安装包不是其记录版本；请使用对应 release 执行 install --upgrade 修复");
+        }
+        stageRuntime = true;
+    }
+    else if (scopeNeedsReplacement && options.upgrade) {
+        stageRuntime = !runtimeMatchesRelease(paths, sharedRuntime, packageRoot, verified.release);
+    }
+    else if (!runtimeSupportsRelease(sharedRuntime, verified.release)) {
+        throw new Error("共享 CLI 不满足目标 Skill 的 requires_cli；升级时请使用 upgrade 或 install --upgrade");
+    }
+    if (stageRuntime) {
+        assertRuntimeCompatibleWithRegisteredScopes(scopes, paths, verified.release);
+    }
+    const installedVersion = sharedRuntime?.release_version;
+    if (stageRuntime && installedVersion && !options.allowDowngrade
+        && compareSemver(verified.release.release_version, installedVersion) < 0) {
+        throw new Error("目标版本低于已安装版本；确认回滚时请添加 --allow-downgrade");
+    }
+    const stateStaging = stageRuntime ? fs.mkdtempSync(path.join(paths.stateDir, ".install.")) : null;
+    const stagedInstall = stateStaging && path.join(stateStaging, "current");
+    const skillStaging = fs.mkdtempSync(path.join(paths.skillsDir, `.${SKILL_NAME}.install.`));
+    const stagedSkills = path.join(skillStaging, "skills");
+    const shimTemporary = path.join(paths.binDir, `.${CLI_NAME}.${process.pid}.${Date.now()}.tmp`);
+    const stateBackup = path.join(paths.stateDir, `.backup.${process.pid}.${Date.now()}`);
+    const shimBackup = path.join(paths.binDir, `.${CLI_NAME}.backup.${process.pid}.${Date.now()}`);
+    let stateMoved = false;
+    let shimMoved = false;
+    let hadState = false;
+    let hadShim = false;
+    let legacyBackupPath = null;
+    let legacyMoved = false;
+    const skillBackups = [];
+    const installedSkills = [];
+    try {
+        if (stageRuntime)
+            stagePersistentInstall(stagedInstall, packageRoot, verified);
+        fs.mkdirSync(stagedSkills);
+        for (const [name, source] of Object.entries(verified.skillRoots)) {
+            const target = path.join(stagedSkills, name);
+            fs.cpSync(source, target, { recursive: true, errorOnExist: true });
+            if (treeDigest(target) !== verified.release.skills[name].sha256) {
+                throw new Error(`staged Skill 摘要不匹配: ${name}`);
+            }
+        }
+        writeShim(shimTemporary, paths.dispatcher);
+        if (backingUpUnmanaged) {
+            legacyBackupPath = backupUnmanagedSkill(paths.target, paths.skillsDir, Boolean(legacy));
+            legacyMoved = true;
+        }
+        if (stageRuntime && pathEntryExists(paths.installRoot)) {
+            fs.renameSync(paths.installRoot, stateBackup);
+            hadState = true;
+        }
+        if (stageRuntime) {
+            fs.renameSync(stagedInstall, paths.installRoot);
+            stateMoved = true;
+        }
+        for (const name of Object.keys(verified.release.skills)) {
+            const target = path.join(paths.skillsDir, name);
+            const staged = path.join(stagedSkills, name);
+            const backup = path.join(paths.skillsDir, `.${name}.backup.${process.pid}.${Date.now()}`);
+            if (pathEntryExists(target)) {
+                fs.renameSync(target, backup);
+                skillBackups.push({ target, backup });
+            }
+            fs.renameSync(staged, target);
+            installedSkills.push(target);
+        }
+        if (pathEntryExists(paths.shim)) {
+            fs.renameSync(paths.shim, shimBackup);
+            hadShim = true;
+        }
+        fs.renameSync(shimTemporary, paths.shim);
+        shimMoved = true;
+        const runtime = safeReadRuntimeRecord(paths.runtimeRecord);
+        if (!runtimeMatchesRuntimeRecord(paths, runtime))
+            throw new Error("安装后的共享 CLI 摘要不匹配");
+        const record = buildInstallationRecord(paths, verified.release, runtime);
+        writeJsonAtomic(paths.record, record);
+        const nextRegistry = updateInstallationRegistry(registry, paths, staleIds);
+        writeJsonAtomic(paths.registry, nextRegistry);
+        assertInstalledState(paths, record, runtime, options.prewarm !== false);
+        if (stateStaging && pathEntryExists(stateStaging))
+            removeOwnedDirectory(stateStaging, paths.stateDir, ".install.");
+        if (pathEntryExists(skillStaging))
+            removeOwnedDirectory(skillStaging, paths.skillsDir, `.${SKILL_NAME}.install.`);
+        if (hadState)
+            removeOwnedDirectory(stateBackup, paths.stateDir, ".backup.");
+        for (const { backup } of skillBackups)
+            fs.rmSync(backup, { recursive: true, force: true });
+        if (hadShim)
+            fs.rmSync(shimBackup, { force: true });
+        const action = options.migrateLegacy ? "migrated"
+            : scopeNeedsRepair ? "repaired"
+                : current || (targetExists && !backingUpUnmanaged) ? "upgraded" : "installed";
+        const result = installationResult(action, paths, verified.release, record, runtime);
+        if (legacyBackupPath) {
+            if (legacy)
+                result.legacy_skill_backup = legacyBackupPath;
+            else
+                result.unmanaged_skill_backup = legacyBackupPath;
+        }
+        return result;
+    }
+    catch (error) {
+        if (shimMoved && pathEntryExists(paths.shim))
+            fs.rmSync(paths.shim, { force: true });
+        if (hadShim && pathEntryExists(shimBackup))
+            fs.renameSync(shimBackup, paths.shim);
+        for (const target of installedSkills.reverse())
+            fs.rmSync(target, { recursive: true, force: true });
+        for (const { target, backup } of skillBackups.reverse())
+            if (pathEntryExists(backup))
+                fs.renameSync(backup, target);
+        if (legacyMoved && legacyBackupPath && pathEntryExists(legacyBackupPath) && !pathEntryExists(paths.target)) {
+            fs.renameSync(legacyBackupPath, paths.target);
+        }
+        if (stateMoved && pathEntryExists(paths.installRoot))
+            removeOwnedDirectory(paths.installRoot, paths.stateDir, "current");
+        if (hadState && pathEntryExists(stateBackup))
+            fs.renameSync(stateBackup, paths.installRoot);
+        if (previousRecord === null)
+            fs.rmSync(paths.record, { force: true });
+        else
+            fs.writeFileSync(paths.record, previousRecord);
+        if (previousRegistry === null)
+            fs.rmSync(paths.registry, { force: true });
+        else
+            fs.writeFileSync(paths.registry, previousRegistry);
+        if (pathEntryExists(shimTemporary))
+            fs.rmSync(shimTemporary, { force: true });
+        if (stateStaging && pathEntryExists(stateStaging))
+            removeOwnedDirectory(stateStaging, paths.stateDir, ".install.");
+        if (pathEntryExists(skillStaging))
+            removeOwnedDirectory(skillStaging, paths.skillsDir, `.${SKILL_NAME}.install.`);
+        throw error;
+    }
+}
 function stagePersistentInstall(target, packageRoot, verified) {
-  fs.mkdirSync(path.join(target, "scripts"), { recursive: true });
-  fs.mkdirSync(path.join(target, "runtime"), { recursive: true });
-  for (const name of ["main.js", "lib.js"]) {
-    fs.copyFileSync(path.join(packageRoot, "scripts", name), path.join(target, "scripts", name));
-  }
-  fs.copyFileSync(path.join(packageRoot, "package.json"), path.join(target, "package.json"));
-  fs.chmodSync(path.join(target, "scripts", "main.js"), 0o755);
-  fs.cpSync(verified.clientRoot, path.join(target, "runtime", "business-client"), {
-    recursive: true,
-    errorOnExist: true,
-  });
-  fs.copyFileSync(path.join(packageRoot, "release.json"), path.join(target, "release.json"));
-  fs.copyFileSync(path.join(packageRoot, "release-policy.json"), path.join(target, "release-policy.json"));
-  writeJsonAtomic(path.join(target, "ownership.json"), {
-    schema_version: RUNTIME_RECORD_SCHEMA,
-    owner: PACKAGE_NAME,
-    release_version: verified.release.release_version,
-    cli_version: verified.release.cli.version,
-    cli_sha256: verified.release.cli.sha256,
-  });
-  if (treeDigest(path.join(target, "runtime", "business-client")) !== verified.release.cli.sha256) {
-    throw new Error("staged JavaScript CLI 摘要不匹配");
-  }
-}
-
-function buildInstallationRecord(paths, release) {
-  const record = {
-    schema_version: RECORD_SCHEMA,
-    owner: { package: PACKAGE_NAME, installation_id: installationId(paths) },
-    release_version: release.release_version,
-    agent: paths.agent,
-    scope: paths.scope,
-    cli: {
-      name: CLI_NAME,
-      version: release.cli.version,
-      path: paths.clientRoot,
-      sha256: release.cli.sha256,
-    },
-    skill: {
-      name: SKILL_NAME,
-      revision: release.skills[SKILL_NAME].revision,
-      requires_cli: release.skills[SKILL_NAME].requires_cli,
-      path: paths.target,
-      sha256: release.skills[SKILL_NAME].sha256,
-    },
-    shim: { path: paths.shim, sha256: sha256File(paths.shim) },
-    manager_sha256: treeDigest(path.join(paths.installRoot, "scripts")),
-    release_sha256: sha256File(path.join(paths.installRoot, "release.json")),
-    policy_sha256: sha256File(path.join(paths.installRoot, "release-policy.json")),
-  };
-  record.skills = Object.fromEntries(Object.entries(release.skills).map(([name, item]) => [name, {
-    name, revision: item.revision, requires_cli: item.requires_cli,
-    path: path.join(paths.skillsDir, name), sha256: item.sha256,
-  }]));
-  return record;
-}
-
-function assertInstalledState(paths, record, prewarm) {
-  if (!digestEquals(paths.clientRoot, record.cli.sha256)) throw new Error("安装后的 CLI 摘要不匹配");
-  if (!digestEquals(paths.target, record.skill.sha256)) throw new Error("安装后的 Skill 摘要不匹配");
-  for (const skill of Object.values(record.skills || {})) if (!digestEquals(skill.path, skill.sha256)) throw new Error(`安装后的 Skill 摘要不匹配: ${skill.name}`);
-  if (sha256File(paths.shim) !== record.shim.sha256) throw new Error("安装后的 CLI shim 摘要不匹配");
-  if (prewarm) assertRuntime(paths.dispatcher);
-}
-
-function installationResult(action, paths, release, record) {
-  const pathMatches = findAllOnPath(CLI_NAME);
-  const pathReady = pathMatches.some((candidate) => sameFileOrContent(candidate, paths.shim));
-  return {
-    ok: true,
-    action,
-    release_version: release.release_version,
-    cli_version: release.cli.version,
-    cli_root: paths.clientRoot,
-    cli_shim: paths.shim,
-    skill: SKILL_NAME,
-    skill_root: paths.target,
-    installation_record: paths.record,
-    ownership: record.owner,
-    path_ready: pathReady,
-    path_setup: pathReady ? null : `将 ${paths.binDir} 加入 PATH`,
-    restart_agent_session: true,
-  };
-}
-
+    fs.mkdirSync(path.join(target, "scripts"), { recursive: true });
+    fs.mkdirSync(path.join(target, "runtime"), { recursive: true });
+    for (const name of ["main.js", "lib.js"]) {
+        fs.copyFileSync(path.join(packageRoot, "scripts", name), path.join(target, "scripts", name));
+    }
+    fs.copyFileSync(path.join(packageRoot, "package.json"), path.join(target, "package.json"));
+    fs.chmodSync(path.join(target, "scripts", "main.js"), 0o755);
+    fs.cpSync(verified.clientRoot, path.join(target, "runtime", "business-client"), {
+        recursive: true,
+        errorOnExist: true,
+    });
+    fs.copyFileSync(path.join(packageRoot, "release.json"), path.join(target, "release.json"));
+    fs.copyFileSync(path.join(packageRoot, "release-policy.json"), path.join(target, "release-policy.json"));
+    writeJsonAtomic(path.join(target, "ownership.json"), {
+        schema_version: RUNTIME_RECORD_SCHEMA,
+        owner: PACKAGE_NAME,
+        release_version: verified.release.release_version,
+        cli_version: verified.release.cli.version,
+        cli_sha256: verified.release.cli.sha256,
+        manager_sha256: treeDigest(path.join(target, "scripts")),
+        release_sha256: sha256File(path.join(target, "release.json")),
+        policy_sha256: sha256File(path.join(target, "release-policy.json")),
+    });
+    if (treeDigest(path.join(target, "runtime", "business-client")) !== verified.release.cli.sha256) {
+        throw new Error("staged JavaScript CLI 摘要不匹配");
+    }
+}
+function buildInstallationRecord(paths, release, runtime) {
+    const record = {
+        schema_version: RECORD_SCHEMA,
+        owner: { package: PACKAGE_NAME, installation_id: installationId(paths) },
+        release_version: release.release_version,
+        agent: paths.agent,
+        scope: paths.scope,
+        cli: {
+            name: CLI_NAME,
+            version: runtime.cli_version,
+            path: paths.clientRoot,
+            sha256: runtime.cli_sha256,
+        },
+        skill: {
+            name: SKILL_NAME,
+            revision: release.skills[SKILL_NAME].revision,
+            requires_cli: release.skills[SKILL_NAME].requires_cli,
+            path: paths.target,
+            sha256: release.skills[SKILL_NAME].sha256,
+        },
+        shim: { path: paths.shim, sha256: sha256File(paths.shim) },
+    };
+    record.skills = Object.fromEntries(Object.entries(release.skills).map(([name, item]) => [name, {
+            name, revision: item.revision, requires_cli: item.requires_cli,
+            path: path.join(paths.skillsDir, name), sha256: item.sha256,
+        }]));
+    return record;
+}
+function assertInstalledState(paths, record, runtime, prewarm) {
+    if (!runtimeMatchesRuntimeRecord(paths, runtime))
+        throw new Error("安装后的 CLI 摘要不匹配");
+    if (!digestEquals(paths.target, record.skill.sha256))
+        throw new Error("安装后的 Skill 摘要不匹配");
+    for (const skill of Object.values(record.skills || {}))
+        if (!digestEquals(skill.path, skill.sha256))
+            throw new Error(`安装后的 Skill 摘要不匹配: ${skill.name}`);
+    if (sha256File(paths.shim) !== record.shim.sha256)
+        throw new Error("安装后的 CLI shim 摘要不匹配");
+    if (prewarm)
+        assertRuntime(paths.dispatcher);
+}
+function installationResult(action, paths, release, record, runtime) {
+    const pathMatches = findAllOnPath(CLI_NAME);
+    const pathReady = pathMatches.some((candidate) => sameFileOrContent(candidate, paths.shim));
+    return {
+        ok: true,
+        action,
+        release_version: release.release_version,
+        cli_version: runtime.cli_version,
+        runtime_release: runtime.release_version,
+        cli_root: paths.clientRoot,
+        cli_shim: paths.shim,
+        skill: SKILL_NAME,
+        skill_root: paths.target,
+        installation_record: paths.record,
+        ownership: record.owner,
+        path_ready: pathReady,
+        path_setup: pathReady ? null : `将 ${paths.binDir} 加入 PATH`,
+        restart_agent_session: true,
+    };
+}
+function runtimeMatchesRuntimeRecord(paths, runtime) {
+    return Boolean(runtime && !runtime.legacy
+        && digestEquals(paths.clientRoot, runtime.cli_sha256)
+        && digestEquals(path.join(paths.installRoot, "scripts"), runtime.manager_sha256)
+        && fs.existsSync(path.join(paths.installRoot, "release.json"))
+        && sha256File(path.join(paths.installRoot, "release.json")) === runtime.release_sha256
+        && fs.existsSync(path.join(paths.installRoot, "release-policy.json"))
+        && sha256File(path.join(paths.installRoot, "release-policy.json")) === runtime.policy_sha256);
+}
+function runtimeMatchesRelease(paths, runtime, packageRoot, release) {
+    return runtimeMatchesRuntimeRecord(paths, runtime)
+        && runtime.release_version === release.release_version
+        && runtime.cli_version === release.cli.version
+        && runtime.cli_sha256 === release.cli.sha256
+        && runtime.release_sha256 === sha256File(path.join(packageRoot, "release.json"))
+        && runtime.policy_sha256 === sha256File(path.join(packageRoot, "release-policy.json"));
+}
+function runtimeIdentityMatchesRelease(runtime, packageRoot, release) {
+    if (!runtime || runtime.release_version !== release.release_version
+        || runtime.cli_version !== release.cli.version
+        || runtime.cli_sha256 !== release.cli.sha256)
+        return false;
+    if (runtime.legacy)
+        return true;
+    return runtime.release_sha256 === sha256File(path.join(packageRoot, "release.json"))
+        && runtime.policy_sha256 === sha256File(path.join(packageRoot, "release-policy.json"));
+}
+function runtimeSupportsSkills(runtime, skills) {
+    return Boolean(runtime && Object.values(skills).every((skill) => versionSatisfies(runtime.cli_version, skill.requires_cli)));
+}
+function runtimeSupportsRelease(runtime, release) {
+    return runtimeSupportsSkills(runtime, release.skills);
+}
+function scopeSkillsMatchRelease(record, release) {
+    if (!record || record.release_version !== release.release_version)
+        return false;
+    const expectedNames = Object.keys(release.skills).sort();
+    const actualNames = Object.keys(record.skills || {}).sort();
+    if (expectedNames.join("\0") !== actualNames.join("\0"))
+        return false;
+    return expectedNames.every((name) => {
+        const current = record.skills[name];
+        const expected = release.skills[name];
+        return current.revision === expected.revision
+            && current.requires_cli === expected.requires_cli
+            && current.sha256 === expected.sha256;
+    });
+}
+function scopeSkillsInstalled(record) {
+    return Boolean(record && Object.values(record.skills || {}).every((skill) => digestEquals(skill.path, skill.sha256)));
+}
+function shimMatchesRecord(paths, record) {
+    return Boolean(record && fs.existsSync(paths.shim)
+        && sha256File(paths.shim) === record.shim.sha256
+        && shimTargetsDispatcher(paths.shim, paths.dispatcher));
+}
 function readInstallationRecord(file, paths) {
-  const record = readJson(file, "installation record");
-  if (record.schema_version !== RECORD_SCHEMA || record.owner?.package !== PACKAGE_NAME
-      || record.owner.installation_id !== installationId(paths)
-      || record.agent !== paths.agent || record.scope !== paths.scope
-      || record.cli?.name !== CLI_NAME || record.cli.path !== paths.clientRoot
-      || !isSemver(record.cli?.version) || !isSha256(record.cli?.sha256)
-      || record.skill?.name !== SKILL_NAME || record.skill.path !== paths.target
-      || !isSemver(record.skill?.revision) || !isSha256(record.skill?.sha256)
-      || record.shim?.path !== paths.shim || !isSha256(record.shim?.sha256)
-      || !isSha256(record.manager_sha256) || !isSha256(record.release_sha256)
-      || !isSha256(record.policy_sha256)) {
-    throw new Error("安装记录 ownership、路径、版本或摘要无效");
-  }
-  return record;
-}
-
+    const record = readJson(file, "installation record");
+    if (![RECORD_SCHEMA, LEGACY_RECORD_SCHEMA].includes(record.schema_version) || record.owner?.package !== PACKAGE_NAME
+        || record.owner.installation_id !== installationId(paths)
+        || record.agent !== paths.agent || record.scope !== paths.scope
+        || record.cli?.name !== CLI_NAME || record.cli.path !== paths.clientRoot
+        || !isSemver(record.cli?.version) || !isSha256(record.cli?.sha256)
+        || record.skill?.name !== SKILL_NAME || record.skill.path !== paths.target
+        || !isSemver(record.skill?.revision) || !isSha256(record.skill?.sha256)
+        || record.shim?.path !== paths.shim || !isSha256(record.shim?.sha256)
+        || !record.skills || typeof record.skills !== "object") {
+        throw new Error("安装记录 ownership、路径、版本或摘要无效");
+    }
+    for (const [name, skill] of Object.entries(record.skills)) {
+        if (!skill || skill.name !== name || skill.path !== path.join(paths.skillsDir, name)
+            || !isSemver(skill.revision) || !isSha256(skill.sha256)
+            || typeof skill.requires_cli !== "string") {
+            throw new Error("安装记录 Skill 路径、版本或摘要无效");
+        }
+    }
+    if (!record.skills[SKILL_NAME]
+        || record.skills[SKILL_NAME].sha256 !== record.skill.sha256
+        || record.skills[SKILL_NAME].path !== record.skill.path) {
+        throw new Error("安装记录主 Skill 与 Skill 列表不一致");
+    }
+    if (record.schema_version === LEGACY_RECORD_SCHEMA
+        && (!isSha256(record.manager_sha256) || !isSha256(record.release_sha256)
+            || !isSha256(record.policy_sha256))) {
+        throw new Error("旧安装记录运行时摘要无效");
+    }
+    return record;
+}
 function safeReadInstallationRecord(file, paths) {
-  try { return fs.existsSync(file) ? readInstallationRecord(file, paths) : null; }
-  catch (_) { return null; }
+    try {
+        return fs.existsSync(file) ? readInstallationRecord(file, paths) : null;
+    }
+    catch (_) {
+        return null;
+    }
 }
-
 function safeReadRuntimeRecord(file) {
-  try {
-    const record = readJson(file, "runtime ownership record");
-    return record.schema_version === RUNTIME_RECORD_SCHEMA && record.owner === PACKAGE_NAME
-      && isSemver(record.release_version) && isSemver(record.cli_version) && isSha256(record.cli_sha256)
-      ? record : null;
-  } catch (_) {
-    return null;
-  }
-}
-
+    try {
+        const record = readJson(file, "runtime ownership record");
+        const coreValid = record.owner === PACKAGE_NAME && isSemver(record.release_version)
+            && isSemver(record.cli_version) && isSha256(record.cli_sha256);
+        if (!coreValid)
+            return null;
+        if (record.schema_version === RUNTIME_RECORD_SCHEMA) {
+            return isSha256(record.manager_sha256) && isSha256(record.release_sha256)
+                && isSha256(record.policy_sha256) ? record : null;
+        }
+        if (record.schema_version === LEGACY_RUNTIME_RECORD_SCHEMA) {
+            return { ...record, legacy: true };
+        }
+        return null;
+    }
+    catch (_) {
+        return null;
+    }
+}
+function readInstallationRegistry(paths) {
+    if (!fs.existsSync(paths.registry)) {
+        return { schema_version: REGISTRY_SCHEMA, owner: PACKAGE_NAME, installations: {} };
+    }
+    const registry = readJson(paths.registry, "installation registry");
+    if (registry.schema_version !== REGISTRY_SCHEMA || registry.owner !== PACKAGE_NAME
+        || !registry.installations || typeof registry.installations !== "object"
+        || Array.isArray(registry.installations)) {
+        throw new Error("安装 scope 注册表格式无效");
+    }
+    for (const [id, entry] of Object.entries(registry.installations)) {
+        validateRegistryEntry(id, entry);
+    }
+    return registry;
+}
+function validateRegistryEntry(id, entry) {
+    if (!/^[0-9a-f]{64}$/.test(id) || !entry || typeof entry !== "object"
+        || !["codex", "pi", "custom"].includes(entry.agent)
+        || !["user", "project"].includes(entry.scope)
+        || typeof entry.skills_dir !== "string" || !path.isAbsolute(entry.skills_dir)
+        || typeof entry.bin_dir !== "string" || !path.isAbsolute(entry.bin_dir)
+        || typeof entry.record_path !== "string" || !path.isAbsolute(entry.record_path)
+        || entry.record_path !== path.join(entry.skills_dir, `.${SKILL_NAME}.ml-platform.json`)) {
+        throw new Error("安装 scope 注册表条目无效");
+    }
+    const scopePaths = scopePathsFromRegistryEntry(entry);
+    if (installationId(scopePaths) !== id)
+        throw new Error("安装 scope 注册表 installation_id 无效");
+}
+function scopePathsFromRegistryEntry(entry) {
+    const skillsDir = path.resolve(entry.skills_dir);
+    const binDir = path.resolve(entry.bin_dir);
+    return {
+        agent: entry.agent,
+        scope: entry.scope,
+        skillsDir,
+        target: path.join(skillsDir, SKILL_NAME),
+        record: path.join(skillsDir, `.${SKILL_NAME}.ml-platform.json`),
+        binDir,
+        shim: path.join(binDir, CLI_NAME),
+        stateDir: null,
+    };
+}
+function registeredScopePaths(entry, paths) {
+    const scopePaths = scopePathsFromRegistryEntry(entry);
+    return {
+        ...scopePaths,
+        stateDir: paths.stateDir,
+        installRoot: paths.installRoot,
+        clientRoot: paths.clientRoot,
+        dispatcher: paths.dispatcher,
+        runtimeRecord: paths.runtimeRecord,
+        registry: paths.registry,
+        lock: paths.lock,
+    };
+}
+function collectRegisteredScopes(paths) {
+    const registry = readInstallationRegistry(paths);
+    const scopes = [];
+    const staleIds = [];
+    for (const [id, entry] of Object.entries(registry.installations)) {
+        const scopePaths = registeredScopePaths(entry, paths);
+        if (!fs.existsSync(scopePaths.record)) {
+            if (!pathEntryExists(scopePaths.target)) {
+                staleIds.push(id);
+                continue;
+            }
+            throw new Error(`已登记 scope 缺少安装记录，拒绝变更共享 CLI: ${scopePaths.record}`);
+        }
+        let record;
+        try {
+            record = readInstallationRecord(scopePaths.record, scopePaths);
+        }
+        catch (error) {
+            throw new Error(`已登记 scope 安装记录无效，拒绝变更共享 CLI: ${error.message}`);
+        }
+        scopes.push({ id, paths: scopePaths, record });
+    }
+    return { registry, scopes, staleIds };
+}
+function registryEntry(paths) {
+    return {
+        agent: paths.agent,
+        scope: paths.scope,
+        skills_dir: paths.skillsDir,
+        bin_dir: paths.binDir,
+        record_path: paths.record,
+    };
+}
+function updateInstallationRegistry(registry, paths, staleIds) {
+    const installations = { ...registry.installations };
+    for (const id of staleIds)
+        delete installations[id];
+    installations[installationId(paths)] = registryEntry(paths);
+    return { schema_version: REGISTRY_SCHEMA, owner: PACKAGE_NAME, installations };
+}
+function registryContainsScope(registry, paths) {
+    const entry = registry.installations[installationId(paths)];
+    return Boolean(entry && entry.record_path === paths.record && entry.skills_dir === paths.skillsDir
+        && entry.bin_dir === paths.binDir);
+}
+function assertRuntimeCompatibleWithRegisteredScopes(scopes, currentPaths, release) {
+    const incompatible = [];
+    for (const scope of scopes) {
+        if (scope.id === installationId(currentPaths))
+            continue;
+        for (const skill of Object.values(scope.record.skills)) {
+            if (!versionSatisfies(release.cli.version, skill.requires_cli)) {
+                incompatible.push(`${scope.paths.skillsDir}/${skill.name} requires ${skill.requires_cli}`);
+            }
+        }
+    }
+    if (incompatible.length > 0) {
+        throw new Error(`目标共享 CLI ${release.cli.version} 与已登记 scope 不兼容: ${incompatible.join(", ")}`);
+    }
+}
 function installationId(paths) {
-  return crypto.createHash("sha256")
-    .update(`${paths.agent}\0${paths.scope}\0${paths.skillsDir}`, "utf8")
-    .digest("hex");
+    return crypto.createHash("sha256")
+        .update(`${paths.agent}\0${paths.scope}\0${paths.skillsDir}`, "utf8")
+        .digest("hex");
 }
-
 function writeShim(file, dispatcher) {
-  const source = `#!/usr/bin/env node\n"use strict";\nconst { spawnSync } = require("child_process");\nconst result = spawnSync(process.execPath, [${JSON.stringify(dispatcher)}, ...process.argv.slice(2)], { stdio: "inherit", env: process.env });\nif (result.error) { process.stderr.write(result.error.message + "\\n"); process.exitCode = 1; } else { process.exitCode = result.status === null ? 1 : result.status; }\n`;
-  fs.writeFileSync(file, source, { mode: 0o755 });
+    const source = `#!/usr/bin/env node\n"use strict";\nconst { spawnSync } = require("child_process");\nconst result = spawnSync(process.execPath, [${JSON.stringify(dispatcher)}, ...process.argv.slice(2)], { stdio: "inherit", env: process.env });\nif (result.error) { process.stderr.write(result.error.message + "\\n"); process.exitCode = 1; } else { process.exitCode = result.status === null ? 1 : result.status; }\n`;
+    fs.writeFileSync(file, source, { mode: 0o755 });
 }
-
 function shimTargetsDispatcher(shim, dispatcher) {
-  try { return fs.readFileSync(shim, "utf8").includes(JSON.stringify(dispatcher)); }
-  catch (_) { return false; }
+    try {
+        return fs.readFileSync(shim, "utf8").includes(JSON.stringify(dispatcher));
+    }
+    catch (_) {
+        return false;
+    }
 }
-
 function assertRuntime(dispatcher) {
-  const result = runCliRuntime(dispatcher, ["version"], false);
-  if (!result.ok) throw new Error(`CLI runtime 检查失败: ${result.detail || "未知错误"}`);
+    const result = runCliRuntime(dispatcher, ["version"], false);
+    if (!result.ok)
+        throw new Error(`CLI runtime 检查失败: ${result.detail || "未知错误"}`);
 }
-
 function runCliRuntime(dispatcher, args, inheritOutput) {
-  if (!fs.existsSync(dispatcher)) return { ok: false, detail: "缺少持久 ml-platform dispatcher" };
-  const result = spawnSync(process.execPath, [dispatcher, ...args], {
-    encoding: "utf8",
-    stdio: inheritOutput ? "inherit" : ["ignore", "pipe", "pipe"],
-    env: { ...process.env },
-  });
-  if (result.error) return { ok: false, detail: result.error.message };
-  const detail = inheritOutput ? null : (result.stdout || result.stderr || "").trim();
-  return { ok: result.status === 0, detail };
-}
-
+    if (!fs.existsSync(dispatcher))
+        return { ok: false, detail: "缺少持久 ml-platform dispatcher" };
+    const result = spawnSync(process.execPath, [dispatcher, ...args], {
+        encoding: "utf8",
+        stdio: inheritOutput ? "inherit" : ["ignore", "pipe", "pipe"],
+        env: { ...process.env },
+    });
+    if (result.error)
+        return { ok: false, detail: result.error.message };
+    const detail = inheritOutput ? null : (result.stdout || result.stderr || "").trim();
+    return { ok: result.status === 0, detail };
+}
 function runApiHealth(dispatcher, apiUrl) {
-  let parsed;
-  try { parsed = new URL(apiUrl); }
-  catch (_) { return { ok: false, detail: "--api-url 必须是绝对 HTTP(S) URL" }; }
-  if (!["http:", "https:"].includes(parsed.protocol) || !parsed.host) {
-    return { ok: false, detail: "--api-url 必须是绝对 HTTP(S) URL" };
-  }
-  return runCliRuntime(dispatcher, ["--api-url", apiUrl.replace(/\/+$/, ""), "health"], false);
-}
-
-function resolveEffectiveApiTarget(
-  options,
-  dispatcher,
-  env = process.env,
-  runtime = runCliRuntime,
-) {
-  if (options.apiUrl && String(options.apiUrl).trim()) {
-    return { apiUrl: String(options.apiUrl).trim(), source: "argument" };
-  }
-  if (env.ML_PLATFORM_API_URL && String(env.ML_PLATFORM_API_URL).trim()) {
-    return { apiUrl: String(env.ML_PLATFORM_API_URL).trim(), source: "environment" };
-  }
-  const configured = runtime(dispatcher, ["show-config"], false);
-  if (!configured.ok) {
-    return {
-      apiUrl: null,
-      source: "saved_config",
-      error: `无法读取已保存的 API 配置: ${configured.detail || "未知错误"}`,
-    };
-  }
-  let payload;
-  try {
-    payload = JSON.parse(configured.detail);
-  } catch (_) {
-    return { apiUrl: null, source: "saved_config", error: "show-config 未返回有效 JSON" };
-  }
-  const apiUrl = payload && payload.effective && payload.effective.api_url;
-  return apiUrl
-    ? { apiUrl: String(apiUrl).trim(), source: "saved_config" }
-    : { apiUrl: null, source: null };
-}
-
+    let parsed;
+    try {
+        parsed = new URL(apiUrl);
+    }
+    catch (_) {
+        return { ok: false, detail: "--api-url 必须是绝对 HTTP(S) URL" };
+    }
+    if (!["http:", "https:"].includes(parsed.protocol) || !parsed.host) {
+        return { ok: false, detail: "--api-url 必须是绝对 HTTP(S) URL" };
+    }
+    return runCliRuntime(dispatcher, ["--api-url", apiUrl.replace(/\/+$/, ""), "health"], false);
+}
+function resolveEffectiveApiTarget(options, dispatcher, env = process.env, runtime = runCliRuntime) {
+    if (options.apiUrl && String(options.apiUrl).trim()) {
+        return { apiUrl: String(options.apiUrl).trim(), source: "argument" };
+    }
+    if (env.ML_PLATFORM_API_URL && String(env.ML_PLATFORM_API_URL).trim()) {
+        return { apiUrl: String(env.ML_PLATFORM_API_URL).trim(), source: "environment" };
+    }
+    const configured = runtime(dispatcher, ["show-config"], false);
+    if (!configured.ok) {
+        return {
+            apiUrl: null,
+            source: "saved_config",
+            error: `无法读取已保存的 API 配置: ${configured.detail || "未知错误"}`,
+        };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(configured.detail);
+    }
+    catch (_) {
+        return { apiUrl: null, source: "saved_config", error: "show-config 未返回有效 JSON" };
+    }
+    const apiUrl = payload && payload.effective && payload.effective.api_url;
+    return apiUrl
+        ? { apiUrl: String(apiUrl).trim(), source: "saved_config" }
+        : { apiUrl: null, source: null };
+}
 function checkTree(checks, name, root, expected) {
-  if (!expected || !fs.existsSync(root)) {
-    checks.push({ name, ok: false, error: `缺少安装目录或预期摘要: ${root}` });
-    return;
-  }
-  try {
-    const actual = treeDigest(root);
-    checks.push({ name, ok: actual === expected, expected_sha256: expected, actual_sha256: actual });
-  } catch (error) {
-    checks.push({ name, ok: false, error: error.message });
-  }
+    if (!expected || !fs.existsSync(root)) {
+        checks.push({ name, ok: false, error: `缺少安装目录或预期摘要: ${root}` });
+        return;
+    }
+    try {
+        const actual = treeDigest(root);
+        checks.push({ name, ok: actual === expected, expected_sha256: expected, actual_sha256: actual });
+    }
+    catch (error) {
+        checks.push({ name, ok: false, error: error.message });
+    }
 }
-
 function checkFile(checks, name, file, expected) {
-  if (!expected || !fs.existsSync(file)) {
-    checks.push({ name, ok: false, error: `缺少安装文件或预期摘要: ${file}` });
-    return;
-  }
-  const actual = sha256File(file);
-  checks.push({ name, ok: actual === expected, expected_sha256: expected, actual_sha256: actual });
-}
-
+    if (!expected || !fs.existsSync(file)) {
+        checks.push({ name, ok: false, error: `缺少安装文件或预期摘要: ${file}` });
+        return;
+    }
+    const actual = sha256File(file);
+    checks.push({ name, ok: actual === expected, expected_sha256: expected, actual_sha256: actual });
+}
 function digestEquals(root, expected) {
-  try { return fs.existsSync(root) && treeDigest(root) === expected; }
-  catch (_) { return false; }
+    try {
+        return fs.existsSync(root) && treeDigest(root) === expected;
+    }
+    catch (_) {
+        return false;
+    }
 }
-
 function pathEntryExists(entry) {
-  try {
-    fs.lstatSync(entry);
-    return true;
-  } catch (error) {
-    if (error.code === "ENOENT") return false;
-    throw error;
-  }
-}
-
+    try {
+        fs.lstatSync(entry);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
 function withInstallLock(lockPath, callback) {
-  let descriptor;
-  try {
-    descriptor = fs.openSync(lockPath, "wx", 0o600);
-  } catch (error) {
-    if (error.code === "EEXIST") throw new Error(`另一个安装进程正在运行: ${lockPath}`);
-    throw error;
-  }
-  fs.closeSync(descriptor);
-  try { return callback(); }
-  finally { fs.rmSync(lockPath, { force: true }); }
-}
-
+    let descriptor;
+    try {
+        descriptor = fs.openSync(lockPath, "wx", 0o600);
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            throw new Error(`另一个安装进程正在运行: ${lockPath}`);
+        throw error;
+    }
+    fs.closeSync(descriptor);
+    try {
+        return callback();
+    }
+    finally {
+        fs.rmSync(lockPath, { force: true });
+    }
+}
 function removeOwnedDirectory(target, parent, requiredName) {
-  const resolvedParent = fs.realpathSync(parent);
-  const resolvedTarget = fs.realpathSync(target);
-  const basename = path.basename(resolvedTarget);
-  const nameAllowed = requiredName.endsWith(".")
-    ? basename.startsWith(requiredName)
-    : basename === requiredName;
-  if (path.dirname(resolvedTarget) !== resolvedParent || !nameAllowed) {
-    throw new Error(`拒绝删除不受安装器管理的目录: ${resolvedTarget}`);
-  }
-  fs.rmSync(resolvedTarget, { recursive: true, force: true });
-}
-
+    const resolvedParent = fs.realpathSync(parent);
+    const resolvedTarget = fs.realpathSync(target);
+    const basename = path.basename(resolvedTarget);
+    const nameAllowed = requiredName.endsWith(".")
+        ? basename.startsWith(requiredName)
+        : basename === requiredName;
+    if (path.dirname(resolvedTarget) !== resolvedParent || !nameAllowed) {
+        throw new Error(`拒绝删除不受安装器管理的目录: ${resolvedTarget}`);
+    }
+    fs.rmSync(resolvedTarget, { recursive: true, force: true });
+}
 function assertTopLevel(root, allowed, label) {
-  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) throw new Error(`${label} 目录不存在: ${root}`);
-  const actual = new Set(fs.readdirSync(root));
-  if (actual.size !== allowed.size || [...actual].some((item) => !allowed.has(item))) {
-    throw new Error(`${label} 顶层文件不在 allowlist`);
-  }
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory())
+        throw new Error(`${label} 目录不存在: ${root}`);
+    const actual = new Set(fs.readdirSync(root));
+    if (actual.size !== allowed.size || [...actual].some((item) => !allowed.has(item))) {
+        throw new Error(`${label} 顶层文件不在 allowlist`);
+    }
 }
-
 function assertAllowedClient(root) {
-  const actual = new Set(fs.readdirSync(root));
-  const required = ["package.json", "README.md", "src"];
-  if (required.some((item) => !actual.has(item)) || [...actual].some((item) => !CLIENT_TOP_LEVEL.has(item))) {
-    throw new Error("business client 顶层文件不在 allowlist");
-  }
-  const packageJson = readJson(path.join(root, "package.json"), "business client package.json");
-  if (packageJson.bin?.[CLI_NAME] !== "src/cli.js") throw new Error("business client bin 入口无效");
-}
-
+    const actual = new Set(fs.readdirSync(root));
+    const required = ["package.json", "README.md", "src"];
+    if (required.some((item) => !actual.has(item)) || [...actual].some((item) => !CLIENT_TOP_LEVEL.has(item))) {
+        throw new Error("business client 顶层文件不在 allowlist");
+    }
+    const packageJson = readJson(path.join(root, "package.json"), "business client package.json");
+    if (packageJson.bin?.[CLI_NAME] !== "src/cli.js")
+        throw new Error("business client bin 入口无效");
+}
 function rejectForbiddenTree(root, label) {
-  const visit = (directory) => {
-    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
-      const item = path.join(directory, entry.name);
-      if (entry.isSymbolicLink()) throw new Error(`${label} 不允许符号链接: ${item}`);
-      if (entry.isDirectory()) {
-        if (FORBIDDEN_DIRECTORIES.has(entry.name) && fs.readdirSync(item).length > 0) {
-          throw new Error(`${label} 包含禁止目录: ${item}`);
+    const visit = (directory) => {
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+            const item = path.join(directory, entry.name);
+            if (entry.isSymbolicLink())
+                throw new Error(`${label} 不允许符号链接: ${item}`);
+            if (entry.isDirectory()) {
+                if (FORBIDDEN_DIRECTORIES.has(entry.name) && fs.readdirSync(item).length > 0) {
+                    throw new Error(`${label} 包含禁止目录: ${item}`);
+                }
+                visit(item);
+            }
+            else if (entry.isFile()) {
+                if (FORBIDDEN_FILES.has(entry.name) || FORBIDDEN_SUFFIXES.has(path.extname(entry.name).toLowerCase())) {
+                    throw new Error(`${label} 包含禁止文件: ${item}`);
+                }
+            }
+            else {
+                throw new Error(`${label} 包含不支持的文件类型: ${item}`);
+            }
         }
-        visit(item);
-      } else if (entry.isFile()) {
-        if (FORBIDDEN_FILES.has(entry.name) || FORBIDDEN_SUFFIXES.has(path.extname(entry.name).toLowerCase())) {
-          throw new Error(`${label} 包含禁止文件: ${item}`);
-        }
-      } else {
-        throw new Error(`${label} 包含不支持的文件类型: ${item}`);
-      }
-    }
-  };
-  visit(root);
+    };
+    visit(root);
 }
-
 function rejectForbiddenContent(files, label) {
-  for (const file of files) {
-    if (!fs.statSync(file).isFile() || path.basename(file) === "release-policy.json") continue;
-    const text = fs.readFileSync(file, "utf8");
-    for (const rule of FORBIDDEN_CONTENT_PATTERNS) {
-      if (rule.pattern.test(text)) {
-        throw new Error(`${label} 包含禁止发布内容 ${rule.name}: ${file}`);
-      }
+    for (const file of files) {
+        if (!fs.statSync(file).isFile() || path.basename(file) === "release-policy.json")
+            continue;
+        const text = fs.readFileSync(file, "utf8");
+        for (const rule of FORBIDDEN_CONTENT_PATTERNS) {
+            if (rule.pattern.test(text)) {
+                throw new Error(`${label} 包含禁止发布内容 ${rule.name}: ${file}`);
+            }
+        }
     }
-  }
 }
-
 function treeDigest(root) {
-  const files = listFiles(root);
-  const hash = crypto.createHash("sha256");
-  for (const file of files) {
-    const relative = path.relative(root, file).split(path.sep).join("/");
-    hash.update(relative, "utf8");
-    hash.update("\0");
-    hash.update(sha256File(file), "utf8");
-    hash.update("\n");
-  }
-  return `sha256:${hash.digest("hex")}`;
-}
-
+    const files = listFiles(root);
+    const hash = crypto.createHash("sha256");
+    for (const file of files) {
+        const relative = path.relative(root, file).split(path.sep).join("/");
+        hash.update(relative, "utf8");
+        hash.update("\0");
+        hash.update(sha256File(file), "utf8");
+        hash.update("\n");
+    }
+    return `sha256:${hash.digest("hex")}`;
+}
 function listFiles(root) {
-  if (!fs.existsSync(root)) throw new Error(`目录不存在: ${root}`);
-  const result = [];
-  const visit = (directory) => {
-    const entries = fs.readdirSync(directory, { withFileTypes: true })
-      .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
-    for (const entry of entries) {
-      const item = path.join(directory, entry.name);
-      if (entry.isSymbolicLink()) throw new Error(`发布目录不允许符号链接: ${item}`);
-      if (entry.isDirectory()) visit(item);
-      else if (entry.isFile()) result.push(item);
-      else throw new Error(`发布目录包含不支持的文件类型: ${item}`);
-    }
-  };
-  visit(root);
-  return result;
-}
-
+    if (!fs.existsSync(root))
+        throw new Error(`目录不存在: ${root}`);
+    const result = [];
+    const visit = (directory) => {
+        const entries = fs.readdirSync(directory, { withFileTypes: true })
+            .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+        for (const entry of entries) {
+            const item = path.join(directory, entry.name);
+            if (entry.isSymbolicLink())
+                throw new Error(`发布目录不允许符号链接: ${item}`);
+            if (entry.isDirectory())
+                visit(item);
+            else if (entry.isFile())
+                result.push(item);
+            else
+                throw new Error(`发布目录包含不支持的文件类型: ${item}`);
+        }
+    };
+    visit(root);
+    return result;
+}
 function sha256File(file) {
-  return `sha256:${crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex")}`;
+    return `sha256:${crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex")}`;
 }
-
 function writeJsonAtomic(file, payload) {
-  const temporary = `${file}.${process.pid}.tmp`;
-  fs.writeFileSync(temporary, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 });
-  fs.renameSync(temporary, file);
+    const temporary = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, file);
 }
-
 function readJson(file, label) {
-  try { return JSON.parse(fs.readFileSync(file, "utf8")); }
-  catch (error) { throw new Error(`无法读取 ${label}: ${file}: ${error.message}`); }
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`无法读取 ${label}: ${file}: ${error.message}`);
+    }
 }
-
 function resolveInside(root, relative) {
-  const resolvedRoot = path.resolve(root);
-  const target = path.resolve(resolvedRoot, relative);
-  if (target === resolvedRoot || !target.startsWith(`${resolvedRoot}${path.sep}`)) {
-    throw new Error(`路径越界: ${relative}`);
-  }
-  return target;
-}
-
+    const resolvedRoot = path.resolve(root);
+    const target = path.resolve(resolvedRoot, relative);
+    if (target === resolvedRoot || !target.startsWith(`${resolvedRoot}${path.sep}`)) {
+        throw new Error(`路径越界: ${relative}`);
+    }
+    return target;
+}
 function normalizeRelative(value) {
-  if (value.includes("\\")) throw new Error(`checksum 路径必须使用 /: ${value}`);
-  const normalized = path.posix.normalize(value);
-  if (normalized !== value || normalized.startsWith("../") || normalized.startsWith("/") || normalized === "..") {
-    throw new Error(`非法相对路径: ${value}`);
-  }
-  return normalized;
-}
-
+    if (value.includes("\\"))
+        throw new Error(`checksum 路径必须使用 /: ${value}`);
+    const normalized = path.posix.normalize(value);
+    if (normalized !== value || normalized.startsWith("../") || normalized.startsWith("/") || normalized === "..") {
+        throw new Error(`非法相对路径: ${value}`);
+    }
+    return normalized;
+}
 function expandHome(value) {
-  if (value === "~") return os.homedir();
-  if (value.startsWith(`~${path.sep}`) || value.startsWith("~/")) return path.join(os.homedir(), value.slice(2));
-  return value;
+    if (value === "~")
+        return os.homedir();
+    if (value.startsWith(`~${path.sep}`) || value.startsWith("~/"))
+        return path.join(os.homedir(), value.slice(2));
+    return value;
 }
-
 function findAllOnPath(name) {
-  const matches = [];
-  const extensions = process.platform === "win32" ? [".cmd", ".exe", ""] : [""];
-  for (const directory of (process.env.PATH || "").split(path.delimiter).filter(Boolean)) {
-    for (const extension of extensions) {
-      const candidate = path.join(directory, `${name}${extension}`);
-      try {
-        fs.accessSync(candidate, fs.constants.X_OK);
-        if (fs.statSync(candidate).isFile()) matches.push(candidate);
-      } catch (_) { /* continue */ }
-    }
-  }
-  return matches;
-}
-
+    const matches = [];
+    const extensions = process.platform === "win32" ? [".cmd", ".exe", ""] : [""];
+    for (const directory of (process.env.PATH || "").split(path.delimiter).filter(Boolean)) {
+        for (const extension of extensions) {
+            const candidate = path.join(directory, `${name}${extension}`);
+            try {
+                fs.accessSync(candidate, fs.constants.X_OK);
+                if (fs.statSync(candidate).isFile())
+                    matches.push(candidate);
+            }
+            catch (_) { /* continue */ }
+        }
+    }
+    return matches;
+}
 function sameFileOrContent(left, right) {
-  try { return fs.realpathSync(left) === fs.realpathSync(right) || sha256File(left) === sha256File(right); }
-  catch (_) { return false; }
+    try {
+        return fs.realpathSync(left) === fs.realpathSync(right) || sha256File(left) === sha256File(right);
+    }
+    catch (_) {
+        return false;
+    }
 }
-
 function isSha256(value) {
-  return typeof value === "string" && /^sha256:[0-9a-f]{64}$/.test(value);
+    return typeof value === "string" && /^sha256:[0-9a-f]{64}$/.test(value);
 }
-
 function isSemver(value) {
-  return typeof value === "string" && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(value);
+    return typeof value === "string" && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(value);
 }
-
 function parseSemver(value) {
-  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/.exec(value);
-  if (!match) throw new Error("无法比较无效 SemVer");
-  return {
-    core: [Number(match[1]), Number(match[2]), Number(match[3])],
-    prerelease: match[4] ? match[4].split(".") : null,
-  };
-}
-
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/.exec(value);
+    if (!match)
+        throw new Error("无法比较无效 SemVer");
+    return {
+        core: [Number(match[1]), Number(match[2]), Number(match[3])],
+        prerelease: match[4] ? match[4].split(".") : null,
+    };
+}
 function compareSemver(left, right) {
-  const aParsed = parseSemver(left);
-  const bParsed = parseSemver(right);
-  const a = aParsed.core;
-  const b = bParsed.core;
-  for (let index = 0; index < 3; index += 1) {
-    if (a[index] !== b[index]) return a[index] < b[index] ? -1 : 1;
-  }
-  if (!aParsed.prerelease && !bParsed.prerelease) return 0;
-  if (!aParsed.prerelease) return 1;
-  if (!bParsed.prerelease) return -1;
-  const length = Math.max(aParsed.prerelease.length, bParsed.prerelease.length);
-  for (let index = 0; index < length; index += 1) {
-    if (index >= aParsed.prerelease.length) return -1;
-    if (index >= bParsed.prerelease.length) return 1;
-    const leftPart = aParsed.prerelease[index];
-    const rightPart = bParsed.prerelease[index];
-    if (leftPart === rightPart) continue;
-    const leftNumeric = /^\d+$/.test(leftPart);
-    const rightNumeric = /^\d+$/.test(rightPart);
-    if (leftNumeric && rightNumeric) return Number(leftPart) < Number(rightPart) ? -1 : 1;
-    if (leftNumeric !== rightNumeric) return leftNumeric ? -1 : 1;
-    return leftPart < rightPart ? -1 : 1;
-  }
-  return 0;
-}
-
+    const aParsed = parseSemver(left);
+    const bParsed = parseSemver(right);
+    const a = aParsed.core;
+    const b = bParsed.core;
+    for (let index = 0; index < 3; index += 1) {
+        if (a[index] !== b[index])
+            return a[index] < b[index] ? -1 : 1;
+    }
+    if (!aParsed.prerelease && !bParsed.prerelease)
+        return 0;
+    if (!aParsed.prerelease)
+        return 1;
+    if (!bParsed.prerelease)
+        return -1;
+    const length = Math.max(aParsed.prerelease.length, bParsed.prerelease.length);
+    for (let index = 0; index < length; index += 1) {
+        if (index >= aParsed.prerelease.length)
+            return -1;
+        if (index >= bParsed.prerelease.length)
+            return 1;
+        const leftPart = aParsed.prerelease[index];
+        const rightPart = bParsed.prerelease[index];
+        if (leftPart === rightPart)
+            continue;
+        const leftNumeric = /^\d+$/.test(leftPart);
+        const rightNumeric = /^\d+$/.test(rightPart);
+        if (leftNumeric && rightNumeric)
+            return Number(leftPart) < Number(rightPart) ? -1 : 1;
+        if (leftNumeric !== rightNumeric)
+            return leftNumeric ? -1 : 1;
+        return leftPart < rightPart ? -1 : 1;
+    }
+    return 0;
+}
 function versionSatisfies(version, range) {
-  const match = /^>=(\S+)\s+<(\S+)$/.exec(range);
-  if (!match) return false;
-  return compareSemver(version, match[1]) >= 0 && compareSemver(version, match[2]) < 0;
+    const match = /^>=(\S+)\s+<(\S+)$/.exec(range);
+    if (!match)
+        return false;
+    return compareSemver(version, match[1]) >= 0 && compareSemver(version, match[2]) < 0;
 }
-
 function migrate(options = {}, packageRoot = PACKAGE_ROOT) {
-  return install({ ...options, backupUnmanaged: true, migrateLegacy: true }, packageRoot);
+    return install({ ...options, backupUnmanaged: true, migrateLegacy: true }, packageRoot);
 }
-
 function packageVersion(packageRoot = PACKAGE_ROOT) {
-  try {
-    const release = readJson(path.join(packageRoot, "release.json"), "release manifest");
-    if (isSemver(release.release_version)) return release.release_version;
-  } catch (_) { /* source checkout may not have a generated release */ }
-  try {
-    const packageConfig = readJson(path.join(packageRoot, "package.json"), "package.json");
-    if (isSemver(packageConfig.version)) return packageConfig.version;
-  } catch (_) { /* use the package fallback */ }
-  return PACKAGE_VERSION;
-}
-
+    try {
+        const release = readJson(path.join(packageRoot, "release.json"), "release manifest");
+        if (isSemver(release.release_version))
+            return release.release_version;
+    }
+    catch (_) { /* source checkout may not have a generated release */ }
+    try {
+        const packageConfig = readJson(path.join(packageRoot, "package.json"), "package.json");
+        if (isSemver(packageConfig.version))
+            return packageConfig.version;
+    }
+    catch (_) { /* use the package fallback */ }
+    return PACKAGE_VERSION;
+}
 function shellQuote(value) {
-  return `'${String(value).replace(/'/g, "'\\''")}'`;
+    return `'${String(value).replace(/'/g, "'\\''")}'`;
 }
-
 function buildInstallCommand(paths, options, command, version, extraArgs = []) {
-  const args = [
-    "npm exec --yes --registry=https://registry.npmjs.org/",
-    `--package=${PACKAGE_NAME}@${version}`,
-    "--",
-    "ml-platform",
-    command,
-    "--agent", paths.agent,
-    "--scope", paths.scope,
-  ];
-  if (paths.projectDir) args.push("--project-dir", paths.projectDir);
-  if (options.skillsDir) args.push("--skills-dir", paths.skillsDir);
-  if (options.stateDir) args.push("--state-dir", paths.stateDir);
-  if (options.binDir) args.push("--bin-dir", paths.binDir);
-  args.push(...extraArgs);
-  return args.map((arg, index) => index < 2 ? arg : shellQuote(arg)).join(" ");
-}
-
+    const args = [
+        "npm exec --yes --registry=https://registry.npmjs.org/",
+        `--package=${PACKAGE_NAME}@${version}`,
+        "--",
+        "ml-platform",
+        command,
+        "--agent", paths.agent,
+        "--scope", paths.scope,
+    ];
+    if (paths.projectDir)
+        args.push("--project-dir", paths.projectDir);
+    if (options.skillsDir)
+        args.push("--skills-dir", paths.skillsDir);
+    if (options.stateDir)
+        args.push("--state-dir", paths.stateDir);
+    if (options.binDir)
+        args.push("--bin-dir", paths.binDir);
+    args.push(...extraArgs);
+    return args.map((arg, index) => index < 2 ? arg : shellQuote(arg)).join(" ");
+}
 module.exports = {
-  CHECKSUM_SCHEMA,
-  CLI_NAME,
-  PACKAGE_NAME,
-  PACKAGE_VERSION,
-  RECORD_SCHEMA,
-  RELEASE_SCHEMA,
-  SKILL_NAME,
-  compareSemver,
-  detectLegacySkill,
-  doctor,
-  install,
-  listFiles,
-  loadRelease,
-  migrate,
-  parseOptions,
-  resolveEffectiveApiTarget,
-  resolveInstallPaths,
-  sha256File,
-  status,
-  treeDigest,
-  verifyPackage,
+    CHECKSUM_SCHEMA,
+    CLI_NAME,
+    PACKAGE_NAME,
+    PACKAGE_VERSION,
+    RECORD_SCHEMA,
+    RELEASE_SCHEMA,
+    SKILL_NAME,
+    compareSemver,
+    detectLegacySkill,
+    doctor,
+    install,
+    listFiles,
+    loadRelease,
+    migrate,
+    parseOptions,
+    resolveEffectiveApiTarget,
+    resolveInstallPaths,
+    sha256File,
+    status,
+    treeDigest,
+    verifyPackage,
 };