dsh-sansheng-liubu/docs/ds-bot-analysis.md

26 KiB
Raw Blame History

DS Bot 实际源码架构拆解

分析日期:2026-11-14。静态只读审查;未安装依赖、未启动应用、未执行测试或仓库脚本。本文只写入工作区根目录 docs,不修改任何仓库。 “已实现”指存在已接入的源码,不代表本机运行验证通过。第三方服务是否可用、具体安装包能否启动,不能由本次静态审查保证。

1. 先分清两个 ds-bot

工作区是 C:/Users/qyh15/三省六部。外层 ds-bot 是整个 Git 项目;内层 ds-bot/ds-bot 是可发布的 DSH 插件包。二者不是两个重复项目。

已先读 AGENTS.md:7–10,其中明确区分插件与桌面应用;AGENTS.md:22–28 要求使用 DSH 公共入口、不修改 DSH、生成文件不手改、不碰用户自有数据。

  • 核心插件目录:Bot 团队业务、浏览器 UI、工具、存储、外部能力。
  • 桌面应用目录:Electron、自己的 React 页面、精简 DSH engine、安装升级和导入。
  • 手机应用目录:React Native / Expo 客户端,并非桌面网页简单缩小。
  • 加密链路目录:手机与电脑通信协议、配对、WebSocket Relay 服务。
  • 设计文档目录:已定设计与限制,不应一概当成未实现路线图。

一句话架构:DS Bot 是建立在 DSH 执行引擎之上的长期机器人团队工作台。它自己管理“谁是谁、谁找谁、群里怎么工作、记住什么”,DSH 管真正的 Session、模型请求、工具执行和宿主能力。

核心插件以 index.js:55–86 的 Cordis 风格 name / inject / apply 注册;不是一套独立 Express、FastAPI 或 Spring 后端。

2. 前端:同一批 Bot 组件,三种承载方式

2.1 嵌在 DSH Web / Desktop 的插件页面

框架是 React,普通 JavaScript ESM,广泛使用 createElement 而非必须依赖 JSX;例如 sidebar.js:1–18 直接导入 React Hooks、createPortal。

入口为 src/client/index.js:61–63。它注入 sessions、uiWorkspace、uiConversation、slots、theme、layout,向 DSH 的既有界面槽位挂组件;index.js:982–985 展示具体 slots 注册。

发布入口是生成的 client.js,包的 exports 声明见 package.json:24–30。构建脚本由 package.json:45–50 指向 esbuild 构建;实际修改应发生在源码目录。

页面不是只有聊天框。入口导入已经体现这些组成:index.js:1–32。

  • 侧栏、团队角色和形象:sidebar、characters、mark、themes。
  • 聊天内容与输入:cells、composer、questions、widget-cell、at-menu。
  • 群聊与工作状态:成员状态、群设置、目标状态及协作消息。
  • 设置与管理:模型、Provider、权限、记忆、定时任务、连接器、能力、用量。
  • 浏览器、电脑接管、密钥卡、临时问题与侧聊:独立面板结合聊天状态展示。

这些 UI 依赖后端 team view、Session 投影和动作接口;复制组件时必须带上对应数据适配层,不能只拷 CSS 就获得完整应用。

2.2 独立桌面页面

桌面有自己的 app/ui/src/main.js:1–19,导入 React、createRoot 与 App,同时直接复用核心插件的侧栏、设置、主题 CSS 和国际化代码。

技术依赖明确为 React 19.3.0、React DOM 19.3.0、Vite 8.3.4;另用 react-markdown、remark-gfm,见 app/package.json:74–85。这不是 Vue / Next.js 前端。

桌面自己的页面只与 Bot channel 对话:api.js:1–2 写明 POST api/bot 与 api/bot/feed。实时事件通过 fetch 流读取 SSE,而非 EventSource,原因是窗口使用自己的 scheme,见 api.js:16–29。

2.3 手机页面

手机入口由 mobile/package.json:4 指向 index.ts,App 的启动分支在 App.tsx:122–137:身份、电脑配对、语言准备好后才进入 Linked 视图。

依赖为 Expo 58、React Native 0.88、React Navigation、SecureStore、相机、图片选择、生物识别等,见 mobile/package.json:5–34。这是独立原生客户端,有真实代码,但本次未构建 APK/IPA。

3. 后端入口、模块组织与 API

3.1 宿主与插件的分工

index.js:56 要求 llm、tools、systemPrompt、sessionController、sessions、sessionTitle、workspaceRegistry、connection。

