wuyang/research-blog

Fork 0

Files

T

wuyang6 a03dc0e1e4 docs: clarify DeepSeek Harness plugin composition

2026-08-14 10:18:13 +08:00

23 KiB

Raw Blame History

title, summary, date, updated, topic, tags, kind, status, visibility, canonicalUrl, sourceRepo

title

summary

date

updated

topic

DeepSeek Harness：全插件化 Agent 运行时与评测现状

一句话结论：DeepSeek Harness 已经展示出一套有辨识度的“全插件化 Agent 运行时”，适合持续观察与隔离试点；在兼容性、发布稳定性和 Agent 任务评测补齐前，不适合作为组织级默认 Harness。

调研范围

本文面向需要选择或建设 Agent Harness 的研发与技术管理者，回答三个问题：DeepSeek Harness 实际如何组织和运行 Agent；它与常见 coding agent 系统的关键差异是什么；当前公开证据是否足以支持观察、试点或正式采用。

调研冻结在 2026 年 8 月 14 日，目标代码固定为提交 47f943859bef60e4160492346772ded9b24f765a。横向对照也固定到同日抓取的 Codex、Gemini CLI 与 OpenHands 提交。本文不评价 DeepSeek 模型能力，不使用 GitHub star 数作为成熟度证据，也不把不同项目、不同模型、不同任务下的数字拼成排行榜。

当前判断

最值得关注的是扩展边界。 dsh 允许替换的不只包括工具和模型适配器，还包括会话、Agent loop、工具注册表、策略、持久化和 UI。Profile、Bundle 与 patch 可以逐层改写这些配置，比“在固定 Agent 核心外围加插件”更激进。
插件由完整主链路连接。 一次 turn 通过 durable session event、live agent event 和 capability waterfall 串成完整流程；工具审批、执行和结果回写有明确顺序；会话日志同时服务模型上下文、恢复、分叉和 UI 投影。
工程质量证据多于效果证据。 仓库有高覆盖率单元测试、keyless snapshot、真实 API e2e 入口、Web 性能/压力 runner 和 CI runner benchmark；但在冻结范围内没有发现公开的 Agent 任务成功率成绩。
现在的合理动作是观察或隔离试点。 Developer Preview、兼容性主动破坏、会话格式 v0、无正式 GitHub Release，以及缺少可复现的目标任务评测，都会阻断生产级采用。

一次 Agent 请求如何流过系统

启动时，dsh 先从 Profile 读取有序 Bundle，再叠加 Profile、Harness home 和命令行 patch，得到实际 Cordis 插件树。官方架构文档明确写到，模型适配器、工具注册表、会话日志和 Agent loop 本身都是插件；配置行可以被更高层 patch 整体替换。架构文档

运行时，输入先进入 Agent inbox。loop 在每个 step 前组装系统提示、工具 schema 与从会话日志派生的历史，然后发出 agent/pre-step；通过后写入 step/start 与用户消息，再经 agent/request 调用 LLM。模型产生工具调用时，执行路径依次经过 tools/pre-execute、审批、guard、tools/execute、工具本体、tools/post-execute 和结果固化。需要审批却没有可用 answerer 时，ask 会退化为拒绝，而不是静默放行。Tools README

这些事实被追加到 SessionEvent 日志。模型历史从日志派生；resume、fork、轨迹视图和持久化也复用同一事实源。若进程在工具调用中断，恢复逻辑会区分“工具尚未开始”和“工具结果未知”，后者会提示模型先验证副作用，避免盲目重试。持久化说明

这条链路的价值在于，扩展不必侵入一个巨大核心：插件可以提供服务、监听或包裹 waterfall，并在卸载时撤销注册。Cordis 预印本将其归纳为时间可组合性与空间可组合性：一方面追踪可逆 effect，另一方面根据依赖变化重新协调组件。但论文仍处于 active revision，适合作为设计解释，不应当作稳定标准。Cordis 预印本

Cordis 插件树到底怎样实现

“插件树”容易让人误以为是一棵类继承树。dsh 里实际叠加了三层机制：

配置层决定“挂载什么”。 Profile 先列出有序 Bundle；启动时再依次应用 Bundle patch、Profile 自身 patch、Harness home patch 和命令行 --patch。每个配置行用 id 作稳定身份，name 指向插件模块，还可带 config、inject 和 disabled。后层 patch 按 id 命中前层行时，替换整个 config，不做字段级深合并。CLI 组合参考
Cordis 运行时决定“何时激活”。 根 Context 下的 Loader 把每行配置挂成一个插件实例，每个实例都有 Fiber 状态。插件通过 apply(ctx, config) 贡献能力，通过 inject 声明必需服务。因此 YAML 行的先后不决定加载顺序：依赖未就绪的插件保持 PENDING，服务出现后才激活。Cordis 服务教程
effect 层决定“怎样安全拆除”。 ctx.tools.register(...)、ctx.on(...)、服务注册和子插件都与当前插件生命周期绑定。配置删除、HMR 或服务提供方消失时，Cordis 会卸载相关 Fiber，反向撤销注册；服务恢复后，依赖它的插件再重新加载。Cordis 生命周期教程

