DeepSeek Harness 上手：安装配置与四种模式

 

 

DeepSeek 开源了一个叫 Harness 的东西，不少人点进来就开始啃 Cordis 论文，或者第一天就想把 160 个插件折腾个遍。其实这样效率很低。最快的路径只有一条：把 Web UI 启动起来，配好模型，选定工作区，让它在测试项目里完成第一条任务。

 

这篇文章就按这个思路展开。先解释 Harness 的定位和底层设计，再过一遍安装、模型配置、工作区选择、运行模式、插件体系、轨迹追踪、文件引用和自动化，最后讲安全边界和适用人群。读完之后你应该能回答两个问题：现在要不要装，装完第一步干什么。

 

Agent = Model + Harness

 

DeepSeek 官方给了一个简洁的公式：Agent = Model + Harness。模型负责思考，Harness 负责把模型接到文件、终端、工具、权限、会话、沙箱、子 Agent 和工作流上，让它能够持续做事。

 

 

开发者预览版官方首页，右侧展示了一键启动命令。

 

 

官方首页明确打出的主张是“一切皆插件”。

 

 

GitHub 仓库采用 MIT 许可证，目前仍处在快速迭代阶段。

 

这也是为什么同一个模型放进不同的 Agent 工具里，表现像换了个人。模型本身没变，变的是上下文怎么喂、工具怎么调、权限怎么收、失败后怎么重试、文件怎么读写、子 Agent 怎么分工，这些都由 Harness 决定。LangChain 今年也专门撰文解释过 Agent Harness 的构成，指出模型之外还需要一整套运行环境。

 

 

Harness 是什么：不是新模型，也不只是 Claude Code 替代品

 

DeepSeek Harness（命令名 dsh）是一个开源的 Agent Harness，可以理解成 Coding Agent 的运行底座。它不是 V4-Pro 或 V4-Flash 这类模型，而是把模型接入真实运行环境的那一层。

 

官方当前标注为 Developer Preview，仓库里也提示未来会有破坏兼容性的变化。所以它属于“已经能用、值得研究、但还在高速施工”的开发者产品，别把它当成成熟的企业级成品。

 

一切皆插件：连底层能力都可以替换

 

这套框架最核心的设计不是插件数量多，而是连底层能力也做成了插件。官方列出的可插件化范围包括模型、工具、Skills、会话、沙箱、存储、循环、调度、UI 等。

 

传统软件里写死的部分，在这里尽量被拆成可替换组件。今天你用某套模型适配加本地文件系统，之后想换掉其中一层，不需要把整个 Agent 推倒重写。

 

 

这套插件底盘来自 Cordis，对应论文讨论“时空可组合性”与可撤销副作用。Cordis 负责插件的装载、卸载和依赖管理，具体 Agent 能力放在各插件里。普通用户不必先读论文，但理解这个结构后，就明白它为什么强调可插拔和可组合。

 

五步跑通最小闭环

 

新手被劝退，往往是上来就研究源码、插件机制和各种模式。正确的做法是先跑通最小闭环：

 

 

1. 安装 Node.js。快速体验只需要这一项；如果要从源码开发，再按仓库文档准备 pnpm 和 Corepack 环境。
2. 在终端执行 npx @deepseek-ai/dsh web，Web UI 默认在本地 3080 端口提供服务。
3. 进入 Settings → Models，填入 DeepSeek API Key 并保存。官方文档说明保存后模型路由立即可用，不用重启。
4. 点击 Choose workspace，添加并选中测试项目目录。不选工作区时，会话输入区域不会进入可用状态。
5. 先用 Standard 标准模式，第一条任务只做读取和总结，确认理解正确后再逐步开放写文件和执行命令。

 

 

 

启动 Web UI 后的路线：API Key → 模型 → 工作区 → 运行模式。

 

 

首次启动后添加 API Key 的界面。

 

 

Settings → Models 中配置模型提供方与 API Key。

 