index.js:63–89 按顺序调用各模块 install(rt),把共享函数放在 runtime 对象上。模块之间在运行时经 rt 调用,不是每块单独启动服务。

这是一种“单进程业务模块 + 宿主服务依赖注入”的组合。安装顺序影响监听器和工具顺序,入口 index.js:58–62 特别说明 privacy 应先拦截、usage 应后计量。

普通文件操作、Shell、Subagent、Web、工作流等执行器大多来自 DSH;精简 engine 的依赖清单 engine/package.json:26–59 可以直接对照。不要把这些全算成 DS Bot 自写的执行引擎。

3.2 API 是统一动作通道

channel.js:844–854 通过 ctx.connection.fetch.register 注册 POST route。请求 JSON 中用 endpoint + payload 选择业务动作;响应采用 ok/value 或 ok/error,见 channel.js:55–58。业务错误并不都表现为不同 HTTP 状态。

浏览器认证复用 DSH connection cookie;不是 DS Bot 另建了一套用户登录数据库。

主要接口组与源码位置:

实时推送另走 feed:事件序列化为 SSE,保存触发监听,并支持手机接入用的 tap,见 feed.js:34–48。手机与桌面尽量复用业务视图,而不是各写一份 Bot 后端。

3.3 模型可调用的工具

Bot 专属工具放进 teamTools,并按 Bot Session scope 注册,而非全局暴露给所有 DSH 会话,见 index.js:78–89。

核心工具有 list_bots、message_bot、stop_bot、create_bot、update_bot、list_bot_models,见 tools.js:80、tools.js:167、tools.js:298–363、tools.js:453。

群管理与交互有 create_group、update_group、delete_group、post_to_group、ask_user、show_view,见 tools.js:496–726。还有 group_relay、read_own_chat、read_group_chat,见 groups.js:1–2。

能力管理工具有 list_capabilities、save_capability、delete_capability,见 tools.js:1129–1185。目标工具 group_goal 位于 goals.js:670–709,不是只有文档里的口头流程。

注意:界面有 delete-bot 动作不等于模型拥有 delete_bot 工具;用户层操作与 Bot 工具权限必须分别判断。

4. 桌面壳:真正的多进程分工

Electron 主入口是 app/package.json:12 声明的 main.mjs;main.mjs:8 导入 BrowserWindow、IPC、Tray、WebContentsView 等原生组件。

主进程负责窗口、系统托盘、文件选择、下载、浏览器视图、首次设置、导入和更新;宿主运行在独立子进程。实际 Host 创建见 main.mjs:573–590。

Host 明确把 DSH_HOME 设为应用数据目录,同时传入工作文件夹、runtime 目录、用户原 DSH 数据位置。其 app profile 不等于用户日常运行的 DSH profile。

host.mjs:8–43 调用公开 runProfile 入口并加载 layered env、profile 和应用自己的 patch。这里的 patch 是配置组合,不是修改 DSH 安装源码。

engine/cordis.patch.yml:1–5 明确没有 DSH Web 前端:engine 只给 Bot API 提供回环 HTTP 服务、连接和 Session 执行能力。

Host 启动后生成 authenticatedUrl,经 IPC 回主进程,见 host.mjs:61–72。engine 根路由只做启动 token 换 cookie,授权后返回 204,见 engine/index.js:7–18。

关闭窗口通常只是隐藏,机器人继续在后台工作;真正退出经托盘处理,见 shell.mjs:1–15。这也是“长期 Bot”在桌面生命周期上的基础。

5. 一条消息到底怎么跑

  1. 用户在 React / 手机 / IM 界面发消息;桌面到 Bot API,手机走加密链路,IM 由平台适配器转成内部请求。
  2. channel.js:802–815 把 Bot 或旧分段引用解析成当前 Session,准备 capabilities,然后 sessionController.prompt(mode: queue)。
  3. DSH 解析 Agent、加载模型和工具,进入常规执行回合。DS Bot 在旁跟踪状态、注入身份/记忆/群目标等上下文。
  4. Bot 想找同伴时调用 message_bot;delivery 解析接收方 Agent,delivery.js:10–14 使用 DSH sessionController,而不是启动一个独立模型服务器。
  5. handoffs 保存上下级工作关系,子工作全部归来后把结果送回上层;见 handoffs.js:1–7。
  6. turns 跟踪运行、失败和回报路由;feed 推 UI;需要长时记忆时由 memory 的审核/写入链处理。
  7. 上下文快满时压缩或切新 Session;旧段继续可查,见 parts.js:1–16。Bot 身份不随 Session 换段消失。

