插件安装避坑指南 samorachumbi/dsh-plugin-install-guide

dsh plugin add 如何两次搞垮我的配置文件——以及那种绝不会出问题的安装方法

如果你的 DeepSeek Harness 工具突然报错：

TypeError: Cannot read properties of undefined (reading 'prepare')

——而且 web_search 并不报错，它只是返回 “无结果”——那么你的配置文件出现了 分裂的 Symbol。这两个症状其实是同一个故障。

下面说明它的成因、如何在十秒内确认，以及如何安装插件才能杜绝此问题。已针对 DSH 0.1.1-rc.2 验证。

bash diagnose.sh # 或者：先 curl 该文件并阅读，它只有 60 行

简要版

- DSH 工具分发通过 模块级 Symbol 查找其调度器。
- @deepseek-ai/dsh-tools 的两份物理副本 → 两个 Symbol 实例 → 查找返回 undefined → 每一次工具调用都会抛错。
- dsh plugin --profile web add 会在你的配置文件目录内运行 pnpm。这正是产生第二份副本的原因。
- 所以“使用官方 CLI，绝不要在配置文件内运行 pnpm”是自相矛盾的建议——而它在很多地方被反复提及，包括我自己写的笔记。

为什么是 Symbol，以及为什么两份副本会毁掉一切

@deepseek-ai/dsh-tools 在模块作用域中只定义一次调度器键：

// @deepseek-ai/dsh-tools/lib/index.js:2416
const TOOL_RUNTIME_SCHEDULER = Symbol("@deepseek-ai/dsh-tools.scheduler");

// @deepseek-ai/dsh-tools/lib/index.js:2564
ToolRuntime[TOOL_RUNTIME_SCHEDULER] = { prepare, dispatch, finalize, finish };

而 agent 循环会把它读回来：

// @deepseek-ai/dsh-agent-loop/lib/index.js:193
const prepared = await ctx.tools[TOOL_RUNTIME_SCHEDULER].prepare(call.exec);

Symbol 是 身份，而不是字符串。Symbol("x") === Symbol("x") 为 false。因此，如果循环从副本 A 加载 dsh-tools，而运行时从副本 B 注册自身，那么 ctx.tools 中的键就不是正在查找的键——查找结果为 undefined，于是 .prepare() 抛错。

最麻烦的是影响范围：你调用的工具是什么完全无关紧要。所有工具都会失效，包括你从未碰过的包里的工具，所以它读起来像是整个 harness 彻底崩溃，而不是某次安装出了问题。

为什么在配置文件内运行 pnpm 会创建第二份副本

配置文件使用提升式（hoisted）链接器，而插件将 @deepseek-ai/ 声明为 peer dependencies。当 pnpm 以配置文件目录作为工作目录运行时，它会通过写入 真实目录 来满足这些 peer 依赖，而配置文件此前在那里是 指向单一全局副本的符号链接：

~/.dsh/profiles/node_modules/@deepseek-ai/dsh-tools -> symlink, one global copy (healthy)
~/.dsh/profiles/web/node_modules/@deepseek-ai/dsh-tools -> real directory, second copy (split)

两棵物理目录树。两个 Symbol。下一次工具调用就会崩溃。

而官方 CLI 正是如此：

// @deepseek-ai/dsh/lib/bin.js:96
program.command("plugin")
.description("通过在 profile 目录中将剩余参数转发给 pnpm 来管理某个 profile 的插件")

// @deepseek-ai/dsh/lib/plugin-9h8shc4d.js:108
const result = spawnSync("pnpm", args.map((a) => anchorPathSpec(a, process.cwd())), { cwd: dir, ... })

这个 CLI 是一个有意为之、且有文档记录的 pnpm 转发器。它不是 bug——它就是设计——但这意味着你被告知要使用的命令，正是那个会破坏 profile 的命令。

一个本地手写的插件会让情况更糟，因为对 @deepseek-ai/ 的 peer 依赖是编写插件的常规方式：我们自己的插件就把 cordis、dsh-host-webserver、dsh-storage-domain 和 dsh-tools 声明为 peer。通过 CLI 安装那个插件，正是这套配方。

十秒钟确认它

线索是本该是符号链接的地方出现了一个真实目录：

find ~/.dsh/profiles -type d -path '/node_modules/@deepseek-ai/'

