自学教程

DeepSeek Harness 组合包

DeepSeek Harness

DeepSeek Harness 组合包 Bundle 与运行配置 Profile：双 Manifest 架构详解

DeepSeek Harness 最核心的模块化编排能力，由两套独立 Manifest 清单驱动：Bundle 清单与Profile 清单。

绝大多数配置不生效、插件加载异常、环境切换错乱、自定义包无法启用的问题，根源都是混淆了这两套 Manifest 的职责边界。

一句话总览核心差异：

  • Bundle（dsh.bundle）：静态发行清单，定义「一个能力包包含哪些插件、配置、依赖」，用于封装分发。
  • Profile（dsh.profile）：运行组合清单，定义「当前进程堆叠哪些 Bundle、叠加哪些补丁」，用于环境组装。

Harness 所有官方预设环境（web / headless / sdk / minimal）、自定义私有环境、生产/测试隔离，全部基于这两套 Manifest 分层叠加实现。

一、核心概念：为什么需要两套 Manifest？

传统框架只有一层配置，存在致命问题：能力封装与运行环境强绑定，无法复用、无法分层、无法快速切换部署形态。

Harness 采用双层分离架构彻底解耦：

  1. 开发层（Bundle）：开发者封装一组内聚能力，打包为可复用、可分发的组合包，固定插件集合与默认配置。
  2. 运行层（Profile）：使用者自由堆叠多个 Bundle、叠加自定义补丁、挂载外置插件，动态组装出不同运行环境。

Bundle 负责「造零件」，Profile 负责「拼整机」，二者各司其职、互不越界，构成 Harness 灵活可编排的底层基石。

二、第一套 Manifest：Bundle 组合包清单（dsh.bundle）

1. 定位与本质

Bundle 是 可复用、可版本化、可分发的能力发行单元。

在 NPM 包的 package.json 中通过 dsh.bundle 字段声明，标记当前包为「组合包」，而非普通工具库。

核心特征：自包含、可独立运行、可被 Profile 堆叠继承。

2. Bundle 清单作用

  • 批量声明当前包内置的插件列表、默认配置、依赖关系
  • 对外暴露标准化能力集合，支持全局复用
  • 被 Profile 统一引用堆叠，无需逐个手动注册插件
  • 支持版本迭代、能力增量更新、批量升级

3. 典型 Bundle 结构示例

在自定义组合包的 package.json 中声明：

{
  "name": "dsh-custom-dev-bundle",
  "dependencies": {
    "@deepseek-ai/dsh-shell": "^1.0.0",
    "@deepseek-ai/dsh-code-run": "^1.0.0"
  },
  "dsh": {
    "bundle": {
      "plugins": [
        "@deepseek-ai/dsh-shell",
        "@deepseek-ai/dsh-code-run"
      ]
    }
  }
}

4. 关键规则：Bundle 与普通库包的区别

  • 普通库包：只有 dependencies，无dsh.bundle 声明，仅用于代码导入，不会自动注册插件、不产生配置层
  • Bundle 组合包：包含 dsh.bundle 声明，可被 Profile 引用，自动批量加载插件、生成独立配置层

简单区分：要自动加载插件、批量组合能力，必须声明 bundle；仅工具函数依赖，无需 bundle。

三、第二套 Manifest：Profile 运行配置清单（dsh.profile）

1. 定位与本质

Profile 是 进程级运行时组合方案，是 Harness 启动的「入口配置」。

对应目录下的 dsh.profile 文件，是整个运行环境的顶层 Manifest，负责定义当前进程由哪些 Bundle 堆叠而成，并承载用户自定义补丁与外置插件。

2. Profile 目录完整结构（官方标准）

一个合法 Profile 环境包含三类核心文件：

  • dsh.profile：顶层运行清单，定义 Bundle 堆叠顺序、环境标识
  • package.json：记录当前环境的外置插件、树外依赖
  • cordis.patch.yml：用户自定义配置补丁，覆盖上层 Bundle 默认配置

3. Profile 清单核心能力

  • 有序堆叠 Bundle：按声明顺序叠加多个组合包，后加载覆盖先加载
  • 挂载外置插件：管理树外自定义插件、本地调试插件
  • 配置补丁覆盖：通过 patch 文件局部修改 Bundle 默认配置，不改动原包源码
  • 环境隔离：多 Profile 实现开发/测试/生产环境完全隔离

4. dsh.profile 示例

{
  "bundles": [
    "@deepseek-ai/dsh-base",
    "@deepseek-ai/dsh-web",
    "dsh-custom-dev-bundle"
  ]
}

内核将严格按照数组顺序逐层叠加 Bundle，后置 Bundle 配置优先级高于前置，实现能力覆盖与定制。

四、双 Manifest 完整协作链路（核心架构）

Harness 启动加载顺序严格固定，是解决配置不生效问题的关键：

  1. 读取当前激活的 Profile 清单（dsh.profile）
  2. 按顺序遍历清单内所有 Bundle
  3. 读取每个 Bundle 的 bundle 清单（dsh.bundle），批量加载插件与默认配置
  4. 叠加 Profile 目录的 cordis.patch.yml 补丁，覆写配置
  5. 加载 Profile 外置树外插件
  6. 内核完成拓扑排序、依赖等待、插件激活

核心优先级规则：Patch 补丁 > 后置 Bundle > 前置 Bundle 默认配置

五、两套 Manifest 全方位对比表

对比维度Bundle Manifest（dsh.bundle）Profile Manifest（dsh.profile）
文件位置NPM 包 package.json 内部字段Profile 独立目录下 dsh.profile 文件
定位静态能力封装、分发单元动态运行环境、组合入口
核心职责定义一组固定插件与默认配置堆叠多 Bundle、叠加补丁、组装运行环境
复用性可被多个 Profile 重复引用当前环境独享，多环境可多配置
可修改性版本固化，迭代需更新包版本随时修改、热重载生效
加载顺序被 Profile 按序加载全局最先加载，驱动所有 Bundle
适用场景官方能力包、自定义通用能力组合环境切换、配置定制、本地调试

六、官方预设 Bundle 与 Profile 模板

Harness 官方内置多套标准模板，全部基于双 Manifest 架构实现：

预设 Profile（运行环境模板）

  • web：完整网页交互环境，含UI、会话、完整工具集
  • headless：无界面后台运行环境，适合服务部署
  • sdk / sdk-minimal：轻量化SDK环境，适配二次开发与嵌入场景
  • acp：高级智能体编排环境

核心基础 Bundle（能力组合包）

  • dsh-base：基础能力合集，模型适配、会话持久化、沙箱、安全校验核心底座
  • dsh-toolset：命令行、文件、代码运行等工具合集
  • dsh-web：网页UI、前端交互能力包

七、高频踩坑与官方解决方案

坑1：安装依赖后插件不生效

原因：仅安装 dependencies，未将包加入 Profile 的 bundles 列表，或包未声明 dsh.bundle

标签：

0 条笔记