自学教程

DeepSeek Harness 声明依赖

DeepSeek Harness

DeepSeek Harness 基于 Cordis 微内核实现全自动插件依赖解析、拓扑排序、加载优先级、冲突规避。不同于传统前端/Node 项目靠 npm 管理依赖，Harness 拥有一套插件运行时专属的声明依赖体系。

绝大多数插件加载异常、功能不生效、能力覆盖错乱、启动报错，根源都是 依赖未声明、依赖顺序错误、版本不兼容。本文系统讲解 Harness 插件依赖原理、完整声明语法、运行时依赖、可选依赖、条件依赖、版本锁定、冲突解决与生产最佳实践。

一、什么是 Harness 声明依赖

在 DeepSeek Harness 中，每个插件都是独立可卸载的微服务，插件之间存在强依赖关系：

  • UI 插件依赖内核 Web 服务插件
  • 多模态插件依赖模型适配器插件
  • 子代理插件依赖任务调度插件
  • 清理插件依赖会话存储插件

声明依赖指在 cordis.yml 中显性告知内核：当前插件需要哪些前置插件、最低内核版本、可选拓展能力。

内核会根据依赖关系自动拓扑排序加载顺序，保证：先加载依赖、后加载当前插件，彻底解决插件时序 Bug。

二、两套依赖体系（必须分清）

Harness 插件存在双层依赖机制，缺一不可：

1. 代码层依赖（package.json）

管理 NPM 代码依赖，如 @deepseek-ai/dsh-core、第三方工具库，用于 TS 编译、代码类型校验。

2. 运行时依赖（cordis.yml）

管理插件运行时序与能力依赖，由 Cordis 内核解析，决定启动加载顺序、能力可用性、冲突检测。这是 Harness 独有的核心机制。

核心结论：npm 依赖只管编译，cordis 声明依赖只管运行。只装 npm 依赖不声明运行时依赖，插件 100% 启动异常。

三、完整声明依赖语法（官方标准）

所有依赖声明全部写在插件根目录 cordis.yml 中，支持：强制依赖、可选依赖、版本区间、内核版本约束。

1. 基础完整模板

name: dsh-plugin-demo
version: 0.1.0
description: 依赖声明演示插件
main: dist/index.js  //强制运行时依赖（必须满足，否则插件加载失败）
dependencies:
  "@deepseek-ai/dsh-core": ">=0.20.0"
  session: ">=0.1.0"
  model-adapter: "*"
// 可选依赖（有则增强，无则降级运行）
optionalDependencies:
  vision-vlm: ">=0.1.0"
// 冲突声明（禁止共存插件）
conflicts:
  old-clean-plugin: "*"

2. 字段详解

  • dependencies：强依赖，缺少则插件直接加载失败，启动报错终止
  • optionalDependencies：弱依赖，有就启用拓展能力，没有就正常降级运行
  • conflicts：冲突声明，禁止与指定插件同时加载，自动互斥

四、版本匹配规则

Harness 严格遵循语义化版本比对：

  • >=0.20.0：大于等于指定最低版本（最常用）
  • ^0.20.0：兼容次版本更新
  • *：任意版本，仅做能力依赖，不锁版本
  • 0.20.x：锁定主版本，兼容补丁更新

五、典型依赖场景实战写法

场景1：通用工具插件（依赖基础内核）

dependencies:
  "@deepseek-ai/dsh-core": ">=0.20.0"

场景2：会话类插件（依赖会话存储能力）

dependencies:
  "@deepseek-ai/dsh-core": ">=0.20.0"
  session: ">=0.1.0"
  trajectory: ">=0.1.0"

场景3：多模态插件（强制视觉模型 + 可选OCR）

dependencies:
  "@deepseek-ai/dsh-core": ">=0.20.0"
  model-adapter: ">=0.1.0"
optionalDependencies:
  ocr-tool: "*"

场景4：互斥插件（新旧清理插件冲突）

conflicts:
  old-session-cleaner: "*"

六、内核自动加载策略（核心机制）

启动 Harness 时，内核会执行四步依赖解析：

  1. 扫描：读取所有已安装、本地挂载插件的 cordis.yml
  2. 构图：生成插件依赖有向无环图（DAG）
  3. 拓扑排序：自动排序加载顺序，依赖优先加载
  4. 校验：版本不满足、缺失依赖、插件冲突直接报错终止

这就是为什么：正确声明依赖后，永远不会出现“插件加载顺序错乱”的问题。

七、条件依赖与动态能力加载（高阶）

Harness 支持基于 Profile 的条件依赖，可实现：不同运行模式加载不同依赖组合。

借助 !!js 条件语法（官方允许的配置脚本能力）实现动态依赖：

conditions:
  - !!js |
    return process.env.DSH_PROFILE === 'creative';
dependencies:
  dev-tools: "*"

仅创造模式下加载开发工具依赖，标准模式自动跳过。

八、查看依赖树与排错命令

1. 查看完整插件依赖树（排错神器）

dsh --profile web --dump-config

可清晰看到：

  • 每个插件的依赖列表
  • 加载顺序拓扑结果
  • 版本匹配结果
  • 冲突检测日志

2. 列出当前环境所有插件依赖关系

dsh plugin --profile web list

九、依赖报错与解决方案（高频问题）

1. Missing dependency（缺失依赖）

现象：插件启动失败，提示缺少 xxx 插件。

原因：声明了强依赖，但当前 Profile 未加载对应插件。

解决：补充安装对应依赖插件，或降级为 optional 可选依赖。

2. Version mismatch（版本不匹配）

现象：内核版本过低，不满足插件要求。

解决：升级全局 Harness npm install -g @deepseek-ai/dsh-core@latest。

3. Plugin conflict（插件冲突）

现象：互斥插件同时加载，启动阻断。

解决：卸载旧版冲突插件，或在 patch 配置禁用冗余插件。

4. 插件加载成功但功能失效

最常见原因：只装了 npm 依赖，没声明运行时依赖，内核加载时序错乱，导致工具注册晚于模型调度。

十、依赖声明最佳开发规范

  1. 所有自定义插件必须声明 core 最低版本，防止新旧内核兼容问题；
  2. 强业务依赖必须写死 dependencies，不允许隐性依赖；
  3. 拓展能力全部写 optionalDependencies，保证主功能不降级；
  4. 新旧替代插件必须加 conflicts 互斥，避免能力覆盖错乱；
  5. 禁止随意使用 * 版本，生产环境建议锁定最低兼容版本。

十一、依赖声明的工程价值

正是因为有了可声明、可校验、可拓扑排序的运行时依赖体系，DeepSeek Harness 才能实现：

  • 插件零顺序依赖、无脑加载
  • 大型 Bundle 批量组合不冲突
  • 社区插件生态稳定共存
  • 版本迭代平滑兼容、降级可用
  • 企业级长期部署稳定可靠

本篇小结

DeepSeek Harness 的声明依赖是其微内核架构稳定的基石。区别于传统框架“靠运气加载顺序”，Harness 通过 cordis.yml 显性声明运行时依赖、可选依赖、版本约束、插件冲突，由内核自动完成拓扑加载与严格校验。

掌握依赖声明，是开发稳定、兼容、可生产部署的高质量 Harness 插件的必备能力，彻底解决插件加载错乱、隐性报错、环境不一致等疑难问题。

标签：

0 条笔记