DeepSeek Harness 实用指南：能力、安装、插件与最佳实践
本文完全由 WorkBuddy 独立收集资料、调试代码并完成文章写作。
我是 Alex Xiang，前百度/微博工程师，现在专注于 AI 工程与工具产品。更多文章欢迎关注微信公众号「字与码」。
距 8 月 13 日开源不过两个月，DeepSeek Harness（dsh）的 GitHub Star 已经涨到约 24.3 万，v0.2 把桌面端装到了 macOS 和 Windows 上，v0.2.1-alpha.1 又把 Claude Code Mods 兼容层试探性地接了上来。热度够了，但现实问题是：官方文档散落在 releases、Discussions 和一堆第三方站点里，想从零上手的人往往卡在两句话上——「先装什么」和「装完怎么配」。
这篇把它当操作手册来写：能干什么、怎么装、插件怎么选、写代码怎么配、代码在 WSL 里怎么配，最后是官方已经说出口的发布计划。命令按官方文档与社区实测整理，版本号以 10 月 3 日的 v0.2.1-alpha.1 为准。dsh 还在 developer preview，破坏性变更是常态，看到对不上的地方请以官方为准。
dsh 到底能干什么
一句话定位：dsh 是 Agent 的「身体」，不是 Agent 本身。它不生产模型，负责的是把模型接进一个能干活、可替换、可观察的运行时。
底座叫 Cordis，核心约束是「一切皆插件」——模型适配器、工具注册表、agent loop、会话存储、沙箱、甚至 UI，全都是插件。这个设计从写第一行代码之前就定下来了，项目负责人崔添翼的原话是：「一切皆插件」是刻在立项之初的产品基因，开源也是初心，不是被迫开源。
由此带来几件实际能力：
- 模型无关。内置 DeepSeek 自家适配器，也带 anthropic、openai、moonshotai、zai 的 provider 目录，还能填任意 OpenAI 兼容端点。默认新会话跑 DeepSeek V4.1-Flash，但换模型只是换一个插件。
- 四种 Agent Preset（运行模式）。装载的插件组合不同，行为差别很大，这是上手第一件要弄懂的事。
- 桌面端 + Web + CLI + Python SDK 四个入口。桌面端开箱即用、内置 dsh 命令，省掉 Node 环境配置——这一条对国内开发者尤其友好。
- 办公能力。能读文档、表格、PDF，生成图表和幻灯片，也能把网页做出来，产出物在会话里归档、侧栏预览。
- 编程能力。文件编辑、Shell、文件与网页检索、Skills、规划、子代理、工作流，一样不缺。
- Trajectory 复盘。模型看到的一切——系统提示、推理、工具调用结果、子代理调度、上下文注入——都写进追加式会话日志，可以按来源检查、搜索、分叉、重放。这解决了 Agent 调试里最难的问题：不是「它答错了」，而是「它当时到底看到了什么」。
- 多 Agent 与自动化。Agent Teams 多智能体协作、可继续对话的子代理、Automation Task 定时任务（关掉应用也继续跑）。
- 插件管理页与 Creator 模式。v0.2 起不用再命令行装插件，输入 npm 包名即可安装、停用、卸载、查看来源；Creator 模式下还能直接对话让 Agent 把插件写出来。
四种模式的差别值得单列一张表：
| Preset | 装载了什么 | 什么时候用 |
|---|---|---|
| Standard | 完整编程 Agent：文件编辑、Shell、文件/网页检索、Skills、规划、目标、子代理、工作流 | 日常主力，九成任务不用换 |
| PTC | Standard 基础上把工具暴露成 TypeScript SDK，模型写一段程序一次性串完多步 | 同一套流程要重复跑很多次时，省往返、省 token |
| Minimal | 只留持久 Bash 与字符串替换编辑器 | 怀疑它偷偷下了什么命令时；也是官方跑基准测试的环境 |
| Creator | Standard 全部能力，外加运行时检查、插件实验与 preset 创作向导 | 自己写插件、做自定义预设 |
一个容易踩的细节：已经发过请求的会话会记住当时那一版模型，不会因为你后来改了默认值而漂移。回头看旧会话时，能确定当初是谁答的。
怎么装：四条路，按你的环境选
先划清一条边界，能省掉半小时的困惑：官方包是 npm 上的 @deepseek-ai/dsh。PyPI 上有一个同名的 Python 包 deepseek-harness（2026 年 5 月就在了），也会装出一个 dsh 命令，但它和 DeepSeek 官方无关。找错包是新手最常见的坑。
四条路径对应的场景：
| 路径 | 适合谁 | 前置要求 |
|---|---|---|
| 桌面端安装包 | 想开箱即用、不想碰命令行 | macOS Apple silicon / Windows x64；自带 dsh 命令，不需系统 Node |
| Web UI（npx） | 只想先试试、或跑在服务器上 | Node.js 22.19+（22.x 线）或 24+ |
| 源码构建 | 要改 dsh 本身、写插件、跟最新提交 | Node、corepack（仓库锁 pnpm@11.7.0） |
| Python SDK | 要把 dsh 当运行时嵌进自己的程序 | Python 3.10+、Git、独立 workspace 与 Harness home |
桌面端。 去 deepseek.com/harness 下载安装包，macOS 与 Windows 各一份。装完第一次启动，按向导填 API Key、选工作区即可。注意 v0.2 没有 Linux 桌面安装包，Linux 只能走 Web/CLI 运行时或 Python SDK。
Web UI，最快的一条。
# 直接跑最新版，默认起在 http://127.0.0.1:3080
npx @deepseek-ai/dsh web
# 想锁定版本就用 @版本号
npx @deepseek-ai/dsh@0.2.1-alpha.1 web起来之后三步：Settings → Models 里粘贴 API Key；添加并选择工作区目录（Agent 只能动这个目录下的文件）；选一个 Preset，把任务丢进去。默认权限策略是 workspace-write，超出范围的动作用审批弹窗拦一道。
源码构建。
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
corepack enable # 仓库锁了 pnpm@11.7.0，用 corepack 对齐
pnpm install
pnpm run build # 发布风格用 pnpm run build:official
pnpm dsh web源码构建会往版本号里塞一个额外标记（7 位提交号，加上 Git 有本地改动时的 dirty 标记）；想要 CI 同款干净产物就用 build:official。更新源码的顺序固定：git pull → corepack enable → pnpm install → pnpm run build，然后 pnpm run typecheck 加一次真实启动来验证。动手拉代码之前，先把当前能跑的 commit 记下来，出问题好回滚。
Python SDK。
python -m pip install deepseek-harness-sdk
export DEEPSEEK_API_KEY="你的密钥"官方运行时会打包到 Linux x64 / Linux arm64、macOS 14+（Apple silicon）、Windows x64。官方明确说 Python SDK 对 Windows 原生支持有限，Windows 建议放到 WSL2 里跑。
一些所有路径通用的约定：配置住在 ~/.dsh（可用环境变量 DSH_HOME 改），凭据存 $DSH_HOME/.credentials.yaml；Web 端的 profile 配置在 $DSH_HOME/profiles/web/cordis.patch.yml；改模型不需要重启服务，下一个请求就生效。dsh —profile headless 「任务」 可以跑一次性任务并打印最终回复，dsh —dump-config 把装配好的插件树打出来——排查「到底加载了什么」用它最省事。
值得先装的插件
第三方插件是 dsh 真正的特色。官方基于 API 口径统计，大约六成用户都在用第三方插件。社区仓库打 dsh-plugin 这个 GitHub topic 的已经上千，星标高的一批集中在下面几类。名单按社区 Star 排序整理，仅供参考——Star 是热度，不是质量或安全背书。
先装入口层。 不管后面装什么，建议第一步就装一个插件市场类插件，把「设置 → 插件市场」打开，之后大部分插件能一键装：
dsh plugin --profile web add dsh-plugin # DSH Plugin Hub
dsh plugin --profile web add dsh-market # 生态入口 / 插件市场能力增强类，这几款被提名最多：
| 插件 | 干什么 | 安装 |
|---|---|---|
| liustack/modlens | 给纯文本模型补上视觉：截图粘进去直接出结构化 JSON（OCR、版面、语义） | dsh plugin --profile web add liustack/modlens |
| DSH-better-sidebar | 开放的侧边栏底座：文件树、真实终端、Git、子代理状态、侧边对话 | dsh plugin --profile web add + 仓库名 |
| dsh-context | 上下文可视化：透视上下文组成、演进、压缩、剪枝事件 | dsh plugin --profile web add dsh-context |
| dsh-agent-teams | AgentTeams 多 Agent 协作 | dsh plugin --profile web add + 仓库名 |
| dsh-plugin（Plugin Hub） | 插件市场本体，看到更新一键升级 | dsh plugin --profile web update dsh-plugin |
| dsh-deep-whale | 鲸鱼娘系列皮肤 | dsh plugin --profile web add + 仓库名 |
| dsh-TUI | 终端党补位：鲸鱼顶栏、实时状态、流式思考、双击 Esc 回滚、上下文进度与 TPS | 见仓库 |
| dsh-routing-suite | 运行时注入器 + 任务感知的推理模式路由预设 | 见仓库 |
| dsh-automation | 在独立会话里按计划调度编码任务，支持多种周期与运行历史 | 见仓库 |
| dsh-approve-for-me | 用规则门控自动审批 Shell/PowerShell 提权，不确定的仍回退人工 | 见仓库 |
官方内置的六个插件也值得知道：Agent Teams、语音输入、Shell、Agent Loop、Subagent、Web Search。语音输入是本地包（约 1 GB，基于 SenseVoice），离线识别，在意隐私的话这是个加分项。
插件从哪装、装哪个 profile 是两件事。dsh plugin —profile web add <包名> 里的 web 是 profile 名，官方 CLI 会把插件参数转发给该 profile 目录里的 pnpm。从 GitHub 直装会跑打包脚本，pnpm 10 以后默认拦截，需要按提示把包加进 ~/.dsh/profiles/web/pnpm-workspace.yaml 的 allowBuilds——这一步等于允许对方代码在安装时在你机器上执行，且不在 agent 沙箱里，务必先看过源码再放行。
用它写代码，怎么配才对
把 dsh 当编程助手用，真正决定体验的是下面这几条。
先选对 Preset。 我的分工是这样：Standard 天天开，多文件重构、改 Bug、写新功能都用它；PTC 留给「每周都要重做一遍」的批量活——比如同时改几十个文件，让它写一段脚本一次跑完，差别是二十次工具往返对一次往返，而每一次往返都要重送一轮上下文；Minimal 当除错工具，Agent 做了个看不懂的决定时，切到只剩一个 shell 的环境重跑，通常十分钟内就能定位是哪一步出的问题；Creator 只在要写插件时开。
工作区边界要划死。 每个项目给一个独立 workspace 目录，别把 Agent 指到重要项目根目录上。默认策略 workspace-write 加审批提示，能挡住大部分误操作，但官方安全声明写得很清楚：沙箱与审批提示不保证隔离。
规则要写下来，不要靠每次嘴说。 把项目约定（构建命令、目录结构、不许碰的文件）固化成 Skills 或项目内的规则文件，比在每次对话里重复描述可靠得多；社区也有 dsh-purge 这类专门管理 prompt 规则与权限补丁的插件。
分工交给子代理和 Agent Teams。 可继续对话的子代理支持消息排队、编辑、删除、单条或全部 Steer 与停止，父任务能控制推进节奏。多 Agent 并行时，按目录或文件划分边界，别让两个 Agent 同时改同一个文件——覆盖冲突是最常见的翻车方式。并发别开太高，很容易撞上 API 限流。
出问题先看 Trajectory，不要靠猜。 会话日志能按来源审查、搜索、分叉、重放，很多「模型变笨了」的怀疑，看一遍它当时收到的上下文就明白了。
模型分工可以发生在同一个界面里。 便宜模型先出粗胚、贵模型收尾，是省额度最直接的办法。dsh 不锁模型，这个分工在同一工作区里就能做，不用换窗口、不用重新指路。
最后一条是纪律性的：pin 版本，别把 alpha 上生产。 dsh 的破坏性变更已经来过好几轮——v0.2.1-alpha.1 就移除了 runtime invariant plugins，Session 数据格式也从 v1 一路升到 V3，升级后不支持降级读取。值得研究，不适合无脑押生产，这句话到今天依然成立。
代码在 WSL 里，怎么配最顺
这条是 Windows 开发者的高频问题，也是最容易配错的地方。核心只有一句话：代码、依赖、工具链要待在同一个操作系统环境里。
先说清一个事实：v0.2 的官方桌面安装包只有 macOS 和 Windows，没有 Linux 版。所以「Windows 主机 + WSL 代码」这个组合有三种跑法，各有适用面。
跑法一：全在 WSL 里跑，Windows 只当浏览器。 在 WSL 里 npx @deepseek-ai/dsh web，然后从 Windows 的浏览器访问 http://127.0.0.1:3080。现代 WSL2 会把 localhost 自动转发到 Windows 侧，通常不用手工配端口映射。要让别的机器也能访问（比如手机、局域网），用 —public-url 指定对外地址，它同时决定显示、打开以及提供给模型的 URL，还支持带路径前缀的反向代理入口。
跑法二：Windows 桌面端 + WSL 插件。 想在同一个桌面窗口里同时用 Windows 和原生 Linux 两套环境，就装 WSL 类插件。社区里这一族已经有好几款，定位各不相同：
| 插件 | 定位 |
|---|---|
| dsh-wsl（npm 包名 dsh-wsl-tool） | 面向模型：直接通过 wsl.exe 跑 Linux 命令，匹配原生 Linux 行为（真实内核与 bash、退出码与信号、超时、输出截断、后台作业），另带路径转换与环境探测工具 |
| dsh-plugin-wsl-env | 让会话整个跑在某个 WSL 发行版里：ctx.shell、ctx.fs、GUI 终端都由发行版内部提供，用 bubblewrap 做沙箱 |
| dsh-wsl-projects | 每个项目一个 WSL2 内的 web server，从 Windows 应用面板启动、停止、打开 |
| dsh-wsl-native | 在同一个 Windows 桌面窗口里用 Windows 与原生 Linux 对话，支持环境切换与双向互操作 |
| dsh-wsl-distro | 结构化获取 WSL 发行版信息，区分「默认发行版」与「会话所在发行版」，内置 UNC 路径安全 |
装 dsh-wsl 时有个坑要记住：插件在 Bundle 加载时会自动全局注册 tool-wsl，不要在 preset 里再手动列一遍，重复注册会直接报错。
跑法三：源码装在 WSL 里，从 WSL 起服务。 要读 dsh 源码或写插件时用这条。git clone 到 WSL 的 Linux 文件系统里，之后所有构建都在 WSL 内完成。
几条硬纪律：
- 代码放 Linux 文件系统，不要放
/mnt/c或/mnt/d。跨文件系统访问会同时拖慢 Git、依赖安装和构建，Windows 与 WSL 之间的 inode 差异也会带来莫名其妙的错。 - Windows 和 WSL 各自跑一遍
pnpm install和构建。原生二进制和链接在两个系统里不一样，不能共用一份 node_modules。 - 凭据不要提交。真实密钥放仓库根目录的
.env并加进.gitignore，从环境变量读。 - 拉代码前先记下能跑的 commit。源码更新出问题时，这是唯一的回滚参照。
- 怀疑「改了没生效」先怀疑构建。确认
pnpm run build真的跑完了，再看pnpm run typecheck，最后从源码起一次验证。产物目录的 mtime 和运行时版本号要能对上，否则你跑的还是旧产物。 - 插件用内置 Plugin Hub 更新，不要跟着源码一起滚。源码路径管 dsh 本体，插件是另一套命令。
最近和接下来的发布计划
先说已经发生的。从 8 月 13 日到 10 月 3 日，节奏几乎是每两天一个版本：
| 时间 | 版本 | 关键变化 |
|---|---|---|
| 8 月 13 日 | v0.1.0 | MIT 开源，developer preview，插件架构亮相 |
| 9 月 25 日 | v0.1.7-rc.1 | 官方桌面预览包（Electron）上线 Windows / macOS |
| 9 月 28—29 日 | v0.2.0-rc.1 / rc.2 | 桌面端就绪 |
| 9 月 29 日 | v0.2 公测 | 插件管理页、Automation Task 定时任务、Creation 模式；文件与 diff 预览重做 |
| 10 月 3 日 | v0.2.1-alpha.1 | 实验性 Claude Code Mods 兼容层；「让 Agent 创建插件」入口；开发者工具包 |
v0.2 里值得单独记一笔的是插件管理页：过去装插件必须命令行，现在输入 npm 包名就能装、停用、卸载、看来源，第三方插件的门槛一下降下来了。同版本还带了四个实验特性：Agent Teams、自动授权审查、Automation Task、语音输入。
再看官方已经说出口的路线图。v0.2 发布时公布的方向有这几条：
- 更强的沙箱与安全能力
- 增强的 Agent Teams 多智能体协作
- 个性化长期记忆
- 浏览器与其他 GUI 应用的自动化操作
- 远程访问与手机访问
- 会话分享与多人协作
- 官方插件市场，以及更稳定的插件 API
- 针对 Harness 环境专门调优的模型
把这些方向连起来看，能读出一个很清楚的产品意图：沙箱和安全排在最前面，是因为「让模型在自己电脑上跑代码」这件事的信任成本最高，而这恰恰是 dsh 想赢下的场景；长期记忆、GUI 自动化、远程与手机访问，则是把它从「一个编程工具」往「一个常驻的 Agent 运行时」推。至于插件市场和稳定的插件 API——官方自己承认插件生态是核心特色，同时也知道「接口天天变」会劝退插件作者，这两条本质是在给生态补基础设施。
需要提醒的是，路线图是方向，不是排期。以两个月从 v0.1 冲到 v0.2.1、破坏性变更常态化的节奏看，任何一条落地时都可能带着新的不兼容改动。
风险与冷思考
热度归热度，几件事必须单独拎出来。
一，preview 不是口号。官方 README 用大写提醒会有破坏兼容性的变更，安全声明也写明软件没做过安全审计。Session 格式 v1→v2→V3 不支持降级，v0.2.1-alpha.1 移除 runtime invariant plugins，都是现成的例子。
二，插件等于可执行权限。Mods 走 dsh 自己的配置加载，没有沙箱，装一个插件约等于给它可执行权限。GitHub 直装还要放行安装期脚本。装之前读 manifest、看 install 脚本、确认权限范围，是必须做的功课，不是可选项。
三，本地 Web 界面的历史教训要记住。8 月底修掉的那个沙箱逃逸漏洞（CVE-2026-82533，VulnCheck 评 9.4）就是因为本地 Web 界面信任请求的 Host 头、且不需要认证，被诱导文本就能把会话切成 danger-full-access。修复方式是启动时发一次性 token、浏览器换签名 cookie。要跑 Web 端，至少要跑到 0.1.2-alpha.2 之后的版本。
四，别把「开放」读成「成熟」。插件上千不代表生态健康，Star 高不代表能稳定运行，官方也没有审核机制。开放和成熟之间隔着很长一段工程。
写在最后
dsh 最有意思的地方，不是它现在多好用，而是它试图定义一种 Agent 的组装方式：模型是灵魂，Harness 是身体，插件是器官。谁能把这个身体做成标准，谁就能在模型层之外再建一层生态壁垒。
对普通开发者来说，今天最划算的用法是把它当成一个可研究、可拆装的 Agent 运行时：读懂 Cordis 怎么把 agent loop 都做成插件，比记住某个 CLI 的几条命令耐用得多——前者是结构认知，不会因为版本更新而作废。
本篇的命令与版本信息整理自 DeepSeek Harness 官方仓库与发布说明、官方产品页，以及社区的插件清单与实测记录，时间截至 2026 年 10 月 8 日。项目仍在开发者预览期，请以官方最新文档为准。
本文同步发布于 zicode.com（字与码）。
微信公众号
欢迎关注「字与码」
如果这篇文章对你有用，也欢迎在微信里继续关注后续更新。
X / Twitter
关注 @ax2_zicode
更即时的技术观察、新文章提醒和一些短想法会发在 X 上。