Skip to content

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

Add the release checklist for real machines to the public docs

Fei24110229601fbbe7
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c7a0efa0..eb3388e7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -72,7 +72,7 @@ Keep one pull request to one issue. Split a large change into several pull reque
1. In a pull request into `dev`, set the version in `ds-bot/package.json` and write the `CHANGELOG.md` section from the Changelog sentences of the merged pull requests.
2. Open a pull request from `dev` into `main` titled `release: vX.Y.Z`. List every `Fixes #<number>` of the release in its description, so that these issues close when it is merged.
-3. Merge it with a merge commit and publish a GitHub release `vX.Y.Z` on `main`. The Release workflow checks that the tag matches the version and is on `main`, runs the checks and publishes the package to npm (a pre-release version under the npm tag `next`). Do not run `npm publish` by hand.
+3. Before you merge it, run the [release checklist](docs/dev/release-checklist.md) (in Chinese) on a real Windows machine, and on macOS when the change touches it, and post the result in the pull request. Merge it with a merge commit and publish a GitHub release `vX.Y.Z` on `main`. The Release workflow checks that the tag matches the version and is on `main`, runs the checks and publishes the package to npm (a pre-release version under the npm tag `next`). Do not run `npm publish` by hand.
4. For a hotfix, start `fix/hot-<name>` from `main`, open the pull request into `main`, release a patch version, then merge `main` into `dev`.
## Set up
diff --git a/CONTRIBUTING.zh.md b/CONTRIBUTING.zh.md
index 003db60b..7cb25169 100644
--- a/CONTRIBUTING.zh.md
+++ b/CONTRIBUTING.zh.md
@@ -72,7 +72,7 @@
1. 向 `dev` 提一个 Pull Request:修改 `ds-bot/package.json` 里的版本号,根据已合并 Pull Request 的 Changelog 句子写 `CHANGELOG.md` 的这一版。
2. 提一个从 `dev` 到 `main` 的 Pull Request,标题为 `release: vX.Y.Z`。在描述里列出这一版所有的 `Fixes #<号>`,合并时这些 Issue 会一起关闭。
-3. 用 merge commit 合并,在 `main` 上发布 GitHub Release `vX.Y.Z`。Release 工作流会检查 tag 与版本号一致、且在 `main` 上,跑完检查后把包发到 npm(预发布版本发到 npm 的 `next` 标签)。不要手动 `npm publish`。
+3. 合并前在 Windows 真机上做一遍[发版前真机检查](docs/dev/release-checklist.md),改动涉及 macOS 时在 macOS 上也做一遍,结果贴在这个 PR 里。用 merge commit 合并,在 `main` 上发布 GitHub Release `vX.Y.Z`。Release 工作流会检查 tag 与版本号一致、且在 `main` 上,跑完检查后把包发到 npm(预发布版本发到 npm 的 `next` 标签)。不要手动 `npm publish`。
4. 热修:从 `main` 切 `fix/hot-<短名>`,向 `main` 提 Pull Request,发一个补丁版本,再把 `main` 合回 `dev`。
## 搭建环境
diff --git a/docs/dev/release-checklist.md b/docs/dev/release-checklist.md
new file mode 100644
index 00000000..b7c25384
--- /dev/null
+++ b/docs/dev/release-checklist.md
@@ -0,0 +1,136 @@
+# 发版前真机检查
+
+CI 只跑单元测试和 Linux 上的测试台。窗口外框、输入法、高 DPI、安装方式、Desktop 和 Web 同时开这些,只有真机能测。每次发版前,维护者在 Windows 上做一遍;改动涉及 macOS 时,在 macOS 上也做一遍。
+
+每一项记「通过 / 不通过 / 备注」。不通过的截图,抄下错误原文,开 Issue。结果贴在 Release PR 的评论里。
+
+## 准备
+
+- Windows 10 / 11 x64,或 macOS(Apple 芯片)。
+- 官方的 DSH Desktop,版本和 README 里写的一致(现在是 `0.2.0-rc.2`)。只从 DeepSeek Harness 官方渠道下载。
+- 要发的包:在 `ds-bot/` 里运行 `npm pack`,得到 `ds-bot-<版本>.tgz`。
+- 一个能用的模型(DeepSeek API key 或账号)。测试里要填的密钥都用**假值**。
+- 想保留现有数据,先备份数据目录:Windows 是 `C:\Users\<用户名>\.dsh\`,macOS 是 `~/.dsh/`。最好用一台没有自己团队数据的机器或账户来测。
+
+## 1. 安装 DSH Desktop
+
+| # | 步骤 | 期望 | 结果 |
+|---|---|---|---|
+| 1.1 | 安装并启动,完成欢迎页 | 主窗口打开,普通对话能收到回复 | |
+
+## 2. 安装插件
+
+每种方式用一个干净的 profile,或者装完一种先卸载再装下一种。
+
+| # | 方式 | 步骤 | 期望 | 结果 |
+|---|---|---|---|---|
+| 2.1 | `.tgz` | 插件 → 添加插件 → 填 `.tgz` 的完整路径(去掉引号)→ 安装 → 立即启用 | 装好;需要时提示重启 | |
+| 2.2 | `.tgz` 的路径 | 用系统「复制为路径 / 拷贝路径名」得到的路径直接填;路径里有空格、中文时也试一次 | 能装 | |
+| 2.3 | npm(发布后) | 填 `ds-bot`;再用「中国大陆镜像源」装一次 | 两种安装源都能装,版本是新版 | |
+| 2.4 | GitHub(发布后,需要 Git) | 填 `github:Fei2411/DeepSeek-Bot#v<版本>&path:/ds-bot` | 能装;没装 Git 时记下错误信息 | |
+| 2.5 | 命令行 | 应用菜单 → 管理 dsh 命令 → 安装;退出 Desktop;新开终端运行 `dsh --version`、`dsh plugin --profile desktop add <tgz 路径>` | 能装;重启 Desktop 后生效 | |
+| 2.6 | 重启 | 完全退出(Windows:托盘图标 → 退出;macOS:⌘Q)再打开 | 团队界面出现 | |
+| 2.7 | 恢复(可选) | 故意装坏一次,看恢复对话框里的「禁用第三方插件」 | 能回到普通 DSH | |
+
+已知的坑:
+
+- 以前用 `link:` 按路径装过、之后又移动或删除了源码目录:DSH 卸载插件时不删 profile 里 `node_modules/ds-bot` 这个失效的链接,再装 `.tgz` 会报没有写入权限(详情里是 `EPERM … rename … node_modules\ds-bot`)。退出 Desktop,只删掉这个链接,再装一次。Windows:`cmd /c rmdir "%USERPROFILE%\.dsh\profiles\desktop\node_modules\ds-bot"`。这是 DSH 的问题,正常安装的用户不会遇到。
+- 2.5 要用 Desktop 自己装的 `dsh`。npm 全局装的 `dsh` 改不了 Desktop 的 profile(`profile "desktop" is managed exclusively by the Electron application`)。两个都装了时,先用 `where.exe dsh`(macOS:`which -a dsh`)看用的是哪一个。
+
+## 3. 窗口外框
+
+| # | 检查 | 期望 | 结果 |
+|---|---|---|---|
+| 3.1 | 窗口按钮(Windows 右上角,macOS 左上角) | 都能点;没有被插件的按钮、地球按钮、抽屉盖住 | |
+| 3.2 | 打开右侧详情抽屉或 Bot 浏览器后再看 3.1 | 按钮仍然能点;面板让出标题栏 | |
+| 3.3 | 拖动区 | 按住顶部空白处能拖动窗口;双击能最大化 / 还原 | |
+| 3.4 | 顶部的标题、搜索、新建按钮 | 能点,不会变成拖动 | |
+| 3.5 | 把窗口拖窄(约 900 px,或分屏) | 侧栏、标题、按钮不重叠;侧栏收起后还能召回 | |
+| 3.6 | 高 DPI(125%、150% 缩放) | 文字和图标清楚,位置不偏 | |
+| 3.7 | 深色主题(设置 → General → Theme) | 外框按钮和插件颜色都看得清 | |
+| 3.8 | 从 Bot 模式切回 Agent 模式,再切回来 | 两边界面都完整,没有残留另一边的样式 | |
+
+## 4. 快捷键和输入
+
+| # | 按键 | 期望 | 结果 |
+|---|---|---|---|
+| 4.1 | 点一下侧栏,然后直接打字 | 打开搜索,打的字在搜索框里 | |
+| 4.2 | 输入框里 `Enter` / `Shift+Enter` | 发送 / 换行 | |
+| 4.3 | 中文输入法打字时按 `Enter` 选字 | 只选字,不发送 | |
+| 4.4 | `Esc` | 关掉对话框、菜单、抽屉 | |
+| 4.5 | 复制粘贴(`Ctrl` / `⌘` + `C` / `V`) | 在对话和输入框里都能用 | |
+| 4.6 | Bot 提问时(问题卡片在输入框上方)按字母键 | 选中对应字母的选项 | |
+| 4.7 | 应用菜单里列出的 DSH 自带快捷键 | 在团队界面里也能用;被插件挡住的记下来 | |
+
+## 5. 团队
+
+| # | 检查 | 期望 | 结果 |
+|---|---|---|---|
+| 5.1 | 第一次打开 | 让你给 Main Bot「Chief」选模型,选好后它打招呼 | |
+| 5.2 | 让 Chief 建一个 Bot | 新 Bot 出现在侧栏,并打招呼 | |
+| 5.3 | 在 Bot 详情里换模型、改思考强度 | 下一条消息用新设置 | |
+| 5.4 | 设置 → General | 主题列表里有 Mono,强调色能选 | |
+| 5.5 | 设置 → Bots → 换一个 Main Bot | 新的 Main Bot 排在侧栏最上面;原来的不再是 Main Bot | |
+| 5.6 | 侧栏右键一个 Bot 或群 → Pin,再 Unpin;把侧栏拖窄再看一次 | 置顶后出现小图钉,取消后消失;窄栏时图钉在头像右上角 | |
+| 5.7 | 设置 → Usage | 有总量、走势、Bot 和模型排行、活跃度;切换时间范围,数字跟着变;点一个 Bot 打开它的页面,返回箭头回到总览 | |
+| 5.8 | Bot 详情 → 记忆 | 能看到、改、删记忆;让 Bot「记住」一件事后这里出现 | |
+
+## 6. 群聊
+
+| # | 检查 | 期望 | 结果 |
+|---|---|---|---|
+| 6.1 | 建一个三人群,设管理员,发一句话 | 管理员回复,需要时把活派给成员 | |
+| 6.2 | `@` 一个成员 | 被 `@` 的成员直接回复 | |
+| 6.3 | 让一个成员干一件要用工具的活 | 群里、侧栏和它自己的聊天里能看到进度;做完后结果回到群里 | |
+| 6.4 | 设置 → Group chats → 点一个群 | 能改名、公告、谁来回答、成员和管理员、工作文件夹、置顶、删除 | |
+| 6.5 | 两个群同时干活 | 各群的消息和进度不串到另一个群 | |
+
+## 7. 能力和连接器
+
+| # | 检查 | 期望 | 结果 |
+|---|---|---|---|
+| 7.1 | 设置 → Capabilities:给一个 Bot 启用一项能力 | 从它下一条消息开始生效 | |
+| 7.2 | 让 Bot 加一个本地 MCP 命令 | 运行前先请你批准 | |
+| 7.3 | 设置 → Connectors → GitHub(用一个只读的测试 token) | 连接后显示账号;断开后状态回到 off | |
+
+## 8. 密钥
+
+| # | 检查 | 期望 | 结果 |
+|---|---|---|---|
+| 8.1 | 在一个 Bot 的私聊里说「用 request_secret 要一个叫 TEST_TOKEN 的密钥」 | 出现密钥卡片;输入内容被遮住 | |
+| 8.2 | 填一个 8 位以上的假值,选「只给这个 Bot」,保存 | 卡片变成已保存;对话里看不到值 | |
+| 8.3 | 让 Bot 在终端里打印这个变量(Windows:`echo $env:DSH_SECRET_TEST_TOKEN`;macOS:`echo $DSH_SECRET_TEST_TOKEN`) | 工具结果里是 `[secret:TEST_TOKEN]`,不是原值 | |
+| 8.4 | 再要一个 `TEST_PIN`,填 4 位假数字,让 Bot 打印 `pin` 加这个变量 | 能保存;结果是 `pin [secret:TEST_PIN]`;别处含这 4 位数字的长数字不受影响 | |
+| 8.5 | 设置 → Secrets | 列出 TEST_TOKEN;能改范围、换值、删除 | |
+| 8.6 | 看数据目录里的 `bot/secrets.json` 的权限(Windows:右键 → 属性 → 安全;macOS:`ls -l`) | 记下哪些用户能读 | |
+
+## 9. Bot 浏览器
+
+| # | 检查 | 期望 | 结果 |
+|---|---|---|---|
+| 9.1 | 私聊标题栏右侧的地球按钮 | 打开这个 Bot 的浏览器面板 | |
+| 9.2 | 地址栏输入一个 https 网页 | 能打开;后退、前进、刷新能用 | |
+| 9.3 | 让 Bot「读一下我打开的页面」 | Bot 用 `read_browser` 读出标题和正文 | |
+| 9.4 | 选中一段文字,再让 Bot 读 | Bot 读到选中的文字 | |
+| 9.5 | 拖面板左边缘 | 能调宽度;关掉再开,宽度保留 | |
+| 9.6 | 切到另一个 Bot | 面板换成那个 Bot 的;登录状态互不相通 | |
+| 9.7 | 退出 Desktop 再开 | 记住的地址还在;登录状态的表现记下来 | |
+
+## 10. Desktop 和 Web 同时开
+
+| # | 步骤 | 期望 | 结果 |
+|---|---|---|---|
+| 10.1 | Desktop 开着;另开终端运行 `npx @deepseek-ai/dsh@<DSH 版本> plugin --profile web add <tgz 路径>`,再 `npx @deepseek-ai/dsh@<DSH 版本> web` | Web 能打开 | |
+| 10.2 | 在 Web 里看团队 | 同一个团队;Bot 列表上方有只读说明 | |
+| 10.3 | 在 Web 里改一个 Bot 的名字 | 被拒绝,提示 open in another dsh | |
+| 10.4 | 在 Desktop 里改名 | Web 几秒内跟着变 | |
+| 10.5 | 退出 Desktop,在 Web 里再改名 | Web 接手,改名成功 | |
+| 10.6 | 重新打开 Desktop | Desktop 变成只读,显示说明 | |
+
+## 11. 卸载和升级
+
+| # | 步骤 | 期望 | 结果 |
+|---|---|---|---|
+| 11.1 | 插件页卸载 `ds-bot`,重启 | 回到普通 DSH;数据目录里的 `bot/` 还在 | |
+| 11.2 | 重新安装 | 原来的团队、对话、记忆、密钥都在 | |
+| 11.3 | 从上一个发布版本升级到这一版 | 团队、主题、颜色、浏览器宽度和标签页都保留 | |