DeepSeek Harness 傻瓜式部署技能
本技能为 deepseek-harness 项目提供一键式、零配置的部署方案。智能体按照下述流程顺序执行即可完成：下载 ZIP → 解压 → 镜像源安装依赖 → 构建启动，全程无需用户手动干预。
📋 环境前置要求
在开始前，智能体必须用 Shell 工具检测以下环境。缺失项需要自动安装或引导用户安装。
| 依赖 | 最低版本 | 检测命令 | 缺失时处理 |
|---|---|---|---|
| Node.js | v22.19.0 或 v24+ | node --version |
调用 install-node.ps1 自动安装 |
| pnpm | 11.7.0 | pnpm --version |
npm install -g pnpm@11.7.0 |
| PowerShell | 5.1+ | $PSVersionTable.PSVersion |
Windows 自带，无需处理 |
| 磁盘空间 | ≥ 2GB | Get-PSDrive C |
提示用户清理 |
> 操作系统支持：Windows 10/11、macOS、Linux 均可。本技能默认在 Windows PowerShell 下执行；如检测到非 Windows 环境，自动改用 bash 语法。
🚀 完整部署流程（按顺序执行）
步骤 1：创建工作目录
$deployRoot = "e:\360MoveData\Users\lenovo\Desktop\部署文档\deepseek-harness"
New-Item -ItemType Directory -Force -Path $deployRoot | Out-Null
Set-Location $deployRoot
步骤 2：下载项目 ZIP
下载地址（华为云 OBS 预签名链接，有效期至 2026-08-20，过期后需向用户申请新链接）：
https://obs.cn-north-4.myhuaweicloud.com/gitcode-repo-archive-bj/cf7fde2a7d0e9bed3bafd4372409a744242e1c59f0fdcfbe975668722211e28e10593198.zip?AWSAccessKeyId=X364SUL65RWWOYRBZEMU&Expires=1787192935&response-content-disposition=attachment%3Bfilename%3D%22deepseek-harness-master.zip%22&Signature=%2FV33RhkLjGwJ92E%2BZ6hQOUhNH1I%3D
执行下载（使用 Invoke-WebRequest，超时 10 分钟）：
$zipUrl = "https://obs.cn-north-4.myhuaweicloud.com/gitcode-repo-archive-bj/cf7fde2a7d0e9bed3bafd4372409a744242e1c59f0fdcfbe975668722211e28e10593198.zip?AWSAccessKeyId=X364SUL65RWWOYRBZEMU&Expires=1787192935&response-content-disposition=attachment%3Bfilename%3D%22deepseek-harness-master.zip%22&Signature=%2FV33RhkLjGwJ92E%2BZ6hQOUhNH1I%3D"
$zipPath = Join-Path $deployRoot "deepseek-harness-master.zip"
Write-Host "⬇️ 正在下载项目 ZIP 包..."
Invoke-WebRequest -Uri $zipUrl -OutFile $zipPath -TimeoutSec 600 -UseBasicParsing
Write-Host "✅ 下载完成：$zipPath"
> 若链接已过期：智能体应提示用户从 GitHub releases 重新获取：https://github.com/deepseek-ai/deepseek-harness/archive/refs/heads/master.zip
步骤 3：解压项目
Write-Host "📦 正在解压..."
Expand-Archive -Path $zipPath -DestinationPath $deployRoot -Force
# ZIP 内根目录名为 deepseek-harness-master，如已存在则合并
if (Test-Path (Join-Path $deployRoot "deepseek-harness-master")) {
# 若目标 deepseek-harness 目录已存在，先备份再移动
if (Test-Path (Join-Path $deployRoot "deepseek-harness")) {
Rename-Item (Join-Path $deployRoot "deepseek-harness") "deepseek-harness.bak.$(Get-Date -Format 'yyyyMMddHHmmss')"
}
Move-Item (Join-Path $deployRoot "deepseek-harness-master") (Join-Path $deployRoot "deepseek-harness") -Force
}
Set-Location (Join-Path $deployRoot "deepseek-harness")
Write-Host "✅ 解压完成，已进入项目目录"
步骤 4：配置阿里云镜像源
关键步骤：使用阿里云 npm 镜像源加速依赖下载（国内速度比默认源快 10 倍以上）。
Write-Host "🔧 配置阿里云镜像源..."
pnpm config set registry https://registry.npmmirror.com
# 同时配置 Node.js 原生镜像（node-sass / esbuild 等原生模块下载加速）
pnpm config set node-mirror https://npmmirror.com/mirrors/node/
npm config set registry https://registry.npmmirror.com
# 设置 electron 镜像（如果项目用到）
$env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"
Write-Host "✅ 镜像源已配置为阿里云 npmmirror"
步骤 5：配置 pnpm store 到项目目录（避免沙箱权限问题）
> 经验教训：默认 pnpm store 在系统目录可能触发沙箱权限错误（ERR_SQLITE_ERROR: disk I/O error），必须配置到项目内。
Write-Host "📁 配置 pnpm store 到项目目录..."
pnpm config set store-dir "$(Get-Location)\.pnpm-store"
Write-Host "✅ pnpm store: $(Get-Location)\.pnpm-store"
步骤 6：安装依赖
Write-Host "📥 安装项目依赖（这可能需要 3-10 分钟）..."
pnpm install --frozen-lockfile 2>&1 | Tee-Object -Variable installLog
if ($LASTEXITCODE -ne 0) {
Write-Host "⚠️ frozen-lockfile 失败，尝试普通安装..."
pnpm install 2>&1 | Tee-Object -Variable installLog
}
Write-Host "✅ 依赖安装完成"
安装耗时参考：约 3-5 分钟（923 个包），下载量约 400MB。
步骤 7：构建 Host 端库
Write-Host "🏗️ 构建 Host 端库（TypeScript 编译 + tsdown 打包）..."
pnpm run build:lib:host 2>&1 | Tee-Object -Variable buildLog
if ($LASTEXITCODE -ne 0) {
Write-Host "❌ 构建失败，查看日志：$buildLog"
exit 1
}
Write-Host "✅ Host 端库构建完成"
构建耗时参考：约 30-60 秒（取决于 CPU 性能）。
步骤 8：启动 Web 应用
Write-Host "🚀 启动 Web 应用..."
# 在后台启动，避免阻塞
$webPort = 3081
$webHost = "127.0.0.1"
Start-Process -FilePath "pnpm" -ArgumentList "run", "dsh", "web", "--port", $webPort, "--host", $webHost -NoNewWindow -PassThru | Out-Null
Start-Sleep -Seconds 10
Write-Host "✅ Web 应用已启动"
Write-Host "🌐 访问地址: http://$webHost`:$webPort"
步骤 9：验证部署
Write-Host "🔍 验证服务可用性..."
try {
$response = Invoke-WebRequest -Uri "http://127.0.0.1:3081" -UseBasicParsing -TimeoutSec 10
if ($response.StatusCode -eq 200) {
Write-Host "✅ 部署成功！Web 服务响应正常"
Write-Host "🌐 请在浏览器打开: http://127.0.0.1:3081"
}
} catch {
Write-Host "⚠️ 服务可能仍在启动中，请等待 30 秒后重试访问"
}
🛠️ 智能体执行规范
- 顺序执行：必须严格按步骤 1→9 顺序执行，前一步失败时按下方"故障处理表"修复后重试，不可跳过。
- 进度反馈：每完成一步，向用户输出
✅ 步骤 N 完成形式的进度。 - 超时处理：下载和安装命令必须设置超时（下载 10 分钟、安装 15 分钟），超时后报告而非卡死。
- 日志保存：安装和构建日志应通过
Tee-Object保存到变量，便于失败时分析。 - 幂等性：每一步都必须可重复执行（目录存在则跳过/备份，文件存在则覆盖）。
🚨 故障处理表（智能体内置知识）
遇到错误时，智能体必须按下表匹配错误特征并执行对应解决方案，不可直接报告失败。
错误 1：ERR_SQLITE_ERROR: disk I/O error
原因：pnpm store 在系统目录被沙箱拦截。
解决方案：执行步骤 5（配置 store 到项目内）后重试安装。
错误 2：EPERM: operation not permitted 或 EACCES
原因：文件权限不足。
解决方案：
1. 关闭可能锁文件的程序（VSCode、杀毒软件）。
2. 以管理员身份运行 PowerShell。
3. 执行 pnpm store prune 清理后重试。
错误 3：ERR_PNPM_OUTDATED_LOCKFILE
原因：lockfile 与 package.json 不同步。
解决方案：去掉 --frozen-lockfile 参数，使用 pnpm install 重新生成。
错误 4：Unsupported platform: wanted {"cpu":["arm64"],"os":["linux"]}
原因：跨平台原生模块警告（linux-arm64 包在 Windows 上无法安装）。
解决方案：这是 WARN 不是 ERROR，可安全忽略，安装会继续。
错误 5：Failed to create bin at ...dsh-acp-demo
原因：demo 包需要先 build 才有 lib/bin.js。
解决方案：这是 WARN 不是 ERROR，不影响主项目运行，可安全忽略。
错误 6：Node.js 版本不满足 ^22.19.0 || >=24.0.0
原因：Node.js 版本过低。
解决方案：调用 install-node.ps1 安装 Node.js v24 LTS。
错误 7：pnpm : 无法将"pnpm"项识别为 cmdlet
原因：pnpm 未安装或未加入 PATH。
解决方案：执行 npm install -g pnpm@11.7.0，然后重启 PowerShell。
错误 8：下载 ZIP 失败（403 Forbidden 或连接超时）
原因：预签名链接过期或网络问题。
解决方案：
1. 先重试 2 次。
2. 仍失败则改用 GitHub 直接下载：https://github.com/deepseek-ai/deepseek-harness/archive/refs/heads/master.zip
3. 若 GitHub 也无法访问，提示用户手动下载 ZIP 并放到部署目录。
错误 9：duplicate loader entry id: cordis-host-runner（仅 demo:cordis 出现）
原因：demo 配置与构建产物冲突。
解决方案：这是 demo 命令的已知问题，不影响 dsh web 主功能。不要试图修复它，直接用 dsh web 启动。
错误 10：端口 3081 被占用
原因：其他程序占用端口。
解决方案：
# 查找占用进程
netstat -ano | findstr :3081
# 换用其他端口启动
pnpm run dsh web --port 3082 --host 127.0.0.1
错误 11：构建失败 Cannot find module 'xxx'
原因：依赖未完整安装。
解决方案：
pnpm install --force
pnpm run build:lib:host
错误 12：postinstall 失败（node-pty / koffi 原生模块编译）
原因：缺少 C++ 编译工具链。
解决方案：
npm install -g windows-build-tools
# 或安装 Visual Studio Build Tools: https://visualstudio.microsoft.com/visual-cpp-build-tools/
📁 技能文件结构
deepseek-harness-deploy-skill/
├── SKILL.md # 本文件：主部署流程
├── install-node.ps1 # Node.js 自动安装脚本
├── setup.ps1 # 一键完整部署脚本
├── start-web.ps1 # 仅启动 Web 服务脚本
├── faq.md # 常见问题解答
└── guide.md # 详细故障排查指南
📝 使用示例
场景 A：完整一键部署
用户说："帮我部署 deepseek-harness 项目"
智能体执行：
1. 检测环境 → 2. 下载 ZIP → 3. 解压 → 4. 配置镜像源 → 5. 安装依赖 → 6. 构建 → 7. 启动 → 8. 验证
场景 B：仅启动已部署项目
用户说："启动 deepseek-harness"
智能体执行：
1. 检测项目目录是否存在 → 2. 执行 start-web.ps1
场景 C：部署失败修复
用户说："安装报错了"
智能体执行：
1. 读取错误日志 → 2. 匹配"故障处理表" → 3. 执行对应解决方案 → 4. 重试失败的步骤
✅ 部署成功标志
部署完成后，以下条件全部满足即视为成功：
- [ ] 项目目录 deepseek-harness 存在且包含 package.json
- [ ] node_modules 目录存在且非空
- [ ] pnpm run dsh --version 输出 0.1.0-rc.5
- [ ] http://127.0.0.1:3081 返回 HTTP 200
- [ ] 浏览器可访问 Web 界面
📞 技术支持
- 项目仓库：https://github.com/deepseek-ai/deepseek-harness
- 详细故障排查：见
guide.md - 常见问题：见
faq.md
