DeepSeek Harness插件概念详解与安装教程

DeepSeek Harness（简称 DSH）采用"一切皆插件"的架构设计，模型、工具、界面、沙箱等所有能力都由插件组合而成，用户无需修改源码即可按需扩展。本教程将介绍 DSH 插件的基本概念、命令行与手动两种安装方式、插件市场的使用方法，并推荐三款经过社区验证的常用插件（dsh-better-sidebar、dsh-theme-plugin 与 dshmarket），帮助你快速构建适合自己的 Agent 工作台。

前置教程

如想快速开始学习本教程，你可能需要先完成以下前置教程：

• DeepSeek Harness 安装与使用教程，本教程在此基础上深入讲解 DSH 的插件体系，需先完成 DSH 安装并运行 Web 界面。
• Node.js和Npm安装与使用教程，dsh 插件管理命令底层调用 pnpm 完成安装，依赖 Node.js 环境。
• Harness概念详解，理解 Harness 在 Agent 架构中的定位，以及插件化架构的由来。

1. DSH 插件概念介绍

1.1 什么是 DSH 插件

DeepSeek Harness 的设计哲学是"一切皆插件"（everything is a plugin）：模型接入、工具调用、会话持久化、沙箱隔离、任务循环、调度、Web 界面等所有能力，全部由一个个可独立加载、替换和卸载的插件组合而成。插件系统基于 Cordis 插件框架实现，支持插件的依赖管理、加载与卸载，以及配置的逐层覆盖。

从工程角度看，一个 DSH 插件就是一个npm 包（也可以来自 Git 仓库或本地目录），它在内部实现为一个 Cordis 插件，并通过 package.json 中的 dsh 字段声明自身的能力。插件可以做到以下几类事情：

模型与插件的关系可以这样理解：插件之于 DSH，相当于应用商店的应用之于手机系统。系统本身只提供最小内核，其余功能都由用户自由安装、组合、替换。

1.2 Profile：插件的组合单元

DSH 以 profile 为单位组织插件。一个 profile 就是一份可独立启动的插件组合配置，存放在 $DSH_HOME/profiles/<名称>/ 目录下（Windows 下 $DSH_HOME 默认为 C:\Users\<用户名>\.dsh）。

dsh web 实际启动的是 web profile，dsh --profile headless "任务" 启动的是 headless profile。web 与 headless profile 在首次使用时由 dsh 自动初始化；其他自定义 profile 则通过 dsh plugin 命令创建。

一个 profile 目录包含以下关键文件：

1.3 组合包（Bundle）与配置树叠加

DSH 的配置采用"空根 + 逐层叠加"的方式组合。每个 profile 的 dsh.profile.bundles 列表按顺序列出组合包（bundle）。组合包是声明了 dsh.bundle.patch 字段的依赖包，安装后会自动加入该列表，它的补丁文件会成为配置树的一层。

配置树的叠加顺序为：空根 → 各组合包的补丁（按 bundles 列表顺序）→ profile 自身的 cordis.patch.yml → 主目录级 $DSH_HOME/cordis.patch.yml → --patch 参数指定的覆盖层，后一层覆盖前一层。

DSH 官方提供三个内置组合包：@deepseek-ai/dsh-base（共享核心，每个 profile 的第一层补丁）、@deepseek-ai/dsh-web-app（Web 界面层）、@deepseek-ai/dsh-headless（命令行模式层）。内置组合包先从 dsh 安装目录解析，再回退到 profile 自身的 node_modules 中解析；第三方插件则安装在 profile 的 node_modules 里。

1.4 插件的构成与分类

一个完整的 DSH 插件通常由两部分组成：host 端（运行在 Node.js 服务端的逻辑，如工具、服务、配置）和可选的 client 端（运行在浏览器的界面代码，通过 dsh.client 字段声明，由 Web UI 动态加载）。只改动界面的插件（如主题）可以只包含 client 端。

按照功能，本教程重点介绍的三款插件可以分为以下两类：

判断一个 npm 包是否是 DSH 插件，可以查看它的 package.json 中是否声明了 dsh 字段（如 dsh.bundle.patch 或 dsh.client）。声明了 dsh.bundle.patch 的包会成为 profile 的配置层；仅作为普通依赖安装的包不会进入配置树，只会收到一条提示信息。

1.5 插件的工作原理

dsh plugin 命令是插件的管理入口，它本身不做安装工作，而是把剩余参数转发给 pnpm，在 profile 目录中执行。安装成功后，dsh 会重新读取 profile 的 package.json，凡是解析到声明了 dsh.bundle.patch 的依赖，就自动追加到 dsh.profile.bundles 列表（这个过程称为"自动挂载"），并删除已卸载或不再声明补丁的条目。

2. DSH 插件安装方式

2.1 环境准备

安装插件前，请确认以下环境就绪：

dsh --version
pnpm --version
git --version

如果你的 dsh 未加入 PATH（例如使用 npx 方式启动），可以把所有命令替换为 npx @deepseek-ai/dsh plugin --profile web add 包名 的形式。

2.2 命令行安装（推荐）

安装插件最常用的方式是 dsh plugin 命令。命令格式为：

