DSH Plugin market 装失败怎么取证：插件市场安装日志、命令回显与可提交 issue 的材料

DSH Plugin market 的安装按钮只回一句“安装失败”，剩下的线索得自己找。 上周的一次失败正好把下载、解包、依赖和加载四个阶段串了起来，也让我确认：按日志顺序走，比反复重试有效得多。

DSH Plugin market 安装失败的那个下午

界面上的失败提示只是结论，不是原因。

那是一个文档索引插件，版本 1.4.2，点击安装后进度条转了几秒，弹出一句“download failed”。同一个网络下，别的插件装得很快，所以第一反应并不是网络全断了。 我换了镜像、清了缓存，重新点了一次，错误一模一样。这两步后来证明是白做，因为它们同时改动了多个变量，现场反而更难还原。

把包名和版本从条目页抄下来之后，我在终端用同样的参数重跑了一次。回显比界面多出 registry 地址、HTTP 状态码和一个解包目录，信息量完全不是一个级别。 界面只负责告诉你“没成”，命令行才会告诉你“停在哪”。从这行回显开始，问题被缩小到“这个包在某个阶段失败”。

我没有再换版本，也没有再清缓存，而是固定同一个包、同一个版本，每次只改一个条件。这个约束听起来保守，却让后面的每条日志都能互相对上。 排查安装问题最怕的不是信息少，而是每次失败的条件都不一样。

DSH插件 安装回显里，下载与解包怎么分

先看进度停在哪里，再看错误码指向哪个阶段。

下载阶段的日志通常会出现 fetch、GET、HTTP 状态码或超时字样。404 多半是版本不存在或包名写错，ETIMEDOUT 与证书错误才指向网络链路。 解包阶段的关键词不一样：tarball、integrity、ENOENT、EACCES。看到这些词，说明包已经下来了，问题在压缩包本身或目标目录的权限。

dsh plugin add @acme/doc-index@1.4.2 --verbose

加上详细输出后，终端会打印实际请求的地址和落盘位置。把它与市场条目上的版本核对一次，能排除“装错了版本”这种低级但常见的偏差。 如果回显停在 fetch，先看状态码；如果已经开始写文件，就别再怀疑网络。

npm pack @acme/doc-index@1.4.2
tar -tzf acme-doc-index-1.4.2.tgz | head -20

如果 npm pack 能完成而安装仍然失败，问题不在下载。手动列一次 tarball 内容，可以确认包内路径是否完整、有没有异常的大小写或权限位。 解包失败有时是包本身的打包方式导致，与你的机器无关；这类情况在本地重试多少次都不会变。

DeepSeek Harness 插件依赖解析的日志特征

依赖问题通常不在最后一行报错，而在它前面的解析树。

ERESOLVE、peer dependency、idealTree、reify 这些词出现时，失败发生在依赖解析，而不是下载。日志往往会先列出一串版本关系，最后才给出结论，真正的冲突藏在中间。 这时直接搜索最后一行没有用，要往上找第一个被标红的版本区间。

npm view @acme/doc-index@1.4.2 dependencies peerDependencies
npm ls @acme/shared-utils

前一条命令看插件声明了什么，后一条看当前环境实际装了什么。两边对不上，就能解释为什么解析器拒绝继续。 DeepSeek插件常见的冲突是共享工具库的版本区间重叠，而不是缺少某个包。

还要记录 Node 与包管理器的版本。同一个依赖树在不同 npm 版本下可能给出不同结果，尤其是可选依赖与 peer 依赖的处理方式。 把这些版本写进排查记录，别人复现时就不会因为环境差异得到另一种错误。

DSH plugin 装上却加载失败时看什么

装上了却不能用，证据要从运行日志里取。

命令返回 added，插件状态却停在 FAILED 或 PENDING，这说明安装阶段已经结束，问题进入加载阶段。此时再重装通常没有意义，反而会覆盖掉有用的运行日志。 先确认插件是否出现在列表里，再看它为什么没有进入可用状态。

dsh plugin list
dsh plugin doctor @acme/doc-index

如果运行日志里是 module not found，重点查入口文件与依赖是否真的落盘；如果是 API 不兼容或 schema 校验失败，重点查插件支持的 Harness 版本范围。 加载失败与安装失败的处置路径完全不同，混在一起排查只会绕远路。先判断失败发生在哪个阶段，再决定要不要继续查兼容性。

把 DSH Plugin market 的失败整理成可复现材料

可复现的材料由版本矩阵、最短步骤和脱敏日志组成。

1. 写清 Harness、插件、Node、包管理器与操作系统版本。
2. 给出从干净 profile 开始的最短复现步骤，不省略关键参数。
3. 附上命令回显与日志关键段，保留报错前后的上下文。
4. 说明已经排除的变量，例如换网络、换镜像、清缓存的结果。
5. 替换 token、内网地址与用户名之后再提交。

材料发给同事时，对方应该能按步骤得到同一条错误。只能得到“大概也是失败”，说明还缺关键条件。 日志不是越多越好，能指向同一个包与同一个阶段的几段，比整份终端记录更有用。

连续重试十次会让第一次的错误被覆盖，先清所有缓存则可能把现场一起清掉。把网络、镜像和版本同时改掉，即使装好了也不知道是哪一项起了作用。 每次只改一个变量，改完立刻记录结果，这条规矩在安装排障里同样适用。

最后定位到的并不是网络，而是插件声明的一个 peer 依赖在内网 registry 上不存在。那条信息在第一次失败的回显里就已经写出，只是被界面上的“download failed”盖住了。 这也是我后来坚持先拿命令行回显的原因：它不保证答案显眼，但至少不会把线索删掉。如果当时只保留了截图，这条线索很可能就此丢失。