@ai-wendao/ant 0.3.8 → 0.3.9

package/MIGRATION.md

@@ -0,0 +1,83 @@
+# DSH Agent 操作说明：迁移旧 ANT alias
+
+本说明用于指导已安装旧 `ant` alias 的成员迁移，不代表允许静默修改 profile。修改前必须向成员说明操作并取得确认。
+
+## 适用范围
+
+仅迁移 DSH Desktop 的 `desktop` profile 中以依赖键 `ant` 安装、指向 `@ai-wendao/ant` 的旧 npm alias。已经直接安装 `@ai-wendao/ant` 的 profile 无需迁移。检测到其他来源、重复依赖、异常清单时停止，不要自行修复。
+
+目标 DSH RC2 要求 Bundle 客户端模块身份与 npm 包名称一致。旧 alias 会让冷启动时的客户端身份不匹配。新版应直接安装 `@ai-wendao/ant`。**普通 Desktop profile 优先使用 DSH 自带的插件管理界面；不需要系统 Node.js 或 npm。**旧 alias 先卸载，新包安装完成后再启用。不要删除整个 DSH profile。
+
+## 推荐方式：在 DSH 插件页操作
+
+此方式适用于 DSH Desktop RC2 使用默认、启用 HMR 的 Desktop profile，且目标 ANT 版本已发布到 npm：
+
+1. 打开 **插件 → ANT**，点击 **卸载** 并确认。
+2. 回到插件列表，点击 **添加插件**，输入已发布的直接包名，例如 `@ai-wendao/ant@0.3.9`，然后点击 **安装**。
+3. 安装完成后启用 ANT，打开设置页，检查服务连接与获准模型。
+
+RC2 的 Desktop 基础 profile 默认启用 HMR；官方管理器在该模式下会先卸载 Bundle，再用随 DSH 提供的包管理器移除依赖。包卸载本身不会调用 ANT 的“断开设备”操作，也不会清空 DSH 凭证存储。若 profile 禁用了 HMR，管理器会提示先停止 profile；此时改用下方 CLI 备用流程。真实成员 profile 的凭证保留仍需在目标 RC2 客户端上验收。
+
+## CLI 备用方式
+
+仅当 DSH 插件页提示需要停止 profile，或需要管理员批量、受控处理时使用。该 CLI 是同一份跨 macOS/Windows 的 JavaScript 文件，不是双击式安装器；要求 Node.js 20+、npm 和 DSH Desktop CLI，并需要在终端执行。若团队要求成员不安装 Node/npm 且不使用终端，这条备用路径不满足该体验，需要另行选定免安装分发方式。
+
+### 执行规程
+
+1. 仅当决定使用 CLI 备用路径时，运行 `ant-migrate inspect`。它只检查 `DSH_HOME/profiles/desktop/package.json`，不读取凭证文件或把密钥复制到命令参数、日志或备份。
+2. 若状态是 `current` 或 `not-installed`，结束流程。若是 `conflict`、`unknown-alias` 或 `inconsistent`，停止并报告诊断，不要尝试清理。
+3. 对 `legacy-alias`，向成员解释需要完全退出并重新打开 DSH、迁移期间不会运行 DSH，以及失败会保留备份；确认成员没有需要继续运行的任务，并取得明确确认。
+4. 先运行 `ant-migrate migrate` 查看预检结果。让成员完全退出 DSH，再从独立终端运行下方的 `--apply` 命令。迁移助手确认 DSH 已退出、CLI 能读取 Desktop profile 后，会备份依赖清单和锁文件；随后先安装 scoped 包，再移除旧 alias。
+5. 记录命令输出的备份目录。成功后重新打开 DSH，检查 ANT 设置页、连接状态和获准模型；如需重新验证邮箱，先检查凭证状态，不要自动清空或重建 profile。
+6. 安装新版失败时，旧 alias 会保留。若在“新旧包都已安装”的中间状态中断，保持 DSH 关闭并重跑 `migrate --apply` 续跑；`rollback` 仅用于在该中间态取消迁移。完成迁移后不提供回到旧 alias 的自动回滚，因为这会恢复已知的加载故障。不要手工改 `package.json`、`pnpm-lock.yaml`，不要复制 `node_modules`。
+
+DSH 必须完全退出后才能运行包变更命令。迁移工具是独立进程，不依赖 DSH 退出后仍有子进程驻留；它不会静默关闭 DSH、终止任务或自动重启应用。迁移期间工具会持有 RC2 Desktop profile 启动锁，防止并发打开 profile；请等命令结束后再启动 DSH。过程若被中断，备份目录中的状态记录用于安全续跑，不应手工编辑 profile 清单。
+
+## 权限与数据
+
+迁移工具不会提权。若读取 profile 或创建备份时收到权限错误，它会停止；先为运行迁移命令的终端授予访问 DSH profile 与备份目录的权限，再重试。不要用 `sudo`，也不要把 profile 复制到其他位置来绕过系统权限。
+
+成员凭证、ANT 服务地址和模型设置保存在 DSH/ANT 的独立存储键中，不属于 npm 包目录。卸载旧 Bundle 不会执行“断开账号”或删除这些凭证；活动会话会在 Bundle 退出时结束，重新加载后由保留的凭证恢复。工具只备份包清单和锁文件，不读取或复制密钥。
+
+## 运行方式
+
+要求 Node.js 20+，并需要 DSH Desktop 自带的 CLI。工具只有一份跨平台 JavaScript 实现，不需要分别签名、打包 macOS 与 Windows 应用。若终端找不到 `dsh`，在 DSH 的“更多 → 管理 dsh 命令”安装官方命令，或通过 `--dsh-cli` 传入 Desktop CLI 完整路径。Windows 使用 DSH 安装目录中的 `resources/runtime/cli/bin/dsh.cmd`；macOS 使用应用包中的 `Contents/Resources/runtime/cli/bin/dsh`。
+
+如果从仓库运行：
+
+```sh
+node packages/ant-bundle/tools/migrate-legacy.mjs inspect
+node packages/ant-bundle/tools/migrate-legacy.mjs migrate
+```
+
+成员完全退出 DSH 后再应用：
+
+```sh
+node packages/ant-bundle/tools/migrate-legacy.mjs migrate --apply
+```
+
+安装了系统 Node.js 的成员也可以从已发布 npm 包运行：
+
+```sh
+npm exec --yes --package @ai-wendao/ant@0.3.9 -- ant-migrate inspect
+npm exec --yes --package @ai-wendao/ant@0.3.9 -- ant-migrate migrate
+```
+
+退出 DSH 后执行变更：
+
+```sh
+npm exec --yes --package @ai-wendao/ant@0.3.9 -- ant-migrate migrate --apply
+```
+
+若 CLI 不在 PATH，可追加 `--dsh-cli "<Desktop CLI 完整路径>"`；若 DSH 使用自定义数据目录，可追加 `--dsh-home "<DSH_HOME 路径>"`。
+
+## 回退
+
+`migrate --apply` 会输出受限权限的备份目录，备份包含 profile 的 `package.json`、`pnpm-lock.yaml`、`pnpm-workspace.yaml`（若存在）及其 SHA-256 校验值，不包含密钥库。备份仅用于迁移状态核验和保留原始清单，不等于离线恢复包。确认 DSH 已退出后，通过同一工具调用：
+
+```sh
+npm exec --yes --package @ai-wendao/ant@0.3.9 -- ant-migrate rollback --backup "<备份目录>"
+npm exec --yes --package @ai-wendao/ant@0.3.9 -- ant-migrate rollback --backup "<备份目录>" --apply
+```
+
+回退只在 scoped 包已安装、旧 alias 尚未移除的中间态工作；它会卸载 scoped 包并保留旧 alias。已完成迁移的 profile 不接受该回退，避免自动恢复已知有加载问题的 alias。若安装包时 npm registry 不可用，保持 DSH 关闭，稍后重新运行 `migrate --apply`。

