AI AI Agent DeepSeek Harness Harness Engineering

DeepSeek Harness 快速上手

蔡坨坨2026-08-152026-08-15

转载请注明出处❤️

你好，我是测试蔡坨坨。

这两天 DeepSeek Harness 开放了开发者预览版，我快速翻了一遍官网、README 和入门文档，第一感觉是：它不是又一个简单的 AI Coding 聊天壳，而是想把 Agent 运行时拆成一套可组合、可替换、可追踪的基础设施。

如果你平时只是用 Claude Code、Codex、Cursor 这类工具写代码，可能第一眼会觉得它也就是一个 Web UI 加命令行。但从文档看，DeepSeek Harness 更想解决的是另一个问题：当我们想自己搭一个 Agent，或者给现有 Agent 换模型、换工具、换沙箱、换 UI、换运行循环时，能不能不要每次都从源码里硬改。

DeepSeek Harness 是什么

DeepSeek Harness，命令行叫 dsh，是 DeepSeek AI 开源的 agent harness。官方给它的核心定位很直接：一切皆插件。

这里的 harness，可以理解为模型外面的那层运行时。模型负责推理，但一个真正能干活的 Agent 还需要很多东西：模型适配器、工具调用、文件系统、Shell、会话存储、权限审批、上下文压缩、子 Agent、Web UI、调度和工作流。

DeepSeek Harness 的思路是把这些能力都做成插件，由 Cordis 插件系统加载。Cordis 内核只处理插件加载、卸载和依赖关系，具体 Agent 能力由插件提供。这样一来，开发者可以在配置层替换或扩展能力，而不是改 DeepSeek Harness 自己的源码。

不过先提醒一句：它现在还是开发者预览版。官方 README 明确写了，后续会有破坏兼容性的变更。所以它现在更适合学习、试验、做内部原型，不建议直接拿去承载稳定生产流程。

快速跑起来

最短路径很简单，先安装 Node.js，然后在你的项目目录执行：

1	npx @deepseek-ai/dsh web

这个命令会启动 Web UI，默认地址是：

1	http://127.0.0.1:3080

有一个容易忽略的小细节：dsh 会把你启动命令时所在的目录作为默认文件系统位置，但新的 Web UI 不会自动选中工作区。也就是说，页面打开后还要手动添加并选中 workspace，不然会话输入框不可用。

Web UI 里基本按这个顺序走：

打开设置里的模型页。
输入 DeepSeek API Key 并保存。
添加工作区，选择你启动 dsh 时所在的项目目录。
新建会话，输入任务。

比如可以先让它做一个只读任务：

1	Summarize this repository and identify its main packages.

当 Agent 要读取文件、编辑文件、运行命令、委派工作或维护计划时，Web UI 会展示对应过程。如果某个操作需要审批，页面会先让你确认。

模型配置

默认场景下，直接在设置页配置 DeepSeek API Key 就能用。模型路由会在下一次请求时生效，不需要重启服务。

如果你不是直连 DeepSeek，而是走公司网关、自建 OpenAI 兼容服务，或者想接 Anthropic、OpenAI 这类提供方，也可以在模型页添加提供方或自定义提供方。自定义提供方需要配置 Provider ID、基础 URL、API 协议、凭据和模型列表。

这里有两个细节值得记一下。

一个是 API Key 的处理。文档里提到，密钥保存后，页面只会收到脱敏描述符，不会收到明文密钥；明文凭据存放在 $DSH_HOME/.credentials.yaml，settings 里只保留凭据引用。

另一个是 Provider ID。它是长期标识，请求、历史会话、默认模型和凭据引用都会用它。如果以后想改名，不是直接重命名，而是新增一个 provider，再删掉旧的。

CLI 不只有 Web UI

dsh web 只是最容易上手的入口。CLI README 里还提到几个模式：

1
2
3

dsh --profile web
dsh --profile headless "run the tests"
dsh plugin --profile <name> <pnpm args>

web 是 --profile web 的别名，适合交互式使用。headless 更像一次性任务运行器，跑完任务后打印最终答案并退出，适合脚本化调用。plugin 模式用于给某个 profile 管理插件，本质上是把参数转发给 profile 目录里的 pnpm。

Profile 是 DeepSeek Harness 里很重要的概念。它不是一个简单配置文件，而是一组插件组合。一个 profile 目录里会有：

package.json，记录树外插件依赖。
dsh.profile，声明按顺序叠加的 bundles。
cordis.patch.yml，保存用户自己的 patch 层。

配置组合的优先级大概是：先叠加 profile 里的 bundle patch，再叠加 profile 自己的 cordis.patch.yml，然后是 home 级别的 $DSH_HOME/cordis.patch.yml，最后是命令行传入的 --patch。

你可以用下面的命令看最终组合出来的配置树：

1	dsh --profile web --dump-config

这个设计很工程化。很多 Agent 工具也能配模型和工具，但 DeepSeek Harness 把“运行时如何拼出来”这件事暴露得更彻底。

Python SDK 适合程序化调用

如果你想把它嵌进自己的程序，而不是一直点 Web UI，可以看 Python SDK。

官方示例的前置要求包括 Python 3.10+、Git、DeepSeek 兼容 API 端点、凭据，以及一个允许 Agent 修改的隔离 workspace。安装大致是：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
. .venv/bin/activate
python -m pip install deepseek-harness-sdk

