【agent】DeepSeek Harness 安装踩坑记录

日期: 2026-08-14 版本: v0.1.0-rc.5 环境: Windows 11 + PowerShell 5.1

1. PowerShell 不兼容 Unix 命令

这是今天踩到的最大的坑。
DeepSeek Harness 的脚本（包罗 README 里的一些示例命令）大量使用了 Unix 管道命令，比如 head、tail、grep、sed 等。在 PowerShell 5.1 下直接执行会报错：

1. head:无法将"head"识别为cmdlet、函数、脚本文件或可运行程序的名称。
2. 所在位置行:1字符:27
3. +pnpmruntypecheck2>&1|head-50

复制代码

根本原因： PowerShell 5.1 是 Windows 原生 shell，不包含任何 Unix 工具。纵然安装了 Git for Windows（自带 Git Bash），这些工具也不会主动加入 PowerShell 的 PATH。
解决方案：

• 方案 A：使用 Git Bash 或 WSL 执行命令（推荐） bash # 在 Git Bash 中 pnpm run typecheck 2>&1 | head -50
  
• 方案 B：使用 PowerShell 原生替代语法 ```powershell # 替代 head -50 pnpm run typecheck 2>&1 | Select-Object -First 50
  

# 替代 tail -20 Get-Content .\some-file.log -Tail 20
# 替代 grep "error" pnpm run typecheck 2>&1 | Select-String "error" ```

• 方案 C：将 Git Bash 工具加入 PATH powershell # 将 Git\usr\bin 加入系统 PATH $envATH += ";C:\Program Files\Git\usr\bin" # 永久生效需写入系统环境变量
  

2. Node.js 版本要求严格

项目要求 node ^22.19.0 || >=24.0.0，这意味着：

• Node 18 ❌
  
• Node 20 ❌
  
• Node 22.0 ~ 22.18 ❌
  
• Node 22.19+ ✅
  
• Node 24+ ✅
  

假如版本不对，pnpm install 会直接报 ERR_ENGINES 错误。
解决方案：

1. # 用 nvm 切换
2. nvminstall22.19.0
3. nvmuse22.19.0
5. # 或直接装最新 LTS
6. nvminstall24

复制代码

3. pnpm 版本锁定

项目通过 packageManager 字段锁定了 pnpm 11.7.0：

1. "packageManager":"[email protected]"

复制代码

假如你的全局 pnpm 版本不匹配，可能会碰到 Corepack 警告或依赖剖析异常。
解决方案：

1. corepackenable
2. [email protected]

复制代码

4. 初次构建耗时长 + 大量 PLUGIN_TIMINGS 警告

pnpm run build 需要编译 100+ 个包，初次构建约 35-40 秒。期间会输出大量黄色警告：

1. [PLUGIN_TIMINGS]Yourbuildspentsignificanttimeinplugin`tsdown:deps`
2. [PLUGIN_TIMINGS]Yourbuildspentsignificanttimeinplugin`dsh-typert-generator`
3. [PLUGIN_TIMINGS]Yourbuildspentsignificanttimeinplugin`tsdown:shebang`

复制代码

这些不是错误，可以安全忽略。 只是 tsdown 构建插件的性能提示。
5. TypeScript 6 版本兼容

项目使用 TypeScript 6（^6.0.3），假如你的 VS Code 内置的是 TS 5.x，编辑器可能会显示类型错误，但实际 pnpm run typecheck 是通过的。
解决方案：
VS Code 底部状态栏点击 TypeScript 版本号 → 选择 Use Workspace Version。
6. ESM-only 架构注意事项

项目全面使用 ESM（"type": "module"）。这意味着：

• 不支持 require()，必须用 import
  
• 文件扩展名在某些场景下是必须的（.js、.mjs）
  
• 一些 CommonJS 的工具可能需要额外配置
  

CLI 的启动方式也是 ESM：

1. "dsh":"node --import tsx/esm apps/cli/src/bin.ts"

复制代码

7. 原生插件 landlock-run

native/landlock-run 是一个 C++ 原生插件。在 Windows 上编译需要：

• Python 3
  
• Visual Studio Build Tools（C++ 桌面开发工作负载）
  
• 或者 Windows Build Tools
  

1. npminstall-gwindows-build-tools

复制代码

快速上手 Checklist

1. ✅ Node.js >= 22.19.0 或 >= 24
2. ✅ pnpm 11.7.0（corepack enable）
3. ✅ Git Bash 或 WSL（避免 PowerShell 兼容问题）
4. ✅ TypeScript 使用 Workspace 版本
5. ✅ 忽略 PLUGIN_TIMINGS 警告
6. ✅ 配置 DEEPSEEK_API_KEY（.env 文件）

复制代码

1. gitclonehttps://github.com/deepseek-ai/deepseek-harness.git
2. cddeepseek-harness
3. pnpminstall
4. pnpmrunbuild
5. pnpmdshweb# 启动 Web UI → http://127.0.0.1:3080

复制代码

总结

今天最痛的坑就是 PowerShell 兼容性。DeepSeek Harness 的脚本和文档默认用户在 Unix-like 环境下工作，Windows 用户需要额外注意 shell 兼容。建议直接用 Git Bash 或 WSL 来操作，省去很多麻烦。
项目本身构建是顺利的，typecheck 和 build 都能一次通过，代码质量很高。