DeepSeek Harness: Installing Plugins and Configuration…
Last updated: 2026-08-31
From "writing plugins" to "using plugins" — this lesson focuses on practical plugin installation and configuration management. Four installation methods cover all scenarios, configuration loading priority ensures "local overrides global," and hot patches make emergency production changes safe and controllable.
💡 Tip: The most important step after installing a plugin is
--dump-config — confirm your plugin actually appears in the final configuration. Many "plugin not working" issues are just configuration priority mistakes.
📋 Prerequisites: Completed 12-local-plugin.md and 26-bundle-profile.md
1. What You'll Learn
- npm plugin installation
- GitHub repository direct installation
- tarball installation
- Configuration loading priority
- cordis.patch.yml hot patches
- Plugin conflict resolution
2. npm Plugin Installation
(1) ▶ Example 1
BASH
# Install latest version
pnpm add @dsh-plugin/database
# Install specific version
pnpm add @dsh-plugin/database@1.2.0
# Install as devDependency
pnpm add -D @dsh-plugin/debug-tools
(2) Post-Installation Registration
npm-installed plugins need to be registered in cordis.yml:
YAML
# cordis.yml
plugins:
'@dsh-plugin/database':
config:
connection: 'postgresql://localhost/mydb'
(3) Using dsh plugin add
DSH provides a more convenient install command:
BASH
# Install and auto-register
dsh plugin add @dsh-plugin/database
# Install with configuration
dsh plugin add @dsh-plugin/database --config.connection='postgresql://localhost/mydb'
# Install output
📦 Installing @dsh-plugin/database@1.2.0...
✅ Plugin installed and registered!
(4) ▶ Example 4
JSON
// package.json
{
"dependencies": {
"@dsh-plugin/database": "^1.2.0",
"@dsh-plugin/redis": "~2.1.0"
}
}
| Symbol | Meaning | Update Range |
|---|---|---|
^1.2.0 |
Compatible with 1.x | 1.2.0 ~ 1.9.9 |
~2.1.0 |
Compatible with 2.1.x | 2.1.0 ~ 2.1.9 |
1.2.0 |
Exact version | Only 1.2.0 |
3. GitHub Repository Direct Installation
(1) Installation Methods
BASH
# Install default branch
pnpm add github:alice/dsh-plugin-redis
# Install specific branch
pnpm add github:alice/dsh-plugin-redis#feature/cluster
# Install specific tag
pnpm add github:alice/dsh-plugin-redis#v2.1.0
# Install specific commit
pnpm add github:alice/dsh-plugin-redis#abc1234
(2) Using dsh plugin add
BASH
dsh plugin add github:alice/dsh-plugin-redis
(3) GitHub Installation Notes
| Note | Description |
|---|---|
| Requires Git | Git must be installed on the machine |
| Repo structure | Must be a valid Node.js package (has package.json) |
| Build step | Repo may need building first |
| Network | Requires GitHub access |
| Version locking | Prefer commit hash over branch name |
(4) package.json Representation
JSON
{
"dependencies": {
"@dsh-plugin/redis": "github:alice/dsh-plugin-redis#v2.1.0"
}
}
4. tarball Installation
(1) Install from URL
BASH
# Install from remote tarball
pnpm add https://example.com/dsh-plugin-custom-1.0.0.tgz
# Install from local tarball
pnpm add ./packages/dsh-plugin-custom-1.0.0.tgz
(2) Creating a tarball with npm pack
BASH
# In the plugin project
cd dsh-plugin-my-tool
npm pack
# Generates: dsh-plugin-my-tool-1.0.0.tgz
# In the DSH project
pnpm add ../dsh-plugin-my-tool/dsh-plugin-my-tool-1.0.0.tgz
(3) tarball Use Cases
| Scenario | Description |
|---|---|
| Private plugins | Not published to npm, distribute tgz directly |
| Offline install | No access to npm or GitHub |
| CI/CD | Install build artifacts directly |
| Pre-release testing | Install candidate versions for testing |
(4) Three Installation Methods Comparison
| Method | Command | Network Required | Version Management | Best For |
|---|---|---|---|---|
| npm | pnpm add @dsh-plugin/xxx |
npm registry | ✅ semver | Public plugins |
| GitHub | pnpm add github:user/repo |
GitHub | ⚠️ branch/tag | In-development plugins |
| tarball | pnpm add ./xxx.tgz |
None | ❌ manual | Private/offline |
5. Configuration Loading Priority
(1) Five Priority Layers
graph TB
L5["Layer 5: CLI parameters<br/>(highest priority)"]
L4["Layer 4: cordis.patch.yml"]
L3["Layer 3: Project cordis.yml"]
L2["Layer 2: Profile configuration"]
L1["Layer 1: Bundle defaults<br/>(lowest priority)"]
L5 --> L4 --> L3 --> L2 --> L1
(2) ▶ Example 2
TEXT
📖 Display only
Bundle defaults: plugins: [core, llm, tools], port: 5173
Profile (web): plugins: [+web-ui]
Project config: plugins: [+my-tool], port: 8080
Patch: plugins: [+debug-tools], debug: true
CLI: port: 3000
Final: plugins: [core, llm, tools, web-ui, my-tool, debug-tools]
port: 3000, debug: true
(3) Same-Name Plugin Handling
When multiple layers register the same plugin name, higher-priority layers override lower:
TEXT
📖 Display only
Bundle: llm → deepseek-adapter
Project config: llm → openai-adapter (overrides)
Patch: llm → custom-adapter (overrides again)
Final: llm → custom-adapter
(4) Viewing Load Order
BASH
pnpm dsh web --patch --dump-config
The output marks the source layer for each configuration value.
6. cordis.patch.yml Hot Patches
(1) Hot Patch Purpose
Hot patches temporarily adjust settings without modifying the base configuration:
YAML
# cordis.patch.yml
plugins:
debug-tools:
$insert: ./dev-plugins/debug-tools
llm:
config:
debug: true
(2) Enabling Hot Patches
BASH
# Must add --patch to load the patch file
pnpm dsh web --patch
(3) Production Hot Patches
When encountering urgent issues in production, use a patch for quick fixes:
YAML
# cordis.patch.prod.yml — Emergency disable problematic plugin
plugins:
problematic-plugin:
enabled: false
llm:
config:
maxRetries: 5 # Temporarily increase retries
(4) Hot Patch Rollback
BASH
# Apply hot patch
cp cordis.patch.prod.yml cordis.patch.yml
pnpm dsh web --patch
# Rollback hot patch (delete patch file)
rm cordis.patch.yml
pnpm dsh web
(5) Hot Patches and Git
TEXT
📖 Display only
# .gitignore
cordis.patch.yml # Ignore current patch
cordis.patch.prod.yml # Ignore production patch
# cordis.patch.dev.yml # Commit dev patch (for team sharing)
7. Plugin Conflict Resolution
(1) Common Conflict Types
| Conflict Type | Manifestation | Cause |
|---|---|---|
| Same-name tool | Later registration overrides earlier | Two plugins register same tool name |
| Same-name service | Later registration overrides earlier | Two Providers register same service name |
| Configuration conflict | Config value doesn't take effect | Priority layer is wrong |
| Version incompatibility | Runtime errors | Plugin version incompatible with DSH core |
(2) Same-Name Tool Conflict
TEXT
📖 Display only
Plugin A: register tool 'search'
Plugin B: register tool 'search'
→ Final: Plugin B's search takes effect
Solution:
YAML
# Disable one of them
plugins:
plugin-a:
config:
tools:
disabled: ['search']
Or use realm isolation.
(3) Configuration Conflict Troubleshooting
BASH
# 1. View final configuration
pnpm dsh web --patch --dump-config > dump.yml
# 2. Search for conflicting config items
grep "my-plugin" dump.yml
# 3. Check if overridden by patch
diff cordis.yml cordis.patch.yml
(4) Version Compatibility
BASH
# Check plugin compatibility
dsh plugin check @dsh-plugin/database
# Output
✅ @dsh-plugin/database@1.2.0 is compatible with dsh@0.5.0
⚠️ Requires: dsh >= 0.4.0
(5) Conflict Resolution Decision Tree
graph TD
CONFLICT{Conflict type?}
CONFLICT -->|Same-name tool/service| SCOPE{Need both?}
SCOPE -->|No| DISABLE[Disable one]
SCOPE -->|Yes| REALM[Isolate with realm]
CONFLICT -->|Config not taking effect| DUMP[--dump-config troubleshooting]
DUMP --> FIX[Fix configuration priority]
CONFLICT -->|Version incompatible| UPDATE[Update plugin version]
UPDATE --> CHECK[Check compatibility]
❓ FAQ
Q Must I restart after installing a plugin?
A Yes. Installed plugins require a DSH restart to load. HMR only hot-updates code changes in existing plugins; it can't load newly installed ones.
Q Can I install from a private npm registry?
A Yes. Configure
.npmrc: text @dsh-plugin:registry=https://my-registry.com/ Q Can multiple patch files be layered?
A Currently only one
cordis.patch.yml is supported. If you need multiple patches, merge them into one file.Q How to view all installed plugin versions?
A
bash dsh plugin list # Or pnpm list | grep dsh-plugin Q What if plugin installation fails?
A Check network connection, npm registry accessibility, and package name correctness. Check
pnpm-error.log for detailed error information.Q How to completely uninstall a plugin?
A
bash # 1. Remove plugin entry from cordis.yml # 2. Uninstall npm package pnpm remove @dsh-plugin/database # 3. Restart DSH 📖 Summary
- Four installation methods: npm (standard), GitHub (in-development), tarball (private/offline), local path (development)
- Configuration five-layer priority: Bundle → Profile → Project → Patch → CLI
--dump-configis the core tool for troubleshooting configuration issues- cordis.patch.yml for temporary overrides;
--patchenables it - Plugin conflicts resolved through disabling, realm isolation, or priority adjustment
- Version compatibility checked via
dsh plugin check
📝 Exercises
1. ⭐ Basic： Install a community plugin via npm (e.g., @dsh-plugin/database), register and configure it in cordis.yml, and use --dump-config to confirm the configuration takes effect.
2. ⭐⭐ Intermediate： Create a cordis.patch.yml that overrides a plugin configuration at the patch layer (e.g., change the LLM's default model). Use --dump-config to compare configuration differences with and without the patch.
3. ⭐⭐⭐ Challenge： Simulate a plugin conflict scenario — install two plugins that register same-name tools, observe the later one overriding the earlier one. Then use realm isolation so both plugins have independent tool spaces.
