docs: 记录 #1 dsh-brand-client slot 缺 id 和 #2 阿里云百炼 developer 角色 bug 修复，添加插件兼容性检查清单

BUGFIX.md

@@ -0,0 +1,92 @@
+# Bug 修复记录
+
+> 记录每次 bug 的根因、修复和预防措施。新版本开发前必读，避免重复踩坑。
+
+---
+
+## #1 — dsh-brand-client 插件加载失败：list slot 缺 options.id
+
+**日期**：2026-08-26
+**影响**：DSH Web GUI 启动后显示 "Failed to load plugins"，dsh-brand-client 无法加载，DoTouchAI 品牌替换失效
+**触发条件**：新版 DSH（0.1.1-rc.2）将 `conversation.input.left` 定为 **list slot**，注册时强制要求 `options.id` 字段
+
+### 根因
+
+DSH 的 slot 系统分两种：
+- **single slot**（单槽）：同一 key 只能有一个注册项，`register({ name, priority })` 即可
+- **list slot**（列表槽）：同一 key 可有多个注册项并列显示，**必须带 `options.id`** 做身份标识
+
+dsh-brand-client 往 `conversation.input.left`（输入栏左侧）注册「视频抽帧」按钮时，`slots.register()` 的 options 里**没写 `id`**。新版 DSH 把该槽定为 list slot 后，缺 `id` 的注册被拒绝，整插件加载失败。
+
+### 修复
+
+文件：`dsh-brand-client/lib/client.js`（源码在 `/Users/eastudio/Documents/DSWorkSpace/dsh-brand-client/`）
+
+```diff
+ ctx.slots.inject("conversation.input.left", function* () {
+     yield ctx.slots.register({
+         name: "conversation.input.left",
++        id: "dsh-brand-video-frames",
++        order: 110,
+         label: "识图/视频抽帧"
+     }, VideoFrameButton);
+ });
+```
+
+- `id`: 插件注册的唯一标识，list slot 必需
+- `order: 110`: 排在语音按钮（order 100）后面
+
+### 预防
+
+1. **安装任何新插件前**，确认 DSH 版本兼容性（见 `PLUGIN-COMPAT.md`）
+2. **插件注册到 slot 时**，检查该 slot 是 single 还是 list——list slot 必须带 `id`
+3. **DSH 升级后**，先检查所有已装插件的加载日志，确认无报错再继续工作
+
+---
+
+## #2 — 阿里云百炼 API 报 400：developer 角色不被兼容接口识别
+
+**日期**：2026-08-26
+**影响**：提高推理强度（reasoningEffort: high）后，阿里云百炼兼容接口返回 400 错误
+**触发条件**：DSH 默认 provider 为阿里云百炼 compatible-mode 端点 + 开启推理强度
+
+### 根因
+
+DSH 的推理强度开启后，系统提示改用 `developer` 角色（OpenAI 标准）。但阿里云百炼兼容接口只接受：
+- `system`
+- `assistant`
+- `user`
+- `tool`
+- `function`
+
+DSH 无法识别百炼 URL 为阿里云端点，按 OpenAI 标准组包 → `developer` 角色 → 400。
+
+### 修复
+
+文件：`~/.dsh/settings.yaml`
+
+```yaml
+alibaba:
+  apiKeyEnv: ALIBABA_API_KEY
+  api: openai-completions
+  baseURL: https://llm-iwrb6yiaee24divf.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
+  compat:
+    supportsDeveloperRole: false   # 强制用 system 角色
+    maxTokensField: max_tokens     # 用 max_tokens 而非 max_completion_tokens
+```
+
+### 预防
+
+1. **添加新的第三方 OpenAI 兼容端点时**，先确认其 API 兼容性矩阵（角色支持、token 字段名、推理参数）
+2. **在 settings.yaml 的 compat 段**明确声明该端点的兼容性差异
+3. **DSH 升级后首次使用**，先用低推理强度发一条测试消息，确认 200 再调高
+
+---
+
+## 版本开发纪律
+
+1. **新功能开发前**：先确认当前 DSH 版本 + 所有插件加载正常（检查 Web GUI 无 "Failed to load plugins"）
+2. **DSH 升级后**：立即做冒烟测试（发一条消息 + 检查插件加载日志）
+3. **新插件安装后**：重启 DSH → 检查加载日志 → 验证功能（见 `PLUGIN-COMPAT.md`）
+4. **新增第三方 API 端点**：先在 settings.yaml 声明 compat 差异，再配置模型
+5. **所有 bug 修复**：记录到此文件，更新预防措施清单

PLUGIN-COMPAT.md

@@ -0,0 +1,80 @@
+# 插件兼容性检查清单
+
+> 安装任何 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. 确认恢复正常后，排查插件兼容性问题