dsh plugin --profile <profile名称> <pnpm参数>

以向 web profile 安装主题插件 dsh-theme-plugin（中国传统色主题包）为例：

dsh plugin --profile web add dsh-theme-plugin

命令执行过程如下：

1. 如果 profile 目录不存在，dsh 会先按模板初始化该 profile
2. 将 add dsh-theme-plugin 转发给 pnpm，在 profile 目录中安装依赖
3. 安装成功后自动把 dsh-theme-plugin 加入 dsh.profile.bundles 列表
4. 重启 dsh web，打开浏览器刷新页面，插件生效

安装过程中可能会看到 WARN Issues with peer dependencies found 的提示，例如 missing peer @deepseek-ai/cordis（功能多的大插件可能一次列出十几个 missing peer）。这是 pnpm 的 peer 依赖警告，不是安装失败，命令末尾出现 Done 并列出依赖即表示成功。@deepseek-ai/cordis 等官方包是 DSH 的插件框架与宿主能力，运行时由官方组合包 @deepseek-ai/dsh-base 提供；profile 的 pnpm-workspace.yaml 设置了 autoInstallPeers: false，pnpm 不会自动补齐这些 peer，仅输出警告。请勿手动执行 dsh plugin --profile web add @deepseek-ai/cordis，以普通依赖方式安装框架会生成第二份拷贝，可能干扰官方插件的加载。

dsh plugin 支持所有 pnpm 子命令，常用参数如下：

部分插件的文档建议在命令末尾追加 -w（--workspace-root），这是针对 pnpm 9 对 workspace 根目录的限制；pnpm 10 及以后通常不需要。如果安装时报 ERR_PNPM_ADDING_TO_ROOT，在命令末尾加上 -w 即可。

2.3 支持的安装来源

dsh plugin add 的安装来源与 pnpm 保持一致，包括：

需要特别注意两点：

• Git 源插件的构建脚本：Git 仓库通常需要在安装时执行 prepare 脚本构建，而 pnpm 10 起默认阻止构建脚本，命令失败时会提示把对应的 key 添加到 profile 目录下的 pnpm-workspace.yaml 的 allowBuilds 中，添加后重新执行安装命令。
• 镜像源同步滞后：国内 npm 镜像（如 npmmirror）对 dist-tag 的同步存在滞后，@latest 可能解析到旧版本。遇到"装下来版本不对"的情况，可以显式指定版本号（如 add 包名@0.3.8），或临时指定官方源：dsh plugin --profile web add 包名 --registry=https://registry.npmjs.org。

2.4 更新与卸载插件

更新插件：pnpm add 不会修改已声明的版本范围，例如 profile 中声明了 ^0.1.2，执行 add 包名 不会升级。跨大版本升级必须显式指定最新版：

dsh plugin --profile web add 包名@latest

或使用 pnpm 的 update 语义配合 --latest：

dsh plugin --profile web update 包名 --latest

卸载插件：

dsh plugin --profile web remove 包名

卸载后 dsh 会自动把该包从 dsh.profile.bundles 中移除。更新或卸载后重启 dsh web 使改动生效。

2.5 手动挂载（高级）

多数插件通过 dsh plugin add 安装后会自动挂载，无需手动操作。只有在以下场景才需要手动编辑配置文件：

• 插件包没有声明 dsh.bundle.patch，需要手动把它挂进配置树
• 想调整插件在配置树中的顺序或精确控制加载条目

手动挂载的方法是编辑 profile 目录下的 cordis.patch.yml，追加一条 insert 记录：

- insert:
    - id: theme-plugin
      name: 'dsh-theme-plugin'

也可以直接编辑 package.json 中的 dsh.profile.bundles 列表，把包名加入组合包清单：

{
  "name": "dsh-profile-web",
  "private": true,
  "dependencies": {},
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "dsh-theme-plugin"
      ]
    }
  }
}

手动挂载与 dsh plugin add 自动挂载是两种互斥的方式，不要同时使用：同一插件如果被重复插入，启动时会因 duplicate loader entry id 报错而无法启动。使用 dsh plugin add 安装的插件，无需再手动添加 insert 记录。

2.6 验证插件安装

安装并重启后，可以通过两种方式确认插件已生效：

方式一：检查配置树。不启动 Web 界面即可查看组合后的完整配置树：

dsh --profile web --dump-config

方式二：查看 Web UI。打开 http://127.0.0.1:3080，进入 设置 → 插件，会看到每个注册了配置命名空间的插件以卡片形式列出，可以直接在界面上修改其配置项并保存。

3. 插件市场

3.1 插件生态与数据源

DSH 的插件生态主要分布在三个地方：

在此基础上，社区开发了插件市场插件，安装后可以在 Web 界面里浏览、搜索、一键安装插件，无需手敲命令行。下面介绍目前最流行的选择 dshmarket。

3.2 dshmarket：社区可视化插件市场

dshmarket（npm 包名 dshmarket）是目前最流行的 DSH 插件市场，数据源为社区精选列表 awesome-dsh-plugin，收录 300 多个插件并持续增长。安装命令：

