DSH 插件安装失败：从「git 未安装」到「网络线路问题」的完整排障复盘

一句话摘要：装一个 GitHub 上的 DSH 插件，连续踩了 git 缺失、npm 同名撞车、pnpm store 告警、git 证书不受信、网络线路间歇性断开 五个坑 —— 本文把每一步的前提、交付物、坑的表现、如何避坑完整复盘。

· 结论先行

1. 报错第一行往往不是真正的错误。
    那条 git ls-remote ... '不是内部或外部命令' 才是根因：系统没装 git。
2. 别按 npm 名字装 GitHub 插件。
    npm 上的 dsh-plugin-manager 是另一个作者的项目（同名同版本，纯属「名字撞车」），按名字装会装错东西；必须用 GitHub 仓库 URL / tarball。
3. git 证书报错（SEC_E_UNTRUSTED_ROOT）
   ：Git for Windows 默认走 Windows SChannel，遇到「根证书不受信」→ 一条命令 git config --global http.sslBackend openssl 即可绕过。
4. Connection was reset / Could not connect
   ：这是网络线路问题，不是 git 也不是 VPN 的错。特征是间歇性 —— 换个网络（手机热点）常能通。
5. 「浏览器能开、命令行不能」= 浏览器走 QUIC/DoH，git 走 TCP，两者路径不同
   ，不能用浏览器结果推断命令行。
6. 插件装好后要重启 DSH 才加载；且该插件硬编码了 web profile 路径，在 desktop profile 下它的 MCP 管理会去改 web 的配置（插件作者设计如此，非安装问题）。

一、前提条件（问题产生的前提）

在复盘前我先把「当时处于什么环境」明晰一下，否则很多现象可能会被误判：

⚠️ 重点：「VPN 进程在运行」≠「VPN 在接管你的流量」。后面阶段六会拆解。

二、问题现象（原始报错）

用户执行安装后，终端/面板输出一大段，其中最关键的是这几行：

✓ Lockfile passes supply-chain policies (verified 4d ago)[WARN] deprecated @linxin666/dsh-web-ui-all@0.3.5: 迁移到 @linxin666/dsh-web-all[ERROR] Command failed with exit code 1: git ls-remote "https://github.com/liqichen/dsh-plugin-manager.git" HEAD "HEAD^{}"'git' 不是内部或外部命令，也不是可运行的程序或批处理文件。   ← ⬅ 真正的错误（但显示为乱码）dsh: pnpm failed in profile directory C:\Users\……\.dsh\profiles\desktop

🕳 坑 1 – 错误被「噪音」淹没 + 中文乱码。 报错前面有 Lockfile 校验、deprecated 警告、pnpm 更新提示，真正错误藏在倒数几行，而且 Windows CMD 下的中文报错是 GBK 乱码（'git' �����ڲ����ⲿ���），差点被当成看不懂的乱码忽略。

✅ 避坑：只看 [ERROR]/failed 后面的 命令 那一行，并抓住「不是内部或外部命令」这个特征词（它就是「没找到该程序」）。用 chcp 65001 切 UTF-8 可让中文正常显示。

三、排障决策树（先看结论，再往下走）

插件安装报错 └─ 报错里有没有 "不是内部或外部命令" / "ls-remote" / "git"      有 → 系统没装 git 或 PATH 没生效 → 装 git / 修复 PATH      无 → 往下 └─ 报错是不是 "证书" / "SEC_E_UNTRUSTED_ROOT" / "schannel"      是 → git 走的是 SChannel，根证书不受信 → 设 http.sslBackend=openssl      无 → 往下 └─ 报错是不是 "Connection was reset" / "Could not connect" / timeout      是 → 网络线路问题（间歇性）→ 换网络 / 代理 / 镜像 / 重试      无 → 往下 └─ 报错是不是 "ERR_PNPM_UNEXPECTED_STORE" / "unable to open database file"      是 → store 位置/权限问题 → 指定 --store-dir / 提权

四、分阶段复盘（目标 → 交付物 → 坑 → 避坑）

阶段 1 · 确诊「git 未安装」

• 🎯 目标
  ：搞清 pnpm 为什么在解析 git 依赖时退出。
• 📦 交付物
  ：确认 系统无 git（Get-Command git 为空，常见路径 C:\Program Files\Git\cmd\git.exe 不存在）。
• 🕳 坑的表现
  ：git ls-remote ... 不是内部或外部命令；命令行里 git --version 直接报错。
• ✅ 避坑
  ：装 git（choco install git -y，需管理员）；装完必须开新终端（已运行进程的 PATH 不会刷新，见阶段 5）。

