第8讲 · Profile 与 Bundle 组装模型

《DeepSeek Harness 从上手到精通》系列 · 第三阶配置组装篇

🎯 目标：看懂"运行中的 dsh 是怎么被拼出来的" 难度 ★★☆ ⏱ 约 30 分钟前置：第 7 讲 Seam + 已跑起 dsh

系列基于 deepseek-ai/deepseek-harness（0.1.0-rc.5，MIT）。本讲带你从"只会用"跨到"会组装"——搞清楚那一堆插件、配置、模型设定，究竟是怎么在你敲下 dsh web 后合体成眼前这个产品的。preview 阶段命令可能微调，请以官方 README 为准。

一、先抛一个问题：你眼前的 dsh 从哪来

第 1 讲你跑起 dsh web 时，没写过一行配置，却已经拥有了一整套工具、一套审批策略、一个模型适配器、一个 Web 界面。这些东西是谁决定的？答：配置文件一层层叠出来的。

dsh 的设计哲学是"一切皆插件、一切可组装"。它不直接给你一个写死的成品，而是给你几层可叠加的"预置 + 覆盖"，让你用一份 YAML 就能把产品换成另一个样子。本讲要建立的认知是：运行中的 dsh = 分层配置合并后的结果，而不是某个固定二进制。

二、操作系统发行版类比：为什么这样设计

把 dsh 想象成一套操作系统发行版，就好理解了：

基础内核（bundle）：相当于 Linux 内核 + 基础工具链，决定"这是个什么形态的系统"（Web 应用 / 无头脚本 / 终端 UI）；
发行版定制（profile 的 patch）：相当于 Ubuntu 在 Debian 之上做的那层默认配置——换源、预装软件、默认桌面；
本机个性化（home 级）：相当于你 ~/.bashrc 里的别名和主题，跟随这台机器；
临时启动参数（--patch）：相当于这次开机加的内核参数，重启即失效，不污染系统。

这种"分层叠加"的好处：官方维护基础层，你只改最上面一两层。产品升级（bundle 更新）不会冲掉你的个性化配置，反之亦然。

三、三层预置 + 一层覆盖：配置从哪来

从底到顶，dsh 的配置由四层合并而成（前三层是"预置"，第四层是"用户即时覆盖"）：

dsh 四层配置叠加模型 — **图 1** 四层配置：bundle → profile patch → home 级 → --patch，越靠上层优先级越高。

① bundle（基础层）：三选一，决定运行形态：

bundle	对应形态	典型入口
base	核心能力，无界面	`dsh headless`
web-app	Web UI 全套	`dsh web`
headless	脚本/CI 形态	`dsh --profile headless`

② profile 的 cordis.patch.yml：选中某个 bundle 后，profile 再用一份 patch 声明"在这个基础上改哪些默认值"。比如 web-app 的 profile 会把界面主题、审批默认模式设好。

③ home 级：位于你机器上的用户目录（如 ~/.dsh），跟随这台电脑，对所有 profile 生效。通常放你的模型 Key、个人偏好。

④ --patch 用户即时覆盖：启动命令里临时加一份 patch，优先级最高、用完即弃、不落盘。改错了关掉进程就回到原样——这正是 Cordis 的"可逆副作用"思想。

四、实战：--dump-config 打印真实配置树

别只听我讲，把合并后的真实配置树打出来看一眼：

# 打印当前 profile 合并后的完整配置（示意结构，实际字段以你的版本为准）
dsh --profile web --dump-config

输出是一棵已经被四层合并完毕的树，自上而下逐段对应我们上面说的层级：

profile: web
bundle: web-app                 # 预置层①：选中的基础发行版
cordis:
  plugins:
    - "@deepseek-ai/dsh-core"   # 核心能力（seam 实现都在这里）
    - "@deepseek-ai/dsh-web"    # Web UI 插件
  patch:                        # 预置层②+③：profile 与 home 的叠加
    - id: web-defaults          # 来自 profile 的 cordis.patch.yml
      apply:
        ui.theme: dark
        approval.mode: prompt
    - id: home-overrides        # 来自 ~/.dsh 的本地配置
      apply:
        model: deepseek-chat
# 用户覆盖层④（--patch）不会写进这份静态树，只在运行时叠加

读这份树时记住一件事：越靠下、越靠后的条目，优先级越高。home 覆盖 profile，--patch 覆盖一切。这正是"给产品换脑"的开关所在。

五、动手练习：导出并注释你的配置树

本讲产出：把你自己机器上的完整配置树导出来，用注释标出 3 处你想改的行。

# 1) 导出
dsh --profile web --dump-config > my-config.txt

# 2) 打开 my-config.txt，在下面三处附近写下注释：
#    - model: 想换成别的模型名？
#    - approval.mode: 想从 prompt 改成 auto / deny？
#    - 某个 plugin 行：想禁用某个内置能力？

标完这三处，你就已经为第 9 讲"配置补丁实战"备好了靶子——后续我们将用 --patch 真正动手改它们。

六、常见坑

改了 home 配置却不生效：确认路径是不是 dsh 实际读取的那份（多版本/多用户时容易指错目录）；
--dump-config 看不到 --patch 的内容：它只打印静态合并树，--patch 是运行时叠加，属于预期行为；
把 bundle 和 profile 搞混：bundle 决定"形态"，profile 决定"该形态下的默认值"，别用错开关；
升级后配置"丢了"：通常不会，预置层与 home 层分离；若真异常，先 --dump-config 对比再排查；
字段名对不上文档：preview 阶段配置结构可能调整，以你本机 --dump-config 输出为准。

七、官方文档对应章节

README 的 Configuration / Profile 相关说明；
docs/ 中 bundle、profile、cordis.patch 与 CLI 配置章节；
衔接第 7 讲 Seam：本讲的"预置层"最终就是给那些 seam 选定 Provider。

本讲内容基于 DeepSeek Harness 官方文档与项目源码整理，仅供学习参考，具体命令与配置请以官方最新版本为准。系列文章配合源码仓库食用效果更佳：https://github.com/deepseek-ai/deepseek-harness

咨询 DeepSeek Harness 相关问题，请加微信：A0qingfengyuan_01

个人观点，仅供参考，如有不对之处，请多包涵，欢迎指出。本文由 AI 协助完成！

DeepSeek Harness 教程 · 第8讲 Profile 与 Bundle 组装模型