如何安装 DeepSeek Harness（dsh）插件：CLI 命令、Profile 切换与排错速查指南（2026）

精确命令

要把 npm 或 GitHub 上的 DeepSeek Harness 插件装进 Web UI 的 profile，命令是：

dsh plugin --profile web add <package-or-source>

--profile web 写在 add 前面。具体写法：

# npm：作用域包或普通包名
dsh plugin --profile web add @liustack/modlens
dsh plugin --profile web add dshmarket

# GitHub：仓库地址，可锁定分支、Tag 或 commit
dsh plugin --profile web add github:owner/repo
dsh plugin --profile web add github:owner/repo#main

# 不装全局时的 npx 写法
npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens

装完重启，插件树才会重组：

npx @deepseek-ai/dsh web      # 或：dsh web

dsh plugin 不是第二套包管理器：它把参数转给 profile 目录（~/.dsh/profiles/web/）里的 pnpm，然后把装上的包并入 profile 的 bundle 列表，插件才会真正加载。所以参数必须是 pnpm 认识的写法——registry 包名、github:owner/repo、link:/path/to/plugin——也正因为如此，--profile 必须写在前面：add 之后的内容都是 pnpm 的参数，不是启动器的。

需要 Node.js 24.9 或更新版本（官方 README 与 @deepseek-ai/dsh npm 包声明的下限，Node 22 已不再支持）。本页事实在 2026-11-12 对照官方 README、CLI 文档与已发布的 npm 包核过。

升级 harness 本体之前先看这里

dsh 还是开发者预览版：2026-09-28 的 0.2.0 升级潮之后，npm latest 又变过好几次，官方讨论区当时留下了成片的兼容性报告——插件成批死亡（#8145）、工作区被清（#8140）、Windows 沙箱 0xC0000142（#8141–#8143）。那次发布还有两件事影响插件用户：自动化任务改由可选插件包提供（升级后定时任务可能消失，装上插件包才回来），插件管理界面也做了重做。动 harness 之前：

# 1. 备份你的 Profile
cp ~/.dsh/profiles/<name>/cordis.patch.yml ~/dsh-profile-backup.yml

# 2. 先查清楚实际发布的是什么版本——别假设 @latest 就是稳定版
npm view @deepseek-ai/dsh version          # 2026-11-12 是 0.2.2-rc.1

# 3. 升级时写死精确版本号，翻车就锁回上一个可用版本
npm install -g @deepseek-ai/dsh@<version>

0.2.x 升级波及的逐条「症状 → 原因 → 修复」在排错指南。

一、CLI 命令速查表（Quick Reference）

如果你熟悉 CLI 流程，可以直接参考以下高频命令速查表：

# 1. 启动 harness（Node.js 24.9+），全局安装是可选的
npx @deepseek-ai/dsh web

# 2. 把插件装进 web profile（从 npm registry）
dsh plugin --profile web add dshmarket
dsh plugin --profile web add @liustack/modlens

# 3. 装进其他 profile（headless 或自建 profile）
dsh plugin --profile headless add tokenledger

# 4. 从 GitHub 仓库直接安装（支持锁定分支 / Tag / commit）
dsh plugin --profile web add github:volcengine/openviking#main

# 5. 安装本地正在开发的插件（调试模式）
dsh plugin --profile web add link:/path/to/my-dsh-plugin

# 6. 卸载插件
dsh plugin --profile web remove dshmarket

# 7. 查看某个 profile 最终组装成了什么
dsh --profile web --dump-config

二、理解 DSH 的“一切皆插件”架构

DeepSeek Harness（dsh）采用 Cordis 微内核架构。在 DSH 中，无论是 UI 主题、模型推理中转、视觉 OCR、长短期记忆还是 CLI 工具，一切能力均通过插件实现。

生态也很好逛：仅 GitHub 的 dsh-plugin 主题就收录了数千个公开仓库，官方 deepseek-ai/deepseek-harness 位居榜首。

GitHub 上的 dsh-plugin 主题，数千个社区插件仓库。

为什么 DSH 具有天生的“完全可逆性”？

传统的包管理器在卸载模块时容易留下残留文件或脏状态。而在 DSH 中，插件的注册本质上是向配置层注入一条声明式记录：

• 启动时：Cordis 容器读取配置，自底向上构建插件依赖树。
• 卸载时：只需移出配置记录并重启，插件挂载的所有 API、工具、上下文钩子和 UI 面板立刻全部撤销，真正做到零残留。

三、三种主流安装方式