群聊有所不同:groups.js:4–18 规定 @ 同时点名的成员可并行开工;普通消息在 admin 模式只到管理员,否则按序发言;忙着做工具工作的成员不会无限卡住一轮。

所以 Bot 不是一个永不更换的单 Session,群也不是把所有成员塞进一个共享模型上下文。 Bot 私聊、成员在群中的 Session、历史分段是分别管理的。

6. 大功能模块手册

6.1 身份、角色、团队和普通 Agent

职责:维护 Bot 名字、角色说明、模型、头像、Main 身份、群及成员。关键路径 roster.js:1–5,操作工具见前述 tools。

关系:store 持久化身份,folders 选工作路径,permissions 应用权限,parts 管 Session 换代。另有普通 DSH Agent 入口,不属于 Bot、不带团队工具,agents.js:1–3。

Main Bot 表示更高的团队管理权限,可以有多个;它不是预设“六部职责—门下审查—尚书执行”的固定制度。部门称号可用角色说明表达,但严格业务审批链需另建状态机。

6.2 私聊协作、交接与去重

职责:消息派送、等待、停止、返还结果、识别正在做什么。关键路径 delivery.js:1–14、turns.js:1–16、handoffs.js:1–7。

requests 给调用方指定 request_id 的请求提供稳定回执与指纹,先记录再发送,未知结果不自动重投,requests.js:1–13。它限制重复派工,不等于任意外部副作用都有全局事务保证。

6.3 群聊、目标、工作阶段与审批

职责:管理员/成员调度、并行 @、轮次回报、群消息、任务阶段。groups 与 ledger、turns、goals 相互配合,groups.js:19–32。

group_goal 支持 draft/start/revise/task/pass/rework/complete/pause/resume/stop;只有群管理员或 Main Bot 能修改。pass 和 complete 要求 evidence,见 goals.js:288–299、goals.js:670–671。

这里校验的是目标状态与证据字段,并不自动证明模型提供的证据真实,也不是通用 BPMN 工作流引擎。业务审批应区分“群内工作验收”与“宿主工具权限审批”。

6.4 上下文续接、历史搜索

职责:长聊压缩、换段、交接包、历史页。关键路径 parts.js:1–16;read_own_chat 可查各段和压缩前消息。

聊天全文索引单独存 SQLite,使用 node:sqlite / FTS5 trigram,见 chat-index.js:48–110。它服务历史检索,不是整个应用的唯一数据库。

6.5 长期记忆、审核、召回与整理

职责:Bot / 群 / 团队三层 Markdown 记忆,话题索引、修改日志、快照、删除后的归档;工具与后台审核走同一写入路径,memory.js:1–26。

与 Session 的关系:每段首次渲染冻结记忆提示段,保证前缀缓存稳定;换段或 checkpoint 再冻结。群记忆只在群上下文里给成员读取,并非一份任意串用的团队聊天摘要。

召回使用内存词项排名,类似 BM25 参数与词项覆盖度,见 memory-search.js:1–29。没有据此把它称为向量数据库、embedding RAG 或外置知识图谱的依据。

6.6 工作文件夹、权限与私密 Bot

职责:决定 Session cwd,按 Bot/群保存权限预设,保护私密 Bot 信息。群文件夹优先于成员覆盖、Bot 默认和团队目录,见 folders.js:1–4、folders.js:23–33。

权限来自 DSH permissionPresets;auto review 是 Session 临时模式,不可作为 Bot/群长期预设,见 permissions.js:1–5、permissions.js:41–47。

私密 Bot 关闭其他 Bot 的业务读入口并检查文件/Shell 路径,但源码明说 Shell 仍可能访问 OS 账号可读的任意文件,privacy.js:1–4。因此不是进程、容器或多租户安全隔离。

6.7 模型、思考、Provider、用量与诊断

职责:选择每个 Bot 的模型/推理强度,管理 Provider 配置和展示用量、阻塞原因;入口模块装配见 index.js:7–10、index.js:40–43。

数据关系:模型列表从 DSH 取,不完全受团队 revision 控制,channel.js:59–61。缺密钥、配额、登录和本地 CLI 错误被 turns 标为需要用户修复的阻塞,turns.js:14–20。

6.8 能力库、MCP、技能、学习提案

职责:保存可分配给 Bot 的 MCP、skill 和能力包,按 Session 挂载;保留 connector 名称避免工具前缀冲突,capabilities.js:5–32。

