DeepSeek Harness 排障：12 个常见错误
12 个来自 DeepSeek Harness GitHub Discussions 的真实错误，逐条给出根因、修复方式和原帖链接，覆盖 Windows、Linux 与配置类问题。
DeepSeek Harness（dsh）没有公开的 issue 追踪系统——官方仓库禁用了 GitHub Issues,README 把用户指向了 GitHub Discussions。这意味着关于真实问题和修复方式最可靠的记录,活在 Discussions 帖子里,而不是某份精心编写的 FAQ 里。下面这 12 个问题直接取自这些讨论帖,附上每一个的真实根因和最终解法。
为什么这份清单长这样
针对 deepseek-ai/deepseek-harness 执行 gh issue list 会返回"the repository has disabled issues",API 也确认了 has_issues: false。这个项目唯一的官方反馈渠道是 GitHub Discussions(分 Q&A、General、Ideas、Show Your Plugins! 四个分类)以及 README 里链接的一个 Discord 社区。如果你碰到的问题不在这里,该去 Discussions 搜索或提问,而不是去找 Issues。
12 个错误
| # | 症状 | 根因 | 修复 | 来源 |
|---|---|---|---|---|
| 1 | Arch Linux 上 npx @deepseek-ai/dsh web 报错,插件树加载失败,指向 node-pty | npm 不信任 node-pty 的安装脚本运行自己的编译步骤 | 改用 bun add --global @deepseek-ai/dsh(bun 默认信任它),或手动执行 npm install -g node-pty 并在重试前清空 ~/.npm/_npx | Discussion #49 |
| 2 | dsh web --host 0.0.0.0 报错 | 不是 bug——官方文档明确表示这是"出于安全考虑暂时有意不支持",因为这会把远程代码执行能力暴露到网络上 | 使用 127.0.0.1(默认值);如果需要远程访问,在前面套一层你自己带鉴权的反向代理或隧道,而不是绑定到所有网卡 | Discussion #76 |
| 3 | 全局安装(pnpm add -g @deepseek-ai/dsh)后,dsh --profile headless --help 崩溃,报 Cannot find package '@deepseek-ai/cordis-plugin-timer' | 在 Windows 11 + Node 24 + pnpm 11.9 上复现;指向依赖树解析的一个缺口 | 社区反馈在后续安装中已解决,但截至撰稿时未见公开的补丁细节确认——如果你碰到这个问题,先试着用当前版本的 pnpm 干净重装一次 | Discussion #55 |
| 4 | Windows 下"添加工作区"报错 directory picker failed: win32 folder dialog worker exited before reporting a result | 原生目录选择器依赖 koffi 原生绑定,而它安装失败 | (1)用 npm i -g @deepseek-ai/dsh --ignore-scripts --registry=https://registry.npmjs.org 重装,跳过导致崩溃的脚本;(2)编辑 ~/.dsh/profiles/web/cordis.patch.yml,禁用原生/自动目录选择器,改插入 directory-picker-browse 及其配套的客户端 UI 包 | Discussion #30 |
| 5 | npx @deepseek-ai/dsh web 报错 The requested module 'node:zlib' does not provide an export named 'createZstdDecompress' | Node 版本过低(createZstdDecompress 需要 Node ≥22.15;dsh 目标是 22.19+/24+) | 升级 Node 到受支持的版本 | Discussion #100 |
| 6 | dsh 每次启动都打印 failed to load .env: EISDIR | 工作目录下存在一个名叫 .env 的目录(而不是文件);两处独立的 .env 加载逻辑读取路径前都没有先判断它是不是一个普通文件 | 官方已确认是 bug,并给出了已知的复现 commit;修复前可先把 .env 目录重命名或删除作为临时规避方案 | Discussion #71 |
| 7 | 从源码执行 pnpm run build 失败,报 [ELIFECYCLE] Command failed with exit code 1 | build 脚本内部混用了 npm run 和 pnpm 调用,与 README 描述的纯 pnpm 工作流冲突 | 官方不支持其他包管理器——从头到尾只用 pnpm,不要混用 npm 和 pnpm 调用 | Discussion #86 |
| 8 | 自定义视觉模型(Claude/GPT 系列)无法处理图片——"无法识别图片" | 自定义 provider 在 settings.yaml 里的模型条目没有声明 input: [text, image];未声明的模型会被当作纯文本处理,附图在请求发出前就被拒绝了 | 给模型定义加上 input 字段(对内置目录 provider 则用 modelOverrides) | Discussion #112 |
| 9 | "我想要长期记忆能力" | dsh 没有内置的记忆能力——这是仓库里讨论最热烈的开放 Idea | 没有官方修复;社区路径是接入第三方 MCP memory server(参见官方的 examples/mcp-memory/ 参考配置)或使用一个专注记忆的插件 | Discussion #14 |
| 10 | 第一次安装 GitHub 来源的插件就立刻因构建权限报错而失败 | pnpm 10+ 默认拦截 git 依赖上的 prepare 脚本执行 | 在 profile 的 pnpm-workspace.yaml 里给该包加上 allowBuilds: true——完整流程见我们专门的GitHub 安装指南 | apps/cli/reference/README.md,"Plugin management" |
| 11 | 归档后的会话无法查看或恢复 | 截至本报告撰写时,官方文档中未找到关于恢复归档会话的设计说明 | 在文档明确说明之前,把归档当作事实上不可逆的操作;不要依赖它作为一个可恢复的状态 | Discussion #40 |
| 12 | Windows 上选择工作区时,中文路径被截断或不被支持 | 两份独立报告都反映了 Windows 特有的、针对非 ASCII(中文)路径名的路径处理 bug | 截至撰稿时未见官方修复确认;如果你碰到这个问题,在 Windows 上尽量避免工作区路径含非 ASCII 字符 | Discussion #47、Discussion #107 |
你最有可能碰到的两个
#2(host 0.0.0.0)和 #10(allowBuilds) 出现得最频繁,因为它们本质上不是 bug——是有意为之的摩擦。--host 0.0.0.0 的限制存在,是因为 dsh 的 Web UI 一旦能被网络访问,就等同于把远程代码执行能力当成服务暴露出去;没有任何配置开关能安全绕过这一点,唯一的办法是在前面做好正确的网络隔离(带自己鉴权的反向代理、VPN、SSH 隧道)。allowBuilds 提示的存在,是因为安装一个插件会在你机器上执行代码,pnpm 10+ 不会悄悄地就这么做。如果你是在团队场景下运行 dsh,这两点都值得在我们团队环境下运行 DeepSeek Harness这篇里深入了解。
如果这里没有你要的修法
这份清单具体取自截至 2026 年 8 月的 dsh-tutorial-facts 调研。因为 dsh 处于活跃的开发预览期、发版频繁,又没有正式的 changelog,新问题冒出来(旧问题被修复)的速度,比任何一篇文章能追踪的都快。如果你的错误不在上面:
- 直接搜索 GitHub Discussions——这些修法本来就来自这里。
- 确认一下这具体是不是一个插件安装问题,而不是运行时问题——见我们范围更窄的插件安装错误与修复指南,更详细地覆盖了 pnpm 找不到、
allowBuilds、缺失构建产物这几类。 - 运行
dsh --profile <name> --dump-config,先排除是不是某层配置补丁写错了,再假设这是 dsh 的 bug。
FAQ
我该去哪里真正上报一个新 bug？
去 GitHub Discussions,不是 Issues——官方仓库禁用了 Issues(has_issues: false)。README 里还链接了一个 Discord 社区作为次要渠道。
dsh 的版本足够稳定,能保证这些修法一直准确吗？
dsh 明确处于开发预览期,没有 SemVer 承诺,也没有 GitHub Releases;README 直白地写着会有破坏性变更。上面每一条修法都以截至 2026 年 8 月为准,如果你用的是更新的版本,建议对照当前的 Discussions 再核实一遍。
为什么 .env 是目录会搞崩 dsh(#6）？
两处独立加载 .env 文件的代码路径,在读取之前都没有检查这个路径是不是一个普通文件,所以一个意外命名为 .env 的目录会触发 Node 的 EISDIR 错误。这是一个已确认、有已知复现方式的 bug,不是用户的操作失误。
有官方的 Windows 专属安装指南吗？
官方没有一份统一整合的指南——上面提到的 Windows 特有问题(目录选择器、中文路径、headless 崩溃)全部分别来自各自独立的 Discussions 帖子,而不是一份统一的排障页。
这篇文章和插件安装错误指南有什么区别？
这一篇覆盖的是 dsh 本身——启动、环境和平台问题。插件安装错误与修复范围更窄,专门针对 dsh plugin add、update、remove 内部具体的失败情形。
下一步
关于插件安装本身的失败,见DeepSeek Harness 插件安装错误与修复。专门针对 GitHub 安装路径,从 GitHub 安装插件详细讲了 allowBuilds。如果你是为团队而不是自己配置 dsh,团队环境下运行 DeepSeek Harness讲了在那个规模下重要的 --host 限制以及沙箱/遥测配置。