一个现实提醒：DeepSeek 在 8 月 13 日的 API 更新日志里宣布，V4 系列将从 8 月 16 日 16:00 UTC 起调价，并采用峰谷时段计费。照着教程配置时，别把任何文章里的价格截图当作长期价格。

 

 

这是 8 月 14 日时点的价格信息，请以发布当日官方页面为准。

 

主界面先认三个位置

 

 

Web UI 主界面。

 

第一次使用，最需要确认三个点：当前选中的模型、当前工作区、这条会话拥有多大操作权限。工作区决定 Agent 能看到和操作哪些文件；权限决定它能否写文件、运行命令甚至做更高风险的操作。

 

 

工作区选择入口。先用测试目录，别第一天就指向敏感项目。

 

 

模型可在 V4-Flash 与 V4-Pro 之间切换。

 

 

思考强度可选 Off / High / Max，复杂任务再逐步提高。

 

V4-Pro 和 V4-Flash 都可以作为模型来源。日常轻量任务更看重速度和成本，复杂 Agent 任务在意成功率和长链路执行时，再考虑 Pro 和更高的 thinking effort，没必要一上来就全开最高档。

 

四种运行模式：新手记住 Standard 就够

 

 

左侧是真实模式下拉，右侧是四种模式的适用场景总结。

 

标准模式是完整的 Coding Agent，包含文件编辑、Shell、文件与网页检索、Skills、计划、目标、子 Agent 和工作流，绝大多数人直接从它开始。

 

PTC 模式偏重把多步工具操作写成一段 TypeScript 编排；极简模式故意只保留 bash 和文件编辑器，适合做模型基准测试；创造模式面向 Harness 扩展开发，可以检查运行时、试验插件、编写新的 preset。

 

这四种模式传达的意思不是功能分四档，而是同一个 Agent 可以按任务换一套运行配方。

 

插件页：框架的灵魂所在

 

 

设置页的插件列表。

 

从官方截图能看到大量插件处于启用状态。关键不在于数量，而在于插件覆盖了框架本身的关键层：模型、session、API gateway、storage、工具、UI 都能拆开替换。

 

这意味着团队做自己的 Agent 时，不必接受官方预设的全部组合。你可以换掉模型入口、加入自家的工具和权限逻辑，甚至围绕同一个 Harness 为不同岗位做不同 preset。

 

 

GitHub 上的 dsh-plugin 生态已经出现社区项目，插件发现机制正在形成。

 

但眼下也是插件最容易踩坑的阶段。官方安全政策明确提醒：只安装可信且已审查的插件、MCP Server、Skills、Hooks 及其依赖。社区插件看着有意思，不等于可以直接进生产环境。

 

Trajectory：Agent 做了什么必须留下证据

 

 

Trajectory 视图把上下文、工具调用、结果和事件放在同一条可追踪记录里。

 

Agent 一旦能改文件、跑命令、调工具，最怕的情况就是“结果看着还行，但没人知道中间发生了什么”。Harness 的方案是把模型看到的内容与关键事件写入仅追加式会话日志，再在 Trajectory 里按来源查看。

 

官方列出的记录项包括系统提示、推理过程、工具调用与返回、子 Agent 调度、上下文注入等。恢复、分叉、检索、回放也共享同一份事件流。

 

这类能力在个人玩具项目里不起眼，但进入团队协作后会直接影响排错、复现、审计和安全治理。一个 Agent 可不可控，很大程度取决于它有没有留下足够清晰的过程证据。

 

两个顺手细节：@ 引用与自动化

 

 

输入 @ 可以直接选择工作区里的文件或目录。

 

大型项目里“让 AI 自己猜该看哪些文件”经常浪费上下文。更稳的做法是明确 @ 某个目录、配置文件或文档，让它从你指定的材料入手。

 

 

自动化页面可以把一次性 Agent 操作串成持续工作流。

 

自动化让 Harness 不再是“你问一句、它做一次”，而是逐步走向持续任务和工作流，最终可以用在代码检查、仓库巡检、定时任务和重复维护上。

 

 

