2026-08-14 · DeepSeek Harness（
dsh）v0.1.0-rc.6 · Windows 11 + Node.js v24
先认识一下：DeepSeek Harness 是什么？
DeepSeek Harness（命令行工具名 dsh）是 DeepSeek 官方开源的 AI 智能体（Agent）框架，2026 年 8 月随 DeepSeek-V4-Pro 一起发布，定位对标 Claude Code 和 OpenAI Codex。
它的核心设计理念是 "一切皆插件"：整个执行引擎由插件组成，基于 Cordis 微内核 构建——想加能力就装插件，不需要的能力就拆掉。这个可插拔的架构，是它和传统一体化 agent 框架最大的区别。
术语解释：Agent（智能体） 指能自主调用工具、完成多步骤任务的 AI 程序；微内核 指只保留最核心调度功能、其余能力都通过插件扩展的架构。
环境信息
本文所有操作在以下环境验证通过：
- 系统：Windows 11
- Node.js：v24.14.0（官方要求 v18+）
- npm：11.8.0
- 包版本：
@deepseek-ai/dsh@0.1.0-rc.6
⚠️ 注意：目前是 v0.1 开发预览版，官方明确提示会频繁出现破坏性变更（Breaking Change），升级时留意兼容性。
安装方式一：npx 快速体验（免安装）
如果只是临时体验，不需要装到系统里：
npx @deepseek-ai/dsh web
npx 会自动拉取最新包并启动 Web UI。
安装方式二：npm 全局安装（推荐，本文采用）
经常使用的话，全局安装一步到位：
npm install -g @deepseek-ai/dsh
验证安装：
dsh --version
# 0.1.0-rc.6
启动 Web UI：
dsh web
服务起来后，浏览器打开 http://127.0.0.1:3080。
首次使用需要配置：
- 填入模型 API Key（如 DeepSeek 开放平台 key），保存在
$DSH_HOME/.credentials.yaml - 选择一个工作区目录
- 也支持接入其它 OpenAI 兼容模型（Web UI 设置或
$DSH_HOME/settings.yaml）
配置一次后，以后启动就是 dsh web + 打开网址，两步走。
安装方式三：源码构建（进阶）
想跟源码、做二次开发的话：
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
遇到的坑与解决
坑 1：GitHub 直连失败
源码方式的第一步 git clone 就卡住了——国内网络直连 GitHub 不通，git 报 Failed to connect to github.com port 443。
解决思路： 其实大部分场景根本不需要碰 GitHub。@deepseek-ai/dsh 已经发布到了 npm 官方源，而国内 npm 通常配置了镜像（如 npmmirror）。检查一下你的 npm 源：
npm config get registry
# 输出 https://registry.npmmirror.com 即为镜像源
只要 npm 走镜像源，npm install 就能正常下载，全程不经过 GitHub。所以选 安装方式二（npm 全局） 是最省心的路线。
如果确实要 clone 源码，那才需要开代理（如 http://127.0.0.1:10808）或配置 git 代理。
坑 2：EADDRINUSE 端口被占
重启时踩到的坑——报错长这样：
Error: dsh: plugin tree failed to load: ... listen EADDRINUSE: address already in use 127.0.0.1:3080
含义： 3080 端口被占用。典型场景是：之前启动的 dsh web 进程没退干净（比如后台任务被终止了，但底层 node 进程还活着），新实例抢不到端口就崩了。
排查：
# Windows 下找出谁占了 3080 端口
netstat -ano | findstr :3080 | findstr LISTENING
# TCP 127.0.0.1:3080 0.0.0.0:0 LISTENING 16164
# ^PID
解决： 杀掉占端口进程再启动：
taskkill /PID 16164 /F
dsh web
一个反直觉的坑：后台任务的"任务被终止"不等于进程被杀。在 Claude Code 之类的工具里，后台任务被停止后，实际 node 进程常常成了"孤儿进程"继续跑、继续占端口。所以"重启服务"的标准动作应该是先查端口 → 杀 PID → 再启动，而不是盲目再启一个。
收尾：一键启动脚本
每次手动 netstat + taskkill + dsh web 太啰嗦了。写一个 Windows 批处理脚本，双击就能完成全流程。
@echo off
chcp 65001 >nul
setlocal enabledelayedexpansion
rem ===== DeepSeek Harness 一键启动脚本 =====
rem 功能：检查 3080 端口 -> 释放旧进程 -> 后台启动 dsh web -> 就绪后打开浏览器
echo.
echo ============================================
echo DeepSeek Harness Launcher
echo ============================================
echo.
rem ---- 1. 检查 dsh 是否已安装 ----
where dsh >nul 2>nul
if errorlevel 1 (
echo [错误] 未找到 dsh 命令，请先安装：npm install -g @deepseek-ai/dsh
pause
exit /b 1
)
rem ---- 2. 检查 3080 端口占用，释放旧进程 ----
set "PORT=3080"
for /f "tokens=5" %%a in ('netstat -ano ^| findstr ":%PORT%" ^| findstr LISTENING') do (
echo [清理] 端口 %PORT% 被 PID %%a 占用，正在终止旧实例...
taskkill /PID %%a /F >nul 2>nul
)
ping 127.0.0.1 -n 3 >nul
rem ---- 3. 后台启动 dsh web（独立窗口）----
echo [启动] 正在后台启动 dsh web ...
start "DeepSeek Harness Server" /min cmd /k "dsh web"
rem ---- 4. 轮询端口，就绪后打开浏览器 ----
echo [等待] 等待服务就绪 ...
set /a count=0
:waitloop
set /a count+=1
netstat -ano | findstr ":%PORT%" | findstr LISTENING >nul 2>nul && goto :up
if %count% GEQ 30 goto :timeout
ping 127.0.0.1 -n 2 >nul
goto :waitloop
:up
echo [成功] 服务已就绪！正在打开浏览器...
start "" "http://127.0.0.1:%PORT%"
echo 访问地址: http://127.0.0.1:%PORT%
echo 停止服务: 在 "DeepSeek Harness Server" 窗口按 Ctrl+C 或关闭该窗口
pause
exit /b 0
:timeout
echo [超时] 30 秒内服务未就绪，请检查 "DeepSeek Harness Server" 窗口的错误信息。
pause
exit /b 1
保存为 dsh-start.bat（注意必须是 CRLF 行尾，Linux 风格 LF 行尾的 bat 在 Windows 会运行异常），双击即可。
小知识：为什么 bat 必须是 CRLF？Windows 的命令行解释器（cmd.exe）依赖回车换行（CRLF）来解析批处理命令，如果文件只有换行（LF），脚本经常出现诡异的"不是内部或外部命令"错误。用 VS Code 保存时注意右下角行尾选择，或者用
sed 's/$/\r/' file.bat > file_crlf.bat转换。
总结
| 步骤 | 命令 / 操作 |
|---|---|
| 安装 | npm install -g @deepseek-ai/dsh |
| 启动 | dsh web |
| 访问 | http://127.0.0.1:3080 |
| 首次配置 | 网页里填 API Key + 选工作区 |
| 端口被占 | netstat -ano | findstr :3080 → taskkill /PID xxx /F → 重启 |
| 一键启动 | 双击桌面 dsh-start.bat |
一句话总结：npm 全局装、dsh web 起、端口冲突就 taskkill，再用 bat 脚本把这些打包成双击一次搞定。
如果你也在用 DeepSeek Harness 或其它 Agent 框架，欢迎交流踩坑经验。