DeepSeek Harness 开源解读：一切皆插件的 Agent 运行底座

2026 年 8 月 13 日晚，DeepSeek 在公布 API 调价后不久，正式发布并开源了 DeepSeek Harness（以下简称 dsh）开发者预览版 v0.1。DeepSeek Harness 是 DeepSeek 官方开发的开源 agent harness（智能体框架，负责把大模型接入文件系统、终端、网页等真实环境并驱动其持续工作），其核心设计被定义为：Everything is a plugin（一切皆插件）。模型、工具、技能、会话、存储、沙箱、调度、UI，所有 Agent 能力都由插件组合而成，可自由替换、灵活重组。项目以 MIT 协议开源，仓库地址为 github.com/deepseek-ai/deepseek-harness。

需要注意的是，这不是一个全新的 DeepSeek 模型，也不是单纯的 API 客户端。官方把 Agent 拆成两个部分：模型是灵魂，harness 负责让模型理解环境、使用工具、在真实场景里持续工作。dsh 是这套“除模型之外的全部”的开源实现，也是 DeepSeek 从模型层向 Agent 运行时层延伸的第一块正式拼图。

一天 6.6 万星

GitHub API 数据（2026-08-14 早）：deepseek-ai/deepseek-harness 仓库创建于 8 月 13 日，发布 24 小时左右即收获约 4.6 万星，次日早晨已超过 6.6 万星、5,596 forks，是近期增长最快的开源项目之一。npm 包 @deepseek-ai/dsh 最新版本为 0.1.0-rc.6，拆分为 20 多个 @deepseek-ai/dsh-* 子包。

项目背景可以追溯到 2026 年 5 月。彼时 DeepSeek 资深研究员陈德里公开招人，称要对标 Anthropic 的 Claude Code 做 “DeepSeek Code Harness”；团队负责人崔添翼随后发文，说团队新成立、人员紧缺，“每天都在面试”。此次开源前，项目已铺垫数月，8 月初部分媒体获得内测资格并提前体验。

与 dsh 同天发布的还有 DeepSeek V4 Pro 正式版，dsh 默认深度适配 V4 Pro 和 V4-Flash 模型。官方明确表示，当前处于开发者预览阶段，核心插件与接口会快速迭代，未来将出现破坏兼容性的变更。

一切皆插件：Cordis 微内核

dsh 最醒目的设计主张是“一切皆插件”，而且是字面意义上的全部。项目建立在 Cordis 微内核之上，运行中的 dsh 本质上是一个 Cordis Context。

Cordis 是 cordiverse/cordis 项目（2022 年创建，GitHub 实测 2,337 星），自称 “Meta-Framework of Spatiotemporal Composability”（时空可组合性元框架），设计思想源自论文《A Programming Paradigm for Spatiotemporal Composability》（一种面向时空可组合性的编程范式，见 cordiverse/paper）。Cordis 的思路是：插件向共享上下文贡献服务、类型化事件和可逆的副作用。新能力通过挂载插件加入，插件卸载时，自己注册的服务和副作用一并撤销。

这套设计带来两个直接结果：

可观测。 每一步状态都能被追踪和还原。

可回放。 多 Agent 协作可以像录像一样回放、调试。

官方架构文档明确写道：“不存在需要打补丁的特权内核”。扩展 dsh 的方式是把插件挂载到其他插件旁边，各项注册都是副作用，会在插件卸载时撤销。换模型就替换模型适配器，加工具就注册到统一的工具系统，换本地执行为远程沙箱就替换文件系统、进程和终端提供方，调整 Agent 行为可以替换整个 Agent Loop，不需要重写产品。

核心包：没有“大 Agent 类”

dsh 的仓库规模很大，包含超过 230 个 workspace 成员，代码分布在 packages/、apps/、examples/、python/、native/、vendor/、website/ 等区域。文件系统、终端、子进程、PTY、语言服务器、网页访问、技能、子智能体、工作流、计划模式、会话持久化、设置、凭据、遥测，几乎每一项能力都有自己的包。

官方架构文档把核心职责拆到不同包，没有一个大而全的 Agent 类包办所有事情：

模型是模型，工具是工具，循环是循环，需要时再把它们拼起来。这种结构体现了一种边界意识：谁拥有接口，谁负责实现，谁把能力呈现给模型，尽量不混在一起。

Profile 与 Bundle：运行配置也能组合

运行中的 dsh 是一棵插件树，由启动时按序叠加的各层组合而成。

profile 是一套命名好的运行组合，存放在 Harness home 中。它列出自己叠放的组合包（bundle），存放自己安装的树外插件，并保存用户自己的 cordis.patch.yml。官方交付了两个模板：web（启动 Web UI）和 headless（一次性运行，不带服务器）。

bundle 是可以分发的插件组合。启动时，Harness 会从空配置开始，依次叠加 profile 指定的 bundle，再应用 profile、用户目录和命令行上的 patch。各层按此顺序应用：先按 profile 列出的顺序应用每个组合包，然后是 profile 的 cordis.patch.yml，然后是 home 级的那份，最后是任意 --patch overlay。