可以把一个简化后的运行时理解为：

Root Context
└─ Loader
   ├─ tools provider Fiber       → 提供 ctx.tools
   ├─ greet-tool Fiber          → inject: tools
   ├─ llm provider Fiber         → 提供 ctx.llm
   ├─ agent-loop Fiber           → 消费 agents / tools / llm
   └─ surface Fiber              → Web、ACP 或 SDK JSON-RPC

这棵“树”同时包含两种关系：Loader 建立的父子生命周期，以及 inject 建立的服务依赖图。Bundle 是生成配置行的发布层，并不会成为一个不可拆的运行时黑盒。

一个最小例子：向模型增加 `greet` 工具

下面是官方 Cordis 教程示例的精简版。插件不自己启动 Agent，只声明“我需要 tools 服务，并向它注册一个工具”：

import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'greet',
    description: 'Greet the named person.',
    parameters: {
      name: { type: 'string', required: true },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    execute: async ({ name }) => `Hello, ${name}!`,
  }))
}

假设将它发布并安装为虚构示例包 @acme/dsh-greet-tool，可在 Profile 的 cordis.patch.yml 插入一行：

- insert:
    - id: greet-tool
      name: '@acme/dsh-greet-tool'

这个例子假定所选 Profile 已有 tools、LLM 和 agent loop 等基础行；它只演示新能力如何插入既有 Agent。完整过程是：Loader 看到 greet-tool 行 → 发现它需要 tools，Fiber 在缺失时保持 PENDING → ctx.tools 就绪后调用 apply 并进入 ACTIVE → greet 的 schema 进入模型工具列表 → 模型发出 greet({"name":"Ada"}) 时经标准工具管线执行 → 返回 Hello, Ada!。删掉这行或 HMR 热替换包时，Loader 根据稳定 id 重挂变化节点；旧 Fiber 进入卸载并最终 DISPOSED，工具注册随 effect 自动撤销。官方完整例子还演示了如何监听 tools/result 事件。进入 Harness 教程

“接入协议”要先区分方向

接入面	连接方式	解决的问题
Cordis 插件	进程内：TypeScript `apply(ctx, config)`、`inject`、Service、Event、effect	增加或替换模型、工具、会话、策略、loop 和 UI 组件
Profile / Bundle / patch	部署时：YAML 配置行与稳定 `id`	选哪些插件、如何覆盖默认值；它不是远程协议
Web	浏览器 → dsh：HTTP POST 一元调用；dsh → 浏览器：WebSocket 事件下行	产品 UI、会话展示和交互式操作；业务 Remote 由 Typert 生成严格描述
ACP	外部 Agent 客户端 ↔ dsh：Agent Client Protocol over newline-delimited JSON-RPC stdio	标准化的 `session/new`、`session/prompt`、取消和一次性权限回答
Python / TypeScript SDK	评测器或程序 ↔ dsh：项目自有的逐行 JSON-RPC 2.0 stdio	批量任务、自动化和 benchmark runner；方法为 `initialize`、`session/prompt`、`shutdown` 及事件/状态通知
MCP client	dsh ↔ 外部工具服务器：MCP stdio 或 Streamable HTTP	发现工具并注册为 `mcp__<server>__<tool>`；当前不桥接 Resources 和 Prompts

关键区别是：Web 是浏览器产品面；ACP 和 SDK 是“从外部驱动整个 Agent”；MCP 是“把外部工具接给 Agent”；Cordis 则是“在进程内改变 Agent 由哪些部件构成”。 它们解决的问题不同，不应放在同一层比较。ACP 只暴露基线自动化能力，而 SDK 线协议当前没有版本协商和单 prompt 取消，都不能等同于 Web 产品面的完整功能。ACP 协议契约 SDK 线协议 Web Connection MCP client

这套设计解决了什么

运行时结构也可以替换

许多 Agent 产品把模型、会话和 loop 固定在核心，只开放工具、MCP、Skill 或 Hook。dsh 把替换面进一步下沉：可以用不同 Profile 组成 Web 或 headless 产品，也可以替换会话后端、工具策略、模型适配器乃至 Agent loop。对于需要研究不同上下文策略、执行器、持久化或交互面的团队，这能减少 fork 主干的压力。

