@zhuoyuezs/ml-platform 0.1.0 → 0.1.1

package/DEVELOPMENT.md

@@ -10,7 +10,7 @@
 - Skill 直接调用正式命令 `ml-platform`，不嵌入 CLI runtime。
 - 正式 npm 包只有 `@zhuoyuezs/ml-platform`，正式 bin 只有 `ml-platform`。
 - `business-client-js/` 是 CLI 唯一源码，`skills/feature-management/` 是 Skill 唯一源码。
-- `npx @zhuoyuezs/ml-platform@<version> install` 是统一安装入口。
+- `npx --registry=https://registry.npmjs.org/ @zhuoyuezs/ml-platform@<version> install` 是统一安装入口。
 - npm `postinstall` 不得修改 Agent Skills 目录。
 - Python business client 只保留为迁移 oracle，不进入 release。
 - Codex CLI 不重新打包；当前只支持唯一自研 Host。
@@ -138,7 +138,7 @@ Host 副本、日志、会话数据、attic、凭证和实验文件。
 ```json
 {
   "name": "@zhuoyuezs/ml-platform",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "bin": {
     "ml-platform": "scripts/main.js"
   },

package/README.md

@@ -1,103 +1,76 @@
 # ML Platform
 
-`@zhuoyuezs/ml-platform` 通过一个 npm 产品提供 JavaScript business CLI 和
-`feature-management` Agent Skill。
+ML Platform 的 JavaScript CLI 和 `feature-management` Agent Skill。运行时只需要 Node.js 18+，
+不需要 Python 或 `uv`。
 
-正式包名和命令固定为：
+## 安装
 
-```text
-package: @zhuoyuezs/ml-platform
-bin:     ml-platform
-```
+在 Codex 项目根目录运行：
 
-> 当前状态：`0.1.0` release candidate 已实现 release v2 的外部 CLI + 纯 Skill 架构，并通过
-> 干净安装、cache 删除、`status`、`doctor` 和摘要验证。当前范围仅包含 Skill + CLI，不打包
-> Agent Host。正式发布必须从 `dist/package/` 执行 `npm publish`。
+```bash
+npx --yes --registry=https://registry.npmjs.org/ \
+  @zhuoyuezs/ml-platform@latest install \
+  --agent codex \
+  --scope project \
+  --project-dir "$PWD"
+```
 
-## 组件关系
+安装器会创建持久命令 `~/.local/bin/ml-platform`，并将 Skill 安装到：
 
 ```text
-开发人员 / CI
-  -> ml-platform CLI
-  -> ML Platform API
-
-Codex / ml-platform-host
-  -> feature-management Skill
-  -> ml-platform CLI
-  -> ML Platform API
+<project>/.agents/skills/feature-management/
 ```
 
-- CLI 可以独立运行，不依赖 Skill。
-- Skill 负责工作流程、业务契约和安全边界，直接调用 `ml-platform`。
-- npm release 同时固定 CLI version 和 Skill revision。
-- Skill 不再携带 business CLI、Python wheel、bootstrap 或安装器。
-- Codex CLI 和唯一自研 Host 是并行入口，都不进入本 npm 包。
+如果输出 `path_ready: false`，按 `path_setup` 提示配置 PATH，然后重启终端和 Agent。
 
-## 包结构
+用户级安装：
 
-```text
-@zhuoyuezs/ml-platform/
-├── package.json
-├── scripts/
-├── runtime/business-client/
-├── skills/feature-management/
-├── release.json
-├── checksums.json
-├── README.md
-└── DEVELOPMENT.md
+```bash
+npx --yes --registry=https://registry.npmjs.org/ \
+  @zhuoyuezs/ml-platform@latest install \
+  --agent codex \
+  --scope user
 ```
 
-归档中只有 `runtime/business-client/` 一份 business CLI。`skills/feature-management/` 是纯
-Skill，与 CLI 并列。
+## 迁移旧 Skill
 
