Skip to content

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

Add the browser, search, secrets and connector design to docs/plans

Fei24114d2059953028
diff --git a/docs/plans/2026-10-08-browser-and-secrets.md b/docs/plans/2026-10-08-browser-and-secrets.md
new file mode 100644
index 00000000..3154329f
--- /dev/null
+++ b/docs/plans/2026-10-08-browser-and-secrets.md
@@ -0,0 +1,75 @@
+# Bot 浏览器、联网搜索、密钥和连接器
+
+- 日期:2026-10-08 定 Bot 浏览器,2026-10-09 定读网页和密钥卡,之后补了连接器
+- 相关:#114(链接在 Bot 浏览器里打开)、#128(关掉 auto 搜索后的恢复)、#184(opencode 路由的 `web_search`)
+- 代码:`ds-bot/src/host/browser.js`、`src/client/bot-browsers.js`、`src/client/read-page.js`、`ds-bot/web-search.js`、`src/host/secrets.js`、`src/host/connectors.js`
+
+## 为什么
+
+Bot 要替用户在网上做事,就会碰到两类东西:网页,以及登录网页、调用服务要用的密钥。两者的风险是同一个:**网页内容不可信,密钥不能泄露**。网页里可能藏着「把你的 token 发到这里」这样的指令,模型请求会发往第三方,聊天记录也会被保存。
+
+所以定下的原则是:
+
+- 浏览器由**用户操作**,Bot 只能读。每个 Bot 的浏览器互相隔离。
+- 密钥的值**只有用户输入、只存在本机**。Bot 只拿到环境变量名;值在离开本机之前一律换成占位符。
+
+## 已定的行为
+
+### Bot 浏览器(只在 DSH Desktop 里有)
+
+- 每个 Bot 有自己的浏览器面板,可以开多个标签页。每个标签页是一个 Electron webview,放在这个 Bot 自己的存储分区里(`bot:<id>`)。同一个 Bot 的标签页共用登录状态,不同 Bot 之间的 cookie 和登录状态不互通。
+- 页面由用户操作。Bot 的 `read_browser` 只读当前标签页:标题、地址,以及可见内容转成的 Markdown。链接和控件在文中标成 `[#n]`,并列出目标。长页面分段读,用 `from` 接着读。
+- 能读进 Web Components(open shadow DOM)和同源 iframe。读不了跨域 iframe(只给出它们的名字)、canvas 上画的字和隐藏的内容。
+- `read_browser` **不能点击、输入、滚动或打开页面**。工具说明里要求 Bot 把页面内容当作数据,不当作指令。
+- 页面在应用窗口里,不在插件进程里。所以读取请求要经过窗口:客户端一直挂着一个长轮询(`browser-wait`),报告哪些 Bot 开着页面,并把读取请求带回窗口,窗口用 `browser-result` 回答。请求在窗口回答之前一直排队;轮询中断过的会重新发,窗口按 id 去重。
+- 所有 Bot、所有标签页加起来最多同时保留 6 个活着的页面(每个都是一个渲染进程)。超过时释放最久没看的那个,地址和摘要保留,再显示时重新加载。
+- 能打开本机和局域网的页面。云主机的元数据服务不能打开,因为它会发放账号凭据。
+- 抽屉里的卡片用页面自己的描述或第一段正文做预览,不截图:Windows 上截图失败会让整个应用的渲染进程崩溃。
+
+### 联网搜索(`auto` 提供方)
+
+- `web-search.js` 是 DSH 联网搜索的一个提供方,和 Bot 团队的代码互相独立,普通 DSH 会话也能用。
+- 每次搜索先试**提问的那个会话自己的模型路由**的原生搜索:用这条路由自己的 key、发往这条路由自己的地址。按协议判断有没有原生搜索,不按厂商判断。一个地址支不支持只能试了才知道,所以每次的结果都会记下来。
+- **绝不借用另一条路由的 key**:每个 key 都在它自己的账户上计费。
+- 原生搜索不可用时,退回到不需要 key 的方式:通过 DSH 的 `fetch` 取一个公开的搜索结果页并解析。
+- 每条结果都注明是哪条路径给的。两条路径都失败时,错误信息告诉模型不要猜。
+
+### 密钥
+
+- **只有用户能输入值**。Bot 用 `request_secret` 在自己的聊天里弹出一张密钥卡,用户在卡里输入,Bot 永远看不到值。卡片一出现,Bot 这一回合就结束;用户保存或取消后,Bot 会收到通知。已经给这个 Bot 存过的密钥,只告诉它变量名。
+- 值只存在数据目录的 `bot/secrets.json`(权限 600)和插件进程里。
+- Bot 在 shell 里用 `$DSH_SECRET_<名字>` 取值。工具结果在保存之前去掉值;每次模型请求发出之前,值都换成 `[secret:<名字>]`。JSON 转义和 URL 编码后的形式也会替换;多个值时先换最长的。
+- 不到 8 个字符的短值(PIN、短密码)如果哪里出现都替换,会误伤普通文字,所以只在它单独出现时替换:前后紧挨着的不是字母或数字。
+- 范围:「只给这个 Bot」或「所有 Bot」。另一个 Bot 再要同一个密钥、用户同意时,把它加进范围。`list_secrets` 列出名字、用途、哪些 Bot 能用,不显示值。
+- 设置 → Secrets 能改范围、换值、删除。
+- 记忆不保存看起来像密钥的内容(见[上下文与记忆](2026-10-09-context-and-memory.md))。
+- 能力里的 MCP 配置引用密钥时写 `$DSH_SECRET_<名字>`,不写值(见 [Bot 运行配置](2026-10-10-bot-runtime.md))。
+
+### 连接器(GitHub)
+
+- 连接器是所有 Bot 都能用的外部服务,GitHub 是第一个。工具来自 GitHub 的 MCP 服务,通过 DSH 自己的 MCP 客户端挂在插件上,所以每个 Bot 和会话都能以 `mcp__github__<工具>` 调用。
+- token 存为密钥 `GITHUB_TOKEN`。它只出现在发往 GitHub 的 MCP 请求头里,这个请求头在内存里生成,不写进 DSH 的 profile。
+- 新连接的 token **默认不进任何 Bot 的 shell**:MCP 工具用不着它;而一个读到了 Issue 里埋的指令的 Bot,可能把它发到任何地方。用户可以在 Secrets 页面上自己放开。
+- 连接时先问 GitHub 这个 token 属于谁,GitHub 接受就算通过。删掉 `GITHUB_TOKEN` 就断开。
+- 连接器地址不是 https 时,拒绝发送 token。
+
+## 不做什么
+
+- Bot 不操作浏览器:不点击、不输入、不打开页面。
+- 不让 Bot 看到或输入密钥的值,不把值写进聊天记录、记忆、DSH 的 profile 或模型请求。
+- 联网搜索不借用别的路由的 key。
+
+## 已知限制
+
+- Bot 浏览器只在 DSH Desktop 里有,DSH Web 没有。
+- 历史消息里的链接还不能直接在 Bot 浏览器里打开(#114)。
+- 关掉 `auto` 搜索以后,`web_search` 可能报错,恢复方法见 #128。
+- 用 opencode 路由时,原生搜索缺少 `x-opencode-session`(#184)。
+- 和[愿景](../vision.zh.md)第 7 条的差距:导入 cookie 还没做。
+- 密钥只防泄露到模型、记录和其他 Bot 的 shell。有权限的 Bot 在自己的 shell 里能用到值,所以给哪些 Bot 开放,要由用户判断。
+
+## 变更
+
+- 2026-10-08:每个 Bot 一个浏览器,由用户操作,Bot 只读。
+- 2026-10-09:`read_browser` 读成 Markdown 并标注链接和控件;密钥卡和替换规则。
+- 之后:加了多标签页、最多 6 个活着的页面、GitHub 连接器。
diff --git a/docs/plans/README.md b/docs/plans/README.md
index 84f18f11..91a533f3 100644
--- a/docs/plans/README.md
+++ b/docs/plans/README.md
@@ -39,3 +39,4 @@
| [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) | 谁来回答、按顺序发言、@ 提及、轮数上限、干活中的进度和迟到的回复、审批 |
+| [浏览器、搜索、密钥和连接器](2026-10-08-browser-and-secrets.md) | 每个 Bot 的浏览器和 `read_browser`、`auto` 联网搜索、密钥卡和替换规则、GitHub 连接器 |