阶段 2 · 干掉「npm 同名撞车」

• 🎯 目标
  ：确定到底该装「哪个 dsh-plugin-manager」。
• 📦 交付物
  ：查明 npm 上的 dsh-plugin-manager@0.1.0 是 hrhgit 的项目；你要装的是 liqichen 的仓库（同名同版本但不同项目）；它的 package.json 里 repository 指向 github.com/hrhgit/...。
• 🕳 坑的表现
  ：如果直接 dsh plugin add dsh-plugin-manager，会安安静静装成另一个项目，功能对不上，且很难察觉。
• ✅ 避坑
  ：装前核对 repository/description；用 GitHub 仓库 URL / commit tarball 安装，而不是裸名字。

阶段 3 · 用「GitHub tarball」绕过 git（阶段性成功）

• 🎯 目标
  ：在没有 git 的前提下先把插件装上。
• 📦 交付物
  ：用 commit 快照 tarball 让 pnpm 直接下载，无需 git ls-remote：

  dsh plugin --profile desktop add --store-dir "C:\Users\……\AppData\Local\pnpm\store" \  "https://github.com/liqichen/dsh-plugin-manager/archive/36a73f0174f0714243ba01afcc9a5ffaa36b0b04.tar.gz"

   装完后 package.json 的 dependencies 与 dsh.profile.bundles 都写入 dsh-plugin-manager，node_modules/dsh-plugin-manager/ 文件齐全。

• 🕳 坑的表现
  ： 
• 第一次报 ERR_PNPM_UNEXPECTED_STORE：node_modules 链接的 store 和 pnpm 当前默认 store 不一致。
• 第二次报 ERR_SQLITE_ERROR unable to open database file：写入全局 store 被权限/沙箱拦截。
• ✅ 避坑
  ： 
• store 不一致 → 显式 --store-dir <node_modules 实际链接的那个 store>。
• 写 store 被拒 → 需完整写权限（受限命令行环境里即使 --store-dir 也可能写不进，要提升权限）。
• ⚠️ 诚实提醒：这个 store 告警往往跟运行环境有关（受限/沙箱命令行 vs 真实 GUI，pnpm 默认 store 可能不同）。很多场景下真实用户环境根本没有此问题，别把它当成必然坑。

阶段 4 · 验证安装与加载

• 🎯 目标
  ：确认插件「真的装进去了、且会被加载」。
• 📦 交付物
  （三条都过）： 

1. package.json
   ：dependencies 含 dsh-plugin-manager；dsh.profile.bundles 含 dsh-plugin-manager。
2. node_modules/dsh-plugin-manager/
   ：index.js、client.js、cordis.patch.yml、package.json 齐全。
3. 让 DSH 实际组合一次配置：

   dsh --profile desktop --dump-config

    输出出现 # == dsh-plugin-manager 和它插入的 - id: plugin-manager-ui，即加载链路打通。
• 🕳 坑的表现
  ： 
• dsh.client.inject
   里的 @deepseek-ai/dsh-client-runtime 等在 profile 的 node_modules顶层找不到 → 误以为缺依赖。
• ✅ 避坑
  ：这些 @deepseek-ai/dsh-client-* 是宿主 @deepseek-ai/dsh-web-app 运行时提供的，不进 profile 的 node_modules，属正常。
• 🕳 坑的表现
  ：装完当前 DSH 实例还没加载（它是新 bundle 层，要重启）。
• ✅ 避坑
  ：重启 DSH 再进「设置 → 插件管理」。

阶段 5 · 修复 git 的「证书不受信」

• 🎯 目标
  ：让 git 能正常连 GitHub。
• 📦 交付物
  ：

  git config --global http.sslBackend opensslgit ls-remote https://github.com/liqichen/dsh-plugin-manager.git HEAD# 36a73f0174f0714243ba01afcc9a5ffaa36b0b04	HEAD   ✅

• 🕳 坑的表现
  ：git ls-remote ... schannel: SEC_E_UNTRUSTED_ROOT (0x80090325) 证书由不受信任的颁发机构颁发。
• ✅ 避坑 + 根因
  ：Git for Windows 默认 SChannel（Windows 证书库），对 GitHub 根证书不信任；切到 OpenSSL 后端（用 git 自带的 CA 包）即可。写在 ~/.gitconfig，用 git config --global --unset http.sslBackend 可撤销。
• 🕳 坑的表现
  ：装完 git 后旧终端/DSH 里 git 仍找不到（系统 PATH 已更新，但已启动的进程 PATH 没有刷新）。
• ✅ 避坑
  ：重开终端 / 重启 DSH；用 git --version 验证。

