读 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。这样即使上游继续合并提交,你点开的仍然是文章写作时读的那份代码。

每篇的三步读法

  1. 先看图,不看代码。 图里的顺序就是运行时的先后顺序;看不懂的箭头先记下来。
  2. 再读“源码坐标”表。 按行号打开文件,只读表里列出的那几段,不要从文件第一行开始通读。
  3. 最后运行“自己验证”一节的命令。 不需要模型 Key 的命令会标出来;需要模型 Key 的命令单独说明。

源码阅读中最常见的一种误判,是把“文件里定义了某个函数”当成“运行时一定会执行到那个函数”。每篇都尽量追到实际调用点:谁发起调用、在什么条件下调用、调用失败时执行哪一条分支。如果某个结论只来自注释或类型声明,文中会直接说明这是注释里的约束,不会写成实测行为。

实验环境

  • Windows 11(10.0.26200),Node 24.18.0,npm 11.16.0
  • dsh 0.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 的实验会明确写出,不把“没有运行过”写成“已经运行过”。

官方文档对应位置

三篇是官方文档的补充读法,不替代官方文档。接口签名、配置字段和设计决策以官方文档为准;三篇负责把顺序讲清楚,并给出可以自己复核的入口。

从哪篇开始

  • 想知道插件从哪来:从插件树开始。
  • 想知道一条消息怎么走:从消息生命周期开始,先读插件树会更省力。
  • 想改工具策略:从工具流水线开始,先读消息生命周期会更省力。

常见问题

读源码前要先会什么?

会用 dsh 启动 Web UI、知道 profile 和插件的基本概念即可。Cordis 的五个概念可以在第一篇里边读边补,不需要先通读框架文档。

为什么文章里的行号不是最新的?

源码行号会随版本移动。这三篇固定到 dsh-v0.2.1-rc.5(commit b830ec9),每页头部写明核验日期;升级后行号可能失效,文件路径与函数名更稳定。

源码文章和官方文档有什么区别?

官方文档定义接口与设计约束;这里按一次真实运行的顺序把文件串起来,补上先看哪、为什么这样排、怎么自己验证。