把 DeepSeek Harness 从毛坯房装成精装房

2026年8月25日 606点热度 0人点赞 0条评论

文章目录

一、产品区别
二、环境准备
三、安装 DSH
- 解决 PowerShell 执行策略
四、提前规划数据目录
五、安装插件与踩坑排错
- 🚨 插件依赖安装踩坑警示
- 启动 DSH
六、关于识图
七、架构总结
八、重装系统后的一键恢复
九、常见问题

一、产品区别

先搞清楚：网页版 vs 本地 DSH，区别到底是什么？

很多人（包括我一开始）有个误解：装了 DSH 是不是就在本地跑大模型了？

不是。 DSH 本质是一个本地客户端框架，模型推理仍然在云端：

	DeepSeek 官方网页/App	本地 DSH
程序跑在哪	DeepSeek 公司的服务器	你自己的电脑（Node.js 后端）
数据存在哪	DeepSeek 服务器（对话、上传的文件）	本地硬盘（`C:\Users\xxx\.dsh` 或你指定的目录）
模型选择	只能用 DeepSeek 官方提供的	可接 OpenAI、Claude、Gemini、本地 Ollama 等几十家
系统提示词	不能改	完全自定义
插件/扩展	没有	丰富的社区插件生态
隐私	数据上传给第三方	对话历史本地存储，只有 API 请求发出去

一句话总结：官方是"用别人的软件"，DSH 是"自己搭一个可定制的客户端"。你的 API Key 还是调用 DeepSeek 的模型，但整个交互层在你本地。

二、环境准备

打好便携地基（含 pnpm 避坑）

1. Node.js 便携版

我使用的是便携版 Node.js，解压到：

D:\Program Files\Portable\Nodejs

为什么用便携版？ 重装系统后不需要重新安装，直接设 PATH 就能用。

2. 配置系统环境变量

为了让单用户或重装系统后都不产生权限与路径问题，建议直接写入系统环境变量（Machine）：

# 以管理员身份打开 PowerShell

# 1. 设置系统变量 PNPM_HOME
[Environment]::SetEnvironmentVariable("PNPM_HOME", "D:\Program Files\Portable\Nodejs", "Machine")

# 2. 将 Node.js / PNPM 路径加入系统 PATH
$sysPath = [Environment]::GetEnvironmentVariable("Path", "Machine")
if ($sysPath -notlike "*D:\Program Files\Portable\Nodejs*") {
    [Environment]::SetEnvironmentVariable("Path", "$sysPath;D:\Program Files\Portable\Nodejs", "Machine")
}

3. 配置 pnpm 纯便携化配置文件

默认情况下，pnpm 会自动在 D:\.pnpm-store 或用户根目录下生成乱七八糟的缓存。为了实现彻底便携，我们需要在 Node.js 目录下创建一个配置文件。

在 D:\Program Files\Portable\Nodejs\ 目录下创建一个名为 .npmrc 的文件，写入以下配置（路径统用正斜杠 /，且不加引号）：

store-dir=D:/Program Files/pnpm-store
global-bin-dir=D:/Program Files/Portable/Nodejs
cache-dir=D:/Program Files/Portable/Nodejs/pnpm-cache
state-dir=D:/Program Files/Portable/Nodejs/pnpm-state
registry=https://registry.npmmirror.com/

⚠️ Windows 记事本踩坑提醒：
在 Windows 资源管理器里新建文件时，记事本可能会自动加上隐藏的后缀，变成 .npmrc.txt，导致 pnpm 完全读取不到而依然使用默认配置（pnpm config get store-dir 显示 undefined）。请务必开启 Windows 的“文件扩展名”显示，确保文件名准确为 .npmrc！

三、安装 DSH

千万别用 npx！

我一开始踩的坑：

# ❌ 错误！这是临时运行，跑完就消失
npx @deepseek-ai/dsh web

npx 的作用是临时下载并执行，不会在本地留下 dsh 命令。关闭窗口后，你的配置虽然还在，但程序本体没了，下次打不开。

正确做法：全局安装

npm install -g @deepseek-ai/dsh

如果有以下提示说明npm 默认阻止了这些包的安装脚本执行，而这些脚本往往负责编译原生模块、准备运行环境。如果不执行，dsh 很可能在启动时报错，比如找不到原生绑定、子进程无法创建等。


