AI AI Agent DeepSeek Harness Harness Engineering

DeepSeek Harness 快速上手，像拼乐高一样搭建你的 Harness

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

转载请注明出处❤️

你好，我是测试蔡坨坨。

2026 年 8 月 13 日，DeepSeek Harness v0.1 Developer Preview 对外开放测试，并同步以 MIT 协议开源。

我把官网、README 和 quickstart 翻了一遍，感觉它不像一个单纯的 AI Coding 聊天入口，更像一盒 Agent 零件：模型、工具、沙箱、会话、UI、运行循环，都可以拆出来重新拼。

如果你平时主要用 Claude Code、Codex、Cursor 写代码，刚打开 DeepSeek Harness 可能会冒出一句：这不就是一个 Web UI 加命令行吗？继续看文档，味道就变了。它关心的是另一类问题：我们想自己搭一个 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

Tips：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 就能用。模型路由会在下一次请求时生效，不需要重启服务。

如果你的请求要走公司网关、自建 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

这套 profile 设计解决的是组合问题。很多 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 工具强在哪

这里说的“强”，范围要收窄一点。它不一定比成熟 AI Coding 工具更顺手，但如果你关心 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。

这背后其实很现实：做产品开发、做基准测试、做插件实验，需要的工具面和权限面不一样。把模式做成可组合 profile，比在一个大配置里堆开关清楚。

还有一点容易被低估：它优先让你改配置。

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

适合谁用

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

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

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

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

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