DeepSeek Harness 保姆级教程：从「一行命令跑起来的 Agent」到「双击即用的桌面驾驶舱」

永恒风暴级

341人浏览 · 2026-08-17 20:06:49

永恒风暴级 · 2026-08-17 20:06:49 发布

本文会先从零教你安装并使用 DeepSeek Harness（dsh），把本地 Agent 真正跑起来；
然后用我们实际用了一两周之后遇到的"痛点"引出今天的重点——一个把它桌面化、常驻后台的开源桌面壳 DshCockpit（含 v0.2.3 全新「手机远程控制」）。

一、DeepSeek Harness 是什么？

DeepSeek Harness（命令行工具叫 dsh）是 DeepSeek 官方开源的 Agent 运行时（harness），MIT 协议，几乎全 TypeScript。

它有几点和很多 AI 编程工具不一样的设计哲学：

一切皆插件：模型适配器、工具注册表、Agent Loop、会话日志……核心能力全部以插件形式参与运行，可以自由组合、替换。底层基于 Cordis 构建。
本地 Web UI 交互：不用记住一堆 CLI 参数，直接在浏览器里看 Agent 干活、审批操作、管理会话。
看得见、可审批：Agent 要改文件、要跑命令、要访问网络之前，会停下来等你审批（内置文件沙箱 + 审批机制）。
当前是 developer preview：官方迭代极快，会不定期出现破坏性变更——这一点后面会引出大问题。

如果你用过 Claude Code、Codex 这类工具，会很容易上手；如果你没用过，下面从安装开始带你走一遍。
在这里插入图片描述

二、安装：一行命令，浏览器里跑起 Agent

前提条件

只需要一个 Node.js（建议装 LTS 版本）。不用装别的。

开始

打开终端，执行一行命令：

npx @deepseek-ai/dsh web

首次运行会自动下载 @deepseek-ai/dsh，随后启动本地 Web UI，默认地址是：

http://127.0.0.1:3080

浏览器会自动（或手动）打开这个地址，你就看到 DeepSeek Harness 的 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 UI 的设置里填入你的 DeepSeek API Key（到 DeepSeek 开放平台申请）。
添加工作区：选择 Agent 要干活的文件夹（工作区）。
新建会话，下任务：比如"帮我重构这个模块的异常处理"，然后看着它干活。

四、Agent 是怎么干活的？

这是我觉得 DeepSeek Harness 体验上最爽的地方：

过程全透明：你能看到它规划 → 改代码 → 跑测试 → 自查的完整过程，而不是干等一个结果。
该审批就审批：涉及文件写入、执行命令、网络访问这类敏感操作时，它会停下来等你确认，而不是擅自乱动你的机器。
可无限扩展：想加能力？去 GitHub 搜 dsh-plugin 话题，官方和社区有一堆插件，装进去就能用（比如加模型适配器、加工具、改界面）。

到这里，一切都很美好。但用上一两周之后，问题就来了——而且都不是"某个功能不好用"，而是它长在终端和浏览器里带来的结构性痛点。

五、用的越久，越戳心的几个痛点

1. 关掉终端，Agent 当场断

dsh web 是前台进程。合上笔记本盖子、关掉终端窗口、或者电脑睡一觉，Agent 就断了。长任务（比如跑一晚上批处理）只能开着电脑、开着终端、守着。

2. 每次都要开终端敲命令

"想用一下"的代价是：打开终端 → 敲 npx @deepseek-ai/dsh web → 等启动。对非开发者朋友来说，"终端"两个字本身就劝退了。

3. 官方迭代快，升级全靠手动

前面说了它是 developer preview，版本更新非常频繁。手动 npm 升级不仅麻烦，还容易一不留神把坏版本装上去——装完发现跑不起来，又得回退。

4. 烧钱没感觉

Token 用量只在对话里"闪一下"就没了。月底一看账单吓一跳，也不知道是哪个工作区、哪天的任务在烧钱，更没预算报警。

5. 长任务只能干瞪眼守着

跑一个 20 分钟的任务，你就得开着页面盯着。中途想干别的？不敢。

6. 随手想问个问题，流程太重

“这个函数的签名是啥来着？”——为这一句话，要开浏览器、建会话、等模型。太慢了。

7. 历史会话翻不出来

聊过的内容要靠记忆翻找，没有全文检索。项目做了几个月，早期讨论的内容基本等于丢了。

