🚧 安装过程与问题解决

第 1 步：初次尝试（失败）

cmd

npx @deepseek-ai/dsh web

错误：ERR_MODULE_NOT_FOUND: Cannot find package '@deepseek-ai/cordis-plugin-group'
原因：npx 临时缓存中依赖解析不完整，缺少大量 peer 依赖。

第 2 步：全局安装（部分失败）

cmd

npm install -g @deepseek-ai/dsh

问题：全局安装后 dsh 命令找不到（PATH 未添加），手动添加 PATH 后运行 dsh web 仍报缺失 cordis-plugin-loader 等包，陷入“缺什么补什么”的循环。

教训：该项目依赖数十个内部子包，npm 默认不会自动安装 peer dependencies，手动安装无法穷尽。

---

第 3 步：切换到本地安装 + npx（仍失败）

cmd

cd “你的路径”
npm init -y
npm install @deepseek-ai/dsh --legacy-peer-deps
npx dsh web

新错误：大量 Cannot find package '@deepseek-ai/dsh-xxx'（如 dsh-timeout、dsh-atomic-write 等），覆盖了 50+ 个插件包。

诊断：@deepseek-ai/dsh 是一个 monorepo 项目，其插件系统通过 peer dependencies 引用众多独立包，npm 的扁平安装策略无法正确解析此复杂结构。

---

第 4 步：使用 pnpm 彻底解决依赖问题

pnpm 对 workspace 和 peer 依赖的处理更加完善，且通过 --shamefully-hoist 能模拟 npm 的扁平结构。

cmd

# 清理旧依赖
del package-lock.json
rmdir /s /q node_modules

# 安装 pnpm（全局）
npm install -g pnpm

# 用 pnpm 安装 dsh（关键参数）
npx pnpm add @deepseek-ai/dsh --shamefully-hoist --config.dedupe-peer-dependents=false

遇到的问题：

• pnpm 命令找不到 → 使用 npx pnpm 代替。

• 下载过程中出现大量网络超时警告（error (23)），但 pnpm 自动重试并最终完成所有包下载（523 个包）。

安装结果：所有依赖成功下载，但 pnpm 安全策略默认忽略构建脚本（如 node-pty、koffi 等原生模块的 install 脚本），提示：

text

[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: ...
Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.

---

第 5 步：批准构建脚本，完成原生模块编译

cmd

npx pnpm approve-builds

• 交互界面选择所有包（按 a 全选，然后确认 Yes）。

• 随后运行 pnpm install 以执行这些脚本：

  cmd

  npx pnpm install --shamefully-hoist --config.dedupe-peer-dependents=false

  这次 node-pty、koffi 等原生模块成功编译，无错误。

---

第 6 步：启动 Web 服务（最终成功）

cmd

npx dsh web

输出类似启动日志，并在终端显示访问地址（http://localhost:3080），成功打开 DeepSeek Harness Web 界面。