DS Bot 内部拆解：一个会话编排层是怎么搭起来的

01一切都是一次普通的 Session

插件的入口 index.js 极短：定义一个 21 项的 MODULES 数组，逐个调用 module.install(rt)，把函数挂到一个共享的运行时对象 rt 上。模块之间不直接 import 互相调用，而是运行时通过 rt 取用——于是注册顺序就是行为顺序。

// index.js
export const inject = ['llm','tools','systemPrompt','sessionController',
  'sessions','sessionTitle','workspaceRegistry','connection']

const MODULES = [diagnostics, store, models, turns, delivery, roster, agents,
  prompt, tools, chatIndex, groups, memory, parts, images, secrets,
  connectors, schedules, browser, usage, update, channel]

▸Bot 是怎么被「造」出来的

• 每个 Bot 就是 DSH 里的一个 root Session。团队名册、群聊、Bot 间消息日志全部落在一个 JSON 文件 state.json 里，重启即恢复——不新增任何 Session 事件类型。
• Session 的 id 有个约定：一个 Bot 的 id 永远等于它第一段私聊 Session 的 id，之后换段不变；bot.sessionId 才指向当前段。历史段列表 bot.segments 归档保留、仍可检索。
• 名册变更后，indexSessions() 重建三张内存映射：chatOwners（Session→Bot）、groupOwners（群会话→成员/群）、pastOwners（历史段→Bot）。之后每次 save() 都刷新。

▸系统提示词为什么是「一段」

整个身份提示只注册一个 section（order: 640，interpolate: false），文本只依赖渲染它的那个 Session 自己的 Bot 记录。因为前缀逐字节稳定，provider 的 prompt cache 才能命中；名册怎么变、别的 Bot 怎么改，都不影响这段前缀。

更细的一步：群聊里成员用的隐藏 Session，渲染的提示词与它私聊时完全相同。于是私聊和群聊共享同一份缓存前缀，群聊回合也绝不会读到该成员的私人上下文。

02一条消息的一生

DSH 的 Session 之间没有「同步调用」这回事。deliver() 做的就是把一段文本当成一条新的用户消息灌进对方 Session：

const agent = await ctx.sessionController.resolveAgent(sessionId)
agent.followup(createUserMessage({
  content: [{ type: 'text', text: `[Message from ${fromName}]\n${text}` }],
  source: { kind: SOURCE_KIND, form: 'relay', role, exchangeId, hop, replyTo },
}))
await ctx.sessions.flush(agent.session)

身份不是靠 API 参数传递的，而是靠消息头 + 一个结构化 source 对象双重编码：

▸回复怎么被路由回去

turns.js 订阅 session/event，用一张进程内的 live 表跟踪每个 Session 的当前回合：

• turn/start：记下回合号，认领触发它的那条 relay 消息。
• assistant/message：把这一回合产出的文本攒起来。
• turn/end：如果是被另一个 Bot 触发的请求，就用攒下的文本 deliver(role:'reply', hop+1) 回传。MAX_HOPS 限制 Bot 之间来回的层数，防止无限套娃。

▸「隐藏回合」与吉祥物状态

不是所有回合都该让用户看见。被 Bot 间消息触发的那些，会在 state.exchangeTurns[sessionId] 里打标，界面据此隐藏；群聊会话整体隐藏，所以无需打标。吉祥物「在干什么」则由实时的 tool/call 事件映射而来（sending / orbit / searching / working / thinking），只在进程内重建、从不落盘。

03上下文管家：不用内核压缩，自己决定怎么续命

DSH 自带的压缩在 Bot 会话上被完全禁用。取而代之的是一条按模型窗口算出来的水位线：

• usable = 声明窗口 − 回复预留(maxTokens)，上限不低于窗口一半；模型没声明窗口按 500,000 计。
• 回合结束时若越过 check line，就发起一次独立的小模型调用（预算约 6000 token）去读最近的若干条消息，只回答一件事。

// steward.js —— 只回一行 JSON，取「最后一个」带 action 的对象
{"action":"switch"|"compact", "reason":"一句话"}
//  switch  → 工作到了一个停顿点：换一段全新 Session
//  compact → 还在进行中：就地压缩旧消息，无缝继续

无论哪种，用户看到的始终是一个连续聊天、没有分隔标记。而「压缩了几次」会被真的数出来：管家提示里会告诉它「这段已压缩 N 次」，越压越倾向于把合理的停顿点算作终点——因为「摘要的摘要会丢更多细节」。越界溢出（超过 hard line 甚至窗口）时，直接换段、连笔记都来不及写。

