dsh插件安装原理与profile驱动机制详解

1. 先搞清楚 dsh 是什么，再谈插件安装

很多人一看到“dsh如何安装插件”就直接抄命令、改配置，结果报错一串：“plugin tree failed to load”、“@deep plugin failed to load”、“dsh web authentication required”，甚至卡在“reopen the url printed by dsh web”这一步死循环。我去年帮三个团队落地 dsh 时，前两次都栽在这儿——不是命令写错了，而是压根没搞清 dsh 的本质。

dsh 不是传统意义上的 IDE 插件宿主（比如 VS Code 或 PyCharm），也不是一个开箱即用的桌面应用（像 Blender 或 OBS）。它是一个基于 Node.js 构建的、面向开发者工作流的命令行驱动型诊断与协作平台，核心定位是“代码现场的轻量级协同诊断终端”。它的插件体系不走 npm install -g 那套全局路径逻辑，也不依赖 package.json 的 dependencies 字段自动加载；相反，它采用profile 驱动的插件沙箱机制：每个 profile（如 web、desktop、self-improved）对应一套独立的插件注册表、依赖隔离环境和权限上下文。你执行dsh plugin --profile web add dshmarket，本质不是“安装一个包”，而是向名为web的 profile 注册一个远程插件源的声明，并触发该 profile 下的专用插件加载器去拉取、校验、沙箱化执行。

这就解释了为什么大量热词里反复出现dsh web authentication required和reopen the url printed by dsh web—— 因为webprofile 的插件（尤其是 dshmarket 这类带 UI 组件的）必须通过浏览器完成 OAuth2.0 授权链，获取 scoped token 后才能访问其后端服务。这不是“网络问题”，而是设计使然：dsh 把插件的权限粒度控制到了 profile 级别，避免一个插件越权读取 desktop profile 的本地文件或调用系统 API。

所以，安装 dsh 插件的第一步，永远不是敲npm install，而是确认三件事：

1. 你当前使用的 dsh 版本是否支持目标插件的最低 runtime 要求（例如@deep插件要求 dsh ≥ 3.8.0）；
2. 你要安装到哪个 profile（web/desktop/self-improved），不同 profile 的插件 ABI 不兼容；
3. 该插件是否需要外部认证（如 dshmarket）、本地构建（如自定义 diagnostic rule 插件）或二进制依赖（如涉及 PDF 解析的 doc/pdf 插件需 libpoppler）。

提示：dsh --version和dsh profile list是你启动前必须运行的两个命令。很多报错源于版本过旧或 profile 未初始化。dsh 3.x 默认只创建defaultprofile，而webprofile 需显式运行dsh profile create web才能使用。

2. 插件安装的三种路径：官方市场、Git 仓库、本地开发包

dsh 的插件安装不是单一命令能覆盖的，它根据来源和形态分为三类路径，每类路径的底层机制、失败原因和调试方法完全不同。把它们混用，是导致failed to clone git repository和invalid filename returned by a server这类错误的根源。

2.1 官方市场插件（dshmarket）：走 Web Auth + CDN 分发

这是最常见也最容易出错的路径。当你执行dsh plugin --profile web add dshmarket，实际发生的是：

1. dsh CLI 向https://api.dshmarket.io/v1/registry发起 GET 请求，查询dshmarket插件元数据（含 manifest.json、签名证书、支持的 profile 列表）；
2. 检查webprofile 是否已授权：若未授权，CLI 输出类似dsh web: opening the default browser; pass --no-open to disable的提示，并生成一个临时 URL（如https://auth.dsh.dev?code=xxx&state=yyy）；
3. 你手动在浏览器打开该 URL，完成登录并授权dshmarket.readscope；
4. 授权成功后，dsh CLI 收到回调，用获得的 access_token 向https://cdn.dshmarket.io/plugins/dshmarket-1.2.0.tgz下载压缩包；
5. 校验.tgz内置的SIGNATURE.asc与公钥匹配，解压到~/.dsh/profiles/web/plugins/dshmarket/；
6. 加载manifest.json中声明的入口文件（通常是index.js），注入webprofile 的沙箱环境。