npm warn allow-scripts 5 packages have install scripts not yet covered by allowScripts:
npm warn allow-scripts @deepseek-ai/dsh-subprocess-local@0.1.1-rc.2 (postinstall: node scripts/ensure-spawn-helper.mjs)
npm warn allow-scripts koffi@3.1.6 (install: node ./cnoke.cjs -P . -D src/koffi --prebuild --release)
npm warn allow-scripts node-pty@1.2.0-beta.15 (install: node scripts/prebuild.js || node-gyp rebuild; postinstall: node scripts/post-install.js)
npm warn allow-scripts @google/genai@1.52.0 (preinstall: echo 'preinstall: no-op')
npm warn allow-scripts protobufjs@7.6.6 (postinstall: node scripts/postinstall)

允许这些脚本重新安装

npm install -g @deepseek-ai/dsh --allow-scripts=@deepseek-ai/dsh-subprocess-local,koffi,node-pty,@google/genai,protobufjs/code>

装完后会在 D:\Program Files\Portable\Nodejs\ 下生成 dsh.cmd，以后任何位置直接打 dsh 就能用。

解决 PowerShell 执行策略

如果报错"无法加载文件...因为在此系统上禁止运行脚本"：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

四、提前规划数据目录

这是本文最核心的经验。

DSH 默认把数据存在 C:\Users\<用户名>\.dsh。但这里有两个问题：

系统重装会清空 C 盘
pnpm 使用大量符号链接（symlink），普通复制工具（如 robocopy）会把它"展开"成真实文件夹，导致 DSH 启动时连环报错

正确顺序：先建目录、设环境变量，再装插件。

# 1. 创建 D 盘数据目录
New-Item -ItemType Directory -Path "D:\AppData\.dsh" -Force
New-Item -ItemType Directory -Path "D:\AppData\.codex" -Force

# 2. 设置 DSH_HOME 系统环境变量（永久）
[Environment]::SetEnvironmentVariable("DSH_HOME", "D:\AppData\.dsh", "Machine")
$env:DSH_HOME = "D:\AppData\.dsh"

# 3. Codex 桌面版不支持环境变量，只能建 Junction（目录联接）
cmd /c mklink /J "C:\Users\$env:USERNAME\.codex" "D:\AppData\.codex"

为什么 Codex 用 Junction，DSH 用环境变量？

DSH 官方原生支持 DSH_HOME，直接改读取路径，最干净

Codex Windows 桌面版硬编码读取 %USERPROFILE%\.codex，不支持环境变量，只能用 Junction 做透明转发

五、安装插件与踩坑排错

DSH 官方只提供核心框架，所有功能扩展都来自社区插件。以下是我筛选后的"最小必要集"：

插件	功能	安装命令
`dshmarket`	可视化插件市场，以后装插件不用敲命令	`dsh plugin --profile web add dshmarket`
`@liustack/modlens`	视觉识图，支持 15+ 视觉引擎	`dsh plugin --profile web add @liustack/modlens`
`@liustack/modsearch`	联网搜索，补上没有实时信息的短板	`dsh plugin --profile web add @liustack/modsearch`
`dsh-at-file`	输入 `@` 引用工作区文件	`dsh plugin --profile web add github:omdsh-dev/dsh-at-file`
`@linxin666/dsh-web-ui-all`	UI 全家桶（任务看板、SSH 面板、皮肤中心、Git 图谱等）	`dsh plugin --profile web add @linxin666/dsh-web-all@latest`
`dsh-notification`	桌面通知，长任务跑完自动提醒	`dsh plugin --profile web add github:omdsh-dev/dsh-notification`
`dsh-custom-tool`	自定义 JS 工具，Agent 可直接调用	`dsh plugin --profile web add github:omdsh-dev/dsh-custom-tool`
`dsh-annotation`	文本批注，选中段落让 AI 逐条修改	`dsh plugin --profile web add github:omdsh-dev/dsh-annotation`

重要提醒：这些插件全部来自社区（liustack、linxin666、omdsh-dev 等），不是 DeepSeek 官方维护。你的 API Key 会流经这些插件调用的第三方服务，请自行评估信任度。

🚨 插件依赖安装踩坑警示

在执行插件依赖安装时，可能会遭遇以下三个经典坑：

坑 1：node_modules/cpu-features 编译报错

