一、它是什么
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 | 文本 + 图片 |
📝 2026-10-12 更新：DeepSeek 官方 API 已改用
deepseek-flash（DeepSeek-V4.1-Flash，支持图片输入）作为 Flash 模型名。旧名deepseek-v4-flash和deepseek-v4-flash-vision-exp仍可调用，但对应模型已下线，请求会由 V4.1-Flash 处理；deepseek-v4-pro目前对应 DeepSeek-V4-Pro-0813。详见 DeepSeek 官方价格页。另外 dsh 截至 2026-10-09 已发布到dsh-v0.2.1-alpha.2，本文评测基于0.1.1-rc.2。
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