Skip to content

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

Publish the vision and the first decided designs

Fei2411d9585199d952
diff --git a/AGENTS.md b/AGENTS.md
index 143e17c5..da9d3377 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -50,6 +50,7 @@ The full workflow is in [CONTRIBUTING.md](CONTRIBUTING.md#how-we-work). The part
- Bring a branch up to date with `git merge dev`. Never rebase a pushed branch and never force-push.
- Fill in the pull request template. Link the issue with `Fixes #<number>`; a bug fix names the bug it fixes. Write the user-visible change in the Changelog field, and do not edit `CHANGELOG.md`.
- Do not start work on an issue or pull request with the `maintainer` label; it waits for the maintainer. Do not take an issue that someone else is assigned to.
+- Before you change behavior, read the design for it in `docs/plans/` (and `docs/vision.md`). A change to a decided design needs the maintainer; a new large feature adds its design note to the same pull request.
- Do not close an issue without evidence: the pull request or commit that fixed it, the issue it duplicates, or the reason it will not be fixed.
## Layout
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c25e1031..b9ea203c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -18,7 +18,7 @@ Collaborators of this repository push branches here and open pull requests into
## How we work
-Anyone on the team can do any kind of work: triage, bug fixes, features, the interface, docs. Only some decisions belong to the maintainer: the direction of the product, changes to a design that is already decided, these rules, releases and the architecture. Issues and pull requests that need such a decision carry the `maintainer` label; wait for the maintainer's answer before you start on them. When you are not sure whether something is a bug or works as designed, ask in the issue.
+Anyone on the team can do any kind of work: triage, bug fixes, features, the interface, docs. Only some decisions belong to the maintainer: the direction of the product, changes to a design that is already decided, these rules, releases and the architecture. Issues and pull requests that need such a decision carry the `maintainer` label; wait for the maintainer's answer before you start on them. What DS Bot is meant to be is in [docs/vision.md](docs/vision.md); the decided designs are in [docs/plans/](docs/plans/) (in Chinese). When you are not sure whether something is a bug or works as designed, read them first, then ask in the issue.
### Branches
diff --git a/CONTRIBUTING.zh.md b/CONTRIBUTING.zh.md
index ed78f644..72e28ccd 100644
--- a/CONTRIBUTING.zh.md
+++ b/CONTRIBUTING.zh.md
@@ -18,7 +18,7 @@
## 协作方式
-团队里谁都可以做任何工作:分诊、修 bug、做功能、改界面、写文档。只有一部分决定归维护者:产品方向、改动已定的设计、这些规则、发版和架构。需要这类决定的 Issue 和 Pull Request 带 `maintainer` 标签;开工前先等维护者回复。拿不准是 bug 还是设计如此时,在 Issue 里问。
+团队里谁都可以做任何工作:分诊、修 bug、做功能、改界面、写文档。只有一部分决定归维护者:产品方向、改动已定的设计、这些规则、发版和架构。需要这类决定的 Issue 和 Pull Request 带 `maintainer` 标签;开工前先等维护者回复。DS Bot 要做成什么,见 [docs/vision.zh.md](docs/vision.zh.md);已定的设计在 [docs/plans/](docs/plans/)。拿不准是 bug 还是设计如此时,先查这两处,再在 Issue 里问。
### 分支
diff --git a/docs/plans/2026-10-07-group-chat.md b/docs/plans/2026-10-07-group-chat.md
new file mode 100644
index 00000000..3edaf541
--- /dev/null
+++ b/docs/plans/2026-10-07-group-chat.md
@@ -0,0 +1,78 @@
+# 群聊
+
+- 日期:2026-10-07 定下按顺序发言和群管理;之后多次调整,见文末「变更」
+- 相关:#129,PR #19、PR #175、PR #79、PR #180
+
+## 为什么
+
+群聊是多个 Bot 一起工作的主要方式,有两个根本难题:
+
+1. **协调。** 早期让成员并行写、发出前再检查新消息,连报数都会乱:模型会沿用乱掉的数字硬发。把排序交给模型做不好。结论是 **群里一次只有一个人说话**,每个成员开口前读到的都是最新的群。
+2. **成本。** 每叫一个成员,就要带上它整个会话的上下文跑一次模型。成本随发言人数线性增长,系数很大。所以默认少叫人:普通消息先给管理员,由它决定点谁。
+
+另外,成员在群里接到长任务时,不能让用户面对一个静止的页面(「黑盒」),也不能让做完的结果丢掉。
+
+## 已定的行为
+
+### 谁来回答
+
+- 群有两种回答方式:
+ - **管理员先答**(新群默认):没有 `@` 的普通消息只给管理员,管理员用 `@名字` 叫其他成员。
+ - **全员轮流**:普通消息由每个成员按顺序回答,管理员第一个。
+ - 没有管理员的群按「全员轮流」回答。
+- `@名字` 只叫被点名的成员。`@all`、`@everyone`、`@所有人`、`@全体` 叫全员;成员回复里的这几个词只有管理员说才算,防止成员互相叫起一大片。
+- 成员按顺序发言:上一个人发完(或跳过)下一个人才开始,每个人看到本轮之前所有人的发言和自己的位置。
+- 回复里 `@` 了别人,被点的人接着说(接力)。每人每轮、每轮总数都有上限,管理员叫人的上限更高。
+- 每个成员可以跳过(`[PASS]`),不必每轮都说话。
+
+### 提及
+
+- 只有 `@名字` 算提及,也只有它渲染成带头像的链接;不带 `@` 的名字是普通文字。客户端和服务端用同一条规则(`ds-bot/src/shared/mentions.js`)。
+- `@` 前面是字母、数字、`_`、`.`(邮箱等地址)不算;名字后面紧跟字母、数字、`_`、`-`(更长的词)不算;代码、链接、引用里的不算。名字不分大小写,长的名字优先匹配。
+- `all`、`everyone`、`所有人`、`全体` 不能用作 Bot 名字。
+- 输入框的 `@` 菜单把 Bot 排在最前(群里列成员和「所有人」,私聊列其他 Bot)。引用其他对话放在「+」里。
+
+### Bot 发起的轮次和上限
+
+- Main Bot 能往任何群发言,管理员能往自己的群发言(`post_to_group`),发言人自己不参与回答。
+- 用户在群里再次说话之前,Bot 在一个群里最多连续发起 3 轮。
+- 全团队的 Bot 消息(`message_bot` 和群发言)在没有外部输入(用户发言、问题卡片的回答、定时任务)时最多 40 条;超过后这两个工具失败,并让 Bot 向用户汇报。Bot 被告知不要发感谢或确认,也不要回复一条回复。
+
+### 干活中的进度和迟到的回复
+
+- 成员在群里接到需要干活的任务时,第一次调用工具后 15 秒仍在干活,本轮就继续往下走,不再等它。
+- 干活过程中,它说的第一句话和带 `@` 的话立刻发到群里;间隔不到 30 秒的几句合并成一条发。最后的结果由派活的 Bot(管理员或叫它的成员)接话。
+- 本轮结束后才完成的回复照样发进群。用户再次发言之前,群里最多为这类迟到的结果再接 10 次话。
+- 回答超时只在成员的会话完全没有动静时计时(4 分钟)。没及时回应、需要审批的成员各在群里留一行淡色事件,让用户知道发生了什么。
+
+### 审批与状态
+
+- 群里成员的审批请求(例如提权)由 DS Bot 接到群里:输入框上方的状态胶囊列出正在忙的成员,等审批的排在前面;点开群详情可以「允许一次」或「拒绝」。需要审批的成员立刻让出发言。
+- 群的工作文件夹和统一权限是群级设置,见 [角色与权限](2026-10-07-roles-and-permissions.md)。
+
+### 群的设置
+
+- 用户新建群且没有附第一句话时,管理员先发一句问候,问这个群要做什么。Main Bot 用工具建群时不发。
+- 群公告(最多 2000 字)放进每次发言的提示里。成员最多 12 个,群名不能重复(最长 60 字),没起名的群显示成员名。
+- Main Bot 能看到所有群;其他 Bot 只能看到自己所在的群。
+- `message_bot` 发来的消息只进 Bot 自己的私聊;它在群里的工作不受影响。
+
+## 不做什么
+
+- 不并行发言后再检查冲突。
+- 不做「一直轮到没人说话为止」的多轮讨论:每条消息都要多跑一整轮跳过。需要讨论时用 `@` 接力。
+- 不让成员把长任务一直占着发言位:长活在后台做完再报到群里。
+
+## 已知限制
+
+- PTC 预设下建的旧群,一轮最长约 10 分钟([DSH 让步总账](2026-10-13-dsh-concessions.md) C1)。
+- DSH 的「对话」引用组仍会出现在 `@` 菜单里,群里打 `@名字` 直接回车可能选中它(C3)。
+
+## 变更
+
+- 2026-10-08:普通消息默认先给管理员(少叫人),群有自己的 Session。
+- 2026-10-10:提及只认 `@名字`;新建群管理员先问候。
+- 2026-10-11:`@` 菜单 Bot 优先,引用对话移到「+」(PR #19)。
+- 2026-10-12:群里的审批、状态胶囊、超时只算无动静的时间、迟到回复补发(PR #79)。
+- 2026-10-13:全团队 Bot 消息上限 40 条(#129)。
+- 2026-10-14:干活中的进度发到群里,结果由派活的 Bot 接话(PR #175);群的统一权限(PR #180)。
diff --git a/docs/plans/2026-10-07-roles-and-permissions.md b/docs/plans/2026-10-07-roles-and-permissions.md
new file mode 100644
index 00000000..d943d1c4
--- /dev/null
+++ b/docs/plans/2026-10-07-roles-and-permissions.md
@@ -0,0 +1,50 @@
+# 角色与权限
+
+- 日期:2026-10-07 定下三级角色;2026-10-11 加 Bot 的权限预设;2026-10-14 加群的统一权限
+- 相关:PR #180(群的统一权限),PR #154(每个 Bot 能改自己的设置)
+
+## 为什么
+
+团队要能自己组织起来:Main Bot 负责建 Bot、建群、调度,群管理员管自己的群,其他 Bot 专心做事。同时,越权的动作(删 Bot、改别人的设置、放开沙盒权限)必须有明确的边界,否则一个 Bot 的错误判断会波及整个团队。
+
+这里有两层权限,互相独立:
+
+- **角色权限**:谁能管理 Bot、群和团队记忆。由 DS Bot 自己检查。
+- **沙盒权限**:一个 Bot 的工具能碰到什么(读文件、改文件、跑命令)。用 DSH 提供的权限预设,由 DSH 执行。
+
+## 已定的行为
+
+### 角色权限
+
+| 谁 | 范围 | 能做什么 |
+|---|---|---|
+| 用户 | 全部 | 一切操作,包括设置、取消 Main Bot,设置 Bot 和群的沙盒权限 |
+| Main Bot | 整个团队 | 建 Bot(`create_bot`)、改任何 Bot(`update_bot`)、停止别的 Bot 正在跑的回合(`stop_bot`);建群、改任何群、删群、往任何群发言;写团队记忆,按用户要求读写某个 Bot 的记忆;给任何 Bot 挂、摘能力 |
+| 群管理员 | 自己管的群 | 改自己的群(改名、公告、成员、管理员、回答方式),往自己的群发言,写团队记忆。不能删群,不能改群的工作文件夹 |
+| 普通 Bot | 自己 | 改自己的名字、角色、颜色、模型、工作文件夹、指令;给自己挂、摘能力;在群里发言、用 `@` 点名;用 `message_bot` 给任何 Bot 发消息 |
+
+- 可以有多个 Main Bot,至少保留一个。只有用户能设置或取消 Main Bot。
+- Main Bot 不能直接删除,要先取消它的 Main Bot 角色。
+- 每个群最多一个管理员,必须是群成员。管理员不能直接退群,也不能把群设成没有管理员,要先移交。Main Bot 建群时默认自己当管理员。删除一个 Bot 时,它管的群变成没有管理员。
+- 越权的工具调用会被拒绝,并告诉 Bot 该怎么办(例如「只有 Main Bot 能创建 Bot,请让 Main Bot 来做」),让 Bot 能自己改道。
+
+### 沙盒权限
+
+- 每个 Bot 有自己的权限预设(DSH 提供的:仅可查看 / 工作区内修改 / 完全权限),存在 Bot 上,用于它的私聊、它所在的群,以及之后的新对话段。没设时用 DSH 的默认预设。
+- **只有用户能设**。Bot 发起的修改一律拒绝,`update_bot` 和 `update_group` 都没有这个参数。
+- 选「完全权限」要再确认一次,界面上这几个字一直是红色。
+- 群可以设一个统一的预设(「全员统一」),覆盖成员自己的:立即作用于所有成员在这个群里的会话,之后成员在群里新开的会话、群里换段后的新段也用它。成员改自己的预设,不影响设了统一预设的群。关掉后,每个成员回到自己的预设。
+
+## 不做什么
+
+- 不做细粒度的角色权限表(谁能 `@` 全员、谁能读群聊等),界面上也不展示一张权限矩阵。
+- 不让 Bot 提升自己或别人的沙盒权限。
+- 群的统一权限不能交给 DSH 的自动审核(Auto review 只针对单个会话)。
+
+## 已知限制
+
+- DSH 的「+」和「/」菜单里仍有权限入口,用户在 Bot 会话里用它改了,会绕过 Bot 上的设置(见 [DSH 让步总账](2026-10-13-dsh-concessions.md) C4)。
+
+## 变更
+
+- 2026-10-14:群的统一权限,PR #180。
diff --git a/docs/plans/2026-10-13-dsh-concessions.md b/docs/plans/2026-10-13-dsh-concessions.md
new file mode 100644
index 00000000..ae427187
--- /dev/null
+++ b/docs/plans/2026-10-13-dsh-concessions.md
@@ -0,0 +1,33 @@
+# DSH 让步总账
+
+- 日期:2026-10-13 建立,之后持续追加
+- 相关:#37、#38、#105、#112、#116、#118、#123、#125、#127、#128、#129、#133,PR #134、#135、#140、#141、#161、#168、#169
+
+## 为什么
+
+DS Bot 是 DSH 插件,只能用 DSH 公开的接口。有些地方 DSH 的设计和 Bot 不合:全局注册、没有按会话过滤、预设是全局的、界面结构不对插件开放。原则是 **以 Bot 的正确行为为准,不为兼容 DSH 的特定模式或限制无限增加复杂度**。不得不让步的地方记在这里,等桌面应用自己掌握 profile 和界面之后逐条清理。
+
+判断一个 Issue 是 DS Bot 的 bug 还是 DSH 的限制时,先看这张表。属于 DSH 的,加 `upstream` 标签。
+
+## 总账
+
+| # | 日期 | 相关 | DSH 的限制 | 现在的做法 | 代价 | 桌面应用之后 |
+|---|---|---|---|---|---|---|
+| C1 | 10-13 | #37 #38 #105 #123,PR #134 #135 #168 | PTC 预设下模型只能直接调用 `run_code`,真正的工具在子调用里;一次程序运行最长约 10 分钟 | 工具展示和服务端都遍历子调用。新会话固定用 standard 预设;旧 PTC 群会话的中继包一层 `run_code` | 每个工具相关功能都要同时处理顶层调用和子调用;PTC 下群里一轮超过 10 分钟会被中止;模拟模型和冒烟测试不覆盖 PTC | 固定用 standard 预设,删掉子调用兼容代码 |
+| C2 | 10-13 | #133,PR #168 | 命令全局注册,不能按会话过滤或拦截 | Bot 会话一律不支持 goal:去掉 goal 工具,goal 一创建就停下并说明,界面不显示 goal 轮次 | `/goal` 仍出现在命令菜单里,但用不了 | 不提供 `/goal`;需要长任务自主推进时,做成 Bot 自己的功能,并能跨段保留 |
+| C3 | 10-11 | PR #19 | `@` 引用源全局注册,不能在 Bot 会话里隐藏 | `@` 菜单把 Bot 组排在最前;引用对话放到「+」 | 群聊里打 `@名字` 直接回车,可能选中 DSH「对话」组的第一项 | `@` 只列 Bot |
+| C4 | 10-10 | — | DSH 不提供删除指令菜单项的接口 | 「+」和「/」里仍有计划、权限、模型、压缩等 Bot 不该用的入口 | Bot 的设置可能被绕过 | 自己画菜单 |
+| C5 | 10-13 | #128,PR #161 | patch 没有条件语法;网页搜索选择器在配置的 id 没注册时不回落,也没有优先级 | 只写文档:关掉 `web-search-auto` 时必须同时改 `web.searchProvider` | 只关这一行,所有会话的 `web_search` 都会失效 | profile 里直接写 `searchProvider`,和 provider 一起管理 |
+| C6 | 10-13 | #125 | MCP 客户端把服务器响应体写进日志,插件没法脱敏 | 文档建议把密钥放在 headers 里 | 服务器回显 URL 时,密钥可能进 DSH 日志 | 控制日志出口,或向 DSH 提需求 |
+| C7 | 10-13 | #127,PR #169 | 其他插件的 CSS 能覆盖 ds-bot;ds-bot 依赖 DSH 的私有类名 | 最小修正:几处布局属性加 `!important`,占位文字改用 `::before` | DSH 每次改结构或换皮都可能弄坏布局 | 用自己的组件,不再覆盖 DSH 的 DOM |
+| C8 | 10-13 | #118 #123 | 插槽不允许重复声明或渲染没声明的子节点 | 工具展示只补了 present,其他插件的工具视图没有通用组合 | 其他插件的工具视图在 Bot 聊天里不显示 | 自己渲染全部工具 |
+| C9 | 10-13 | #116,PR #140 | 显式默认模型不可用时,`defaultModel()` 返回模型目录第一项 | 接受这个行为 | 可能落到另一个服务商的模型上 | 自己管理候选模型和回落顺序 |
+| C10 | 10-13 | #112,PR #141 | profile 里禁用 bot 行后插件不加载,插件内部无法诊断 | 只写排障文档 | 用户只能手动排查 | 启动器在加载插件前诊断 |
+| C11 | 10-13 | #129 | 模型流卡死时没有看门狗,回合不会结束 | 只做背压:一个 Bot 最多积压 10 条未读请求 | 卡死的 Bot 要用户手动停止 | 监控回合,提供恢复入口 |
+| C12 | 10-13 | #38 | 超长工具结果会被截断(默认约 12500 tokens) | 未处理 | 超长的群轮次,刷新后回复可能不见 | 插件侧可改为只存摘要和 id;应用有自己的存储 |
+| C13 | 10-14 | #37,PR #168 | 预设是全局或按会话选的,插件不能只给 Bot 会话换掉 PTC 的工具展示、保留用户其余配置 | DS Bot 新建的会话一律用 standard 预设,用户给 DSH 选的预设(包括自定义组合)不用于 Bot | 用户自定义预设里的插件不会出现在 Bot 里 | 每个 Bot 可选自己的 harness(愿景第 9 条),默认 standard |
+
+## 记录规则
+
+- 新的让步追加到表尾,写明日期、相关 Issue/PR、DSH 的限制、现在的做法、代价、桌面应用之后怎么处理。
+- 处理完的条目不删,在「现在的做法」里写「已处理」、日期和 PR。
diff --git a/docs/plans/README.md b/docs/plans/README.md
new file mode 100644
index 00000000..84f18f11
--- /dev/null
+++ b/docs/plans/README.md
@@ -0,0 +1,41 @@
+# docs/plans:已定的设计
+
+这里收录 DS Bot 已经定下的设计:为什么这样做、已定的行为、不做什么、已知限制。拿不准一个现象是 bug 还是设计如此时,先查这里和 [愿景](../vision.zh.md);这里没写的,在 Issue 里问。
+
+设计文档用中文写。
+
+## 什么时候写
+
+- **大功能**:在同一个 Pull Request 里附一份 `docs/plans/<日期>-<主题>.md`,和代码一起审、一起合。
+- **改动已定的设计**:先在 Issue 里和维护者确认(带 `maintainer` 标签),合并时同步改对应的文档。
+- **修 bug**:不用写。
+
+## 格式
+
+```markdown
+# 标题
+
+- 日期:设计定下的日期(之后的修改在文末「变更」里追加)
+- 相关:Issue / PR 编号
+
+## 为什么
+要解决的问题,以及当时的取舍。
+
+## 已定的行为
+可以验证的规则。写现在的行为,不写过程。
+
+## 不做什么
+
+## 已知限制
+
+## 变更
+- 日期:改了什么,对应的 PR。
+```
+
+## 目录
+
+| 文档 | 内容 |
+|---|---|
+| [DSH 让步总账](2026-10-13-dsh-concessions.md) | 因 DSH 本身的限制而做的妥协,以及桌面应用之后怎么处理。判断「是 DS Bot 的 bug 还是 DSH 的限制」先看这里 |
+| [角色与权限](2026-10-07-roles-and-permissions.md) | 用户、Main Bot、群管理员、普通 Bot 各能做什么;Bot 的权限预设和群的统一权限 |
+| [群聊](2026-10-07-group-chat.md) | 谁来回答、按顺序发言、@ 提及、轮数上限、干活中的进度和迟到的回复、审批 |
diff --git a/docs/vision.md b/docs/vision.md
new file mode 100644
index 00000000..2e2f6ef2
--- /dev/null
+++ b/docs/vision.md
@@ -0,0 +1,48 @@
+# The vision of DS Bot
+
+English | [中文](vision.zh.md)
+
+This file says what DS Bot is meant to be, why, and what it does not do. For how to use it, see the [README](../README.md); for the designs that are decided, see [docs/plans/](plans/) (written in Chinese); for how to take part, see [CONTRIBUTING](../CONTRIBUTING.md).
+
+## What DS Bot is
+
+DS Bot is a team of long-lived Bots, built on [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH). It is open source under the Apache 2.0 license. The user does not chat with one assistant but leads a team with clear roles: one or more Main Bots organize the work, the other Bots each do their own part and talk to each other, and the user can see at any time who is doing what.
+
+## Two forms
+
+| Form | What it is |
+|---|---|
+| The `ds-bot` plugin | A standard DSH plugin for DSH Desktop and DSH Web. All the Bot features are here |
+| The DS Bot desktop app | Opens straight into DS Bot. It brings a pinned DSH, its own profile and its own data folder, imports a team the user already has in DSH, and installs DSH-compatible plugins, so that DS Bot grows its own plugin ecosystem. The plugin can still be used on its own |
+
+Both forms run the same `ds-bot` plugin. The point of the app is that DS Bot controls its own profile and interface, free of the limits of DSH's general interface and global settings (see the [DSH concessions](plans/2026-10-13-dsh-concessions.md)).
+
+## Ten core requirements
+
+1. **Built on DSH.** Every Bot is a DSH Session and runs through the normal DSH agent loop, tools and model routes. DS Bot follows DSH's plugin model and uses only documented interfaces. It does not patch DSH and does not add a second agent runtime.
+2. **The team comes first.** The point is many Bots working together, not one Bot. Bots message each other and share group chats. A Main Bot has the highest rights: it creates, changes and removes other Bots, and there can be more than one. Other Bots do not get these rights.
+3. **Clear roles.** Each Bot has its own role; a team is not a set of Bots that all do the same thing.
+4. **A polished interface with careful motion.** Motion is smooth and has a cause: a change of state has a transition, an action has feedback, nothing moves for its own sake.
+5. **Independent, and visible to each other.** Each Bot works on its own and does not disturb the others; when it needs to, it can see what the others are doing.
+6. **One Bot, one continuous conversation.** The user sees one continuous chat. When the context fills up, the Bot moves on to a new part (a new DSH Session) and the old part goes into a searchable index, instead of compacting again and again and losing detail.
+7. **Active memory.** Bots have a memory and look things up in it themselves, not only through what is injected.
+8. **Reliable.** Bots stay aligned with the goal, act on evidence, stay inside their task, and their results can be checked. When unsure, a Bot looks it up or asks instead of guessing.
+9. **Customizable.** Users customize each Bot: name, role label, instructions, model, character; later also the system prompt and even the harness each Bot runs on.
+10. **Other local agents can join.** Later, other agents on the same computer (for example through their command line) can join the team.
+
+## Principles for trade-offs
+
+- **Correct Bot behavior comes first.** Where a DSH mode or limit does not fit Bots, DS Bot does not pile up complexity to stay compatible. Concessions that cannot be avoided go into the [DSH concessions](plans/2026-10-13-dsh-concessions.md), to be removed once the app controls its own profile.
+- **Data stays on the user's computer.** Teams, chats and memory live in the local DSH data folder.
+- **Only original material.** No code, text, icons or graphics copied from other products.
+- **Done means checked.** Behavior is covered by tests; interface changes are looked at for real.
+
+## What DS Bot does not do
+
+- It does not patch DSH or depend on internal files of a DSH install.
+- It does not add its own agent runtime or go around DSH's tools and permissions.
+- It is not a hosted service: DS Bot runs in the user's own DSH.
+
+## Who sets the direction
+
+The maintainer decides the direction of the product, changes to decided designs, the rules for working together, releases and the architecture. Anyone can do the rest of the work; see [CONTRIBUTING](../CONTRIBUTING.md#how-we-work).
diff --git a/docs/vision.zh.md b/docs/vision.zh.md
new file mode 100644
index 00000000..6727a23a
--- /dev/null
+++ b/docs/vision.zh.md
@@ -0,0 +1,48 @@
+# DS Bot 的愿景
+
+[English](vision.md) | 中文
+
+本文写 DS Bot 要做成什么、为什么这样做,以及不做什么。功能怎么用,见 [README](../README.zh.md);已定的具体设计,见 [docs/plans/](plans/);怎么参与开发,见 [CONTRIBUTING](../CONTRIBUTING.zh.md)。
+
+## DS Bot 是什么
+
+DS Bot 是一支长期在线的 Bot 团队,基于 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(DSH)构建,开源,使用 Apache 2.0 许可。用户不是和一个助手聊天,而是带一支有分工的团队:一个或几个 Main Bot 负责组织,其他 Bot 各做各的事,互相沟通,用户随时能看到谁在做什么。
+
+## 两种形态
+
+| 形态 | 是什么 |
+|---|---|
+| `ds-bot` 插件 | 标准的 DSH 插件,装进 DSH Desktop 或 DSH Web 使用。Bot 的全部功能都在这里 |
+| DS Bot 桌面应用 | 一打开就是 DS Bot。自带锁定版本的 DSH、自己的 profile 和数据目录,能导入用户在 DSH 里已有的团队,也能安装与 DSH 兼容的插件,逐步形成 DS Bot 自己的插件生态。插件仍然可以单独用 |
+
+两种形态用的是同一份 `ds-bot` 插件。桌面应用的意义在于:DS Bot 自己掌握 profile 和界面,不再受 DSH 通用界面和全局配置的限制(见 [DSH 让步总账](plans/2026-10-13-dsh-concessions.md))。
+
+## 十条核心要求
+
+1. **基于 DSH 构建。** 每个 Bot 都是一个 DSH Session,走 DSH 正常的 agent 循环、工具和模型路由。按 DSH 的插件规范来做,只用 DSH 有文档的接口,不修改 DSH,也不另造一套 agent 运行时。
+2. **团队协作优先。** 重点是多个 Bot 一起工作,而不是一个 Bot。Bot 之间能互发消息、共用群聊。Main Bot 权限最高:能创建、修改、删除其他 Bot,可以有多个 Main Bot;普通 Bot 不授予这些权限。
+3. **分工明确。** 每个 Bot 有自己的角色,团队里不应该是一群做同样事情的 Bot。
+4. **界面精致,动效讲究。** 动效流畅、有因果:状态变化有过渡,操作有反馈,不为动而动。
+5. **独立运行,互相可见。** 每个 Bot 单独工作,互不打扰;需要时能知道别的 Bot 在做什么。
+6. **一个 Bot,一条连续的对话。** 用户看到的是一条连续的聊天。上下文快满时换到新的一段(新的 DSH Session),旧内容进索引、可以搜索,而不是一遍遍压缩把细节丢掉。
+7. **主动的记忆。** Bot 有记忆系统,并且会主动去查,不只靠被动注入。
+8. **可靠。** 思路对齐、做事有依据、目标有约束、结果可验证。Bot 拿不准时去查、去问,而不是猜。
+9. **可定制。** 用户能定制每个 Bot:名字、角色标签、指令、模型、形象;以后扩展到系统提示词,乃至每个 Bot 用哪套 harness。
+10. **能接入其他本地 Agent。** 以后可以把本机的其他 Agent(例如通过命令行)接进团队。
+
+## 取舍原则
+
+- **Bot 的正确行为优先。** DSH 某些模式或限制和 Bot 不兼容时,不为了兼容无限增加复杂度。不得不让步的地方,记进 [DSH 让步总账](plans/2026-10-13-dsh-concessions.md),等桌面应用掌握 profile 后清理。
+- **数据留在用户自己的电脑上。** 团队、聊天、记忆都存在本机的 DSH 数据目录里。
+- **只用原创素材。** 代码、文字、图标、图形都不从其他产品复制。
+- **能验证才算完成。** 行为要有测试覆盖,界面改动要实际看过。
+
+## 不做什么
+
+- 不修改 DSH,不依赖 DSH 安装目录里的内部文件。
+- 不另造 agent 运行时,不绕开 DSH 的工具和权限。
+- 不做云端托管的团队:DS Bot 跑在用户自己的 DSH 里。
+
+## 谁来定方向
+
+产品方向、已定设计的改动、协作规则、发版和架构由维护者决定。其他工作谁都可以做,流程见 [CONTRIBUTING](../CONTRIBUTING.zh.md#协作方式)。