|
|
@@ -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 修复**：记录到此文件，更新预防措施清单
|