-## 安装体验
-
-参考飞书 CLI，正式入口使用显式版本化 npx 命令：
+如果目标位置已有旧 Python Skill、实验 symlink 或其他未托管 Skill，确认后显式备份并安装：
 
 ```bash
-npx @zhuoyuezs/ml-platform@<version> install \
+npx --yes --registry=https://registry.npmjs.org/ \
+  @zhuoyuezs/ml-platform@latest install \
   --agent codex \
   --scope project \
-  --project-dir /absolute/path/to/project
+  --project-dir "$PWD" \
+  --backup-unmanaged
 ```
 
-安装命令必须建立可持续使用的 `ml-platform` 命令，再把纯 Skill 安装到目标 Agent 目录。它不能
-依赖一次性 npx cache，也不能通过 npm `postinstall` 修改用户 Skills。
-
-默认 runtime 位于 `~/.local/share/ml-platform/current/`，shim 位于
-`~/.local/bin/ml-platform`。安装结果中的 `path_ready` 和 `path_setup` 会说明是否还需把 bin
-目录加入 PATH。隔离测试可显式传入 `--state-dir` 和 `--bin-dir`。
+安装器会保留带时间戳的备份，不会直接删除原 Skill。
 
-安装后：
+## 使用
 
 ```bash
-ml-platform version
-ml-platform status --agent codex --scope project --project-dir /absolute/path/to/project
-ml-platform doctor --agent codex --scope project --project-dir /absolute/path/to/project
-
-ml-platform configure --api-url http://<approved-host>:<port>
+ml-platform configure --api-url http://<host>:<port>
 ml-platform health
+ml-platform list-parameters
+ml-platform apply /absolute/path/to/catalog --dry-run
+ml-platform status --agent codex --scope project --project-dir "$PWD"
+ml-platform doctor --agent codex --scope project --project-dir "$PWD"
 ```
 
-## Canonical Source
+查看完整命令：
 
