BSFC Tech

主题

DeepSeek Harness 上手指南：一条命令跑起你的第一个 Agent ​

2026 年 8 月 13 日，DeepSeek 开源了它的 Agent 框架 DeepSeek Harness（npm 包 @deepseek-ai/dsh，简称 dsh），发布后 12 小时 GitHub star 即突破 5 万。本文从环境准备到首个任务，带你快速跑通它。

一、它是什么 ​

DeepSeek 官方给出的定义很直白：模型 + Harness = Agent。模型是「脑子」，Harness 是「手脚」——聊天机器人交付的是一段话，Agent 交付的是一件做完的事。

DeepSeek Harness 是由 DeepSeek AI 开发的开源智能体框架（agent harness），核心定位与特征如下：

维度说明
定位连接模型与真实系统的「执行框架」，负责工具调用、文件读写、命令执行、任务编排
架构一切皆插件（Everything is a Plugin），由 Cordis 驱动
状态开发者预览版（0.1.0-rc.x），官方明确提示未来会有破坏兼容性的变更
许可证MIT
仓库https://github.com/deepseek-ai/deepseek-harness

关于「Harness（承载管控）工程」的概念体系，可参考本博客的承载管控工程（Harness Engineering）；本文聚焦 DeepSeek Harness 这个具体产品的上手。

二、核心特点 ​

上手之前，先理解它的三个关键设计，能帮你少走弯路。

1. 一切皆插件 ​

模型适配器、工具注册表、会话日志、甚至驱动整个 Agent 运转的主循环本身，都是插件。没有所谓的「特权内核」——你要扩展它，就在其它插件旁挂载一个新插件；插件的注册是「可逆效果」，卸载时会自动回退。官方甚至允许你把整个 Web 前端都换掉。

2. 四种运行模式 ​

从通用到专用，dsh 内置四种 Agent 预设（见第六节详述）。

3. 全程留痕 ​

「模型看到的一切」都会被写入只增不改的会话日志（append-only session log）：系统提示词、思维链、每一次工具调用与返回结果、子代理调度决策。配合「轨迹（Trajectory）视图」，你可以对任意一步做 恢复（Resume）、分叉（Fork）、搜索（Search）、重放（Replay）。这是它和聊天机器人在架构上的根本区别之一：聊天工具只保存最终对话，它保存的是过程里的每一步。

三、环境准备 ​

  • Node.js：仓库声明 ^22.19.0。推荐使用 Node 24 LTS；Node 23 这类奇数版本不在支持范围，会启动失败。
  • 一个 DeepSeek API Key：在 DeepSeek 开放平台 获取。
  • 建议在一个有意选择的空目录/测试仓库中启动（工作目录即默认工作区根目录）。

四、快速上手 ​

4.1 一条命令启动 Web UI ​

最简单的方式，无需安装，直接通过 npx 运行：

sh
npx @deepseek-ai/dsh web

命令会启动 Web UI，默认地址为 http://127.0.0.1:3080，浏览器打开即可。

4.2 全局安装（可选） ​

如果经常使用，可以全局安装：

sh
npm install -g @deepseek-ai/dsh
dsh web

4.3 从源码运行 ​

需要阅读或修改源码时，从仓库构建：

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

4.4 headless 模式（无界面） ​

无需浏览器界面，跑一次任务并输出最终答案：

sh
dsh --profile headless "总结这个仓库并列出主要模块"

该命令会启动一个全新持久化会话，打印最终答案后退出。

五、首次配置 ​

启动 Web UI 后，按以下三步完成首次配置。

第一步：配置模型。 打开 Settings → Models，在 DeepSeek 卡片中填入 API Key 并保存。保存后无需重启服务即可生效。密钥是「只写」的：页面只能看到脱敏描述符，真实密钥存放在 ~/.dsh/.credentials.yaml（$DSH_HOME 目录下）。