代价是配置态数量迅速增加。某个行为可能来自 Bundle 默认值、Profile patch、home patch、命令行 overlay 或运行时插件；“一切可替换”会把复杂度从代码分支转移到组合、来源追踪和兼容性验证。官方 plugin inventory 甚至明确说明它不记录条目由哪个 Bundle、Profile 或 override 引入，也不能直接修改插件，这意味着生产排障仍需要更强的配置溯源工具。Plugin inventory

事件日志让执行、恢复和观察共享事实

事件溯源避免了“模型看到的历史、UI 显示的历史、持久化记录”长期漂移。工具调用、结果、权限变化和 turn 边界都可以成为 durable fact；模型上下文只从带 surface 语义的事件派生。这个约束对恢复尤其重要，因为系统可以识别未闭合的调用并合成明确错误状态。

但事件溯源不能自动解决格式演进。当前 SESSION_FORMAT_VERSION = 0，持久化协调器会拒绝无法升级的旧格式或更新格式；在 Developer Preview 阶段，这意味着长生命周期会话不应被当作稳定资产。试点需要固定提交，并接受迁移、导出或放弃历史的可能性。

安全策略是可组合能力，但不是全局护栏

默认权限预设把 workspace-write + ask 与 danger-full-access + never 组合成两个选择，审批缺失时 fail-closed；这比把“是否询问”散落在每个工具内更清晰。Permission presets

需要注意的是，策略 seam 只有在工具主动接入或部署增加 tools/pre-execute 策略时才生效。官方 Web 工具说明明确指出，它的两个工具本身不会请求 ctx.approval，也没有持久 URL 或域名授权；需要确认的部署必须另外挂载策略。Web tool 因此，不能仅凭“系统有 approval 与 sandbox 包”推断所有能力都受到同等保护。

安装与扩展门槛

体验入口很短：官方给出的 Web 启动方式是 npx @deepseek-ai/dsh web，默认监听 127.0.0.1:3080。如果从源码开发，则需要 Node.js ^22.19.0 或 >=24.0.0、仓库锁定的 pnpm 11.7，完成依赖安装和构建后再通过 pnpm dsh web 启动。README 开发指南

扩展有两条路径。已有能力的轻量改造，可以先用 dsh --profile web --dump-config 查看最终配置，再按配置行 ID 用 patch 整体替换；新增模型、工具、策略、会话后端或 loop，则需要实现 Cordis 插件，把它加入 Bundle/Profile，并同时处理服务依赖、事件或 waterfall、effect 清理和测试。后者不是“放入一个脚本即可”的低成本插件：当前项目仍处于 Developer Preview，配置 inventory 又不能完整回答某一行由哪层引入，因此试点需要固定提交、锁定插件版本，并为每个自定义插件建立组合测试和升级回滚检查。

与常见 Harness 的差异

下表比较的是同一生命周期上的架构边界，不是产品效果排名。冻结版本分别为 Codex 053dda6、Gemini CLI 1ac3377 与 OpenHands 4f465f3。

维度	DeepSeek Harness	Codex	Gemini CLI	OpenHands
首要形态	Web、headless、SDK/ACP 由 Profile 组合	本地 coding agent，CLI/IDE/App 共用核心与 app-server	terminal-first CLI，CLI 与 core 分包	Agent Server/Runtime 加 Web/Canvas 与云服务
扩展边界	模型、会话、loop、工具、策略、UI 都可配置替换	Skills、MCP、Hooks、工具和客户端协议扩展，核心 loop 更集中	Extensions、MCP、Hooks、Policy Engine、工具注册	Skills/MCP/工具集、Agent SDK、Runtime/Cloud 服务
会话语义	append-only SessionEvent，history 派生，支持 resume/fork/repair	thread/turn/item 持久化，支持 resume/fork/interrupt	CLI/core 管理会话历史与 checkpoint/resume	Conversation/Event 由 Agent Server 管理，Runtime 承担执行状态
工具安全	guarded pipeline；ask 缺通道 fail-closed；沙箱与审批可组合	OS sandbox、approval policy 与权限 profile 是产品核心能力	sandbox、policy engine 与交互批准围绕 terminal tool	以隔离 Runtime/sandbox 与服务端执行边界为主
主要取舍	最大可替换性，同时承担配置态和插件兼容复杂度	集成一致性与产品化成熟度	终端体验、Gemini 集成与扩展生态	隔离运行环境、长任务与服务化编排