-```text
-business-client-js/                 JavaScript CLI 唯一源码
-skills/feature-management/          Skill 唯一源码
-npm/ml-platform/                    npm dispatcher 与 installer 唯一源码
-npm/scripts/build_ml_platform_release.py
-agent_poc/codex-host/               唯一自研 Host
+```bash
+ml-platform --help
 ```
 
-不要修改 `dist/`、临时安装目录或 Agent Skills 安装副本。Python `business-client/` 只保留为迁移
-oracle，不进入 npm release。
+## 包内容
 
-## 当前开发状态
+- 一份 JavaScript business CLI；
+- 一份纯 `feature-management` Skill；
+- 显式安装、升级、迁移、状态、校验和回滚逻辑。
 
-1. `business-client-js` parity 与纯 `feature-management` Skill 已完成并独立验收。
-2. npm v2 builder、dispatcher、持久 installer、ownership、digest 与回滚已完成。
-3. 新的本地 `.tgz`、`.tgz.sha256` 和 Codex project clean install smoke 已通过。
-4. Agent Host 当前不在本包构建范围内；后续需明确需求后单独推进。
+本包不包含 Codex CLI、Python business-client wheel、Agent Host、平台服务端、模型训练或
+Kubernetes 部署。
 
-完整约束见 [DEVELOPMENT.md](DEVELOPMENT.md) 和
-[`npm/docs/AGENT_SKILL_CLI_PACKAGING_ARCHITECTURE.md`](../docs/AGENT_SKILL_CLI_PACKAGING_ARCHITECTURE.md)。
+开发和发布约束见 [DEVELOPMENT.md](DEVELOPMENT.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuoyuezs/ml-platform",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "ML 数据平台 business CLI 与 Agent Skills 管理工具",
   "bin": {
     "ml-platform": "scripts/main.js"

package/release.json

@@ -25,7 +25,7 @@
     "ml_data_platform.feature_set/v1",
     "ml_data_platform.dataset_manifest/v1"
   ],
-  "release_version": "0.1.0",
+  "release_version": "0.1.1",
   "runtime_requirements": {
     "node": ">=18"
   },
@@ -34,9 +34,9 @@
     "feature-management": {
       "path": "skills/feature-management",
       "requires_cli": ">=0.5.0 <0.6.0",
-      "revision": "0.1.0",
+      "revision": "0.1.1",
       "sha256": "sha256:f7c2ba836338602f6f01ebec18b595a366f5dd1bcbfcb58e249cda5c10bd61dd"
     }
   },
-  "source_commit": "0a124d08d6d35f07b6bd90bb37fd81ff0f698ab7"
+  "source_commit": "07e4f763c89c574d417e37d23d84cf5bc04120d7"
 }

package/scripts/lib.js

@@ -7,7 +7,9 @@ const path = require("path");
 const { spawnSync } = require("child_process");
 const RELEASE_POLICY = require("../release-policy.json");
 
-const PACKAGE_NAME = "@zhuoyuezs/ml-platform";
+const PACKAGE_CONFIG = require("../package.json");
+const PACKAGE_NAME = PACKAGE_CONFIG.name;
+const PACKAGE_VERSION = PACKAGE_CONFIG.version;
 const CLI_NAME = "ml-platform";
 const SKILL_NAME = "feature-management";
 const RELEASE_SCHEMA = "data_platform.ml_platform_release/v2";
@@ -31,6 +33,7 @@ function parseOptions(args) {
     upgrade: false,
     allowDowngrade: false,
     prewarm: true,
+    backupUnmanaged: false,
   };
   const valueFlags = new Map([
     ["--agent", "agent"],
@@ -54,6 +57,8 @@ function parseOptions(args) {
       options.allowDowngrade = true;
     } else if (arg === "--no-prewarm") {
       options.prewarm = false;
+    } else if (arg === "--backup-unmanaged") {
+      options.backupUnmanaged = true;
     } else {
       throw new Error(`未知参数: ${arg}`);
     }
@@ -68,6 +73,7 @@ function resolveInstallPaths(options = {}) {
   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") {
@@ -76,7 +82,7 @@ function resolveInstallPaths(options = {}) {
       : 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()));
+    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");
@@ -98,6 +104,7 @@ function resolveInstallPaths(options = {}) {
   return {
     agent,
     scope,
+    projectDir,
     skillsDir,
     target,
     record: path.join(skillsDir, `.${SKILL_NAME}.ml-platform.json`),
@@ -247,6 +254,29 @@ function doctor(options = {}, packageRoot = PACKAGE_ROOT) {
   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;
@@ -320,18 +350,70 @@ function install(options = {}, packageRoot = PACKAGE_ROOT) {
   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;
+}
+
+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;
+}
+
 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 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 (fs.existsSync(paths.installRoot) && !sharedRuntime) {
+  if (pathEntryExists(paths.installRoot) && !sharedRuntime) {
     throw new Error(`持久 CLI 目录不受 ${PACKAGE_NAME} 管理，拒绝覆盖: ${paths.installRoot}`);
   }
-  if (fs.existsSync(paths.shim) && (!current || sha256File(paths.shim) !== current.shim.sha256)
+  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}`);
   }
@@ -360,7 +442,7 @@ function installLocked(options, packageRoot, verified, paths) {
     return installationResult("unchanged", paths, verified.release, current);
   }
 