常见失败点：

• 浏览器未完成授权就关闭页面 → 报错dsh web authentication required，此时需重新运行命令，不能 Ctrl+C 中断后重试，必须让 CLI 完整等待回调；
• 网络策略拦截 CDN 域名 → 报错failed to fetch from cdn.dshmarket.io，解决方案是配置DSH_PLUGIN_CDN_MIRROR=https://mirrors.tuna.tsinghua.edu.cn/dshmarket/环境变量；
• manifest.json中main字段指向不存在的文件 → 报错plugin entry not found，这是插件作者发布缺陷，需联系维护者。

实操心得：我遇到过一次invalid filename returned by a server，排查发现是公司代理服务器对.tgz文件的 Content-Disposition 头做了非法重写，强制添加了双引号包裹的 filename。临时解法是在~/.dsh/config.json中添加"plugin_cdn_bypass_proxy": true，让插件下载绕过系统代理直连。

2.2 Git 仓库插件：走 Git Clone + 语义化版本解析

这类插件通常由社区开发者维护，格式为username/repo或完整 Git URL。执行dsh plugin --profile desktop add madage/dsh-self-improved时，dsh 并不会调用npm install git+https://...，而是：

1. 解析madage/dsh-self-improved为https://github.com/madage/dsh-self-improved.git；
2. 运行git clone --depth 1 --branch main https://github.com/madage/dsh-self-improved.git /tmp/dsh-plugin-xxxx；
3. 检查克隆目录下是否存在dsh-plugin.json（非 package.json！这是 dsh 专用插件描述文件）；
4. 读取dsh-plugin.json中的compatible_profiles: ["desktop"]，验证当前 profile 是否匹配；
5. 执行npm ci --no-audit --no-fund安装依赖（注意：是ci而非install，强制使用 lockfile）；
6. 将整个目录软链接到~/.dsh/profiles/desktop/plugins/madage-dsh-self-improved/。

关键细节：

• --depth 1导致无法检出 tag，若插件作者只打 tag 不推 main 分支，会报错failed to clone。此时需指定 commit hash：dsh plugin --profile desktop add madage/dsh-self-improved#v2.1.0；
• dsh-plugin.json必须存在且格式正确，最小结构为：

  { "name": "dsh-self-improved", "version": "2.1.0", "main": "dist/index.js", "compatible_profiles": ["desktop"], "dsh_runtime": ">=3.7.0" }

• 若插件依赖 native addon（如 node-pdfium），npm ci可能失败，需提前安装 Python 3.9+ 和 Visual Studio Build Tools（Windows）或 Xcode Command Line Tools（macOS）。

注意：dsh plugin --profile web add ...不能用于 Git 仓库插件，因为webprofile 的沙箱禁止执行git clone和npm ci。这类插件只能安装到desktop或self-improved等允许本地构建的 profile。

2.3 本地开发插件：走符号链接 + 热重载

这是调试插件最高效的方式。假设你在/home/user/my-dsh-plugin开发一个诊断规则插件，目录结构如下：

my-dsh-plugin/ ├── dsh-plugin.json ├── src/ │ └── index.ts ├── dist/ │ └── index.js └── package.json

安装命令为：dsh plugin --profile desktop add /home/user/my-dsh-plugin。dsh 会：

1. 验证dsh-plugin.json存在且compatible_profiles包含desktop；
2. 检查dist/index.js是否存在（若不存在，报错build output missing）；
3. 在~/.dsh/profiles/desktop/plugins/my-dsh-plugin/创建指向/home/user/my-dsh-plugin的符号链接；
4. 启动时自动监听dist/目录变化，文件更新后 300ms 内热重载插件。

优势在于无需反复npm publish和dsh plugin add，改完代码tsc --watch即可实时生效。但必须注意：

