DeepSeek Harness: 安装插件与配置加载顺序

Q: 可以从私有 npm registry 安装吗？

可以。配置 .npmrc ： text @dsh-plugin:registry=https://my-registry.com/

Q: 多个 patch 文件可以叠加吗？

当前只支持一个 cordis.patch.yml 。如果需要多个补丁，合并到一个文件中。

Q: 插件安装失败怎么办？

检查网络连接、npm registry 可达性、包名是否正确。查看 pnpm-error.log 获取详细错误信息。

最后更新：2026-08-31

从"写插件"到"用插件"——本课聚焦插件的实际安装与配置管理。四种安装方式覆盖所有场景，配置加载优先级确保"局部覆盖全局"，热补丁让生产环境的紧急修改变得安全可控。

💡 提示：安装插件后最重要的一步是 --dump-config——确认你的插件真的出现在最终配置中。很多"插件没生效"的问题，其实只是配置优先级搞错了。

📋 前置知识：已完成 12-local-plugin.md 和 26-bundle-profile.md

1. 你将学到

npm 安装插件
GitHub 仓库直接安装
tarball 安装
配置加载优先级
cordis.patch.yml 热补丁
插件冲突解决

2. npm 安装插件

(1) ▶ 示例 1

BASH

# 安装最新版本
pnpm add @dsh-plugin/database

# 安装指定版本
pnpm add @dsh-plugin/database@1.2.0

# 安装到 devDependencies
pnpm add -D @dsh-plugin/debug-tools

(2) 安装后注册

npm 安装的插件需要在 cordis.yml 中注册：

YAML

# cordis.yml
plugins:
  '@dsh-plugin/database':
    config:
      connection: 'postgresql://localhost/mydb'

(3) 使用 dsh plugin add

DSH 提供了更便捷的安装命令：

BASH

# 安装并自动注册
dsh plugin add @dsh-plugin/database

# 安装时指定配置
dsh plugin add @dsh-plugin/database --config.connection='postgresql://localhost/mydb'

# 安装输出
📦 Installing @dsh-plugin/database@1.2.0...
✅ Plugin installed and registered!

(4) ▶ 示例 4

JSON

// package.json
{
  "dependencies": {
    "@dsh-plugin/database": "^1.2.0",
    "@dsh-plugin/redis": "~2.1.0"
  }
}

符号	含义	更新范围
`^1.2.0`	兼容 1.x	1.2.0 ~ 1.9.9
`~2.1.0`	兼容 2.1.x	2.1.0 ~ 2.1.9
`1.2.0`	精确版本	只用 1.2.0

3. GitHub 仓库直接安装

(1) 安装方式

BASH

# 安装默认分支
pnpm add github:alice/dsh-plugin-redis

# 安装指定分支
pnpm add github:alice/dsh-plugin-redis#feature/cluster

# 安装指定标签
pnpm add github:alice/dsh-plugin-redis#v2.1.0

# 安装指定 commit
pnpm add github:alice/dsh-plugin-redis#abc1234

(2) 使用 dsh plugin add

BASH

dsh plugin add github:alice/dsh-plugin-redis

(3) GitHub 安装的注意事项

注意点	说明
需要 Git	机器上必须安装 Git
仓库结构	必须是有效的 Node.js 包（有 package.json）
构建步骤	仓库可能需要先 build
网络	需要访问 GitHub
版本锁定	建议用 commit hash 而非分支名

(4) package.json 中的表示

JSON

{
  "dependencies": {
    "@dsh-plugin/redis": "github:alice/dsh-plugin-redis#v2.1.0"
  }
}

4. tarball 安装

(1) 从 URL 安装

BASH

# 从远程 tarball 安装
pnpm add https://example.com/dsh-plugin-custom-1.0.0.tgz

# 从本地 tarball 安装
pnpm add ./packages/dsh-plugin-custom-1.0.0.tgz

(2) 使用 npm pack 创建 tarball

BASH

# 在插件项目中
cd dsh-plugin-my-tool
npm pack
# 生成: dsh-plugin-my-tool-1.0.0.tgz

# 在 DSH 项目中安装
pnpm add ../dsh-plugin-my-tool/dsh-plugin-my-tool-1.0.0.tgz

(3) tarball 的适用场景