阶段 6 · 拆解「网络线路问题」（最大的坑）

• 🎯 目标
  ：解释 Recv failure: Connection was reset / Could not connect to github.com:443 ... 超时。
• 📦 交付物
  ：确诊这是间歇性网络线路问题，与 git 配置、VPN 均无关；换网络（手机热点）后 git ls-remote 成功。
• 🕳 坑的表现与判定
  （逐条排除）： 
1. 「是 VPN 吗？」
    —— 排查发现：VPN 进程在跑（CNPC_C330、openvpn-gui），但虚拟网卡全部「已断开」（Media disconnected），其默认路由跃点数 256（备用），真正生效的是直连线路（跃点数 0），系统代理也处于关闭状态。→ 并非 VPN 接管流量。👉 教训：单看「进程存在」会误判，要看「路由/网卡实际状态」。
2. 「是 DNS 吗？」
    —— github.com 解析到 20.205.243.166；api.github.com 解析到紧挨着的 20.205.243.168却能通。说明不是 DNS 解析不到，而是对特定边结点 IP 的 TCP 连接不通。👉 教训：解析出 IP ≠ 该 IP 能连；要真正建立 TCP 才算通。
3. 「是 IPv6 吗？」
    —— github.com 无 AAAA(IPv6) 记录 → 排除。
4. 「为什么浏览器能开、命令行不能？」
    —— 浏览器走 QUIC(UDP)/DoH，git/pnpm 走 TCP，两者路径不同。👉 教训：不能用浏览器结果推断命令行能否连通。
5. 「是间歇性吗？」
    —— 是该 IP 的 TCP 连接间歇性被重置/超时，换网络往往就好。
• ✅ 避坑（按需三选一）
  ： 
• 换一条更稳的网络/线路后重试；
• 有代理则 git config --global http.proxy http://127.0.0.1:<端口>；
• 用加速镜像前缀，如 https://ghproxy.com/https://github.com/...。

五、坑点汇总表（一表看懂）

六、快速排查清单（下次直接照做）

当再次遇到「DSH 插件装不上」：

•  先看报错中 [ERROR] 后的命令与错误行，别被前面噪音带偏。
• git --version
  ：没有 → 装 git，开新终端。
•  确认安装源：npm 名字 vs GitHub 仓库？装前核对 repository，GitHub 插件优先用 URL/tarball。
•  若报 store 相关 → pnpm config get store-dir 与 node_modules/.modules.yaml 的 storeDir 对比，不一致就显式 --store-dir。
•  若报 unable to open database file → 检查是否有写全局 store 的权限。
•  若报证书 → git config --global http.sslBackend openssl。
•  若报 Connection reset / Could not connect / timeout → 这是网络（间歇性），换网络 / 代理 / 镜像 / 重试，别去改 git 配置。
•  装完用 dsh --profile <名字> --dump-config 看是否出现该 bundle 层。
•  确认以上后 重启 DSH，再进设置面板使用。

七、结论与长期建议

1. 95% 的「git 装不上 GitHub 插件」= 没装 git + 网络线路不稳定
   ，跟 DSH 本身无关。
2. git 证书问题
   用一条 http.sslBackend openssl 根治（写在 ~/.gitconfig，保留即可）。
3. GitHub 插件安装
   优先用 仓库 URL/tarball，避免 npm 同名撞车；装前核对 repository。
4. 网络线路是最大变量
   ：GitHub 在你所在网络常间歇性不通。要长期稳定用 GitHub，建议代理或镜像，不要裸连大流量场景。
5. 重启
   ：装插件、改 PATH、改 git 配置后，凡是「看起来没生效」，先重启进程/DSH。

附录 · 本文用到的关键命令与文件

# 查 gitgit --versiongit ls-remote https://github.com/liqichen/dsh-plugin-manager.git HEAD# 修证书 / 走代理git config --global http.sslBackend opensslgit config --global http.proxy http://127.0.0.1:<端口># 装插件（GitHub tarball，无需本地 git）dsh plugin --profile desktop add \  --store-dir "C:\Users\……\AppData\Local\pnpm\store" \  "https://github.com/liqichen/dsh-plugin-manager/archive/<commit>.tar.gz"# 验证加载链路dsh --profile desktop --dump-config# 查 store / 路由 / 网络pnpm config get store-dirroute print -4Resolve-DnsName github.com -Type A

关键文件：package.json（dependencies + dsh.profile.bundles）、node_modules/.modules.yaml（storeDir）、node_modules/dsh-plugin-manager/{package.json,cordis.patch.yml,index.js,client.js}、~/.gitconfig（http.sslBackend）。