DeepSeek Harness 基于 Cordis 微内核，彻底摒弃了传统框架「固定加载顺序、手动重启生效、静态依赖绑定」的落后模式。它独创 依赖驱动加载 + 运行时自动重载 机制，实现插件拓扑排序、自动启停、依赖自愈、无重启热更新，是 Harness 高弹性、高稳定、可工程化部署的核心底层能力。
绝大多数框架插件报错、加载错乱、功能残留、升级崩溃，本质是缺少动态依赖调度与可逆热更新能力。本文系统讲解依赖驱动加载原理、拓扑排序、强弱依赖调度、自动触发重载、热插拔机制、副作用原子回滚与生产级最佳实践。
一、什么是依赖驱动加载
传统 Node/前端插件系统，加载顺序由「文件写入顺序、导入顺序、启动顺序」决定，属于静态顺序加载，极易出现时序 Bug：先加载子插件、后加载依赖插件，直接导致能力缺失、启动报错。
而 Harness 采用 依赖驱动加载（Dependency-Driven Loading）：
内核不看书写顺序，只看依赖关系拓扑图，自动计算合法加载顺序，保证依赖永远优先加载。
插件不再是“按顺序执行的脚本”，而是按需激活、依赖就绪后自动运行的微服务单元。
核心特性
- 自动构建插件依赖有向无环图（DAG）
- 拓扑排序自动纠错加载时序
- 强依赖缺失自动挂起，就绪后自动恢复
- 可选依赖动态适配，自动降级/增强
- 全程无人工干预，内核自治调度
二、强弱依赖对应的加载策略
结合前文声明依赖体系，不同依赖类型，内核加载逻辑完全不同。
1. 强依赖 dependencies（必选）
规则：依赖不就绪，当前插件绝不启动。
- 依赖插件未安装/未激活 → 当前插件进入 Suspended 挂起状态
- 等待依赖插件加载完成 → 自动拓扑补序、自动启动当前插件
- 依赖插件卸载 → 当前插件自动挂起，能力下线，防止空指针与调用异常
适用：模型适配器、会话存储、任务调度、核心工具依赖。
2. 可选依赖 optionalDependencies（柔性）
规则：有无依赖均可运行，存在则增强，缺失则降级。
- 可选依赖存在 → 自动加载拓展能力
- 可选依赖缺失 → 插件主功能正常运行，关闭拓展分支
- 可选依赖状态变更 → 触发插件自动重载适配新环境
适用：多模态拓展、OCR、UI 增强、日志统计类插件。
3. 冲突依赖 conflicts（互斥）
规则：互斥插件共存时，阻断加载，保证环境唯一能力。
避免新旧插件、同类能力插件互相覆盖导致逻辑错乱。
三、完整依赖驱动加载流程
Harness 每次启动、插件变更、配置变更，都会执行一次完整的依赖调度流程：
- 扫描阶段：遍历所有 Profile 插件、本地插件、Bundle 插件，读取 cordis.yml 依赖声明
- 构图阶段：生成全局插件依赖 DAG 拓扑图
- 校验阶段：检查版本匹配、依赖缺失、插件冲突
- 排序阶段：自动计算安全加载顺序（依赖优先、被依赖后置）
- 启停阶段：启动合法插件、挂起缺失依赖插件、禁用冲突插件
- 就绪阶段：所有插件稳定后触发系统 ready 事件，Agent 开始工作
关键结论：你写的插件顺序不生效，内核拓扑排序顺序才是最终真实加载顺序。
四、自动重载机制（热更新核心）
Harness 支持运行时无重启自动重载，无需重启 dsh web 服务、不中断全局运行，是生产级 7×24 挂机的关键能力。
自动重载的底层基石是前文的 可逆副作用 + 插件生命周期：重载 = 旧实例原子销毁 + 新实例原子加载。
1. 哪些场景会触发自动重载
- 插件配置变更（WebUI / patch.yml / settings.yaml）
- 可选依赖插件安装/卸载
- 插件版本升级、本地插件代码更新
- Profile 运行时参数变更
- Bundle 组合包动态更新
2. 自动重载四步原子流程
- 冻结：暂停当前插件新任务接入
- 销毁：逆序执行撤销栈，清空旧插件所有副作用（监听、定时器、工具注册、服务实例）
- 重启：基于最新配置与依赖，重新执行 apply 注册新能力
- 恢复：新插件实例就绪，恢复任务调度
整个过程原子化、无残留、不影响其他插件，真正实现局部热插拔。
五、手动重载命令（开发者必备）
除了内核自动重载，开发者可手动触发单插件热重载，调试效率极高。
# 重载指定插件（无需重启服务）
dsh plugin --profile web reload 插件名
#查看插件状态（区分 Active / Suspended）
dsh plugin --profile web list# 查看依赖拓扑与加载顺序
dsh --profile web --dump-config
优势：修改插件代码、编译后，直接 reload，秒级生效，无需重启整个服务、不丢失会话。
六、依赖联动重载（链式自愈能力）
Harness 支持依赖联动触发重载，形成自愈链路：
插件B（底层依赖）更新/重载 → 所有依赖B的上层插件自动触发重载适配。
典型场景：
- 模型适配器插件更新 → 所有多模态、推理拓展插件自动重载适配新模型能力
- 会话存储插件更新 → 会话清理、轨迹记录插件自动适配新存储结构
这也是 Harness 大型插件生态可以平滑升级、无崩溃迭代的根本原因。
七、常见加载时序问题彻底解决
1. 传统框架通病
- 依赖未就绪，上层插件先加载，调用报错
- 升级插件必须全量重启服务
- 卸载插件残留副作用，内存泄漏、后台残留任务
- 多插件共存互相冲突，能力覆盖错乱
2. Harness 解决方案
- 依赖驱动排序，从根源杜绝时序错误
- 可逆副作用保证重载零残留
- 强弱依赖分层调度，自动挂起/恢复
- 冲突检测阻断非法共存
八、开发最佳实践（适配自动重载）
想要插件完美支持依赖驱动加载与自动重载，代码必须遵循以下规范：
- 所有副作用托管 ctx.effect：定时器、长连接、轮询、监听，必须托管，保证重载可彻底销毁
- 禁止全局变量缓存实例：重载会多实例残留，所有状态存在插件局部作用域
- 区分强弱依赖：核心能力写 dependencies，拓展能力写 optionalDependencies
- 插件幂等设计：apply 函数必须支持多次执行（热重载会反复执行 apply）
- 不裸写初始化逻辑：启动逻辑放在 ready 事件，避免半初始化状态
九、排错指南：加载/重载异常
1. 插件一直处于 Suspended 挂起
原因：强依赖缺失、版本不匹配、依赖插件加载失败。
解决：dump-config 查看依赖树，补齐依赖或降级版本约束。
2. 重载后功能异常
原因：存在未托管副作用、全局实例残留、代码不幂等。
解决：全部 effect 托管，清空全局缓存，保证多次 apply 无副作用叠加。
3. 配置修改不生效
原因：普通参数热生效、核心参数需要重载；旧会话缓存旧插件能力。
解决：执行 reload 重载插件，新建会话测试。
4. 多插件互相覆盖
原因：未声明冲突、依赖顺序错乱。
解决：补充 conflicts 互斥声明，交由内核拓扑排序调度。
本篇小结
依赖驱动加载解决了「插件加载时序混乱、依赖缺失报错、环境不一致」的底层问题，让插件加载完全自治、有序、安全。
自动重载解决了「改代码必重启、升级必中断、插件更新有残留」的工程问题，实现运行时热插拔、平滑迭代、7×24 稳定运行。
两者结合，配合 Harness 可逆副作用生命周期体系，构成了业界领先的高弹性、可自愈、可热更新插件运行架构，也是企业级智能体长期部署的核心基石。
0 条笔记