DeepSeek Harness（dsh）上手指南

它到底是什么

先澄清一个最容易混的点：DeepSeek Harness（命令行叫 dsh）不是新模型， 也不是一个 API 客户端。它是 harness——把模型接到文件系统、Shell、代码编辑器、 网页和其他 Agent 上的那一层，同时记录它做过什么，限制它能做什么。

仓库把自己的架构总结成四个字：一切皆插件。这话是字面意思， 连 Agent Loop 本身也是插件。底座是 Cordis 微内核，配套发了论文《A Programming Paradigm for Spatiotemporal Composability》。 跑起来的 harness 本质上是一个 Cordis Context，各个包往里注册服务、事件和能力， 最后由配置文件决定这个 Agent 拿到哪些。

所以文件系统、终端、子进程、PTY、语言服务器、网页访问、技能、子智能体、工作流、 计划模式、会话持久化、设置、凭据、遥测，几乎每一项都有自己的包和自己的接口。 官方那个编程 Agent，更像这套 SDK 的第一个客户，而不是项目的目的。

装上跑起来

装好 Node.js，然后一条命令：

npx @deepseek-ai/dsh web

Web UI 默认服务在 http://127.0.0.1:3080。运行命令的目录会成为默认工作区根目录， 但新装的 Web UI 并没有选中任何工作区——不点一下「Choose workspace」把目录加进来， 下面的输入框一直是灰的。第一次用卡在这一步的人不少。

想从源码跑：

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

配模型

打开「Settings → Models」，填 DeepSeek API Key，保存即生效，不用重启。 Key 对前端是只写的：存完之后页面只拿得到一个脱敏描述符，密钥落在 $DSH_HOME/.credentials.yaml，设置里只留一个引用。

凭据的解析顺序是固定的：先读继承来的环境变量，然后 $DSH_HOME/.credentials.yaml，然后运行目录下的 .env， 最后 $DSH_HOME/.env。托管的那份凭据文件不会被塞进 process.env。

别的服务商走「Add provider」（Anthropic、OpenAI 等自带目录）， 公司网关或自建端点走「Add a custom provider」，填 Provider ID、Base URL、协议、凭据和至少一个模型。 有两个坑值得先知道：

• Provider ID 定了就改不了。请求、已保存的会话、模型默认值、 凭据引用全都用它做键。想改名只能新建一个再删旧的。
• 手填的模型默认按纯文本处理。没有任何办法去问一个端点支持哪些模态， 所以给这类模型发图片会在发出去之前就被拒掉。要开图片，得在 $DSH_HOME/settings.yaml 里给这个模型加一行 input: [text, image]， 表单里没有这个字段。

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]

顺带一提，DeepSeek 自家的 chat-completions 路由本身是纯文本的，配也配不出图片能力。

四种 Agent 预设

Web UI 里有四个预设。它们不是四套独立的 Agent，也不只是换提示词风格—— 底层的模型路由、会话持久化、沙箱和审批是同一套宿主，预设只决定往这个 Agent 里装哪些工具和提示词。

极简模式最能说明这套架构。它的整个系统提示词就是一句You are a helpful software engineer assistant.，运行时上下文快照被关掉， 上下文压缩也不存在，模型手里只有常驻 bash 和 str_replace_editor 两个工具。 而 harness 的其余部分照常在跑，只是没有装进这个 Agent 而已。

配置分层：profile 才是入口

不少报道只提了一个 cordis.yml。实际发布的 CLI 比这个说法具体：dsh 是 profile 的启动器，一个 profile 就是一摞按顺序叠起来的 插件包补丁层，最上面盖着你自己的配置。

最终生效的配置树从空根开始，按这个顺序叠：

1. profile 清单里 dsh.profile.bundles 列出的每个 bundle 补丁
2. profile 自己的 cordis.patch.yml
3. 用户级的 $DSH_HOME/cordis.patch.yml，它压过 profile 那一层
4. 命令行上每个 --patch <path>，按参数顺序

还有个连带的坑：官方有些行的配置是靠表达式读运行时服务的，比如 port: !!js ctx.webStartup.port ?? 3080。你把整个 config 换成字面量， 这个运行时读取就悄悄没了，命令行参数也就压不过文件了。 想看清楚合成出来的树，用 --dump-default-config 和 --dump-config，不用真启动。

TUI 不在包里

报道里常把「Web、TUI、Headless、SDK」并列成四个官方入口。实际盒子里有三个。 终端界面是个外部插件，得自己建 profile 再装：

dsh plugin --profile tui add github:deepseek-harness/turtle-ui
dsh --profile tui

只有 web 和 headless 会在首次使用时按内置模板自动初始化， 别的 profile 名字直接报错，并提示你先装一个包进去。

沙箱与审批

编程 Agent 一旦拿到 Shell 和文件系统权限，就能改代码、装依赖、起进程。 这个项目把它当架构问题处理，而不是在界面上加个确认弹窗。文件写入受沙箱模式管：

落地的后端分平台：Linux 用 bwrap 和 Landlock，macOS 用 Seatbelt，Windows 用 ACL 受限令牌。 隔离强度不是靠假设，而是后端自己上报的事实——full 表示模式承诺的文件效果全都管住了，partial 表示只管住一部分，目前老版本 Landlock ABI 和 Windows ACL 就是 partial。 整个接缝是失败即关闭的：runner 要么返回真正带约束的命令行，要么直接失败， 悄悄降级成无保护执行是被明令禁止的。

