DeepSeek Harness 全面评测：当「一切皆插件」遇上 DeepSeek-V4

一、它是什么

2026 年 8 月 13 日，DeepSeek 在 GitHub 上创建了一个新仓库：deepseek-ai/deepseek-harness。十天后，它有了 186,694 个 Star、20,709 个 Fork、13,147 个提交。这不是又一个 ChatBot 前端——这是 DeepSeek 官方出品的 Agent Harness（智能体运行框架），代号 dsh。

如果你用过 Claude Code、OpenAI Codex 或者 Cursor 的 Agent 模式，你对「AI 写代码」这件事已经有了直觉。dsh 要解决的问题是同一类，但思路截然不同：它不绑定某个 IDE，不绑定某个前端，甚至不绑定某个模型——它是一个可插拔的智能体运行时，所有能力（模型适配、工具注册、沙箱执行、会话持久化、子代理编排）都是插件，通过配置文件组合。

当前版本 0.1.1-rc.2，MIT 协议，明确标注 developer preview，且不承诺兼容性。换句话说，现在用它在生产环境要冒破坏性升级的风险——但正因如此，它也迭代得极快：最近 30 天有 4,253 个提交，核心团队 10 人，主力贡献者 Tianyi Cui 一人贡献了 5,268 个提交。

二、架构：一切皆插件

dsh 的底层框架叫 Cordis，一个「时空可组合编程范式」的实现。dsh 把 Cordis 源码 vendor 进仓库（不是 npm 依赖），重命名为 @deepseek-ai/cordis，完全拥有框架层——可审计、可打补丁、可 pin 版本。这意味着 dsh 不受上游 Cordis 发版节奏约束，可以随时改框架代码。

插件树

dsh 的运行时是一棵插件树，在启动时从有序的层（layer）组合而成：

Profile：命名组合，定义用哪些 bundle。内置 web（带浏览器 UI）和 headless（纯命令行一次性运行）两个模板。
Bundle：Cordis 配置行和对应代码的分发格式。dsh-base 是所有 profile 的第一层，包含模型适配器、工具、持久化、沙箱、审批策略、设置、凭证、遥测。dsh-web-app 加上浏览器应用，dsh-headless 加上一个无服务的一次性运行器。
Patch：每一层可以覆盖下层配置。profile 的 cordis.patch.yml → home 级 patch → --patch 命令行覆盖。

用 dsh --profile web --dump-config 可以看到实际启动的完整插件树。任何一行都可以被你自己的 patch 替换。

包规模

整个 monorepo 有 229 个子包，全部在 @deepseek-ai/dsh-* scope 下。源码（不含 node_modules 和 .git）约 153MB，TypeScript 代码行数约 46.8 万行。这不是一个小项目——它是一个工程化程度极高的大型系统。

核心包的职责划分：

包	职责	ctx 键
`core/session`	追加式会话事件日志与内存存储	`ctx.sessions`
`core/system-prompt`	Prompt 段和工具 Schema 组装	`ctx.systemPrompt`
`core/tools`	有作用域的工具注册表和受保护的执行管线	`ctx.tools`
`core/agent`	Agent 接口、运行时注册表、事件词汇	`ctx.agents`
`core/agent-loop`	具体的 Agent 循环实现	—

关键设计原则：注册即效果（Registrations are effects）。每个插件的贡献都通过 ctx.effect() / ctx.on() 注册，register() 返回一个 disposer——插件卸载时，它注册的所有东西都会自动撤销。这不是「加个标志位然后到处检查」，而是框架级别的生命周期管理。

三、模型能力

dsh 的 LLM 层是 provider-neutral 的抽象缝（seam），DeepSeek 适配器是默认实现。

DeepSeek-V4 系列

内置三个模型：

模型 ID	名称	上下文窗口	模态
`deepseek-v4-flash`	DeepSeek-V4-Flash	1,000,000	文本
`deepseek-v4-pro`	DeepSeek-V4-Pro	1,000,000	文本
`deepseek-v4-flash-vision-exp`	DeepSeek-V4-Flash-Vision (实验)	1,000,000	文本 + 图片

100 万 Token 的上下文窗口——这是当前公开可用的最大上下文之一。意味着你可以把一个中型项目的全部源码塞进上下文，让模型在完整代码库范围内推理。

默认配置是 thinking enabled + reasoning effort max：每次请求都开启深度思考，推理强度拉满。这是 DeepSeek 对自己模型能力的自信——也是「我们就是 DeepSeek，推理算力不是成本约束」的体现。测试策略里白纸黑字写着：「We are DeepSeek — do not ration real-API tests.」

适配器特性

