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

一、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 工具，一切能力均通过插件实现。

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

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

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

三、三种主流安装方式

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

方式 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 市场插件：

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

四、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）

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

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

八、相关资源与延伸阅读

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