Skip to content

A team of long-lived bots for DeepSeek Harness, with main bots, bot-to-bot messages and group chats.

Add the design for the Windows onboarding

AdamPlatin12311263abb10ce
diff --git a/docs/plans/2026-10-26-windows-onboarding.md b/docs/plans/2026-10-26-windows-onboarding.md
new file mode 100644
index 00000000..d167be4a
--- /dev/null
+++ b/docs/plans/2026-10-26-windows-onboarding.md
@@ -0,0 +1,344 @@
+# Windows 上手流程:从下载到第一条有用的回复
+
+- 日期:2026-10-26
+- 相关:#523、#559、#384、#500、#551(PR #567)、#529、#561、#515、#423、#499、#428、#265;Discussions #530、#150
+- 一起改:[桌面应用](2026-10-16-desktop-app.md)(结构、窗口、模型、首次启动和导入、改位置、安装和更新、暂时不做、已知限制)、[Bot 运行配置](2026-10-10-bot-runtime.md)(新 Bot 的模型来源和那条已知限制)、[DSH 让步总账](2026-10-13-dsh-concessions.md)(预览版说明关不掉、设置卡借用 `settings.models.sign-in` 的操作、借 `settings.onboarding` 步骤打开「模型」)、[UI 标准](../design/ui-standard.md) 第 11 节(术语「提供商」)
+- 代码:`app/src/main.mjs`、`first-run.mjs`、`import.mjs`、`updates.mjs`、`preload.cjs`、`host.mjs`、`host-process.mjs`、`downloads.mjs`、`move-data.mjs`、新的 `app/src/start/`;`app/electron-builder.yml`、`app/build/installer.nsh`;`ds-bot/index.js`;`ds-bot/src/client/model-menu.js`、`team-actions.js`、`sidebar.js`、`settings.js`、`diagnostics.js`、`i18n.js`、`ds-bot/src/client/index.js`;`ds-bot/src/host/models.js`、`roster.js`、`turns.js`、`providers.js`、`channel.js`、`parts.js`;`.github/workflows/release.yml`、`.github/ISSUE_TEMPLATE/`;`README.md`、`README.zh.md`
+
+## 为什么
+
+### 谁在用
+
+Windows 是桌面应用的主要平台:0.2.0 到 0.2.2 三个版本的安装包下载里,Windows 约 3850 次,macOS 约 1900 次,Linux 约 250 次(GitHub 下载计数,含自动更新)。这些 Windows 用户几乎不提 Issue:259 个 Issue 里能确认来自 Windows 桌面应用的只有 3 个左右。另一边,有 10 位不同的用户报告过「第一条消息就失败 / 没有回复」。大多数人是在半路悄悄放弃的。
+
+典型用户:中文界面,可能不是开发者,可能在中国大陆(GitHub 慢或打不开),可能还没有 DeepSeek 账号或 API Key,可能从没用过 DeepSeek Harness(DSH)。
+
+### 今天的路有多长
+
+2026-10-26 在 `dev` 上用全新用户的身份实测:一次性的家目录、数据位置和壳数据,环境里没有任何 key,界面中文。实测用的是未打包的 Electron 和 `DS_BOT_HOME`,所以下表的下载、安装、首次启动对话框、导入、启动失败和卸载几行来自代码、CI 和用户报告,其余几行是实测。
+
+| 步骤 | 用户看到的 | 问题 |
+|---|---|---|
+| 下载 | README 先是英文;Releases 页是英文更新日志加 11 个文件,按字母排,`.exe` 排第五,紧挨着 `.exe.blockmap` | 不知道下哪个;约 212 MB 只能从 GitHub 下,没有国内镜像 |
+| 打开安装包 | 浏览器提示「不常下载」;「Windows 已保护你的电脑」,发布者「未知发布者」 | 没签名。开着「智能应用控制」的 Windows 11 直接拦下,没有「仍要运行」 |
+| 安装 | NSIS 向导:选目录(点「安装」)→ 进度 → 完成(点「完成」) | 多两次点击,NSIS 默认图 |
+| 首次启动 | 还没有窗口,先弹系统对话框「欢迎使用 DeepSeek Bot」,里面只有两个路径(`数据:C:\Users\<用户名>\.ds-bot`、`总工作区:C:\Users\<用户名>\DeepSeek Bot`) | 不说这是什么、下一步做什么。「更改位置…」连开两个从家目录起步的选择框,直接点两次「选择文件夹」,两个位置都是家目录,会被「数据文件夹不能放在总工作区里面。」拒绝,提示框只有一个英文「OK」。对话框没有父窗口,被挡住时再双击图标也没反应 |
+| 已有 DSH 团队时 | 「要复制到 DeepSeek Bot 吗?」→ 可能「正在使用这个团队」反复重试(PID 被系统重用的旧锁)→ 可能「更新版本写的对话」,默认按钮是「退出」,而更新器这时还没启动 → 可能「用哪一份模型设置?」,`DSH Desktop`、`DSH Web` 以外的 profile 直接显示 `headless` 之类的原始名字,也看不出每份里有什么 | 只问一次,跳过、失败或「不带团队开始」后再也找不回来。复制在「正在启动 DeepSeek Bot…」后面进行,只有任务栏图标上不确定的进度 |
+| 等待 | 一页白底黑字「正在启动 DeepSeek Bot…」,实测冷启动 21 秒(第二次 13 秒;CI 上约 2.5 秒) | 没有品牌、进度和解释;窗口拖不动。启动失败时还要再等 GitHub 最多 15 秒,然后弹出标题为英文「Error」的框,里面是 8 KB 英文 stderr,没有日志文件 |
+| 进入窗口 | DSH 的「预览版说明」(讲 DeepSeek Harness 0.2、开发者、插件 API)→ DSH 的「开始使用」(登录 / 添加 API Key)→ DSH 的「添加一个 API Key 开始使用」;下面 Chief 的卡片又问一遍「我还没有可用的模型。你想怎么配置?」 | 四个面,两个重复。没有一个告诉用户 key 去哪里拿、要先充值、填的 key 对不对 |
+| 先打字 | 红字「本轮运行失败」加英文原文 `llm-deepseek: no API key for provider route "deepseek-official"; … export DEEPSEEK_API_KEY in the launching environment`,代码 `MISSING_CREDENTIAL` | 中文界面里的开发者报错,没有按钮;这条消息还会删掉 Chief 留着的开场白 |
+| 填了 key 之后 | Chief 再问一次「先给我选一个模型吧」,选完才打招呼 | key 从不校验:填错或余额为零,要到第一轮才报「API 密钥无效」或「额度已用尽」,只有文字,没有按钮 |
+| 第一个小时 | 默认沙盒下 Bot 跑的每条命令都可能返回 `exit code 3221225794`(#523);Host 不读 Windows 系统代理,Clash、v2rayN 只开系统代理时请求不走代理(#529 的「连不上 GitHub」很可能是这个原因,推断);冷启动可能一个 Bot 都不显示(#559);导入后第一条消息可能 84 秒没有任何显示(#384) | 都没有说明和下一步 |
+| 卸载 | 什么都不问,key、登录、对话全部留下;重装后跳过首次启动 | 想「重来一次」的人做不到 |
+
+另外,「下载」文件夹解析不到时(被删掉,或者重定向到一个当前不可用的位置),`app.getPath('downloads')`(`main.mjs` 建窗口时调用)会抛错:窗口一直不显示,等最多 15 秒后弹出「DeepSeek Bot 没能启动」和 Electron 的英文报错,然后退出。已在 Electron 44 上复现这个抛错。
+
+手里已经有 key、也没有 DSH 团队时,最快也要:两次 SmartScreen 点击,安装向导点两次,一个系统对话框,等 13 到 21 秒,再点「继续 → 添加 API Key → 粘贴 → 保存并继续 → 选模型」,一共 10 步,第一条回复才出来;有 DSH 团队时最多 13 步。没有 key 时还得自己离开应用去弄一个。
+
+### 根因
+
+1. **首次启动按实现来提问。** 数据位置、总工作区、DSH 的 profile 都是实现概念,却在还没有窗口的系统对话框里先问用户。
+2. **接模型有三个入口,彼此重复,又都不完整。** DSH 网页版自己的两步引导,加上 Chief 的卡片。哪个都不说怎么拿 key、要付费、key 能不能用。
+3. **失败不给下一步。** 凭据错误显示原文,启动失败弹英文框,导入遇到新版对话是死路,导入只给一次机会。
+4. **分发只靠 GitHub,而且没签名。** 下载和自动更新都走 GitHub,SmartScreen 和智能应用控制把人挡在门外,发布页不告诉人下哪个文件。
+5. **第一个小时的坑没人接。** Windows 特有的沙盒启动失败、系统代理、「下载」文件夹,以及各平台都有的冷启动不显示 Bot(#559,报在 Windows 上)和导入后漫长的换段(#384)。
+
+### 取舍
+
+- **每个阶段只有一个引导面,显示什么由状态决定,不存「已完成」标记。** 引擎起来之前,引导面是应用自己画的启动页;引擎起来以后,是 Main Bot 聊天里的设置卡。跳过的步骤哪里都不记,条件还在,它下次就自己回来。
+- **模型在聊天卡里接,不在应用里另做欢迎向导。** 设置卡是插件的代码,DSH Desktop 和 DSH Web 里的用户也一起受益;应用里再做一套向导,就要维护两套。启动页只负责说清「这是什么、下一步是什么」,好让等待不是空等。
+- **先补悄悄流失的地方。** 下载页、信任提示、一键安装最便宜,影响面最大。签名和国内镜像要等外部审批和账号,所以最先开始办。
+- **不改 DSH。** 只用有文档的开关和插槽。DSH 的「预览版说明」没有文档开关,就向 DSH 提需求,期间在启动页上先提醒一句;不伪装 `dshDesktop`。
+
+## 已定的行为
+
+下面写的是新流程。界面文字的源语言照旧:插件是英文加 `i18n.js` 里的中文,应用主进程用自己的中英文表;这里只列中文。文案里的 `{名字}` 是 Main Bot 的名字。标了「待定」的几处,按文末「待定」里的建议写,拍板后改成定下的那一种。
+
+### 1. 下载
+
+- `README.md` 和 `README.zh.md` 开头都是同一块中英双语的下载区(GitHub 默认显示英文 README):Windows 10/11(64 位)、约 212 MB,「国内镜像下载(推荐)」和「GitHub」两个直接下载链接。镜像没验证通过之前只放 GitHub 链接,不放死链。
+- 下载区紧接着写清:双击就会安装,装好自动打开;不用管理员权限,不用另装 Node 或 DSH;需要一个 DeepSeek 账号(可以当场用手机号注册)或 DeepSeek API Key;DeepSeek 按用量收费,一轮对话大约多少钱(实测三次开场白得出,附 DeepSeek 价格页链接);DS Bot 是社区开源项目,不是 DeepSeek 官方产品。
+- 签名之前,下载区带一段信任说明(文字加自己画的示意图,不贴 Windows 或其他产品的截图):
+ - Edge 提示「不常下载」:「···」→「保留」→「仍然保留」。
+ - 「Windows 已保护你的电脑」:「更多信息」→「仍要运行」。
+ - 「智能应用控制已阻止…」且没有「仍要运行」:未签名的安装包没有安全的绕过办法,请改用 DSH Desktop 加 DS Bot 插件。不要关掉智能应用控制。
+ - 杀毒软件拦截:先用 `certutil -hashfile <文件> SHA256` 和 `SHA256SUMS.txt` 核对,再选「信任」。
+ - 安装时提示卸载旧版失败:先关掉 DeepSeek Bot;杀毒软件拦了安装包时,按上面的方法核对后选「信任」,再运行一次安装包。
+- 每个 Release 的说明开头是 CI 生成的「下载 / Download」表:Windows 排第一(国内镜像、GitHub、大小、「双击安装」),然后是 macOS(Apple 芯片 / Intel)和 Linux(AppImage / deb);表下注明 `.blockmap`、`latest*.yml`、`ds-bot-*.tgz` 和源代码是给自动更新和插件用的,不用下载。之后才是更新日志。
+- Release 附上不带版本号的文件(如 `DeepSeek-Bot-win-x64.exe`)和 `SHA256SUMS.txt`。README 用 `releases/latest/download/` 的固定链接,不经过文件列表。README 里插件安装那一行也不写具体版本号(今天两份 README 都还写着 `ds-bot-0.2.1.tgz`)。
+- 发版顺序是「打包(→ 签名)→ 上传到 GitHub 和镜像 → 写下载表 → npm 发布 → 最后才标为 Latest」,不会再出现 Release 已经是 Latest、安装包几分钟后才到的情况。今天的工作流由 `release: published` 触发,没有公开的 Release 就没有标签,而工作流要靠标签检出代码、并检查它在 `main` 上;npm 的 Trusted Publishing 也绑定在 `release.yml` 上。所以起点是维护者发布时不勾「设为最新」,最后一步由工作流 `gh release edit --latest`;npm 发布留在 `release.yml`。
+- 新增「安装问题」Issue 表单:不要求诊断信息(应用都没跑起来),只问 Windows 版本、Windows 语言、卡在哪一步、对话框的文字或手机拍的照片。
+
+### 2. 安装(一键安装待定)
+
+- 双击后只有一个小窗口「正在安装 DeepSeek Bot,请稍候…」和进度条,约 30 秒,没有页面要点。只装给当前用户,装到 `%LOCALAPPDATA%\Programs\DeepSeek Bot`,不要管理员权限。建桌面和开始菜单快捷方式「DeepSeek Bot」,装完自动打开应用。
+- 要换程序位置的用户用 `/D=`(README.md 和 README.zh.md 的进阶说明);数据和总工作区本来就可以放到别的盘。
+- 安装语言 `[en_US, zh_CN]`:中文 Windows 用中文,其他语言用英文(今天其他语言会落到简体中文)。
+- 在旧版向导装到自定义目录的基础上一键升级,保留原目录(CI 验证)。
+- 签名后(路线待定),发布者显示签名主体;设置 `publisherName`,让 `electron-updater` 校验以后更新包的签名。
+- electron-builder 自带的几条 NSIS 报错(卸载旧版失败、解压失败)没有中文,照样显示英文。不在 `installer.nsh` 里重新定义它们:electron-builder 默认把 NSIS 警告当错误,重复定义会让构建失败。中文翻译提给 electron-builder。
+
+### 3. 首次启动:启动页
+
+- 窗口先出来。进程启动约 1 秒内,窗口就显示应用自己的本地页(`app/src/start/`):和现在一样无边框,40 px 的标题带可以拖动,系统按钮在右上角,Windows 11 上用 Mica。启动页和引擎的页面共用这个窗口。
+- 标题「正在准备你的 Bot 团队…」,下面三个真实阶段,各带进度勾:「准备数据文件夹」→「启动本机引擎」→「打开团队」。超过 5 秒显示已用秒数。
+- **只在第一次启动时**,等待期间显示一段说明:
+ - 「DeepSeek Bot 是一支替你干活的 Bot 团队:你告诉主 Bot 要做什么,它安排其他 Bot 一起完成。」
+ - 没有要导入的团队时:「下一步:接上一个模型。推荐用 DeepSeek 账号登录(没有账号可以用手机号注册),也可以粘贴 DeepSeek API Key。DeepSeek 按用量收费。」
+ - 「聊天和设置保存在这台电脑上(对话内容会发给你选的模型服务)· 社区开源项目,不是 DeepSeek 官方产品」
+ - 小字写明位置:「数据保存在 `C:\Users\<用户名>\.ds-bot`,Bot 默认在 `C:\Users\<用户名>\DeepSeek Bot` 里工作。都可以在 设置 → 通用 → 位置 里改。」
+ - 最后一个阶段,DSH 会挂出「预览版说明」时(会话准备好、主视图里没有非空会话):「接下来会先显示 DeepSeek Harness 的「预览版说明」。DeepSeek Bot 建在 DeepSeek Harness 上,点「继续」就行。」
+ - 超过 10 秒:「第一次启动会慢一些,Windows 可能在检查刚装好的文件。」超过 45 秒:「比平时慢,可能是杀毒软件在检查新文件,请再等一会儿。」加「打开日志文件夹」。
+- **一般情况下什么都不问**,用默认位置。只在状态需要时出现一张卡片,每张都说明以后在哪里改:
+ - 找到以前的 DS Bot 数据但没有保存的位置(重装过):「找到了之前的 DeepSeek Bot 数据:6 个 Bot、2 个群聊(`C:\Users\<用户名>\.ds-bot`)。旧数据会保留在原处。」〔接着用(推荐)〕〔用新的空白团队开始…〕
+ - 数据所在的盘不到 5 GB:「C 盘只剩 1.2 GB。聊天和 Bot 的文件会越来越多,最好放到别的盘。」〔选择其他位置…〕〔仍然放在 C 盘〕
+ - 位置不能用(没有写入权限、在 OneDrive 里、整个磁盘、别人的非空文件夹):一句话说明原因,加〔选择其他位置…〕。OneDrive 里的总工作区只提醒,不拒绝。
+ - 保存过的数据文件夹找不到了:「找不到数据文件夹 `D:\DeepSeek Bot\data`。可能是移动硬盘没插上,或者文件夹被移走、删除了。旧数据不会被改动。」〔重试〕〔重新找到它…〕〔用新的空白团队开始…〕
+- 选择框挂在窗口上,从上一级文件夹开始。选了磁盘根目录或别人的非空文件夹时,自动在里面加一层子文件夹,并显示结果:「会放在 `D:\DeepSeek Bot\data`」〔就用这里〕〔重新选〕。两个位置分开改。DSH 数据的规则只在那个文件夹真的存在时才检查。
+- 首次启动的位置检查和「换数据位置」用同一套规则(不能是整个磁盘、不能是别人的非空文件夹),外加一次试写。
+- `locations.json` 只在引擎第一次成功启动(`ready`)、导入问题也答完之后才写。同时写一份 UTF-16LE 的 `locations.ini` 给卸载程序读;应用自己新建的数据文件夹里放一个不含任何机密的 `.deepseek-bot` 标记。「首次启动没走完就退出时什么都不记」的规则不变。
+- 然后加载引擎的页面:DSH 的「预览版说明」→「继续」。DSH 自己的「开始使用」和「添加一个 API Key」不再自动出现:应用在自己的 profile 补丁(和 `search-patch.mjs` 一样经 `runProfile` 的 `patchFiles` 传入)里设 `ui-settings-models` 的 `credentialOnboarding: false`,这是 DSH 有文档的配置。补丁会替换这一行的整个 `config`,所以每次升级锁定的 DSH 都对照新版本重写这一行。应用的补丁里只有这一行。
+- **启动失败**时,启动页当场变成恢复页(不再等 GitHub、不再隐藏窗口、不再弹英文「Error」框):标题「DeepSeek Bot 没能启动」,一句对应的原因(没有写入权限 / 磁盘空间不够 / 程序文件不完整,可能被杀毒软件拦掉了一部分 / 本机引擎启动到一半停下了 / 出了点意外),每种都给〔重试〕〔换个数据文件夹…〕〔用新的空白团队开始…〕〔打开日志文件夹〕〔复制详细信息〕,再加一个「详细信息」折叠区(日志最后 200 行,已脱敏)。
+- 启动超过 180 秒:「启动比平常慢很多。可以再等一会儿,或者重试。」〔继续等待〕〔重试〕〔打开日志文件夹〕,引擎同时继续启动。
+- 后台更新器发现了新版本时,恢复页上显示「DeepSeek Bot {版本} 已经发布,可能修好了这个问题。」〔下载并安装〕,带下载百分比和「下载太慢?手动下载」(打开镜像页)。
+- 引擎起来了但 DS Bot 界面 20 秒内没报告就绪(ds-bot 在界面挂载完成后调用 `dsBotApp.ready()`):回到启动页,显示「团队界面没有加载出来。」〔重新载入〕〔打开日志文件夹〕〔复制详细信息〕。
+- 首次启动期间再双击图标:恢复并聚焦已有窗口,失败页上也一样。
+- 建窗口不再依赖「下载」文件夹:每次下载时才取它的位置,取不到就用家目录,再不行就不给默认位置,让用户自己选。
+- 日志:`%APPDATA%\DeepSeek Bot\logs\main.log`,2 MB × 3 份轮换,收主进程和引擎的输出;写之前去掉 `token=…`、`sk-…`,把用户文件夹的完整路径(如 `C:\Users\<用户名>`)换成 `%USERPROFILE%`。
+- 启动页是纯 DOM,CSP `default-src 'self'`;颜色取 [UI 标准](../design/ui-standard.md) 2.1 节 DeepSeek 主题的值,字号用标准里的 13 / 14 / 15 px。它只拿到 `dsBotStart`(`onState`、`act`),只在页面地址正好是启动页文件时才暴露。引擎页面上的 `dsBotApp` 只新增 `ready()`(上面的 20 秒检查)和 `focus()`(第 5 节登录后回到前台),其余不变。主进程对两者分别做精确的来源检查。
+- `DS_BOT_HOME` 的一次性运行照旧:不问、不导入,但也显示启动页和失败页。
+
+### 4. 已有 DSH 团队:导入卡
+
+条件:`~/.dsh`(或 `DSH_HOME`)里有 Bot 团队,而数据文件夹里还没有。
+
+- 导入卡在启动页上出现,引擎同时在新数据位置预热(已定的「先在新数据位置启动一次再复制」照旧,只是和提问并行,不再空等)。
+- 标题「要把 DeepSeek Harness 里的 Bot 团队复制过来吗?」,内容先列名字、数量和大小,再说会复制什么、不会复制什么:
+ - 「在 `C:\Users\<用户名>\.dsh` 里找到 6 个 Bot(Chief、写手、程序员等)和 2 个群聊,143 段对话。对话和记忆约 1.2 GB,工作文件约 3.4 GB。」
+ - 「会复制:Bot、群聊、记忆、对话、附件、模型设置和 API Key。不会复制:MCP、技能和 DSH Agent。DeepSeek Harness 里的内容不会改动,复制以后两边各用各的。」
+ - 模型设置自动选一份:先选有 key 的,再按 desktop、web、行数最多的顺序。显示提供商和默认模型,旁边有「更换」,可以按同样的格式换另一份。
+ - 可重新生成的文件夹(`node_modules`、`.venv`、`__pycache__`、`.pnpm-store`、`.next` 等)合计 200 MB 以上时,默认勾选「不复制可以重新生成的文件夹」。工作文件超过 2 GB 或空间不够时,提供「先不复制工作文件」(之后能在设置里补)。
+ - 〔复制过来(推荐)〕〔先不复制〕,脚注「也可以在 设置 → 通用 → 位置 里复制。」
+- 复制前先查空间:按今天的顺序,约「对话 + 附件 × 2 + 工作文件 + 500 MB」(检查用的对话副本在复制开始前就删掉了;附件先进暂存再复制到目标,算两份)。空间不够就说清楚差多少,并给〔先不复制工作文件〕〔换个位置…〕〔先不复制〕。
+- 复制时显示分步进度和数字:「检查对话 23/40」→「复制 Bot 和对话 820 MB / 1.2 GB」→「复制工作文件 1,204 个」→「启动团队」,带剩余时间估计和任务栏进度。〔停止复制〕会就地确认,并说明停下后会留下什么:不留下复制了一半的团队,DSH 里的团队不受影响,已复制的工作文件留在总工作区,下次复制不会覆盖已有文件。
+- DSH 正在用这个团队:「请完全退出 DSH Desktop(任务栏右下角的托盘图标也要退出),并关掉 DSH Web,这里会自动继续。」每 2 秒自动重查,不用点重试。判断规则和 ds-bot 的 home-lock 一样:同一台机器上 PID 活着**而且**锁在 60 秒内刷新过(#428 的修法),被系统重用的旧 PID 不再算。
+- 有更新版本 DSH 写的对话:更新器现在随应用一起启动,找到能读的版本时:「DeepSeek Bot 0.2.4 能读它们,正在下载(37%)。装好后会重新打开,再复制团队。」位置在这之前不保存,重开后会再问导入。没找到时:「这些对话是更新版本的 DeepSeek Harness 写的,DeepSeek Bot 现在读不了。」主按钮是〔先不带团队开始〕(不再是「退出」),脚注「可以在 设置 → 通用 → 位置 里再复制。」
+- 复制失败:「团队没有复制完:{原因}。DeepSeek Harness 里的团队没有变化。」常见原因翻成人话(文件被别的程序占用 / 没有权限读取 / 磁盘满了),其他放进「详细信息」。〔重试〕〔先不带团队开始〕〔复制详细信息〕。失败或停止时删掉 `.import-<时间>` 暂存文件夹。
+- 导入的修正:群聊的接力 Session(`room.id`)也复制(#551,PR #567);目标里已有的 `.credentials.yaml` 不覆盖。
+- 复制完成后,窗口打开在导入来的 Main Bot 的聊天里,先显示一张一次性的卡片「复制好了:6 个 Bot、2 个群聊、143 段对话。」,然后是对模型的检查结果。检查通过显示「模型:DeepSeek-V4-Pro · DeepSeek API — Key 可以用,余额 ¥23.50」;没通过就在用户打字前显示对应的修复卡(见第 6 节)。
+- 导入后,Main Bot 在模型检查通过后马上(空闲时)换到新文件夹的新一段(只提前换 Main Bot 待定),并显示「正在把{名字}搬到新的工作文件夹(要读一遍最近的对话,大约 1 分钟)。现在发消息也可以,会排在后面。」其他 Bot 在各自的第一条消息时换段,换段期间先显示用户的消息和「正在搬到新文件夹…」,不再出现 84 秒什么都没有的情况(#384)。
+
+### 5. 接上模型:Main Bot 的设置卡
+
+这是插件的功能,桌面应用、DSH Desktop 和 DSH Web 里都一样。
+
+- Main Bot 还没有能用的模型时,它的聊天里不再是三个按钮,而是一张卡片(按 UI 标准里提问卡的样式):
+ - 气泡:「你好,我是{名字},负责管理你的 Bot 团队。开始之前,我需要先接上一个模型。选一种方式:」
+ - A「用 DeepSeek 账号登录」,标「推荐」:「不用管理 API Key。没有账号的话,在登录页用手机号就能注册。费用从账号余额里扣;新账号如果有赠送额度,登录后会显示在这里。」主按钮〔在浏览器中登录〕。profile 里没有 DeepSeek 账号功能时不显示 A。
+ - B「粘贴 DeepSeek API Key」:掩码输入框(占位「sk-…」)、〔检查并保存〕、「去 DeepSeek 开放平台创建 Key ↗」(`https://platform.deepseek.com/api_keys`)和一句「API 按用量计费,账户里要先有余额。」
+ - 底部「用其他模型服务…」打开 DS Bot 设置 → 模型的添加表单。
+- **登录**:点按钮就在系统浏览器打开 DeepSeek 登录页,卡片变成「已在浏览器打开 DeepSeek 登录页。登录完会自动回到这里;登录完成前请不要关闭这个窗口。」,带有效期、「浏览器没打开?复制登录链接」和〔取消〕。登录完成后窗口自动回到前台(桌面应用新增的 `dsBotApp.focus()`);Windows 不允许抢前台时,任务栏按钮闪烁。
+ - 卡片用的是 `settings.models.sign-in` 条目注入的操作,取法和今天一样(`ctx.slots.entries('settings.models.sign-in')` 的第一个,即现有的 `actions.signInEntry()`)。这些操作有类型声明,但 DSH 没有写成给插件用的接口:每个要调的操作都先确认存在,缺了就退回今天的 `DeepSeekSignIn`。
+ - 和 DSH 自己的做法一样:开始登录时 `setOnboarding(true)`;成功、取消、过期、失败,以及卡片卸载时,都调 `setOnboarding(false)` 和 `showLogin(false)`。否则切到经典 Agent 模式时,DSH 的账号菜单会再弹出一个登录框。`start()` 本身失败时按「登录没有完成」处理。
+- **粘贴 key**:保存前先检查。只对 DeepSeek 官方地址:`GET https://api.deepseek.com/user/balance`,8 秒超时,不记录 key 和返回内容。`DEEPSEEK_BASE_URL` 指向本机地址时(mock 模型),检查发到那个本机地址的 `/user/balance`;其他自定义地址或中转服务不检查余额,交给第一轮的修复卡。key 只会发给 `api.deepseek.com` 或本机地址。
+ - 401:「DeepSeek 不接受这个 Key(401)。请确认整段复制了,或者新建一个。」key 不保存,输入框保留内容和焦点。
+ - 格式不对(带引号、带 `NAME=` 等,沿用现有规则):「只粘贴 Key 本身,不要带引号或 NAME=…」
+ - 余额为零:key 保存,卡片显示「Key 没问题,但账户余额是 ¥0.00,充值后才能用。」〔去充值 ↗〕〔再查一次余额〕。
+ - 连不上:「暂时连不上 api.deepseek.com,Key 还没保存。如果在用代理软件,确认它开着。」〔再试一次〕〔仍然保存〕。429 或 5xx:「DeepSeek 服务暂时繁忙({状态码}),Key 还没保存。」同样两个按钮。
+ - key 来自环境变量 `DEEPSEEK_API_KEY` 而检查没通过:「这个 Key 来自环境变量 DEEPSEEK_API_KEY,这里改不了。」〔换一种方式〕
+- **账号余额为零**(登录后):「已登录 DeepSeek 账号,但余额是 ¥0.00。充值后我就能开始;一般一轮对话只要{实测值},以 DeepSeek 价格页为准。」〔去充值 ↗〕〔再查一次余额〕〔换一种方式〕。key 余额为零时用上面「粘贴 key」里的卡片。这两张卡显示期间,窗口回到前台时、以及每 10 秒(最多 10 分钟)自动重查,余额一到就自己往下走。
+- **自动选模型**(插件形态里是否也这样待定):只有一个提供商能用时,不再让用户选,直接用 DSH 默认模型(能用的话),否则用这个提供商的第一个模型。选之前先确认能用:有不调用模型的检查就用它(账号余额、`/user/balance`;后者是否计费没有文档),没有就发一次 8 token 的试连。通过后卡片收成一行「已接上 DeepSeek-V4.1-Flash · DeepSeek 账号 更换」,Main Bot 的开场白随即开始。两个以上提供商能用时,仍按提供商分组让用户选,DSH 默认模型标「推荐」。
+- 登录 DeepSeek 账号后,DSH 的账号前端会尽力把账号模型存成默认,但这一步不保证完成、也不保证先于我们,所以只剩账号这一个提供商时,DS Bot 自己选账号的第一个模型,不等 DSH。
+- 开场白只在确认能用之后才发。聊天记录不会以一行红字开头。
+- 没有能用的模型、且模型列表已知时,Bot 聊天的输入框不可用,占位写「先在上面接上模型,我就能回复你」(DSH 有文档的 `ComposerBlocks`)。
+- 万一消息在接上模型前就发出去了(比如别的入口),开场白不再被删掉:Main Bot 接上模型后先回答这条消息,再用一句话说明自己是管团队的。
+- 判断「能用」:catalog 里标了 `needsKey` 的模型不算能用。Host 的默认模型(`pickDefault`、`defaultModel`、`cachedDefault`)、建 Bot、`create_bot` 不指定模型时的回退、模型不再被服务时 `desiredModel` 和 `memory.js` 里的回退、模型菜单(`ModelRows`)和选模型卡片,都只从能用的模型里挑。需要 key 的模型在列表里显示「需要 API Key」,点它打开 key 卡片。
+- `needsKey` 只覆盖「profile 写了 `apiKeyEnv`、而凭据未配置」的提供商;DeepSeek 账号这类登录式的提供商永远不会标 `needsKey`,没登录时也在列表里。所以「能用」最终以上面的检查为准,`needsKey` 只是第一道过滤。
+- 提供商的显示名:`deepseek-account` 显示「DeepSeek 账号」,`deepseek-official` 显示「DeepSeek API」。中文统一用「提供商」(替换 `i18n.js` 里的「服务商」)。
+
+### 6. 第一条有用的回复
+
+- 开场白用界面语言(沿用现有的 kickoff),两句,以一个问题结尾。下面在用户发第一条消息前显示:「已接上 DeepSeek-V4.1-Flash · DeepSeek 账号 更换」、「工作文件夹:`C:\Users\<用户名>\DeepSeek Bot` 更换」,以及「试试:」三个固定按钮:「你能帮我做什么?」「帮我建一个写周报的 Bot」「搜一下今天的科技新闻,挑 5 条讲给我」。这三件事不需要读文件、跑命令或日历权限,第一步不依赖模型自己出题。点按钮等于用户自己发这句话。
+- Bot 聊天里任何一轮失败,都由插件画一个修复卡,替换 DSH 的「本轮运行失败」那一行(DSH Agent 的普通会话不变)。原文、代码、HTTP 状态码和 request id 放在「技术详情」里,可以复制;AUTH 的原文照旧不显示。
+
+| 代码 | 卡片 | 按钮 |
+|---|---|---|
+| MISSING_CREDENTIAL | 「{名字} 用的模型还没有 API Key。」 | 填入 API Key / 用 DeepSeek 账号登录 / 换个模型 |
+| INVALID_CREDENTIAL | 「这个 API Key 的格式不对。」 | 重新填 Key / 换个模型 |
+| AUTH | 「{提供商} 不接受现在的 API Key({状态码})。」 | 重新填 Key / 改用账号登录 / 换个模型 |
+| QUOTA | 「{提供商} 的余额或额度不够了({状态码})。」 | 去充值 ↗(只有 DeepSeek 官方时)/ 重试 |
+| ACCOUNT_QUOTA | 「DeepSeek 账号余额不足。」 | 去充值 ↗ / 重试 |
+| ACCOUNT_SIGN_IN_REQUIRED、ACCOUNT_SIGNED_OUT、ACCOUNT_TOKEN_INVALID | 「DeepSeek 账号的登录失效了。」 | 重新登录 |
+| TRANSPORT、TIMEOUT | 「连不上模型服务。」在用系统代理时加一句「现在走的是系统代理 127.0.0.1:7890:如果代理软件没开,打开它,或者在 设置 → 通用 → 网络 里关掉「跟随系统代理」。」 | 重试 |
+| RATE_LIMIT | 「请求太频繁,稍等一会儿再试。」 | 重试 |
+| SERVER | 「模型服务出错了。」 | 重试 |
+| 其他 | 现有的简短说明 | 重试 |
+
+- 卡片按失败代码选,不看原文(DSH 也是按代码分流的,原文和 `failureMessage` 都是它的内部细节)。提供商名字和状态码取自这次失败的路由和 HTTP 状态,不写死「402」或「DeepSeek」:QUOTA 也可能来自别的状态码和别的提供商。`noteTurnFailure` 今天只把状态码和 request id 写进诊断日志,要新增到 Bot 的状态里(`bot.blocked`),经 `api/bot` 给卡片读。
+- 「重试」让 Bot 接着做,不会把用户的话再发一遍。充值回来后自动重查余额,并接着做。
+- 开场白因为凭据或余额失败时,重新留着,下一次检查通过时再发。
+
+### 7. 第一个小时
+
+- **命令沙盒启动不了命令**(#523,`exit code 3221225794`,DSH 的问题):工具结果下面显示「这台电脑上,DeepSeek Harness 的沙盒启动不了命令(错误 0xC0000142),不是命令本身的问题。可以给 {名字}「完全权限」,或者在它请求时批准单条命令。」〔打开 {名字} 的权限设置〕〔先不改〕。给完全权限照旧要二次确认、照旧标红。Bot 也会收到一条说明,改为请求批准,而不是盲目重试。
+- 没有装 PowerShell 7 的 Windows 上,提示词里写明命令跑在 Windows PowerShell 5.1:不能用 `&&` 和 `||`。
+- **系统代理**(仅桌面应用;默认开待定):用户自己没设 `http_proxy` / `https_proxy` / `all_proxy`(任何大小写)、数据位置的 `.env` 里也没有时,应用用 `session.resolveProxy` 读 Windows 系统代理,作为启动环境传给引擎。
+ - `resolveProxy` 返回的是 Chromium 的 PAC 结果列表(`;` 分隔,可能有 `PROXY`、`HTTPS`、`SOCKS`、`DIRECT`):按顺序取第一个可用项,遇到 `DIRECT` 就停;`PROXY h:p` 写成 `http://h:p`,`HTTPS h:p` 写成 `https://h:p`,一律带协议(DSH 不认没有协议的 `h:p`);SOCKS 跳过(DSH 也不支持),相关提示改为「系统代理是 SOCKS 类型,DeepSeek Bot 用不了;请在代理软件里打开 HTTP 端口,或设置 https_proxy」。
+ - 不设 `NO_PROXY`:DSH 自己会让本机地址直连,而 Windows 上同名不同大小写的环境变量只会传一个,设了反而可能盖掉用户的 `no_proxy`。PAC 可能对不同主机给出不同答案,按 `api.deepseek.com` 解析只是近似。
+ - 代理变量只放在启动环境里,绝不写进 profile 文件夹的 `.env`(DSH 会拒绝那里出现代理变量)。应用自己的更新下载走 Chromium 网络栈,本来就跟随系统代理,不受这项影响。
+ - 设置 → 通用 → 网络里有开关「跟随系统代理」,打开时旁边显示现在的系统代理(如 127.0.0.1:7890)。「连不上 GitHub」加一句代理提示。
+ - 验证 `NODE_USE_SYSTEM_CA` 在 `ELECTRON_RUN_AS_NODE` 下有效后,才在引擎的启动环境里设它;验证不了就不设。
+- 冷启动时 Bot 列表不会是空的(#559):第一次挂载后检查团队侧栏是否真的出来了,没有就重新挂载一次;「回到 Main Bot」的逻辑移出 `TeamSidebar`。
+- Bot 还在干活时关窗口,先问「有 2 个 Bot 还在工作,关闭窗口会让它们停下。」〔仍然关闭〕〔取消〕(#500)。
+- 鲸鱼菜单增加「模型和 API Key」,以及未登录时的「登录 DeepSeek 账号」。桌面应用里「切换经典 Agent 模式」只放在 设置 → 通用。
+
+### 8. 以后的启动和回头入口
+
+- 以后每次启动也显示启动页,只写「正在打开你的团队…」,然后打开上次的 Bot(预计 3 到 12 秒,以后的启动还没实测)。
+- 设置卡由状态决定:没有能用的模型(跳过过、删了 key、退出了登录),Main Bot 的设置卡就回来;账号登录过期时显示「DeepSeek 账号的登录失效了。」〔重新登录〕。
+- DS Bot 设置 → 模型在所有形态里都有(在 `team-actions.js` 里接上插件 Host 已有的 `providers`、`provider-key` 等接口,今天只有停用的 `app/ui` 接了),显示每个提供商的 key 状态(「已设置 Key」「需要 API Key」「Key 来自 DS Bot 之外」)和「添加提供商」。原来的「Harness 设置」改叫「高级设置(DeepSeek Harness)」。
+- 要打开 DSH 自己的模型页时(「高级设置」里的模型、鲸鱼菜单的「模型和 API Key」在没有 DS Bot 模型页时),直接落在「模型」上,不再落在「通用设置」:插件注册一个自己的 `settings.onboarding` 步骤,自动检查时立刻完成、什么也不画;被 `openOnboarding(id)` 明确打开时调用 DSH 交给步骤的 `openSection('models')` 再完成。这些都是 DSH 有文档的接口。
+- 设置 → 通用 → 位置(桌面应用):总工作区和数据位置各有〔打开〕〔更换…〕;`~/.dsh` 有团队时有「从 DeepSeek Harness 复制团队…」(复制到一个新的数据文件夹,现在的团队原样保留);跳过过工作文件时有「复制 DeepSeek Harness 里的工作文件…」;还有标红、要点两次的「用新的空白团队开始…」(在新文件夹新建,现在的数据原样保留)。这些都在新文件夹里完成,新引擎 `ready` 之后才切换 `locations.json`,失败就继续用原来的,不需要恢复。
+- 设置 → 关于:下载更新时显示百分比和大小(「正在下载 0.2.4(37%,78/212 MB)」),「下载失败」和「没能检查更新」分开,各带〔重试〕〔手动下载〕;「保存诊断信息…」把诊断表和日志最后 200 行存成一个 .txt(默认放桌面),报问题不需要能上 GitHub。反馈页里形态显示为「DeepSeek Bot 应用」(今天会误报成 DSH Web)。
+- **更新**:更新器随应用启动(不再等导入结束),首次启动和导入期间不弹重启提示。中文界面或中国时区先试镜像、再试 GitHub,其他情况反过来,记住上次能用的源。60 秒没有收到数据的下载会取消并换源;两个都失败时显示「没能检查更新:连不上更新服务器。」〔重试〕〔手动下载〕,不阻塞任何东西。
+
+### 9. 卸载和重置
+
+- 卸载时先是 NSIS 的「确定要卸载吗」,然后只多问一个问题,默认「否」:「要同时删除 DeepSeek Bot 的数据吗?会删掉对话、Bot、记忆、API Key 和登录信息:{数据位置},以及 {壳数据}。数据文件夹是 DeepSeek Bot 新建的,会整个删除;否则只删除 DeepSeek Bot 自己的文件。不会删除 Bot 的工作文件夹 {总工作区}(里面是你的文件)。选「否」会全部保留,重新安装后接着用。」
+- 选「是」:数据文件夹有 `.deepseek-bot` 标记就整个删掉;没有标记(老版本装的,或者老版首次启动允许过的 `D:\`、非空文件夹)就只删应用和 DSH 自己的条目(`bot`、`profiles`、`sessions`、`attachments`、`storages`、`.anonymous-user-id`、`.credentials.yaml`、`.env`、`.import-*`、`.import-check-*`),删完是空文件夹才删文件夹本身。换数据位置的暂存在数据文件夹旁边(`.<文件夹名>.moving-*`),不在里面。磁盘根目录、家目录和总工作区永远不删。再删 `%APPDATA%\DeepSeek Bot` 和 `%LOCALAPPDATA%\deepseek-bot-updater`。
+- 静默卸载(`/S`,包括 winget)和更新时的卸载(旧卸载程序带 `/S --updated` 运行)不问、不删(CI 现有的「卸载后数据还在」检查照旧通过)。
+- 一键安装模式下,卸载程序在 `customUnInit` 之前已经被设成静默,`${Silent}` 分不出用户的 `/S` 和正常卸载,所以真正起作用的是重新解析命令行里的 `/S` 和 `--updated`,有任一个就不问。提问用不带 `/SD` 的 MessageBox(带了在一键模式下就永远不显示),加 `MB_SETFOREGROUND`,因为这时没有卸载窗口可依附。提示文字用 LCID 1033 和 2052 定义自己的 LangString(`installer.nsh` 被包含时 `${LANG_ENGLISH}` 等常量还没定义)。模板顺序是 electron-builder 的内部细节,升级它时由 CI 的交互式卸载测试把关。
+- README.md 和 README.zh.md 都增加「卸载和重置」一节,用 `%APPDATA%`、`%LOCALAPPDATA%`、`%USERPROFILE%` 写出 Windows 上的实际位置。
+
+### 用词
+
+- 一个东西一个名字:DeepSeek Bot(应用)、DS Bot(项目和插件)、DeepSeek Harness(底层;界面里只在讲它本身时出现:导入和复制团队、「预览版说明」的提醒、它的沙盒问题、「高级设置(DeepSeek Harness)」)、本机引擎(启动页上对应用启动的 DSH 的叫法)、主 Bot(Main Bot)、群聊、总管(中文界面里第一个 Main Bot 的默认名字,待定)、模型、API Key、DeepSeek 账号、提供商、数据位置(设置项的名字;说那个文件夹本身时叫「数据文件夹」)、总工作区。
+- 本文里「引擎」指桌面应用启动的 DSH 子进程,「引擎的页面」是它提供的网页前端;「Host」只指插件的 `ds-bot/src/host`。
+- 第一次介绍产品的地方都写「不是 DeepSeek 官方产品」。
+- README.md 和 README.zh.md 各加一行名词解释:DeepSeek Bot / DS Bot / DeepSeek Harness。
+- 中文界面里用户能看到的英文,只允许专有名词(DeepSeek、DS Bot、Bot、API、Key、Harness、DSH、Agent、MCP、Windows、PowerShell、GitHub、SmartScreen、OneDrive、HTTP、SOCKS)、模型名、文件名、路径、网址、环境变量名和单位(KB、MB、GB);「技术详情」和「详细信息」里的原文不算。测试会扫描。
+
+## 改动的已定设计
+
+| 原来的设计 | 现在 |
+|---|---|
+| [桌面应用](2026-10-16-desktop-app.md)「首次启动分别选数据位置和总工作区……用的是系统对话框」 | 窗口先出来,显示应用自己的启动页;默认位置直接用,只在需要时出卡片;选择框挂在窗口上,两个位置分开改 |
+| 同上「结构」「窗口」:窗口加载引擎自己的本机地址 | 窗口先加载应用自己的启动页,引擎起来后再加载引擎的本机地址(同一个地址和端口) |
+| 同上「首次启动没走完就退出时什么都不记」 | 保留;`locations.json` 改在引擎第一次 `ready` 之后才写,另写 `locations.ini` 和 `.deepseek-bot` 标记 |
+| 同上「问要不要导入,只在首次启动问一次」 | 首次启动仍然问(带预览和大小),之后在 设置 → 通用 → 位置 里随时可以复制到一个新的数据文件夹 |
+| 同上「DSH 正在用这个团队时,请用户先关掉」 | 判断加上锁的刷新时间;自动重查,不用反复点重试 |
+| 同上「旧团队工作文件夹里的文件复制到新的总工作区,不覆盖已有的文件」 | 仍然不覆盖;默认跳过可重新生成的文件夹;工作文件可以以后再复制 |
+| 同上「几个 profile 都有时让用户选一份」 | 自动选,按提供商和默认模型显示,可以更换 |
+| 同上 有新版本对话时按钮是「退出 / 不带团队开始」 | 能更新就「更新后再复制」;不能就以「先不带团队开始」为主 |
+| 同上「模型服务商和 key 在 DSH 自己的设置里配」 | 在 Main Bot 的设置卡和 DS Bot 设置 → 模型里配(仍写进 DSH 的凭据和设置);应用关掉 DSH 的自动凭据引导;DSH 的模型页放在「高级设置(DeepSeek Harness)」 |
+| 同上「暂时不做」:DS Bot 自己的界面先停下 | `app/ui` 仍然停着;应用只画启动、导入、失败这几页,不画 Bot 界面 |
+| 同上「改位置」 | 加「从 DeepSeek Harness 复制团队…」「复制 DeepSeek Harness 里的工作文件…」「用新的空白团队开始…」 |
+| 同上 Windows 安装向导,可以改程序位置 | 一键安装、装完自动打开(待定) |
+| 同上「卸载不删数据位置」 | 卸载时问一次,默认不删 |
+| 同上 更新检查在首次启动的导入之后开始;启动失败时错误框里提新版本 | 随应用启动;首次启动和导入时不弹重启;镜像优先;失败页里直接给更新 |
+| 同上 不签名,SmartScreen 是已知限制 | 走签名(路线待定);签名前在下载页说明 |
+| [Bot 运行配置](2026-10-10-bot-runtime.md)「团队的第一个 Main Bot 没有模型,等用户在它的聊天里选好再打招呼」 | 只有一个提供商能用时自动选,并在确认能用后再打招呼;两个以上仍然让用户选 |
+| 同上 已知限制「新 Bot 可能落到没配好密钥的模型上」(「怎么根治待维护者定」) | 按那里写的方向解决:默认只从能用的模型里选(`needsKey` 先过滤,再用检查确认),凭据失败回到设置卡或修复卡。那条限制里「DSH 不告诉插件哪个提供方已经配好了凭据」已经部分过时:DS Bot 现在能标出 `needsKey`,但「有 key」仍不等于「key 能用」 |
+| `ds-bot/index.js` 默认 Main Bot「Chief / Chief of Staff」 | 中文界面下建团队时用「总管 / 团队负责人」(待定):看配置里有没有指定名字(`rt.config`,不看已经合并了英文默认值的 `rt.defaults`),没有时按第一次 `state` 请求带来的界面语言的主标签是不是 `zh` 决定;英文不变,已有团队不改 |
+
+实现各批时,同步改写上面几份文档里对应的规则本身(「已定的行为」写现在的行为,不只是在末尾追加),并在它们的「变更」里写一条;新的 DSH 让步记进 [DSH 让步总账](2026-10-13-dsh-concessions.md),「提供商」记进 [UI 标准](../design/ui-standard.md) 第 11 节的术语表。
+
+## 需要 DSH 提供的
+
+不打补丁,以下向 DSH 提需求:
+
+1. 给网页版的「预览版说明」一个有文档的关闭开关(和 `credentialOnboarding` 放在一起),供嵌入它的应用使用。
+2. 修 Windows 沙盒在 Electron(`ELECTRON_RUN_AS_NODE`)里启动 pwsh 时的 `0xC0000142`(#523 有复现),并报一个有结构的错误码,不要只给退出码。
+3. `MISSING_CREDENTIAL` 在聊天里显示本地化的一句话,不显示提供商路由和环境变量的原文;AUTH、QUOTA 的失败节点带上 HTTP 状态码(不带 key)。
+4. 把 `settings.models.sign-in` 条目注入的操作(`start`、`cancel`、`showLogin`、`setOnboarding`、`refreshAccount`、`hooks.account` 等)和 `credentialOnboarding` 声明为跨版本稳定的插件接口,或者提供一个有文档的「开始 DeepSeek 登录、读余额」的客户端 API。
+5. 一个不扣费、也不需要插件读回 key 的凭据检查(`ok / invalid / no-balance / unreachable`),并给模型页的 key 编辑框加上实时检查。
+6. `listModels` 标出哪些模型的提供商还没有凭据(PR #316 的后续)。
+7. 网页版余额不足的提示加一个充值按钮(今天在没有 `nativePlatform` 时只是一个 Toast);这条提示能按 Session 区分,或者让插件接管自己的 Session。
+8. 登录完成页提示用户回到原来的应用;应用已经关掉、回调地址失效时给出清楚的提示。
+9. 让 DSH 的代理跟随 Windows 系统代理(含 PAC),并考虑信任系统证书库。
+10. `settings.launcher` 插槽能直接打开设置的某一节(比如「模型」)。今天可以借一个自己的 `settings.onboarding` 步骤绕一步做到(见第 8 节),有了这个接口就更简单。
+11. `runProfile` 报告命名的启动阶段,供壳显示真实进度。
+12. pwsh 工具的说明里写明实际是 Windows PowerShell 5.1 还是 PowerShell 7。
+
+## 分批上线
+
+每批一个或几个小 PR,按「对用户的影响 ÷ 工作量」排序。签名申请和镜像试测最先开始,因为它们要等外部审批。
+
+| 批次 | 内容 | 估计 |
+|---|---|---|
+| M1 去掉死路 | 应用:「下载」文件夹兜底;`credentialOnboarding: false`;`focusWindow` 在失败时也能聚焦;导入的锁判断、失败清理暂存、`room.id`(合 #567)、不覆盖已有 key。插件:在所有形态接上提供商接口(模型页和 key 卡片活过来);key 卡片加「去创建 Key」链接和余额说明;默认模型只从能用的里选;先打字不再删开场白;`bot.blocked` 和 Bot 聊天的修复卡,「重试」不重发;鲸鱼菜单加「模型和 API Key」「登录」;「高级设置」改名,DSH 设置直接落在「模型」页。文档和发版:README 双语下载区和信任说明、安装问题表单、Release 下载表、`SHA256SUMS` 和固定文件名、最后才标为 Latest | 约 4 人日 |
+| M2 Main Bot 聊天里的第一条回复 | 设置卡:浏览器登录的完整状态、回到前台(应用的 `dsBotApp.focus()`)、余额和赠送额度、充值后自动重查;粘贴 key 时的余额检查(mock 模型提供 `sk-test-ok` / `sk-test-bad` / `sk-test-empty`);插件 Host 侧的「能用」检查和自动选模型;「已接上 · 更换」;输入框锁定;试试按钮和工作文件夹行;中文默认名字(如果定下来) | 约 6 人日 |
+| M3 国内能下、一键安装、卸载说清楚 | 镜像发布和镜像优先的更新(随应用启动、首次启动和导入时不弹重启、可取消的下载、60 秒无数据换源、百分比);一键安装;卸载时的问题、`locations.ini`、标记文件;CI:一键升级覆盖旧的自定义目录、交互式卸载(UI Automation 答「否」和「是」)、固定链接检查;README「卸载和重置」 | 约 5 人日 |
+| M4 窗口先出来:启动页、卡片和恢复页 | 启动页、它的 IPC 和来源检查、中英文案;`main.mjs` 重排;位置检查和重装识别;失败页和 180 秒提示;日志;`dsBotApp.ready()` 和 20 秒界面检查;#559。CI:打包后的首次启动,用名为「测试 用户」、没有「下载」文件夹、没有 `~/.dsh` 的一次性用户,经 CDP 驱动启动页,并检查日志里没有 key、token 和用户名 | 约 7 人日 |
+| M5 启动页上的导入 | 预览、大小和可跳过的文件夹;并行预热;自动重查占用;新版本对话走「更新后再复制」;空间检查;进度和停止;设置里的再次导入;导入后的检查卡和 Main Bot 提前换段(#384)。CI 用假的 `~/.dsh`(含 junction、新版本对话、PID 被重用的旧锁、群聊、大 `node_modules`) | 约 5 人日 |
+| M6 第一个小时和回头入口 | 系统代理和网络设置;沙盒失败提示(#523);PowerShell 5.1 说明;GitHub 代理提示;关窗提醒(#500);保存诊断信息;「DeepSeek Bot 应用」形态;「用新的空白团队开始」 | 约 4 人日 |
+| M7 签名 | 签名钩子、`publisherName`;README 的信任说明缩成杀毒软件一条;winget 清单 | 约 2–3 人日,加外部审批 |
+
+## 验收
+
+- 打包后的 Windows CI,用名为「测试 用户」、没有「下载」文件夹、没有 `~/.dsh` 的一次性用户:进程启动后 2 秒内窗口可见(目标 1 秒,CI 留余量);引擎的页面之前不出现任何卡片;能进到引擎的页面。
+- 首次启动期间没有一个 `dialog.show*` 不挂在主窗口上(单元测试扫描调用处),窗口出来之前没有系统对话框。
+- mock 模型粘贴 `sk-test-ok`:第一个 Main Bot 的 Session 里没有失败节点,引擎的页面出来后 30 秒内收到开场白;CI 上从双击安装包到开场白不超过 90 秒。
+- `sk-test-bad` 不会被保存(`credentials.describe` 仍是未配置),卡片显示 401 的文字,Session 里没有回合。`sk-test-empty` 会保存,但 `/user/balance` 报出余额之前不跑开场白,卡片显示「去充值」。
+- 插件 Host 的单元测试(替身 `deepseekAccount`):未登录和零余额的账号不会产生开场白回合;有余额的会在自动选模型后产生;`getBalance` 失败时照常往下走。
+- 中文界面下,把启动页、设置卡、修复卡的每种状态和卸载提示都渲染一遍,除允许名单外找不到英文单词。
+- 没有能用的模型且模型列表已知时,Bot 聊天的输入框不可用;绕过输入框发出的消息在接上模型后会得到回答,开场白不丢。
+- 「重试」不会在 Session 记录里多出一份用户的话。
+- Bot 聊天里每种失败代码都显示插件的修复卡,至少一个按钮;原文只在「技术详情」里,AUTH 的原文从不显示。
+- 从卡片发起登录后,无论成功、取消、过期还是失败,切到经典 Agent 模式都不会冒出 DSH 的登录框。
+- 全新的应用 profile 上,DSH 的「开始使用」凭据框不会自动出现,页面里 `__DSH_MODELS_ONBOARDING__.credentialOnboarding` 是 `false`。
+- 「高级设置」里的模型入口打开的是 DSH 设置的「模型」页;DS Bot 自己注册的那个 `settings.onboarding` 步骤在自动检查时立刻完成,不挡住 DSH 自己的步骤。
+- 引擎失败后 1 秒内出现失败页,每种都有五个按钮,窗口不隐藏。禁用 ds-bot 的测试 profile 在 25 秒内显示「团队界面没有加载出来」。
+- `main.log` 和复制出来的详细信息里没有 `sk-test-*`、`token=` 的值和用户文件夹的路径。
+- 导入:PID 活着但锁超过 60 秒没刷新,不算占用;失败或停止后没有 `.import-*` 文件夹;`room.id` 的 Session 被复制;已有的 `.credentials.yaml` 不被覆盖;导入写模型设置时,数据位置里 `profiles/ds-bot/cordis.patch.yml` 的其他行(如 `ui-settings-general`)保留,应用自己的补丁里没有这一行。
+- 卸载:`/S` 和更新时什么都不删;交互卸载显示问题,「否」全部保留,「是」删掉带标记的文件夹和 `%APPDATA%\DeepSeek Bot`,没标记的只删自己的条目,从不删磁盘根目录,总工作区永远保留。
+- 更新:镜像挂了一次检查内就换到 GitHub;60 秒没有收到数据的下载会取消并换源;关于页显示百分比。
+- 发版:「标为 Latest」是最后一步,依赖 GitHub 上传、镜像和下载表;链接检查访问两个固定地址(200 或 302)。
+- README.md 和 README.zh.md 前 10 行有 Windows 下载链接(有镜像后镜像在前)和「不是官方产品」,两份同步。
+- README 和卡片里「一轮多少钱」来自 PR 里记录的实测(默认模型上三次开场白)。
+- `npm test`、`node scripts/build-client.mjs --check`、`npm run lint` 和冒烟测试通过;`dev/smoke.mjs`、`app/scripts/check-packed.mjs` 和它们覆盖的行为在同一个 PR 里改。
+
+## 待定
+
+| 问题 | 选项 | 建议 |
+|---|---|---|
+| Windows 用哪种代码签名? | SignPath Foundation(开源项目免费;发布者显示「SignPath Foundation」;要审批,每次发版要人工批准);云 HSM 上的 OV 证书(每年约 200–400 美元;发布者是维护者);Azure Artifact Signing(约 9.99 美元/月,但个人只能在美国和加拿大申请);Microsoft Store MSIX(微软免费重新签名,没有 SmartScreen 和智能应用控制的拦截;要审核,名字里带「DeepSeek」有风险,多一条更新渠道) | 先申请 SignPath Foundation,问清它是否接受 electron-builder 的签名钩子、能否签 Electron 自带的 exe 和第三方 `.node` / `.dll`。被拒再考虑 OV 证书。MSIX 等改名的决定之后再说 |
+| 国内镜像放在哪里? | CNB(cnb.cool)镜像仓库的 Release(免费,腾讯运营;限制未验证);腾讯云 COS 默认域名(下载不需要备案;约 ¥0.5/GB,按现在的量每月约 ¥100–450;要实名账号);npmmirror 的 binary-mirror-config(免费,晚几小时同步,要对方维护者同意);Gitee Release(附件大小限制,约 212 MB 的安装包很可能放不下) | 先从大陆网络试测 CNB(固定的 latest 地址、300 MB 以上文件、不用登录、支持断点续传)。通过就用 CNB,否则用 COS。GitHub 永远是第二个链接和第二个更新源 |
+| 中文界面里第一个 Main Bot 叫什么? | 「总管」,角色「团队负责人」;保留「Chief」,角色「团队总管」;「总管家」,角色「团队负责人」 | 「总管」,角色「团队负责人」,按建团队时的界面语言决定;英文不变,配置优先,已有团队不改,测试和 README 同一个 PR 里改 |
+| 安装包要不要改成一键安装? | 一键、只装给当前用户、装完打开、没有目录页(`/D=` 自定义);保留向导,但去掉目录页、默认勾选「运行」 | 一键安装。少两次点击(「安装」「完成」),也去掉了最技术化的一页 |
+| 插件形态(DSH Desktop、DSH Web)里,第一个 Main Bot 也自动选模型并打招呼吗? | 所有形态都这样(只有一个提供商能用且检查通过时);只在桌面应用这样,插件形态仍然「先选再打招呼」 | 所有形态。开场白本来就是用户选完模型后会触发的一次调用;检查优先用不调用模型的余额查询;「已接上 · 更换」让选择看得见、改得了 |
+| 导入后哪些 Bot 提前换到新文件夹?(每次换段都要写交接说明,花 token) | 只有 Main Bot;Main Bot 加最近 30 天用过的 Bot,一个一个来;都不提前,只在第一条消息时显示换段状态 | 只有 Main Bot:它是用户落地的聊天,成本最低就能去掉看得见的等待 |
+| 引擎默认跟随 Windows 系统代理吗? | 默认开,设置里能关,用户自己的环境变量或 `.env` 优先;默认关,能打开 | 默认开。大陆用户开着 Clash、v2rayN 的系统代理,会期待 GitHub 和国外提供商像浏览器里一样能用;代理不对时修复卡会点名代理和开关 |
+| Bot 聊天里余额不足时,DSH 的余额提示(Toast,不分 Session)还会和修复卡同时出现,怎么办? | 接受两处同时出现;接管这条提示(会影响所有 Session) | 先接受,记进「已知限制」,并向 DSH 提需求(「需要 DSH 提供的」第 7 条) |
+
+## 不做什么
+
+- 不在应用里另做一套配置模型的欢迎向导:模型只在 Main Bot 的设置卡和 DS Bot 设置 → 模型里配。
+- 不伪装 `dshDesktop`,不用 CSS 或 DOM 去藏、改 DSH 的界面;DSH 的「预览版说明」等它的开关。也不预先写入它的「已读」版本号(`ui-settings-general` 的 `welcomeNoticeVersion`):那等于替用户点了「继续」,版本号也没有公开导出,写在补丁层里还会让用户以后点「继续」时保存失败。
+- 不改 DSH,不依赖 DSH 安装里的文件。DSH 的内部接口只用已经在用的 `@deepseek-ai/dsh-app-boot`、`@deepseek-ai/dsh-session-format`、`@deepseek-ai/dsh-session-format-catalog` 和 `settings.models.sign-in` 条目注入的操作(设置卡会多调 `setOnboarding`、`showLogin`、`cancel`、`refreshAccount`,见「已知限制」),不再新增。
+- 不扫描 D: 到 Z: 去推荐数据位置:读卡器、U 盘和网络盘一概不碰,只检查建议的那个位置所在的盘和用户自己选的文件夹。
+- 卸载从不删除总工作区、磁盘根目录和家目录。
+- 日志、复制出来的详细信息、诊断文件和文档里不出现 key、token 和真实的用户路径;界面上的位置只给用户本人看。截图只用一次性目录。
+- 不用其他产品的文字、图标和插图(包括 DSH Desktop 的欢迎页插图和字体);信任说明用自己画的示意图。
+
+## 已知限制
+
+- DSH 加开关之前,「预览版说明」仍然是引擎页面的第一屏,用户要多点一次「继续」;每个新的数据文件夹(以后的导入、重新开始)都会再出现一次。启动页只能提前提醒。
+- 设置卡调用的是 `settings.models.sign-in` 条目注入的操作。它们有类型声明,但 DSH 没有写成给插件用的接口,rc 版本之间可能变化。缺了哪个就退回到今天的 `DeepSeekSignIn`;每次升级锁定的 DSH 都要重测(另见「需要 DSH 提供的」第 4 条)。
+- `credentialOnboarding` 那一行的 id 如果在 DSH 里改了名,补丁只会留下一条警告、悄悄失效;靠验收里对 `__DSH_MODELS_ONBOARDING__` 的检查发现。
+- `GET /user/balance` 不在聊天 API 里,是否计费没有文档;它证明的是 key 和余额,不是模型能不能用。除了 401 以外的失败都不拦人,第一轮的修复卡兜底。
+- 自动选模型会在用户没有明确点选的情况下发出开场白(几 token 的付费调用);没有不调用模型的检查的提供商还要多一次 8 token 的试连。
+- Bot 聊天里余额不足时,DSH 自己的余额提示(不分 Session)会和修复卡同时出现。
+- 中文默认名字看的是第一次请求时的界面语言;DSH 存的语言偏好还没加载完时,它可能还是浏览器的语言,所以浏览器是英文、DSH 设成中文时,新团队仍可能叫 Chief。桌面应用里全新的数据位置以系统界面语言为准。
+- Windows 的前台规则可能不让窗口在登录后回到前台,这时只能靠任务栏闪烁和卡片自己的「已登录」状态。
+- 签名之前,开着智能应用控制的 Windows 11 装不了未签名的安装包,只能先走 DSH Desktop 插件这条路。签名主体如果是 SignPath Foundation,发布者会显示它的名字。
+- 一键安装去掉了选程序目录(估计约 600–700 MB 在 C 盘,实测后写进 README),只剩 `/D=`。
+- electron-builder 自带的几条 NSIS 报错(卸载旧版失败、解压失败)只有英文。
+- 卸载时删除数据是不可撤销的;没有标记的文件夹只删已知条目,列表不全时只会留下文件,不会多删。
+- 跟随系统代理可能让 DeepSeek 的流量走一个用户忘了的、或者已经退出的代理;诊断和修复卡会点名代理,可以关掉。
+- `NODE_USE_SYSTEM_CA` 在 `ELECTRON_RUN_AS_NODE` 下是否有效未验证;验证不了就不设,使用 TLS 检查的公司网络仍然连不上,只是提示更明确。
+- 导入后 Main Bot 提前换段要读一遍最近的对话写交接说明,冷缓存时会花不少 token(#384 实测 17 万 token)。
+
+## 变更
+
+- 2026-10-26:定下 Windows 上手流程。依据:`dev` 上的实测(全新用户,中文界面)、代码和 DSH 0.2.1-rc.2 的包、GitHub 上的 Issue 和 Discussions、同类应用的上手做法(只取原则)。
diff --git a/docs/plans/README.md b/docs/plans/README.md
index 283d53e4..bcd39f02 100644
--- a/docs/plans/README.md
+++ b/docs/plans/README.md
@@ -49,3 +49,4 @@
| [Bot 视图](2026-10-20-widget-views.md) | Bot 在回答里画视图:固定组件目录的 JSON 蓝图(含图表、输入和本地公式),目录外的放沙箱 html;提问卡回路的泛化 |
| [Side chat(侧边对话)](2026-10-21-btw.md) | 人顺带问一句:侧栏里的常驻对话,以与会话同构的请求回答、不执行工具、不打断、不进模型可见历史;可追问、可开多条;Bot 之间的 `ask_bot` 另行提案 |
| [消息布局和宽度](2026-10-22-message-layout.md) | 气泡 / 平铺两种布局;平铺时 Bot 的话带头像、名字、时间;气泡宽度和平铺正文宽度各用一个滑块,按正文列的百分比调 |
+| [Windows 上手流程](2026-10-26-windows-onboarding.md) | 从下载到第一条回复:下载区和信任说明、安装、窗口先出来的启动页、启动页上的导入、Main Bot 聊天里的模型设置卡(登录或检查过的 key、自动选模型)、修复卡、第一个小时的 Windows 问题、卸载时问一次 |