根据使用习惯，你可以选择最适合的安装方式：

官方课程讲义把日常三条路概括成一张图：敲一条命令、对话里说一声、去插件市场点一下——下文再展开到配置文件与 Profile。

官方总结的三种插件安装方式。

方式 1：CLI 命令行一键添加（推荐）

dsh plugin --profile <name> add <spec> 会通过 pnpm 解析包、装进该 profile，并把 bundle 写进 profile 的 dsh.profile.bundles 列表。

# 安装指定版本
dsh plugin --profile web add dsh-mnemon@^1.2.0

# 装进具名 profile，而不是 web
dsh plugin --profile headless add tokenledger

方式 2：配置文件显式声明（cordis.patch.yml）

如果你习惯使用 Git 统一管理团队或个人的开发环境，可以直接编辑配置层文件：

# ~/.dsh/profiles/default/cordis.patch.yml 或项目根目录 .dsh/cordis.patch.yml
plugins:
  # 基础工具与视觉插件
  dsh-vision-toolkit:
    enabled: true
    options:
      ocrEngine: 'default'
      maxImageSizeMb: 10

  # 记忆增强插件
  volcengine/openviking:
    enabled: true
    options:
      persistPath: '~/.dsh/memory/viking.db'

编辑完成后，执行 dsh 重启会话即可加载。

方式 3：可视化市场一键安装

对于通过 Web 界面使用 DSH 的开发者，可以首先安装 dsh-market 市场插件：

最快的方式是对话安装：直接说一声要装什么——下图中 DSH 自动拉取、校验并热重载了 dshmarket v1.14.1，全程没离开聊天窗口。

在对话里让助手装 dsh-market，装完自动热重载。

1. 在 Web 界面进入 Settings → Plugin Market。
2. 搜索所需插件（如 dsh-web-ui 或 modlens）。
3. 点击 Install 按钮，系统将在后台自动完成配置更新与热载入。

在社区插件市场弹窗中输入 dsh-market 搜索，目录会立刻收敛到匹配的插件卡片。

Web UI 内置的社区插件市场搜索。

点开卡片就是详情弹窗：功能简介、精确的 dsh plugin add 手动命令，以及跳转源码仓库和 DSH 市场的入口。

dsh-market 详情弹窗，自带手动安装命令。

装好之后都在同一个弹窗里管理：「已安装」页签给每个插件配了启用开关、更新状态和卸载按钮。

已安装插件集中在同一个弹窗里管理。

国内网络加速：官方换源与 npmmirror 镜像

国内网络环境下，从 npm 官方源安装插件经常卡在下载阶段，两条加速路线：

1. 官方换源入口（已随 0.1.7 线进入 latest 通道）：官方发布说明确认，插件管理中的安装已支持选择 官方源 / npmmirror 镜像站 / 自定义源，并提供安装示例与进度展示；0.1.7 线还新增了「首次安装且未配置源时，自动优先选择可访问的最优 npm 源」。npm latest 已于 2026-09-28 翻转到 0.1.7 线（0.1.7-rc.2），当前稳定版即带此能力。

2. npmmirror 镜像（立即可用）：社区通用做法是把 npm registry 指向国内镜像站，让插件下载走加速通道：

# 将 registry 指向 npmmirror（去掉 -g 则只对当前项目生效）
npm config set registry https://registry.npmmirror.com

# 之后正常安装插件即可
dsh plugin add <owner>/<repo>

dsh plugin add github:owner/repo 直连 GitHub 超时时，可先克隆到本地再按方式 1 的调试模式从本地路径安装，或配置代理后重试。npmmirror 是 npm 官方数据的完整镜像，包内容一致；企业内网也可在官方换源入口里填自己的私有 registry（自定义源）。

四、Profile 多环境隔离与切换

Profile 是 DSH 管理多场景插件组合的核心机制。例如，你在本地写代码需要强大的 Web UI 与视觉调试工具，但在 CI/CD 自动流水线上只需要轻量级的 Headless 模式。

Profile 配置路径层级

1. 全局 Profile：~/.dsh/profiles/<profile-name>/cordis.patch.yml（适用于所有工作区）
2. 项目级 Profile：<project-root>/.dsh/cordis.patch.yml（仅在当前项目生效，优先级高于全局）

切换与启动 Profile

# 以 Web UI 模式启动（加载 web profile 中的面板与皮肤）
dsh --profile web

# 以 Headless 自动化模式启动（仅加载核心推理与代码执行插件）
dsh --profile headless --task "run all tests and fix lint errors"

