@ai-wendao/ant 0.0.0-stage → 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

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# ANT for DeepSeek Harness
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.