EvanAgent/BUGFIX.md

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/）

 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

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