夜雨聆风DeepSeek Harness 安装实测教程（Windows 版）：从零到跑通，踩坑全记录
8 月 13 日晚，DeepSeek 正式发布开发者预览版 V0.1，MIT 开源。官方定义“一切皆插件”——模型、工具、技能、会话、沙箱、存储、循环、调度、UI 全部插件化，可以像乐高一样自由组装。
这篇教程是我们在 Windows 11 上从零实测跑通的完整记录，包含网上教程基本不会写的三个坑：Node 版本、lefthook 安装失败、pnpm 缺失。照着抄就能跑起来。
● ● ●
一、先说结论
| 项目 | 说明 |
|---|---|
| 官方仓库 | https://github.com/deepseek-ai/deepseek-harness |
| 协议 | MIT，可商用 |
| 当前版本 | 0.1.0-rc（开发者预览版，迭代很快，会有破坏性变更） |
| Node 要求 | ^22.19.0 || >=24.0.0（注意：22.14 都不行！） |
| 包管理器 | pnpm（核心依赖） |
| 启动后地址 | http://127.0.0.1:3080 |
| 上手门槛 | 中等。会 Git 和基本命令行即可，不需要会写插件也能玩 |
需要准备的：
▸ Git（git --version 确认）
▸ Node.js 24（后面详细说版本坑）
▸ 一个 DeepSeek API Key（platform.deepseek.com 申请，用于登录 Harness）
▸ 科学上网（clone GitHub 和装依赖时更稳，国内直连慢但也能跑）
● ● ●
二、环境准备：先把版本坑填平
我们实测本机环境：
坑 1：Node 版本不够，直接装个独立版
Harness 声明的 Node 范围是 ^22.19.0 || >=24.0.0，本机 22.14 不满足，构建时 tsdown 直接报 Failed to import module "unrun"。
不要动你现有的 Node，下载一个 Node 24 独立版放旁边，用的时候把 PATH 指过去就行：
之后每次跑 Harness 前，先让 PATH 指向 Node 24：
坑 2：没有 pnpm？一条命令装
● ● ●
三、克隆源码
浅克隆（--depth 1）只拉最新版本，速度快很多：
国内直连 GitHub 如果很慢，可以挂代理或者用镜像加速。
● ● ●
四、安装依赖：这里藏着一个大坑
坑 3：lefthook 在 Windows 上装不上（不影响使用，但会卡住流程）
现象：依赖装到 99%，postinstall 脚本失败：
原因：DeepSeek 自己写的 lefthook 安装脚本在 Windows 上有锁文件所有权检测 bug，删了锁文件重试还是失败。
解决：lefthook 只是 git 钩子管理工具，和运行 Harness 完全无关，直接跳过它。编辑根目录 package.json，把：
改成：
然后重跑：
看到 Done in xx s 就成功了。构建时那两行 [WARN] Failed to create bin at ... 是无害警告，忽略。
● ● ●
五、构建 + 启动
构建（务必在 Node 24 环境下）
构建分两步：build:lib（TypeScript 编译核心库）+ build:web（Vite 打包前端）。这一步不能省——只装依赖不构建的话，Web 页面会缺产物打不开。
构建耗时 1-3 分钟，最后看到
built in xx s就是成了。
启动
看到这行就绪：
浏览器打开 http://127.0.0.1:3080，输入 DeepSeek API Key 就能进。
● ● ●
六、上手：界面和四种模式
打开后你可能有点懵——界面就是一个对话框 + 左侧历史记录，像个“毛坯房”。这是正常的，它的功能都藏在插件里，需要自己组装。
四个模式，对应不同插件集合：
| 模式 | 说明 | 适合谁 |
|---|---|---|
| 标准模式 | 完整工具组合 | 新手入门，先玩这个 |
| PTC 模式 | 程序化工具调用，模型生成代码组合多轮工具调用 | 玩 Agent 自动化 |
| 极简模式 | 只留 shell + 文件编辑 | 模型基准测试 |
| 创造模式 | 运行时试验插件、组合新模式 | 进阶玩家 |
● ● ●
七、加餐：一键启动脚本
每次开机都要先切 PATH 再启动太麻烦，我们写了个一键启动 .bat 放桌面，双击即用：
逻辑：先检测 3080 端口有没有在跑——在跑就直接开浏览器；没跑就先启动服务等 6 秒再开浏览器。
● ● ●
八、想更进一步？插件玩法预告
跑通基础版之后，可以往两个方向进阶：
1. 装现成的生产级插件（以 DSH Vision Toolkit 为例，给纯文本模型补上视觉能力）：
2. 自己写一个最小插件：结构只有四步——apply(ctx) 定义加载入口 → ctx.tools.register(...) 注册工具 → execute(args) 写执行逻辑 → cordis.yml 声明插件路径，启动时用 --patch 挂载。最小示例可以写一个 greet 问候工具，跑通“加载插件 → 注册工具 → 模型调用 → 返回结果”的完整闭环。
提醒：Harness 插件运行在宿主进程里，属于可信代码。装第三方插件前，务必检查仓库是否公开、许可证是否清楚、安装脚本会下载什么、需要哪些权限。
● ● ●
写在最后
DeepSeek Harness 目前还是开发者预览版，官方自己也说“会有兼容性破坏变更”，但它把 Agent 的底层运行框架彻底开放了——模型、工具、循环、UI 全部可插拔。这跟 Codex / Claude Code 那种“开箱即用的成品”是两条路线：前者给你一块地基，后者给你精装房。
对于想理解 Agent 到底怎么跑的人，Harness 是最好的教材；对于想快速出活的人，现阶段 Claude Code 可能更顺手。但无论如何，8 月 13 日这个 MIT 开源的版本，值得每个玩 Agent 的人装一次。
● ● ●
本文基于 2026-08-14 实测，环境：Windows 11 + Node 24.19.0 + pnpm 11。如有版本更新导致步骤变化，以官方仓库 README 为准。