- 无输出——健康。该 profile 的 @deepseek-ai/ 条目是指向某个全局副本的符号链接。
- 有任何输出——一个被实体化的重复副本。下一次工具调用就会分裂 Symbol。

那个会喊狼来了的检查

常见的建议是“数一数物理副本的数量，必须恰好只有一个”：

find ~/.dsh ~/.nvm/versions/node//lib/node_modules -type d -name dsh-tools | xargs realpath | sort -u

这会过度报告。 如果你安装了两个 Node 版本，那条命令会在每个版本下都找到一个 dsh-tools——而那并不是分裂。一个运行 Node v24 的进程无法加载 versions/node/v22 下的副本，无论磁盘上有什么。
只有从实际运行 dsh 的那个 node 可达的副本才可能冲突。

本仓库中的 diagnose.sh 做得正确：它从正在运行的进程中找到那个 node，然后报告该 node 能加载哪些副本。

安装插件而不创建第二个副本

A. 复制文件——我现在就是这么做的

完全不涉及任何包管理器，所以这种失败模式根本不存在：

DEST="$HOME/.dsh/profiles/web/node_modules/"
mkdir -p "$DEST"
cp -r /lib /package.json "$DEST"/

然后在 profile 的 patch 层（~/.dsh/profiles/web/cordis.patch.yml）中注册它：

- insert:
- id:
name: ''

裸的 @deepseek-ai/ 导入会通过 ~/.dsh/profiles/node_modules/ 解析——那是共享的、指向全局副本的符号链接树——所以根本不需要安装任何依赖。这正是关键：插件的 peer 已经被那唯一存在的副本满足了。

这不是我发明的变通办法；这是我手写的一个插件自 2026-09-02 以来一直采用的安装方式。它经受住了服务器重启和一次完整的 harness 重装，正是因为没有任何依赖边需要重新解析。

B. 如果你必须使用包管理器

在除 profile 之外的任何地方做，然后把结果复制进去：

mkdir -p /tmp/pkg && cd /tmp/pkg && pnpm add @
cp -r /tmp/pkg/node_modules/ "$HOME/.dsh/profiles/web/node_modules/"
永远不要以 profile 作为工作目录运行 pnpm install、npm install 或 dsh plugin add。

如果它已经崩溃了

1. 删除已实体化的副本，使解析回退到单一的全局依赖树：
rm -rf ~/.dsh/profiles/web/node_modules/@deepseek-ai

2. 重启服务器。
3. 重新运行上面的 find，直到它不输出任何内容。
4. 通过复制文件来重新安装你的插件，而不是通过 CLI，否则你又会回到这里。

两次尝试中对我都没有用的方法：仅重启、清除缓存，或重新安装那个“导致”问题的插件。重复副本就在磁盘上；必须将其删除。

更隐蔽的变体，以防你在磁盘上没有重复副本时遇到它

dsh-tools 提供了双重构建：主入口 lib/index.js 和子路径 lib/types/.js 各自定义了自己的 Symbol。如果一个插件直接导入 @deepseek-ai/dsh-tools/types（或 ./presentation），而核心使用的是主入口，那么即使磁盘上只有一份副本，Symbol 也会被分裂。如果 find 结果是干净的，但你仍然崩溃，请检查你的插件导入了什么。

该给的功劳还是要给

这一切都不是对 DSH 设计的批评——在 profile 中使用 pnpm 是一个合理的默认设置，而崩溃是使用 Symbol 作为身份标识的后果，这同样合理。这是一个很容易踩进去、且很难从错误信息中诊断出来的尖锐边缘，所以有了这个页面。

测试环境：DSH 0.1.1-rc.2、Node v24.20.0、Linux。

与我合作

本页记录的故障正是我赖以为生的大部分工作：我构建和审计 DeepSeek Harness 插件，并修复因插件安装而已经损坏的 profile。

- Profile 救援——上述 reading 'prepare' 崩溃，诊断并恢复，附带在临时端口上验证过的加固安装方法
- 插件构建——宿主路由加客户端 UI，安全安装，支持回滚
- 插件审计——先给结论，针对固定提交给出 file:line 发现

可接单——在本仓库开一个 issue，或通过我的 GitHub 主页联系我。

实际案例：dsh-cost-bubble（一个实时客户端半插件）和 dsh-daily-progress-tab（一个带 agent 工具的规划器）。

许可证

MIT——见 LICENSE。