第二步：选择工作区。 点击 Choose workspace，添加你启动 dsh 的目录并选中。未选择工作区前，会话输入框不可用。

第三步：跑第一个任务。 新建会话，发送一句任务，例如：

Summarize this repository and identify its main packages.

Agent 会读取并修改工作区文件、执行命令、委派子任务、维护执行计划。凡是在当前权限策略下需要审批的操作，Web UI 都会先向你确认。

首次运行会在 ~/.dsh 下自动初始化配置目录，profile、凭证、设置都在这里。

六、四种运行模式 ​

这是 Harness 最有意思的设计，覆盖了从通用到专用的完整场景。

模式官方标识定位适用场景
标准模式standard全能均衡型，功能最完整默认首选，覆盖 90% 日常需求
Code 模式（PTC）code标准模式 + Code Mode SDK，用 TypeScript 程序组合多步操作批量任务、多步骤重复操作
极简模式minimal仅保留持久 Bash + str_replace_editor模型基准测试，排除工具面干扰
创造模式creator标准模式 + 运行时自省、内存中试插件、预设编写指导打造专属 Agent，面向插件开发者

其中 Code 模式（PTC，Programmatic Tool Composition） 尤其值得关注：原本可能需要 5 轮工具调用才能完成的操作，模型写一段 TypeScript 程序、一次执行即可，中间数据留在执行环境而不进入上下文。对长流程任务而言，省 Token 的效果非常明显。

七、架构初窥 ​

dsh 的一次启动，本质是一棵在启动时按顺序组合出来的插件树。理解下面几个概念，后续自定义与排查会轻松很多。

  • Profile（配置文件）：一个命名的组合，存放在 Harness home 下，列出它叠加的 bundles、安装的插件，以及用户自己的 cordis.patch.yml。web 和 headless 是官方内置模板。
  • Bundle（组合包）：Cordis 配置行与代码的分发格式，保证插入的内容仍可被上层 patch 覆盖。
  • Cordis：底层框架。插件向共享上下文贡献「服务、类型化事件、可逆效果」。
  • Session Log：会话日志是模型看到上下文的唯一来源。deriveMessages() 从日志投影出模型历史，恢复、分叉、回放、遥测、持久化都派生自这条事件流。
  • Capability Seam（能力接缝）：可替换能力的抽象，由「服务定义 + 服务提供方 + 消费者」三方组成。文件系统与子进程提供方共享同一个执行世界，把它们指向远程沙箱，Bash、PTY、LSP 都会随之迁移。

想看你机器上实际启动的插件树，可以用：

sh
dsh --profile web --dump-config

打印出的任意一行都可以通过你自己的 patch 替换。

八、上手注意事项 ​

  1. CLI 只服务本机：官方故意拒绝 --host 0.0.0.0，这是安全设计，不是 bug。
  2. 端口被占用：用 dsh web --port 8090 换端口。
  3. 工作目录即工作区：dsh 使用启动它的目录作为默认文件系统位置，务必在有意选择的目录中启动，不要放在家目录或含无关凭证的目录。
  4. 预览版不稳定：插件名、配置字段、包边界都可能变动。做可复现实验时请锁定版本或 commit，并随时回查官方文档。
  5. 成本可见：每个会话底部有实时统计——本轮几步、模型耗时、输入输出 token、缓存命中率，量入为出。

九、小结 ​

DeepSeek Harness 不是又一个「模型品牌 UI」，而是一套可拆可换的 Agent 运行时：模型适配器、工具、会话状态、执行后端、Agent 循环全部可替换。它更适合想研究 Agent 基础设施、需要混合多模型/自托管端点、愿意接受破坏性变更的开发者；如果你需要的是开箱即用的稳定编码助手，现阶段它仍是一副「毛坯」。

一条命令 npx @deepseek-ai/dsh web 即可开始，接下来就看你用它拼出什么了。

参考资料 ​

Copyright © 2024-2026 BSFC Tech · GitHub · CC BY-NC-SA 4.0