@ai-wendao/ant 0.0.0-stage → 0.3.9

package/tools/migrate-legacy.mjs

@@ -0,0 +1,639 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process'
+import { createHash, randomUUID } from 'node:crypto'
+import { chmod, lstat, mkdir, open, readFile, readdir, rename, stat, unlink, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { delimiter, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PACKAGE_NAME = '@ai-wendao/ant'
+const ALIAS_NAME = 'ant'
+const PROFILE_NAME = 'desktop'
+const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
+const PACKAGE_VERSION = JSON.parse(await readFile(join(PACKAGE_ROOT, 'package.json'), 'utf8')).version
+const PROFILE_FILES = ['package.json', 'pnpm-lock.yaml', 'pnpm-workspace.yaml']
+
+function usage() {
+  process.stdout.write(`ANT 存量 Bundle 迁移工具
+
+用法：
+  ant-migrate inspect [--dsh-home <路径>]
+  ant-migrate migrate [--apply] [--dsh-cli <路径>] [--dsh-home <路径>]
+  ant-migrate rollback --backup <目录> [--apply] [--dsh-cli <路径>]
+
+migrate 和 rollback 默认只预检；只有显式传入 --apply 才会修改 DSH profile。
+`)
+}
+
+function parseArgs(argv) {
+  const [command = 'inspect', ...rest] = argv
+  if (command === '--help' || command === '-h' || command === 'help') return { help: true }
+  if (!['inspect', 'migrate', 'rollback'].includes(command)) throw new Error(`未知命令：${command}`)
+  const options = { command, apply: false }
+  for (let index = 0; index < rest.length; index += 1) {
+    const item = rest[index]
+    if (item === '--apply') options.apply = true
+    else if (item === '--dsh-home' || item === '--dsh-cli' || item === '--backup') {
+      const value = rest[index + 1]
+      if (!value || value.startsWith('--')) throw new Error(`${item} 需要一个路径`)
+      options[item.slice(2).replaceAll('-', '_')] = value
+      index += 1
+    } else throw new Error(`未知参数：${item}`)
+  }
+  if (command === 'rollback' && !options.backup) throw new Error('rollback 需要 --backup <备份目录>')
+  if (command !== 'rollback' && options.backup) throw new Error('--backup 仅用于 rollback')
+  return options
+}
+
+function resolveDshHome(configured) {
+  const candidate = configured?.trim() || process.env.DSH_HOME?.trim() || join(homedir(), '.dsh')
+  const expanded = candidate === '~' ? homedir()
+    : candidate.startsWith('~/') || candidate.startsWith('~\\')
+      ? join(homedir(), candidate.slice(2))
+      : candidate
+  return resolve(expanded)
+}
+
+function aliasPointsToAnt(spec) {
+  return typeof spec === 'string' && /^npm:@ai-wendao\/ant(?:@[^\s]+)?$/u.test(spec)
+}
+
+function directSpecIsAnt(spec) {
+  return typeof spec === 'string' && /^(?:=|\^|~)?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u.test(spec)
+}
+
+function directSpecMatchesTarget(spec, version = PACKAGE_VERSION) {
+  return spec === version
+}
+
+async function readProfile(dshHome) {
+  const dir = join(dshHome, 'profiles', PROFILE_NAME)
+  const manifestPath = join(dir, 'package.json')
+  let manifest
+  try {
+    manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
+  } catch (error) {
+    if (error?.code === 'ENOENT') throw new Error(`找不到 DSH Desktop profile：${manifestPath}。请先打开并初始化 DSH。`)
+    throw new Error(`无法读取 DSH profile 清单：${error instanceof Error ? error.message : String(error)}`)
+  }
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    throw new Error('DSH profile 清单不是 JSON 对象；工具不会修改。')
+  }
+  const dependencies = manifest.dependencies ?? {}
+  if (typeof dependencies !== 'object' || Array.isArray(dependencies)) {
+    throw new Error('DSH profile dependencies 格式异常；工具不会修改。')
+  }
+  const aliasSpec = dependencies[ALIAS_NAME]
+  const directSpec = dependencies[PACKAGE_NAME]
+  const bundles = manifest.dsh?.profile?.bundles ?? []
+  if (!Array.isArray(bundles) || !bundles.every((name) => typeof name === 'string')) {
+    throw new Error('DSH profile Bundle 列表格式异常；工具不会修改。')
+  }
+  if (aliasSpec !== undefined && directSpec !== undefined) {
+    if (aliasPointsToAnt(aliasSpec) && directSpecIsAnt(directSpec)
+      && bundles.includes(ALIAS_NAME) && bundles.includes(PACKAGE_NAME)) {
+      return { state: 'both', dir, manifestPath, manifest, aliasSpec, directSpec, bundles }
+    }
+    return { state: 'conflict', dir, manifestPath, manifest, aliasSpec, directSpec, bundles }
+  }
+  if (directSpec !== undefined) {
+    if (!bundles.includes(PACKAGE_NAME)) return { state: 'inconsistent', dir, manifestPath, manifest, directSpec, bundles }
+    return { state: 'current', dir, manifestPath, manifest, directSpec, bundles }
+  }
+  if (aliasSpec !== undefined) {
+    if (!aliasPointsToAnt(aliasSpec)) {
+      return { state: 'unknown-alias', dir, manifestPath, manifest, aliasSpec, bundles }
+    }
+    if (!bundles.includes(ALIAS_NAME)) {
+      return { state: 'inconsistent', dir, manifestPath, manifest, aliasSpec, bundles }
+    }
+    return { state: 'legacy-alias', dir, manifestPath, manifest, aliasSpec, bundles }
+  }
+  if (bundles.includes(ALIAS_NAME) || bundles.includes(PACKAGE_NAME)) {
+    return { state: 'inconsistent', dir, manifestPath, manifest, bundles }
+  }
+  return { state: 'not-installed', dir, manifestPath, manifest, bundles }
+}
+
+function findOnPath(command) {
+  const pathEntries = (process.env.PATH || '').split(delimiter)
+  const extensions = process.platform === 'win32'
+    ? (process.env.PATHEXT || '.EXE;.CMD;.BAT').split(';')
+    : ['']
+  for (const entry of pathEntries) {
+    for (const extension of extensions) {
+      const candidate = join(entry, `${command}${extension}`)
+      try {
+        if (process.platform === 'win32') {
+          const result = spawnSync('where.exe', [candidate], { encoding: 'utf8', windowsHide: true })
+          if (result.status === 0) return result.stdout.trim().split(/\r?\n/u)[0]
+        } else {
+          const result = spawnSync('test', ['-x', candidate])
+          if (result.status === 0) return candidate
+        }
+      } catch {}
+    }
+  }
+  return undefined
+}
+
+async function findDshCli(explicit) {
+  const candidates = [explicit, process.env.DSH_DESKTOP_CLI]
+  if (process.platform === 'darwin') {
+    candidates.push(
+      '/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh',
+      join(homedir(), 'Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh'),
+    )
+  } else if (process.platform === 'win32') {
+    const local = process.env.LOCALAPPDATA
+    const programFiles = process.env.ProgramFiles
+    if (local) candidates.push(join(local, 'Programs/DeepSeek Harness/resources/runtime/cli/bin/dsh.cmd'))
+    if (programFiles) candidates.push(join(programFiles, 'DeepSeek Harness/resources/runtime/cli/bin/dsh.cmd'))
+  }
+  candidates.push(findOnPath(process.platform === 'win32' ? 'dsh.cmd' : 'dsh'), findOnPath('dsh'))
+  for (const candidate of candidates) {
+    if (!candidate) continue
+    try {
+      if ((await stat(candidate)).isFile() && await isDesktopCli(candidate)) return resolve(candidate)
+    } catch {}
+  }
+  throw new Error('找不到可确认属于 DSH Desktop 的 dsh 命令。请在 DSH「更多 → 管理 dsh 命令」安装命令，或用 --dsh-cli 指定 Desktop CLI 完整路径。')
+}
+
+async function isDesktopCli(candidate) {
+  const source = await readFile(candidate, 'utf8')
+  return source.includes('ELECTRON_RUN_AS_NODE=1')
+    && source.includes('--expose-internals')
+    && source.includes('dsh-desktop-host')
+}
+
+function powershellQuote(value) {
+  return `'${String(value).replaceAll("'", "''")}'`
+}
+
+async function runDsh(cli, args, dshHome) {
+  const env = { ...process.env, DSH_HOME: dshHome }
+  if (process.platform !== 'win32' || extname(cli).toLowerCase() !== '.cmd') {
+    return spawnSync(cli, args, { encoding: 'utf8', windowsHide: true, maxBuffer: 8 * 1024 * 1024, env })
+  }
+  const body = [
+    '$ErrorActionPreference = \'Stop\'',
+    `& ${powershellQuote(cli)} ${args.map(powershellQuote).join(' ')}`,
+    'exit $LASTEXITCODE',
+  ].join('\n')
+  return spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', body], {
+    encoding: 'utf8', windowsHide: true, maxBuffer: 8 * 1024 * 1024, env,
+  })
+}
+
+async function assertDesktopClosed() {
+  if (process.platform === 'darwin') {
+    const result = spawnSync('ps', ['-A', '-o', 'comm=,args='], { encoding: 'utf8' })
+    if (result.error || result.status !== 0) throw new Error('无法确认 DSH 是否已退出；请完全退出 DSH 后再运行。')
+    const running = result.stdout.split(/\r?\n/u).some((line) =>
+      line.includes('DeepSeek Harness.app/Contents/MacOS/DeepSeek Harness')
+      || /^\s*DeepSeek Harness(?: Helper)?(?:\s|$)/u.test(line))
+    if (running) throw new Error('请先完全退出 DSH，再从独立终端重新运行迁移命令。')
+    return
+  }
+  if (process.platform === 'win32') {
+    const script = "$p = Get-CimInstance Win32_Process | Where-Object { $_.Name -like 'DeepSeek Harness*.exe' }; if ($p) { exit 3 } else { exit 0 }"
+    const result = spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], {
+      encoding: 'utf8', windowsHide: true,
+    })
+    if (result.error || result.status === null) throw new Error('无法确认 DSH 是否已退出；请完全退出 DSH 后再运行。')
+    if (result.status !== 0) throw new Error('请先完全退出 DSH，再从独立终端重新运行迁移命令。')
+    return
+  }
+  throw new Error('目前仅支持 macOS 和 Windows 上的 DSH Desktop profile。')
+}
+
+function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`)
+}
+
+function stateMessage(profile) {
+  const messages = {
+    'legacy-alias': '发现旧 ant alias，可以迁移到直接安装的 @ai-wendao/ant。',
+    both: '发现新旧 ANT 包都在 profile 中；只有存在有效迁移记录时才会续跑。',
+    current: '已经直接安装 @ai-wendao/ant，无需迁移。',
+    'not-installed': '这个 DSH profile 没有安装 ANT。',
+    conflict: 'profile 同时包含旧 alias 和 scoped 包；工具不会自动修改。',
+    'unknown-alias': 'ant 依赖指向非 ANT 包；工具不会修改。',
+    inconsistent: '依赖清单与 DSH Bundle 列表不一致；工具不会修改。',
+  }
+  return messages[profile.state] || 'profile 状态无法识别；工具不会修改。'
+}
+
+async function inspect(options) {
+  const dshHome = resolveDshHome(options.dsh_home)
+  const profile = await readProfile(dshHome)
+  printJson({
+    platform: process.platform,
+    profile: PROFILE_NAME,
+    dshHome,
+    state: profile.state,
+    aliasSpec: profile.aliasSpec ?? null,
+    directSpec: profile.directSpec ?? null,
+    target: `${PACKAGE_NAME}@${PACKAGE_VERSION}`,
+    message: stateMessage(profile),
+  })
+  if (profile.state === 'conflict' || profile.state === 'unknown-alias' || profile.state === 'inconsistent') process.exitCode = 2
+}
+
+async function createBackup(dshHome, profile) {
+  const backupDir = join(dshHome, 'ant-migration-backups', `${new Date().toISOString().replaceAll(':', '').replaceAll('.', '-')}-${randomUUID()}`)
+  await mkdir(backupDir, { recursive: true, mode: 0o700 })
+  const fileRows = []
+  for (const name of PROFILE_FILES) {
+    const source = join(profile.dir, name)
+    try {
+      const contents = await readFile(source)
+      await writeFile(join(backupDir, name), contents, { mode: 0o600, flag: 'wx' })
+      fileRows.push({ name, existed: true, sha256: createHash('sha256').update(contents).digest('hex') })
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error
+      fileRows.push({ name, existed: false })
+    }
+  }
+  const record = {
+    format: 1,
+    createdAt: new Date().toISOString(),
+    dshHome: resolve(dshHome),
+    profileDir: resolve(profile.dir),
+    profile: PROFILE_NAME,
+    originalAliasSpec: profile.aliasSpec,
+    targetSpec: `${PACKAGE_NAME}@${PACKAGE_VERSION}`,
+    targetVersion: PACKAGE_VERSION,
+    status: 'pending',
+    phase: 'prepared',
+    files: fileRows,
+  }
+  await writeFile(join(backupDir, 'migration.json'), `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600, flag: 'wx' })
+  if (process.platform !== 'win32') await chmod(backupDir, 0o700)
+  return { backupDir, record }
+}
+
+async function saveBackupRecord(backupDir, record) {
+  const temporary = join(backupDir, `.migration-${randomUUID()}.tmp`)
+  await writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600, flag: 'wx' })
+  await rename(temporary, join(backupDir, 'migration.json'))
+}
+
+async function validateBackup(backupDir, dshHome) {
+  const backupRoot = resolve(dshHome, 'ant-migration-backups')
+  const absolute = resolve(backupDir)
+  const backupRelative = relative(backupRoot, absolute)
+  if (!backupRelative || backupRelative === '..' || backupRelative.startsWith(`..${sep}`) || isAbsolute(backupRelative)) {
+    throw new Error('备份目录不属于当前 DSH home；没有修改任何文件。')
+  }
+  const record = JSON.parse(await readFile(join(absolute, 'migration.json'), 'utf8'))
+  if (record.format !== 1 || record.profile !== PROFILE_NAME || record.dshHome !== resolve(dshHome)
+    || record.profileDir !== resolve(dshHome, 'profiles', PROFILE_NAME)
+    || !aliasPointsToAnt(record.originalAliasSpec) || !directSpecIsAnt(record.targetVersion)
+    || record.targetSpec !== `${PACKAGE_NAME}@${record.targetVersion}`
+    || !['pending', 'completed', 'rolled-back'].includes(record.status)
+    || !['prepared', 'installing-scoped', 'scoped-installed', 'removing-alias', 'complete', 'rolled-back'].includes(record.phase)
+    || !Array.isArray(record.files)) {
+    throw new Error('备份归属、格式或原 alias 无效；没有修改任何文件。')
+  }
+  const seen = new Set()
+  for (const file of record.files) {
+    if (!PROFILE_FILES.includes(file.name) || seen.has(file.name) || typeof file.existed !== 'boolean') {
+      throw new Error('备份文件清单异常；没有修改任何文件。')
+    }
+    seen.add(file.name)
+    if (file.existed) {
+      if (typeof file.sha256 !== 'string' || !/^[a-f0-9]{64}$/u.test(file.sha256)) {
+        throw new Error(`备份文件 ${file.name} 校验值异常；没有修改任何文件。`)
+      }
+      const contents = await readFile(join(absolute, file.name))
+      const digest = createHash('sha256').update(contents).digest('hex')
+      if (digest !== file.sha256) throw new Error(`备份文件 ${file.name} 校验失败；没有修改任何文件。`)
+    } else if (file.sha256 !== undefined) {
+      throw new Error(`备份文件 ${file.name} 元数据异常；没有修改任何文件。`)
+    }
+  }
+  if (seen.size !== PROFILE_FILES.length) throw new Error('备份文件清单不完整；没有修改任何文件。')
+  return { absolute, record }
+}
+
+async function findPendingBackup(dshHome) {
+  const root = join(dshHome, 'ant-migration-backups')
+  let entries
+  try { entries = await readdir(root, { withFileTypes: true }) } catch (error) {
+    if (error?.code === 'ENOENT') return undefined
+    throw error
+  }
+  const pending = []
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const filename = join(root, entry.name, 'migration.json')
+    let record
+    try { record = JSON.parse(await readFile(filename, 'utf8')) } catch (error) {
+      if (error?.code === 'ENOENT') continue
+      throw new Error(`迁移记录无法读取：${filename}。请勿手动修改 profile。`)
+    }
+    if (record.status === 'pending' && record.dshHome === resolve(dshHome)) {
+      pending.push(await validateBackup(join(root, entry.name), dshHome))
+    }
+  }
+  if (pending.length > 1) throw new Error('发现多条未完成迁移记录；工具不会猜测目标。请保留备份并联系管理员。')
+  return pending[0]
+}
+
+function processIsAlive(pid) {
+  try { process.kill(pid, 0); return true } catch (error) { return error?.code === 'EPERM' }
+}
+
+async function acquireMigrationLock(dshHome) {
+  const lockPath = join(dshHome, 'ant-migration.lock')
+  const token = randomUUID()
+  await mkdir(dshHome, { recursive: true })
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    let handle
+    try {
+      handle = await open(lockPath, 'wx', 0o600)
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error
+      let current
+      try { current = JSON.parse(await readFile(lockPath, 'utf8')) } catch {
+        throw new Error(`发现无法识别的迁移锁：${lockPath}。确认没有迁移进程运行后，请联系管理员处理。`)
+      }
+      if (!Number.isSafeInteger(current.pid) || current.pid < 1 || processIsAlive(current.pid)) {
+        throw new Error(`另一个迁移进程正在运行（PID ${String(current.pid)}）；请等待它结束后重试。`)
+      }
+      const stalePath = `${lockPath}.${randomUUID()}.stale`
+      try { await rename(lockPath, stalePath); await unlink(stalePath) } catch (renameError) {
+        if (renameError?.code !== 'ENOENT') throw renameError
+      }
+      continue
+    }
+    try {
+      await handle.writeFile(`${JSON.stringify({ pid: process.pid, token, createdAt: new Date().toISOString() })}\n`)
+      await handle.sync()
+      await handle.close()
+    } catch (error) {
+      await handle.close().catch(() => undefined)
+      await unlink(lockPath).catch(() => undefined)
+      throw error
+    }
+    return async () => {
+      try {
+        const current = JSON.parse(await readFile(lockPath, 'utf8'))
+        if (current.token === token) await unlink(lockPath)
+      } catch (error) { if (error?.code !== 'ENOENT') throw error }
+    }
+  }
+  throw new Error('无法取得迁移锁；请稍后重试。')
+}
+
+async function acquireDesktopProfileLock(dshHome) {
+  const profileDir = join(dshHome, 'profiles', PROFILE_NAME)
+  const lockPath = join(profileDir, 'lock')
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    let handle
+    try {
+      handle = await open(lockPath, 'wx', 0o600)
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error
+      const details = await lstat(lockPath)
+      if (details.isSymbolicLink() || !details.isFile()) {
+        throw new Error('DSH Desktop profile lock 不是普通文件；工具不会修改。')
+      }
+      const rawOwner = await readFile(lockPath, 'utf8')
+      const owner = Number.parseInt(rawOwner, 10)
+      if (!Number.isSafeInteger(owner) || owner < 1 || processIsAlive(owner)) {
+        throw new Error(`DSH 正在启动或另一个 profile 操作正在运行（PID ${String(owner)}）；请等待并确认 DSH 完全退出后重试。`)
+      }
+      await unlink(lockPath)
+      continue
+    }
+    try {
+      await handle.writeFile(`${process.pid}\n`)
+      await handle.sync()
+    } catch (error) {
+      await handle.close().catch(() => undefined)
+      await unlink(lockPath).catch(() => undefined)
+      throw error
+    }
+    return async () => {
+      try {
+        const current = Number.parseInt(await readFile(lockPath, 'utf8'), 10)
+        if (current === process.pid) await unlink(lockPath)
+      } catch (error) { if (error?.code !== 'ENOENT') throw error }
+      finally { await handle.close() }
+    }
+  }
+  throw new Error('无法锁定 DSH Desktop profile；请稍后重试。')
+}
+
+function showDshOutput(result) {
+  if (result.stdout) process.stdout.write(result.stdout)
+  if (result.stderr) process.stderr.write(result.stderr)
+}
+
+async function invokeDsh(cli, args, label, dshHome) {
+  await assertDesktopClosed()
+  process.stdout.write(`执行：dsh plugin --profile ${PROFILE_NAME} ${args.at(-1)}（${label}）\n`)
+  const result = await runDsh(cli, ['plugin', '--profile', PROFILE_NAME, ...args], dshHome)
+  showDshOutput(result)
+  if (result.error) throw new Error(`${label}失败：${result.error.message}`)
+  if (result.status !== 0) throw new Error(`${label}失败，退出码 ${String(result.status)}`)
+}
+
+async function rollbackWithCli(cli, profile, aliasSpec) {
+  let current = await readProfile(profile.dshHome)
+  if (current.state === 'both') {
+    await invokeDsh(cli, ['remove', PACKAGE_NAME], '移除未完成的 scoped Bundle', profile.dshHome)
+  }
+  current = await readProfile(profile.dshHome)
+  if (current.aliasSpec === undefined) {
+    await invokeDsh(cli, ['add', `${ALIAS_NAME}@${aliasSpec}`], '恢复旧 ANT alias', profile.dshHome)
+  }
+  current = await readProfile(profile.dshHome)
+  if (current.aliasSpec !== aliasSpec || current.directSpec !== undefined
+    || !current.bundles.includes(ALIAS_NAME) || current.bundles.includes(PACKAGE_NAME)) {
+    throw new Error('旧 alias 回退后状态未通过检查；请保留备份并联系管理员。')
+  }
+}
+
+async function migrate(options) {
+  const dshHome = resolveDshHome(options.dsh_home)
+  if (!options.apply) {
+    const profile = await readProfile(dshHome)
+    process.stdout.write(`${stateMessage(profile)}\n`)
+    if (profile.state === 'current' || profile.state === 'not-installed') return
+    if (profile.state !== 'legacy-alias') throw new Error('检测到非标准 profile 状态；工具不会修改。')
+    process.stdout.write(`预检完成。执行迁移前请完全退出 DSH；确认后运行：ant-migrate migrate --apply${options.dsh_home ? ` --dsh-home "${options.dsh_home}"` : ''}${options.dsh_cli ? ` --dsh-cli "${options.dsh_cli}"` : ''}\n`)
+    return
+  }
+  const releaseLock = await acquireMigrationLock(dshHome)
+  let releaseProfileLock
+  try {
+    await assertDesktopClosed()
+    releaseProfileLock = await acquireDesktopProfileLock(dshHome)
+    await assertDesktopClosed()
+    let profile = await readProfile(dshHome)
+    let pending = await findPendingBackup(dshHome)
+    process.stdout.write(`${stateMessage(profile)}\n`)
+    if (!pending && (profile.state === 'current' || profile.state === 'not-installed')) return
+    if (!pending && profile.state !== 'legacy-alias') {
+      throw new Error('profile 不是可识别的旧 ANT alias；工具不会修改。')
+    }
+    if (!pending) {
+      const initial = profile
+      const backup = await createBackup(dshHome, initial)
+      pending = { absolute: backup.backupDir, record: backup.record }
+      process.stdout.write(`profile 备份已保存：${pending.absolute}\n`)
+    }
+    const { absolute: backupDir, record } = pending
+    const targetVersion = record.targetVersion || PACKAGE_VERSION
+    const targetSpec = `${PACKAGE_NAME}@${targetVersion}`
+    const cli = await findDshCli(options.dsh_cli)
+    await assertDesktopClosed()
+    const listResult = await runDsh(cli, ['plugin', '--profile', PROFILE_NAME, 'list'], dshHome)
+    showDshOutput(listResult)
+    if (listResult.error || listResult.status !== 0) {
+      throw new Error('DSH Desktop CLI 未能读取 desktop profile；请确认 CLI 路径正确且 profile 已初始化。')
+    }
+    profile = await readProfile(dshHome)
+    if (['conflict', 'unknown-alias', 'inconsistent'].includes(profile.state)) {
+      throw new Error('预检后 profile 状态与迁移记录不一致；迁移尚未继续，备份已保留。')
+    }
+    if (profile.state === 'current') {
+      if (!directSpecMatchesTarget(profile.directSpec, targetVersion)) {
+        throw new Error(`已发现直接安装的 ANT，但版本范围与迁移记录目标 ${targetSpec} 不符；工具不会覆盖。`)
+      }
+      record.status = 'completed'
+      record.phase = 'complete'
+      record.completedAt = new Date().toISOString()
+      await saveBackupRecord(backupDir, record)
+      printJson({ state: 'migrated', profile: PROFILE_NAME, package: PACKAGE_NAME, version: targetVersion, backupDir,
+        next: '请重新打开 DSH；检查 ANT 设置页、连接状态和模型目录。' })
+      return
+    }
+    if (profile.state === 'legacy-alias' || profile.state === 'not-installed') {
+      record.phase = 'installing-scoped'
+      await saveBackupRecord(backupDir, record)
+      try {
+        await invokeDsh(cli, ['add', '--save-exact', targetSpec], '安装 scoped ANT Bundle', dshHome)
+      } catch (error) {
+        const afterAttempt = await readProfile(dshHome)
+        if (afterAttempt.state !== 'both' && afterAttempt.state !== 'current') throw error
+      }
+      profile = await readProfile(dshHome)
+    }
+    if (profile.state === 'current' && directSpecMatchesTarget(profile.directSpec, targetVersion)) {
+      record.status = 'completed'
+      record.phase = 'complete'
+      record.completedAt = new Date().toISOString()
+      await saveBackupRecord(backupDir, record)
+      printJson({ state: 'migrated', profile: PROFILE_NAME, package: PACKAGE_NAME, version: targetVersion, backupDir,
+        next: '请重新打开 DSH；检查 ANT 设置页、连接状态和模型目录。' })
+      return
+    }
+    if (profile.state !== 'both' || !directSpecMatchesTarget(profile.directSpec, targetVersion)
+      || profile.aliasSpec !== record.originalAliasSpec) {
+      throw new Error('scoped 包未按预期安装；旧 alias 保留，备份已保留。关闭 DSH 后重试 migrate --apply。')
+    }
+    record.phase = 'scoped-installed'
+    await saveBackupRecord(backupDir, record)
+    record.phase = 'removing-alias'
+    await saveBackupRecord(backupDir, record)
+    try {
+      await invokeDsh(cli, ['remove', ALIAS_NAME], '移除旧 ANT alias', dshHome)
+    } catch (error) {
+      const afterAttempt = await readProfile(dshHome)
+      if (afterAttempt.state !== 'current') throw error
+    }
+    const finalProfile = await readProfile(dshHome)
+    if (finalProfile.state !== 'current' || !directSpecMatchesTarget(finalProfile.directSpec, targetVersion)) {
+      throw new Error('移除旧 alias 后 profile 未达到预期状态；请保持 DSH 关闭，再运行 migrate --apply 续跑。')
+    }
+    record.status = 'completed'
+    record.phase = 'complete'
+    record.completedAt = new Date().toISOString()
+    await saveBackupRecord(backupDir, record)
+    printJson({ state: 'migrated', profile: PROFILE_NAME, package: PACKAGE_NAME, version: targetVersion, backupDir,
+      next: '请重新打开 DSH；检查 ANT 设置页、连接状态和模型目录。' })
+  } catch (error) {
+    const pending = await findPendingBackup(dshHome).catch(() => undefined)
+    if (pending) {
+      process.stderr.write(`迁移未完成：${error instanceof Error ? error.message : String(error)}\n`)
+      process.stderr.write(`旧 alias 会保留到新版安装成功。保持 DSH 关闭，检查 profile 后可重试 ant-migrate migrate --apply。备份：${pending.absolute}\n`)
+      process.exitCode = 1
+      return
+    }
+    throw error
+  } finally {
+    try { if (releaseProfileLock) await releaseProfileLock() }
+    finally { await releaseLock() }
+  }
+}
+
+async function rollback(options) {
+  const dshHome = resolveDshHome(options.dsh_home)
+  const releaseLock = await acquireMigrationLock(dshHome)
+  let releaseProfileLock
+  try {
+    const { absolute, record } = await validateBackup(options.backup, dshHome)
+    const profile = await readProfile(dshHome)
+    if (record.status !== 'pending') throw new Error('该迁移记录已结束；rollback 只用于取消尚未完成的迁移。')
+    if (profile.state === 'legacy-alias' && profile.aliasSpec === record.originalAliasSpec) {
+      if (options.apply) {
+        record.status = 'rolled-back'
+        record.phase = 'rolled-back'
+        await saveBackupRecord(absolute, record)
+        process.stdout.write('旧 alias 仍完整存在；已将迁移标记为取消。\n')
+      } else {
+        process.stdout.write('预检完成：旧 alias 仍完整存在，无需回退。运行 rollback --apply 可取消这条迁移记录。\n')
+      }
+      return
+    }
+    if (profile.state !== 'both' || profile.aliasSpec !== record.originalAliasSpec) {
+      throw new Error('当前状态无法无损取消迁移；该工具不会重建旧 alias 或覆盖现有依赖。优先继续 migrate --apply。')
+    }
+    if (!options.apply) {
+      process.stdout.write(`预检完成。确认 DSH 已完全退出后运行：ant-migrate rollback --backup "${absolute}" --apply\n`)
+      return
+    }
+    await assertDesktopClosed()
+    releaseProfileLock = await acquireDesktopProfileLock(dshHome)
+    await assertDesktopClosed()
+    const cli = await findDshCli(options.dsh_cli)
+    const listResult = await runDsh(cli, ['plugin', '--profile', PROFILE_NAME, 'list'], dshHome)
+    showDshOutput(listResult)
+    if (listResult.error || listResult.status !== 0) throw new Error('DSH Desktop CLI 未能读取 desktop profile。')
+    const beforeRollback = await readProfile(dshHome)
+    if (beforeRollback.state !== 'both' || beforeRollback.aliasSpec !== record.originalAliasSpec) {
+      throw new Error('执行回退前 profile 已变化；工具不会继续。')
+    }
+    await rollbackWithCli(cli, { dshHome }, record.originalAliasSpec)
+    record.status = 'rolled-back'
+    record.phase = 'rolled-back'
+    await saveBackupRecord(absolute, record)
+    printJson({ state: 'rolled-back', profile: PROFILE_NAME, backupDir: absolute,
+      next: '新包已移除，原 alias 恢复。它会恢复迁移前的加载限制；优先修复并继续迁移。' })
+  } finally {
+    try { if (releaseProfileLock) await releaseProfileLock() }
+    finally { await releaseLock() }
+  }
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2))
+  if (options.help) return usage()
+  const nodeMajor = Number.parseInt(process.versions.node.split('.')[0], 10)
+  if (!Number.isInteger(nodeMajor) || nodeMajor < 20) throw new Error('迁移工具需要 Node.js 20 或更高版本。')
+  if (!['darwin', 'win32'].includes(process.platform)) throw new Error('目前仅支持 macOS 和 Windows 上的 DSH Desktop。')
+  if (options.command === 'inspect') return inspect(options)
+  if (options.command === 'migrate') return migrate(options)
+  return rollback(options)
+}
+
+main().catch((error) => {
+  process.stderr.write(`ant-migrate：${error instanceof Error ? error.message : String(error)}\n`)
+  process.exitCode = 1
+})