ARTICLE · 1366852
一个 7.9 k star 的插件,记了 12 笔「宿主不让干的事」
DS-Bot 这个项目建仓到现在只有三十九天,已经拿了 7.9 k star,仓库里大大小小一共 853 个文件。
这里面躺着 33 份设计文档,一天不落,从十月七号到十一月十号。
我第一次翻到这个目录的时候有点意外,因为一个还在飞速迭代、497 个 issue 没关的项目,通常不会有心情写文档。它不光写了,还给文档定了格式,五个固定章节,其中两个是不做什么、已知限制。
一个跑得飞快的项目,主动写下自己做不了什么。
得先说清它是个什么东西。DS Bot 把 dsh 改造成了 bot 的样子,每个 bot 是一个独立的 dsh 会话,有自己的名字、角色、指令和模型,能私聊,也能拉群。
两种形态,桌面应用和 dsh 插件。
桌面版自带 dsh,去 Releases 下对应系统的安装包就行,打开之后在设置里配好模型就能用,不用先装 dsh。如果你原来在 dsh 里已经有一支 bot 团队,可以直接复制过去。
喜欢装在现有 dsh 里的,桌面版走「插件 → 添加插件」,包名填 ds-bot(大陆选镜像源),装完点立即启用。命令行则是这一行。
dsh plugin --profile web add ds-bot--profile 后面跟你的用法,网页是 web,桌面是 desktop。还有个 Docker 版给 NAS 和 Linux 服务器用。
有一个坑要提一句,如果你装过更早的 dsh-bot 包,得先把它删掉再装新的,因为两个包用的是同一个插件 id,会撞。团队和聊天记录不会丢,存东西的地方不在那儿。
第一次打开,它会自动建一个叫 Chief 的主 bot。
接下来你基本不用点设置面板。官方的建议原话是,直接通过和 bot 对话来配置其他 bot 和群聊。 想加人就让它加,想建群就让它建,它手里有 create_bot 和 update_group 这些工具。
日常怎么派活,两条路。私聊里用 message_bot 直接指使另一个 bot,或者在群里 @ 谁谁上。
要并行的时候它不靠一个 bot 派子代理,而是让几个 bot 同时干,这一点后面细说,是这篇的主线之一。
docs/plans/README.md 里说得很清楚,三条流程。
大功能要在同一个 PR 里附一份设计文档,和代码一起审、一起合。改动已经定下的设计,得先在 Issue 里跟维护者确认,合并的时候同步改文档。
修 bug 不用写。
最后这条我觉得挺关键。它说明作者分得清做事和改设计,不是什么都往文档里塞,也不是随手记几笔。
文档有五个固定章节,为什么、已定的行为、不做什么、已知限制、变更。
不做什么和已知限制这两节是强制的,不是可选。这一点大部分项目的 README 都做不到。
我再往下翻了几份,发现格式真的被守住了。每份文档都带日期,改动过的地方在文末的变更一节里追加,写清哪天改了什么、对应哪个 PR。日期和 PR 号让每一句话都能追回去,不是事后补一段自我感觉良好的叙述。
这套东西不难写,难的是三十九天里每个大功能都照着来。
十月中旬,它专门开了一份文档,叫 DSH 让步总账。
起因写得很直接,DS Bot 是 DSH 插件,只能用 DSH 公开的接口,而有些地方宿主的设计和它不合,全局注册、没有按会话过滤、预设是全局的、界面结构不对插件开放。
它给自己定的原则是,以 Bot 的正确行为为准,不为兼容宿主的限制无限增加复杂度。
这条原则翻译成人话就是,我按我想要的样子做,宿主不让我做的部分,我记下来,但我不为了迁就它把自己搞成一团乱麻。
账本记到今天一共十二笔,C1 到 C12。每一笔记七样东西,编号、日期、相关 Issue、宿主的限制、现在的做法、代价、以及等桌面应用自己掌握 profile 之后打算怎么处理。
那个代价一栏是这个账本最值钱的地方。
C9 是这么一笔。 用户显式指定的默认模型不可用时,宿主的 defaultModel() 会返回模型目录里的第一项。插件接受这个行为,代价是可能落到另一个服务商的模型上,而用户并不知道自己什么时候换了家。
C11 更难受。 模型流卡死的时候,宿主没有看门狗,回合永远不会结束。插件现在能做的只是把没读的请求合成一条,让 list_bots 和 message_bot 里看得到对方在干什么、在等什么。代价写得很坦白,卡死的 Bot 要用户手动停止。
C4 是最憋屈的一笔。 宿主不提供删除指令菜单项的接口,所以加号和斜杠菜单里还留着计划、权限、模型、压缩这些 Bot 不该用的入口。代价是Bot 的设置可能被绕过。
这三笔有个共同点,宿主不报错,插件自己知道不对,但改不了。
还有一笔能看出这本账记得有多细。C2 是命令全局注册,不能按会话过滤,它的处理很干脆,bot 一律不支持 goal,把工具去掉,一旦创建就停下并说明。代价写在旁边,/goal 还是出现在菜单里,但点了用不了。
C6 我单独拿出来说。 宿主的 MCP 客户端会把服务器响应体写进日志,插件没法脱敏,服务器回显 URL 的时候,密钥就可能进 DSH 的日志。这是安全问题,而它在账本里只占一行。
最实用的一条写在文档开头。
判断一个 Issue 是 DS Bot 的 bug 还是 DSH 的限制,先看这张表。属于宿主的,加 upstream 标签。
这句话看着不起眼,但它把两件事分开了,一件是「我们的代码写错了」,一件是「平台的形状不允许」。分开之后才知道该修哪边,也才知道哪些事情根本不该由自己来修。
一个三十九天的项目能把这件事做成流程,我觉得比它的功能更值得看。
因为这件事有个隐性的好处,它把吐槽变成了记录。同样是遇到宿主不给接口,一般项目的处理方式是开个 issue 抱怨两句,或者在代码里留一行注释写个 hack。这个项目把它记成了一张有七列的表,每一列都得填,填到代价那一列的时候,你得诚实。
不诚实也填不下去,因为下一列问的是「以后怎么处理」。
它允许 bot 之间互相发消息(message_bot),甚至允许 bot 创建 bot(create_bot)。听起来挺吓人,所以它做了一件反直觉的事。
它从 bot 的会话里删掉了三类工具。 委派类的 subagent、subagent_fork、workflow,子代理控制类的 send_message、interrupt_agent、list_agents,还有 Agent Teams 的整套队友工具,连宿主写进系统提示里的用法说明也一起拿掉了。
理由是三个具体后果,不是安全教条。
> 子代理跑起来用户看不到、停不到,换段时会被连带取消,结论丢失。
这三件事都跟用户有关,不是理论上的风险。一个看不见、停不下、切换一下就没了的东西,放在一个给普通人用的产品里,就是不能用。
那要并行怎么办,让几个 bot 同时干,靠 message_bot 派活,群里 @ 点名。
这是一个明确的取舍,用「几个独立的 bot」替代「一个 bot 派子代理」。 前者的每一个成员都是完整会话,用户看得到、停得掉、切段也不会丢;后者跑在暗处,什么都抓不住。
代价是调度变复杂了,谁派活、谁汇报、几个 bot 撞在一起怎么办,都得自己设计。但它宁可背这个复杂度,也不肯把子代理放进来。
它也没有假装这件事做得很干净。文档里明说了,宿主注册在 Agent 自身作用域里的那几个工具拿不掉,从 DSH 0.2.2 起它们还是会出现在工具列表里,只能靠拒绝来挡住调用。万一真有调用进来,会被拒绝,并提示 Bot 自己做,或者把活交给别的 Bot。
群聊的消息原来存在四个地方。
界面读的是 group_relay 的工具结果,成员读的是 state.json 里最近 60 行,记忆整理读的是 group-logs,长消息的全文又另外放在 group-lines。
四个地方,四份代码分别写,漏写一处,界面和成员看到的就不一样。
更麻烦的是宿主会截断超长的工具结果,所以超长的那一轮刷新之后,回复可能直接不见。
解法是把这四个写入方收成一个,每个群一本只追加的账本(bot/ledger/group-*.jsonl),一行一条记录,不改旧行,消息先写进账本,其他地方都从账本读。
账本还有几条讲究,一行按序号从旧到新,第一次用到整本读进内存,写盘排队,删群时一起删,不按时间自动清。
界面那一侧也不直接画账本,每次工具调用记一个锚点,页面显示锚点到下一个锚点之间的行,刷新之后位置不变,工具结果也不会因为太长被截掉。
这一节我最想说的是因果关系。宿主的一个行为,截断,直接逼出了一个架构决策,单一真相源。 如果没有那个截断,这四个写入方大概会一直并存下去。
角色权限管的是谁能管 Bot、管群、管团队记忆,这部分 DS Bot 自己检查。
沙盒权限管的是一个 bot 的工具能碰到什么,读文件、改文件、跑命令,这部分用宿主提供的权限预设,由宿主执行。
越权调用会被拒绝,而且会告诉 bot 该怎么办,比如只有 Main Bot 能创建。
该自己管的自己管,该交给宿主的交给宿主。这句话听起来简单,但很多插件把两件事混在一起,最后谁也说不清一个越权是谁拦住的。
它在这件事上有很明确的分工意识。角色权限是业务逻辑,它自己写自己查;沙盒权限是宿主的能力,它不重造一套,直接调宿主的预设。
道理很朴素,插件一旦自己实现沙盒,宿主升级一次安全策略,插件就落后一次。不在别人的地基上再浇一层水泥。
写下来不解决问题。那十二笔债到今天一笔都没还,有几笔明确写着要等桌面应用自己掌握 profile 和界面之后才能清,在那之前它们就是债,一直挂着。
但记下来之后情况不一样了。后来的人知道债在哪,知道哪个 bug 该自己修,知道哪些事不该拿去问宿主。
而且这本账从头到尾没有控诉的语气,它记的是限制,每一条都在写那我现在怎么办。
插件开发最难的部分,大概不是接口不够用。是接口不够用的时候,你还能不能对自己诚实,说清楚自己妥协了什么。
最后说清楚我看到了什么、没看到什么。
我没装这个插件,也没跑过它的任何功能,上面所有判断都来自它的文档和代码。497 个没关的 issue 说明它还很粗糙,那些漂漂亮亮的设计文档和真实可用之间,还有很长的距离。7.9 k star 里可能有不少是冲着 bot 陪聊来的,那跟工程价值是两回事,我不想把这两件事混着说。
至于那本总账,它是维护者自己写的,每一笔的代价轻重也是他自己判断的。我读到的是一份诚实的自我描述,不是审计过的账目。 这个区别值得留着。
💬 互动话题
你手上有没有那种因为平台不给接口、只能绕过去的妥协?最后是记下来了,还是就那么放着了?
👍 如果觉得有用
欢迎点赞、收藏、转发三连。
我是Hank, 我们下次再见。















































































