DeepSeek Harness 加载本地插件

本地插件加载是插件开发、调试、内测的核心环节。DeepSeek Harness 支持三种本地插件加载方案，分别适配快速调试、长期开发、自定义Profile打包场景。

不同于社区 NPM 插件，本地插件支持实时修改、本地热调试、无需发布、完全私密，是插件开发者日常最常用的功能。本文详细讲解全部加载方式、生效规则、调试命令、热更新技巧与常见报错排查。

一、本地插件加载前置条件

本地插件工程必须包含完整 cordis.yml 清单文件
插件必须编译完成（dist/index.js 存在）
Harness 为最新稳定版本，避免内核版本不兼容

二、三种本地插件加载方式（全覆盖）

方式一：命令行临时加载（适合快速调试）

直接通过本地路径安装插件，无需修改配置文件，轻量化、临时生效。

# 加载本地插件到 Web 运行环境
dsh plugin --profile web add ./你的插件文件夹路径

示例：

dsh plugin --profile web add ./dsh-plugin-custom-demo

优点：

零配置、一键加载
不修改全局配置

缺点：重启服务后需要重新加载。

方式二：Profile 配置永久加载（推荐开发模式）

修改用户 Profile 配置文件，永久绑定本地插件，每次启动自动加载，适合长期开发调试。

1. 找到本地配置文件

Mac/Linux：~/.dsh/settings.yaml
Windows：C:\Users\用户名\.dsh\settings.yaml

2. 写入本地插件路径

在配置中新增 plugins 节点：

plugins:
  - /绝对路径/dsh-plugin-custom-demo

建议使用绝对路径，避免启动路径不一致导致加载失败。

3. 重启服务生效

dsh web

方式三：自定义 Bundle 集成插件（高阶工程化）

适合批量管理多个本地插件、自定义专属 Agent 模板，可打包为 .dshpreset 预设包。

在自定义 bundle 配置中统一引入本地插件，实现一套配置、多环境复用。

三、查看本地插件加载状态

校验插件是否成功载入、是否冲突、是否启用。

1. 查看已加载插件列表

dsh plugin --profile web list

2. 查看完整插件配置树（排错神器）

dsh --profile web --dump-config

可查看：插件加载顺序、配置参数、是否覆盖原生能力、是否存在冲突。

四、本地插件热更新调试技巧

插件开发需要反复修改调试，这里提供最高效的开发流程：

开启 TS 自动编译：tsc --watch
修改插件代码自动编译
重启 dsh web 即可加载最新代码

虽然不支持运行时热重载，但配合 watch 编译，调试效率极高。

五、本地插件卸载方法

1. 命令行安装的本地插件卸载

dsh plugin --profile web remove 插件名

2. 配置文件挂载的插件卸载

直接删除 settings.yaml 中对应的插件路径，重启服务即可。

六、本地插件生效核心规则（必看）

插件对新建会话生效：已存在的旧会话不会加载新插件，调试必须新建会话。
本地插件优先级高于官方插件：可覆盖官方工具、模型配置。
多插件冲突：同名工具后加载覆盖先加载。
环境隔离：web / tui / standard 插件互相独立，互不干扰。

七、本地插件常见报错与解决方案

1. 提示找不到 cordis.yml

插件根目录缺少清单文件，或路径配置错误，必须保证路径直接指向包含 cordis.yml 的文件夹。

2. 插件加载成功但工具无响应

工具描述不清晰，模型无法触发调用
未新建会话，旧会话不加载新插件能力

3. 模块缺失、依赖报错

本地插件未安装依赖，进入插件目录执行 npm install。

4. 版本不兼容

本地插件依赖的 dsh-core 版本过高，升级全局 Harness 即可解决。

5. 路径中文/空格导致加载失败

插件目录尽量使用纯英文路径，避免特殊字符。

八、本地插件最佳开发流程

搭建插件工程、编写代码、tsc 编译
使用 dsh plugin add 临时快速调试
稳定后写入 settings.yaml 永久挂载
反复迭代、热编译调试
最终打包发布 NPM / 保存为私有 preset

本篇小结

加载本地插件是插件开发的日常核心操作。三种加载方式分别适配调试、长期开发、工程化打包场景。熟练掌握本地插件加载、状态查看、热调试、排错方法，可以完全私有化定制 Harness 能力，不依赖任何社区插件，实现完全自主可控的智能体运行环境。