DeepSeek Harness 到底改变了什么？从 AI Agent Framework 到下一代 Coding Agent 基础设施

阅读前速览

层级	一句话	你维护什么
Agent Framework	在应用代码里编排 prompt、工具与步骤	Python / TS 调用图
Agent Harness	把工具、文件系统、沙箱、循环挂成可替换插件的运行时	Profile / Bundle / SessionEvent
DeepSeek Harness	基于 Cordis 的 MIT 开源 dsh：Everything is a Plugin	ctx.* 服务 + JSON 工具 Schema

先记住分层：Framework 卖的是链条；Harness 卖的是可替换宿主。模型会换，Seam 与 JSON 契约应该先稳定。

DeepSeek Harness 是什么？

DeepSeek Harness（命令行入口常写作 dsh）是 DeepSeek 官方开源的 Agent Harness：把大模型接到文件系统、终端、网络等真实环境，并驱动它持续工作。核心口号是 Everything is a Plugin——模型适配器、工具、会话、存储、沙箱、调度、UI，全部由插件组装。

它明确不是：

• 新模型：同日发布的 DeepSeek V4 系列是模型层；dsh 是模型之外的那一层。
• 单纯 API 客户端：它管的是循环、权限、会话回放，而不只是发 HTTP。
• 又一个「万能 Agent 类」：没有把一切塞进一个上帝对象；职责拆在 core/session、core/tools、core/agent-loop 等包里。

若你还在把「聊天机器人」和「能跑完多步工作流的运行时」混为一谈，先读 AI Agent 完整指南。Harness 讨论的是后者的宿主形态。

从 AI Agent Framework 到 Harness，到底换了什么？

过去两年，多数团队说的「Agent Framework」是：用链式 / 图式 API 把 prompt、工具、记忆串起来，再在应用进程里跑一个 Agent Loop。产品边界在你的业务仓库；换模型、换沙箱、换审计，往往意味着改核心类。

Harness 把问题倒过来：默认假设没有需要打补丁的特权内核。扩展方式是挂载插件；卸载时，注册的服务与副作用一起回滚。官方文档写得很直白——换模型就换适配器，加工具就注册进统一工具系统，本地执行改远程沙箱就替换 FS / 进程 / 终端 Provider，甚至可以替换整个 Agent Loop，而不重写产品。

• 特权内核 → 插件树：能力以副作用注册进共享 Context，而不是继承一个 BaseAgent。
• 聊天记录 → Session Log：模型看见的一切必须能从日志重建，而不是只剩最终气泡。
• 硬编码沙箱 → Capability Seam：接口、实现、面向模型的工具分三角色，可整层替换。
• Prompt 当产品 → 配置组合：Profile / Bundle / cordis.patch.yml 决定运行时形状。

这一刀切的是「谁拥有运行时」。Framework 时代，运行时通常是业务代码的附属品；Harness 时代，运行时本身是可分发、可审计、可替换的基础设施。

Everything is a Plugin：Cordis 微内核

dsh 建在 Cordis 之上。运行中的 dsh 本质上是一个 Cordis Context：插件向共享上下文贡献服务、类型化事件与可逆副作用。挂载即生效，卸载即回滚——这直接带来可观察与可回放。

部署差异优先写进配置组合，而不是堆一堆 if env == prod。例如用 patch 换模型并挂一个仓库搜索工具：

# cordis.patch.yml — swap model + add a tool
plugins:
  - name: llm/deepseek
    config:
      model: deepseek-v4-pro
  - name: tools/my-repo-search
    config:
      root: ./src

对工程团队，这意味着：产品发布物变成「一组有序 Bundle + 补丁」，而不是「某个不可 fork 的巨型 Agent 类」。插件热替换与 HMR 也因此成为一等公民，而不是演示彩蛋。

Capability Seam：换后端而不换产品

dsh 把可替换能力叫作 Capability Seam（能力接缝）。一条完整 Seam 通常三角色齐全：

1. Service Definition：声明「执行命令 / 读写文件」是什么。
2. Service Provider：本地进程、远程容器或企业执行平台的具体实现。
3. Consumer：通常是面向模型的工具，把能力投影成 Schema 与结果对象。

以 Bash 为例：接口定义「跑命令」，本地 Provider 真正 spawn 进程，工具包负责把能力变成模型能理解的参数与返回值。文件系统与进程 Provider 共享同一执行世界——指向远程沙箱时，Bash、PTY、LSP 一起搬家，而不必给每个工具写远程分支。

面向模型的那一层，仍然是 JSON Schema 形状的工具定义。例如编辑器工具：

{
  "name": "str_replace_editor",
  "description": "Edit a file by exact string replacement",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": { "type": "string" },
      "old_str": { "type": "string" },
      "new_str": { "type": "string" }
    },
    "required": ["path", "old_str", "new_str"],
    "additionalProperties": false
  }
}

这一层和 MCP Tool Schema vs Function Calling、AI 为什么需要 JSON Schema 是同一条纪律：仓库里一份口径，再投影到 Function Calling 的 parameters 或 MCP 的 inputSchema。Harness 不消灭 Schema，它把 Schema 放进可替换的工具注册表。

Session Log：模型看见的，就是记录下来的

Coding Agent 翻车时最痛的问题是：当时模型到底看见了什么？工作区注入、工具结果截断、中途改路由、用户打断——如果只存最终聊天文本，这些全丢了。