• dsh-plugin.json中的main字段必须指向dist/下的文件，不能是src/；
• package.json中的scripts.build应设为tsc --build，确保类型检查通过才生成 dist；
• 符号链接路径不能包含空格或中文，否则 Windows 下会报错EINVAL。

3. Profile 配置深度解析：为什么插件总在错误的环境下加载

几乎所有plugin(s) failed to load错误，根源都在 profile 配置上。dsh 的 profile 不是简单的配置文件夹，而是一套完整的执行上下文，包含独立的 Node.js runtime、环境变量、插件注册表和权限策略。理解 profile 的构成，是解决插件加载问题的核心。

3.1 Profile 的物理结构与加载优先级

每个 profile 对应~/.dsh/profiles/<name>/目录，其内部结构严格固定：

web/ ├── config.json # profile 级配置（如 auth token、CDN mirror） ├── plugins/ # 已安装插件的符号链接或解压目录 │ ├── dshmarket/ # 来自 market 的插件 │ └── my-custom/ # 来自本地路径的插件 ├── node_modules/ # 仅用于插件构建的临时依赖（git 插件 clone 后 npm ci 生成） ├── cache/ # 插件 manifest 缓存、CDN 下载缓存 └── runtime/ # profile 专属的 Node.js 二进制（可选，用于版本隔离）

dsh 加载插件时，按以下顺序搜索：

1. 当前命令指定的 profile（--profile web）；
2. 若未指定，则使用dsh config get profile.default返回的 profile；
3. 若profile.default为空，则 fallback 到defaultprofile；
4. 绝不跨 profile 加载：webprofile 的插件无法被desktopprofile 调用，反之亦然。

这就是为什么dsh plugin --profile web add dshmarket成功后，在dsh --profile desktop下却提示plugin not found—— 它们根本不在同一个插件注册表里。

3.2 Profile 初始化的隐藏陷阱

dsh profile create web看似简单，实则暗藏玄机。该命令会：

• 创建~/.dsh/profiles/web/目录；
• 生成默认config.json，其中"auth": {"token": "", "expires_at": 0}；
• 但不会自动设置runtime.version。

这意味着，如果你的系统全局 Node.js 是 v18.17.0，而某个插件（如@deep）要求 Node.js ≥ v20.0.0，dsh --profile web启动时会直接报错incompatible node version，且错误信息不明确。解决方案是：

1. 下载 Node.js v20.0.0 二进制到~/.dsh/profiles/web/runtime/node-v20.0.0-linux-x64/（Linux）；
2. 在~/.dsh/profiles/web/config.json中添加：

   { "runtime": { "version": "20.0.0", "path": "~/.dsh/profiles/web/runtime/node-v20.0.0-linux-x64/bin/node" } }

3. 运行dsh profile verify web确认 runtime 可用。

实操心得：我在某客户现场遇到dsh: plugin tree failed to load，最终发现是webprofile 的runtime.path指向了一个被rm -rf删除的旧 Node.js 目录。dsh 不会主动校验 runtime 路径有效性，只在启动时静默失败。建议每次dsh profile create后，立即运行dsh profile verify <name>。

3.3 Profile 级环境变量与插件行为差异

插件在不同 profile 下的行为可能截然不同，这由 profile 的环境变量决定。例如：

• webprofile 默认设置DSH_ENV=production和DSH_AUTH_MODE=oauth2，插件调用 API 时自动携带 Bearer token；
• desktopprofile 设置DSH_ENV=development和DSH_AUTH_MODE=none，插件可直接读取本地文件；
• self-improvedprofile 设置DSH_ENV=staging和DSH_AUTH_MODE=api_key，插件需从~/.dsh/api_key读取密钥。

一个典型问题是：你开发的插件在desktop下正常读取./docs/report.pdf，但在web下报错Permission denied。这不是插件 bug，而是webprofile 的沙箱策略禁止直接访问文件系统，必须通过dsh.file.read()API（该 API 在web下会触发浏览器 File API 选择器）。

因此，插件开发必须遵循 profile-aware 设计：

