DeepSeek Harness: 加载本地插件
最后更新：2026-08-31
理解插件加载机制，是从"写了一个插件"到"高效开发插件"的关键跨越。cordis.yml 是 DSH 的配置中枢，而 --patch overlay 机制让你在不修改默认配置的前提下灵活叠加本地插件。
💡 提示：
--patch 机制的核心思想是"叠加而非覆盖"——默认配置保持不变，你的本地修改作为 overlay 层叠加上去。这让开发调试和正式部署可以共享同一份基础配置。
📋 前置知识：已完成 11-first-plugin.md，能创建最小插件
1. 你将学到
- cordis.yml 配置文件详解
$insert与$replace操作- 绝对路径 vs 相对路径选择
--patchoverlay 机制原理--dump-config查看最终配置- 本地开发调试工作流
2. cordis.yml 配置详解
(1) 配置文件位置
cordis.yml 是 DSH 的核心配置文件，位于项目根目录：
TEXT
📖 仅展示
my-dsh-project/
├── cordis.yml ← 主配置
├── cordis.patch.yml ← 补丁配置（可选）
├── package.json
└── src/
(2) ▶ 示例 2
YAML
# cordis.yml 基本结构
plugins:
plugin-name:
# 插件配置项
enabled: true
config:
key: value
# 全局配置
hostname: localhost
port: 5173
(3) 插件条目格式
每个插件条目包含三部分信息：
| 字段 | 说明 | 示例 |
|---|---|---|
| 插件名 | key 即插件标识 | my-plugin: |
| 路径 | 从哪里加载 | $insert 或 npm 包名 |
| 配置 | 传给插件的参数 | config: 下的字段 |
YAML
plugins:
# npm 包插件
@dsh-plugin/database:
config:
connection: "postgresql://localhost/mydb"
# 本地插件
my-local-plugin:
$insert: /home/alice/dev/my-plugin
config:
debug: true
3. $insert 与 $replace 操作
(1) $insert：追加插件
$insert 在现有插件列表中追加一个插件：
YAML
plugins:
my-tool:
$insert: /home/alice/dev/dsh-plugin-my-tool
效果等价于：
TEXT
📖 仅展示
默认插件列表: [core, llm, tools, shell, ...]
insert 后: [core, llm, tools, shell, ..., my-tool]
(2) $replace：替换插件
$replace 用一个新实现替换已有插件：
YAML
plugins:
# 用自定义 LLM 适配器替换默认的
llm:
$replace: /home/alice/dev/custom-llm-adapter
效果：
TEXT
📖 仅展示
默认: llm → @deepseek-ai/dsh-plugin-llm
替换: llm → /home/alice/dev/custom-llm-adapter
⚠️ $replace 必须指定已存在的插件名，不能替换不存在的条目。
(3) ▶ 示例 3
YAML
plugins:
# 追加本地工具
my-tool:
$insert: /home/alice/dev/dsh-plugin-my-tool
# 替换默认 shell 为安全版本
shell:
$replace: /home/alice/dev/dsh-plugin-safe-shell
# 追加另一个本地插件
my-monitor:
$insert: /home/alice/dev/dsh-plugin-monitor
(4) 操作优先级
当同一插件同时有 $insert 和 $replace 时：
TEXT
📖 仅展示
优先级: $replace > $insert
如果 $replace 目标不存在，则退化为 $insert 行为。
4. 路径策略
(1) ▶ 示例 1
YAML
plugins:
my-plugin:
$insert: /home/alice/dev/my-plugin
优点：
- 不受工作目录影响
- 调试时路径明确
- 跨项目复用配置
缺点：
- 硬编码用户路径，不可移植
- 团队协作时各人路径不同
(2) 相对路径
YAML
plugins:
my-plugin:
$insert: ./plugins/my-plugin
相对路径基于 cordis.yml 所在目录解析。
优点：
- 可移植，适合团队协作
- 插件可随项目一起版本管理
缺点：
- 依赖启动时的工作目录
- 嵌套目录时路径计算复杂
(3) 路径选择建议
| 场景 | 推荐 | 原因 |
|---|---|---|
| 个人开发 | 绝对路径 | 路径明确，无歧义 |
| 团队协作 | 相对路径 | 可移植，各人环境一致 |
| CI/CD | 相对路径 | 构建环境路径不固定 |
| 临时调试 | 绝对路径 | 快速定位，不怕路径问题 |
5. --patch overlay 机制
(1) 配置层叠模型
DSH 的配置由多层叠加而成：
graph TB
BASE[基础层<br/>默认配置] --> BUNDLE[Bundle 层<br/>dsh-base / dsh-web-app]
BUNDLE --> PROFILE[Profile 层<br/>web / headless]
PROFILE --> PATCH[Patch 层<br/>cordis.yml + --patch]
PATCH --> FINAL[最终配置]
每一层覆盖上一层的同名配置项，类似 CSS 的层叠优先级。
(2) --patch 参数
BASH
# 启动时应用 patch 层
pnpm dsh web --patch
不加 --patch 时，DSH 只读取默认配置，忽略 cordis.yml 中的 $insert/$replace。加 --patch 后，cordis.yml 中的覆盖操作才会生效。
(3) cordis.patch.yml
除了主配置，还可以使用 cordis.patch.yml 作为额外的补丁层：
YAML
# cordis.patch.yml — 仅在开发环境使用
plugins:
debug-tools:
$insert: ./dev-plugins/debug-tools
--patch 同时读取 cordis.yml 和 cordis.patch.yml，后者优先级更高。
(4) overlay 合并规则
TEXT
📖 仅展示
基础配置: { a: 1, b: 2, c: 3 }
Patch 层: { b: 20, d: 4 }
─────────────────────────────
最终配置: { a: 1, b: 20, c: 3, d: 4 }
- 同名字段：Patch 层覆盖基础层
- 新增字段：直接追加
- 不涉及的字段：保持不变
6. --dump-config 查看最终配置
(1) 基本用法
BASH
pnpm dsh web --patch --dump-config
输出最终合并后的完整配置：
YAML
# === Merged Configuration ===
hostname: localhost
port: 5173
plugins:
core:
enabled: true
llm:
enabled: true
config:
provider: deepseek
tools:
enabled: true
my-tool: # ← 你 insert 的
$insert: /home/alice/dev/my-tool
config:
debug: true
debug-tools: # ← patch.yml 追加的
$insert: ./dev-plugins/debug-tools
(2) 调试配置问题
当插件没有按预期加载时，用 --dump-config 排查：
BASH
# 排查步骤
pnpm dsh web --patch --dump-config > config-dump.yml
# 检查你的插件是否出现在最终配置中
# 检查 $insert 路径是否正确
(3) 只看特定插件
BASH
# 过滤查看特定插件配置
pnpm dsh web --patch --dump-config | grep -A 10 "my-plugin"
7. 本地开发调试工作流
(1) 标准开发循环
graph LR
CODE[编写插件代码] --> REG[注册到 cordis.yml]
REG --> START[启动 dsh web --patch]
START --> TEST[测试插件行为]
TEST --> BUG{有 Bug？}
BUG -->|是| CODE
BUG -->|否| DONE[完成]
(2) 快速迭代技巧
Alice 在开发一个工具插件时的典型工作流：
BASH
# 1. 一次性配置 cordis.yml
cat > cordis.yml << 'EOF'
plugins:
my-tool:
$insert: /home/alice/dev/dsh-plugin-my-tool
EOF
# 2. 开发循环
# 改代码 → 重启 → 测试
pnpm dsh web --patch
# 测试完毕 Ctrl+C 停止
# 3. 验证配置
pnpm dsh web --patch --dump-config | grep my-tool
(3) 多插件并行开发
Bob 同时开发两个插件：
YAML
# cordis.yml
plugins:
tool-a:
$insert: /home/bob/dev/dsh-plugin-a
tool-b:
$insert: /home/bob/dev/dsh-plugin-b
分别在不同终端开发，重启 DSH 时两个插件同时加载。
(4) 临时禁用插件
不需要卸载，直接在配置中注释：
YAML
plugins:
my-tool:
$insert: /home/alice/dev/my-tool
# experimental-tool: # 暂时禁用
# $insert: /home/alice/dev/exp-tool
❓ 常见问题
Q cordis.yml 和 dsh.config.yaml 有什么区别？
A
cordis.yml 是 Cordis 框架的配置，管插件加载和覆盖。dsh.config.yaml 是 DSH 应用的配置，管模式、审批策略等。两者互补，不冲突。Q $insert 的路径指向一个没有 package.json 的目录会怎样？
A DSH 会尝试将目录当作插件加载，如果缺少必要字段（如 main 入口），会报错跳过。建议始终确保本地插件目录有
package.json。Q 不用 --patch 启动，cordis.yml 会被读取吗？
A 不会。不加
--patch 时 DSH 使用默认配置，忽略 cordis.yml。这是有意设计——防止开发配置意外影响生产环境。Q cordis.patch.yml 可以放在其他位置吗？
A 当前只支持项目根目录下的
cordis.patch.yml。如果需要多套补丁，可以手动切换文件内容。Q 配置修改后需要重启吗？
📖 小节
- cordis.yml 是 DSH 的插件配置中枢，包含插件路径和配置项
$insert追加插件，$replace替换已有插件- 绝对路径适合个人开发，相对路径适合团队协作
--patch启用 overlay 机制，将 cordis.yml 叠加到默认配置上--dump-config查看最终合并配置，是排查加载问题的利器- 开发循环：改代码 → 注册 cordis.yml →
dsh web --patch→ 测试
📝 作业
1. ⭐ 基础题：在 cordis.yml 中用 $insert 注册上一课创建的 hello-world 插件，用 --dump-config 确认它出现在最终配置中。
2. ⭐⭐ 进阶题：分别用绝对路径和相对路径两种方式注册同一个插件，用 --dump-config 对比两种配置的输出差异。
3. ⭐⭐⭐ 挑战题：创建两个本地插件 A 和 B，在 cordis.yml 中同时 $insert 两者。尝试用 $replace 将 DSH 内置的某个工具插件替换为你的自定义版本，用 --dump-config 验证替换结果。
