# dsh-std · 插件标准 / 兼容协议

> 这个文件夹回答一个核心问题：**要让一个插件被官方 DSH 正常加载、并且能在版本演进中保持兼容，必须对齐哪些契约面？**

## 一句话结论

- 官方**没有**叫 "dsh-std" 的标准文档；真正的兼容协议由三件事构成：
  1. **Cordis 插件契约**（模块导出 `name`/`inject`/`Config`/`apply`，服务用 `Service` 子类）
  2. **`package.json` 的 `dsh` 字段**（`dsh.bundle.patch` / `dsh.profile` / `dsh.client`）
  3. **配置层**（`cordis.patch.yml` 的 `insert` 行 + `cordis.yml` + `!!js` + `disabled`）
- 社区有个同名项目 `Yan-Zero/dsh-std` 提出独立的静态 `dsh-plugin.json` manifest（Community v0.15），是**非官方**的跨 host 提案，作前瞻参考。

## 文档索引

| 文件 | 内容 | 优先级 |
|---|---|---|
| `01-官方插件兼容协议.md` | 官方 DeepSeek Harness 插件协议全貌：Cordis 模型、seam/扩展点、manifest 三层、兼容要点 | ★★★ 必读 |
| `02-manifest与配置层细节.md` | `cordis.patch.yml` / `cordis.yml` / `!!js` / `disabled` / 覆盖顺序 + 完整示例 | ★★★ 必读 |
| `03-社区dsh-std与跨框架协议.md` | 社区 `dsh-plugin.json` 提案 + MCP / A2A / OpenAI / LiteLLM / vLLM 提炼出的"通用兼容协议要素清单" | ★★ 前瞻 |
| `04-参考资料URL清单.md` | 全部可溯源 URL（官方仓库、文档页、规范） | ★★ 溯源 |

## 兼容性的"命门"清单（写插件前先背下来）

1. **字段名精确**：是 `dsh.bundle.patch`，不是 `bundlePatch`。
2. **`dsh.client` 插件 ≠ `dsh.profile.bundles`**：只声明 `dsh.client` 的客户端插件被塞进 `bundles` 会让 DSH 启动崩溃，这是最高优先级自愈动作（bundle ↔ cordis 重分类）。
3. **版本精确 pin + fail-closed**：官方处于 preview，破坏性变更频繁；依赖必须精确版本，不能用 `^`/`~` 或 GitHub URL。
4. **`arguments` 全程原始 JSON 字符串**：工具调用参数不做对象化，端到端保留字符串。
5. **配置里 `!!js` 不是 `!js`**：注入表达式用双感叹号。
6. **加载顺序由 `inject` 决定**，不是 `cordis.yml` 里的列表顺序。
7. **所有注册都是可逆 effect**：卸载时靠 disposer 自动回退（HMR 安全）。

细节展开见 `01-官方插件兼容协议.md` / `02-manifest与配置层细节.md`。