6. FAQ

1. @deepseek-ai/dsh-tools 的 latest 是过期的。 锁 next tag 版本（^0.1.0-rc.6）。
2. Node 太旧。 ^22.19 || >=24；否则只是 EBADENGINE 警告（无害）。
3. dsh-* 版本线混用。 全部保持同一 0.1.0-rc.x。
4. 运行时 import @deepseek-ai/cordis。 它是 peerDependency——只用 import type。
5. 没写 "type": "module"。 插件必须是纯 ESM。
6. 丢弃 disposer。 ctx.tools.register/ctx.on 自动 dispose；自己的定时器/连接用 ctx.effect(() => { ...; return cleanup }) 包起来。
7. dsh plugin add <dir> 的相对路径锚定。 在插件的父目录执行。
8. cordis.patch.yml 的 name 是包名，不是相对路径。（dsh-spike，不是 ./dist/tool-time.js。）
9. 以为文件顺序 = 加载顺序。 加载顺序由 inject 服务依赖决定。
10. tools/change 是未过滤的注册表主体通知。 宿主级监听器会收到所有工具注册/反注册—— boot 时刷几十条属正常。
11. npm/pnpm ≥10 拦截原生构建脚本（koffi、node-pty）。 首次 npx @deepseek-ai/dsh（或安装插件）可能卡住：包管理器扣住了 DSH 依赖的原生包 install 脚本。批准即可——npm：npm approve-scripts koffi node-pty（或 npm approve-scripts --all；npm 10 的命令名是 npm approve-builds）；pnpm：pnpm approve-builds。npm/pnpm ≥10 默认先询问再跑 install 脚本（供应链加固）——这是预期行为，不是报错。
12. 桌面壳（Electron / 裸 WKWebView）里插件外链点击无反应。 壳没实现 openExternal 代理时，所有 target=_blank / window.open 点击会被静默吞掉。插件侧 plugin-manager 0.8.1+ 已兜底「复制链接 + toast」；真正治本是宿主侧——Swift 两行：实现 WKUIDelegate.createWebViewWith → NSWorkspace.shared.open(url)，或在 decidePolicyFor 里对外链 host 取消导航 + 系统浏览器打开。
13. Cordis patch 配置写了不生效。 配置覆盖必须是顶层 { id, config } 行——包在 - set: 列表里会被静默跳过，于是「配置写了没用」。实测踩坑：notify v0.2 就是这个坑。
14. Web UI token 鉴权门（alpha）。 Web UI 首屏改回 401，boot 日志打印 ?token= URL。playwright/curl 自动化要先 token 换 cookie——curl -c jar -b jar -L "http://127.0.0.1:3080/?token=$TOKEN"——之后每次请求带 jar。插件自定义路由不被门控。

---

← Prev: 分发与发布 · Contents · Next: 皮肤与个性化 →