A4 · Profile 与 Bundle：分层组合与 Patch 覆盖机制

A4 · Profile 与 Bundle：分层组合与 Patch 覆盖机制

developer preview：API 可能变更。

1. Profile 与 Bundle 是什么

• Profile（配置档）：存放在 Harness home 中的具名组装。它列出自己叠加的 bundles、保存树外插件、保留用户的 cordis.patch.yml。web 与 headless 作为模板随发行版交付。
• Bundle（组合包）：Cordis 配置行 + 其挂载代码的发布格式。它插入的内容始终可被上层 patch。
• 两者都在各自 package.json 通过 dsh 字段声明：dsh.profile 列出 profile 的 bundles，dsh.bundle 指向 bundle 的 patch 文件。

// packages/bundle/base/package.json
"dsh": {
  "bundle": { "patch": "./cordis.patch.yml" }
}

2. 分层叠加顺序

运行中的 dsh 是一棵按序叠加各层组合出的插件树：

每一层按此顺序应用在空条目列表之上：先按 profile 列出的顺序应用每个 bundle，然后是 profile 的 patch，然后是 home 级 patch，最后是 --patch overlay。一条 patch 按 id 定位某个条目并替换其整个 config，或插入新条目。

3. 三大基础 Bundle

// packages/boot/app-boot/src/profile.ts
export const PROFILE_TEMPLATES = {
  web: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app'],
  headless: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-headless'],
}

4. Patch 机制（insert / replace by id）

composeEntries(layers) 调用 applyEntryPatches，按 id 合并各 layer 的 cordis.patch.yml 补丁条目，用户层最后叠加。

5. 可运行示例：查看与覆盖配置

# 打印本机实际启动的配置树（排查 patch 是否生效的神器）
pnpm dsh --profile web --dump-config

# 自定义覆盖层：插入一个本地插件
# my-overlay.yml
- insert:
    - id: hello
      name: '/abs/path/to/scratch-plugin/src/my-plugin.ts'
pnpm dsh web --patch ./my-overlay.yml

--dump-config 打印出的任何条目都可被你自己的 patch 替换。

6. 核心术语中英对照

7. 官方文档 vs 源码 对照表

8. 一句话小结

dsh 用「profile 列 bundles + 逐层 patch 叠加」实现了可预测的组装：你永远可以用 --dump-config 看到真实启动树，再用一条 patch 改写其中任意条目。