读 dsh 源码:三条主线与固定版本
核验于 2026-10-31dsh 0.2.1-rc.5版本说明
这三篇要回答的是:一次 dsh 进程启动之后,源码里到底是谁在对什么做什么。官方文档已经把每个子系统写得很细,接口表去官方文档查更合适;这三篇按一次运行发生的先后顺序,把三块源码串起来:启动时读哪几个配置文件、这些配置怎么合成插件树;一条消息怎么变成一个步骤;一次工具调用要经过哪些检查才真正执行。
每篇的结构相同:一张图、一张源码坐标表、一段可以自己运行的命令。图用来看清各部分的先后顺序,坐标表用来按行号打开文件,命令用来确认你看到的是自己运行出来的结果,不是文章转述的结论。
三条主线
01 · 插件树
一次 dsh --profile web 启动,96 行 base 配置要经过哪几层 patch,才变成运行中的服务?
入口:packages/boot/app-boot/src/profile.ts。你会看到 profile、bundle、patch、composeEntries()、Cordis Loader。
02 · 消息生命周期
一条 followup() 怎么走完 turn 和 step,什么时候写日志、什么时候发请求?
入口:packages/core/agent-loop/src/agent.ts。你会看到 inbox、agent/pre-step、prompt 组装、请求冻结、流式结算。
03 · 工具流水线
模型发出 tool call 后,这次调用先经过谁的检查、谁可以拒绝执行、执行失败之后又怎么变成结果?
入口:packages/core/tools/src/index.ts。你会看到参数快照、审批、守卫、环绕分发、post-execute、finalizeContent。
三篇有先后关系。插件树解释插件从哪来,消息生命周期解释谁在驱动一次运行,工具流水线解释能力怎么被安全地调用。如果你只想先解决一个具体问题,可以直接跳到对应篇目,再回头补前置概念。
版本先说清楚
三篇的行号固定在一份源码上:
- 源码标签:
dsh-v0.2.1-rc.5 - commit:
b830ec950faba0a46dda564be3e2d854afed94f1 - npm
latest:0.2.1-rc.5 - npm
next:0.2.1-rc.5(当前与 latest 指向同一个版本)
源码与命令都核验在 rc.5。2026-10-31 这一轮把源码坐标从 rc.3 换到 rc.5:三篇引用的 20 个文件在两个 tag 之间没有任何改动,行号与结论因此不变;换坐标是为了让你点开链接时看到当前版本。版本页有通道对照。行号只对上面列出的那一个 commit 有效,文件路径和函数名通常比行号变化得慢。
每条源码链接都指向 commit b830ec950faba0a46dda564be3e2d854afed94f1 的 GitHub blob,而不是 main。这样即使上游继续合并提交,你点开的仍然是文章写作时读的那份代码。
每篇的三步读法
- 先看图,不看代码。 图里的顺序就是运行时的先后顺序;看不懂的箭头先记下来。
- 再读“源码坐标”表。 按行号打开文件,只读表里列出的那几段,不要从文件第一行开始通读。
- 最后运行“自己验证”一节的命令。 不需要模型 Key 的命令会标出来;需要模型 Key 的命令单独说明。
源码阅读中最常见的一种误判,是把“文件里定义了某个函数”当成“运行时一定会执行到那个函数”。每篇都尽量追到实际调用点:谁发起调用、在什么条件下调用、调用失败时执行哪一条分支。如果某个结论只来自注释或类型声明,文中会直接说明这是注释里的约束,不会写成实测行为。
实验环境
- Windows 11(10.0.26200),Node 24.18.0,npm 11.16.0
dsh0.2.1-rc.5,通过npx -y @deepseek-ai/dsh@0.2.1-rc.5运行- 源码:
dsh-v0.2.1-rc.5的 codeload 压缩包,解压后按 tag 对应的 commit 核对 - 需要 pnpm 的命令单独标注;
dsh plugin会把参数转发给 profile 目录里的 pnpm
不需要模型 Key 的实验包括 --dump-config、源码 grep 和插件加载日志。需要模型 Key 的实验会明确写出,不把“没有运行过”写成“已经运行过”。
官方文档对应位置
- 架构总览:profile、组合包、轮次流程、能力 seam
- Cordis 入门:插件、上下文、服务依赖、waterfall
- Agent 轮次与步骤生命周期:时序图与事件清单
- 工具执行流水线:策略、守卫、审批与结果重写
- 安全边界:沙箱、审批与信任模型
三篇是官方文档的补充读法,不替代官方文档。接口签名、配置字段和设计决策以官方文档为准;三篇负责把顺序讲清楚,并给出可以自己复核的入口。
从哪篇开始
常见问题
读源码前要先会什么?
会用 dsh 启动 Web UI、知道 profile 和插件的基本概念即可。Cordis 的五个概念可以在第一篇里边读边补,不需要先通读框架文档。
为什么文章里的行号不是最新的?
源码行号会随版本移动。这三篇固定到 dsh-v0.2.1-rc.5(commit b830ec9),每页头部写明核验日期;升级后行号可能失效,文件路径与函数名更稳定。
源码文章和官方文档有什么区别?
官方文档定义接口与设计约束;这里按一次真实运行的顺序把文件串起来,补上先看哪、为什么这样排、怎么自己验证。