跳到主要内容
赞助推荐 搬瓦工怎么选:三网直连 CN2 GIA-E
核对于 2026-11-05
课程目录 · 11 节

Agent 框架源码

第 3 节:四层 patch 叠出插件树,base 就占 99 条

核对 2026-11-05 更新 1 次 引用 0 个来源

启动不是加载模块,是从空列表出发按顺序叠四层 patch。base 99 条、web-app 121 条、headless 8 条——模式差异靠 bundle,用户差异靠 patch。patch 按 id 整行替换 config,不做字段合并。

关键事实 · 6 条口径随行标注
dsh-base 条目
99 条全部为 insert 新增,共享第一层:模型适配器、工具、持久化、沙箱、审批、设置、凭据、遥测
dsh-web-app 条目
121 条24 条覆盖已有行加 97 条新增,浏览器应用与 Web Client 插件
dsh-headless 条目
8 条6 条覆盖加 2 条新增,最轻的一个组合包
dsh-sdk-app 条目
18 条4 条覆盖加 14 条新增,SDK 的 JSON-RPC 服务器
dsh-acp-app 条目
5 条3 条覆盖加 2 条新增,仅用于自动化
dsh-sdk-minimal 条目
37 条纯新增,刻意不叠 base 的完整显式配置树

启动不是「加载模块」,是「在空列表上叠四层」

dsh 没有 main 函数式的初始化流程。它的启动过程可以精确描述成一句话:从一个空的条目列表出发,按顺序应用若干层 patch,最后把列表变成插件树。叠的顺序是固定的,越靠后优先级越高:

① profile 里有序的组合包 bundle      ← dsh-base、dsh-web-app …
② profile 自带的 cordis.patch.yml    ← 用户自己的覆盖
③ home patch                         ← 这台机器级的覆盖
④ --patch overlay                    ← 命令行临时覆盖
        ↓  逐层应用,last write wins(按 id 定位整行替换 config)
   最终条目列表 → 插件树

一条 patch 做两件事之一:按 id 找到某个已有条目,替换它的整个 config;或插入一个新条目。注意是「替换整个 config」而不是深合并——所以官方在 base 的那个 patch 文件开头专门写了注释:如果某一行在不同模式下取值不同,它就不该放在 base 里,否则任何一层都没法只改其中一个字段。

这条规则看起来抠细节,实际影响很大。它意味着配置的组合是「整行覆盖」而非「字段合并」,你在 patch 里写一行,就得把这一行的 config 写全,不能只写想改的那半个字段。

实测:一个 web profile 叠了多少条目

把随发行版交付的几个组合包摊开数条目,能直观看到「base 很重、模式很轻」的结构:

0.2.2-rc.1 各 bundle 的 patch 条目数(覆盖行 + 新增行)
组合包 覆盖已有行 insert 新增 合计 它负责什么
dsh-base 0 99 99 模型适配器、工具、持久化、沙箱、审批、设置、凭据、遥测
dsh-web-app 24 97 121 浏览器应用:HTTP 服务器、Web Client 插件、UI 槽位
dsh-sdk-app 4 14 18 SDK 的 JSON-RPC 服务器
dsh-headless 6 2 8 不带服务器的一次性运行器,并改写 base 的 HMR 行为
dsh-acp-app 3 2 5 仅用于自动化的 ACP 服务器
dsh-sdk-minimal 0 37 37 刻意例外:完整显式配置树,不叠 base

先看两个结构性事实。只有 base 和 sdk-minimal 是纯新增,其余组合包都是「少量覆盖 + 较多新增」——因为上层要改写下层已经定好的行,比如 web-app 把 system-prompt 的 persona 前缀换成 Web 版,把 session-query-sqlite 改成内存索引。

再看 headless:6 条覆盖 + 2 条新增,一共 8 条。它是最轻的一个——复用 base 的 99 条,自己只加「一次性运行器」和「禁用 HMR」两件事,其余 6 条是改 base 的行为。这个结构说明 profile 的差异度差异很大,web 要 121 条,headless 只要 8 条。

这也解释了 profile 为什么是「组装」而不是「配置文件」:一个 profile 记着它自己的组合包列表、树外插件、以及它自己的 patch。模式差异靠 bundle,用户差异靠 patch,机器差异靠 home patch,三层各管一段,不互相污染。

patch 长什么样:id、name、config、disabled

这是 base 组合包里真实的一段,注意 disabled 可以用 !!js 写成表达式,在挂载决策时求值:

- insert:
    - id: plugin-manager
      name: '@deepseek-ai/dsh-plugin-manager'
      disabled: !!js "!ctx.get('profileContext')"

    - id: timer
      name: '@deepseek-ai/cordis-plugin-timer'

四个字段各有用处。id 是稳定锚点,所有后续层都靠它定位;name 是实际加载的包名,同一个 id 换 name 就等于换了实现;config 是该插件声明的运行时 schema;disabled 决定这一行在当前环境下是否激活。

「按 id 换实现」这条最值得利用。想换掉默认的模型适配器,不需要改任何源码,只在你的 cordis.patch.yml 里写同 id、新 name、完整 config 即可。dsh 文档把这类可替换点称为配置目录里的每一行都可被你的 patch 替换——这不是营销说法,是 --dump-config 能验证的事实。

还有一个容易踩的点:preset patch 只在目标声明的 config.plugins 内部生效,沿用同一套层优先级。所以「给某个会话换一套能力」不是改全局配置,是给它挂一个 preset,其中的服务行还要标 isolate realm 才真正隔离。

下一节进入这棵树最里面的那 2127 行:一个 turn 到底怎么被驱动出来。

变更记录

日期类型改了什么范围
新建 按 cordis.patch.yml 实测条目数,写出四层装配模型 全页
赞助推荐 一键部署 AI 大模型
赞助推荐 一键部署 AI 大模型