统一图片管线：master 和 Files API 请求管线已合并，read_image 工具报告缩放后尺寸和坐标比例，附件存储使用确定性规范编码
重试策略：provider-routed 的 LLM 请求重试（llm-retry 包），按 provider 路由不同重试策略
Token 计量：回放感知的 token 测量服务（token-meter），支持 compaction 决策
pi-ai 适配器：llm-pi-ai 是 llm-deepseek 的设计验证孪生，用 pi-ai 后端验证适配器接口的正确性

四、工具生态

dsh 的工具不是硬编码的几个 function call——每个工具都是一个插件包，通过 ctx.tools 注册，模型通过 system prompt 里的 JSON Schema 知道工具的存在。工具目录由代码生成器自动维护（pnpm run gen-tool-catalog），有完整性守卫确保新工具不会遗漏文档。

Shell 执行

bash：本地子进程实现 + 沙箱消费实现（每个命令都经过 ctx.sandbox 约束）
PowerShell：本地 + 沙箱两套，支持 Windows
持久终端：tool-bash-persistent 和 tool-pwsh-persistent，模型面向的 owner 作用域持久终端，由 PTY 服务支撑

文件系统

fs-local：本地文件系统实现
fs-sandbox：沙箱消费实现
fs-observation-policy：文件系统观察策略
tool-fs：模型面向的文件读写工具
tool-fs-search：文件搜索工具（ripgrep 风格）
tool-str-replace-editor：字符串替换编辑器（类似 sed 但更安全，带模糊匹配）

Web 能力

三个搜索引擎可选：

Provider	包	说明
DeepSeek	`web-search-deepseek`	通过 Anthropic 兼容 API 的原生 web_search
Exa	`web-search-exa`	Exa 搜索后端
Perplexity	`web-search-perplexity`	Perplexity 搜索后端

加上 web-fetch-http 做网页抓取。

代码运行时

code-runtime：抽象代码执行缝
code-runtime-python：CPython 子进程实现
code-runtime-worker-thread：Worker 线程实现
e2b：E2B 云沙箱 POC，包含 FS 和 subprocess 适配器

其他工具

LSP：语言服务器协议支持（lsp-stdio），模型可以获取代码补全、定义跳转、诊断信息
MCP 客户端：连接外部 MCP Server，自动把其工具注册到 ctx.tools
Skill 系统：Agent 技能提供者注册表，支持文件系统加载
Todo：任务管理工具
Plan Mode：带用户审查退出机制的计划模式
Goal：事件源的同会话目标状态和生命周期服务
Workflow：JavaScript 编排脚本运行时，通过 ctx.workflowEngine 执行
Schedule：Agent 作用域的持久化定时提醒（after / at / fixed-rate）
Session Query：会话历史查询工具，支持 SQLite 后端

五、子代理与编排

这是 dsh 最有野心的部分——四种子代理后端，可以把任务分派给不同的 AI Agent 运行时：

后端	包	机制
Claude Code	`subagent-claude-code`	通过官方 Agent SDK 的一次性 Claude Code 子代理
Codex	`subagent-codex`	通过官方 app-server 协议的一次性 Codex 子代理
ACP	`subagent-acp`	子进程中通过 Agent Client Protocol 驱动子 Agent
DSH SDK	`subagent-dsh-sdk`	子进程中通过 stdio JSON-RPC 驱动另一个 dsh 运行时

这意味着 dsh 可以作为元编排器（meta-orchestrator）：用 DeepSeek-V4 做主控，把具体编码任务分派给 Claude Code，把推理任务分派给另一个 dsh 实例。每种后端都有对应的 hook 桥接插件（hooks-claude-code、hooks-codex），可以在 dsh 的拦截缝上运行它们的 hook 配置。

最近新增的 Agent Teams（experimental/agent-team）提供了持久化的多 Agent 团队运行时——不只是一次性分派，而是长期协作的 Agent 编排。

六、沙箱与安全

dsh 的沙箱不是「跑在 Docker 里就完事了」——它是一个四平台原生沙箱体系：

平台	机制	说明
Linux	Landlock	自研 Node 原生插件 `landlock-run`，self-restrict-then-exec
macOS	Seatbelt	Apple 原生沙箱
Windows	ACL	受限令牌运行器
通用	bwrap	bubblewrap 容器隔离

landlock-run 是一个独立的 npm 三包族（entry + 平台包），有自己的 CI 构建和发布流程。这不是调一个系统命令，而是写了一个 Node 原生插件来做 Linux Landlock 沙箱——工程深度可见一斑。

沙箱策略（sandbox-policy）支持多种模式：

workspace-write：默认模式，限制在 workspace 内写入
danger-full-access：完全访问（CI/测试用）
每个会话可以独立设置模式和 workspace root