安装过程终端输出：Running install script, failed in 2.7s (skipped as optional)。
不用担心！ cpu-features 是原生的 C++ 扩展，Windows 上缺乏 MSVC 编译环境就会失败。由于标注了 (skipped as optional)，pnpm 会自动忽略并降级，完全不影响 DSH 功能。

坑 2 pnpm 安全策略拦截依赖脚本

[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts:
cloudflared@0.7.3,
cpu-features@0.0.10,
node-pty@1.1.0,
ssh2@1.17.0

pnpm 11.24.0 的安全策略拦截了依赖的 build/install 脚本，所以虽然包装得差不多了，dsh 还是把安装判定为失败。pnpm 11 默认不会让未批准的依赖随便执行安装脚本；官方推荐通过 pnpm approve-builds 或 allowBuilds 明确放行。

解决办法：

cd D:\AppData\.dsh\profiles\web
pnpm approve-builds

如果你信任这个插件及这些依赖，就把这 4 个全部选中批准，然后确认。

或者直接执行

cd D:\AppData\.dsh\profiles\web
pnpm approve-builds cloudflared cpu-features node-pty ssh2
dsh plugin --profile web install

坑 3：cloudflared: Running postinstall script... 无限卡死

`cloudflared` 的 postinstall 脚本需要去 GitHub Releases 下载 `cloudflared.exe`，由于网络问题极易无响应卡死十几分钟。
解决方法：

在 PowerShell 中按 Ctrl + C 终止当前命令。
手动去 GitHub 下载 Windows 64 位的 cloudflared.exe，直接丢进 D:\Program Files\Portable\Nodejs\ 目录下（因为该目录已在 Path 中，全局可调用）。
在 PowerShell 注入跳过环境变量，重新运行即可秒过安装：
```
$env:CLOUDFLARED_INSTALL_SKIP="1"
dsh plugin --profile web install
```

启动 DSH

dsh web

浏览器自动打开 http://127.0.0.1:3080，在设置页里填入你的 API Key 即可开始使用。

六、关于识图

为什么 DeepSeek API 不够？

DeepSeek 官方 API（V3/R1）是纯文本模型，本身不能直接读图片。

你装的 modlens 识图时，不是调用 DeepSeek 官方 API，而是调用你配置的其他视觉模型：

Google Gemini（有免费额度）
Claude 3.5 Sonnet
OpenRouter（聚合平台，一个 Key 通吃多家）
硅基流动（SiliconFlow，国内稳定）
本地 Ollama + llava 模型

流程是：你贴图 → 视觉插件把图发给 Gemini/Claude → 拿到文字描述 → 再把描述 + 你的问题一起发给 DeepSeek 回答。

所以你需要至少两个 Key：一个 DeepSeek（对话），一个视觉模型（识图）。

七、架构总结

最终我的环境架构如下：

组件	位置	机制
Node.js + DSH 本体	`D:\Program Files\Portable\Nodejs`	便携版，含全局 bin 及 `.npmrc` 配置文件
DSH 数据/配置/插件	`D:\AppData\.dsh`	`DSH_HOME` 系统环境变量
Codex 数据	`D:\AppData\.codex`	Junction → `C:\Users\...\.codex`
pnpm 包仓库	`D:\Program Files\pnpm-store`	`.npmrc` 配置文件中的 `store-dir` 定义

八、重装系统后的一键恢复

因为所有配置和配置文件都在 D 盘，重装系统后只需运行下面这个简洁的 PowerShell 恢复脚本：

#requires -RunAsAdministrator
<# .SYNOPSIS DSH + Codex + Node.js/pnpm 重装系统后一键恢复脚本 #>

param(
    [switch]$CheckOnly   # 只输出清单，不执行任何操作
)

# ========== 配置区 ==========
$NodeJsPath      = "D:\Program Files\Portable\Nodejs"
$DshDataPath     = "D:\AppData\.dsh"
$CodexDataPath   = "D:\AppData\.codex"
$PnpmStorePath   = "D:\Program Files\pnpm-store"
$ExpectedUser    = "nicky"

# ========== 检测当前用户 ==========
$CurrentUser = $env:USERNAME
$IsDifferentUser = ($CurrentUser -ne $ExpectedUser)

# ========== 检查模式 ==========
if ($CheckOnly -or $IsDifferentUser) {
    if ($IsDifferentUser) {
        Write-Host "⚠️ 检测到用户名不一致，请手动检查路径！" -ForegroundColor Yellow
        exit 0
    }
}

# ========== 执行恢复 ==========
Write-Host "`n开始恢复系统环境..." -ForegroundColor Green

# 1. 校验 D 盘关键目录
$checks = @{
    "Node.js"    = $NodeJsPath
    "DSH 数据"   = $DshDataPath
    "Codex 数据" = $CodexDataPath
    "pnpm store" = $PnpmStorePath
}

foreach ($name in $checks.Keys) {
    $path = $checks[$name]
    if (-not (Test-Path $path)) {
        Write-Host "❌ $name 路径不存在: $path" -ForegroundColor Red
        exit 1
    }
}
Write-Host "✅ D 盘数据完整性检查通过" -ForegroundColor Green

# 2. 设置系统环境变量 (Machine 级别)
Write-Host "`n[1/3] 配置系统环境变量 (System)..." -ForegroundColor Cyan
[Environment]::SetEnvironmentVariable("DSH_HOME", $DshDataPath, "Machine")
[Environment]::SetEnvironmentVariable("PNPM_HOME", $NodeJsPath, "Machine")
Write-Host "   DSH_HOME  = $DshDataPath" -ForegroundColor Green
Write-Host "   PNPM_HOME = $NodeJsPath" -ForegroundColor Green

# 3. 追加 Node.js 到系统 Path (Machine 级别)
Write-Host "`n[2/3] 添加 Node.js 到系统 Path..." -ForegroundColor Cyan
$sysPath = [Environment]::GetEnvironmentVariable("Path", "Machine")
if ($sysPath -notlike "*$NodeJsPath*") {
    [Environment]::SetEnvironmentVariable("Path", "$sysPath;$NodeJsPath", "Machine")
    Write-Host "   系统 Path 已追加: $NodeJsPath" -ForegroundColor Green
} else {
    Write-Host "   系统 Path 已存在，跳过" -ForegroundColor Yellow
}

# 4. 重建 Codex Junction
Write-Host "`n[3/3] 创建 Codex 目录 Junction..." -ForegroundColor Cyan
$codexJunction = "C:\Users\$CurrentUser\.codex"
if (Test-Path $codexJunction) {
    $item = Get-Item $codexJunction
    if (-not ($item.Attributes -match "ReparsePoint")) {
        Remove-Item $codexJunction -Recurse -Force
        cmd /c mklink /J "$codexJunction" "$CodexDataPath" >$null
        Write-Host "   Junction 已更新" -ForegroundColor Green
    } else {
        Write-Host "   Junction 已存在，跳过" -ForegroundColor Yellow
    }
} else {
    cmd /c mklink /J "$codexJunction" "$CodexDataPath" >$null
    Write-Host "   Junction 已创建" -ForegroundColor Green
}

# ========== 完成提示 ==========
Write-Host "`n========================================" -ForegroundColor Green
Write-Host "  恢复完成！重新打开终端即可运行 'dsh web'" -ForegroundColor Green
Write-Host "========================================" -ForegroundColor Green

九、常见问题

Q：DSH 关闭 PowerShell 窗口后还能用吗？
A：不能。dsh web 启动的是本地后端服务器，关闭窗口等于关机。如需后台运行，可使用 pm2 等进程守护工具。

Q：Codex 的 .codex 文件夹为什么不用 CODEX_HOME 环境变量？
A：Codex CLI 支持 CODEX_HOME，但 Windows 桌面版硬编码读取 %USERPROFILE%\.codex，不支持环境变量，只能用 Junction。

Q：pnpm store 可以删掉吗？
A：不可以。它是 pnpm 的"中央仓库"，DSH 的插件通过硬链接引用这里的包。删掉后插件会全部失效。

Q：为什么一开始不能用 robocopy 直接复制 .dsh？
A：pnpm 的 node_modules 包含大量符号链接，robocopy 默认会把它"展开"成真实文件夹。DSH 启动时检查发现 symlink 变成了真实文件夹，就会报错。正确做法是设 DSH_HOME 让 DSH 自己去 D 盘读写，或者复制时加 /SL 参数保留链接。

本文基于 DeepSeek Harness 实际配置经验整理，环境为 Windows 11。