DeepSeek V4 Pro 昨天发布，DeepSeek Harness（dsh）开发者预览版同步开源。本文从实战演示到源码架构，逐层拆解这套系统的设计哲学与技术细节。

DeepSeek V4 Pro 昨天发布，DeepSeek Harness（dsh）开发者预览版同步开源。这不是又一个 API 客户端，也不是某款模型的专属外壳，它是一个拥有 230+ workspace 成员、基于 Cordis 微内核、奉行 "一切皆插件" 架构的智能体框架。本文从实战演示到源码架构，逐层拆解这套系统的设计哲学与技术细节。

一、先厘清概念：Harness 到底是什么？

在深入代码之前，必须先回答一个容易混淆的问题：DeepSeek Harness 不是新模型，也不是 ChatGPT 式的对话客户端。

它是一套用来构建、运行和扩展智能体的 SDK 与应用框架。默认连接 DeepSeek 模型，但也能一键切换 Anthropic、OpenAI、Kimi、Moonshot 等20+ 家模型提供商；它让模型能够读取项目、修改文件、运行 Shell 命令、管理任务、分配子任务，并通过 Web UI、全屏终端、Headless 命令行或自动化协议（ACP/JSON-RPC）与用户交互。

Harness 这个词的隐喻：原意是马具、线束、约束装置。抽象一层，它的作用是把"模型之力"连接到可工作的机构（文件系统、Shell、浏览器、代码编辑器）上，同时不让这股力量脱缰：记录它做了什么、限制它能做什么、出错时决定重试还是取消。

这或许能解释为什么这个项目的代码量如此庞大。当 Agent 开始同时搜索十个文件、运行测试、接受用户追加指令，并且还要允许随时取消时，"过度设计"很快就会变成"事故调查报告里最想早点拥有的东西"。

二、实战看能力：30 分钟丧尸游戏与"华强买瓜"基准

机器之心团队在 8 月初获得了内测资格，用 DeepSeek-V4-Flash（参数规模远低于 GPT-5.6）驱动 Harness，做了两个 one-shot 演示：

1. 第一人称丧尸射击网页游戏

提示词（仅一句）：

"构建一个第一人称的丧尸射击游戏，需要素材的话你可以在网络下载免费权限的素材。画面好看一点，让游戏能在网页中运行。"

结果：零人工干预，30 多分钟得到一个可运行的成品。从 Trajectory 面板可以看到，Agent 执行了3 个 Turn、127 个 Step，期间自动完成了环境检查（Node.js、Python、网络）、项目规划、素材下载（Poly Haven 纹理）、Three.js 场景搭建、游戏逻辑编写。

2. "华强买瓜"3D 动画复现

在 Andrej Karpathy 用 AI 生成 3D 世界的热潮下，团队让 Harness 基于文本描述复现经典片段。故事剧情和人物关系大体还原。作为对照，同样提示词用 GPT-5.6 sol-xhigh 驱动的 Codex 输出效果明显更差。

这印证了一个关键判断：Harness 的框架能力对模型表现有显著放大作用。好的 Agent 框架不只是"把工具塞给模型"，而是让模型在正确的时机、以正确的方式、调用正确的工具，并在出错时自我修复。

三、架构核心："一切皆插件" + Cordis 微内核

DeepSeek Harness 最醒目的设计主张是"一切皆插件"，甚至连 Agent Loop 本身也被视为插件。

项目建立在 Cordis 微内核之上，运行中的 Harness 本质上是一个 Cordis Context。不同包向 Context 注册服务、事件和能力，最终由配置文件把它们组合成一套可以运行的智能体。

这种架构与常见的"单体 Agent"形成鲜明对比：

维度	传统 Agent 项目	DeepSeek Harness
结构	一台装好的电脑	一块尺寸惊人的洞洞板
模型	硬编码或简单配置	插件化适配器，20+ 提供商
工具	内建函数	接口/实现/消费者三层拆分
界面	单一形态	Web/TUI/Headless/ACP 可切换
存储	各自维护状态	Session Log 事件溯源
安全	代码里写死	策略插件 + 守卫流水线

DeepSeek 真正想创造的，并非某个固定形态的"DeepSeek 编程助手"，而是一种组装智能体的方式。

四、代码解剖：230+ Workspace 的项目结构全景

仓库的体量非常惊人，代码分布在packages/、apps/、examples/、python/、native/、vendor/、website/等区域。核心结构如下：