场景	说明
私有插件	不发布到 npm，直接分发 tgz
离线安装	无法访问 npm 和 GitHub
CI/CD	构建产物直接安装
预发布测试	安装候选版本测试

(4) 三种安装方式对比

方式	命令	网络需求	版本管理	适用
npm	`pnpm add @dsh-plugin/xxx`	npm registry	✅ semver	公开插件
GitHub	`pnpm add github:user/repo`	GitHub	⚠️ 分支/tag	开发中插件
tarball	`pnpm add ./xxx.tgz`	无	❌ 手动	私有/离线

5. 配置加载优先级

配置加载顺序

(1) 五层优先级

graph TB
    L5["Layer 5: CLI 参数<br/>(最高优先级)"]
    L4["Layer 4: cordis.patch.yml"]
    L3["Layer 3: 项目 cordis.yml"]
    L2["Layer 2: Profile 配置"]
    L1["Layer 1: Bundle 默认<br/>(最低优先级)"]
    L5 --> L4 --> L3 --> L2 --> L1

(2) ▶ 示例 2

TEXT 📖 仅展示

Bundle 默认:    plugins: [core, llm, tools], port: 5173
Profile (web):  plugins: [+web-ui]
项目配置:       plugins: [+my-tool], port: 8080
Patch:          plugins: [+debug-tools], debug: true
CLI:            port: 3000

最终:           plugins: [core, llm, tools, web-ui, my-tool, debug-tools]
                port: 3000, debug: true

(3) 同名插件处理

当多个层注册同名插件时，高优先级层覆盖低优先级层：

TEXT 📖 仅展示

Bundle:    llm → deepseek-adapter
项目配置:  llm → openai-adapter (覆盖)
Patch:     llm → custom-adapter (再覆盖)

最终: llm → custom-adapter

(4) 查看加载顺序

BASH

pnpm dsh web --patch --dump-config

输出会标注每个配置值的来源层。

6. cordis.patch.yml 热补丁

(1) 热补丁的用途

热补丁用于在不修改基础配置的前提下临时调整：

YAML

# cordis.patch.yml
plugins:
  debug-tools:
    $insert: ./dev-plugins/debug-tools
  llm:
    config:
      debug: true

(2) 启用热补丁

BASH

# 必须加 --patch 才会加载 patch 文件
pnpm dsh web --patch

(3) 生产环境热补丁

生产环境遇到紧急问题时，可以用 patch 快速修复：

YAML

# cordis.patch.prod.yml — 紧急禁用问题插件
plugins:
  problematic-plugin:
    enabled: false
  llm:
    config:
      maxRetries: 5  # 临时增加重试

(4) 热补丁的回滚

BASH

# 应用热补丁
cp cordis.patch.prod.yml cordis.patch.yml
pnpm dsh web --patch

# 回滚热补丁（删除 patch 文件）
rm cordis.patch.yml
pnpm dsh web

(5) 热补丁与 Git

TEXT 📖 仅展示

# .gitignore
cordis.patch.yml           # 忽略当前 patch
cordis.patch.prod.yml      # 忽略生产 patch
# cordis.patch.dev.yml    # 提交开发 patch（方便团队共享）

7. 插件冲突解决

(1) 常见冲突类型

冲突类型	表现	原因
同名工具	后注册的覆盖先注册的	两个插件注册了同名工具
同名服务	后注册的覆盖先注册的	两个 Provider 注册了同名服务
配置冲突	配置值不生效	优先级层搞错了
版本不兼容	运行时报错	插件版本与 DSH 核心不兼容

(2) 同名工具冲突

TEXT 📖 仅展示

Plugin A: register tool 'search'
Plugin B: register tool 'search'
→ 最终: Plugin B 的 search 生效

解决：

YAML

# 禁用其中一个
plugins:
  plugin-a:
    config:
      tools:
        disabled: ['search']

或使用 realm 隔离。

(3) 配置冲突排查

BASH

# 1. 查看最终配置
pnpm dsh web --patch --dump-config > dump.yml

# 2. 搜索冲突的配置项
grep "my-plugin" dump.yml

# 3. 检查是否被 patch 覆盖
diff cordis.yml cordis.patch.yml

(4) 版本兼容性

BASH

