pi2dsh 装完没反应？按这个顺序查七步
pi2dsh 是给 DSH 加一层「Pi 插件兼容」的引擎：装上之后，Pi 生态里的 npm 包可以原封不动地在 DSH 上跑。它的失败模式很有特点——大多不是报错，而是什么都没有发生。这篇给一条固定的排查顺序，外加五个已经写在文档里的真实坑。想先看同类插件清单，见 完整插件清单与汉化避坑指南。
七步排查顺序
- 重启了吗—— 插件在
dsh启动时挂载，不重启不生效。 - 装对包了吗—— 引擎是
pi2dsh，适配器是pi-mcp-adapter，两个都要装。 - profile 有界面载体吗—— 自定义 profile 必须在
dsh.profile.bundles里有 surface。 - pnpm 是否拦了构建脚本——
ERR_PNPM_IGNORED_BUILDS。 - 版本对得上吗—— pi2dsh 0.27.0 对应 DSH 0.2.1-rc.2，只有三组组合被声明。
- 是不是装到了旧版本——
minimumReleaseAge会让刚发布的版本被跳过。 - 能力是否本来就没映射—— 无法映射的能力会被明确报出，并把插件标为不可用。
前六步是环境问题，第七步不是故障。
坑一 · 装完不重启就什么都没有
现象。dsh plugin --profile web add pi2dsh返回成功，list里也能看到，但界面上没有任何变化，工具也没多出来。
原因。插件在启动时挂载。add 只是把包写进 profile，不触发重新加载。
解决。重启dsh。这一步在 README 里是加粗写的，但仍然是最高频的「假故障」。
坑二 · pnpm 拦下依赖构建脚本
现象。装到一半失败，报ERR_PNPM_IGNORED_BUILDS。
原因。pnpm 默认阻止依赖执行构建脚本。这是一个安全默认值，不是 bug。
解决。到$DSH_HOME/profiles/web里跑pnpm approve-builds，或在该 profile 的pnpm-workspace.yaml的allowBuilds下把列出的包设为true，然后重跑 add。README 特别说明「这是你要做的决定，桥不会替你绕过去」——换句话说，别指望它偷偷加个--ignore-scripts=false。
坑三 · 刚发版却装到旧版本
现象。官方刚发 0.27.0，你add pi2dsh之后版本号还是旧的。
原因。pnpm 的minimumReleaseAge会跳过刚发布不久的版本，这是一种供应链保护。
解决。写死版本：dsh plugin add pi2dsh@0.27.0。同理，升级插件用dsh plugin add <pkg>@latest（引擎不动），升级引擎用dsh plugin add pi2dsh@latest（插件不动）。
坑四 · 宿主版本不在兼容表里
现象。换到一条新的 DSH RC 线之后，Pi 包挂不上，或行为异常。
原因。兼容性是枚举的，不是范围：
| pi2dsh | DSH 宿主 |
|---|---|
| 0.27.0 | 0.2.1-rc.2 |
| 0.26.0 | 0.2.0-rc.2 |
| 0.25.2 | 0.1.5-rc.2 |
README 明确写了「未测过的宿主版本不包含在兼容声明里」。也就是说，其它版本不是「一定不行」，而是「没人担保」。
解决。对齐表格。不要用allow-version强行绕过——README 对某个具体组合专门写了「不要用 allow-version 绕过」，因为绕过之后挂载的是已移除的宿主不变量。
坑五 · 终端类插件与当前宿主不匹配
现象。在 0.2.1-rc.2 上装@xmoon76/dsh-pi-tui@0.5.1，终端起不来或功能缺失。
原因。这个终端仍挂载已移除的宿主不变量组件，并使用了已移除的cwdprompt 变量。README 直接把它列为「不受支持的组合」。
解决。换@deepseek-harness-tui/dsh-tui@0.16.1那条路径，或退回 pi2dsh 的 Web 路径。注意这是两件不同的事：pi2dsh 的 Web 支持与 dsh-TUI 路径各自独立，别把前者的成功当成后者也可用。
第七步为什么不是故障
如果前六步都过了、某些能力仍然不可用，多半命中了「无法映射」。README 的原则是不伪造成功：某个能力没有安全映射时，它会每个插件报一次，用平实语言说明；需要该能力才能启动的插件，会被标为不可用并给出移除提示，而不是半可用。
这比「静默返回一个编造的结果」好得多，但你得知道它是设计，不是残留 bug。
一个最小的验证动作
装完并用重启之后，做一次「有没有真的挂上」的确认：在会话里看 Pi 包贡献的命令是否出现在可选项里。最省事的验证是装pi-mcp-adapter然后跑/pi-mcp——它会打开全屏服务器管理器，底部有启用/停用、重连、OAuth 登录的按键说明。
能看到这个界面，说明引擎、适配器、profile 三层都通了；看不到，回到七步的第一步。
总结
pi2dsh 的排查几乎不需要读日志：重启、包名、profile 载体、pnpm 策略、版本表、装到的版本、能力映射，七步覆盖了绝大多数情况。更多 DSH 插件的中文说明见 完整插件清单与汉化避坑指南。
适合与不适合
适合：刚装完 pi2dsh 却发现没效果的人；在多个 DSH RC 版本间切换的人；要判断「这是故障还是设计」的人。
不适合：不愿意重启进程的人；想在未声明的宿主版本上强行跑生产的人；期待插件自动绕过 pnpm 安全策略的人。
标签：pi2dsh、DeepSeek Harness、排错、pnpm、兼容性
本文由 DeepSeek Harness Hub 自动整理，数据来源于插件详情页。