想查看实际启动的配置树，运行：

dsh --profile web --dump-config

这条命令打印出的任何条目，都可以由自己的 patch 替换。部署差异尽量放进配置组合，而不是变成一堆分支代码。

Turn 与 Step：一轮任务的完整生命周期

官方把一次工作拆成 turn 和 step 两个层级。一个 turn 是一轮完整任务，里面可以有多个 step；一个 step 对应一次模型请求，以及这次请求触发的工具调用。

简化后的事件流如下：

turn/start → claim → agent/pre-step → 组装提示词和工具 schema
→ agent/request → llm/stream → assistant/message → tool/call
→ tools/pre-execute → tools/execute → tools/post-execute
→ tool/result → step/end → turn/end

这些事件是给插件提供的具体接入点，模型请求前可以改写或拒绝输入；请求发出时可以拦截；工具执行前后可以加入审批、超时、监控和策略检查。

输入通过同一个 inbox 到达驱动器，有些消息会立即唤醒它；注入的上下文会留在 inbox 中，直到另一条消息将其唤醒。agent/pre-step 决定模型看到什么，监听器可以改写已领取的消息，也可以直接拒绝；首次领取被拒绝或被改写为空时，仍会关闭一个不含步骤的持久轮次，日志会记录这次尝试。

工具也不是“拿到函数名就调用”，它会经过前置策略、不可逆的安全守卫、实际执行、后置处理、内容整理和结果通知。允许或拒绝、超时、重试、指标统计、附加上下文，都可以从流水线的不同位置接入。工具可以声明某类参数下的调用是并发安全的，调度器便会让连续的只读任务并行；一旦碰到修改状态或无法确定安全性的调用，就把它当作屏障，等待前面的任务结束后独占执行。

会话日志：模型可见即已记录

dsh 另一项核心设计是会话日志（Session Log）。项目规定，凡是模型看见的内容，都必须能够从日志中重建，并由一项运行时不变量断言这一点。因此，新增一项模型可见输入就需要新增一个会话事件：扩展 SessionEventMap 并从日志渲染。

用户消息、运行环境上下文、模型请求信息、流式输出、工具调用和结果、压缩事件、权限切换、取消原因，都会以事件形式进入追加式会话流。deriveMessages() 从日志中投影出模型历史，原始 assistant/chunk 事件则保证回放和 UI 保真。fork、恢复、transcript（文本记录）、遥测和持久化都派生自该事件流。

这项原则解决的是 Agent 系统里一个棘手问题：当任务出错时，我们能不能知道模型当时到底看到了什么？如果系统只保存最终聊天文本，许多关键因素会丢失。也许模型请求前刚注入了工作区状态，也许工具结果被裁剪过，也许系统自动切换了模型路由，也许用户在流式输出中途改变了方向。dsh 在请求边界保存足以重建消息的记录，原始流式 chunk 也保留，以便界面和回放维持一致。

会话持久化本身仍然是插件，项目提供 JSONL 和 SQLite 后端，查询能力可以优先访问实时会话，也可以通过 SQLite 全文检索历史记录。Resume 会沿用原会话继续工作，Fork 则从一个确定的历史边界派生新会话。

能力 seam：换后端不换产品

dsh 把可替换能力称为 seam（接缝）。一个 seam 通常有三层：声明接口的 Service Definition、实现它的 Service Provider，以及使用它的 Consumer（通常是面向模型的工具）。

以 Bash 为例，接口定义“执行命令”是什么，本地实现负责真正创建进程，而面向模型的工具包负责把这项能力变成模型可理解的 schema 和结果。文件系统与进程提供方共享同一个执行世界，因此把它们指向远程沙箱，也就把 Bash、PTY 和 LSP 一并搬了过去，无需为每个工具写远程分支。subagent 提供方在同一个接口之后也千差万别，从新建一个子 agent，到把一个轮次委派给另一个产品。

这种设计让替换一个提供方就能改变整个产品的行为，本地 Shell 换成远程容器、云端沙箱或企业执行平台，理论上只需替换实现层，不必重写模型工具和 Agent Loop。

四种运行模式

dsh 的 Web UI 提供四种 Agent 预设模式。它们是基于同一套 Harness 宿主，为当前会话装配不同的工具、提示词和运行时能力：

创造模式是“一切皆插件”最极致的表达。选择这一预设后，Agent 可以检查当前运行时的插件树，并动态挂载或卸载临时插件，在任务完成后卸载。自指 Cordis 工具不会进入标准、Code 或极简模式，作为明确的高级入口提供，官方定位为面向高级用户的高信任模式。

快速上手

前置条件只有 Node.js（≥ 18）。运行：

npx @deepseek-ai/dsh web