dsh 试图把 Harness 自身变成可动态组合的研究与产品平台。如果团队只需要一个成熟 coding agent，深度可替换性未必能抵消兼容与运维成本；如果团队正在建设多种执行器、策略、持久化或交互形态，它提供了值得借鉴的边界设计。

类型	任务与指标	是否有仓库内正式成绩	能说明什么
Web 长历史性能	1,000 个侧边栏会话、500-turn 历史、2,100 行轨迹、100-turn soak；记录 wall/task/script/style、首 chunk、p95 等	未发现提交的正式运行结果	Web UI 在高基数历史下的性能分析能力
reasoning chunk 压力	100,000 个 chunk；最大主线程延迟与计划交互延迟门槛均为 250 ms	runner 有断言，未发现官方发布结果	流式 reasoning 渲染的响应性
CI runner benchmark	不同 Linux/Windows core 数下的 typecheck、文档构建和聚合 gate	未发现结果汇总	CI 容量与拓扑选择，不是 Agent 能力

风险与采用门槛

门槛	当前状态	证据	判断
观察	文档、源码和入口足以形成机制判断	架构文档、源码、冻结提交	通过
隔离试点	需要固定版本、一次性 workspace、低风险任务、明确权限与恢复方案	构建/定向测试通过；权限与恢复机制可审计	有条件通过
组织级采用	需要兼容/迁移承诺、目标任务复现评测、安全审查、升级回滚和责任人	Developer Preview、格式 v0、无正式 Release、未发现公开 Agent 任务成绩	不通过

截至调研日，官方 README 明确标注 Developer Preview 并预告兼容性破坏；GitHub Releases 页面没有正式 Release。版本与发布状态本身不否定技术价值，但会显著增加升级、会话迁移和插件兼容成本。

如果进入隔离试点，建议固定 47f9438 或新选定提交，使用可丢弃 workspace，保留默认 workspace-write + ask，逐项确认 Web、文件、shell 与外部服务能力是否真正接入审批策略，并把会话导出与版本切换当作可失败项。试点只能回答“它是否适合我们的具体任务和运维方式”，不能用一次成功演示替代采用评审。

建议

现在可以把 dsh 纳入架构观察清单，并安排一个受限试点；不应直接替换现有生产 Harness。观察重点应放在三处：插件树对多产品形态的复用是否真的降低 fork 成本；事件日志能否让恢复、审计和 UI 投影保持一致；工具策略在自定义插件和 Web 能力接入后是否仍然 fail-closed。

从“试点”升级到“采用评估”至少要看到三项变化：项目给出更稳定的发布与迁移政策；在固定模型、工具、预算和任务集下产生可复现的目标任务结果；团队完成插件供应链、权限、数据与回滚审查。任一项缺失，都应继续停留在观察或隔离环境。

来源与复现说明

目标仓库：deepseek-ai/deepseek-harness
冻结提交：47f943859bef60e4160492346772ded9b24f765a
主要官方文档：README、Architecture、Persistence、Tools、Benchmark entry
证据等级：官方声明与源码文档、冻结源码、仓库测试/CI、边界执行结果、明确标注的推断；不同等级不互相替代。
未核验：真实模型端到端效果、生产负载、跨版本迁移、第三方插件生态质量、组织级安全与运维成本。

23 KiB

Raw Blame History

DeepSeek Harness：全插件化 Agent 运行时与评测现状

调研范围

当前判断

一次 Agent 请求如何流过系统

Cordis 插件树到底怎样实现

一个最小例子：向模型增加 `greet` 工具

“接入协议”要先区分方向

这套设计解决了什么

运行时结构也可以替换

事件日志让执行、恢复和观察共享事实

安全策略是可组合能力，但不是全局护栏

安装与扩展门槛

与常见 Harness 的差异

相关评测与验证现状

没有发现公开的 Agent 任务成绩

仓库已有三类相关评测资产

边界验证不能填补效果证据

风险与采用门槛

建议

来源与复现说明

23 KiB Raw Blame History Unescape Escape

DeepSeek Harness：全插件化 Agent 运行时与评测现状

调研范围

当前判断

一次 Agent 请求如何流过系统

Cordis 插件树到底怎样实现

一个最小例子：向模型增加 greet 工具

“接入协议”要先区分方向

这套设计解决了什么

运行时结构也可以替换

事件日志让执行、恢复和观察共享事实

安全策略是可组合能力，但不是全局护栏

安装与扩展门槛

与常见 Harness 的差异

相关评测与验证现状

没有发现公开的 Agent 任务成绩

仓库已有三类相关评测资产

边界验证不能填补效果证据

风险与采用门槛

建议

来源与复现说明

23 KiB

Raw Blame History

一个最小例子：向模型增加 `greet` 工具