# 插件兼容性检查清单

> 安装任何 DSH 插件前，按此清单逐项确认。避免出现 "Failed to load plugins" 影响正常工作。

---

## 安装前检查

| # | 检查项 | 方法 |
|---|---|---|
| 1 | 确认当前 DSH 版本 | `dsh -V` |
| 2 | 确认插件最新版本 | `npm view <package> version` |
| 3 | 确认插件 peerDependencies 与 DSH 版本兼容 | `npm view <package> peerDependencies` |
| 4 | 确认插件最近更新时间（活跃度） | `npm view <package> time` |
| 5 | 确认插件是否与已装插件有功能重叠 | 对照已装插件清单 |

## 安装后验证

| # | 检查项 | 通过标准 |
|---|---|---|
| 1 | 重启 DSH Web 服务 | `dsh web` 无报错启动 |
| 2 | 检查 Web GUI 无 "Failed to load plugins" | 页面加载后无红色错误横幅 |
| 3 | 检查浏览器 Console 无插件相关错误 | DevTools → Console，过滤 `error` |
| 4 | 新插件功能可用 | 按插件文档触发功能，确认正常 |
| 5 | 已有插件未受影响 | 确认品牌替换、语音等现有功能正常 |

## Slot 注册检查（写给插件开发者）

DSH slot 分两种类型，注册要求不同：

| Slot 类型 | 特点 | register 要求 |
|---|---|---|
| **single slot** | 同一 key 只能有一个注册项 | `{ name, priority }` |
| **list slot** | 同一 key 可有多个注册项并列 | `{ name, id, order, label }` —— **必须带 `id`** |

常见 list slot：
- `conversation.input.left`（输入栏左侧按钮区）
- `shell.overlay`（全局浮层）

## 第三方 API 端点兼容性检查

| # | 检查项 | 方法 |
|---|---|---|
| 1 | 确认端点支持的 roles | 查阅 API 文档，确认是否支持 `developer` |
| 2 | 确认 token 限制字段名 | `max_tokens` vs `max_completion_tokens` |
| 3 | 确认是否支持 reasoning_effort | 查阅 API 文档 |
| 4 | 在 settings.yaml 声明 compat 差异 | 参照阿里云百炼的配置模板 |

### settings.yaml compat 模板

```yaml
<provider-name>:
  apiKeyEnv: <ENV_VAR>
  api: openai-completions
  baseURL: <endpoint-url>
  compat:
    supportsDeveloperRole: false    # 如果不支持 developer 角色
    maxTokensField: max_tokens      # 如果端点用 max_tokens 而非 max_completion_tokens
    # supportsReasoningEffort: true # 如果支持推理强度参数
  models:
    - id: <model-id>
      ...
```

## 已装插件清单

| 插件 | 版本 | 用途 | 安装日期 |
|---|---|---|---|
| dsh-brand-client | 0.1.6 | DoTouchAI 品牌替换 + 视频抽帧 | 2026-08-24 |
| dsh-voice-client | - | 语音输入客户端 | 2026-08-23 |
| dsh-voice-server | - | 语音识别服务端（sherpa-onnx） | 2026-08-23 |
| mcp-harmonyos | - | HarmonyOS 设备 MCP 工具链 | 2026-08-23 |
| @nanmicoder/dsh-agent-teams | 0.1.13 | 多 Agent 团队协作 | 2026-08-26 |

## 回滚预案

如果新插件导致 DSH 无法正常启动：
1. 编辑 `~/.dsh/profiles/web/cordis.patch.yml`，注释掉或删除问题插件的 `insert` 条目
2. 重启 `dsh web`
3. 确认恢复正常后，排查插件兼容性问题