dsh 的硬约束是：模型可见输入必须能从 Session Log 重建。用户消息、环境上下文、请求元数据、流式输出、工具调用与结果、压缩事件、权限切换、取消原因，都以 append-only 事件进入会话流。例如一条工具结果事件：

{
  "type": "tool/result",
  "tool_call_id": "call_7f2a",
  "name": "bash",
  "ok": true,
  "content": {
    "stdout": "passed 12",
    "exit_code": 0
  },
  "ts": "2026-09-11T06:12:04.221Z"
}

持久化本身仍是插件（JSONL / SQLite）。Resume 从原会话继续，Fork 从历史边界衍生。调试时，把 SessionEvent 格式化，再和上周能跑通的轨迹做 JSON Diff——这比「再试一次 prompt」更接近生产工程。

Profile、Bundle 与 Turn / Step

一次启动是一层层叠出来的插件树：

• Profile：命名的运行时组合（如 web、headless），带自己的 Bundle 列表与 cordis.patch.yml。
• Bundle：可分发的插件组合；按 Profile 顺序叠加，再套用户与命令行补丁。
• Turn：一次完整任务轮次，可含多个 Step。
• Step：单次模型请求及其触发的工具调用；agent/* 事件可在请求前改写、拦截、审批。

工具执行也不是「有函数名就调」：前置策略、不可逆安全门、执行、后处理、内容清理、结果通知都可挂钩。只读任务可并行；碰到会改状态或安全性不明的调用，就当屏障串行。这是基础设施级调度，不是 demo 里的 for 循环。

四种运行模式：同一宿主，不同工具面

Web UI 提供四种 Agent 预设。它们共享同一个 Harness 宿主，但为当前会话组装不同的工具、提示与能力：

Creation Mode 是「Everything is a Plugin」的极端表达：Agent 可以观察甚至修改自身运行时。生产默认应 fail closed，而不是一上来就开自指工具。

为什么说这是「下一代 Coding Agent 基础设施」？

Coding Agent 要改仓库、装依赖、起进程，权限一开就是生产事故面。dsh 把安全当成基础设施：默认拒绝、策略可挂钩、执行世界可整体迁到沙箱。对团队而言，「下一代」意味着四件事同时成立：

• 可替换：模型、沙箱、UI、循环都能换，不必 fork 整仓。
• 可回放：Session Log 让评测、审计、事故复盘有对象可 Diff。
• 可组合：Profile / Bundle 把部署差异收成配置，而不是分支爆炸。
• 可校验：工具参数与工具结果仍是 JSON Schema 口径，宿主侧继续门禁。

这和「多写几句 system prompt」不是同一条路。把工具与工作流状态收成 Schema，再让 Harness 挂载执行——细节见 JSON Schema 与 AI Agent 工作流。模型会换代；基础设施应该先稳住接口。

和传统 Agent Framework 怎么对比？

不是谁好谁坏，而是你在买哪一层：

你仍可以在 Harness 之上写业务 Agent；只是不要再把「业务编排」和「宿主基础设施」糊成一团。

常见误区

• 把 dsh 当成新模型。 模型是 V4；Harness 是宿主。混谈会导致采购与评测完全错位。
• 为加一个工具 fork 整仓。 正确路径是写插件并挂进 Profile / patch。
• 跳过 Schema 校验。 Harness 管执行管道，不替你免除 arguments 二次解析与校验。
• 忽略 Session Log。 没有事件流，就没有可复现的 Coding Agent。
• 在不信任环境开 Creation Mode。 自指改运行时属于高信任能力，默认应关闭。

FAQ

DeepSeek Harness 是在对标 Claude Code 吗？

公开招聘与早期叙述里确实对标过 Coding Agent 体验。开源后的定位更宽：可组合的 Agent 运行时基础设施，而不只是单一 IDE 产品。

必须用 DeepSeek 模型吗？

默认深度适配 DeepSeek 模型，但架构上模型是适配器插件。换适配器是一等操作；是否覆盖你的厂商，看当前插件生态与你自己的实现。

不会 Cordis 还能用吗？

可以用 npx @deepseek-ai/dsh web 先跑 Web UI。要深度扩展（新 Seam、新工具、新 Profile），就需要理解 Cordis 的挂载与配置树。

这和 JSON / JSON Schema 有什么关系？

工具定义、工具结果、SessionEvent、配置补丁，全是结构化对象。Harness 把它们放进可替换管道；口径仍然靠 Schema。没有 Schema，插件再优雅也只是把半对的对象传得更快。

现在能上生产吗？

官方标注为 developer preview，核心接口会快速迭代并可能破坏兼容。适合基建预研与受控环境；上生产前锁版本、写适配层、把 Session 与 Schema 纳入 CI。

结论

DeepSeek Harness 改变的不是「又一个能写代码的聊天框」，而是把 Coding Agent 从应用内 Framework推到可替换运行时基础设施：插件、Seam、Session Log、fail-closed 安全与 JSON 契约同一套语言。

从今天起，少争论哪家模型更聪明，先把工具 Schema 与执行 Seam 写进仓库。模型会换；宿主接口应该先稳定。

延伸阅读

• AI Agent 是什么？完整指南 运行时、Tool Calling 与 JSON 契约
• AI 为什么需要 JSON Schema Schema / Function Calling / Structured Output
• MCP Tool Schema vs Function Calling 工具 JSON 的协议边界
• JSON Schema 与 AI Agent 工作流 从 Schema 到可编排流水线
• JSONSort 本地工具箱 格式化、校验、Diff
• 全部文章 更多 JSON 与 AI 开发笔记

更新记录： 2026-09-11 首次发布