然后设置环境变量：

1
2
3

export DEEPSEEK_API_KEY=sk-your-key-here
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# export DSH_MODEL=deepseek-v4-flash

运行内置示例：

python examples/jsonrpc-agent/minimal.py \
  --workspace /absolute/path/to/workspace \
  --session-root /absolute/path/to/sessions \
  --session-id example-001 \
  "Inspect the repository and fix the failing tests."

这个示例会把 assistant 的最终回复打印出来，同时把会话日志写到 session 目录。文档里强调，这份 JSONL 日志包含组装后的模型请求与工具调用。

SDK 还有一个比较实用的点：同一个 harness 和 session id 可以保留会话里的 Bash 进程状态，包括当前目录、环境变量和 shell 函数。独立任务应该换新的 session id；只有要延续同一段对话和 shell 状态时，才复用旧 id。

不过官方示例使用的是 danger-full-access，Bash 和编辑器可以修改运行时进程能访问到的任何路径。测试时最好放在可丢弃的 checkout 或容器里。

它比常见 Harness 工具强在哪

这里说的“强”，不是说它在所有场景都替代现有工具。更准确的说法是：如果你关心的是 Agent 运行时的可组合性、可追踪性和二次开发空间，DeepSeek Harness 的设计很有针对性。

我把它和常见几类工具放一起看，会更清楚。

类型	常见形态	DeepSeek Harness 的差异
AI Coding CLI	开箱即用，围绕终端或 IDE 工作	DeepSeek Harness 更强调 profile、插件、配置层和可替换运行时
Agent 工作流框架	用代码编排节点、工具和状态	DeepSeek Harness 把模型、工具、UI、沙箱、会话、循环都纳入插件系统
评测 Harness	跑 benchmark、收集指标	DeepSeek Harness 面向真实 workspace 的持续工作，不只是评测入口
低代码 Agent 平台	UI 友好，适合搭业务流	DeepSeek Harness 更偏开发者基础设施，适合改底层能力

它的第一个优势是插件边界足够底层。

很多框架也有 plugin 或 extension，但通常只是给工具、模型或回调留扩展点。DeepSeek Harness 的拆法更激进，模型、工具、技能、会话、沙箱、存储、循环、调度、UI 都是插件。对开发者来说，这意味着你不是只能加一个工具，而是可以替换某个 Agent 能力本身。

第二个优势是运行可追踪。

官网提到，模型看到的内容会写进仅追加的会话日志，包括系统提示词、工具调用与结果、子 Agent 调度、上下文注入等。在 Trajectory 视图里，可以按来源查看这些信息。对测试同学来说，这点很关键。Agent 出错时，最怕的是只能看到一句“任务失败了”，却不知道它到底看到了什么、调用了什么、在哪一步跑偏了。

第三个优势是运行模式不是写死的。

官方页面列了标准模式、PTC 模式、极简模式和创造模式。标准模式是完整编码 Agent；PTC 模式让模型用 TypeScript 程序组合多步工具调用；极简模式只保留持久 bash 和文件编辑工具；创造模式用于创建自定义 Agent preset。

这几个模式背后其实是同一个观点：Agent 不应该只有一种固定形态。做产品开发、做基准测试、做插件实验，需要的工具面和权限面都不一样。把模式做成可组合 profile，会比在一个大配置里堆开关更清晰。

第四个优势是配置层优先，而不是源码优先。

架构文档里说得很直白，不存在需要打补丁的特权内核。扩展 dsh 的方式，是把插件挂载到其他插件旁边；注册是可逆副作用，插件卸载时会撤销。这种设计对长期维护比较友好。你要换一个模型适配器、替换某个工具策略、调整审批或沙箱，不一定要 fork 主仓库。

适合谁用

如果你只是想找一个马上能帮你写代码的工具，成熟的 AI Coding CLI 或 IDE 插件会更省心。

如果你想研究 Agent 是怎么工作的，或者要在团队里搭一套可控的 Agent Runtime，DeepSeek Harness 更值得看。它把很多原本藏在工具内部的东西拆开了：上下文怎么进模型，工具怎么注册和审批，会话怎么恢复和回放，沙箱策略怎么落到每次执行，UI 和 headless 怎么共享底层能力。

测试同学也可以重点关注两个方向。

一个是可观测性。Agent 的每一次行为都应该能被追踪、复盘和定位，这和我们做自动化测试、链路追踪、问题排查的思路很像。

另一个是可控性。Agent 能访问哪些目录，能不能写文件，什么时候需要审批，哪些工具可以用，这些都不该只靠一句系统提示词约束。DeepSeek Harness 把这部分做成运行时能力和策略层，这比单纯 prompt 约束更靠谱。

小结

DeepSeek Harness 现在还很早，文档也明显偏开发者预览阶段。它的价值不在“今天就比所有工具都好用”，而在它把 Agent Harness 这件事拆得足够工程化。

如果你想快速体验，跑 npx @deepseek-ai/dsh web，配好模型，选中 workspace，就能开始。如果你想深入一点，建议接着看 profile、bundle、Cordis 和 Python SDK。理解这些以后，你会更容易判断一款 Agent 工具到底只是套了个聊天入口，还是认真在做可扩展的运行时。

参考资料：