DeepSeek Harness 从零到一运行教程

DeepSeek Harness 从零到一运行教程本教程面向 Windows 用户手把手教你从环境搭建到成功运行 DeepSeek Harness。让程序员扣棣的粉丝也能跟着跑起来一、项目简介DeepSeek Harness 是一个基于 Cordis 的插件式 AI 编码智能体框架支持CLI 模式命令行直接给 AI 下达任务Web UI 模式浏览器可视化界面与 AI 交互二、Node.js 版本选择重要Node 版本CLI 模式Web UI 模式dev:web 开发模式22.19.x✅正常正常有兼容性问题24.x正常正常有兼容性问题结论推荐使用 Node 22.19.0 LTS这是最稳定的选择。⚠️pnpm run dev:web是开发者用于热更新客户端插件的命令内部依赖import-without-cache0.4.0该包在 Node 22/24 下均有兼容性问题。普通用户不需要运行此命令直接用pnpm dsh web启动 Web UI 即可。三、环境准备3.1 安装 nvm-windowsNode 版本管理器访问 https://github.com/coreybutler/nvm-windows/releases下载最新的nvm-setup.exe并安装安装完成后重新打开 PowerShell3.2 安装 Node.js 22.19.0nvm install 22.19.0 nvm use 22.19.0验证安装node--version# 应输出: v22.19.03.3 启用 pnpm项目使用 pnpm 作为包管理器通过 Node.js 内置的 corepack 启用corepack enable corepack prepare pnpm11.7.0--activate验证pnpm--version# 应输出: 11.7.0四、获取项目源码# 克隆仓库体替换为你的仓库地址git clone https://github.com/deepseek-ai/deepseek-harness cd deepseek-harness五、安装依赖由于国内访问 npm 官方源较慢推荐使用npmmirror 镜像pnpm install--registryhttps://registry.npmmirror.com 首次安装约需 5-10 分钟取决于网络速度。安装约 923 个包。如果看到WARN Unsupported platform关于linux-arm64或linux-x64的警告可以忽略这是因为 landlock-run 是 Linux 专用的安全沙箱Windows 上不需要。安装成功的标志Done in XXs using pnpm v11.7.0六、构建项目DeepSeek Harness 是 TypeScript 项目运行前需要先编译pnpm run build 构建约需 1-3 分钟。会依次编译 host 端、client 端和 Web 前端。构建成功的标志最后几行✔ [deepseek-ai/dsh] Build complete in XXXXXms ✓ built in X.XXs⚠️常见错误如果跳过此步直接运行会报错Cannot find module ...lib\typert.host.js。必须先 build七、配置 API KeyDeepSeek Harness 需要 DeepSeek API Key 才能运行。7.1 获取 API Key访问 https://platform.deepseek.com/注册/登录账号进入「API Keys」页面创建一个新 Key格式为sk-xxxx7.2 创建 .env 配置文件在项目根目录创建.env文件注意开头的点号# 在 PowerShell 中创建Set-Content-Path.env-ValueDEEPSEEK_API_KEYsk-你的API密钥或手动创建文件内容为DEEPSEEK_API_KEYsk-你的API密钥⚠️安全提醒.env文件已在.gitignore中不会被提交到 Git。请勿将 API Key 分享给他人或提交到代码仓库。八、运行项目方式一CLI 命令行模式最简单pnpm dsh--profile headless你好请用一句话介绍自己成功运行后你会看到 AI 的回复你好我是 DeepSeek Harness 的编码智能体基于 deepseek-v4-flash 模型构建...方式二Web UI 浏览器模式推荐新手pnpm dsh web启动成功后会显示dsh web: http://127.0.0.1:3080打开浏览器访问 http://127.0.0.1:3080 即可看到 Web 界面。 按CtrlC停止服务。九、完整命令速查# 一次性环境搭建 nvm install 22.19.0 nvm use 22.19.0 corepack enable corepack prepare pnpm11.7.0--activate# 获取项目 git clone 仓库地址 cd deepseek-harness# 安装依赖国内镜像加速 pnpm install--registryhttps://registry.npmmirror.com# 构建项目 pnpm run build# 配置 API Key Set-Content-Path.env-ValueDEEPSEEK_API_KEYsk-你的密钥# 运行 CLI pnpm dsh--profile headless你的任务指令# 运行 Web UI pnpm dsh web# 然后浏览器打开 http://127.0.0.1:3080十、常见问题排查Q1:pnpm: 无法将pnpm项识别为 cmdlet原因pnpm 未安装或未启用。解决corepack enable corepack prepare pnpm11.7.0--activateQ2:Cannot find module ...lib\typert.host.js原因未执行构建步骤。解决pnpm run buildQ3:EADDRINUSE: address already in use 127.0.0.1:3080原因端口 3080 被占用可能之前的实例还在运行。解决# 查找并关闭占用端口的进程Stop-Process-Id(Get-NetTCPConnection-LocalPort 3080).OwningProcess-Force# 然后重新启动pnpm dsh webQ4:pnpm install非常慢或超时原因默认 npm 源在国内访问慢。解决使用国内镜像pnpm install--registryhttps://registry.npmmirror.comQ5:DEEPSEEK_API_KEY相关错误原因API Key 未配置或配置错误。解决检查.env文件是否存在于项目根目录检查内容格式是否正确DEEPSEEK_API_KEYsk-xxxx确认 Key 有效可在 DeepSeek 平台测试Q6: 切换 Node 版本后 pnpm 丢失原因每个 Node 版本有独立的 corepack 环境。解决切换 Node 版本后重新启用 pnpmnvm use 22.19.0 corepack enable corepack prepare pnpm11.7.0--activate十一、项目结构简述deepseek-harness/ ├── apps/ │ ├── cli/ # CLI 入口 │ └── web/ # Web 前端 ├── packages/ # 核心包200 个工作区包 │ ├── core/ # 核心 APIsession、tools、agent loop │ ├── llm/ # LLM 能力DeepSeek 提供商 │ ├── shell/ # Shell 命令执行 │ ├── fs/ # 文件系统操作 │ └── ... # 更多功能插件 ├── vendor/ # vendored Cordis 源码 ├── docs/ # 文档 ├── examples/ # 示例配置 └── scripts/ # 构建脚本十二、进阶用法使用自定义配置运行项目支持通过cordis.yml自定义插件组合# 使用示例配置运行pnpm dsh--profile headless--config examples/headless-agent/cordis.yml你的任务运行 Demo# Cordis DemoAI 修改自身运行时pnpm run demo:cordis# ACP 自动化服务器pnpm run demo:acp总结整个流程其实就是5 步装 Node 22.19→nvm install 22.19.0 nvm use 22.19.0装依赖→pnpm install --registryhttps://registry.npmmirror.com构建→pnpm run build配 Key→ 创建.env写入DEEPSEEK_API_KEYsk-xxx运行→pnpm dsh web或pnpm dsh --profile headless 任务就这么简单