learning 对长回合在空闲后做低频审核,提出技能或项目规则卡片,经批准才落地,拒绝的建议会被记住,learning.js:1–30。这已是代码实现,但不意味着可不受约束地自我重写系统。

6.9 浏览器、联网搜索、电脑操控

浏览器面板:每 Bot 独立 Electron 存储分区;Host 通过 browser-wait/browser-result 长轮询请求页面读取,见 browser.js:1–18。需要实际承载页面的客户端在线。

自动化:团队选一个浏览器后端,各 Bot 独立 profile,已有 refs/script/task 三种模块,browser-plugins.js:1–12。

联网搜索是独立 auto provider:优先按当前模型协议和自身凭据尝试原生搜索,失败再公共搜索页回退,web-search.js:1–24。与 Bot 团队代码分离较好,但仍依赖 DSH web seam。

电脑操控挂载 DSH 平台 Provider,DS Bot 补每 Bot 等级、应用同意、应用租约、指示器与人工交接;见 computer/index.js:1–30。不能据此假定三个系统实际权限和驱动体验一致。

6.10 密钥、通用连接器、邮件

密钥独立保存,通过 DSH_SECRET 环境变量引用;模型请求和工具结果做脱敏,见 secrets.js:1–4。这是应用级保护,文件 mode 600 不等于静态加密。

连接器模块组合 OAuth、catalog、gateway、mail 与 MCP client,connectors/index.js:1–17。MCP loader 缺失时明确失败,connectors/index.js:147–148。

关系:连接器凭据由 secrets 提供,能力可分配给 Bot,邮件依赖 imapflow/mailparser/nodemailer;不是自带所有 SaaS 的离线替代品。

6.11 IM、手机与 Relay

IM 一个平台 Bot 账号绑定一个内部 Bot,平台群可映射 DS Bot 群;统一处理配对、路由、交互卡与发送队列,仅团队锁持有者连接,im/index.js:1–4。

源码已注册 Telegram、Discord、Slack、QQ、钉钉、企业微信、飞书、微信适配器;其余 UI 列表项可能只是 coming soon,im/platforms/index.js:1–12。存在 adapter 不代表本次已验证账号和远端服务。

手机后端负责设备配对、撤销与状态,phone.js:123–159。加密协议依赖 clatterjs 与 noble 系列,link/package.json:13–18。

Relay 是 Node HTTP + WebSocket:healthz、upgrade 路径检查、Gateway 和 DeviceStore,server.ts:23–43。服务入口可配置端口、设备 TTL、连接数等限制,main.ts:7–16。它负责链路转发,不替电脑执行模型回合。

6.12 定时、Office、图片头像与更新

定时任务依赖 DSH schedule 服务;会话换段后迁移任务,服务缺失时接口报告不可用,schedules.js:1–7。因此装上插件不代表自动具备完整调度服务。

Office 注册路由 skill 与 office-tools;CLI 可检查/编辑 docx、pptx、xlsx 包,office-skills.js:1–14、office/cli.js:1–22。没有证据把它称作浏览器内完整 Office 协同编辑器。

图片、头像库、更新、DSH 更新、思考显示等均在运行时入口接入,index.js:30–43。上传暂存由 channel 维护 MIME 白名单与 30 分钟窗口,channel.js:10–11。

6.13 本地 Agent CLI

本地 CLI 作为 Bot 执行方式,不只是模型下拉列表别名。引擎有 ACP/stdin-stdout、Codex app-server JSON-RPC、Claude stream-json,local-agents/engines.js:1–5。

已有 Claude Code、Codex、OpenCode、Gemini 等命令定义,见 engines.js:18–22;权限预设要映射到各引擎语义,engines.js:80–89。本机必须另有相应 CLI、登录和权限,不能当成仓库随附的模型。

7. 数据存放:不是“只有一个 JSON”

