DeepSeek Harness (dsh)

DeepSeek Harness（命令行名 dsh）是 DeepSeek AI 开源的 Agent Harness，目标是把「一个能读写代码、执行命令、维护计划并委派子任务的编码智能体」拆成可以自由拼装的插件栈。它建立在 everything-is-a-plugin 架构之上，底层复用 Cordis 的可组合编程模型，官方文档站的自我描述是「用于构建 Agent Harness 的插件化 SDK」。

它同时面向几类人：想直接上手跑任务的开发者，可以一条 npx 命令启动 Web UI 开始会话；想定制自己 harness 的工程团队，可以把 dsh 当作宿主，用官方包与第三方插件重写行为；需要自动化接入的场景，则通过 headless、SDK、ACP 等 Profile 把 dsh 接进已有流水线。需要先明确一点：项目处于 developer preview 阶段，官方在 README 中用大写强调「会出现破坏兼容性的变更」。

核心功能

官方仓库与文档把 dsh 的能力组织在几层：可组合的插件树、面向用户的 Web/桌面入口、面向自动化的 Profile，以及围绕工作区的智能体执行能力。下面几项是文档中明确描述的关键能力。

• 一切皆插件：harness 的行为由插件的有序分层组合而成，官方提供 base、Web、headless、SDK、SDK-minimal、ACP 等多个 bundle，第三方插件通过 profile 的 package.json 以 out-of-tree 依赖形式装入。
• Web UI：启动后默认在 http://127.0.0.1:3080 提供界面，本地启动会自动打开浏览器，SSH 场景只打印访问地址（因为本地转发地址由 SSH 客户端或编辑器持有）。
• 多模型接入：在 Settings → Models 填入 DeepSeek API Key 并保存后，模型路由无需重启服务即可使用；官方另有模型配置指南，覆盖其他服务商与自定义 OpenAI 兼容端点。
• 工作区化的智能体执行：dsh 以启动目录作为默认文件系统位置，但全新 Web UI 需要你先「选择工作区」；选中后智能体可以读取和编辑工作区文件、执行命令、委派工作并维护计划。
• Profile 分层与热重载：一个 profile 目录包含 package.json 与 cordis.patch.yml，最终配置按 bundle 补丁 → profile 补丁 → home 级补丁 → --patch 覆盖的顺序组合；启用 dsh-hmr 后，profile 清单与补丁文件变更会以序列化重载即时生效。
• 自动化与 SDK 入口：dsh --profile headless "job" 用于一次性任务，sdk / sdk-minimal 通过 JSON-RPC 提供 SDK 服务，acp 通过 ACP stdio 对接自动化客户端，官方还提供 Python SDK 指南与反向代理部署指南。

界面与体验

Web UI 是大多数用户的第一入口。按官方使用指南，界面上的核心动线是：在 Settings → Models 配置模型与 API Key，用 Choose workspace 添加并选中项目目录，然后新建会话、在输入框里下达任务。指南特别说明，未选择工作区时会话输入区不可用，这是新用户最容易困惑的一步。

权限与确认也体现在界面里：智能体在读取与编辑文件、运行命令、委派任务时，凡是当前权限策略要求审批的操作，Web UI 都会先请求确认。除浏览器形态外，Desktop 版本是包在 Electron 外壳里的完整 dsh Web 应用，默认监听操作系统分配的端口（因此不会与 Web 的 3080 冲突），窗口关闭只是隐藏，任务会继续运行，可用托盘或再次启动唤回。

官方仓库 README、文档站首页与使用指南中均未提供可用的产品界面截图，本条目的界面描述全部来自官方文字文档，不附截图。

完整使用流程

前置条件：本机需要有 Node.js（官方 README 只写明「安装 Node.js」，未标注最低版本）；需要一个模型凭据，官方指南指向 DeepSeek 平台的 API Key，若使用其他服务商请看模型配置指南；另建议先读一遍仓库里的安全须知，因为这会让智能体在你授权范围内执行命令和访问文件。

第一步：用 npm 启动 Web UI