vendor/          # Cordis 源码（微内核本体）
packages/
  core/          # 脊柱：Session、System Prompt、Tools、Agent、Agent Loop
  api/           # 远程 BFF 组装与 TypeRPC 网关
  llm/           # 模型适配器：Service Definition + DeepSeek 及第三方 Provider
  shell/         # Bash 能力：本地 / PowerShell 实现
  subprocess/    # 子进程能力 + 进程树 Provider
  terminal/      # 持久化终端会话
  fs/            # 文件系统能力 + 策略限制
  lsp/           # 语言服务器：语义级代码导航
  web/           # 网页搜索与抓取
  skill/         # 可复用技能注册表
  subagent/      # 子智能体委派
  workflow/      # 多智能体工作流编排
  compaction/    # 上下文压缩
  context/       # 请求上下文插件
  todo/          # 待办事项工具
  plan/          # 计划模式（状态机）
  guard/         # 循环卫生 + 工具超时守卫
  self-modification/  # 智能体自检/挂载自身插件
  hooks/         # Claude Code / Codex 桥接
  session/       # 持久化：JSONL / SQLite / 投影 / 遥测
  settings/      # 用户设置
  credentials/   # 凭据引用（环境变量 / .env / 加密存储）
  acp/           # Agent Client Protocol 服务器
  interaction/   # 审批 / 权限 / 命令 / ask-user
  sdk/           # JSON-RPC 协议 + TypeScript 客户端
python/          # Python SDK 与运行时
native/          # node-addon（Landlock 沙箱）
examples/        # 可运行的 cordis.yml 示例
.agents/         # Agent 工作流与 Agent Notes
docs/            # 架构文档、Catalog、Cookbook

关键洞察：文件系统、终端、子进程、PTY、语言服务器、网页访问、技能、子智能体、工作流、计划模式、会话持久化、设置、凭据、遥测登顶，几乎每一项能力都有自己的包。

这种"近乎执拗的边界意识"体现在：谁拥有接口、谁负责实现、谁把能力呈现给模型，尽量不要混在一起。

五、能力三层模型：接口、实现、消费者

项目文档把典型能力拆成三层，以 Bash 为例：

• 接口层（packages/shell/）：定义"执行命令"的抽象契约：输入什么、输出什么、错误怎么表示。
• 实现层：本地实现负责真正创建进程；未来可替换为远程容器、云端沙箱或企业执行平台，无需重写模型工具。
• 消费者层：面向模型的工具包，把这项能力变成模型可理解的 JSON Schema 和调用结果。

这种分层意味着：换模型、换存储、换安全策略、加工具，甚至换掉 Agent Loop，都不需要动核心代码。这是一种典型的框架思维，也是"真·开源"的体现，不是放出一份只能官方维护的成品，而是让社区能深度定制。

六、配置驱动：一份 cordis.yml，组装出不同形态的 Agent

插件化架构最终通过 cordis.yml 落到开发者手里。配置文件列出插件名称、稳定 ID 和参数，决定当前 Agent 拥有哪一组能力。

同一套代码可以被组装成完全不同的产品形态：

• 加入 DeepSeek LLM 适配器 + 文件系统 + Bash + TUI → 终端编程智能体
• 把交互界面换成 Web 插件 → 浏览器应用
• 使用 Headless 入口 → 接受任务、完成轮次、打印答案后退出的 CLI 工具
• 换成 ACP 或 JSON-RPC 前门 → 其他程序可调用的自动化服务

配置还支持覆盖层。TUI 和 Web UI 可以共享一份基础配置，再叠加各自的界面插件；个人配置位于最后一层，部署方只需对指定插件做替换。

安全细节：配置允许通过 !!js 读取环境变量（如 DEEPSEEK_API_KEY），但密钥不应直接写入 cordis.yml 或进入会话日志。Web UI 会把密钥写入$DSH_HOME/.credentials.yaml，环境变量和 .env 作为回退来源。

⚠️ 注意：配置补丁替换的是目标插件的整个 config，不是深度合并。如果只写一个新字段，原有的 API Key 可能会一起消失。

七、Agent Loop 深度解析：不是循环，而是一套交通规则

许多早期 Agent 的核心代码可以简化为：

while True:
    response = model.chat(messages)
    if response.has_tool_call:
        result = execute_tool(response.tool_call)
        messages.append(result)
    else:
        break

DeepSeek Harness 当然也做这件事，但把它拆成了严格的生命周期：

1. Turn / Step 语义

• Turn：一次用户输入开启的生命周期。
• Step：一个 Turn 内的单次模型请求及其后续工具执行。

