EvanAgent/PLUGIN-COMPAT.md

插件兼容性检查清单

安装任何 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 模板

<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. 确认恢复正常后，排查插件兼容性问题