别再把 DSH 当聊天框：一张图讲透 DeepSeek Harness 的五层架构

真正难的不是“接上一个模型”，而是让模型能被接入、被约束、能调工具、能恢复、也能被企业接管。DSH 的答案不是堆功能，而是把 Agent 系统拆成五层。

“大模型负责决定下一步；Harness 负责让这一步在真实世界里可靠地发生。”

这两年，很多团队做 Agent 时都会经历同一个阶段：先做一个聊天页面，接上模型，再接几个工具。演示很快就能跑起来。但当任务开始跨越多轮推理、文件修改、命令执行、审批、会话恢复和企业系统集成时，系统会迅速变成一团难以维护的胶水代码。

DeepSeek Harness，简称 DSH，值得研究的原因不只是它来自 DeepSeek，而是它把“如何运行一个 Agent”拆成了一套很明确的工程结构：启动时如何组装，任务如何进入，任务如何循环执行，能力如何替换，事实又如何持久保存。

先给结论：DSH 更像一个可组合的 Agent 运行底座，而不是一个固定形态的聊天产品。它的核心不是“多一个模型”，而是把模型、工具、权限、会话、入口和存储都做成可替换、可组合的部件。

一、先看全局：五层不是技术分层，而是五个必须回答的问题

下面这张图是基于 DSH 当前源码整理的学习版架构图。阅读时不要把它理解成一次请求必定从上到下穿过的传统分层架构，更准确的理解是：它按职责把一个 Agent 系统拆开。

图：DSH 学习版架构图。发布前请将本地图片路径替换为已上传的微信素材图片 URL。

二、第一层：Profile 决定“启动哪一种 DSH”

很多人第一次看到 DSH 的命令会以为 dsh web只是“打开一个网页”。实际上，它等价于选择一个名为 web的 Profile：这份 Profile 规定了这次应用需要的插件组合与配置。

把 Profile 想成“运行配方”：

web：浏览器交互；headless：终端跑一次任务后退出；sdk：给 TypeScript 或 Python 程序调用；acp：给自动化客户端持续管理 Agent。入口不同，背后的 Agent、模型、工具和 Session 能力可以共享。

Profile 之后是 Bundle 和 Patch。Bundle 提供一批默认插件；Patch 则像“启动时的配置覆盖层”，可以替换某个插件的完整配置，或插入新的插件条目。它不是 Git patch，也不是改源码，而是改变本次启动实际加载的插件树。

这带来一个企业级价值：同一个 DSH 核心，可以为研发助手、知识助手、运维助手分别准备不同 Profile。区别不应只停留在提示词，还可以落实到工具集合、模型路由、文件访问、审批和外部系统连接方式上。

三、第二层：同一个 Agent，可以从五种“门”进来

DSH 并不假设用户一定坐在网页前。它把“任务如何进入系统”单独做成接入层：浏览器、SDK、命令行、ACP、Webhook 和桌面应用，都可以把任务交给同一套 Agent 系统。

这里最值得注意的是：接入方式不决定 Agent 的“智力”，而是决定谁能发起任务、如何传输状态、谁拥有交互界面。Web 页面只是 Client；真正持有模型凭据、文件权限、工具执行和 Session 的是 Host 端进程。

四、第三层：Agent Loop 才是 DSH 的执行中枢

如果说模型是“大脑”，Agent Loop 就是项目经理和执行调度器。模型只能产生文本或提出工具调用；Agent Loop 负责接住这些决定，把它们变成真实、有顺序、可取消、可记录的任务过程。

图：一次用户任务的默认执行主路径。发布前请将本地图片路径替换为已上传的微信素材图片 URL。

DSH 用 Turn 和 Step 两个概念管理任务。一个 Turn 是用户交给 Agent 的完整工作，例如“定位测试失败、修复代码并验证”。一个 Step 则是一次模型请求，加上这次请求产生的工具执行。

一个真实任务可能这样推进：Step 1 读取日志和源码；Step 2 修改文件；Step 3 再跑测试；Step 4 向用户说明结果。它们属于同一个 Turn，却不一定是同一次模型调用。

这一层还有三个经常被忽略的工程点。第一，提示词、工具 schema、运行时上下文会在请求前被组装。第二，模型调用前会解析实际的 Provider 与模型参数。第三，工具调用不是模型说了就直接执行，它会先经过统一的执行流水线。

从源码设计看，Agent Loop 还管理输入队列、创建或恢复会话、取消、并行安全工具的并发上限，以及独占工具的顺序屏障。这里的重点不是“让模型多想一步”，而是“让每一步都有可观察的生命周期”。

五、工具不是函数列表：它是一条受控的执行流水线

在一个简单 Demo 里，工具通常就是一段函数：模型调用，函数执行，结果返回。DSH 的工具系统更像一条管线：

tool/call → pre-execute → approval / guard → execute → post-execute → tool/result