默认 Bot 数据根为 DSH_HOME/bot,也可 config.home 覆盖,index.js:69–77。入口开头“one JSON file”的简述不足以覆盖现在全部存储。

  • state.json:Bot/群/Agent/分区/能力/偏好/工作与请求等目录及状态,结构见 store.js:22–23。
  • state.lock:阻止两个 Host 同时写同一团队;另一窗口只读。锁失败会警告而非神奇获得分布式一致性,store.js:49–67。
  • ledger/*.jsonl:按会话追加消息和状态记录,先落盘再交付;首次整本读入内存,按 book 串行写,ledger.js:1–11。
  • chat-index.sqlite:聊天历史搜索索引,原始 Session 仍由 DSH sessionPersistence 保存,chat-index.js:48–110、host.mjs:55–58。
  • memory/:Markdown 正文、journal、snapshots、summaries、archive、reviewed 游标,memory.js:6–14。
  • secrets.json:凭据文件与进程内存,不放进普通团队状态/模型正文,secrets.js:1–4。
  • im/、浏览器 profile、头像、手机配对数据等是功能附属持久数据;不能只备份 state.json 就声称备份完成。

数据规模边界:账本首次整本读入内存,request 身份不随便过期,单团队文件锁与 JSON 状态都偏向个人/本机长期助手。它不是已验证的高并发分布式团队数据库。

8. 运行依赖与可用性条件

插件自身要求 DSH 的 Cordis / llm / scope / tools / web peer 服务;实际 peer 版本写 *,package.json:52–57。不应误解为任何 DSH 版本都保证兼容。

桌面把 DSH 系列包固定在 0.2.2-rc.1,Electron 44.7.0,见 app/package.json:28–64、app/package.json:75。构建与发行还涉及 electron-builder、Vite、pnpm;属于桌面交付依赖。

插件实际运行依赖还包括 MCP client、deep-view、邮件库、playwright-core、图像编解码和 ws,package.json:72–81。Playwright Core 存在不等于已安装完整浏览器。

模型仍需要有效 Provider 凭据/账户或已登录 CLI;电脑操控需要平台 Provider 和 OS 授权;连接器需要远端服务;手机需要电脑 Host 在线与可达 Relay;定时需 schedule 服务。

Node 必须能满足所用 DSH 包以及 node:sqlite 等 API;本次未执行环境探测,因此不擅自给整个项目一个未经核验的统一 Node 最低版本。

9. 哪些是源码实现,哪些是文档规划

plans/README.md:1–9 明确该目录记录“已定的设计”,大功能设计跟代码在同一 PR。文件名带 plans 不等于功能还没写。

已核实接入的功能:长期身份、多 Main Bot、群聊调度、阶段目标、Markdown 记忆、历史搜索、私密 Bot 业务限制、浏览器、电脑操控、MCP/连接器、学习提案、Office CLI、IM、手机链路、本地 Agent CLI。证据是入口装配 + 对应模块实现,而非 README 宣传语。

文档存在滞后:vision.md:23 仍写 self-improvement planned,但 learning 已有“后台审核→提案→用户批准”代码;这仅支持说“有限学习提案已实现”,不支持“全面自我进化”。

同样 vision.md:28 写 Cookie 导入 planned,而 main.mjs:825–845 已有导入分支。应以当前代码描述能力,并保留未运行验证的限定。

IM 的 coming soon 有明确代码边界:只有 adapters 中列出的平台可新增连接。不要把完整平台目录里的每个名字都算已打通。

没有据本次源码得到的能力:固定部门制审核链、跨团队强多租户隔离、任意外部副作用恰好一次、分布式高可用调度、模型结果自动正确性保证。应作为新需求评估,不能从“Main”“workspace”“evidence”这些字段名称推导出来。

10. 可复用边界与实际选型建议

最容易整体复用的是“DSH + DS Bot 插件”组合。 保留现成 Session、工具、权限和模型服务,开发重点放在角色约束、流程与业务 UI;成本显著小于抽掉 DSH 后重做所有宿主接口。

可以相对独立借鉴/抽取:追加式消息账本与去重设计、记忆格式与词项排名、Office 包处理、加密 Relay、纯 React 展示组件。仍需检查导入依赖、许可证和持久格式,不能称为复制即用。

不适合直接割裂复用:rt 大量互调的群聊/turns/handoffs/parts、依赖 DSH slots 的插件 UI、依赖宿主 Session schema 的历史/权限/模型接口、Electron 原生浏览器与电脑操控。

若用于“多项目、多部门协作平台”,建议保留 Bot 身份与协作机制,但单独定义项目实体、成员/资源授权、产物归属和流程审批状态机;仅改机器人名字、分配文件夹、添加 Main 标记,不会自动补齐这些边界。

源码许可证标注 Apache-2.0,package.json:23;桌面部分明确引用 DSH MIT 代码并要求 NOTICE,host.mjs:5。复用时应保留相应声明和来源,不把开源许可误当作无义务搬运。

本报告的结论是架构与实现边界,不是安全审计通过、性能测试通过或发布可用性背书。全部源码引用对应本工作区静态版本。