# DS-Bot 上游 API 调研(供三省六部「伴侣插件」决策) - 调研对象:DS-Bot `8e0013e077eaeccc137327956e18425e73a5bb8c`(version 0.3.2) - 本地源码根:`.scratch/p0/DS-Bot-8e0013e077eaeccc137327956e18425e73a5bb8c/ds-bot/` - 宿主:DeepSeek Harness(asar 内的 `@deepseek-ai/*` 已解包到 `.scratch/p0/asar/`,下文以 `dsh-tools/lib/index.js` 指代宿主实现) - 证据格式:`src/host/xxx.js:123` 指 ds-bot 源码行;`dsh-tools/lib/...` 指解包后的宿主包 > 说明:本文只读源码得结论,未运行 npm build/test(源码树无 node_modules,无法执行)。 --- ## 结论摘要 1. **`rt` 拿不到。** `apply()` 调了 `createRuntime()` 却不返回它(`index.js:63-65`),且全仓没有任何 `ctx.set/provide` 把 `rt` 暴露成 DSH 服务。伴侣插件能拿到的只有 DSH 服务(`ctx.get(...)`)和 `agent/created` 事件里的 `agent`;想拿活 `rt` 必须改上游或 fork。 2. **Bot 就是一个普通 root Session。** `bot.id` 等于它私聊首段 Session 的 id,`bot.sessionId` 是当前段,`chatOf(botId)` 取当前段(`src/host/store.js:454-463`)。 3. **每个成员在每个群有一个隐藏 Session**,存 `room.sessions[botId]`,在该群首次发言时创建(`src/host/groups.js:310-344`);群自己还有一个**只做 relay、从不调模型**的 Session(`src/host/roster.js:638-677`、`src/host/groups.js:1564`)。 4. **模型三级回退**:`bot.model` → `bot.appliedModel`(上次真正跑通的) → `prefs.defaultBotModel` / DSH 默认(`src/host/models.js:180-186`);`applyModel` 会把这个选择同时应用到该 Bot 的每个群 Session(`src/host/models.js:250-269`)。 5. **`message_bot` 没有自建队列**:最终就是 `agent.steer(...)` 或 `agent.followup(...)` + `ctx.sessions.flush(...)`(`src/host/delivery.js:99-101`)。**群内调用根本不投递**,只是把 `@Name …` 写进本群当前 turn 的步骤行(`src/host/tools.js:155-159`)。 6. **幂等靠 `request_id` + 内容指纹 + 落盘回执**,四态 `replay / conflict / uncertain / expired`(`src/host/requests.js:41-50`、`73-138`);回执在真正发送**之前**写盘(`src/host/requests.js:91-96`),所以重启不会把请求发两遍。 7. **`group_goal` 的 pass/complete 能拦截,且不用改上游。** 三条官方钩子:`ctx.tools.guard`(同步拒绝,根 ctx 注册即全局生效)、`tools/pre-execute`(异步 waterfall,可 deny/ask/cancel)、`tools/execute`(around-dispatch,可包住结果)+ `tools/post-execute`(改内容 / 给纠正反馈)。**参数是深冻结的,改不了参数**。 8. **同名覆盖不可行。** team tools 注册在每个 Bot Session 自己的 scope(`src/host/tools.js:765-777`、`808-896`),scoped 注册遮蔽 global(`dsh-tools/lib/index.js:3055-3075`),同层重名直接抛错(`dsh-tools/lib/index.js:2731`)。所以既不会 boot 冲突,也无法用同名全局工具劫持 `group_goal`。 9. **记忆是明文目录,隔离很弱**:`memory/team`、`memory/groups/`、`memory/bots/`(`src/host/memory.js:1-10`、`96-110`)。Main Bot 可读写任何 Bot 的记忆(`src/host/memory.js:406-411`);任何 Bot 可 `recall` 非 private Bot 的记忆(`src/host/memory.js:1129-1137`)。 10. **Web UI 是 client 插件**,产物 `client.js`(1.7 MB,`window.__ModuleLoader__.load({id:'ds-bot'})`);HTTP 只有 `POST /api/bot` 一个路由(`src/host/channel.js:753-764`)。第三方要在 DS Bot 页面里加卡片,**现成入口只有 settings 子插槽**(`src/client/settings-shell.js:22-32`),主对话区被 DS Bot 以最低 priority 独占。 --- ## 1. `create_bot` / `update_bot`:字段、模型、Session 创建与定位 ### 1.1 `create_bot`(`src/host/tools.js:324-360`) | 字段 | 必填 | 说明 | |---|---|---| | `name` | ✅ | ≤40 字符,团队内唯一(`src/host/roster.js:178-184`) | | `role` | ✅ | ≤24 字符(`src/host/roster.js:205-220`) | | `instructions` | ✅ | 系统提示词正文 | | `brief` | | 首次 kickoff 用的任务说明(`src/host/roster.js:227-237`) | | `model` | | 全 ref(`provider/model`)或唯一 id/name(`src/host/models.js:161-174`) | | `effort` | | 需模型支持,否则永不发送(`src/host/models.js:191-195`) | | `work_dir` | | 该 Bot 的私有工作目录 | | `section` | | 侧栏分组(仅用户/Main 可改,`src/host/roster.js:367-369`) | | `avatar` | | 头像规格 | 创建权限:只有 Main Bot 能建 Bot(`src/host/tools.js:341`)。 **模型选择(含 team 默认与回退)** 在工具层先算一次(`src/host/tools.js:351-353`): 1. 可用集合 `served` = catalog 里 `needsKey !== true` 且不是 local agent 的 ref; 2. `fallback = [state.prefs.defaultBotModel, creator.model]` 里第一个落在 `served` 的; 3. `model = args.model || fallback`。 随后 `rt.createBot(...)`(`src/host/tools.js:354`)进入 `src/host/roster.js:186-256`: - `modelRef = model ? await rt.resolveModel(model) : pickModel ? undefined : await rt.defaultBotModel()`(`src/host/roster.js:189`)——**首位 Main Bot 走 `pickModel:true`,故意不选模型,等用户在聊天里选**(`src/host/roster.js:932-941`); - 有模型时:`save()` → `scopeTools()` → `waitForModel(bot)` → `applyModel(bot)` → `sendKickoff`(`src/host/roster.js:243-256`),失败回滚会删 `state.bots[id]`、移出 `mainBotIds`、`archiveSession(id)`(`src/host/roster.js:257-268`)。 ### 1.2 `update_bot`(`src/host/tools.js:362-408`) 可设字段:`bot`(省略=自己)、`name`、`role`、`instructions`、`color`、`avatar`、`model`、`effort`、`work_dir`、`section`(`src/host/tools.js:366-375`)。 权限:**每个 Bot 可改自己,只有 Main Bot 能改别人**(`src/host/tools.js:385`);`section` 只有用户或 Main 能改(`src/host/roster.js:367-369`);`browserGrants/private` 只有用户能改(`src/host/roster.js:361-366`);换 engine 需要用户显式 `changeEngine:true`(`src/host/roster.js:388-390`)。写入走 `rt.updateBot(id, patch, self, exec.agent?.id)`(`src/host/tools.js:400`),内部:`resolveModel` → 改名字时 `ctx.sessionTitle.rename` → `setPermission` → `save()` → 模型变了则 `applyModel(bot,{force:true})`(`src/host/roster.js:358-483`)。 ### 1.3 模型:每 Bot 独立 + team 默认 + 不可用回退 - 「每 Bot 独立」落在 `bot.model` + `bot.appliedModel` + `bot.appliedEffort`(`src/host/models.js:250-269`); - 「团队默认」= `state.prefs.defaultBotModel`,`defaultBotModel()` 只在它仍被 catalog 服务时采用,否则用 `pickDefault()`(先 DSH 默认模型,再第一个可用)(`src/host/models.js:132-148`); - 「不可用回退」= `desiredModel(bot)`:`bot.model` 仍在 catalog → 用它;否则若 `bot.appliedModel` 仍可用 → 用它;再否则 `pickDefault()`(`src/host/models.js:180-186`); - 某个路由整体被拒(`routeRefused`)时,所有 pin 它的 Bot 清 `appliedModel` 并强制重选(`src/host/models.js:306-323`); - **群 Session 也跟着换**:`applyModel` 遍历 `rt.groupSessionsOf(bot.id)` 逐个 `selectSessionModel`(`src/host/models.js:257-262`)。 ### 1.4 agent/session 怎么建、怎么定位 - **建**:`createSession(title,{dir})` 是唯一入口(`src/host/roster.js:86-99`)——`ctx.sessionController.create({workspaceId|cwd, ...botPreset()})` → `resolveAgent(sessionId)` → `ctx.sessionTitle.rename(...)`。Bot、群、成员群 Session 全走它。 - **Bot Session 的定位**:`bot.id` 就是首段 Session id;`bot.sessionId` 是当前段;`chatOf(botId) = botOf(botId)?.sessionId ?? botId`(`src/host/store.js:454-463`)。 - **四个索引**(`src/host/store.js:454-463`,在 `indexSessions()` 里重建,`488-512`): - `chatOwners: sessionId → botId` - `groupOwners: sessionId → {botId, roomId}` - `roomOwners: sessionId → roomId` - `pastOwners: sessionId → {botId?, roomId?}`(归档段) - **反查**:`selfOf(sessionId) = chatOwners.get(id) ?? groupOwners.get(id)?.botId ?? pastOwners.get(id)?.botId`(`src/host/store.js:515-518`)——这就是 `group_goal`/`message_bot` 判断「我是谁」的唯一方式;`isBotSession(id) = chatOwners.has(id) || groupOwners.has(id)`。 - `roster.js` 只把「创建/改名/删除」挂到 rt(`src/host/roster.js:943-948`),**没有导出 `createBot` 的底层 Session 细节**。 --- ## 2. 群:创建、admin、members、room loop、成员隐藏 Session ### 2.1 `create_group`(`src/host/tools.js:495-523`) - 字段:`members`(必填,其他 Bot 的精确名,自己自动加入)、`name`、`notice`(≤2000,全员共享指令)、`admin`、`mode`、`section`; - 权限:**仅 Main Bot**(`src/host/tools.js:510`); - admin 默认 = 自己(`src/host/tools.js:513`),`members = [...new Set([self, ...bots, admin])]`(`515`); - 落库:`rt.createRoom({members, name, notice, mode, admin, section, createdBy})`。 ### 2.2 `update_group`(`src/host/tools.js:525-587`) 字段:`group`、`name`(空串=恢复按成员命名)、`notice`(空串清除)、`add_members`、`remove_members`、`admin`(`"none"` 清空,仅 Main)、`mode`、`work_dir`(仅 Main)、`section`(仅 Main)。权限:Main 可改任意群,群 admin 只能改自己的群(`src/host/roster.js:683-719`)。改文件夹/加人时先 `rt.approveFolder(...)`(`src/host/tools.js:565-571`)。`delete_group` 仅 Main,且群在回合中会拒绝(`src/host/tools.js:589-604`)。 ### 2.3 群的两层 Session | Session | 谁 | 用途 | 证据 | |---|---|---|---| | `room.id` / `room.sessionId` | 群自己 | 只跑 `group_relay`,**不咨询模型**(`llm/stream` 被拦成 relay) | `src/host/roster.js:638-677`、`src/host/groups.js:1564-1575` | | `room.sessions[botId]` | 每个成员 | 该成员在这个群的隐藏 Session,有完整 system prompt + 全量 team tools | `src/host/store.js:442-453`、`src/host/groups.js:310-344` | `buildRoom`:`createSession(title)` 建群 Session(`src/host/roster.js:642`)→ 写 `room` 对象(`651-662`)→ `save()`(`664`)→ `resolveAgent(id)`,**这一步才把 `group_relay` 挂进该 Session 的 scope**(`666`),失败回滚 `archiveSession`(`669-676`)。 成员隐藏 Session(`groupSessionFor`,`src/host/groups.js:310-344`): 1. 已有则只 `ensureCapabilities` 返回; 2. 否则 `rt.createSession(\`${member.name} · ${room.name}\`, {dir: rt.workDirOf({botId, roomId})})`(`317`); 3. 竞态(成员被删/群被删/别人抢先)会归档新 Session 再重试或放弃(`321-326`); 4. 写 `room.sessions[member.id] = id` + `groupOwners.set(id,{botId,roomId})`(`327-328`); 5. 选模型:`desiredModel` → `desiredEffort` → `selectSessionModel`(`330-335`);应用权限(`336`);`save()`(`338`);`resolveAgent(id)`(`340`,挂 scoped tools)。 ### 2.4 room loop `group_relay`(`src/host/groups.js:959-963`)是群里唯一工具,`execute` 做这些事(`964-1109`): 1. `rt.load()`;`room = rt.roomOf(exec.agent?.id)`,非群 Session 返回 `{error:'Not a group chat'}`(`967`); 2. 取 `rt.roomInbox.get(room.id)` 队列并清空(`971-972`);丢弃过期 goal 帖(`977-984`); 3. 把用户/成员发言写进 `room.log`(`995-1007`)→ `save()`(`1008`)→ `rt.goalUserMessage?.(room.id)`(`1009`); 4. 选出 speakers / batch(`1013-1045`),构造 `round`(`1046-1076`); 5. `rt.roomProgress.set(exec.callId, round)`(`1101`)→ `runRound(...)`(`1103`)→ finally 删除(`1106-1108`)。 回合内的补发走 `postToRoom`:**有 round 在跑就只追加日志 + 推 replies,不新开 turn**;没有 round 才 `resolveAgent(sessionOfRoom(room)).followup(...)`(`src/host/groups.js:1300-1329`)。回合结束 `reportRound` 把汇总用 `rt.deliver({role:'report'})` 发回发帖 Bot(`1540-1562`)。 --- ## 3. `message_bot`:完整投递路径 ### 3.1 参数(`src/host/tools.js:166-187`) `to`(必填,精确名)、`message`(必填)、`reply_to ∈ {me,user}`、`when ∈ {now,queue}`、`request_id`(≤200 字符,自定义幂等名)。 ### 3.2 幂等链路(`src/host/tools.js:201-230` + `src/host/requests.js`) - 键 = `caller + context + name`,context 是 `'chat'` 或 `` `room:${room.id}` ``(`src/host/tools.js:201-204`);指纹 = 规整后 payload 的 sha256(`src/host/requests.js:29`); - `knownRequest()` 命中直接回执,不再发送(`src/host/tools.js:222-223`); - 四态文案:`replay` 给回执原文;`conflict` / `uncertain` / `readonly` **抛错**(`refuse`,工具显示为失败);`expired` 返回说明文本(`src/host/tools.js:213-220`); - `admitRequest()` 先写 `pending` 并 `save({required:true})`,再执行 `work()`;`work` 抛错则记 `uncertain` 并 rethrow(`src/host/requests.js:73-138`)。**这就是「失败后不会自动重发」的实现**:结局不明宁可不发。 ### 3.3 群内路径(不投递) `src/host/tools.js:225-230` → `callInGroup`(`155-159`): - `groupRefusal` 先检查目标是否本群成员,非成员直接拒绝(`149-153`); - `rt.roomStepText(exec.agent.id, …, '@Name …', false)` 把这条消息写成**本群当前回合的一个步骤行**,等于在该群里写 `@Name`,目标成员参与的是这个群回合; - 返回文案明确:「Nothing went to its own chat.」(`158`)。 **结论:在群里 `message_bot` 既不入队也不 followup,它只影响本群回合。** ### 3.4 私聊路径(真正的投递) `src/host/tools.js:242-293`: 1. 防环:本回合已经在该群 @ 过对方就拒(`231-233`);对方正在等我的结果就拒(`238-241`); 2. `chat = rt.chatOf(target.id)` → `agent = await rt.resolveAgent(chat)`(`245-246`); 3. **未读请求合并**:`unreadRequest(agent, sender.id, toUser)` 找 inbox 里同发送者、同 audience 的未读 request;同 work 或 toUser 时合并(`250-258`),从 inbox 移除旧消息(`257`)并复用它的 `exchangeId`(`261`); 4. 过长文本先 `rt.attachLong` 转附件(`253`);转不了就直接返回「Not sent: … too long」(`256`); 5. `steer = (args.when !== 'queue' && !toUser) || (joins && earlier.steered)`(`260`)——**默认 now → steer(在下一步被打断读到);queue 或 reply_to=user → followup(排队)**; 6. `rt.openWork(exchangeId, {from,to,parent})`(`263`,非 toUser); 7. `rt.deliver({fromId, toId, text, files, length, role:'request', steer, exchangeId, merged?, audience?})`(`265`); 8. 失败:rethrow;只有目标 Bot 已不存在才 `rt.dropWork(exchangeId)`(`266-272`)。 `rt.deliver` 的真身(`src/host/delivery.js:60-116`): - `to = rt.botOf(toId)` 不存在即 throw(`63`); - `targetSessionId = sessionId ?? rt.chatOf(toId)`(`86`)→ `ensureCapabilities`(`87`)→ `resolveAgent`(`88`); - 文本前加 `headerFor(...)` 头行(`91-98`,如 `[Message from X]`、`audience==='user'` 时带「the user sees your reply here」); - **`steer ? agent.steer(message) : agent.followup(message)`**(`99-100`)→ `await ctx.sessions.flush(agent.session)`(`101`); - role ∈ `{request,reply,stopped}` 时写 `state.exchanges`(`102-114`),`void rt.save()`。 ### 3.5 返回给调用者的内容(`src/host/tools.js:273-291`) 四种正文,按 `toUser` / 在跑+steer / 在跑 / 空闲区分: - `Delivered to X. It will answer the user in its own chat; nothing comes back to you…` - `Delivered to X while it is working: it reads your message at its next step and answers once that work is done…` - `Queued for X: it reads your message after its current work…` - `Delivered to X. Its reply will arrive later as a new message; do not wait for it.` 再拼 notes:合并提示、对方当前状态(`rt.statusOf`)、handoff 归属提示(`281-285`)。**最后一句很重要**(`287-291`):如果对方还有别处(群 / 其他段)在跑,会明确说「你的消息到不了它在 X 的工作」,并(仅对 Main Bot)提示可用 `stop_bot`。 ### 3.6 失败 / 离线 - 目标名不存在 → 返回文本(不抛错)(`src/host/tools.js:193`); - 目标是「不在线的段」(Session 被归档)→ `resolveAgent` 抛错,工具显示失败; - 投递中抛错 → rethrow,`state.works` 里的 work 保留,等重启后 `resume.js` 重试(`src/host/tools.js:266-272` 注释); - 没有任何「离线队列」:DSH 侧的 inbox/queue 才是队列(`agent.inbox.nextStep/nextTurn`,`src/host/tools.js:120-128`)。 --- ## 4. `group_goal` 与拦截面(重点) ### 4.1 注册位置与机制 - 工具在 `src/host/goals.js:672-804` 用 `rt.teamTools.push(defineTool({name:'group_goal', ...}))` 注册;`action` 枚举 = `show/draft/start/revise/task/pass/rework/complete/pause/resume/stop`(`677`)。 - `rt.teamTools` 是一个纯数组(`index.js:78`),由 `src/host/tools.js:808-896`(`shareBotTools`)**逐个 `agent.ctx.tools.register(def)` 注入到每个 Bot Session 自己的 scope**,并保存 disposer;`relayOnly` 的群 Session 只挂 `group_relay`(`834`/`869`)。 - 作用域总纲写在 `src/host/tools.js:765-777` 的注释里:team tools 只进每个 Session 自己的 scope、绝不进全局层;因此**别的插件的同名全局工具既不会 boot 冲突,也不能在这些 Session 内遮蔽它们**。 - 工具执行时 `self = rt.selfOf(exec.agent?.id)` → `botOf` → `roomOf(groupOwners.get(...).roomId)`,群内可省 `group` 参数(`src/host/goals.js:717-729`);权限:仅 admin 或 Main Bot 能改(`730-739`)。 ### 4.2 状态与动作是纯函数,没有内部钩子 - 目标状态存在 `room.goal`(文件头注释 `src/host/goals.js:1-4`),历史归档到 `room.pastGoals`(`53-58`)。 - `passGoal`(`281-300`):必须带 `evidence`(≤2000),然后把当前 stage 置 `passed`、所有 task 置 `done`、`goal.current += 1`、下一 stage 置 `active`,写 `touchGoal(goal,{kind:'pass',...})`。 - `completeGoal`(`329-348`):所有 stage 必须 passed,`evidence` + `summary` 必填,`status='complete'`。 - `stopGoal`(`370-384`):`reason` 必填,`status='stopped'`。 - 这些函数**没有 after/before 钩子**,`rt` 上只暴露 `goalBlock / goalLedger / goalDraft / goalControl / goalDrive / goalSettled / goalUserMessage / goalUserStopped / goalTaskWorking / goalTaskReported / goalTaskReset`(`src/host/goals.js:806-811`)——都是读或驱动,**没有「拦截 pass」的入口**。 ### 4.3 `ctx.tools.guard(...)` 的语义与签名 宿主实现(解包后):`dsh-tools/lib/index.js:3008-3031`,可读镜像 `dsh-tools/lib/types/index.js:521-547`。 ``` guard(guard: (exec) => string | undefined | void): Disposer ``` 文档原文(`dsh-tools/lib/types/index.js:522-529`): - 「Register a monotonic guard **after** the extensible `tools/pre-execute` waterfall.」 - 「A **plain-context** guard applies **globally**; one registered through **`agent.ctx`** applies only to that agent.」 - 「Any matching guard may **deny by returning a reason**, while **no guard can force-allow** a call another guard denied.」 - 「synchronous check」(同步,不能 await)。 执行顺序(`dsh-tools/lib/index.js:3024-3031`):**先全局层,再 scope 链(farthest first)**,第一个返回字符串的即拒绝。 拒绝的落地效果(`dsh-tools/lib/index.js:3321`、`3337-3352`):`tools/pre-execute` waterfall 得到 `{kind:'allow'}` 之后才跑 guard;拒绝时返回 `content:[{type:'text',text:'Error: '}], isError:true` —— 模型看到一条失败结果和你的理由,**工具体根本没执行**,`room.goal` 不会被改。 **自家实证**:ds-bot 自己就用根 ctx 的 guard 拦 Bot Session 内的 `ask_user_question` / 委托类工具(`src/host/tools.js:1034-1040`),并配合 `isBotSession(exec.agent?.id)` 判断——说明「根 ctx 注册的 guard 对 Bot 群 Session 里的工具调用生效」是上游自己依赖的行为。 ### 4.4 另外三条钩子(都在 dsh-tools 里) | 钩子 | 类型 | 能不能改 | 证据 | |---|---|---|---| | `tools/pre-execute` | waterfall `(exec) → {kind:'allow'\|'deny'\|'ask'\|'cancel', reason?}` | 可 deny / 可 ask 审批 / 可 cancel | `dsh-tools/lib/index.js:3321-3338` | | `tools/execute` | **around-dispatch waterfall** `(exec, next) → result` | 可包住 `next()` 改结果,甚至不调 `next` 直接给结果 | `dsh-tools/lib/index.js:3425-3428`;`dsh-tools/lib/types/index.js:980-985` | | `tools/post-execute` | waterfall `(exec, result) → {kind:'accept', content?/value?} \| {kind:'block', feedback}` | accept 可换 `content`(文本)或 `value`(仅成功结果);block 把成功变失败并给「纠正反馈」 | `dsh-tools/lib/types/index.js:1142-1188` | | `tools/pre-execute` 参数 | — | **不可改**:`exec.arguments` 在 `createExecution` 里被 `snapshotJsonValue` + `deepFreeze` | `dsh-tools/lib/index.js`(createExecution,约 3260-3290) | `tools/execute` 是唯一能拿到「结果」的钩子,签名形态就是 `ctx.on('tools/execute', async (exec, next) => { const r = await next(); … return r })`。 ### 4.5 同名工具重复注册,谁生效 - `dsh-tools/lib/index.js:2968-2983`:注释「Scoped tools **shadow** globals; duplicates **within one layer** and the reserved `run_code` name fail.」 - `view(scope)`(`dsh-tools/lib/index.js:3055-3075`):先继承 global + 祖先层(受 `restrict` 过滤),**最后用本层(own)的注册 `visible.set(name, definition)` 覆盖** → scoped 覆盖 global,且**互不报错**。 - 同层重名直接抛:``tool "${name}" is already registered in this scope``;全局重名提示「for a per-agent variant, register through that agent's `agent.ctx` instead」(`dsh-tools/lib/index.js:2731`)。 - `restrict({allow,deny})` **只过滤继承层,不动本层注册**(`dsh-tools/lib/types/index.js:555-560`、`2986-2988`),所以**无法用 `restrict` 把 ds-bot 挂在 Bot scope 里的 `group_goal` 掩掉**(名字甚至会被判为 unknown 而抛错:`restrict` 只认继承来的全局名,`dsh-tools/lib/index.js:2991-3005`)。 ### 4.6 结论(明确回答「能拦截 / 只能改上游 / 有其他钩子」) **能拦截,且不需要改上游。** 推荐顺序: 1. **首选 `ctx.tools.guard`**(根 ctx 立即注册,返回 disposer):同步、便宜、不可被 Bot scope 覆盖,且拒绝发生在工具体之前,`room.goal` 状态干净。典型判定: ``` exec.name === 'group_goal' && ['pass','complete'].includes(exec.arguments?.action) ``` 返回一句中文/英文理由即可(模型能看到,用户也能在工具失败卡片里看到)。要定位「哪个群、哪个 Bot」,用 `exec.agent.id`(Session id)去查 `~/.dsh/bot/state.json` 的 `chatOwners/groupOwners`(见 §6/§7 的只读重建办法)。 2. **需要审批/异步判断 → `tools/pre-execute`**:可返回 `{kind:'ask'}` 走 DSH 审批,或 `{kind:'cancel'}` 直接取消。 3. **需要「先让伴侣做一遍,再让上游做」→ `tools/execute`**:包 `next()`,或在 `next()` 前做自己的副作用(记账、外部系统校验)后决定是否调用。 4. **需要改写给模型的文本 / 把成功改成失败并给纠正指令 → `tools/post-execute`**:`{kind:'block', feedback}`。 **做不到、必须改上游的**: - 改写参数(深冻结); - 替换 `group_goal` 的实现(同 scope 重名会抛错;不同 scope 只能遮蔽全局,遮不到 scoped); - 改 goal 状态机本身(`passGoal` 里 `goal.current += 1` 这类语义); - 伪造群日志 / announce(`goalControl` 才会 `announce`,工具层拒绝后没有任何 announce 机会)。 **其他可用钩子**:`ctx.on('tools/result', ...)`(只观察,`dsh-tools/lib/index.js:3509-3513`)、`tools/change`(工具表变更,`2784`)、`agent/created`(拿到 agent,`src/host/tools.js:1042-1052`)。 --- ## 5. 记忆分层:存储、读取 API、Main Bot 跨 Bot 读写 ### 5.1 三层目录 `/memory/`(`home` 默认 `DSH_HOME/bot`,`index.js:69`;`src/host/memory.js:96-102`): | 层 | 路径 | 谁写 | |---|---|---| | 团队 | `memory/team/MEMORY.md` + topics | Main Bot 或任一**群 admin**(`src/host/memory.js:384-390`) | | 群 | `memory/groups//MEMORY.md` + topics | 该群成员(`src/host/memory.js:406-411`) | | Bot | `memory/bots//MEMORY.md` + topics | 自己;**Main Bot 可写任何 Bot**(`409-411`) | 私有 Bot 另有自己的 `journal.jsonl`(`1-10`、`112-118`),记录每次变更以便 `tidy/undo`。 ### 5.2 工具与 scope 语法 - `remember`(`src/host/memory.js:1065-1102`):`{text, replace?, topic?, until?, pin?, always?, scope?}`;team 且未 `always` 且无 topic → 落到共享 topic(`1092`)。 - `forget`(`1104-1125`):`{entry, topic?, scope?}`。 - `recall`(`1141-1164+`):`{query?, topic?, scope?}`;帮助文本明写「or a Bot's name to read that Bot's memory, **unless it is private**」(`1147`)。 - scope 词法(`392-405`):`own|me|自己`、`group|群`(必须人在该群会话)、`team|团队`、否则按名字 `rt.findBot`。 - 默认读取范围(`1129-1138`):`[own, TEAM]`;在群内为 `[own, group, TEAM]`。 ### 5.3 隔离风险(必须写进设计约束) 1. **Main Bot 跨 Bot 写**:`writeDenied` 里 `scope.botId !== botId && !rt.isMain(botId)` 才拒绝(`src/host/memory.js:406-411`)——Main Bot 可以直接改任何成员的记忆,没有审计、没有二次确认。 2. **跨 Bot 读更松**:只有 `rt.isPrivate(scope.botId)` 才拒绝(`1134-1136`)——**非私有 Bot 的记忆,任何 Bot 都能 `recall` 到**。 3. **文件层没有隔离**:都是明文 Markdown,路径可由 `botId/roomId` 推出(`105-110`);Bot 的 Session 有 `read_file`/shell 能力时,隔离只靠 DSH 权限预设(`src/host/permissions.js:1-5`:Bot 预设是「Bot 自己的」,群可覆盖)。 4. 群记忆的「keeper」= admin,否则首个成员(`123`),并发写靠 `queued()` 串行 + tmp/replace(`160-174`),但没有跨进程锁。 **对三省六部的含义**:伴侣若要保证「记忆不被别的 Bot 读到」,必须自己做(独立目录 + 自己的工具),不能依赖 DS Bot 的 scope 检查。 --- ## 6. `state.json`:结构与保存时机 ### 6.1 位置 `statePath = join(home, 'state.json')`,`home = config.home ?? join(dshHome, 'bot')`(`index.js:67-71`)。 ### 6.2 顶层结构(`src/host/store.js:22-23` 的 EMPTY) ``` version: 1, workspaceId?, mainBotIds: [], bots: {}, rooms: {}, agents: {}, privateArchives: [], sections: [], capabilities: {items:{}}, exchanges: [], exchangeTurns: {}, works: {}, requests: {}, questions: {}, views: {}, closedCards: {}, closedViews: {}, prefs: {}, switching: {}, revision: 0 ``` 运行时还会写入的字段(由各模块构造): - `bots[id]`:`id,name,role,color?,avatar?,model?,appliedModel?,effort?,appliedEffort?,workDir?,sectionId?,instructions,createdAt,createdBy,capabilities,permission?,sessionId,segments,kickoff`(`src/host/roster.js:205-220`、`src/host/models.js:264-267`) - `rooms[id]`:`id,name,named?,sectionId?,members[],admin,mode,notice,createdAt,createdBy,workDir?,permission?,sessions{botId:sessionId},segments,parts,log,seq,seen,memberDirs,goal,pastGoals[]`(`src/host/roster.js:651-662`、`src/host/groups.js:255-265`、`src/host/goals.js:1-4`) - `prefs.defaultBotModel`(team 默认模型,`src/host/models.js:144-148`) ### 6.3 保存时机 - **没有定时器、没有防抖**:所有落盘都是模块里显式 `await rt.save()`(`split` 在几十处)。`save()` 自己串行排队(`writing`)(`src/host/store.js:371-427`)。 - 每次 `save()`:`indexSessions()` 先重建索引 → `state.revision += 1` → `state.exchanges` 截断到 `MAX_EXCHANGES` → 写 `state.json..tmp` → `replaceFile(...)` 原子替换(`src/host/store.js:371-427`)。 - 关键时机会 `save({required:true})`:例如 `admitRequest` 写幂等回执前(`src/host/requests.js:96`)——失败就直接抛,避免「发了但没记账」。 - 生命周期:`ctx.effect(()=>()=>{stopped=true; return writing.finally(()=>lock.release())})`(`src/host/store.js:429-432`)。 ### 6.4 单写者锁与多窗口 `homeLock(join(home,'state.lock'))`(`src/host/store.js:49`);`claimLock()` 拿不到就置 `holder`,`readOnly()` 返回「The Bot team in … is open in another dsh … This window shows the team but cannot change it」(`63-68`)。**同一 home 的第二个 runtime 一定变只读**——这条对伴侣插件自建 `createRuntime` 是致命的。 ### 6.5 重启恢复 1. `load()` 是幂等缓存:`claimLock → adopt(readFileState()) → 必要时 save → 对 stale room void retitleRoom`(`src/host/store.js:265-281`); 2. `readFileState()`:ENOENT → 空;JSON 坏 → 备份 `state.json.broken-`;`version !== 1` → stuck(提示升级 DS Bot)(`72-108`); 3. `adopt()` 以 EMPTY 打底再 `Object.assign`,修字段类型,最后 `indexSessions()`(`112-263`); 4. `indexSessions()` 重建四个 Map + `rt.indexAgents()` + `rt.syncScopedTools()` + `restoreCurrent()`(把被 DSH 归档的当前段 `unarchiveSession` 拉回来)(`469-512`); 5. `roster.bootstrap()`:`await rt.load()` → `syncModels()`;已有 Main Bot 就返回,否则建第一个 Main(无模型,等用户选)(`src/host/roster.js:932-941`); 6. 热重载(不是重启):`createRuntime` 末尾 `void rt.adoptLiveWork?.()` 接管仍存活的 turn / 子 agent(`index.js:92`)。 --- ## 7. `createRuntime` 返回的 `rt`:可复用钩子清单与获取途径 ### 7.1 签名 `export function createRuntime(ctx, config)`(`index.js:67`),返回 `rt`: ``` rt = { ctx, config, dshHome, home, statePath, teamTools: [], defaults: {mainName, mainRole} } ``` 之后各模块 `install(rt)` 往里 `Object.assign`(`index.js:84-92`)。 ### 7.2 关键钩子(按域) | 域 | rt 上的东西 | 证据 | |---|---|---| | 存储/索引 | `state, load, save, refresh, readOnly, own, onSaved, botOf, roomOf, isMain, chatOf, sessionOfRoom, selfOf, isBotSession, chatOwners, groupOwners, roomOwners, pastOwners, groupSessionsOf, findBot, findRooms, isAdminOf, closeCard` | `src/host/store.js:581-586` | | 投递 | `resolveAgent, deliver, exchangeText, attachLong, fileText` | `src/host/delivery.js:174` | | 名册/群 | `createSession, createBot, updateBot, duplicateBot, createRoom, updateRoom, deleteRoom, setMain, deleteBot, roomBusy, retitleRoom, bootstrap, …` | `src/host/roster.js:943-948` | | 群运行时 | `logRoom, onRoomLine, recentGroupLines, keepGroupLine, postToRoom, lateRoomReply, roomStepText, withRoomSteps, workingInRoom, roomBatchPending, stopMemberWork, stopRoomWork` | `src/host/groups.js:266-280`、`1329`、`1451-1504` | | turn/会话 | `live, liveOf, roomWaiters, roomProgress, roomInbox, stopRoomTurn, stopChat, stopSubagents, hasSubagents, doingOf, releaseBot, resumeBot, …` | `src/host/turns.js:1241` | | 目标 | `goalBlock, goalLedger, goalDraft, goalControl, goalDrive, goalSettled, goalUserMessage, goalUserStopped, goalTaskWorking, goalTaskReported, goalTaskReset` | `src/host/goals.js:806-811` | | 模型 | `catalog, defaultBotModel, resolveModel, desiredModel, applyModel, selectSessionModel, syncModels, routeRefused, …` | `src/host/models.js:325-329` | | 记忆 | `renewMemory, archiveBotMemory, archiveGroupMemory, memoryEndpoint, memoryReviews, memoryNews, botShot, tidyMemoryNow` | `src/host/memory.js:1739-1742` | | 工具 | `pickRoom, hideBotUnusedTools, syncScopedTools, addTeamTool, removeTeamTool, reapplyToolMasks` | `src/host/tools.js:1234` | | 权限 | `permissionCatalog, applyPermission, setPermission, cleanRoomPermission, setRoomPermission` | `src/host/permissions.js:116` | | 幂等 | `requestIdentity, knownRequest, admitRequest` | `src/host/requests.js:140` | | Agent 入口 | `agentOf, addAgent, createAgentSession, adoptAgentSession, archiveAgentSession, renameAgentSession, removeAgent` | `src/host/agents.js:128` | `rt.roomProgress` 是 `Map`(`src/host/turns.js:174-196`),round 结构见 `src/host/groups.js:1046-1076`——这是外部观察「群里谁在跑」最细的钩子。 ### 7.3 伴侣插件怎么拿到 `rt`? 结论:**拿不到**。 - `apply(ctx, config = {}) { createRuntime(ctx, config) }`(`index.js:63-65`)——**连返回值都没写**,`rt` 直接落进垃圾回收; - 全仓没有 `ctx.set('...', rt)` / `ctx.provide(...)`(已 grep,`src/host` 里只有 `ctx.plugin` 三处,且都与 rt 无关); - 因此第三方只能: 1. `ctx.get(...)` 拿 DSH 服务(ds-bot `inject` 列出的那些:`tools, sessions, sessionController, workspaceRegistry, connection, systemPrompt, sessionTitle, llm`,`index.js:54`); 2. `ctx.on('agent/created', ({agent}) => ...)` 拿 `agent`(ds-bot 自己就这么做,`src/host/tools.js:1042-1052`);DSH 所有 agent 事件都带 scope carrier(`dsh-agent/lib/index.js:230-283`),无 tag 监听器全局准入(`dsh-scope/lib/index.js:315-337`); 3. 只读 `state.json`(**推荐**,见下); 4. 改上游加一行 `ctx.set('dsbot', rt)`(最小改动,但就是 fork)。 **只读 state.json 的正确姿势**:路径 = `DSH_HOME/bot/state.json`(`index.js:69`;`DSH_HOME` 默认 `~/.dsh`,可用 `folders.dshHomeOf` 同款逻辑)。它是原子替换写入的,读到的要么旧要么新,不会半截;`state.lock` 只影响写,不挡读。拿到后自己重建 `chatOwners/groupOwners/roomOwners`(等价 `indexSessions()`,`src/host/store.js:488-512`),就能把 `exec.agent.id` 映射到 `{botId, roomId}`。注意别写这个文件(会触发 `ELOCKLOST`)。 --- ## 8. DS Bot 页面如何进入 Web UI;第三方能否在页面里加卡片 ### 8.1 打包与注册 - `package.json`:`"dsh": {"client": {"platform": "web" }, "bundle": {"patch": "./cordis.patch.yml"}}`(`package.json:58-65`);`exports` 含 `"./client": "./client.js"`(`26-31`)。 - `client.js` 是 esbuild 产物:首行 `// Generated from src/client by npm run build (scripts/build-client.mjs). Do not edit by hand.`,随后 `window.__ModuleLoader__.load({ id: 'ds-bot', factory: (require) => { ... } })`。1,712,874 B(`office.js` 318 KB、`web-search.js` 42 KB 同理)。 - 构建脚本 `scripts/build-client.mjs`(`package.json:45`);`src/client/` 96 个文件是全部 UI 源码。 - `cordis.patch.yml`:insert `bot`(name `ds-bot`)、insert `web-search-auto`(name `ds-bot/web-search`);`id: web` 的 `searchProvider: auto, fetchProvider: http`;**`id: ui-settings-general disabled: true`**——DS Bot 自己接管设置壳。 ### 8.2 页面如何「占住」UI - `src/client/index.js:60` `inject = ['sessions','uiWorkspace','uiConversation','slots','theme','layout']`; - 用 `ctx.slots.inject(name, () => ctx.slots.register(...))` 抢占 slot;`BOT_PRIORITY = -100`(`index.js:961`),注释说明起点远低于插件常用的 `-10`,且低于已占住该 cell 的条目; - `freePriority(entries,{priority})`(`src/client/surface.js:77-85`):注释「The priority that puts an entry below every other entry of its cell (lowest renders). Another plugin that shadows the same cell at the same priority would make the registration throw; in a Bot surface the cell is DS Bot's.」 - 两种 surface(`src/client/surface.js:1-9`、`groupsFor`):`'bot'` 整屏替换 shell + conversation;`'agent'` 撤销所有替换,回到原生 DSH。模式存 localStorage,切换在 `index.js:588`、`1204-1254`。 - 被抢占的 slot 清单在 `src/client/index.js:1068-1142`(`sidebar.workspaces`、`conversation.chat.node` 的各类节点、`conversation.input.dock` 的各类面板、`sidebar.settings` 等)。 ### 8.3 HTTP 面 只有一个路由:`POST /api/bot`(`src/host/constants.js:22`),用 `ctx.connection.fetch.register({path, methods:['POST'], requestBody:'buffered', fetch})` 注册(`src/host/channel.js:753-764`);body 形状 `{endpoint, payload}`,前端 `src/client/api.js:1-42` 用相对路径 `api/bot` 调。 ### 8.4 第三方加卡片:可行 / 不可行 **可行的唯一干净入口:settings 子插槽。** `src/client/settings-shell.js:1-8` 注释写明:DS Bot 持有 `sidebar.settings`(DSH 的 `ui-settings-general` 被 patch 关掉),持有该座就**必须声明它的子插槽**,而「only the declaring entry may render them」,于是 DSH 自己的设置页仍然画在 DS Bot 的设置对话框里。声明的子插槽表 `SETTINGS_CHILDREN`(`src/client/settings-shell.js:22-32`): ``` settings.launcher / settings.trigger / settings.header / settings.close settings.action (list) / settings.section (list) / settings.section.icon (list, inline) settings.onboarding (list) / settings.general.item (list) ``` 所以:**在 `settings.section` 注册一个设置页、或在 `settings.general.item` 注册一行设置项,会直接出现在 DS Bot 的设置弹窗里**——这是「在 DS Bot 页面里加卡片」目前唯一现成、无需改上游的路径。 **不可行**: - 抢主对话区/侧栏:DS Bot 用最低 priority 占住这些 cell,同名 shadow 要么被压住、要么(同 priority)注册抛错; - 注册**新的** slot 名:DS Bot 的组件树是自己画的,除上面声明的子插槽外不会渲染任意新 slot;我们在 `src/client` 里没找到对外暴露的通用 outlet; - 直接在 `client.js` 里加东西:它是构建产物,且每次 `npm run build` 会被覆盖。 **要动主界面只能**:fork `src/client/*` 并重新 build(需 esbuild 与依赖,本环境无 node_modules),或在自研 client 插件里以更高 priority 反向覆盖 DS Bot(等于把 DS Bot 的 UI 全重做一遍)。 --- ## 9. 停止 / 撤销能力与取消语义 | 入口 | 作用域 | 语义 | 证据 | |---|---|---|---| | `stop_bot`(Main only) | 一个 Bot 的**所有在跑 Session**(私聊 + 各群) | 对每个 `rt.live` 里 turn 未结束的 session `agent.cancel({kind:'hook', reason:'ds-bot/stopped'})`,然后 `deliver({role:'stopped'})` 新起一轮说明原因 | `src/host/tools.js:297-322`;activeSessions `111-115` | | `rt.stopChat(botId)` | 单个 Bot 私聊 | turn / 子 agent 都没跑 → false;先 `stopSubagents`,再 `agent.cancel({kind:'user'})` | `src/host/turns.js:330-343` | | `rt.stopRoomTurn(sessionId, exchangeId)` | 单个群 Session 的特定交换 | 记 `stoppedRoomTurns`;匹配 exchangeId 才 cancel(hook),否则从 `inbox.nextStep/nextTurn` 里按 `exchangeId` 移除未投递消息 | `src/host/turns.js:313-326` | | `rt.stopMemberWork(roomId, botId)` | 某成员在某群 | 没在跑 → false;否则 `stopSubagents` → `cancel({kind:'user'})` → `goalTaskReset(...,'Stopped by the user')` → 静默 `stopped` 帖 | `src/host/groups.js:1451-1472` | | `rt.stopRoomWork(roomId)` | 整个群 | 先 cancel 群 relay Session 的 round,再对每个成员 `stopMemberWork`;**只停本群**,同 Bot 在私聊/别群继续 | `src/host/groups.js:1474-1500`(注释 `1476-1478`) | | `goalControl(roomId,{action:'stop'})` | 目标 + 整群 | `stopGoal` 改 `room.goal` → announce → save → `stopRoomWork` | `src/host/goals.js:552-592`(`579`) | | `group_goal` action `stop` | 目标 + 成员工作 | 改状态后 `post` 阶段对每个成员 `rt.stopMemberWork` | `src/host/goals.js:786-793` | | `delete_group` / `deleteRoom` | 群 | 回合中拒删;删除前 `stopRoomWork`,成员隐藏 Session 逐个 `dropGroupSession` | `src/host/tools.js:600`;`src/host/roster.js:805-827` | **取消语义要点**: - `agent.cancel()` 是 DSH 的 turn 取消,**会连带丢弃该 turn 排队中的消息**(`stop_bot` 的描述:`Its queued messages are dropped with the turn.`,`src/host/tools.js:299`); - 停止不是回滚:`group_goal` 的 `pass/complete` 一旦执行,`goal.current`/`status` 已经前进,**没有 undo**;只能靠 `rework`(重置成员 task、stage.reworks+1)、`revise`、`stop` 这类「前进式纠正」(`src/host/goals.js:302-327`、`217-254`、`370-384`); - `goalTaskReset(roomId, botId, note)` 只改当前 stage 里该成员的 task 状态为 `pending`(`src/host/goals.js:390-409` 的 markTasks 语义),不会撤销已 pass 的 stage。 --- ## 附 A:伴侣插件可落地的方案(不改上游) 1. **拦截守卫**:根 ctx 注册 `ctx.tools.guard(fn)`,命中 `exec.name === 'group_goal'` 且 `action ∈ {pass, complete}` 就返回理由。零依赖、同步、不可绕过。 2. **观测/记账**:`ctx.on('tools/execute', async (exec, next) => { const r = await next(); if (exec.name === 'group_goal') record(exec, r); return r })`——能拿到完整入参与结果。 3. **会话映射**:只读 `DSH_HOME/bot/state.json`,自建 `chatOwners/groupOwners` 反查(等价 `indexSessions`,`src/host/store.js:488-512`);**绝不写该文件**(锁 + `ELOCKLOST`)。 4. **界面**:DS Bot 设置弹窗里挂一页(`settings.section`)或一行(`settings.general.item`),见 §8.4;自建 HTTP 面按 `src/host/channel.js:753-764` 的 `ctx.connection.fetch.register` 形态注册自己的 path(注意 `POST /api/bot` 已被占)。 5. **需要「拦截后替它做事」**:在 guard 里拒绝,同时在 `tools/pre-execute`(先于 guard)或 `tools/execute` 里做副作用;顺序上 `pre-execute` 在 guard 之前(`dsh-tools/lib/index.js:3321` vs `3337`),适合「先记账再判可否」。 ## 附 B:必须改上游才能做到的事 - 改写工具参数、替换 team tool 实现、改 `room.goal` 状态机; - 在 `goal_*` 动作发生时插入官方 announce / 群日志(只有 `rt.goalControl` 与工具内 `announce` 会写); - 让 `group_goal` 在群自己的 relay Session 可用(目前群 Session 只有 `group_relay`,`src/host/tools.js:765-777`); - 让伴侣插件直接拿 `rt`(需要上游加 `ctx.set('dsbot', rt)` 或导出运行时注册表); - 在 DS Bot 主对话区加卡片(需要 fork `src/client` 并 rebuild)。 ## 附 C:未验证 / 待确认 - `groupSessionFor` 是否挂在 `rt` 上(`src/host/groups.js:310` 定义,但 `Object.assign` 列表里没看到); - `ctx.connection.fetch.register` 的同 path 冲突语义(第三方自建路由是否会被拒/覆盖)未在宿主源码核实; - `agent.cancel()` 丢弃排队消息的具体实现(在 `dsh-agent`/`dsh-session` 里),本文只引 ds-bot 的用法与文案; - `stop_bot` 对「子 agent 正在跑」的处理:`activeSessions` 只看 `rt.live.turn`,不看 `hasSubagents`(`src/host/tools.js:111-115`),可能漏掉只有子 agent 在跑的 Session; - 除 `settings.*` 外,是否还有其它被 DS Bot 声明并转发的子插槽(未穷举 `src/client` 全部 96 个文件)。