npx @deepseek-ai/dsh web

命令会启动 Web UI，默认地址为 http://127.0.0.1:3080，本地启动时会自动打开默认浏览器；只想起服务不打开浏览器，追加 --no-open。

第二步：配置模型

1. 打开 Settings → Models。
2. 填入 DeepSeek API Key 并保存。
3. 保存后路由立即可用，不需要重启 dsh 进程。

第三步：选择工作区

点击 Choose workspace，添加你启动 dsh 时所在的项目目录并选中它。只有选中工作区后，会话输入区才会启用。

第四步：跑通第一个任务

新建会话，输入官方指南给出的入门任务，观察它读取文件、给出结论：

Summarize this repository and identify its main packages.

如果任务涉及写文件或执行命令，界面会按当前权限策略弹出审批请求，确认后才会继续。

第五步（可选）：从源码运行或使用其他入口

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

官方说明 pnpm run build 负责准备构建产物，pnpm dsh web 直接使用这些产物而不再重新构建。其他入口包括：

• dsh --profile headless "job"：跑一个全新的持久化会话，打印最终答案后退出。
• dsh --profile sdk / --profile sdk-minimal：以 JSON-RPC stdio 形式服务 SDK 客户端。
• dsh --profile acp：以 ACP stdio 形式服务自动化客户端。
• dsh plugin --profile <name> <pnpm args>：在 profile 目录里转发 pnpm 管理插件。

验证结果

• 浏览器打开 http://127.0.0.1:3080（或 SSH 场景下打印出的地址）能看到 Web UI。
• Settings → Models 中保存的模型在会话里可以正常应答，说明凭据与路由生效。
• 工作区选中后输入区可用，智能体返回的结论与你本机项目实际内容一致，说明文件访问正常。
• 用 dsh --version 可以查看运行时版本；安装与 profile 启动都会用它校验插件的 engines.dsh 或 DSH peer 版本范围。

亮点与差异

多数编码智能体 CLI 把「提示词 + 工具」固化在一个可执行文件里，改行为只能等上游发版；dsh 把同一套能力做成可组合的插件树，入口本身也是 Profile。这意味着同一条安装可以同时是交互式 Web 应用、一次性 headless 任务、SDK 服务端和 ACP 后端。

维度	dsh 的做法	常见单体 Agent CLI
能力扩展	插件 bundle 分层组合，用户补丁可覆盖任意层	通常只有配置文件与少量钩子
入口形态	Web UI、Desktop、headless、SDK、ACP 共用一份 profile 机制	多为单一终端交互界面
配置生效	启用 dsh-hmr 后清单与补丁变更热重载	多数需要重启进程
版本约束	对插件强制校验 engines.dsh / peer 范围，不兼容需精确版本豁免	依赖安装时自行处理冲突

它真正区别于同类工具的地方不是某个功能，而是把 harness 的每一层都交给插件与 profile 决定——代价是配置概念（profile、bundle、patch 层）比一般 CLI 明显更多。

典型使用场景

• 本地仓库问答与改造：选中项目目录后让智能体总结仓库、定位主包、改代码并跑命令。
• 自动化脚本中的一次性任务：用 --profile headless 把任务丢给 dsh，取回最终答案后退出。
• 自建 harness 与插件开发：以官方 bundle 为基线，通过 profile 装入自研插件；官方用 dsh-plugin 话题聚合社区插件。
• 编辑器与其他客户端集成：SDK（JSON-RPC）与 ACP 两个入口用于接入外部客户端与自动化流程。
• 桌面常驻使用：Desktop 版把 Web 应用放进原生窗口，关闭窗口只隐藏、任务继续跑。

定价

项目本身以 MIT 许可证开源，官方仓库没有付费版本或商业授权说明；实际成本主要来自所接入模型 API 的用量。

方案	价格	适合谁
开源版（仓库源码 / npm 包 @deepseek-ai/dsh）	免费，MIT 许可	个人开发者、自建 harness 的团队
模型 API 用量	按所选服务商计费，官方指南指向 DeepSeek 平台 API Key	所有需要真实推理能力的用户