8. 出门在外，完全失联

Agent 在家里电脑上跑，你出门了，它跑完没、有没有报错、要不要审批——你完全不知道。

说白了：DeepSeek Harness 本身很强大，但它"活在终端里"这件事，让它的体验打了不少折扣。

六、一个能"顺手解决"的方案：DshCockpit

这些痛点一个个攒下来，我一开始只想解决"别老开终端"这一个问题，结果做着做着发现可以做得更多。于是把它开源了出来：

DshCockpit —— 把 dsh web 从"终端里的一个标签页"，变成"双击即用、后台常驻、自动更新、会算账的桌面控制台"。

仓库：github.com/Lxiayu/DshCockpit（MIT，完全本地运行，不收集任何数据）

它的定位和"把 dsh 塞进一个窗口"的简单壳不一样：别的壳做"窗口"，它做"控制台"。每个痛点都有对应解法：

痛点	DshCockpit 的解法
关窗口就断	托盘常驻，关闭窗口后台任务照跑
每次敲命令	双击即用，内置运行时，无需装 Node/dsh
手动升级、坏版本	自动更新管道 + 冒烟测试守卫 + 一键回滚
烧钱没数	成本中心：按天/周/月/工作区统计 + 月度预算 80%/100% 报警 + 峰谷分时计价
token 心里没数	右上角实时 token 胶囊 + 上下文压力 60%/85% 黄红预警
随手问太重	`Ctrl+Alt+Space` 全局热键 Quick Ask，后台跑完弹通知
长任务守着	壳级定时任务（每天/间隔）+ 任务完成/审批/提问系统通知
历史翻不出来	`Ctrl+K` 全历史会话全文检索，片段高亮一键复制
出门失联	v0.2.3 全新：手机远程控制（见下）
数据安全	完全本地 + 自动备份（备份刻意不含密钥）+ 隐私声明

在这里插入图片描述

v0.2.3 新功能：手机远程控制 🎉

这是本版的重头戏。出门在外，也能用手机盯着家里电脑上的 Agent：

手机和电脑连同一个 Wi-Fi，把设置页显示的配对链接发到手机，浏览器打开即用；
手机上能看到完整的 dsh 界面：会话流式输出、发消息/插话、审批工具执行、回答提问——躺在床上也能看着长任务跑完（狗头保命）；
一次配对、长期有效，不用每次扫码输码。

怎么用（三步）

设置 → 手机远程 → 打开「启用手机控制」（即存即生效）；
点「刷新配对码」，把显示的配对链接复制发到手机（微信/短信都行）；
手机浏览器打开链接即完成配对，进入完整界面，之后无需再次配对。

安全设计：为什么敢把 Web UI"暴露"到局域网

这里值得多说几句，因为这是技术上最讲究的部分。

dsh 运行时的 HTTP/WS 面板本身没有任何鉴权、TLS 或 origin 策略——上游设计前提就是"单用户本地服务"。如果图省事直接把运行时绑到 0.0.0.0 暴露到局域网，等于把整个机器的控制权交出去（能建会话、跑 bash、读文件）。

所以 DshCockpit 的做法是：运行时继续只监听 127.0.0.1，壳在内部加一层鉴权网关（默认 0.0.0.0:31780），局域网流量只能到达网关，必须持有有效凭据：

手机浏览器 ──HTTP(兼容模式) 或 HTTPS(自签)──> 壳鉴权网关 :31780
                        ├─ 鉴权：一次性配对码 → 长期 token cookie
                        ├─ HTTP 代理 → http://127.0.0.1:<runtime port>
                        └─ WS 升级  → 原始 TCP 管道（重写 Host/Origin、剥离网关 cookie）

几个关键设计：

一次性 6 位配对码：10 分钟内有效、用后即焚，换取长期令牌；
长期令牌加密存储：经系统 safeStorage 加密（macOS Keychain / Windows DPAPI），不进设置文件、不进备份；
运行时仍只监听 127.0.0.1：手机流量只能到网关，必须带有效 cookie 或来自已配对设备；
cookie 剥离：网关把鉴权 cookie 在转发前剥离，运行时永远看不到鉴权材料，同时把 Host/Origin 重写为运行时同源，适配上游的信任栅栏；
兼容模式（HTTP，默认开）：微信/抖音内置浏览器访问不了自签 HTTPS，所以默认走明文 HTTP 让它们能直接打开；设置页明确提示"勿在公共网络开启"，关闭后回到自签 HTTPS 加密传输；
防爆破：同 IP 连续 5 次配对失败锁定 5 分钟；一键撤销所有设备，已连接手机立即断开；
微信内置浏览器不存 cookie 的兜底：配对的 IP 会话机制，让不存 cookie 的浏览器也能稳定工作；
日志不记录令牌与配对码；配套 100 项单元测试全部通过。