该命令会启动 Web UI，默认监听 http://127.0.0.1:3080。也可以在 Web UI 的 Settings → Models 里填入 DeepSeek API key 并保存，模型路由立即生效，无需重启服务。然后选择工作区（workspace），即可开始会话。dsh 进程以调用目录为默认文件系统位置，新 Web UI 需要手动添加工作区。

从源码运行：

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

自动化方面，项目提供 ACP 服务和 JSON-RPC 入口。Python SDK 驱动随附的 JSON-RPC 运行时，让 Python 应用可以启动会话、发送任务、接收通知，而不必直接嵌入 Node 内核。仓库还包含 Code Mode、自指 Cordis、MCP 记忆服务等示例。

安全设计：失败关闭

编程智能体一旦获得文件系统和 Shell 权限，就能修改代码、安装依赖、启动进程，甚至触碰工作区之外的主机环境。dsh 把安全问题当作基础架构问题处理：

• 默认采用 workspace-write 模式，将命令执行和文件修改限制在当前工作区及允许的临时目录中，并配合 ask 审批策略处理需要扩大权限的操作
• danger-full-access 模式存在，但必须由部署方明确选择
• 工具调用经过前置策略、单调安全守卫、执行包装和后置处理。被守卫拒绝的操作不能被后续插件重新放行
• 文件系统、Bash 和子进程共享同一套沙箱策略，避免出现“命令受限制，但文件工具可以绕过去”的割裂边界
• 采用失败关闭原则，系统无法确认隔离机制真正生效时拒绝执行，不静默退化为无保护运行

权限切换、审批请求、工具参数、执行结果和取消原因都会进入 Session Log，为事后审计和问题复现保留依据。

插件生态：发布当天自发成型

GitHub topics 实测：600 多个公开仓库带 dsh-plugin 话题。第三方开发者中心 dsh.so 索引了 490 多个已验证插件。代表性项目：

插件星数来自 dsh.so 与社区文章，发布时间集中在开源后 24 小时内。一个插件生态在项目发布当天自发成型，是“开放插件范式”在 Agent 领域的一次快速验证。

与同类工具的对比

dsh 的差异化在于官方开源加插件范式。Claude Code 和 Codex 都是闭源产品，能力边界由厂商定义；dsh 以 MIT 协议把能力边界交给社区，这是闭源产品难以复制的护城河。

局限与风险

开发者预览阶段。 官方明示未来会出现破坏兼容性的变更，核心插件与接口仍在快速演进，不适合在生产环境锁版本。

学习成本高。 Cordis 插件树、profile/bundle、事件流、seam 等概念有门槛，对初学者不友好。官方文档建议直接用 agent 探索代码库来理解架构。

配置有陷阱。 配置补丁替换的是目标插件的整个 config，不是深度合并。如果只写一个新字段，原有的 API Key、基础地址或其他参数可能会一起消失。

生态早期。 插件虽多但质量参差，多数是 UI 和工具类，深度能力插件还在生长。

技术栈。 项目以 Node.js/TypeScript 为主，与 Python 为主的 AI 社区有隔阂。Python SDK 通过 JSON-RPC 驱动，属于外围接入，不是一等公民。

笔者观点

dsh 的开源意味着 DeepSeek 不再满足于只提供可被调用的模型，开始争夺模型之上的开发者入口。AI 编程是大模型商业化落地最靠前的领域之一。据 Research and Markets 数据，2025 年全球 AI 编程相关工具市场规模约 295.7 亿美元（约合人民币 2,011 亿元），预计 2030 年攀升至 646.8 亿美元（约合人民币 4,398 亿元），年复合增长率约 17.1%。

技术层面，会话日志“模型可见即已记录”的原则解决了 Agent 调试和审计中最痛的问题：任务失败后重试、执行到一半恢复、把会话 fork 出去继续跑，系统首先得回答一个问题，刚才模型到底看到了什么。Cordis 的可观测、可回放能力如果能在多 Agent 协作中真正落地，会推动整个行业的调试标准。

官方在发布页也明确表达：“DeepSeek Harness 仍在开发者预览阶段，核心插件和 API 将继续演进。我们期待与全球开发者一起，用可复用、可组合的开源基础设施探索智能的边界。”

对开发者来说，现在的价值在于研究架构、写插件、跑工作流。执行命令 npx @deepseek-ai/dsh web 即可开始体验；想开发插件，可以从 Cordis 和官方架构文档读起。这个项目后面最值得关注的，是“一切皆插件”最终能把 Agent 拆到多细，又能重新组合出多少种运行方式。

参考来源

• DeepSeek Harness 官方发布页
• DeepSeek Harness GitHub 仓库
• DeepSeek Harness 中文架构文档
• Cordis 项目
• Cordis 论文
• dsh.so 开发者中心
• 第一财经：DeepSeek Harness 预览版来了，AI 编程工具要打响开源之战？
• 百度百家号：DeepSeek Harness 震撼开源：一切皆插件（内测体验）
• UU AI Hub：DeepSeek Harness 深度解析
• StableLearn：DeepSeek Harness 开源：把 Agent 的整套运行底座拆开了