# DeepSeek Harness（DSH）插件兼容协议 · 研究汇总

> 面向 dsh 插件编写的调研成果索引。核心结论：**dsh = 官方 `deepseek-ai/deepseek-harness`（"Everything is a Plugin"，一切皆插件）**，跑在 Cordis 插件框架之上。本目录把研究结论拆成两个文件夹：**标准/协议侧（`dsh-std/`）** 与 **适配器侧（`adapter/`）**。

## TLDR（先看这个）

- 官方仓库：<https://github.com/deepseek-ai/deepseek-harness>（MIT，TypeScript，**developer preview**，破坏性变更随时可能发生，务必精确 pin 版本）。
- 官网 / 文档：<https://deepseek.com/harness> · <https://deepseek-harness.github.io/deepseek-harness/>
- npm 包：`@deepseek-ai/dsh`（版本在快速滚动，写作时约 `0.1.x-rc`），`npx @deepseek-ai/dsh web` 启动 Web UI（默认 `http://127.0.0.1:3080`）。
- **插件协议 = Cordis 插件模型 + `package.json` 的 `dsh` 字段 + `cordis.patch.yml` / `cordis.yml` 配置层**。兼容性的"命门"是几个精确字段名与层级顺序，写错就崩（详见 [`dsh-std/01-官方插件兼容协议.md`](./dsh-std/01-官方插件兼容协议.md)、[`dsh-std/02-manifest与配置层细节.md`](./dsh-std/02-manifest与配置层细节.md)）。
- **"adapter" 有两个含义**：
  1. 官方 **LLM 适配器 seam**：继承 `LlmAdapter`、实现 `stream()`、通过 `ctx.llm.registerAdapter(providers, adapter)` 注册（见 [`adapter/01-LLM-Adapter协议.md`](./adapter/01-LLM-Adapter协议.md)）。
  2. dsh-hotplug-hub 里的**"组合层 adapter"**：把 pack/bundle 组合映射到真实 DSH 字段（见 [`adapter/README.md`](./adapter/README.md) 的映射表）。
- 社区另有一份**非官方**的 `dsh-plugin.json` 静态 manifest 提案（也叫 "dsh-std"），只作跨 host 前瞻参考，**不要当官方标准**（见 [`dsh-std/03-社区dsh-std与跨框架协议.md`](./dsh-std/03-社区dsh-std与跨框架协议.md)）。

## 目录

| 路径 | 内容 |
|---|---|
| [`dsh-std/`](./dsh-std/README.md) | 插件标准/兼容协议：官方插件契约、manifest 与配置层、社区 dsh-std 前瞻、通用兼容协议要素清单、参考资料 URL |
| [`adapter/`](./adapter/README.md) | 适配器规范：LLM adapter seam、目录结构与编写清单、跨框架 adapter 模式 |

## 与 cardian 及 dsh-hotplug-hub 的关系

本仓库主体是 **cardian** —— 一个遵循上述官方兼容协议的 DSH 知识中心插件（RepoWiki / 知识卡片 / 记忆，全部落地本地 Obsidian 仓库）。它的 `package.json` 使用 `dsh.bundle.patch` + `cordis.patch.yml` 接入宿主，其客户端的半侧接入契约详见 [`docs/dsh-integration.md`](../dsh-integration.md)。

配套项目 [**dsh-hotplug-hub**](https://github.com/myYangyunfan/dsh-hotplug-hub) 是独立的插件拼装启动器（读组合 → 拼 profile → 预检 → 拉起官方 DSH → 捕获日志 → 自愈）。它正确使用了官方兼容协议的关键字段：

- `dsh.bundle.patch`（**不是** `bundlePatch`）
- `cordis.patch.yml` 的 `insert` 行（`id` / `name` / `config`）
- `dsh.profile.bundles` vs `dsh.client`（客户端插件误入 `bundles` 会导致 DSH 启动崩溃——即 "bundle ↔ cordis 重分类"）
- profile 落点 `~/.dsh/profiles/<id>` + `DSH_PROFILE` 拉起
- 精确 npm 版本 + fail-closed

这些散点在此补全成一份可查的协议规范，并补上官方 LLM adapter seam 的完整契约，方便直接照它写插件/适配器。