一句话：把"出门也要能控"和"本地数据安全"同时做到了——这是我觉得 v0.2.3 最值得炫耀的地方。

七、怎么安装 DshCockpit

Windows 便携版

去 Releases（github.com/Lxiayu/DshCockpit/releases）下载 DshCockpit-<版本>-win-x64.zip → 用 7-Zip / WinRAR 解压 → 双击根目录的 DshCockpit.exe。

内置 dsh 运行时，无需安装 Node/dsh、无需联网下载，约 9 秒开窗（首次启动初始化 profile 会多花 20–30 秒）；
后续版本自动更新。

macOS 安装包（.dmg）

Releases 里按架构下载：

Apple Silicon（M1/M2/M3/M4）：DshCockpit-<版本>-mac-arm64.dmg
Intel Mac：DshCockpit-<版本>-mac-x64.dmg

双击挂载 → 拖进「应用程序」→ 启动。

⚠️ 当前 macOS 包尚未签名公证，首次打开会被 Gatekeeper 拦截（提示"已损坏"或"无法验证开发者"），应用本身没坏。终端执行一次即可永久放行：
xattr -dr com.apple.quarantine /Applications/DshCockpit.app

从源码运行（开发者/尝鲜）

# 前置：Node.js ≥ 22
git clone https://github.com/Lxiayu/DshCockpit.git
cd DshCockpit
npm install
npm start

首次启动后：① 在 Harness 设置里配好 DeepSeek API Key（右上角齿轮有红点提示）；② 把工作区文件夹拖到右上角工具条；③ 开始对话——右上角胶囊实时显示 token 用量。

八、技术架构（一句话版）

DshCockpit 与 dsh 运行时彻底解耦：运行时版本化共存于 userData/runtime/，互不干扰；接口面刻意做小（spawn 参数、URL 行、HTTP/WS），上游怎么改都不影响壳。所以才能做到"运行时自动更新 + 冒烟守卫 + 一键回滚"这种坏版本绝不激活的稳定性保障。

九、开源 & 社区

MIT 协议，完全本地运行，不收集、不上传、不存储你的个人信息、API Key 与会话内容；
备份刻意不含 API 凭据，运行时下载全程 sha512 校验；
测试从 92 项扩充至 100 项全部通过；首个社区 PR（手机远程控制）也已合入——欢迎你也来提 PR 或 issue；
遇到问题欢迎进交流群反馈，捉虫有奖。

结语

DeepSeek Harness 是一个把"Agent 编程"做成"看得见、可审批、可扩展"的很好尝试，但"活在终端和浏览器里"让它的日常体验打了折扣。

DshCockpit 想做的，就是把这件事补完：双击即用、后台常驻、自动更新、会算账、还能用手机遥控。

如果你也在用 DeepSeek Harness，欢迎试试：

📦 下载：github.com/Lxiayu/DshCockpit/releases
⭐ 如果对你有用，给个 Star 就是最大的支持；发现问题也欢迎提 issue，一起把它磨得更好用。

DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

Google能索引，AI却抓不到

很多技术团队有个错觉：只要Google能正常收录，内容就没问题。但现实是，你的页面在Google搜索结果里好好的，在ChatGPT、Perplexity、Claude的答案里却像从未存在过一样。

DeepSeek技术社区

初识智能体

在过去两年中，几乎所有人都体验过大语言模型（如 ChatGPT、Claude、DeepSeek）的强大能力：写周报、润色邮件、解答编程疑难。被动响应：你问一句，它答一句。如果你的 Prompt 没有写清楚约束条件，它无法主动追问或修正目标。知行脱节：大模型能用流畅的文字告诉你“如何部署一个高可用 K8s 集群”，但它无法替你登录服务器敲下命令、查看报错日志并自动回滚。信息孤岛：大模型的知识止步于预