任务完成后可以在工作区里直接查看 Agent 生成或修改的文件。

 

第一条任务别让它写代码，先做只读体检

 

很多人第一次玩 Coding Agent 就说“把整个项目重构一下”。一旦模型对项目理解有偏差，后面工具调用越多，返工越狠。

 

第一条任务可以直接用这段提示：先只阅读当前工作区，不修改任何文件，也不要运行会改变项目状态的命令。请完成 4 件事：① 用 10 句话以内总结这个项目是做什么的；② 列出主要目录和每个目录的职责；③ 找出启动入口与关键配置文件；④ 给出你认为最需要我先确认的 3 个风险点。输出后停止，等待我确认。

 

这一步对了，再给第二条任务：只修改一个小文件，修改前说明计划，修改后给出 diff 和验证结果。这样能快速验证文件读取、权限、模型理解和工具链是否真正跑通。

 

本地优先不等于数据不出门

 

Harness 定位是 local-first，会话、工具调用记录、附件、文件路径、执行结果等主要在本地环境处理。但只要接入外部模型服务、联网工具、MCP 或第三方插件，数据就可能流向对应的外部服务。

 

更关键的是，Harness 能代表用户在本地计算机上执行操作，权限本身就高于普通聊天框。官方安全使用政策的建议包括：使用虚拟机或容器、限制权限、审查 Agent 生成的代码、避免提供敏感信息、重大操作要求人工确认、把复杂任务拆成更小的隔离步骤。

 

按阶段划分可以整理成：测试阶段用独立目录、虚拟机或容器，不碰生产数据；权限阶段先只读，再逐步开放写入、Shell 和外部网络；插件阶段审查来源、依赖和权限，尤其是社区插件与 MCP；数据阶段客户资料、密钥、商业机密不要默认交给 Agent，外部模型的隐私政策要单独看；发布阶段注意它仍是开发者预览，升级前先看 breaking changes。

 

什么人现在值得装

 

已经在用 Claude Code、Codex、OpenCode 这类工具，并且经常关注模型切换、MCP、Skills、权限、子 Agent、会话和自动化的人，很值得现在装一次，哪怕不当主力，也能看清 Agent 框架层到底长什么样。

 

只想要一个稳定、零配置 AI 编程助手的人，今天不用急。Harness 还在开发者预览期，插件和基础 API 都会继续变化，Windows、第三方网关、插件兼容等问题也会随真实用户增加不断暴露。

 

打算进公司生产环境的话，更不建议全权限加全插件，先测试、锁版本、做权限分层，再决定是否接入正式仓库。

 

最适合现在尝鲜的三类人：想研究 Agent 架构的开发者；长期使用 Coding Agent、想摆脱单一工具绑定的人；想给团队做自定义 preset、插件或工作流的人。

 

模型之外，差距开始在 Harness 层拉开

 

DeepSeek Harness 这次最有意思的地方，不是“DeepSeek 也做了个编程助手”，而是它把模型之外那一层公开摆了出来：工具怎么接、工作区怎么管、权限怎么收、会话怎么存、插件怎么换、运行怎么追踪、任务怎么持续。

 

以后判断一个 Agent 好不好用，模型当然还重要，但你会越来越频繁地问另一组问题：能接哪些工具？上下文怎么管理？出错能不能复现？权限能不能细分？工作流能不能长期跑？这就是 Harness 开始变得重要的原因。

 

把这套开源 Harness 玩明白之后，如果你正在为团队评估企业级 AI Agent 的选型与落地，可以直接找云巴巴聊聊。云巴巴是腾讯云 AI 智能体示范伙伴、腾讯 WorkBuddy 核心伙伴及官方授权服务中心，汇聚了 WorkBuddy、千问办公、TRAE Work 等多家主流 Agent 工具与方案，能结合你的数据边界、任务形态和团队能力，从选型对比、方案验证到陪跑落地提供一站式服务。欢迎咨询云巴巴，获取专属的 Agent 实施落地方案。