// bad: 直接 fs.readFileSync('./report.pdf') // good: if (dsh.env === 'desktop') { const data = fs.readFileSync(path.join(dsh.cwd, 'report.pdf')); } else if (dsh.env === 'web') { const file = await dsh.file.select({ accept: '.pdf' }); const data = await file.arrayBuffer(); }

4. 插件故障排查实战：从failed to load到精准定位

当dsh plugin list显示插件状态为failed，或运行时抛出plugin tree failed to load，不要急于重装。dsh 提供了一套完整的诊断工具链，按以下顺序排查，90% 的问题能在 5 分钟内定位。

4.1 第一层：检查插件注册状态与基础元数据

运行dsh plugin list --profile web --verbose，输出类似：

NAME VERSION STATUS ERROR MESSAGE dshmarket 1.2.0 failed signature verification failed my-custom 0.1.0 active -

STATUS列是第一线索：

• active：插件已加载，可正常使用；
• failed：插件注册失败，需看ERROR MESSAGE；
• pending：插件正在下载或构建，长时间不动说明网络或权限问题；
• disabled：插件被手动禁用（dsh plugin disable）。

对failed插件，重点看ERROR MESSAGE。常见类型：

• signature verification failed→ 插件包被篡改或镜像源未同步签名；
• dsh_runtime incompatible→dsh-plugin.json中dsh_runtime字段与当前 dsh 版本不匹配；
• missing dsh-plugin.json→ 插件源码未提供 dsh 专用描述文件。

提示：--verbose参数会显示插件物理路径（如/home/user/.dsh/profiles/web/plugins/dshmarket/），这是下一步检查的起点。

4.2 第二层：验证插件目录完整性与依赖

进入插件目录（如~/.dsh/profiles/web/plugins/dshmarket/），执行：

ls -la # 检查关键文件是否存在 ls -la manifest.json SIGNATURE.asc dist/index.js # 检查签名是否有效（需提前导入 dsh 公钥） gpg --verify SIGNATURE.asc manifest.json # 检查 dist/index.js 是否可执行 node -e "require('./dist/index.js')"

若node -e "require('./dist/index.js')"报错Cannot find module 'dsh-core'，说明插件依赖未安装。此时需：

1. 确认该插件是否为 npm 包（查看是否有package.json）；
2. 若有，运行npm ci --prefix .（注意--prefix .指向当前目录）；
3. 若无package.json，说明是预构建插件，错误源于dist/index.js本身有语法错误，需联系作者。

4.3 第三层：启用插件调试日志

dsh 的插件加载器默认静默失败。要获取详细日志，需设置环境变量：

# Linux/macOS export DSH_LOG_LEVEL=debug export DSH_PLUGIN_DEBUG=true dsh --profile web # Windows PowerShell $env:DSH_LOG_LEVEL="debug" $env:DSH_PLUGIN_DEBUG="true" dsh --profile web

日志中会输出：

• 插件加载的完整路径和时间戳；
• dsh-plugin.json解析过程；
• 沙箱环境初始化参数；
• 每个插件的activate()方法执行堆栈。

我曾用此方法定位到一个@deep插件的 bug：日志显示Error: Cannot find module 'pdfjs-dist'，但pdfjs-dist明明在node_modules/中。深入日志发现，webprofile 的沙箱使用了vm.Module运行插件，而pdfjs-dist的某些 CJS 导出方式与vm.Module不兼容。解决方案是让插件作者将pdfjs-dist改为 ESM 格式发布。

4.4 第四层：模拟插件加载流程

当以上步骤仍无法定位，可手动复现加载流程：

# 1. 进入插件目录 cd ~/.dsh/profiles/web/plugins/dshmarket/ # 2. 设置 dsh 模拟环境 export DSH_PROFILE_PATH="$HOME/.dsh/profiles/web" export DSH_RUNTIME_PATH="/usr/bin/node" # 或你的 Node.js 路径 # 3. 运行插件入口（跳过沙箱，直接执行） node -r ./dist/index.js