被换掉的内容并没有消失：每个 part 都写进本地全文索引，Bot 用 read_own_chat 带着词或 part N 就能翻回去，返回的行都带锚点，例如 [part 2 #1234 · 10-08 14:22]，可再按锚点读上下文。

04群聊轮次协议：一次只让一个说话

群聊是「一个共享的、有序的对话」。核心约束是：一个成员的回合只有在上一个发言者发完或弃权之后才开始。它会看到自上次看过以来新增的内容、当前发言顺序、以及自己在其中的位置——谁都不用数行数去猜轮到谁。

▸为什么群聊费钱，但不会读到你私聊

每个成员在每个群里都有一个专属的隐藏 Session（room.sessions[botId]），它与该成员私聊渲染同一套提示词和工具。这带来两个后果：前缀缓存共享；群聊会话与私聊会话互相隔离——群里读不到成员的私人聊天。这个隐藏 Session 的第一条消息是一份该成员私聊的「简报」，因此固定不变、可缓存。

进群发言前，成员可以 read_local_chat 主动看自己的私聊（群会看到「它去查了」这一行），但只分享群需要的内容；在私聊里则用 read_group_chat 看群里说了什么。

群会话本身只是个「中继」：它的系统提示告诉它你不是参与者——对每条新用户消息调用一次 group_relay，然后以空回复结束回合，绝不自己加话。

05记忆：写死的格式 + 每轮自动复盘 + 提示词冻结

记忆是纯 Markdown，格式取自 Agent Memory Repo：每行一条、结尾带 [source: …; added: …] 元数据；MEMORY.md 用 ## Index 把主题文件以 [[topic]] 链出去。

~/.dsh/bot/memory/
  bots/<botId>/    某个 Bot 自己的 MEMORY.md 与主题
  team/            全队共用、每个 Bot 都读
  journal.jsonl    每一次改动，含改前/改后整行
  snapshots/       每个 Session 冻结下来的那一段
  summaries/       记忆面板的摘要（可删）
  archive/         已删除 Bot 的记忆
  reviewed.json    复盘读到哪了

▸关键：记忆不靠 Bot「想起来要记」

每回合结束后有一次 memory review：它读这段对话里新增的内容（≤16k 字符），自己决定保留、更新还是删除条目。这才是记忆真正可靠的原因——不依赖模型主动调用 remember。三个工具 remember / forget / recall 走的都是同一条写入路径，谁能在哪个作用域写、条目大小上限、拒绝记录密钥，全在这一层强制。

• 尺寸是硬上限：单条 ≤300 字符，MEMORY.md ≤4000，单个主题 ≤16000，一个作用域 ≤40 主题。
• 两份 MEMORY.md（自己的 + 全队的）会随每次请求发送，所以合起来控制在约 8000 字符、几千 token 的量级。
• 记忆是数据不是指令：看起来像 key/token 的条目会被拒；网页或工具结果里「请记住…」这类要求会被忽略。

06密钥：Bot 永远看不到明文

Bot 要 key 的时候调 request_secret，用户在自己聊天里往一张卡上填。值只存在于 secrets.json（权限 600）和宿主进程内存中，Bot 通过环境变量 $DSH_SECRET_<NAME> 使用，从不经过模型。

▸遮蔽器 redactor()

• 一个函数替换所有已知值，长的先替——于是「值是另一个值的子串」时整体被替换掉，不会被切碎。
• 连 JSON 转义后的形态一起覆盖。
• 短值（PIN、短密码）若到处替换会误伤普通词，所以低于阈值时只在「独立出现」的位置替换：前后不能紧挨字母或数字。
• 两个时机生效：工具结果落盘前、每次请求发往模型前。

作者把局限也写进了文档：只替换「完全一致的副本」，Bot 若把值编码、拆分、倒序仍可能打出来；Windows 下 600 权限位无效；非 HTTPS 页面传输是明文。结论写得很直白：别把重要密钥交给你不信任的 Bot。

07一个状态文件，一把单写者锁

state.json 装着整个团队：版本、workspace、主 Bot 列表、bots、rooms、agents、交换日志、隐藏回合表、待答问题、偏好、revision。做法很朴素但很稳：

// 原子写：先写临时文件，再 rename
const temp = `${statePath}.${process.pid}.tmp`
await writeFile(temp, snapshot, 'utf8')
await rename(temp, statePath)   // 同一台机器上 rename 是原子的

写入被串到一个 promise 链上，避免并发覆盖；adopt() 里则集中处理所有历史数据迁移（旧的 lab 字段 → 各自的模型、单个 mainBotId → 数组、初代鲸鱼头像、旧主题名、群聊的 admin/mode…）。

▸桌面版和 Web 版同时开怎么办

两者默认共用 ~/.dsh，若同时内存里各存一份团队状态、各自整文件写回，就会互相覆盖。于是有一把 state.lock：一个很小的 JSON（pid、host、token），持有者每 15 秒 bump 一次 mtime，60 秒没 bump 就算过期。

• 决定归属的是 token 而不是 pid：一个发现自己 token 变了的持有者，就是丢了锁。
• 同一台机器上，进程退出即可判定；跨机器（共享存储）只能靠时间戳，所以要等满一个 stale 窗口。
• 第二个 dsh 打开时进入只读：能看到团队、跟随文件变化，但拒绝一切修改；第一个退出后它自动接管。

08几个做得挺讲究的角落

09它到底好不好

这套实现最值得学的不是功能清单，而是三个反复出现的同一招：

• 让前缀逐字节稳定——身份提示、群会话与私聊共用、记忆 section 冻结，全都为了命中 prompt cache。
• 把不确定的判断外包给一次小调用——上下文该压缩还是该换段，交给一个只回一行 JSON 的「管家」，而不是塞进主对话里纠缠。
• 把「隐藏」做成结构，而不是靠提示词——Bot 间回合靠 exchangeTurns 打标隐藏、群会话整体隐藏、失败回合主动回调发送方。行为由机制保证，不靠模型自觉。

源码：github.com/FeiZhuLulu/DeepSeek-Bot（Apache-2.0，非 DeepSeek 官方）。本文基于 v0.1.0 源码，附带 git 版本 v0.1.0。