# 查看插件兼容性
dsh plugin check @dsh-plugin/database

# 输出
✅ @dsh-plugin/database@1.2.0 is compatible with dsh@0.5.0
⚠️ Requires: dsh >= 0.4.0

(5) 冲突解决决策树

graph TD
    CONFLICT{冲突类型?}
    CONFLICT -->|同名工具/服务| SCOPE{需要同时存在?}
    SCOPE -->|否| DISABLE[禁用其中一个]
    SCOPE -->|是| REALM[用 realm 隔离]
    CONFLICT -->|配置不生效| DUMP[--dump-config 排查]
    DUMP --> FIX[修正配置优先级]
    CONFLICT -->|版本不兼容| UPDATE[更新插件版本]
    UPDATE --> CHECK[检查兼容性]

❓ 常见问题

Q 安装插件后必须重启吗？

A 是的。插件安装后需要重启 DSH 才能加载。HMR 只能热更新已有插件的代码变更，不能加载新安装的插件。

Q 可以从私有 npm registry 安装吗？

A 可以。配置 .npmrc： text @dsh-plugin:registry=https://my-registry.com/

Q 多个 patch 文件可以叠加吗？

A 当前只支持一个 cordis.patch.yml。如果需要多个补丁，合并到一个文件中。

Q 如何查看所有已安装插件的版本？

A bash dsh plugin list # 或 pnpm list | grep dsh-plugin

Q 插件安装失败怎么办？

A 检查网络连接、npm registry 可达性、包名是否正确。查看 pnpm-error.log 获取详细错误信息。

Q 如何完全卸载一个插件？

A bash # 1. 从 cordis.yml 移除插件条目 # 2. 卸载 npm 包 pnpm remove @dsh-plugin/database # 3. 重启 DSH ---

📖 小节

四种安装方式：npm（标准）、GitHub（开发中）、tarball（私有/离线）、本地路径（开发）
配置五层优先级：Bundle → Profile → 项目 → Patch → CLI
--dump-config 是排查配置问题的核心工具
cordis.patch.yml 用于临时覆盖，--patch 启用
插件冲突通过禁用、realm 隔离、优先级调整解决
版本兼容性通过 dsh plugin check 检查

📝 作业

1. ⭐ 基础题：通过 npm 安装一个社区插件（如 @dsh-plugin/database），在 cordis.yml 中注册并配置，用 --dump-config 确认配置生效。

2. ⭐⭐ 进阶题：创建一个 cordis.patch.yml，在 patch 层覆盖项目的某个插件配置（如修改 LLM 的默认模型）。用 --dump-config 对比有无 patch 的配置差异。

3. ⭐⭐⭐ 挑战题：模拟一个插件冲突场景——安装两个注册同名工具的插件，观察后注册的覆盖先注册的。然后用 realm 隔离，让两个插件各自有独立的工具空间。

Web-Tutorial 技术团队

由多位开发者共同维护的编程教程平台。每篇教程由对应领域的开发者编写和审核，确保内容准确可靠。如发现任何问题，欢迎向我们反馈。

关于我们

DeepSeek Harness: 安装插件与配置加载顺序

1. 你将学到

2. npm 安装插件

(1) ▶ 示例 1

(2) 安装后注册

(3) 使用 dsh plugin add

(4) ▶ 示例 4

3. GitHub 仓库直接安装

(1) 安装方式

(2) 使用 dsh plugin add

(3) GitHub 安装的注意事项

(4) package.json 中的表示

4. tarball 安装

(1) 从 URL 安装

(2) 使用 npm pack 创建 tarball

(3) tarball 的适用场景

(4) 三种安装方式对比

5. 配置加载优先级

(1) 五层优先级

(2) ▶ 示例 2

(3) 同名插件处理

(4) 查看加载顺序

6. cordis.patch.yml 热补丁

(1) 热补丁的用途

(2) 启用热补丁

(3) 生产环境热补丁

(4) 热补丁的回滚

(5) 热补丁与 Git

7. 插件冲突解决

(1) 常见冲突类型

(2) 同名工具冲突

(3) 配置冲突排查

(4) 版本兼容性

(5) 冲突解决决策树

❓ 常见问题

📖 小节

📝 作业

🙏 帮我们做得更好