丧尸游戏案例中的 3 Turns / 127 Steps，意味着用户只发了 3 次消息（或系统产生了 3 次顶层任务），但模型与工具之间交互了 127 轮。

2. 请求前组装

系统会组装：

• 稳定的系统提示词
• 当前运行环境快照
• 工具 Schema
• 会话消息历史

3. 工具调用流水线

工具不是"拿到函数名就调用"，而是经过完整流水线：

复制

前置策略 → 不可逆安全守卫 → 实际执行 → 后置处理 → 内容整理 → 结果通知

• 允许/拒绝：权限系统在第一道闸门拦截。
• 超时/重试：可配置的全局或单工具策略。
• 并发调度：工具可声明某类参数下的调用是并发安全的，调度器会让连续的只读任务并行；一旦碰到修改状态或无法确定安全性的调用，就当作屏障，等待前面任务结束后独占执行。
• 指标统计：每个 Step 的延迟、Token 消耗、缓存命中率（如丧尸游戏中显示 Cache hit 99%）。

4. 运行中消息处理

用户在 Agent 工作时发送的新内容，可能是：

• 排队消息：下一轮任务
• 注入上下文：立即补充到当前上下文
• Steering：转向指令，改变当前工作方向

系统通过回执机制确认：某条转向指令究竟在哪一次模型请求中被看到。它不只关心"消息收到了"，还关心"模型究竟在哪一步看到了它"。

八、Session Log：事件溯源作为系统权威来源

DeepSeek Harness 另一个值得关注的设计是 Session Log。

项目规定：凡是模型看见的内容，都必须能够从日志中重建。用户消息、运行环境上下文、模型请求信息、流式输出 chunk、工具调用和结果、压缩事件、权限切换、取消原因等，全部以追加式事件流进入日志。

界面、持久化、恢复、Fork、遥测和回放，不应该各自维护一份"差不多正确"的状态，而应从同一个事件源派生。

这解决了 Agent 系统里最棘手的问题之一：当一次任务出错时，我们究竟能不能知道模型当时看到了什么？

如果系统只保存最终聊天文本，许多关键因素会丢失：

• 模型请求前是否注入了工作区状态？
• 工具结果是否被裁剪过？
• 系统是否自动切换了模型路由？
• 用户在流式输出中途是否改变了方向？

Harness 会在请求边界保存足以重建消息的记录，原始流式 chunk 也会保留，以便界面和回放维持完全一致。

持久化后端：

• JSONL：追加式日志，适合实时写入。
• SQLite：支持全文检索历史记录。
• Resume：沿用原会话继续工作。
• Fork：从确定的历史边界派生新会话。

对开发者而言，这为调试、评估、审计和自动化提供了统一基础。

九、开发者上手：5 分钟跑起来

Harness 目前处于 Developer Preview 阶段，迭代迅速，会有兼容性破坏的变更。但它已经可以通过 npm 一键体验：

方式一：npm 直接运行（推荐尝鲜）

# 需要 Node.js
npx @deepseek-ai/dsh web

默认启动 Web UI，地址 http://127.0.0.1:3080。

方式二：源码构建（适合深度开发）

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

接入第三方模型

Web UI 设置页提供了下拉菜单，直接填入 API Key 即可使用：

• Amazon Bedrock、Anthropic、Azure OpenAI
• Cerebras、Cloudflare、Fireworks
• GitHub Copilot、Google、Groq
• HuggingFace、Kimi、MiniMax、Mistral、Moonshot
• 以及 DeepSeek 自有模型

无需手动编辑配置文件，对开发者非常友好。

十、总结：Harness 想回答什么问题？

总之，DeepSeek Harness 的设计可以概括为三个层面的回答：

层面	问题	Harness 的答案
架构	如何让 Agent 系统可扩展、可定制？	"一切皆插件" + Cordis 微内核 + 能力三层拆分
执行	如何让模型可靠地调用工具、处理并发、响应中断？	严格的 Turn/Step 生命周期 + 工具流水线 + 并发屏障 + Steering 回执
可观测	如何知道模型当时究竟看到了什么？	Session Log 事件溯源，所有状态从同一事件源派生

它不是又一个"AI 编程助手"的竞品，而是一套关于"如何组装智能体"的元框架。230+ 个包看起来庞大，但每一个包都在回答一个具体的问题：文件写入是否越过工作区？取消命令能否真正停止子进程？工具结果是否会污染上下文？会话恢复后怎样重建模型输入？

这些细节，恰恰是当前 Agent 系统从"玩具"走向"生产工具"时必须跨越的门槛。