版本与维护状态

项目处于 developer preview，官方强调迭代很快且会有破坏兼容性的变更，安全须知也写明它「未经过安全审计，不应被视为安全或可投入生产」。仓库 README 与文档站没有标注具体版本号；第三方统计显示 npm 上 @deepseek-ai/dsh 的最新发布为 0.1.1-rc.2，GitHub 上的发布标签均为预发布版本，该数字未在官方页面直接确认，仅供参考。

• 维护方：DeepSeek AI（仓库位于 deepseek-ai 组织下）。
• 许可证：MIT，第三方依赖清单见仓库 THIRD_PARTY_NOTICES.md。
• 社区入口：GitHub Discussions 收集反馈与缺陷，另有官方 Discord 社区。
• 文档：使用指南、模型配置、Python SDK、反向代理部署、架构与插件开发文档均在仓库 docs/ 与官方文档站内。

局限与注意

官方安全须知的态度非常直白：这是实验性软件，会执行模型生成的代码与命令、加载第三方插件，并访问网络、进程、凭据和它被授权访问的文件；错误输出、缺陷、误配置、恶意输入或不可信插件都可能损坏主机、改写或删除文件、泄露数据。沙箱、审批提示与权限控制只能降低风险，不能保证隔离。

• 不要把 dsh 当作不可信负载的唯一安全控制；官方建议以最小权限运行，优先放在一次性虚拟机或容器里，并备份可访问的文件。
• 运行前审查插件、配置与待执行命令，不要把敏感凭据随意暴露给它。
• desktop 这个 profile 名被 Electron 端保留，npm 安装的 CLI 会拒绝它的启动与配置导出请求，也拒绝插件管理请求；需要管理 Desktop profile 时用 Desktop 安装的命令。
• 插件的版本兼容是硬校验：不兼容插件需要显式的精确版本豁免，官方文档也提示了豁免带来的风险。
• Desktop 版的应用卸载器不会移除已注册的命令行入口，官方建议卸载前先用菜单里的 Manage dsh Command… → Remove 清理。
• 第三方资料提到 PyPI 上存在同名的 deepseek-harness Python 包，与本项目不是同一工具；该信息未见于官方文档，安装时注意核对包名来源。

常见问题

为什么会话输入框不能输入？

全新的 Web UI 没有默认工作区，需要先用 Choose workspace 添加并选中项目目录，输入区才会启用。

改了模型配置需要重启吗？

不需要。在 Settings → Models 保存后模型路由立即可用；需要接入其他服务商或自定义 OpenAI 兼容端点时，参照官方模型配置指南。

SSH 里启动为什么没有自动打开浏览器？

SSH 场景下本地转发地址由 SSH 客户端或编辑器持有，dsh 只打印可访问地址；想只起服务可以加 --no-open。

为什么 npm 安装的 CLI 不能启动 Desktop profile？

desktop 名称保留给 Electron 维护的 profile，CLI 会拒绝该名字的启动与配置导出，也会拒绝插件管理请求。

装了 Desktop 却找不到 dsh 命令？

命令注册是可选的。在应用菜单的 Manage dsh Command… 里执行 Install（Windows 则从新位置重新 Install），然后新开一个终端再运行 dsh --version。

插件报版本不兼容怎么办？

安装与 profile 启动会根据 dsh --version 显示的运行时版本校验 engines.dsh 或 DSH peer 范围，不兼容的插件需要显式声明精确版本豁免，官方文档写明了相关风险。

产品主页与下载

项目没有独立官网，官方仓库即产品主页；文档站提供构建 Agent Harness 的使用与开发文档。

• 官方仓库（产品主页）：https://github.com/deepseek-ai/deepseek-harness
• 官方文档站：https://deepseek-harness.github.io/deepseek-harness/
• npm 包：@deepseek-ai/dsh，安装或直接运行 npx @deepseek-ai/dsh web
• 发布标签：GitHub Releases
• 反馈与讨论：GitHub Discussions、Discord 社区
• 安全须知：SAFETY.md