【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 下直接执行会报错：

head:无法将"head"识别为cmdlet、函数、脚本文件或可运行程序的名称。
所在位置行:1字符:27
+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 $env:PATH += ";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 错误。

解决方案：

# 用 nvm 切换
nvminstall22.19.0
nvmuse22.19.0

# 或直接装最新 LTS
nvminstall24

---

3. pnpm 版本锁定

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

"packageManager":"pnpm@11.7.0"

如果你的全局 pnpm 版本不匹配，可能会遇到 Corepack 警告或依赖解析异常。

解决方案：

corepackenable
corepackpreparepnpm@11.7.0--activate

---

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

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

[PLUGIN_TIMINGS]Yourbuildspentsignificanttimeinplugin`tsdown:deps`
[PLUGIN_TIMINGS]Yourbuildspentsignificanttimeinplugin`dsh-typert-generator`
[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：

"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

npminstall-gwindows-build-tools

---

快速上手 Checklist

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

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

---

总结

今天最痛的坑就是 PowerShell 兼容性。DeepSeek Harness 的脚本和文档默认用户在 Unix-like 环境下工作，Windows 用户需要额外注意 shell 兼容。建议直接用 Git Bash 或 WSL 来操作，省去很多麻烦。

项目本身构建是顺利的，typecheck 和 build 都能一次通过，代码质量很高。