DeepSeek Harness:插件化智能体运行时剖析
内核只做调度,能力全部长在插件层,这是 DeepSeek Harness 对“智能体运行时该长什么样”给出的回答。
2026 年,智能体工程正在形成一个共识:模型能力不再是唯一瓶颈,运行时基座(Harness)的工程质量决定智能体的上限。DeepSeek Harness(下文简称 DSH)是这一共识下最具代表性的产品化实现之一:它在形态上是 Electron 桌面应用、本机 Web 服务与 dsh CLI 的组合,在内核上构建于 Cordis 插件框架,在设计上把“一切皆插件”推到极致:模型适配器、工具注册表、会话日志乃至 agent loop 本身,全部是可以被配置替换的插件。
本章基于对 DSH 0.2.x 版本(2026 年 11 月)随发行版交付的架构文档与运行时包的剖析,从总体架构、工作原理、扩展机制三个层面拆解这套运行时。它是本书Harness:智能体的运行时基座一章的概念在真实产品中的完整落地,也是观察智能体运行时演进方向的一个样本。
定位:模型无关的智能体运行时
DSH 的产品定位不是“又一个聊天应用”,而是一个智能体运行时:模型、工具、技能、界面全部可以拆开替换。这一定位首先体现在模型侧的彻底解耦。
DSH 内置一个模型提供商目录,覆盖 Anthropic、OpenAI、Moonshot(Kimi)、Z.ai(GLM)等常见厂商;对于中转站、公司网关或自建服务器,可以添加自定义模型 API,支持 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 与 Gemini 四种协议。API 密钥以只写方式保存在 $DSH_HOME/.credentials.yaml 中,设置界面只会收到脱敏描述符,永远不会显示明文。模型变更在下一次请求时生效,不需要重启。
桌面应用的界面本身也遵循同样的解耦思路:底层是一个监听回环地址的本机 Web 服务,启动时用一次性 token 换取登录态;Electron 壳加载打包的 Web 资源,通过 Node IPC 承载启动注入、就绪与关闭信号。命令行的 dsh CLI 与桌面应用共享同一套 profile 体系,二者是同一运行时的不同入口。
总体架构:Cordis 内核与插件树
理解 DSH 的架构要从两个关键词入手:Cordis 与 Profile。前者回答“插件如何组织”,后者回答“插件如何组合成一个可运行的产品”。
一切皆插件
Cordis 是 DSH 以 vendor 方式引入的底层插件框架,它的五个核心概念构成了整个运行时的组装语法:
- 插件是实现服务的对象:可以是一个带可选
inject与apply(ctx)字段的函数,也可以是一个Service子类,生命周期由 Cordis 挂载到当前上下文。 - 上下文是服务的容器:每个服务占据一个稳定的
ctx.<key>(如ctx.tools、ctx.llm、ctx.sessions),其他插件通过 key 查找服务,而非导入具体实现。 - 通过
inject声明依赖:插件声明所需服务后等待其就绪才启动,加载顺序由服务依赖表达,而非手动编排启动序列。 - 类型化事件用于通信:事件名通过 TypeScript 声明合并注册,以
emit、waterfall、parallel、serial或bail方式分发。 - 注册是可逆的副作用:提示词片段、工具 schema、适配器与监听器通过
ctx.effect()或ctx.on()安装,重载与卸载时按预期撤销。
在这套语法之上,DSH 做出了一个关键架构决策:产品不存在需要打补丁的特权内核。扩展 DSH 的方式是把插件挂载到其他插件旁边,而各项注册都是副作用,会在其插件卸载时自动撤销。桌面版运行时 0.2.2-rc.3 的依赖清单里有 337 个 @deepseek-ai 作用域的包,全部锁定同一版本,从模型适配、工具、持久化到界面组件,产品真的是一层层插件叠出来的。
Profile:有序补丁层叠栈
Profile 是存放在 Harness home(默认 ~/.dsh)中的具名组装。CLI 帮助文档对它的定义是“ordered stack of plugin-bundle patch layers”(有序的插件补丁层叠栈)。每个 profile 目录实际上是一个 pnpm workspace,包含 package.json(记录树外插件依赖与组合包清单 dsh.profile.bundles)、node_modules(pnpm 安装的插件)、cordis.yml(空的根条目列表)与 cordis.patch.yml(用户自己的补丁层)。
运行中的 DSH 是一棵插件树,配置从空根出发依次叠加:
dsh.profile.bundles中各组合包(bundle)的 patch,按声明顺序应用- profile 自身的
cordis.patch.yml - home 级的
$DSH_HOME/cordis.patch.yml --patch命令行指定的覆盖层
下图自上而下展示了这套层叠:越靠上的层优先级越高,最终组合出的就是运行中的插件树。
一条 patch 按 id 定位某个条目,替换其整个 config,或插入新条目;YAML 中的 !!js 表达式由 loader 插件在对应服务激活后插值。例如,想在用户层改写默认模型:
# ~/.dsh/profiles/web/cordis.patch.yml(用户补丁层)
- id: agent-default-model
config:
provider: zai
model: glm-5.3启用 dsh-hmr 的 profile 会监视配置文件,通过统一串行重载重新组合所有层;未启用时更改在重启后生效。使用 dsh --profile web --dump-config 可以在不启动的情况下检查组合后的配置树:它打印出的任何条目,都可以被你自己的 patch 替换。
组合包与多形态入口
组合包是 Cordis 配置项及其挂载代码的分发格式,因此它插入的内容始终可被其上各层 patch。dsh-base 是 web、headless、sdk 与 acp profile 的共享第一层,提供模型适配器、工具、持久化、沙箱与审批策略、设置、凭据与遥测;其上的应用组合包决定最终形态:
| Profile | 组合包 | 形态 |
|---|---|---|
web | dsh-web-app | 浏览器应用,本地 Web 服务 |
desktop | 桌面专属组装 | Electron 桌面应用(名称保留,CLI 拒绝直接启动) |
headless | dsh-headless | 一次性运行器:运行单个任务,打印最终答案并退出 |
sdk | dsh-sdk-app | JSON-RPC stdio 服务器,服务 SDK 客户端 |
sdk-minimal | dsh-sdk-minimal | 刻意保留的例外:不叠加 dsh-base 的显式极简配置树 |
acp | dsh-acp-app | Agent Client Protocol stdio 服务器,服务自动化客户端 |
多形态入口共享同一个 launcher 与同一套组合机制:Python SDK 的运行时 wheel 里打包的就是同一个 dsh CLI,客户端默认启动 dsh --profile sdk。插件管理统一走 dsh plugin --profile <name> <pnpm args>(内部转发给 pnpm)或界面中的插件管理器,二者共享包操作与 profile 写锁。安装时会按插件声明的 engines.dsh 范围检查运行时版本兼容性,不兼容的插件需要用户明确确认精确版本豁免。
下图是这套运行时的分层全景。
工作原理:轮次、日志与流水线
架构决定了“如何组装”,工作原理回答“如何运转”。DSH 的运行时语义围绕三个机制展开:轮次与步骤的状态机、作为唯一事实来源的会话日志、带把关的工具执行流水线。
轮次与步骤
DSH 用两个粒度刻画智能体的工作过程:
- 步骤(step)是一次模型请求加上它调用的工具
- 轮次(turn)包含零个或多个步骤:它在领取首条输入之前打开,在不再欠下任何工作时关闭
一个典型轮次的流转如下:驱动器(agent loop)从 inbox 领取待处理输入,快照会话的模型选择,组装提示词片段与本步骤获准的工具 schema;agent/pre-step 瀑布事件让监听器接纳、改写或拒绝这批消息(拒绝首个批次会直接关闭一个不含步骤的轮次);随后提交系统提示词与用户消息、从日志冻结请求,经 llm/stream 瀑布发起流式调用;模型返回的工具调用进入执行流水线,结果写回会话日志;若工具欠下新的模型请求或有新输入到达,则开启下一个步骤;不再有欠账时,agent/turn-stopping 串行事件给出终止检查点,轮次关闭。
下图把这条流程放进时序视图:turn/start 与 turn/end 是高亮的轮次边界事件,中间的 STEP 块按步骤重复。
重试语义经过仔细设计:重试保留轮次开头的模型选择快照,不重复组装与 agent/pre-step,只在开放步骤内重新准备调用。失败步骤会记录缺失的工具结果,保证日志的完整性。
会话日志:模型可见即已记录
会话日志是 DSH 工程纪律的核心,可以概括为一句话:模型可见即已记录。每个模型请求都必须能从日志重建;新增模型可见的输入需要新增会话事件。
- 日志是仅追加的
SessionEvent流,deriveMessages()从中投影出模型历史 - 每条
assistant/message都嵌入产生它的精确紧凑带时间流;失败的、被重试的、被取消的尝试以assistant/attempt落盘,但不进入模型历史 - fork、恢复、transcript、遥测与持久化都从这些持久 settlement 派生;实时 UI 增量则来自
agent/assistant-stream事件 - 存储格式按 generation 演进(JSONL,可选 zstd 压缩),已提交的 generation 路径绝不重命名、替换或删除;版本迁移由相邻迁移包逐级
vN -> vN+1完成
这套设计让“审计”与“回放”成为内建能力而非附加功能:轨迹视图能把整个工作过程录成时间线,模型思考、工具调用、等待时长都可回放。插件若要修改现有消息内容,须注册纯消息投影(ctx.sessionProjections),读取方显式传入相同处理器,保证不同消费者看到一致的视图。
三类事件域
事件在三个域内提供扩展点,分别对应三种时间尺度:
- 会话事件(
session/event广播):追加到日志的持久事实。某个事实必须在重载后仍然存在时,使用它。 - Agent 事件(
agent/*):携带活跃智能体的 inbox、步骤、状态、请求、验证与续跑。要观察或拦截进行中的工作时,使用它。 - 能力事件:无需导入循环即可向某个 seam(
fs/*、tools/*、telemetry/*)附加策略和适配器。
每个事件的分发模式是公开约定的一部分,五种模式各司其职:
| 模式 | 是否 await | 分发顺序 | 返回值 |
|---|---|---|---|
emit | 否 | 监听器按注册顺序观察 | 无 |
waterfall | 否 | 环绕中间件,监听器包装并委托 next() | 有 |
parallel | 是 | 所有监听器并行观察 | 无 |
serial | 是 | 监听器按顺序执行 | 有 |
bail | 否 | 顺序执行,直到某个监听器返回 bail 值 | 有 |
其中 waterfall 是环绕中间件语义:监听器可以修改共享的请求或决策对象后委托下游,也可以在不调用 next() 时直接短路。对单决策事件而言,短路是设计意图,拥有决策权的策略监听器可以直接给出裁决。
工具执行流水线
工具执行是策略密度最高的环节。内置执行器负责原始批次解析、调度、取消与调用/结果日志,而策略、钩子、沙箱、文件系统守卫、结果改写与 UI 呈现全部通过共享流水线插入,无需改动循环:
这套分层让钩子可以跨越不同工具族生效,而无需让工具与某个策略服务耦合:审批插件、沙箱策略与结果改写各自注册自己的瀑布监听器,组合行为由层叠顺序决定。
扩展机制:能力 Seam 与插件生态
“一切皆插件”描述的是静态结构;扩展机制回答的是动态问题:替换一个提供方为什么能改变整个产品?
Seam:可替换能力的三角色合同
DSH 把一项可替换能力称为一个 seam,它包含三种角色:声明接口的 Service Definition、实现它的 Service Provider,以及使用它的 Consumer(通常是面向模型的工具)。一个包可以合并承担多个角色,但单一角色本身不是 seam;添加一项能力意味着把三者一并设计。
seam 正是替换经济学生效的原因。文件系统与进程提供方共享同一个“执行世界”,因此把它们指向远程沙箱,也就把 Bash、PTY 和 LSP 一并搬了过去,无需提供方专用 fork。subagent 提供方在同一个接口后面同样千差万别:从新建一个子智能体,到把一个轮次委派给另一个产品。
扩展点地图
官方架构文档给出了一张“新行为的归属位置”映射表,摘译如下:
| 目标 | 机制 |
|---|---|
| 接入新的模型提供方 | 在 ctx.llm 上注册适配器 |
| 添加面向模型的能力 | 在 ctx.tools 上注册,schema 加入提示词组装 |
| 为会话换一套能力组合 | 组装 agent preset;服务行需要 isolate realm |
| 添加 Shell 执行 | 注册 ctx.shell 后端;本地后端经 ctx.subprocess spawn 进程 |
| 添加用户命令 | 在 ctx.commands 上注册,无需模型轮次即可分派 |
| 管理后台任务 | 在 ctx.jobs 上注册;job_* 工具读取或停止任务 |
| 从外部 Webhook 启动会话 | 在 ctx.webhookRuntime 上注册可信规则 |
| 文件系统访问或策略 | 注册 ctx.fs 提供方,或监听 fs/* 事件 |
| 限制所启动的进程 | 使用 ctx.sandbox 后端;消费方在启动前包装 argv |
| 拦截请求、工具或轮次 | 使用相应的 agent/* 或 tools/* 瀑布事件 |
| 注入模型可见上下文 | 调用 agent.inject(),落入下一次获准请求 |
| 添加 UI 集成 | 驱动 ctx.agents,从 session/event 渲染 |
| 添加持久会话状态 | 扩展 SessionEventMap,从日志渲染与回放 |
| 在新后端存储会话 | 基于共享句柄脚手架实现 SessionPersistence |
插件能贡献什么
从使用者视角看,插件可以向运行时贡献五样东西:
- 工具:智能体可调用的函数,schema 自动进入提示词组装,例如浏览器插件带来的数十个
ego_*工具 - 技能:按需加载的操作手册。技能是一个包含
SKILL.md的目录包,前置元数据声明路由描述,正文是工作流程本身;模型按需加载,也可由用户显式调用 - 界面:侧边栏按钮、标签页、面板,界面本身也是插件,任务看板与上下文仪表盘都以此实现
- 子智能体:把任务分派给拥有独立上下文的另一个智能体,可指定不同的提供商、模型与推理强度;官方还提供把轮次委派给 Claude Code、Codex 的桥接插件
- MCP 连接:接入 Model Context Protocol 资源服务器,把外部系统挂进运行时
分发:npm 包、市场与索引
插件的分发单位是 npm 包:界面里的一键安装,背后是往 profile 的 pnpm workspace 里装一个包,重启后生效(配置层的变更则可经 dsh-hmr 热重载)。版本治理以 engines.dsh 语义化范围为锚点,安装时强制检查,不兼容版本需要用户明确豁免。
第三方市场的能力刻意保持了去中心化:插件索引就是一个静态 JSON 文件,列出可安装的组合包及其标题、图标、作者、版本与来源(npm 或 Git 仓库),放在任意静态主机上即可发布。DSH 本身不内置任何索引源;启用实验性的自定义插件索引组合包后,可在“发现”页添加索引源并浏览安装。市场按“与当前运行时兼容且非预发布的最高版本”推荐版本;索引属于第三方内容,DSH 检查文件格式但不验证其中的声明,只添加信任的索引源。
生态实践:做减法是必修课
插件生态的繁荣是红利也是噪音。本站《DeepSeek Harness 上手记》记录了一次真实的筛选实验:从装满 30 个插件开始,一周后删 3 个、停 7 个,常驻 20 个。留下来的最大一族是上下文与记忆插件:上下文怎么花、记忆怎么留,决定了智能体的上限。
那篇文章还量化了一类典型权衡:上下文压缩插件把已消费的历史折叠成摘要块,一次会话可省数万 token、账本累计节省上亿 token;但每次折叠都要额外跑一次模型调用,重任务明显变拖。省 token 与响应速度的取舍,没有普适答案,只有按任务负载的动态选择,这正是“能力皆插件”的价值:压缩与否不必是产品决策,可以是每个用户自己的 patch。
产品形态与安全边界
架构与扩展机制之外,DSH 的产品层提供了几组与治理直接相关的原语。
工作区与会话:日常使用的组织方式是 workspace 加 session。每个 git 仓库是一个 workspace,workspace 下开多个 session,每个 session 有独立的上下文、待办计划与审批记录。会话状态持久化在 $DSH_HOME/sessions,配合全文检索与跨会话记忆插件,支撑长周期工作。
权限与沙箱:文件与命令操作有分级权限预设,从只读、工作区可写到完全访问逐级放开;破坏性操作可走审批门控,流水线中的单调守卫与一次性审批在工具执行前把关。执行侧有本地与沙箱两类后端(dsh-bash-local 与 dsh-bash-sandbox),seam 设计意味着二者可以整体替换为远程执行世界。
多智能体协作:子智能体拥有运行时树成员关系,主智能体与子智能体的关系可在编队视图中实时观察。Agent Teams 在根会话上提供任务策略与共享任务板;任务看板的每张卡片对应一次真实的会话执行,并支持定时任务。
观测:轨迹视图提供全过程的可回放时间线;上下文仪表盘把 token 构成、缓存命中率与耗时分布可视化。这两者都不是特权功能,而是界面插件。
用六项职责检验 DSH
本书 Harness 一章提出,完整的 Harness 需要覆盖观察、行动、反馈、验证、权限、记忆六项核心职责。以此检验 DSH:
| Harness 职责 | DSH 中的落地 |
|---|---|
| 观察 | ctx.fs 观察策略、工具结果结构化回写、附件与文件引用子系统 |
| 行动 | ctx.tools 注册表与带把关的执行流水线、ctx.shell 与 ctx.subprocess、沙箱后端 |
| 反馈 | 仅追加会话事件日志、agent/assistant-stream 实时流、压缩插件族 |
| 验证 | tools/post-execute 改写与阻断、finalizeContent 不变式、轨迹与仪表盘插件 |
| 权限 | 审批 ctx.approval、单调守卫、分级权限预设与沙箱、凭据只写脱敏 |
| 记忆 | 会话持久化与 generation 迁移、投影 seam、跨会话记忆插件生态 |
检验的结论不是“六项都有”,而是“六项的每一项都有可替换的实现”:观察可以换文件系统提供方,权限可以换审批策略,记忆可以换记忆插件。按照“同时覆盖六项职责的系统才是 Harness”的标准,DSH 不仅达标,还把每一项都做成了 seam,这是它与工具调用封装库的本质区别。
总结
DSH 的架构给出了智能体运行时设计的一个完整参照:
- 无特权内核的组合式架构:产品各部分皆为插件,注册是可逆副作用,profile 以有序补丁层叠出整机。定制不靠 fork 源码,靠层叠 patch,“内核即调度,能力即插件”在这里是字面事实。
- 日志即真相的工程纪律:模型可见即已记录,每个请求可从日志重建,实时视图与持久事实分离。这让审计、回放与恢复成为内建能力。
- seam 作为替换的抽象:能力以“定义、提供方、消费方”三角色合同存在,替换一个提供方即改变整个产品行为,这是插件生态得以健康生长的结构前提。
- 治理内建于分发:版本兼容强制检查、去中心化的索引市场、分级权限与审批流水线,让“敢装 30 个插件再慢慢做减法”成为合理的工程策略。
对本书而言,DSH 是Harness:智能体的运行时基座概念的参照实现,也是智能体作为 Workload从抽象走向产品的一步。它的演进方向提示了智能体运行时的下一阶段竞争焦点:不在模型,也不在单个产品的功能清单,而在扩展机制的合同质量与生态的治理水平。
参考链接
- 本站Harness:智能体的运行时基座:Harness 概念、六项核心职责与形态分化
- 本站Agent Control Loop:智能体自治闭环:控制闭环的理论视角,DSH 的轮次/步骤机制是其一阶实现
- 本站智能体状态语义:Session、Task 与 Execution Graph:会话状态建模,可与 DSH 的会话日志对照阅读
- 本站Agent Sandbox:Agent Runtime 的统一执行域:沙箱作为执行域的统一抽象
- DeepSeek Harness 上手记:架构、插件市场与留下来的 20 个插件:本站的 DSH 实践记录与插件筛选实录
- DSH 随发行版交付的架构文档(
@deepseek-ai/dsh包docs/目录):Cordis 入门、轮次时序图、工具执行流水线与配置目录的一手资料