界面上那个权限选择器，其实是把沙箱模式和审批策略两个独立开关打包成了命名预设。 默认只有两个：workspace-write（workspace-write + ask）和 danger-full-access（danger-full-access + never）。

还有一个和行业惯例反着来的决定值得单独说：默认一个 MCP Server 都不开。 MCP 客户端是作为依赖发出来的，供补丁层使用，但每个 server 命令都是跑在 Agent 沙箱之外的可执行代码， 所以开哪个得你自己明确写进去。对比一下别家怎么默认装 MCP，这个取舍挺清楚。

会话日志是唯一权威

项目给自己定的规矩是：凡是模型看见过的东西，都必须能从日志里重建出来。 用户消息、运行环境上下文、模型请求信息、流式输出、工具调用和结果、压缩事件、 权限切换、取消原因，全部以事件形式追加进同一条会话流。界面、持久化、恢复、Fork、 遥测和回放都从这一个事件源派生，而不是各自维护一份「差不多对」的状态。

这解决的是智能体系统里一个很难缠的问题：出错的时候，模型当时到底看到了什么？ 只存最终聊天文本的话，请求前刚注入的工作区状态、被裁剪过的工具结果、 系统自动切换的模型路由、用户在流式输出中途插进来的转向指令，全都查不到了。 持久化本身也是插件，提供 JSONL 和 SQLite 两种后端；Resume 沿用原会话， Fork 从一个确定的历史边界派生新会话。

自动化：Headless、ACP、JSON-RPC、Python

接 CI 用 dsh --profile headless "跑一下测试"：接一个任务， 等 Agent 完全停稳，把最后一条非空回复打到 stdout，然后退出。 headless profile 不挂 HTTP 服务、不挂 Web 运行时、不挂浏览器客户端，跑干净了一个监听端口都不开。

需要结构化事件和持续控制的，走 ACP 服务或 JSON-RPC 入口。 Python SDK 驱动的就是随附的 JSON-RPC 运行时，Python 程序可以开会话、发任务、收通知， 不必把 Node 内核嵌进去：

python -m pip install deepseek-harness-sdk
export DEEPSEEK_API_KEY=sk-your-key-here
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1   # OpenAI 兼容代理
# export DSH_MODEL=deepseek-v4-flash

SDK 要 Python 3.10 以上，自带同版本运行时，不需要系统装 Node。 目前支持 Linux x64、Linux arm64，以及 macOS 14 以上的 arm64。

它不做什么

dsh 是跑在你面前这台机器上的编程 harness。这个定位本身就解释了它的边界：

• 没有消息平台。没有 Telegram、Discord、WhatsApp、微信这些入口， 只能通过本地 Web UI、终端或代码去用。
• 不是常驻的。合上电脑它就停了，凌晨三点没人替你接消息，也没有定时任务在跑。
• 是开发者预览版。官方明说会有破坏性变更，迭代速度也确实快，配置格式还会变。
• 默认围绕工作区。整套设计都假定有一个 clone 下来的项目目录，供它读、改、跑命令。

这些不算缺点，是它本来的形状。只不过和「一个常驻的私人助手」是两件事。

和常驻托管智能体怎么分工

两者是互补的。手边仓库要重构、要写代码，用 dsh； 想要合上电脑之后还能在微信或 Telegram 里回你的，那是另一件事。

模型这一层是通的。在 dsh 里试出来 V4 Pro 或 V4 Flash 好用， 同样可以让托管的龙虾 OpenClaw 用同一批模型—— 模型选择器里直接选、用自己的 DeepSeek Key，或者走 OpenRouter。 具体见 DeepSeek V4 Pro 部署教程 和 V4 Flash 详解。

常见问题

DeepSeek Harness 免费吗？

框架本身免费开源，MIT 协议。模型推理不免费——需要自己提供 API Key，用谁的模型就付谁的钱。

它是新模型吗？

不是。它是模型外面那一层运行时。内置 DeepSeek 原生适配器， 也能通过服务商目录或自定义 provider 接 Anthropic、OpenAI 以及任何 OpenAI 兼容端点。

怎么安装？

装 Node.js，跑 npx @deepseek-ai/dsh web，Web UI 在 http://127.0.0.1:3080。然后进「Settings → Models」填 Key， 再选一个工作区，才能开始对话。

支持 MCP 吗？

支持，但默认一个都不开。MCP 客户端是作为依赖提供给补丁层用的； 每个 server 命令都是跑在 Agent 沙箱之外的可执行代码，所以要不要开由你明确决定。

能接微信或 Telegram 吗？

不能。它没有消息平台入口，只能通过本地 Web UI、需要自己安装的终端界面、 一次性的 Headless 命令，或者 ACP / JSON-RPC / Python 接口来用。 要在聊天软件里用，得换常驻托管的方案。

能上生产吗？

按官方自己的说法，还不行。README 标的是开发者预览版，并且用大写强调会有破坏性变更。

相关阅读

• DeepSeek V4 Pro 部署教程
• DeepSeek V4 Flash 0731 详解
• DeepSeek 机器人搭建教程
• Claude Code 使用指南