dsh plugin --profile web add dshmarket

重启 dsh web 后，打开 设置 → Plugin Market 即可使用。主要功能包括：

dshmarket 只做"市场"本身，插件目录来自社区精选列表仓库 awesome-dsh-plugin/awesome-dsh-plugin。想让自己开发的插件被收录，需要向该仓库提交 PR。

4. 推荐插件

以下插件均来自 npm 社区，配合第 3 章的 dshmarket 使用。安装命令统一为 dsh plugin --profile web add <包名>，装完重启 dsh web 生效。

4.1 界面与工作台增强

4.2 推荐安装组合

对于大多数用户，推荐按以下顺序组合安装，兼顾市场发现与日常体验：

# 第一步：装可视化插件市场，日常浏览、搜索、安装插件
dsh plugin --profile web add dshmarket

# 第二步：安装界面增强插件
dsh plugin --profile web add dsh-better-sidebar
dsh plugin --profile web add dsh-theme-plugin

安装完成后重启 dsh web，刷新浏览器页面，即可在设置中看到 "Plugin Market" 新入口，以及侧边栏与主题等界面变化。

插件均为第三方代码，安装前建议先查看其 GitHub 仓库与 README，了解它解决的问题、维护活跃度与安全说明。dshmarket 只接受精选注册表中的来源，能显著降低安装风险。

5. 总结

5.1 核心内容回顾

• DSH 采用"一切皆插件"架构，插件是一个 npm 包，基于 Cordis 框架，可注入工具、注册界面、提供服务、叠加配置
• profile 是插件的组合单元，配置树按"组合包补丁 → profile 补丁 → 全局补丁 → --patch 覆盖层"的顺序叠加
• 安装插件的主命令是 dsh plugin --profile web add <包名>，底层转发给 pnpm 在 profile 目录执行，安装后自动挂载到 dsh.profile.bundles
• 支持 npm registry、GitHub 仓库、Git URL、本地目录、tarball 等多种安装来源，Git 源插件需注意 allowBuilds 放行
• 插件市场：dshmarket（社区可视化插件市场），安装后可在 Web 界面浏览、搜索、一键安装插件
• 推荐插件：dsh-better-sidebar（右侧栏与底部面板双工作台）与 dsh-theme-plugin（中国传统色主题），配合 dshmarket 浏览与安装

5.2 常见问题与解答

问：安装插件后 Web 界面没有变化？

答：多数插件需要重启 dsh web 进程并刷新浏览器页面（涉及 client 端新代码时尤其如此）。若仍未生效，执行 dsh --profile web --dump-config 检查插件是否进入配置树，并查看启动日志中的报错。

问：安装时报 ERR_PNPM_ADDING_TO_ROOT 怎么办？

答：这是 pnpm 9 对 workspace 根目录的限制，在命令末尾追加 -w（--workspace-root）即可；pnpm 10 及以后一般不需要。

问：安装时提示一堆 missing peer 依赖警告？

答：这是 pnpm 的 peer 依赖提示，不是安装失败，命令末尾的 Done 与依赖列表说明插件已安装成功。装 dsh-better-sidebar 这类大插件时可能一次列出十几个 missing peer（@deepseek-ai/cordis、@deepseek-ai/dsh-client-runtime、react、react-dom 等），它们都由 DSH 宿主运行时提供：官方组合包把对应包安装在共享 node_modules 中，版本与插件声明一致（如 react@18.3.1 满足 ^18.2.0）。profile 的 pnpm-workspace.yaml 设置了 autoInstallPeers: false，pnpm 静态检查看不到宿主提供的依赖，因此只警告不补齐。个别如 xterm 的 deprecated 提示也只是上游改名（xterm → @xterm/xterm），旧包仍可用。请不要手动安装 @deepseek-ai/cordis 等官方包：以普通依赖方式安装会生成第二份拷贝，可能干扰官方插件的加载。

问：安装后设置页报 settings-not-exposed 错误？

答：DSH 的主机 API 网关只放行白名单内的配置命名空间，部分插件首次启动时会自行补丁该白名单，但当前进程仍按旧名单响应。重启 dsh web 一次即可；若错误持续，检查启动日志中 [settings-expose] 开头的提示。

问：装了插件后 dsh web 启动失败怎么办？

答：先定位问题层：删除 profile 目录 cordis.patch.yml 中对应插件的 insert 记录，或用 dsh --profile web --patch <空补丁文件> 临时绕开用户层排查，再结合启动日志定位冲突来源。

问：插件安全吗？

答：插件是第三方代码，运行在本地并拥有工作区访问权限，应安装来源可信、维护活跃的插件。dshmarket 提供了来源白名单、构建脚本默认阻止等防护，安装后仍建议关注其 GitHub 仓库的 Issue 与安全说明。

问：dsh plugin 与直接执行 pnpm add 有什么区别？

答：dsh plugin 会在 pnpm 执行成功后自动把声明了 dsh.bundle 的依赖挂载进 dsh.profile.bundles 配置层；直接运行 pnpm add 只写入依赖，不会自动挂载，需要手动编辑配置。日常使用请优先用 dsh plugin。