dsh-ant 0.0.0-stage → 0.5.12

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.13`），然后点击 **安装**。
+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.13 -- ant-migrate inspect
+npm exec --yes --package @ai-wendao/ant@0.3.13 -- ant-migrate migrate
+```
+
+退出 DSH 后执行变更：
+
+```sh
+npm exec --yes --package @ai-wendao/ant@0.3.13 -- 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.13 -- ant-migrate rollback --backup "<备份目录>"
+npm exec --yes --package @ai-wendao/ant@0.3.13 -- ant-migrate rollback --backup "<备份目录>" --apply
+```
+
+回退只在 scoped 包已安装、旧 alias 尚未移除的中间态工作；它会卸载 scoped 包并保留旧 alias。已完成迁移的 profile 不接受该回退，避免自动恢复已知有加载问题的 alias。若安装包时 npm registry 不可用，保持 DSH 关闭，稍后重新运行 `migrate --apply`。

package/README.md

@@ -1,3 +1,69 @@
-# 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 (AI-native Teams) connects a DeepSeek Harness Desktop profile to its team's membership and approved models.
+
+## 安装包与更新通道
+
+ANT 同一份源码可发布为 `@ai-wendao/ant` 和 `dsh-ant`，DSH 添加插件时直接输入其中一个包名。两者连接同一 ANT 服务并使用相同业务协议；同一 DSH profile 只安装并启用其中一份，不同时启用两个包，也不使用 npm alias。选择新包不代表自动迁移旧包；需要跨包切换时先另行验证凭证和本机配置的保留流程。
+
+每个包只查询和安装自己的已审核更新。缺省更新指引 `/ant-update` 对应原包；`dsh-ant` 使用 `/ant-update?package_name=dsh-ant`，该指引分发以 `.tgz` 结尾、不带查询参数的 `/api/ant-bundles/dsh-ant/<版本>/package.tgz` 安装地址。服务端须先升级到支持双包的版本；旧服务端返回原包信息时，新包拒绝安装，不跨包回退。历史 `ant` alias 的迁移工具仍只处理 `@ai-wendao/ant`，不用于切换包名。
+
+## DSH 客户端兼容性
+
+当前 Bundle 声明的 DSH 最低版本是 `0.2.1-rc.3`。DSH 会在安装和启动 profile 时检查此范围；低于最低版本时，DSH 插件管理器会报告并跳过 ANT Bundle。高于最低版本的 DSH 不会被版本上限拦截；ANT 只把 `0.2.1-rc.3` 标为已记录的验收基线，其他版本显示为“未验收”。ANT 的“关于”页会检查当前 DSH 与候选 ANT 制品的兼容状态；低于最低版本、版本未知或候选制品未提供范围时，不提供自动更新操作。
+
+`0.2.1-rc.3` 是仓库当前有记录的 DSH 基线。更高的稳定版和预发布版都可以通过最低版本门禁，但在完成对应 Desktop/DSH-IM 验证前仍标为“未验收”。ANT 协作会话还会在实际调用前检查 Session 事件接口；缺少该接口时会提示检查 DSH 兼容状态，不发送协作 prompt。
+
+## 团队模型默认值
+
+团队管理员在 ANT 控制台设置团队默认模型，并授权成员可用模型。成员第一次在 ANT 插件中同步模型时，团队默认会写入 DSH 的全局默认模型；成员之后可在“团队模型”页选另一项已获准模型。成员也可按 provider 选择同步到本机 DSH 的模型路由；首次升级保留已有路由，关闭某项并刷新后会从本机 Profile 移除，保存了该路由的历史会话可能暂时无法调用，重新启用并刷新可恢复。普通同步保留成员默认选择；若模型被撤销，插件会回到仍获准的团队默认。该默认写入 DSH profile，因此也影响同一 profile 新建的普通 DSH 会话。ANT 对话和任务会额外校验当前用户的获准模型；Codex 与 Claude Code 使用各自执行器的默认模型。
+
+图片输入能力由管理员按团队模型配置；成员默认继承。成员可在“团队模型”页关闭当前 DSH Profile 中单个模型的图片输入，并通过刷新应用；这只限制本机同步，不修改团队设置或授权。管理员未开放图片输入时，成员不能自行打开。
+
+每个 OpenAI 兼容模型可配置 Chat Completions 或 Responses API。旧模型记录在升级后按 Chat Completions 解释；ANT 服务端继续使用原配置的 `/chat/completions` URL，并从相同 API 根路径派生 `/responses` 上游路径。
+
+## 企业品牌
+
+团队管理员可在 ANT 管理台的“企业品牌”页设置 DSH 侧栏 Logo、品牌名称、品牌徽标和新会话标题。Logo 接受 PNG、JPEG 或 WebP，最大 350 KB；图片和文字保存在当前团队的 ANT 服务端。成员 Bundle 启动时立即同步，DSH 保持打开时每 5 分钟通过 ETag 检查版本；网络暂时不可用时继续使用本机最近一次成功配置，不阻止 DSH 启动。
+
+Logo 与侧栏品牌使用 DSH 正式 UI 插槽。新会话标题目前没有官方文本插槽，Bundle 只在页面中精确匹配 DSH 当前标题原文后替换；上游更改该文案时可能需要更新 ANT Bundle。此项不影响会话和工具功能，也不控制 DSH 原生欢迎/登录窗口、菜单或应用图标。
+
+飞书和企业微信的机器人连接、消息收发由 DSH-IM 负责；ANT Bundle 不保存机器人密钥或直连 IM 平台。ANT 继续负责团队成员身份和模型授权，并可在成员显式开启时接管一个专用飞书机器人的文本收件，按成员授权范围处理协作请求。
+
+## 协作机器人与任务卡
+
+飞书机器人连接和消息收发由 DSH-IM 负责；ANT Bundle 不保存机器人密钥，也不直连 IM 平台。成员在 ANT 插件的“协作”页选择机器人、启用本机协作，并设置私聊和各群的普通聊天开关。群第一次 @ 机器人后会出现在群列表。群聊天开关只控制普通聊天；任务卡还要单独指定私聊或群、请求人范围和有效期。
+
+开放任务时，成员用自然语言描述要完成什么、可以使用哪些资料、怎样处理和返回结果。输入停顿后，ANT 会调用当前获准的 DSH 团队模型，在描述旁检查并显示必需信息缺项、可选限定建议、自然语言请求示例和运行方式；草稿不会自动开放，机器人主人检查后明确开放。机器人主人指在本人 DSH 中连接并管理该 DSH-IM 机器人的 ANT 成员，不代表群管理员身份；群内谁能请求仍由规则中的群范围和请求人范围决定。任务由模型在当前请求人和会话可申请的能力中按语义匹配；意图不明确或信息不足时先追问，不要求固定触发前缀。模型匹配不是安全边界，服务端每次仍核验任务状态、机器人、会话、请求人、有效期和参数。
+
+PR 来源和仓库由机器人主人写在任务描述中，AI 提取候选范围供主人复核；B 的原始描述仍是任务行为的主要依据。若机器人尚未绑定 Gitea 主机，主人确认并开放首个 PR 任务卡时会明确看到绑定来源，服务端在保存任务卡的事务中完成首次绑定；此后每张 PR 任务卡和每次请求都必须匹配该主机。无需填写固定地址表单，也不单独设置机器人的可信地址。请求人每次提供 PR 链接或编号，也可以明确指定 Head SHA；没有指定时，按任务开始处理时读取到的最新 Head。ANT 会校验来源、仓库、PR、base/head，并在执行后再次核对快照。
+
+DSH Agent 负责自然语言理解和任务执行；B 原始描述决定任务行为，AI 整理摘要只辅助理解。A 本次请求、已核验参数和 Host 实际提供的资源上下文作为本次任务输入。ANT Server 逐次核验身份、会话、范围、有效期和参数，ANT Host 只代取 ANT 自己管理的资源。当前委托任务会话不开放 DSH connector/tool，不能据 DSH Profile 拥有这些连接器推断任务 Agent 已可使用它们；授权路径列入[待决策事项](../../docs/decisions/2026-10-22-delegation-ux-pending.md)。
+
+群任务和群聊天设置只在 ANT 协作页配置。当前版本不设群管理员身份绑定，也不支持在群里开放任务、确认授权或开关群聊。群成员可以普通聊天，或按已开放任务的群范围、请求人范围和有效期用自然语言发起任务；未开放的任务不会因为群成员的消息而执行。关闭群普通聊天不会撤销已开放任务。
+
+当前所有协作任务都由 DSH 获准团队模型处理。`ant-delegated-task` 会话的 DSH 工具 allowlist 为空，只能处理对话内容和 ANT Host 明确提供的资源；Codex 与 Claude Code 即使已在 DSH 注册，也暂不可用于协作任务。DSH 的外部 provider 不继承 ANT 的任务 preset，ANT 也没有接口核验其逐任务文件、Git 和网络权限，因此服务端会拒绝外部执行器任务卡，Bundle 运行时也会失败关闭。执行策略版本头只用于拒绝旧 Bundle 的 legacy PR 授权路径，防止服务端先升级后旧 Bundle 仍可启动外部 provider。
+
+ANT Host 只代取 ANT 自己管理的资源。当前 Host Connector 使用成员保存在 DSH 凭据服务中的 Gitea 只读令牌读取已授权 PR；令牌不会同步到 ANT 服务端，也不会提供给任务模型。任务来源仍由 B 的自然语言描述并经主人复核，但服务端要求它与该机器人的 Gitea 连接器来源一致；Host 不会把全局令牌发送给任务描述里任意填写的主机。当前每台机器人只绑定一个 Gitea 来源；未来若需支持多来源，须按来源隔离令牌，见[待决策事项](../../docs/decisions/2026-10-22-delegation-ux-pending.md)。Host 核验来源、仓库、PR、base/head 和 diff 后，将只读资源上下文交给 DSH。PR 数据是不可信内容，不能改变 B 原始任务描述。任务可以审查、总结或解释 PR，由 B 描述决定。当前只提供 PR diff 和快照元信息，不提供仓库工作树或完整文件访问；diff 含 Git LFS 指针时，任务模型看不到对应文件内容。ANT 只核验自己的连接器资源，不管理 DSH Profile 中的 workspace、skill、connector 或本机凭据。DSH 自有资源的任务级授权方式仍待决策，见[待决策事项](../../docs/decisions/2026-10-22-delegation-ux-pending.md)。
+
+本机与任务页显示执行器状态、最近任务和运行状态，并允许调整本机任务并发。当前不创建 PR 仓库快照；旧的仓库缓存上限设置暂不可修改，仅在停用或到期能力清理旧缓存时保留原值。停止 ANT 授权后，若需恢复 DSH-IM 原有收件行为，请在 DSH-IM 中切回普通模式。
+
+## 企业精选技能
+
+团队管理员可在 ANT 管理台从 GitHub 目录、ZIP、TAR、TAR.GZ／TGZ 或单份 `SKILL.md` 导入技能，核对来源、文件和依赖后发布，并为企业技能和插件指定主要用途类别。成员可从 DSH 主侧栏“ANT”或 ANT Bundle 配置页直接进入团队设置；DSH“设置”中的 ANT 项提供打开 ANT 主页面的快捷入口。主侧栏“企业扩展”继续进入统一目录，可组合筛选办公文档、编程开发、设计与多媒体、数据分析、协作沟通、写作与营销、自动化与效率、运维与安全或其他类别，同时按来源范围、技能/插件类型和安装状态筛选或搜索。类别只用于发现内容；“本企业”“全市场精选”和“DSH 官方”是独立来源范围。ANT Host 将固定版本的完整文件集放进 DSH 的用户技能目录，并重新核对本机文件；启用本地技能的 DSH 会话随后由原生技能提供者发现和使用。ANT 不用 Host 全局技能列表判断会话是否已发现技能。
+
+安装不会自动运行技能脚本或安装 Python、Node 等系统依赖。ANT 只更新或卸载自己管理且本机内容未被修改的技能目录；发现同名个人技能或本机改动时会停止覆盖。
+
+## 企业精选插件
+
+管理员从 npm 官方源的 DSH Bundle 精确版本创建草稿，填写源码、许可证、依赖和安装脚本的审核记录后发布。成员在“企业扩展”总览或“插件”分类查看审核信息和本机状态；发布后可让 DSH 官方插件管理器从 npm 安装目录中的精确版本，无须先由管理员锁定 ANT tarball。ANT 也保留可选的固定 tarball 安装路径。直接安装时，DSH 按 registry/fallback 配置解析依赖，设备间版本可能不同；ANT 不会批准依赖构建脚本，如安装因此中断需按 DSH 提示转到原生插件管理页处理。ANT 目录不控制插件之后的自更新；部分插件可提供自己的更新器，DSH 原生插件管理页也可更换版本。安全撤回版本会停止通过 ANT 目录发起的新安装，但不会自动删除本机副本。范围与限制见[上线边界](../../docs/decisions/2026-10-15-plugin-center-rollout.md)。
+
+ANT 自身更新使用单独的已审核安装包。管理员将与 npm 发布一致的 `.tgz` 上传到 ANT 服务端并登记版本；新版 ANT 页面可点击“更新”，DSH 原位替换同名 Bundle 后提示重启。旧版 `@ai-wendao/ant` 用户可打开团队服务的 `/ant-update` 指引，在 DSH“添加插件”中粘贴该安装包地址完成一次性原位更新，无需先卸载或使用终端。此入口只分发 ANT 自身，不启用扩展中心其他插件的一键安装。
+
+企业精选是团队推荐目录，不是强制白名单；ANT 不能阻止成员从 DSH 原生插件管理页或插件自身更新器安装其他版本。DSH `0.2.0-rc.2` 本身不自动更新已安装 Bundle；插件可以提供自己的更新操作。ANT 目录只约束它发起的安装，不对本机安装后的版本持续强制管理。上线边界见[待决策记录](../../docs/decisions/2026-10-15-plugin-center-rollout.md)。
+
+## 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.