这意味着“模型建议执行命令”与“命令真的开始跑”之间，仍可以插入权限询问、不可绕过的守卫、超时、重试、文件修改意图检查和结果重写。工具结果被结算后，才作为 tool/result写入会话，并成为下一次模型调用的依据。

这正是 Agent 系统与普通对话系统的分水岭：Agent 的风险并不主要来自回答得对不对，而来自模型能否把回答转化为不可逆的真实动作。把策略放在工具管线里，才有机会统一处理权限、审计和失败。

六、第四层：能力接口把“会做什么”和“在哪里做”拆开

第四层最容易被术语吓住。它的核心只有一句话：工具不应该绑定某个具体执行环境，而应该依赖能力接口。

Consumer → Service Definition → Provider

工具或其他使用者 → 能力接口 → 具体实现

以 Shell 为例：面向模型的 bash 工具是 Consumer；ctx.shell是 Service Definition；本机 Bash、PowerShell 或远程沙箱实现是 Provider。这样，Agent 只需表达“我要执行一个 Shell 命令”，而不必知道它究竟在开发者电脑、容器还是远程执行环境中运行。

这套拆分覆盖了文件系统、Shell、子进程、持久终端 PTY、LSP、网页检索、Skill、Subagent、后台 Jobs 和 Workflow。它让企业能够以更低成本替换底层实现：例如将本地文件和进程能力整体迁移至隔离环境，而不是为每个工具各写一套远程版本。

但能力越强，越需要治理。文件系统和进程必须处在同一个执行世界：如果 Agent 在远程环境运行测试，却在本地环境修改文件，模型看到的代码与测试的代码可能根本不是同一份。这个看似细小的工程约束，决定了 Agent 是否可靠。

七、第五层：Session 不是聊天记录，而是 Agent 的事实账本

DSH 最有工程味的设计之一，是把 Session 定义为仅追加的事件日志。它记录的不只是用户和助手说了什么，还包括 Turn、Step、系统消息、模型结果、工具调用和工具结果。

DSH 的关键原则：模型可见，即已记录。

任何进入模型请求的内容，都必须能从 Session 日志重建。下一次模型调用看到的历史，是从日志派生出来的，而不是临时从内存里拼出来的。

这条原则让恢复、回放、分叉、追踪和 UI 状态有了统一事实来源。DSH 随后把这份事实分成三类消费方式：Persistence 将事件落到版本化 JSONL；Projection 将日志增量折叠为“当前任务正在做什么”；Query 为历史检索和全文搜索建立查询能力。

因此 JSONL 不是“数据库的替代品”，SQLite 也不是“所有会话的真源”。前者承载会话事件，后者可服务于索引与查询；设置、凭据、附件、非会话存储、遥测也都有独立所有者。一个成熟 Agent 系统不应该把所有数据塞进一张会话表里。

八、用一个“修复测试失败”任务，把五层串起来

1.研发团队从 Web、SDK 或 Git 平台 Webhook 发起“定位并修复测试失败”。

2.Profile 决定本次启动加载哪些模型、工具、权限和接入插件。

3.Agent Loop 创建或恢复 Session，领取任务，组装提示词、工作区规则和工具 schema。

4.模型先调用读文件与运行测试工具；工具流水线执行审批、守卫和超时控制。

5.文件系统、Shell、终端和 LSP 等第四层能力在统一执行环境中完成实际工作。

6.工具结果与模型输出写入 Session；日志派生下一次模型上下文，直到任务结束。

从这个例子就能看出：所谓 Agent，不是“模型会自动写代码”这么简单，而是一条贯穿启动、入口、调度、能力、治理和数据的闭环。

九、企业落地，先从“只读分析”开始

DSH 的插件化、Session、Webhook、SDK 和工具管线，很适合成为研发效能、运维辅助、知识问答、工单分流和数据分析的执行底座。但当前官方定位仍是 Developer Preview，明确提示未来会有破坏兼容性的变化；安全说明也明确指出它尚未完成安全审计，不应被视为生产就绪的安全产品。

部署前先验证：模型与插件版本锁定策略、最小权限、隔离执行环境、网络与凭据范围、审计日志、人工审批、数据分级和失败回滚。DSH 的 sandbox 与审批可以降低风险，但官方文档明确说明它们不构成唯一安全控制。

结语：DSH 的价值，不是“替你调用模型”

如果只需要问答，模型 API 加一个聊天框就够了。DSH 解决的是另一类问题：当模型需要进入真实工作流，谁来决定它能看到什么、能做什么、怎样被调用、怎样被限制、怎样恢复，又怎样留下可追踪的事实。

近期还会在视频号发布专门的讲解DSH的视频，感兴趣的麻烦点个关注。

理解 DSH 的最好方式，是从“模型能力”转向“Agent 系统能力”：组装、接入、循环、执行与记忆，缺一不可。