A team of long-lived bots for DeepSeek Harness, with main bots, bot-to-bot messages and group chats.
参与 DS Bot 开发
English | 中文
感谢参与。本文说明团队怎么协作、怎么搭环境、怎么测试改动,以及改动必须遵守的规则。插件做什么、用户怎么安装,见 README.zh.md。
谁可以提 Pull Request
本仓库的协作者直接在这里推分支,向 dev 提 Pull Request(见协作方式)。目前只有协作者能提 Pull Request。如果你不是协作者,发现 bug 请开 Issue(见报告问题),提问或建议请到 Discussions。
最重要的规则
- 基于 DSH 构建,不改 DSH。 Bot 功能是 DSH 插件:只用 DSH 有文档的插件接口(Cordis 服务、插件客户端入口、profile patch)。桌面应用只通过 DSH 有文档的入口启动 DSH(
@deepseek-ai/dsh/profile-boot、dsh命令)。不修改 DeepSeek Harness,不依赖 DSH 安装目录里的文件。功能需要 DSH 没有提供的能力时,先在这里开 Issue;修复可能应该放在 DSH 里。 - Bot 的工作跑在 DSH Session 里。 Bot 的身份不变,工作跑在 DSH Session 里:私聊一条、每个群各一条,上下文快满时换一条新的。每个回合都走 DSH 正常的 agent 循环、工具和模型路由。不要另加一套 agent 运行时。
- 任何地方都不放真实密钥。 不要提交 API key、token、cookie、
DSH_HOME目录、日志,或带个人信息的截图。测试和测试台用脚本化的模拟模型,不需要密钥。 - 只用原创素材。 不要从其他产品或网站复制代码、文字、图标、logo 或其他图形。唯一例外是与 Apache 2.0 兼容许可的代码:注明出处,并把它的声明加进
NOTICE文件。 - 每个改动都要测试。 每个改动都要跑单元测试和客户端检查(见测试改动)。
协作方式
团队里谁都可以做任何工作:分诊、修 bug、做功能、改界面、写文档。只有一部分决定归维护者:产品方向、改动已定的设计、这些规则、发版和架构。需要这类决定的 Issue 和 Pull Request 带 maintainer 标签;开工前先等维护者回复。DS Bot 要做成什么,见 docs/vision.zh.md;已定的设计在 docs/plans/。拿不准是 bug 还是设计如此时,先查这两处,再在 Issue 里问。
分支
| 分支 | 用途 | 谁来合并 |
|---|---|---|
dev |
集成分支。所有修复和功能先进这里 | 所有协作者,CI 通过即可 |
main |
只放已发版的代码。维护者发版时把 dev 合进来,或合入热修 |
维护者 |
fix/<Issue 号>-<短名>、feat/<Issue 号>-<短名>、docs/<短名>、chore/<短名> |
你的工作分支。从最新的 dev 切出 |
— |
- 分支名不要以
dev/开头。有dev分支时,Git 建不了dev/<名字>。 - 同步分支用
scripts/merge-dev.sh:合入origin/dev,生成文件ds-bot/client.js冲突时取 dev 的版本再重新生成(热修分支用git merge main)。已推送的分支不要 rebase,也不要强推。 - 默认分支是
main,所以 GitHub 新建 Pull Request 时默认的 base 是main。请改成dev。
Issue
- 分诊。 给每个新 Issue 打类型、优先级和领域标签(见标签)。每个 Issue 只有一个优先级标签。具体步骤和列出待分诊 Issue 的脚本见 .agents/skills/issue-triage/,AI 也可以照着做。
- 是提问(怎么装、怎么用):选 Convert to discussion,转到 Q&A 分类。
- 信息不够,找不到原因:加
needs-info,写清楚还缺什么。说明 14 天没有回复就关闭。 - 原因在 DSH 或其他插件:加
upstream,并链接到应该处理它的地方。 - 和已有的 Open Issue 相同:加
duplicate,链接原 Issue,关闭这一条。
- 认领。 开工前把 Issue 指派(Assign)给自己,并在 Issue 里写「我来做」,避免两个人做同一件事。已经有人认领的 Issue 不要抢;想接手先在 Issue 里问。
- 功能。 新想法先在 Discussions(Ideas)里讨论。维护者认可后,再开成带
enhancement标签的 Issue。做功能前,先在 Issue 里写几句打算怎么做。大功能在同一个 Pull Request 里附上设计说明docs/plans/<日期>-<主题>.md。 - 有证据才关。 关闭 Issue 时,附上修复它的 Pull Request 或提交、它重复的 Issue,或不修的原因。评论用 Issue 本身的语言。
标签
| 维度 | 标签 |
|---|---|
| 类型 | bug · enhancement · documentation |
| 优先级 | P0 崩溃、丢数据或无法使用 · P1 影响日常使用 · P2 一般缺陷或功能 · P3 建议或窄场景 |
| 领域 | area/host 服务端(index.js、src/host/)· area/client 界面(src/client/)· area/group 群聊、@ 提及、Bot 之间的消息 · area/memory 记忆、对话分段、上下文 · area/browser Bot 浏览器、读网页、网页搜索 · area/build CI、发版、脚本、测试台 · area/docs |
| 流程 | maintainer 等维护者 · needs-info 等报告人 · upstream 原因在 DSH 或其他插件 · duplicate · auto-found 自动测试发现 |
跨多个领域或不属于任何领域的 Issue,不打领域标签。
Pull Request
- 向
dev提 Pull Request,按模板填写。用Fixes #<号>关联 Issue;修 bug 的 PR 一定要写明修的是哪个 bug。从 fork 提 Pull Request 时,请保持勾选 Allow edits from maintainers,方便维护者在合并前解决冲突或做小调整。 - 在模板的 Changelog 一栏写一句用户能看到的变化,没有就写「无」。不要改
CHANGELOG.md:维护者发版时根据这些句子统一写。 - CI 通过后,自己用 Create a merge commit 合并,然后删除分支。不强制审查;想让人看一眼,在 Pull Request 里 @ 队友。
- 合进
dev的修复不会关闭对应的 Issue:Fixes #<号>只在合入默认分支时生效。Issue 会一直开着,直到发版,意思是「已在dev修复,尚未发版」。
一个 Pull Request 只对应一个 Issue。大改动拆成多个 Pull Request。
合并冲突
ds-bot/client.js:不要手工解决。先解决ds-bot/src/client/里的冲突,再在ds-bot/里运行npm run build,提交新生成的client.js。CHANGELOG.md:Pull Request 不改它,所以不应该冲突。如果冲突了,两边都保留。
发版(维护者)
- 向
dev提一个 Pull Request:修改ds-bot/package.json里的版本号,根据已合并 Pull Request 的 Changelog 句子写CHANGELOG.md的这一版。 - 提一个从
dev到main的 Pull Request,标题为release: vX.Y.Z。在描述里列出这一版所有的Fixes #<号>,合并时这些 Issue 会一起关闭。 - 合并前在 Windows 真机上做一遍发版前真机检查,改动涉及 macOS 时在 macOS 上也做一遍,结果贴在这个 PR 里。用 merge commit 合并,在
main上发布 GitHub ReleasevX.Y.Z,发布时不勾「Set as the latest release」:安装包、SHA256SUMS.txt和下载表都传完后,工作流会自己把它标为最新。Release 工作流会检查 tag 与版本号一致、且在main上,跑完检查后把包发到 npm(预发布版本发到 npm 的next标签)。不要手动npm publish。 - 热修:从
main切fix/hot-<短名>,向main提 Pull Request,发一个补丁版本,再把main合回dev。
搭建环境
需要:
- Node.js
22.19或更高(或24及以上)。 - Git。
- 仅测试台需要:pnpm
11,以及插件测试所用 DSH 版本的 DeepSeek Harness 源码。
git clone https://github.com/Fei2411/DS-Bot.git ds-bot-repo
cd ds-bot-repo/ds-bot
# 插件自己的构建工具(只有 esbuild)。
npm ci
# 单元测试和 lint 要加载的 DSH 包,从 npm 装进 dev/harness/。
npm run harness
测试台需要把 DeepSeek Harness 源码放在插件目录旁边(这个目录被 Git 忽略):
cd ..
git clone https://github.com/deepseek-ai/deepseek-harness.git
git -C deepseek-harness checkout dsh-v0.2.2-rc.1
(cd deepseek-harness && pnpm install)
如果 DeepSeek Harness 源码放在别处,把 DSH_HARNESS 设为它的路径。DSH_HARNESS 也会代替 dev/harness/,供单元测试和 lint 使用。
@deepseek-ai/* 包是 peer 依赖:真实安装时由 DSH 的 profile 提供。ds-bot/.npmrc 阻止 npm 把它们装进插件目录。
目录结构
| 路径 | 内容 |
|---|---|
ds-bot/index.js、ds-bot/src/host/ |
服务端:Bot 名册与存储、工具、回合与投递、群聊、对话分段与搜索索引、图片、Bot 浏览器桥接、api/bot 通道 |
ds-bot/src/client/ |
浏览器端:侧栏、聊天、面板与对话框、主题、角色、Bot 浏览器面板 |
ds-bot/client.js |
由 scripts/build-client.mjs 从 src/client/ 生成。它被提交进仓库,这样用 Git 安装时不需要构建 |
ds-bot/web-search.js |
auto 网页搜索提供方。不依赖 Bot 团队代码 |
ds-bot/cordis.patch.yml |
插件带的 profile patch |
ds-bot/test/ |
单元测试和测试数据 |
ds-bot/dev/ |
单元测试用的 DSH 包(harness/)、模拟模型、测试台、冒烟测试、角色生成器、Linux 上的 Desktop 脚本,以及两个用真实模型的工具:上下文管家评测和日志转发 |
测试改动
在 ds-bot/ 里运行:
npm run build # src/client → client.js
npm test # 单元测试;client.js 过期时也会失败
node scripts/build-client.mjs --check # client.js 与 src/client 一致
npm run lint # oxlint
CI 在每个 Pull Request 上,在 Linux 和 Windows 上跑同样的三项检查。它还会扫描入库的文件,查找密钥、token、个人路径和邮箱,以及只应留在本地的材料。想自己扫描,在仓库根目录运行:
mkdir -p /tmp/ds-bot-tree && git archive HEAD | tar -x -C /tmp/ds-bot-tree && node scripts/scan.mjs /tmp/ds-bot-tree
「must fix」的结果会让 CI 失败;「can stay」的结果仅供阅读。分支规则只要求一项检查 Test result,所有检查都通过它才通过。
改服务端(index.js、src/host/)时,还要跑冒烟测试。它启动模拟模型和一个链接到你本地插件的 DSH Web,走一遍主要流程(Bot、群聊、对话分段、压缩、设置)。CONTEXT_WINDOW 和 CHECK_RATIO 让模拟模型的上下文窗口变小,几条长回复就能到达检查线:
CONTEXT_WINDOW=100000 CHECK_RATIO=0.45 dev/bench.sh smoke 3096 8796 reset && node dev/smoke.mjs smoke 3096
dev/bench.sh smoke 3096 8796 stop
想手动试用插件,启动一个测试台,打开它打印的地址:
dev/bench.sh dev 3081 8771 reset # 模拟模型 + DSH Web;数据在 ../.dsh-test-dev
模拟模型只回应一组固定命令,所以测试台不花 token。命令列在 dev/mock-llm.mjs 开头。测试台数据放在插件目录旁边的 .dsh-test-<名字>/,不会碰你自己的 ~/.dsh。
改上下文管家或它的提示词(src/host/steward.js)时,还要用真实模型检查。dev/steward-eval.mjs 在固定的对话结尾上跑它的决策,dev/llm-tap.mjs 记录真实测试台的每次调用。两者都花 token,用法写在文件开头。
改 Bot 浏览器时,要在 DSH Desktop 里检查。在 Linux 上,dev/desktop-linux/ 里的脚本用 Xvfb 运行 DSH Desktop;每个脚本的用法写在开头。
写改动
- 一个改动只做一件事。
- 不要手改
client.js。改src/client/,运行npm run build,两者一起提交。 - 在
src/client/里,颜色用--bt-*变量,圆角只用 4、6、8、10、12、16、18、20、22、999px 和 50% 这几档,弹簧用motion.js里的。有单元测试检查这三项。测试之前就写成的地方列在test/style-debt.json里,这份清单只减不增。改掉一处后,运行node scripts/style-debt.mjs --write更新清单。 - 跟随改动周围代码的风格。只有当代码本身看不出原因时才写注释。
- 提交说明用英文。标题简短,用祈使句(如 "Keep group replies visible"),在正文里写原因。
- 提交的作者是做出改动的人。用 AI 工具辅助时,不要把它加为作者,也不要加
Co-authored-by行;在工具里关掉这个设置。 - 不要改 CHANGELOG.md。把用户能看到的变化写在 Pull Request 的 Changelog 一栏。
报告问题
最简单的方式是在 DS Bot 里:打开 设置 → 反馈,写下发生了什么,选 在 GitHub 上报告。它会新开一个 Issue,DS Bot 和 DSH 版本、系统、模型和最近的错误都已填好。复制 会把同样的内容放进剪贴板,下载 会保存完整的错误日志(<DSH_HOME>/bot/logs/diagnostics.jsonl)。
手动开 Issue 时,请写上:
- DSH 版本(DSH Desktop 或
@deepseek-ai/dsh)、操作系统,以及用的是 DSH Desktop 还是 DSH Web。 - DS Bot 的安装方式(npm、发布文件、Git 地址或命令行)和版本。
- 你做了什么、期望什么、实际发生了什么,报错请贴原文。
- 一张整窗截图,包含聊天和报错。
- 能让问题再次出现的步骤。
DS Bot 会从诊断信息里去掉 API key、token、保存的密钥和你的用户目录。发出前请读一遍,并去掉截图里的个人信息。
安全问题不要开公开 Issue。请在仓库的 Security 页使用 Report a vulnerability。
Issue 只用来报告 bug。提问、想法和功能建议请发到 Discussions。维护者认可的想法会开成 Issue。
许可
DS Bot 使用 Apache License 2.0。提交贡献即表示你同意按同一许可授权,如该许可第 5 条所述。