@zhuoyuezs/ml-platform 0.1.0

package/scripts/lib.js

@@ -0,0 +1,819 @@
+"use strict";
+
+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_NAME = "@zhuoyuezs/ml-platform";
+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 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");
+}
+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);
+
+function parseOptions(args) {
+  const options = {
+    agent: "codex",
+    scope: "user",
+    upgrade: false,
+    allowDowngrade: false,
+    prewarm: true,
+  };
+  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 {
+      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;
+  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") {
+    const 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,
+    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),
+  };
+}
+
+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 skill = release.skills && release.skills[SKILL_NAME];
+  if (!skill || skill.path !== `skills/${SKILL_NAME}` || !isSha256(skill.sha256)
+      || !isSemver(skill.revision) || typeof skill.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 信息");
+  }
+  if (!versionSatisfies(cli.version, skill.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([SKILL_NAME]), "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");
+  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 不一致");
+  }
+  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, clientRoot };
+}
+
+function status(options = {}, packageRoot = PACKAGE_ROOT) {
+  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 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,
+  };
+}
+
+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));
+  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 会话`,
+  });
+  if (options.apiUrl) {
+    const apiHealth = runApiHealth(paths.dispatcher, options.apiUrl);
+    checks.push({ name: "platform_api", ok: apiHealth.ok, detail: apiHealth.detail });
+  } else {
+    checks.push({ name: "platform_api", ok: null, skipped: true, reason: "未提供 --api-url" });
+  }
+  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,
+  };
+}
+
+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));
+}
+
+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 = fs.existsSync(paths.target);
+  if (targetExists && !current) {
+    throw new Error(`目标 Skill 不受 ${PACKAGE_NAME} 管理，拒绝覆盖: ${paths.target}`);
+  }
+  const sharedRuntime = safeReadRuntimeRecord(paths.runtimeRecord);
+  if (fs.existsSync(paths.installRoot) && !sharedRuntime) {
+    throw new Error(`持久 CLI 目录不受 ${PACKAGE_NAME} 管理，拒绝覆盖: ${paths.installRoot}`);
+  }
+  if (fs.existsSync(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 || (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;
+  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 (fs.existsSync(paths.installRoot)) {
+      fs.renameSync(paths.installRoot, stateBackup);
+      hadState = true;
+    }
+    fs.renameSync(stagedInstall, paths.installRoot);
+    stateMoved = true;
+    if (fs.existsSync(paths.target)) {
+      fs.renameSync(paths.target, skillBackup);
+      hadSkill = true;
+    }
+    fs.renameSync(stagedSkill, paths.target);
+    skillMoved = true;
+    if (fs.existsSync(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.`);
+    if (hadShim) fs.rmSync(shimBackup, { force: true });
+    return installationResult(current || targetExists ? "upgraded" : "installed", paths, verified.release, record);
+  } catch (error) {
+    if (shimMoved && fs.existsSync(paths.shim)) fs.rmSync(paths.shim, { force: true });
+    if (hadShim && fs.existsSync(shimBackup)) fs.renameSync(shimBackup, paths.shim);
+    if (skillMoved && fs.existsSync(paths.target)) removeOwnedDirectory(paths.target, paths.skillsDir, SKILL_NAME);
+    if (hadSkill && fs.existsSync(skillBackup)) fs.renameSync(skillBackup, paths.target);
+    if (stateMoved && fs.existsSync(paths.installRoot)) removeOwnedDirectory(paths.installRoot, paths.stateDir, "current");
+    if (hadState && fs.existsSync(stateBackup)) fs.renameSync(stateBackup, paths.installRoot);
+    if (previousRecord === null) fs.rmSync(paths.record, { force: true });
+    else fs.writeFileSync(paths.record, previousRecord);
+    if (fs.existsSync(shimTemporary)) fs.rmSync(shimTemporary, { force: true });
+    if (fs.existsSync(stateStaging)) removeOwnedDirectory(stateStaging, paths.stateDir, ".install.");
+    if (fs.existsSync(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.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) {
+  return {
+    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")),
+  };
+}
+
+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 摘要不匹配");
+  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,
+  };
+}
+
+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;
+}
+
+function safeReadInstallationRecord(file, paths) {
+  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;
+  }
+}
+
+function installationId(paths) {
+  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 });
+}
+
+function shimTargetsDispatcher(shim, dispatcher) {
+  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 || "未知错误"}`);
+}
+
+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 };
+}
+
+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 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 });
+  }
+}
+
+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 });
+}
+
+function digestEquals(root, expected) {
+  try { return fs.existsSync(root) && treeDigest(root) === expected; }
+  catch (_) { return false; }
+}
+
+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 }); }
+}
+
+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 });
+}
+
+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`);
+  }
+}
+
+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 入口无效");
+}
+
+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}`);
+        }
+        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);
+}
+
+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")}`;
+}
+
+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;
+}
+
+function sha256File(file) {
+  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);
+}
+
+function readJson(file, label) {
+  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;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+function sameFileOrContent(left, right) {
+  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);
+}
+
+function isSemver(value) {
+  return typeof value === "string" && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(value);
+}
+
+function compareSemver(left, right) {
+  if (!isSemver(left) || !isSemver(right)) throw new Error("无法比较无效 SemVer");
+  const a = left.split("-")[0].split(".").map(Number);
+  const b = right.split("-")[0].split(".").map(Number);
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) return a[index] < b[index] ? -1 : 1;
+  }
+  return 0;
+}
+
+function versionSatisfies(version, range) {
+  const match = /^(>=\d+\.\d+\.\d+)\s+(<\d+\.\d+\.\d+)$/.exec(range);
+  if (!match) return false;
+  return compareSemver(version, match[1].slice(2)) >= 0 && compareSemver(version, match[2].slice(1)) < 0;
+}
+
+module.exports = {
+  CHECKSUM_SCHEMA,
+  CLI_NAME,
+  PACKAGE_NAME,
+  RECORD_SCHEMA,
+  RELEASE_SCHEMA,
+  SKILL_NAME,
+  compareSemver,
+  doctor,
+  install,
+  listFiles,
+  loadRelease,
+  parseOptions,
+  resolveInstallPaths,
+  sha256File,
+  status,
+  treeDigest,
+  verifyPackage,
+};