权限审批（user-approval）是另一层：在非 danger 模式下，危险操作会 ask 用户确认。凭证管理（credentials）支持启动时自动升级 pre-release 文档、持久化凭证记录。

七、持久化与会话

dsh 的会话是事件源（event-sourced）的：所有状态变更都是不可变事件，追加写入日志。这带来了天然的时间旅行和回放能力。

存储后端

SQLite：主存储后端，最近优化了持久化布局
JSONL：JSON Lines 格式，用于 ACP 和测试 fixture
两种后端都支持 zstd 压缩

会话能力

投影（Projection）：从事件日志派生视图，带缓存
检查点策略：session-checkpoint-policy
遥测：OpenTelemetry 集成（session-telemetry-otel）
标题生成：LLM 驱动的会话标题（首 prompt 或全 prompt 两种策略）
统计：会话级统计数据
日志导出：会话日志导出工具

Compaction

当上下文窗口逼近极限时，compaction 系统介入：

compaction-basic：token-meter 驱动的压缩策略和 LLM 摘要后端
compaction-tool-result-pruner：工具结果裁剪
command-compact：用户可手动触发的 /compact 命令

八、开发者体验

三种入口

Web UI：dsh web 启动后默认自动打开浏览器（http://127.0.0.1:3080），提供完整的对话界面、模型选择器、设置面板、插件库存、子代理管理
CLI：dsh --profile headless "你的任务" 一次性运行，适合脚本化场景
ACP：Agent Client Protocol，JSON-RPC over stdio，给 IDE 集成用——这是 dsh 作为「被嵌入组件」的接口

Python SDK

dsh 提供了完整的 Python SDK（python/ 目录），通过换行分隔的 JSON-RPC over stdio 与 bundled runtime 通信。可以在 Python 里像调用函数一样驱动 dsh：

deepseek-harness-sdk    # 高层 turns API + 底层 JSON-RPC client
deepseek-harness-runtime-bin  # bundled runtime 二进制和默认配置

配置体系

dsh 的配置是声明式的 cordis.yml。一个典型的配置文件长这样：

- id: llm-deepseek
  name: '@deepseek-ai/dsh-llm-deepseek'
  config:
    thinking: enabled
    reasoningEffort: max
    models:
      - id: deepseek-v4-pro
      - id: deepseek-v4-flash-vision-exp
        inputModalities: [text, image]

- id: sandbox
  name: '@deepseek-ai/dsh-sandbox-local'

- id: bash
  name: '@deepseek-ai/dsh-bash-sandbox'
  config:
    timeoutMs: 60000

配置支持 !!js 表达式（在 plugin config 和 entry disabled 字段下），可以做条件组合——比如根据环境变量切换沙箱模式。HMR（热模块替换）支持开发时改代码不重启。

测试

dsh 的测试策略可能是我见过最严谨的开源项目之一：

单元测试：vitest，每个 registry 都有 HMR 安全测试（dispose 后断言清理）
覆盖率门禁：per-file 100% on packages/*/*/src——不是整体 100%，是每个文件 100%
真实 API e2e：打真实 DeepSeek API 的测试，有 key 就跑，没 key 自跳过
快照测试：keyless，用录制的会话回放，diff JSON-RPC 输出
Web 浏览器快照：Chromium 对比回放的浏览器输出，CI 强制只读 replay

覆盖率 100% per-file 这个要求极其激进——它意味着任何一行未被测试执行的代码都会 block PR。文档里说：「An uncovered line is often dead code the gate is correctly flagging for deletion, not a missing test to bolt on.」

九、实战体验

我在这台 Linux 机器上从源码构建并运行了 dsh。

构建

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

构建过程顺畅，最后产出 200 个 client artifact。Node 版本要求较新（实测 v26.5.1 可用），pnpm 11.7.0。

启动

node apps/cli/lib/bin.js web
# → 监听 127.0.0.1:3080，HTTP 200

启动后 Web UI 可用。模型选择器里有 V4-Flash、V4-Pro 和 Vision 三个选项。界面是深色主题，有侧边栏会话列表、模型选择、设置面板。

实际使用

由于 dsh 需要 DeepSeek API Key 才能真正跑 Agent 循环，我主要验证了：

构建和启动流程是否顺畅 ✅
Web UI 是否正常渲染 ✅
配置体系是否合理 ✅
插件树 dump 是否可读 ✅

十、横向对比

