夜雨聆风DEEPSEEK HARNESS · 2026.08.15
DeepSeek Harness 手把手安装教程
macOS 实测 5 分钟跑通 · 附踩坑合集 & 一键启动脚本
AI Agent开源框架保姆级实测记录
DeepSeek 官方开源了 Agent 开发框架 DeepSeek Harness：插件化架构、自带 Web 界面、能自主完成"写代码→跑起来→浏览器测试→修 bug"的完整闭环。网上教程以 Windows 为主，这篇我用 MacBook Air（M5）实测，从零到跑通只花了 5 分钟，所有命令和踩过的坑全部记录在这里，跟着做就行。
1
安装前准备：环境三件套
🟢
Node.js
≥ 22.19 / 24+
📦
pnpm
11+（包管理器）
🐙
Git
macOS 自带 ✓
① 检查 Node.js：打开终端（⌘+空格 搜 Terminal），执行：
$ node -v
v24.15.0
② 检查 pnpm（项目要求的包管理器）：
$ pnpm -v
zsh: command not found: pnpm
⚠️ 坑①：pnpm 没装！新手教程里默认你有 pnpm，但 macOS 全新环境根本没有。别慌，一条命令搞定：方案 A（推荐，Node 自带 Corepack）：corepack enable 然后重新执行 pnpm -v，会自动下载安装。方案 B：npm i -g pnpm
2
下载项目（二选一）
方式一：Git 克隆（推荐，可随时更新）：
$ git clone https://github.com/deepseek-ai/deepseek-harness.git
Cloning into 'deepseek-harness'... done
$ cd deepseek-harness
方式二：网盘下载——不方便访问 GitHub 的话，用网盘版本解压即可（无需翻墙）。
项目结构是 pnpm workspaces 多包仓库，核心代码在 packages/ 下（core 内核、llm 大模型对接、web 网页能力、subagent 子代理……），非常规范。
3
安装依赖 & 构建
在项目目录执行 安装依赖（第一次会自动下载所有包，实测 23 秒搞定）：
$ pnpm install
Done in 23.4s using pnpm v11.7.0
⚠️ 坑②：看到 WARN 别慌！安装结束会出现类似下面的警告：[WARN] Failed to create bin at .../lib/bin.js ENOENT 这是"可执行文件还没构建出来"的正常现象（那些 demo 的 bin 要等 build 之后才存在），不影响安装结果，直接下一步。
然后 构建（把 TypeScript 编译成可运行代码，几秒到几十秒）：
$ pnpm run build
✓ built in 975ms
看到 ✓ built 就是成功。结尾如果有"chunk 超过 500KB"的提示，只是性能建议，完全不用管。
4
启动 Web 界面（最激动人心的一步！）
$ pnpm dsh web
dsh web: http://127.0.0.1:3080
然后浏览器打开 http://127.0.0.1:3080，就能看到 Harness 的 Web 界面啦！👇
界面包含新会话 / 工作区 / 设置三大模块，默认连接 DeepSeek-V4-Flash 模型，支持"创造模式"（Creative Mode）和 Workspace Write 等工具，点击消息流中的工具行还能查看执行详情。
⚠️ 坑③：服务是"前台进程"！这个命令会一直占用当前终端窗口，关掉终端 = 服务停止。想让它一直跑，要么留着终端别关，要么用下面的「一键启动脚本」或 nohup 后台运行。停止服务按 Ctrl+C。
⚠️ 坑④：端口固定 3080。如果提示端口被占用，是之前没关干净，找出来杀掉：lsof -i :3080 然后用输出的 PID 执行 kill PID。
5
首次配置：填入 DeepSeek API Key
第一次使用会提示对接 API Key：去 platform.deepseek.com 注册并创建一个 API Key（就是 DeepSeek 官方模型接口的密钥），粘贴进去即可。配置好后就能体验 Harness 的完整 Agent 能力了：
🎬 场景一：一句话开发"多平台视频下载器"
让 Harness 从零创建、运行、测试一个支持 YouTube / Bilibili / Vimeo / X / TikTok / Instagram 的完整下载管理 Web 应用——需求分析、架构设计、写码、装依赖、起服务、浏览器测试、修 bug 全部自主完成，跑完直接可用。
🏎️ 场景二：赛博朋克 3D 赛车游戏
Three.js + 3D 城市赛道 + WASD 驾驶 + AI 对手 + 氮气加速 + 粒子效果，两轮修改就交付一个能在浏览器里玩的完整游戏。
🧱 场景三：熔炉打砖块游戏
好玩到停不下来的小游戏，AI 只花几十分钟就完成了从创意到可玩版本的迭代。
6
踩坑合集速查表（建议收藏）
🚨
pnpm 不存在（zsh: command not found）
macOS 默认没有 pnpm。执行 corepack enable 启用 Node 自带的管理器，再跑 pnpm -v 即可，或 npm i -g pnpm。
⚠️
Node 版本太老报错
项目要求 Node ^22.19 或 ≥24。老版本跑 build 会报语法/API 错误。去 nodejs.org 装最新 LTS（或 24.x），用 nvm 管理版本最方便。
🤔
install 时 WARN "Failed to create bin ... ENOENT"
正常现象，那些 bin 要等 build 后才生成。无视即可，别浪费时间排查。
🖥️
关掉终端服务就没了
pnpm dsh web 是前台进程。要常驻：用 nohup 或直接双击桌面启动脚本（见下文）。
🔒
.command 启动脚本双击打不开
macOS 对下载/新建的脚本有安全拦截：右键 → 打开 一次即可。脚本记得先 chmod +x 赋予执行权限。
🌐
GitHub 克隆太慢 / 失败
国内网络直连 GitHub 不稳定，可用网盘版，或用 ghproxy 等加速镜像：git clone https://ghproxy.com/https://github.com/deepseek-ai/deepseek-harness.git
7
懒人福利：桌面一键启动脚本
把下面内容保存为 启动DeepSeekHarness.command（放桌面），终端执行一次 chmod +x 授权，以后双击就能启动：
#!/bin/bash
export PATH="/opt/homebrew/bin:$PATH"
cd ~/deepseek-harness || exit 1
echo "🚀 启动 DeepSeek Harness..."
echo "🌐 访问 http://127.0.0.1:3080"
pnpm dsh web
（Intel Mac 用户把 /opt/homebrew 换成 /usr/local 即可）
"不要只生成代码——我要测试的是你的 Agent 能力。"
安装完成了吗？去让 Harness 帮你写第一个应用吧！🎉
关注我 · 后续更新 DeepSeek Harness 实战玩法 · API Key 配置详解 · Agent 编程技巧
星星AI助手 · 2026.08.15
本文为实测记录，环境：macOS (M5) · Node v24 · pnpm 11 · DeepSeek Harness 最新源码
星星AI助手 · 2026.08.15
