# adapter · 适配器规范

> 这个文件夹回答一个问题：**怎么把一个"外部能力"（模型、工具、后端、插件包组合）接进 DSH，并且保持兼容？**

## "adapter" 在 dsh 语境下的两个含义

| 含义 | 是什么 | 规范位置 |
|---|---|---|
| ① 官方 **LLM adapter seam** | 继承 `LlmAdapter`、实现 `stream()`，经 `ctx.llm.registerAdapter(providers, adapter)` 注册的**模型适配器** | `01-LLM-Adapter协议.md` |
| ② **组合层 adapter** | 你 hotplug-hub 里把 pack/bundle/组合描述**映射到真实 DSH 字段**（`dsh.bundle.patch` / `cordis.patch.yml` / `dsh.profile.bundles`）的那一层 | 本文件 §3 |

## 目录索引

| 文件 | 内容 | 优先级 |
|---|---|---|
| `01-LLM-Adapter协议.md` | 官方 LLM adapter seam 完整契约：`LlmAdapter`/`StreamChunk`/`registerAdapter`/流式与错误路径 | ★★★ 必读 |
| `02-适配器目录结构与编写清单.md` | 官方参考目录布局（`packages/llm/llm-deepseek`）+ 写 adapter/插件的检查清单 | ★★★ 必读 |
| `03-跨框架adapter模式.md` | GoF Adapter 在 AI harness 的落地 + MCP/A2A/OpenAI/LiteLLM/vLLM 的 adapter 形态 | ★★ 参考 |

## 官方参考适配器

- `@deepseek-ai/dsh-llm-deepseek`：直连 DeepSeek 官方 API（路由名 `deepseek-official`，默认模型 `deepseek-v4-flash`，OpenAI 兼容 fetch + SSE）。
- `@deepseek-ai/dsh-llm-pi-ai`：多 provider 库封装（路由名 `deepseek`）。
- 源码位置：`packages/llm/llm-deepseek/`、`packages/llm/llm-pi-ai/`（主仓库内）。

## 组合层 adapter 的字段映射（对应 hotplug-hub）

| hotplug-hub 侧概念 | 映射到真实 DSH 字段 |
|---|---|
| bundle / 插件包 | `package.json` 的 `dsh.bundle.patch` → `cordis.patch.yml` 的 `insert` 行 |
| profile 里的 bundle 集合 | `dsh.profile.bundles` |
| 客户端插件 | `dsh.client` + 导出 `./client`（**不能进 `dsh.profile.bundles`**） |
| 组合载体 hotpack v1 | 复用为组合描述，叠加 `resolvedAssembly` 索引（apiLevel/provides/requires/conflicts 只存索引，**不写回 package.json**） |
| 临时工作区 sandbox | 启动时同步为 `~/.dsh/profiles/<id>` 再以 `DSH_PROFILE=<id>` 拉起 |

> 你开发文档里已修的正确结论：`bundlePatch` → `dsh.bundle.patch`；`apiLevel`/`provides`/`requires`/`conflicts` 不写回插件 `package.json`；`bundle ↔ cordis` 重分类是最高优先级自愈动作。