-  if ((targetExists || (sharedRuntime && !sharedRuntimeMatches)) && !options.upgrade) {
+  if (((targetExists && !backingUpUnmanaged) || (sharedRuntime && !sharedRuntimeMatches)) && !options.upgrade) {
     throw new Error("已存在不同版本或摘要；升级时请使用 upgrade 或 install --upgrade");
   }
   const installedVersion = current ? current.release_version : sharedRuntime && sharedRuntime.release_version;
@@ -383,6 +465,8 @@ function installLocked(options, packageRoot, verified, paths) {
   let hadState = false;
   let hadSkill = false;
   let hadShim = false;
+  let legacyBackupPath = null;
+  let legacyMoved = false;
   try {
     stagePersistentInstall(stagedInstall, packageRoot, verified);
     fs.cpSync(verified.skillRoot, stagedSkill, { recursive: true, errorOnExist: true });
@@ -391,19 +475,23 @@ function installLocked(options, packageRoot, verified, paths) {
     }
     writeShim(shimTemporary, paths.dispatcher);
 
-    if (fs.existsSync(paths.installRoot)) {
+    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 (fs.existsSync(paths.target)) {
+    if (pathEntryExists(paths.target)) {
       fs.renameSync(paths.target, skillBackup);
       hadSkill = true;
     }
     fs.renameSync(stagedSkill, paths.target);
     skillMoved = true;
-    if (fs.existsSync(paths.shim)) {
+    if (pathEntryExists(paths.shim)) {
       fs.renameSync(paths.shim, shimBackup);
       hadShim = true;
     }
@@ -419,19 +507,32 @@ function installLocked(options, packageRoot, verified, paths) {
     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);
+    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;
+    }
+    return result;
   } 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 (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);
+    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 (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.`);
+    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;
   }
 }
@@ -442,6 +543,7 @@ function stagePersistentInstall(target, packageRoot, verified) {
   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,
@@ -618,6 +720,16 @@ function digestEquals(root, expected) {
   catch (_) { return false; }
 }
 
+function pathEntryExists(entry) {
+  try {
+    fs.lstatSync(entry);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
 function withInstallLock(lockPath, callback) {
   let descriptor;
   try {
@@ -782,34 +894,101 @@ function isSemver(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,
+  };
+}
+
 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);
+  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 = /^(>=\d+\.\d+\.\d+)\s+(<\d+\.\d+\.\d+)$/.exec(range);
+  const match = /^>=(\S+)\s+<(\S+)$/.exec(range);
   if (!match) return false;
-  return compareSemver(version, match[1].slice(2)) >= 0 && compareSemver(version, match[2].slice(1)) < 0;
+  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);
+}
+
+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;
+}
+
+function shellQuote(value) {
+  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(" ");
 }
 
 module.exports = {
   CHECKSUM_SCHEMA,
   CLI_NAME,
   PACKAGE_NAME,
+  PACKAGE_VERSION,
   RECORD_SCHEMA,
   RELEASE_SCHEMA,
   SKILL_NAME,
   compareSemver,
+  detectLegacySkill,
   doctor,
   install,
   listFiles,
   loadRelease,
+  migrate,
   parseOptions,
   resolveInstallPaths,
   sha256File,

package/scripts/main.js

@@ -7,23 +7,25 @@ const { spawnSync } = require("child_process");
 const {
   doctor,
   install,
+  migrate,
   parseOptions,
   status,
 } = require("./lib");
 
-const MANAGEMENT_COMMANDS = new Set(["install", "upgrade", "status", "doctor"]);
+const MANAGEMENT_COMMANDS = new Set(["install", "upgrade", "migrate", "status", "doctor"]);
 const BUSINESS_ENTRY = path.resolve(__dirname, "..", "runtime", "business-client", "src", "cli.js");
 
 function usage() {
   return `用法:
-  ml-platform install [--agent codex|pi|custom] [--scope user|project] [--skills-dir PATH] [--project-dir PATH] [--state-dir PATH] [--bin-dir PATH] [--upgrade] [--allow-downgrade]
+  ml-platform install [--agent codex|pi|custom] [--scope user|project] [--skills-dir PATH] [--project-dir PATH] [--state-dir PATH] [--bin-dir PATH] [--upgrade] [--allow-downgrade] [--backup-unmanaged]
   ml-platform upgrade [install options]
+  ml-platform migrate [--agent codex|pi|custom] [--scope user|project] [--skills-dir PATH] [--project-dir PATH]
   ml-platform status  [--agent codex|pi|custom] [--scope user|project] [--skills-dir PATH] [--project-dir PATH] [--state-dir PATH] [--bin-dir PATH]
   ml-platform doctor  [status options] [--api-url URL]
   ml-platform <business-command> [args]
 
 安装管理命令:
-  install, upgrade, status, doctor
+  install, upgrade, migrate, status, doctor
 
 其余已注册业务命令由同一份 JavaScript Business CLI 执行。
 `;
@@ -70,6 +72,11 @@ function main(argv) {
     printJson(install(options));
     return 0;
   }
+  if (command === "migrate") {
+    const result = migrate(options);
+    printJson(result);
+    return result.ok ? 0 : 1;
+  }
   if (command === "status") {
     const result = status(options);
     printJson(result);