维度	dsh	Claude Code	OpenAI Codex	Hermes Agent	OpenHands
出品方	DeepSeek	Anthropic	OpenAI	Nous Research	社区
架构	一切皆插件 (Cordis)	单体 CLI	单体 CLI	插件式	容器化
模型绑定	DeepSeek-V4（可换）	Claude（绑定）	GPT（绑定）	任意	任意
上下文窗口	100 万	200K	128K	取决于模型	取决于模型
沙箱	四平台原生	无独立沙箱	无独立沙箱	依赖终端	Docker 容器
子代理	4 种后端	无	无	delegate_task	无
消息平台	无	无	无	20+ 平台	无
Web UI	内置	无	无	无	内置
配置方式	cordis.yml	settings.json	config	config.yaml	config.toml
开源协议	MIT	闭源	闭源	开源	MIT

dsh 的独特定位是：一个平台级的 Agent 运行时框架，而不是一个终端用户工具。Claude Code 和 Codex 是「拿来就用」的 CLI，dsh 是「拿来就改」的框架。它的 229 个包和 100% 覆盖率门禁说明它面向的是贡献者和集成者，不是终端用户。

十一、不足与风险

1. Pre-release，破坏性变更

README 里大写加粗：「THERE WILL BE COMPATIBILITY-BREAKING CHANGES.」版本号 0.1.1-rc.2，SQLite 用单调递增的 SCHEMA_VERSION，session 格式版本 0 且不承诺兼容。现在用 dsh 做生产系统，要做好随时升级踩坑的准备。

2. 无消息平台适配

dsh 没有内置 Telegram、Discord、飞书、微信等消息平台适配器。对外接口是 Web UI、ACP（给 IDE）和 API Gateway（给程序化调用）。如果你想通过消息平台用 dsh，需要自己写中间层，或者用另一个 Agent 框架（比如 Hermes）桥接。

3. 文档密度高，入门门槛陡

文档目录有 30+ 篇文章，包括架构、Cordis primer、事件生产者/消费者、防御性模式、postmortem 等。质量很高，但要求读者理解 Cordis 范式、插件效应系统、作用域事件分发——这不是「5 分钟上手」的项目。

4. Node 版本要求新

实测 Node v26.5.1 可用。没有 .nvmrc 或 .node-version pin，但 engines 字段要求 node ^22.19 || >=24。在一些用 LTS Node 20 的环境里可能需要额外配置。

5. 无独立沙箱的竞品对比

虽然 dsh 的沙箱体系很完善，但 Claude Code 和 Codex 依赖的是 OS 级别的权限控制（用户审批、工作目录约束），对大多数开发者来说已经够用。dsh 的 Landlock/Seatbelt/ACL 沙箱更适合高安全要求的部署场景——但这也增加了理解和配置成本。

6. 模型生态封闭

默认只有 DeepSeek-V4 系列适配器。虽然 LLM 层是 provider-neutral 的抽象，但目前只有一个实现（llm-deepseek）加一个验证孪生（llm-pi-ai）。要接 Claude 或 GPT，需要自己写适配器——虽然有 subagent-claude-code 和 subagent-codex 可以做子代理，但主控模型还是 DeepSeek。

十二、总结

dsh 是一个工程深度令人惊叹的项目。从 Cordis 框架的 vendor 策略、四平台原生沙箱、100% per-file 覆盖率门禁、四种子代理后端、到事件源的会话持久化——它不是在做一个 CLI 工具，而是在做一个Agent 运行时基础设施。

它的优势在于：

可组合性：一切皆插件，一切可替换。不想用 DeepSeek 模型？写个适配器。不想用本地 bash？换成 E2B 云沙箱。不想用 SQLite 持久化？换成 JSONL。
工程严谨度：100% 覆盖率、真实 API e2e、快照测试、Web 浏览器 e2e、文档生成守卫——这不是「先上线再修 bug」的项目。
DeepSeek 原生：100 万上下文窗口、thinking 模式、vision 模型——DeepSeek 自己的模型能力在 dsh 里是一等公民，不需要等第三方适配。

它的风险在于：

太新了。10 天的仓库，pre-release，破坏性变更随时发生。
太重了。229 个包、46 万行代码，对于只想「用 AI 写代码」的终端用户来说，Claude Code 或 Codex 的门槛低得多。
太 DeepSeek 了。模型生态封闭，消息平台缺失，作为通用 Agent 框架还需要时间补齐生态。

适合谁：想在 DeepSeek 模型生态上做深度定制的团队、需要高安全沙箱的 Agent 部署场景、想研究「插件化 Agent 架构」最佳实践的工程师。如果你只是想让 AI 帮你写代码，Claude Code 依然是更务实的选择——但如果你想知道「一个理想的 Agent 运行时应该怎么设计」，dsh 值得仔细读。

项目地址：github.com/deepseek-ai/deepseek-harness 版本：0.1.1-rc.2 | 协议：MIT | 评测时间：2026-08-23