package/README.md

@@ -0,0 +1,9 @@
+# ANT for DeepSeek Harness
+
+ANT connects a DeepSeek Harness Desktop profile to its team's approved models and collaboration services.
+
+## Existing `ant` alias installations
+
+DSH RC2 requires a Bundle's client module identity to match its npm package name. Profiles that installed `ant` as an npm alias for `@ai-wendao/ant` need a one-time package-key migration. Use DSH's Plugins page for the normal Desktop profile; the cross-platform migration CLI is a fallback.
+
+For the normal Desktop profile, migrate from DSH's **Plugins** page by uninstalling the old ANT package and installing `@ai-wendao/ant` directly. This uses DSH's bundled package manager and does not require system Node.js/npm. Read [MIGRATION.md](./MIGRATION.md) first. The `ant-migrate` CLI is a fallback for profiles where the UI cannot unload the running bundle; it requires Node.js 20+, npm, and the DSH Desktop CLI. Neither path clears ANT credentials or model settings by design. This package does not publish or deploy ANT.

package/client.js

@@ -1,5 +1,5 @@
 window.__ModuleLoader__.load({
-  id: 'ant',
+  id: '@ai-wendao/ant',
   factory: (require) => {
     var module = { exports: {} }
     var exports = module.exports
@@ -7,6 +7,7 @@ window.__ModuleLoader__.load({
     const h = createElement
     const SERVICE_URL_STORAGE_KEY = 'ant-team-service-url'
     const DEVICE_ID_STORAGE_KEY = 'ant-team-device-id'
+    const ANT_BUNDLE_PACKAGE_NAME = '@ai-wendao/ant'
     const ANT_API_PROTOCOL_VERSIONS = [1]
     const panelStyle = {
       display: 'grid', alignContent: 'start', gap: 14, padding: 18,
@@ -61,6 +62,31 @@ window.__ModuleLoader__.load({
     }
     const inject = ['slots', 'remote', 'remote.credentials', 'remote.settings', 'remote.pluginManager']
 
+    async function readLocalJsonResponse(response) {
+      const contentType = response.headers?.get?.('content-type') || ''
+      const isJson = /^(?:application|text)\/(?:[a-z0-9!#$&^_.+-]+\+)?json(?:\s*;|$)/iu.test(contentType.trim())
+      if (contentType && !isJson) {
+        if (response.status === 404) {
+          throw new Error('DSH 未找到 ANT 本地接口。请确认 ANT Bundle 已更新，并完全退出后重新启动 DSH。')
+        }
+        throw new Error(`DSH 返回了非 JSON 响应（HTTP ${response.status}）。`)
+      }
+      try {
+        return await response.json()
+      } catch {
+        if (response.status === 404) {
+          throw new Error('DSH 未找到 ANT 本地接口。请确认 ANT Bundle 已更新，并完全退出后重新启动 DSH。')
+        }
+        throw new Error(`DSH 返回的 ANT 响应格式无效（HTTP ${response.status}）。`)
+      }
+    }
+
+    function directInstallSpec(release) {
+      return release?.version && release?.package_name
+        ? `${release.package_name}@${release.version}`
+        : ''
+    }
+
     function loadServiceUrl() {
       try { return normalizeServiceUrl(localStorage.getItem(SERVICE_URL_STORAGE_KEY) || '') || '' } catch { return '' }
     }
@@ -152,7 +178,7 @@ window.__ModuleLoader__.load({
           if (typeof manager?.listBundles !== 'function') throw new Error('当前 DSH 未提供 Bundle 版本读取接口。')
           const listed = await manager.listBundles()
           if (!listed.ok) throw new Error(listed.error?.message || '无法读取已安装的 ANT Bundle 版本。')
-          const installed = listed.value.find((bundle) => bundle.name === 'ant' && bundle.installed)
+          const installed = listed.value.find((bundle) => bundle.name === ANT_BUNDLE_PACKAGE_NAME && bundle.installed)
           if (typeof installed?.version !== 'string') throw new Error('无法确定当前 ANT Bundle 版本。')
           const response = await fetch('/api/ant-teams/service-info', {
             method: 'POST',
@@ -163,7 +189,7 @@ window.__ModuleLoader__.load({
               api_protocol_versions: ANT_API_PROTOCOL_VERSIONS,
             }),
           })
-          const result = await response.json()
+          const result = await readLocalJsonResponse(response)
           if (!response.ok) throw new Error(result.message || `版本检查失败（${response.status}）`)
           const serverProtocols = Array.isArray(result.server_api_protocol_versions) ? result.server_api_protocol_versions : []
           const sharedProtocols = Array.isArray(result.shared_api_protocol_versions) ? result.shared_api_protocol_versions : []
@@ -234,7 +260,7 @@ window.__ModuleLoader__.load({
         try {
           await requireCompatibleService(serviceUrl, true)
           const response = await fetch('/api/ant-teams/models', { method: 'POST' })
-          const result = await response.json()
+          const result = await readLocalJsonResponse(response)
           if (!response.ok) {
             if (response.status === 401) setNeedsReconnect(true)
             throw new Error(result.message || `刷新失败（${response.status}）`)
@@ -255,9 +281,23 @@ window.__ModuleLoader__.load({
         setBundleUpdate({ state: 'checking', currentVersion: '', message: '正在检查 ANT 更新…' })
         setApprovedBuilds([])
         try {
-          const response = await fetch('/api/ant-teams/bundle-release', { cache: 'no-store' })
-          const release = await response.json()
+          const response = await fetch('/api/ant-teams/bundle-release', {
+            cache: 'no-store', headers: { 'x-ant-bundle-capabilities': 'direct-package-install' },
+          })
+          const release = await readLocalJsonResponse(response)
           if (!response.ok) throw new Error(release.message || `检查失败（${response.status}）`)
+          const legacyInstallSpec = `ant@npm:${ANT_BUNDLE_PACKAGE_NAME}@${release.version}`
+          const directSpec = directInstallSpec(release)
+          const validPackageName = release.package_name === ANT_BUNDLE_PACKAGE_NAME
+          const validVersion = typeof release.version === 'string'
+            && (release.version === '' || /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/u.test(release.version))
+          if (release.bundle_name !== 'ant' || !validPackageName || !validVersion
+            || typeof release.install_spec !== 'string' || typeof release.release_notes !== 'string'
+            || (release.version && release.install_spec !== legacyInstallSpec)
+            || (!release.version && release.install_spec !== '')
+            || (release.direct_install_spec !== undefined && release.direct_install_spec !== directSpec)) {
+            throw new Error('ANT 更新信息字段无效。')
+          }
           setBundleRelease(release)
           if (!release.version) {
             setBundleUpdate({ state: 'none', currentVersion: '', message: '管理员尚未发布 ANT 更新。' })
@@ -267,9 +307,17 @@ window.__ModuleLoader__.load({
           if (typeof manager?.listBundles !== 'function') throw new Error('当前 DSH 版本未提供官方 Bundle 管理器。')
           const listed = await manager.listBundles()
           if (!listed.ok) throw new Error(listed.error?.message || '无法读取 DSH 已安装 Bundle。')
-          const installed = listed.value.find((bundle) => bundle.name === release.bundle_name && bundle.installed)
+          const installed = listed.value.find((bundle) => bundle.name === release.package_name && bundle.installed)
           if (!installed || typeof installed.version !== 'string') {
-            throw new Error(`当前 DSH 未找到已安装的 ${release.bundle_name} Bundle。`)
+            const legacy = listed.value.find((bundle) => bundle.name === 'ant' && bundle.installed)
+            if (legacy) {
+              setBundleUpdate({
+                state: 'migration-required', currentVersion: legacy.version || '',
+                message: `当前安装使用旧 alias（${legacy.name}）。请在 DSH 插件管理器卸载旧 ANT，再直接安装 ${release.package_name}@${release.version} 并重启 DSH。若管理器无法完成迁移，请参考 ANT 包内的备用迁移说明。`,
+              })
+              return
+            }
+            throw new Error(`当前 DSH 未找到已安装的 ${release.package_name} Bundle。`)
           }
           const available = newerVersion(release.version, installed.version)
           setBundleUpdate({
@@ -283,7 +331,8 @@ window.__ModuleLoader__.load({
       }
 
       const installBundleUpdate = async (allowScripts = false) => {
-        if (!bundleRelease?.install_spec
+        const installSpec = directInstallSpec(bundleRelease)
+        if (!installSpec
           || (!allowScripts && bundleUpdate.state !== 'available')
           || (allowScripts && approvedBuilds.length === 0)) return
         const manager = remote?.pluginManager
@@ -297,7 +346,7 @@ window.__ModuleLoader__.load({
         setApprovedBuilds([])
         setBundleUpdate((current) => ({ ...current, state: 'installing', message: '正在委托 DSH 官方管理器安装更新…' }))
         try {
-          const result = await manager.installBundle(bundleRelease.install_spec, {
+          const result = await manager.installBundle(installSpec, {
             enabled: true,
             ...(scripts.length ? { approvedBuilds: scripts } : {}),
           })
@@ -323,15 +372,15 @@ window.__ModuleLoader__.load({
             setBundleUpdate({ state: 'failed', currentVersion: bundleUpdate.currentVersion, message: 'DSH 已记录更新，但其他插件配置覆盖了 ANT。请检查 DSH 插件配置后再重启。' })
             return
           }
-          if (outcome.bundle !== bundleRelease.bundle_name) {
+          if (outcome.bundle !== bundleRelease.package_name) {
             setBundleUpdate({ state: 'failed', currentVersion: bundleUpdate.currentVersion, message: 'DSH 返回的安装包名称与 ANT 发布信息不一致。请联系管理员核对发布包。' })
             return
           }
           setBundleUpdate({
             state: 'done', currentVersion: bundleRelease.version,
             message: outcome.application === 'restart-required'
-              ? `DSH 已安装 ${bundleRelease.install_spec}。请完全退出并重新启动 DSH 后生效。`
-              : `DSH 已安装 ${bundleRelease.install_spec}。`,
+              ? `DSH 已安装 ${installSpec}。请完全退出并重新启动 DSH 后生效。`
+              : `DSH 已安装 ${installSpec}。`,
           })
         } catch (error) {
           setBundleUpdate({ state: 'failed', currentVersion: bundleUpdate.currentVersion, message: error instanceof Error ? error.message : 'DSH 未能安装 ANT 更新。' })
@@ -358,7 +407,7 @@ window.__ModuleLoader__.load({
         let serverRevoked = false
         try {
           const response = await fetch('/api/ant-teams/disconnect', { method: 'POST' })
-          const result = await response.json()
+          const result = await readLocalJsonResponse(response)
           serverRevoked = response.ok && result.revoked === true
         } catch {}
         let credentialRemoved = false
@@ -422,7 +471,7 @@ window.__ModuleLoader__.load({
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({ service_url: normalized, email: normalizedEmail }),
           })
-          const result = await response.json()
+          const result = await readLocalJsonResponse(response)
           if (!response.ok) throw new Error(result.message || `请求失败（${response.status}）`)
           setEmail(normalizedEmail)
           setCodeRequested(true)
@@ -458,7 +507,7 @@ window.__ModuleLoader__.load({
               device_id: loadDeviceId(),
             }),
           })
-          const result = await response.json()
+          const result = await readLocalJsonResponse(response)
           if (!response.ok) throw new Error(result.message || `请求失败（${response.status}）`)
           if (typeof result.token !== 'string' || !result.token.startsWith('antm_') || !Array.isArray(result.models)) {
             throw new Error('ANT 返回的连接信息格式无效。')
@@ -490,7 +539,7 @@ window.__ModuleLoader__.load({
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify(body),
         })
-        const result = await response.json()
+        const result = await readLocalJsonResponse(response)
         if (!response.ok) throw new Error(result.message || `飞书操作失败（${response.status}）`)
         return result
       }
@@ -593,7 +642,7 @@ window.__ModuleLoader__.load({
               h('button', { type: 'button', disabled: busy || bundleUpdate.state === 'checking', onClick: () => void checkBundleUpdate(), style: secondaryButtonStyle }, bundleUpdate.state === 'checking' ? '检查中…' : '检查更新')),
             bundleUpdate.message ? h('p', { role: 'status', style: mutedTextStyle }, bundleUpdate.message) : null,
             bundleRelease?.version && bundleUpdate.state === 'available' ? h('div', { style: { display: 'grid', gap: 8 } },
-              h('p', { style: mutedTextStyle }, `发布版本：${bundleRelease.version} · npm：${bundleRelease.install_spec}`),
+              h('p', { style: mutedTextStyle }, `发布版本：${bundleRelease.version} · npm：${directInstallSpec(bundleRelease)}`),
               bundleRelease.release_notes ? h('p', { style: mutedTextStyle }, bundleRelease.release_notes) : null,
               h('button', { type: 'button', disabled: busy, onClick: () => void installBundleUpdate(), style: primaryButtonStyle }, busy ? '安装中…' : '由 DSH 安装并更新')) : null,
             approvedBuilds.length ? h('div', { style: { display: 'grid', gap: 8 } },
@@ -667,7 +716,7 @@ window.__ModuleLoader__.load({
       }
       ctx.slots.inject('plugins.bundle.config', () => ctx.slots.register({
           name: 'plugins.bundle.config',
-          key: 'ant',
+          key: ANT_BUNDLE_PACKAGE_NAME,
           inject: () => ({ remote }),
         }, ({ view, remote: injectedRemote }) => view === 'summary'
           ? h('p', null, 'ANT 团队服务入口。')

package/cordis.patch.yml

@@ -1,3 +1,3 @@
 - insert:
     - id: ant
-      name: ant
+      name: '@ai-wendao/ant'

package/index.js

@@ -14,6 +14,7 @@ const FEISHU_CLAIM_PATH = '/api/ant-teams/feishu/tasks/claim'
 const FEISHU_HEARTBEAT_PATH = '/api/ant-teams/feishu/tasks/heartbeat'
 const FEISHU_COMPLETE_PATH = '/api/ant-teams/feishu/tasks/complete'
 const FEISHU_FINISH_PATH = '/api/ant-teams/feishu/tasks/finish'
+const ANT_NPM_PACKAGE_NAME = '@ai-wendao/ant'
 const MAX_MODEL_RESPONSE_BYTES = 1024 * 1024
 const MODEL_TOKEN_REF = 'ANT_MODEL_API_KEY'
 const SERVICE_RECORD_KEY = 'ant/team-service'
@@ -245,28 +246,38 @@ async function fetchBundleRelease(request, credentials, settings) {
     const session = await updateModelSession(connection.serviceUrl, connection.token, 'heartbeat')
     if (session.status === 401 || session.status === 403) return jsonResponse(401, { message: 'ANT 成员凭证已失效。' })
     if (!session.ok) return jsonResponse(502, { message: '无法激活 ANT 模型会话。' })
+    const headers = { authorization: `Bearer ${connection.token}`, accept: 'application/json' }
+    if (request.headers.get('x-ant-bundle-capabilities') === 'direct-package-install') {
+      headers['x-ant-bundle-capabilities'] = 'direct-package-install'
+    }
     const upstream = await fetch(new URL('/api/me/bundle-release', connection.serviceUrl), {
-      headers: { authorization: `Bearer ${connection.token}`, accept: 'application/json' },
+      headers,
       redirect: 'manual',
       signal: AbortSignal.timeout(10_000),
     })
     const text = await readLimitedBody(upstream)
     if (text === null) return jsonResponse(502, { message: 'ANT 更新信息响应过大。' })
     if (upstream.status === 401 || upstream.status === 403) return jsonResponse(401, { message: 'ANT 成员凭证已失效。' })
+    if (upstream.status === 426) {
+      return jsonResponse(426, { message: '当前 ANT 插件版本不能安全自动安装 scoped Bundle。请通过 DSH 官方插件管理器完成一次包名迁移。' })
+    }
     if (!upstream.ok) return jsonResponse(502, { message: 'ANT 暂时无法提供插件更新信息。' })
     let release
     try { release = JSON.parse(text) } catch { return jsonResponse(502, { message: 'ANT 更新信息格式无效。' }) }
-    const validPackageName = typeof release?.package_name === 'string'
-      && (release.package_name === 'ant' || /^@[a-z0-9][a-z0-9._-]*\/ant$/u.test(release.package_name))
+    const validPackageName = release?.package_name === ANT_NPM_PACKAGE_NAME
     const validVersion = typeof release?.version === 'string'
       && (release.version === '' || /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/u.test(release.version))
     const installSpec = release?.package_name === 'ant'
       ? `ant@${release?.version}`
       : `ant@npm:${release?.package_name}@${release?.version}`
+    const directInstallSpec = release?.package_name && release?.version
+      ? `${release.package_name}@${release.version}`
+      : ''
     if (release?.bundle_name !== 'ant' || !validPackageName || !validVersion
       || typeof release?.install_spec !== 'string' || typeof release?.release_notes !== 'string'
       || (release.version && release.install_spec !== installSpec)
-      || (!release.version && release.install_spec !== '')) {
+      || (!release.version && release.install_spec !== '')
+      || (release.direct_install_spec !== undefined && release.direct_install_spec !== directInstallSpec)) {
       return jsonResponse(502, { message: 'ANT 更新信息字段无效。' })
     }
     return jsonResponse(200, release)

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@ai-wendao/ant",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "AI-native team service for DeepSeek Harness",
   "type": "module",
   "scripts": {
-    "test": "node --test client.test.js index.test.js"
+    "test": "node --test client.test.js index.test.js tools/migrate-legacy.test.mjs"
+  },
+  "bin": {
+    "ant-migrate": "tools/migrate-legacy.mjs"
   },
   "main": "index.js",
   "exports": {
@@ -13,7 +16,7 @@
     "./client": "./client.js",
     "./locale/*.json": "./locale/*.json"
   },
-  "files": ["index.js", "client.js", "cordis.patch.yml", "locale/*.json"],
+  "files": ["index.js", "client.js", "cordis.patch.yml", "locale/*.json", "tools/migrate-legacy.mjs", "MIGRATION.md", "README.md"],
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"

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
+})