常见问题排查

DeepSeek Harness 安装与运行中的常见问题，修复方法基于官方 CLI 参考与文档（2026-08-13 核实）。给出的都是可以直接复制的命令——没有猜测。

安装失败

npx 之后提示「命令找不到」

npx 按需下载包，但不会全局安装 dsh 命令。每次直接重跑 npx @deepseek-ai/dsh web（npx 每次都会解析），或者想获得常驻的 dsh 命令就全局安装：

npx 缓存过期

预览版迭代很快，缓存副本可能显得过时或与文档不匹配。清掉 npx 缓存再试：

网络 / 镜像问题（中国大陆）

• 把 npm 切到镜像：npm config set registry https://registry.npmmirror.com（pnpm 同理）。
• 如果需要代理，确保运行 npx 的 shell 里设置了 HTTP_PROXY/HTTPS_PROXY。

Node.js 版本过旧

DSH 要求 Node.js ≥ 18（建议 LTS）。检查并升级：

启动与端口问题

3080 端口被占用

Web UI 默认服务在 http://127.0.0.1:3080。如果端口被其他进程占用，web 应用支持 --port 参数——启动器会在自己的标志之后透传应用参数：

web profile 还支持可重复的 --trusted-host 参数。

「Profile not found」报错

只有 web 和 headless 会在首次使用时从内置模板自动初始化。其他 profile 名称会响亮地失败并给出提示：

Windows

• PowerShell 执行策略——脚本被阻止时运行 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned（或改用 cmd）。
• 路径含空格——给带空格的路径加引号：dsh --patch "C:\My Plugins\cordis.yml"。
• Windows 启动器——社区有 dsh-launcher-windows；请视其为外部工具（无 dsh manifest，dsh.so 未验证）。

配置与插件调试

不启动就查看组合后的配置树

精确看到你的机器会加载什么——每一行及其来源文件：

--dump-default-config 只打印 bundle 层；--dump-config 会加上 profile 的 cordis.patch.yml、home 级 $DSH_HOME/cordis.patch.yml 与 --patch 覆盖层。未匹配的 patch 目标会打印到 stderr——这是「我的插件没生效」的常见原因。

插件没生效

• 绝对路径——本地 --patch 行引用源码文件时必须是绝对路径；相对路径会相对 profile 目录解析，而不是你的当前目录。
• 名称解析——bundle 行按包名引用包；如果是从 git 安装且没有 prepare 构建，lib/ 产物可能缺失（见插件开发）。
• 配置是替换不是合并——后应用的 patch 会替换整行 config 值；要重述所有键，而不只是改动的那个。

headless 任务退出码 1

dsh --profile headless "run the tests" 打印最终的 assistant 文本，completed 时退出 0，否则退出 1。退出码 1 表示任务未达到完成状态——检查会话日志或用更明确的指令重跑。

在哪里求助

• 官方 GitHub Discussions——项目规范的支持渠道（不使用 issues）。
• 官方 Discord 社区。
• dsh.so 插件注册表找插件，更新日志看版本变化。