# 以 TUI 纯终端增强模式启动
dsh --profile tui

五、常见错误与排错百科（Troubleshooting）

在安装或加载插件时遇到问题？请对照以下高频场景排查：

还有一种配额失败要留意：市场安装过程中，轨迹可能闪出红色 Insufficient Balance 条目——DeepSeek API 余额用尽，充值后重试即可。

余额耗尽时，市场安装会被拦下。

1. Plugin failed to register / Lifecycle timeout

• 症状：启动 dsh 时终端提示插件初始化超时或找不到导出符号。
• 排查步骤：
  1. 检查 Node.js 运行环境：dsh 需要 Node.js 24.9 或更新版本（Node 22 已不再支持）。
  2. 检查依赖包完整性：若使用 Git 源码安装，确认是否执行过 pnpm install && pnpm build。

2. Profile patch collision / Override order issue

• 症状：同时安装了两个同类型插件（如两个侧边栏 UI 插件），界面出现重叠或样式错乱。
• 排查步骤：
  1. 打开 cordis.patch.yml，检查插件列表顺序。排在后面的插件会覆盖前面的同名服务。
  2. 将冲突插件之一设为 enabled: false，或者将两者分配到不同的 Profile 中隔离运行。

3. Permission denied / Sandbox security policy violation

• 症状：插件尝试读写文件或发起网络请求时被拦截报错。
• 排查步骤：
  1. DSH 默认处于 read-only 安全沙箱模式。
  2. 若该插件确实需要写权限（例如自动化重构插件），在启动参数中放宽权限：dsh --sandbox workspace-write。
  3. 详见 DSH 安全沙箱指南。

4. pnpm-workspace allowlist / ESM CJS 模块加载失败

• 症状：在 monorepo 项目下安装第三方插件提示模块找不到。
• 排查步骤：
  1. 确保在根目录 package.json 或 pnpm-workspace.yaml 中将插件包列入允许清单。
  2. 优先使用 npm 发布的官方兼容版本。

六、五分钟插件安全审查清单

在安装任何未经验证的第三方插件前，建议花五分钟执行自检：

1. 查阅 README：明确插件功能边界、所需环境变量以及是否包含外呼网络请求。
2. 检查开源许可证（License）：优先选择 MIT、Apache-2.0 等合规开源协议。
3. 快速扫描入口源码：确认其没有扫描工作区之外的敏感文件（如 ~/.ssh/、~/.aws/）。
4. 查看社区健康度与活跃度：本站每个插件详情页均公开展示 GitHub Star 数、近 90 天 Push 活跃度、Open Issues 与归档状态。
5. 看看有没有我们自己的评测：带「已复核」标记的页面附有我们自己对该仓库的评测；「精选」只表示该仓库出现在社区 awesome 清单里。两者都不等于安全审计。

七、常见问题 FAQ

Q: 有没有类似 npm install 那样的一行命令？
A: 有的。可以使用 dsh plugin add <package>（例如 dsh plugin add dsh-vision-toolkit），它会自动完成包拉取与配置文件追加。

Q: 装完插件需要重启 DSH 吗？
A: 需要。DSH 在启动时动态编译插件树，修改配置后重新执行 dsh 命令即可生效。

Q: 怎么彻底卸载一个 DSH 插件？
A: 运行 dsh plugin remove <package>，或直接在 cordis.patch.yml 中删掉那一行配置并重启。得益于 Cordis 的可逆设计，不会残留任何孤儿文件。

Q: 本站目录里的 29,000+ 个插件都经过审核吗？
A: 没有。绝大多数条目是从 GitHub 自动收录的，按仓库自己的描述列出，我们不会审计其代码。带「已复核」标记的页面附有我们自己的评测，但同样不是安全审计；「精选」只表示该仓库出现在社区 awesome 清单里。安装任何第三方代码前，请务必先走一遍上面的五分钟安全审查清单。

八、相关资源与延伸阅读

• 2026 必装插件排行榜 Top 10 与场景套件 —— 复制一条命令即可装机
• 2026 必装插件推荐（12 款首选深度解读） —— 刚装好 DSH 不知道装什么？看这篇
• 按场景探索精选合集 —— 聚合高频开发工作流
• DSH 配置文件详细语法与叠加规则 —— 深入掌控 Cordis Patch 机制
• 从零编写你的第一个 DSH 插件 —— 插件开发新手教程
• 浏览 22 大分类全部插件目录 —— 按分类检索全部收录条目