如果node -r ./dist/index.js成功，说明问题在沙箱环境；如果失败，说明插件代码本身有缺陷。这是区分“dsh 问题”和“插件问题”的黄金标准。

注意：node -r会绕过所有沙箱限制，仅用于诊断，切勿在生产环境使用。

5. NPM 相关问题的专项处理：为什么npm install不能替代dsh plugin add

大量热词如npm : 无法加载文件 d:\program files\nodejs\npm.ps1、npm run build、npm warn deprecated都指向一个误区：试图用 npm 管理 dsh 插件。必须明确：dsh 插件不是 npm 包，dsh 的插件系统与 npm registry 完全解耦。混淆二者会导致一系列连锁问题。

5.1 npm 与 dsh 插件的边界在哪里

维度	npm 包	dsh 插件
分发源	npm registry（public/private）	dshmarket CDN、Git 仓库、本地路径
安装命令	npm install <pkg>	dsh plugin add <source>
依赖管理	package.json+node_modules/	dsh-plugin.json+ profile 级node_modules/
加载机制	CommonJS/ESM require/import	dsh 沙箱vm.Module或Worker
权限模型	进程级（可访问所有文件）	profile 级（受dsh.file.*API 限制）

一个 npm 包要成为 dsh 插件，必须满足：

1. 提供dsh-plugin.json（而非仅package.json）；
2. 入口文件（main字段）导出符合 dsh 插件协议的对象：

   export default { activate: (context: PluginContext) => { /* 初始化 */ }, deactivate: () => { /* 清理 */ }, contributes: { /* 声明贡献点，如 commands、diagnostics */ } };

否则，npm install dshmarket只是把代码下载到当前项目node_modules/，dsh 完全感知不到它。

5.2 npm 环境问题对 dsh 的间接影响

虽然 dsh 不直接调用 npm，但dsh plugin add的 Git 插件路径会触发npm ci，因此 npm 环境异常会阻断插件安装。常见问题及解法：

问题：npm : 无法加载文件 d:\program files\nodejs\npm.ps1
原因：PowerShell 执行策略禁止运行脚本。
解法：以管理员身份运行 PowerShell，执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser。

问题：npm run build失败，导致插件 dist 不存在
原因：插件作者的buildscript 依赖全局安装的工具（如tsc），但npm ci不安装 devDependencies。
解法：在插件根目录的package.json中，将tsc等构建工具列为dependencies而非devDependencies，或改用npx tsc。

问题：npm WARN deprecated node-domexception@1.0.0
原因：插件依赖了已废弃的包，但不影响 dsh 加载（dsh 沙箱不执行该包代码）。
解法：忽略警告，或向插件作者提交 PR 更新依赖。切勿在~/.dsh/目录下运行npm update，这会污染 profile 环境。

5.3 镜像源配置的最佳实践

dsh 自身不读取.npmrc，但dsh plugin add的 Git 插件路径会调用npm ci，因此.npmrc依然重要。推荐配置：

# ~/.npmrc registry=https://registry.npm.taobao.org/ @deep:registry=https://npm.deep.dev/ //npm.deep.dev/:_authToken=${DEEP_NPM_TOKEN}

同时，为 dsh 插件市场配置独立镜像：

# 设置 dshmarket 镜像 echo '{"plugin_cdn_mirror":"https://mirrors.tuna.tsinghua.edu.cn/dshmarket/"}' > ~/.dsh/config.json

这样，dsh plugin add dshmarket走清华镜像，dsh plugin add deep/some-plugin走 deep.dev 私有 registry，互不干扰。

最后分享一个小技巧：如果你经常在离线环境调试插件，可以预先下载插件包。运行dsh plugin --profile desktop add --dry-run madage/dsh-self-improved，它会输出将要 clone 的 Git URL 和 npm install 命令，你可在联网机器上执行这些命令，打包node_modules/和dist/，再拷贝到离线机器的插件目录。