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

〇、升级 harness 本体之前先看这里（0.2.0-rc.1，2026-09-28）

0.2.0 线已经开跑：2026-09-28 npm latest 翻转到 0.1.7-rc.2，同日 0.2.0 首个候选（0.2.0-rc.1）登上 next。发布说明里有两件事直接关系插件用户：自动化任务改由可选插件包提供（升级后定时任务可能消失，装上插件包才回来），插件管理界面也做了重做。当天的升级潮在官方讨论区留下成片的兼容性报告——插件成批死亡（#8145）、工作区被清（#8140）、Windows 沙箱 0xC0000142（#8141–#8143）。动 harness 之前：

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

# 2. 预览 0.2.0 要写死精确版本号——候选版永远别用 @latest
npm install -g @deepseek-ai/dsh@0.2.0-rc.1

# 3. 翻车就锁回上一个可用的版本
npm install -g @deepseek-ai/dsh@0.1.7-rc.2

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

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

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

# 1. 安装 DeepSeek Harness 本体（dsh CLI）
npm install -g @deepseek-ai/dsh

# 2. 为当前默认环境安装插件（从 npm 仓库）
dsh plugin add dsh-vision-toolkit

# 3. 为特定 Profile（如 Web 界面 / Headless 模式）安装插件
dsh plugin --profile web add dsh-web-ui
dsh plugin --profile headless add tokenledger

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

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

# 6. 卸载插件并移除配置
dsh plugin remove dsh-vision-toolkit

二、理解 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 add 命令，CLI 会自动解析包名、拉取依赖并将配置写入对应的 Profile。

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

# 为指定 Profile 添加带有参数的插件
dsh plugin --profile web add @scope/custom-theme --port 8080

方式 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 ≥ 20.0.0（推荐 Node 22 LTS）。
  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. 优先选择收录/精选插件：本站目录标有 Curated 或 Featured 徽章的插件已经过社区多轮验证。

七、常见问题 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: 本站目录里的 16,360+ 个插件都经过审核吗？
A: 本站提供全网最全的实时索引，并对热门插件进行多维度体检和多语言深度解析。安装第三方代码时，仍建议遵循上述五分钟安全审查清单。

八、相关资源与延伸阅读

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