一、它是什么？（先搞清楚再动手）
DeepSeek Harness （dsh）是 DeepSeek AI 官方开源的 agent harness（智能体框架） ，可以理解为 "国产版 Claude Code / Codex"。
核心特点（记住这三条就够了）
一切皆插件 ：模型、工具、沙箱、存储、UI、甚至 Agent 循环本身都是插件，想换哪个换哪个
三种形态 ：Web 界面 （浏览器用）、headless （命令行一次问答，适合脚本）、TUI（终端界面）
官方出品，MIT 开源 ：仓库
https://github.com/deepseek-ai/deepseek-harness，完全免费
和别的工具比
| DeepSeek Harness | Claude Code | Codex | |
|---|---|---|---|
| 厂商 | DeepSeek（国产） | Anthropic | OpenAI |
| 开源 | ✅ MIT | ❌ | ❌ |
| 插件化 | 最强（一切皆插件） | 一般 | 一般 |
| 语言 | 中文友好 | 英文 | 英文 |
⚠️ 重要提示 ：目前是开发者预览阶段 ，功能接口迭代很快、可能随时变 ，别用于生产环境，玩玩和学习为主。
版本验证
$ npx @deepseek-ai/dsh --version
0.1.0-rc.6二、环境要求（装之前先检查这三样）
| 需要 | 版本要求 | 说明 |
|---|---|---|
| Node.js | v20+ | 本文实测 v24.19.0，没有就去 nodejs.org 下载 LTS 版 |
| npm | 随 Node 自带 | 安装/更新 dsh 用 |
| pnpm | 装插件时才需要 | npm install -g pnpm 一步搞定 |
检查命令（照抄执行）
node -v # 例如 v24.19.0 ✅
npm -v # 例如 11.17.0 ✅只要 node -v 能输出版本号，环境就 OK 了。 如果提示"node 不是内部或外部命令"，说明 Node.js 没装上或没加入 PATH------去 Node.js --- Run JavaScript Everywhere 下载安装包，一路下一步 ，装完重开终端再试。
Windows 用户特别提醒 ：安装 Node 时默认选项即可 （会自动配好 PATH）；装完如果 cmd 里还认不出 node，注销重登或重启电脑一次。
三、安装方式
方式一：免安装直接跑（⭐ 最推荐，先体验再说）
不需要安装任何东西，一条命令：
npx @deepseek-ai/dsh web-
首次运行会自动初始化
web配置模板 -
然后打印访问地址：
dsh web: http://127.0.0.1:3080 -
浏览器打开 http://127.0.0.1:3080 看到界面 = 安装成功 🎉
💡 小贴士 ：dsh 会把你执行命令时所在的目录 当作默认工作区。先
cd到你的项目目录再启动，后面选工作区最方便。
方式二：全局安装（⭐ 推荐长期使用）
npm install -g @deepseek-ai/dsh验证安装：
dsh --version看到版本号 = 装好了。以后随时启动：
dsh web # 启动 Web UI（等价于 dsh --profile web）方式三：源码安装（适合开发者/想读源码）
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web三种方式选一种即可。小白选方式一；想长期用选方式二；想改源码/贡献代码选方式三。
四、首次使用：配置 API Key
打开 Web 界面后，必须先配置 DeepSeek API Key 才能开始对话：
打开 platform.deepseek.com，注册登录
左侧菜单 "API Keys" → 创建 API Key （
sk-开头）回到 dsh Web 界面 → 设置 → 模型/账号 → 填入 Key
默认模型
deepseek-chat，便宜（约 1~2 元/百万字，日常聊天几分钱）
其他要点
想用更强的：模型可换
deepseek-v4-pro或带思考的deepseek-reasoner不想用 DeepSeek 也行：支持配置其他 OpenAI 兼容的 provider
Key 是敏感信息：别发到公开平台；泄露了去 platform.deepseek.com 立刻删除重建
五、常用命令速查
| 命令 | 作用 |
|---|---|
dsh web |
启动 Web UI （--profile web 的别名），默认 127.0.0.1:3080 |
dsh --profile web --port 8080 |
换端口启动（端口被占用时用） |
dsh --profile headless "跑一下测试" |
命令行跑一次任务，打印结果后退出（适合脚本/CI） |
dsh plugin --profile web add <插件名> |
安装插件（转发给 pnpm 执行） |
dsh --profile web --dump-config |
查看完整配置树（不启动服务器） |
dsh --profile web --help |
查看 Web 应用自己的参数 |
数据存在哪？（重启不丢会话）
所有数据在 $DSH_HOME （默认 ~/.dsh）：
~/.dsh/
├── profiles/ # 各 profile（web/headless），含插件依赖
├── sessions/ # 会话记录（JSONL）—— 重启后对话还在
├── settings.yaml # 用户设置（模型、主题等）
└── storages/ # 存储💡 换电脑/备份 ：把整个
~/.dsh拷走，新机器装好 dsh 后放回去，会话和配置全都在。
六、插件生态（进阶玩法，一句话带过）
dsh 的灵魂是 "一切皆插件"，装插件一行命令：
dsh plugin --profile web add dshmarket # 插件市场
dsh plugin --profile web add @liustack/modlens # 视觉识别插件-
前提：装好 pnpm （
npm install -g pnpm） -
装完插件必须重启 dsh web 才生效
-
社区插件 270+，精选清单：awesome-dsh-plugin
⚠️ 安全提醒 ：装插件 = 跑第三方代码，权限和你一样大，优先装社区背书、看过源码的。
七、Windows 启动不了？看这里（排查清单）
启动不了 = 最常见的四种情况，按顺序查：
① 提示"禁止运行脚本 / 无法加载 dsh.ps1"（最最常见）
Windows 默认 PowerShell 执行策略会拦截 npm 装的命令。两种解法：
-
方法 A（推荐） ：改用 cmd（命令提示符） 运行
dsh web，别用 PowerShell -
方法 B：直接调 Node 入口绕过：
node "C:\Users\你的用户名\AppData\Roaming\npm\node_modules\@deepseek-ai\dsh\lib\bin.js" web② 提示"node 不是内部或外部命令" / "找不到 npm"
说明 Node.js 没装好或 PATH 没配上：
-
去 Node.js --- Run JavaScript Everywhere 重装，一路默认下一步
-
装完重开终端（或注销重登）再试
-
还不行就重启电脑
③ 启动时报"端口被占用 / EADDRINUSE"
默认端口 3080 被别的程序占了：
dsh web --port 8080 # 换一个端口注意：启动器参数在前，应用参数在后 ，
--port属于 Web 应用。
④ npx 拉包失败 / 卡住不动 / 报版本错误（国内网络）
- 给 npm 配国内镜像：
npm config set registry https://registry.npmmirror.com-
或清 npx 缓存 后重试：
npx clear-npx-cache后重新执行 -
网络不行时，改用全局安装 ：
npm install -g @deepseek-ai/dsh
⑤ 其他检查
-
防火墙拦截：确认 Windows 防火墙放行 Node.js（首次运行弹窗点"允许"）
-
版本过旧 ：
npm update -g @deepseek-ai/dsh更新到最新 -
插件装坏了导致启动失败 ：检查
~/.dsh/profiles/web的package.json，把刚装的插件从bundles列表移除，再启动