--- { "title": "DeepSeek Harness：全插件化 Agent 运行时与评测现状", "summary": "从配置组合、Agent loop、工具审批、事件日志与恢复机制出发，解释 DeepSeek Harness 的架构取舍，并核对公开评测证据是否足以支持采用。", "date": "2026-08-14", "updated": "2026-08-14", "topic": "agent-systems", "tags": ["deepseek", "agent-harness", "architecture", "evaluation", "cordis"], "kind": "article", "status": "published", "visibility": "public", "canonicalUrl": "https://blog.k1412.top/articles/deepseek-harness-architecture-evaluation/", "sourceRepo": "https://git.k1412.top/wuyang/research-blog" } --- # DeepSeek Harness：全插件化 Agent 运行时与评测现状 > 一句话结论：DeepSeek Harness 已经展示出一套有辨识度的“全插件化 Agent 运行时”，适合持续观察与隔离试点；在兼容性、发布稳定性和 Agent 任务评测补齐前，不适合作为组织级默认 Harness。 ## 调研范围 本文面向需要选择或建设 Agent Harness 的研发与技术管理者，回答三个问题：DeepSeek Harness 实际如何组织和运行 Agent；它与常见 coding agent 系统的关键差异是什么；当前公开证据是否足以支持观察、试点或正式采用。 调研冻结在 2026 年 8 月 14 日，目标代码固定为提交 [`47f943859bef60e4160492346772ded9b24f765a`](https://github.com/deepseek-ai/deepseek-harness/tree/47f943859bef60e4160492346772ded9b24f765a)。横向对照也固定到同日抓取的 Codex、Gemini CLI 与 OpenHands 提交。本文不评价 DeepSeek 模型能力，不使用 GitHub star 数作为成熟度证据，也不把不同项目、不同模型、不同任务下的数字拼成排行榜。 ## 当前判断 1. **最值得关注的是扩展边界。** dsh 允许替换的不只包括工具和模型适配器，还包括会话、Agent loop、工具注册表、策略、持久化和 UI。Profile、Bundle 与 patch 可以逐层改写这些配置，比“在固定 Agent 核心外围加插件”更激进。 2. **插件由完整主链路连接。** 一次 turn 通过 durable session event、live agent event 和 capability waterfall 串成完整流程；工具审批、执行和结果回写有明确顺序；会话日志同时服务模型上下文、恢复、分叉和 UI 投影。 3. **工程质量证据多于效果证据。** 仓库有高覆盖率单元测试、keyless snapshot、真实 API e2e 入口、Web 性能/压力 runner 和 CI runner benchmark；但在冻结范围内没有发现公开的 Agent 任务成功率成绩。 4. **现在的合理动作是观察或隔离试点。** Developer Preview、兼容性主动破坏、会话格式 v0、无正式 GitHub Release，以及缺少可复现的目标任务评测，都会阻断生产级采用。 ## 一次 Agent 请求如何流过系统 ![DeepSeek Harness 从配置组合到会话持久化的主链路](/articles/deepseek-harness-architecture-evaluation/dsh-agent-flow.svg) 启动时，dsh 先从 Profile 读取有序 Bundle，再叠加 Profile、Harness home 和命令行 patch，得到实际 Cordis 插件树。官方架构文档明确写到，模型适配器、工具注册表、会话日志和 Agent loop 本身都是插件；配置行可以被更高层 patch 整体替换。[架构文档](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/architecture.md) 运行时，输入先进入 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](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/core/tools/README.md) 这些事实被追加到 `SessionEvent` 日志。模型历史从日志派生；resume、fork、轨迹视图和持久化也复用同一事实源。若进程在工具调用中断，恢复逻辑会区分“工具尚未开始”和“工具结果未知”，后者会提示模型先验证副作用，避免盲目重试。[持久化说明](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/session/session-persistence/README.md) 这条链路的价值在于，扩展不必侵入一个巨大核心：插件可以提供服务、监听或包裹 waterfall，并在卸载时撤销注册。Cordis 预印本将其归纳为时间可组合性与空间可组合性：一方面追踪可逆 effect，另一方面根据依赖变化重新协调组件。但论文仍处于 active revision，适合作为设计解释，不应当作稳定标准。[Cordis 预印本](https://github.com/cordiverse/paper) ## 这套设计解决了什么 ### 运行时结构也可以替换 许多 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](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/host/plugin-inventory/README.md) ### 事件日志让执行、恢复和观察共享事实 事件溯源避免了“模型看到的历史、UI 显示的历史、持久化记录”长期漂移。工具调用、结果、权限变化和 turn 边界都可以成为 durable fact；模型上下文只从带 surface 语义的事件派生。这个约束对恢复尤其重要，因为系统可以识别未闭合的调用并合成明确错误状态。 但事件溯源不能自动解决格式演进。当前 `SESSION_FORMAT_VERSION = 0`，持久化协调器会拒绝无法升级的旧格式或更新格式；在 Developer Preview 阶段，这意味着长生命周期会话不应被当作稳定资产。试点需要固定提交，并接受迁移、导出或放弃历史的可能性。 ### 安全策略是可组合能力，但不是全局护栏 默认权限预设把 `workspace-write + ask` 与 `danger-full-access + never` 组合成两个选择，审批缺失时 fail-closed；这比把“是否询问”散落在每个工具内更清晰。[Permission presets](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/subsystems/permission-presets.md) 需要注意的是，策略 seam 只有在工具主动接入或部署增加 `tools/pre-execute` 策略时才生效。官方 Web 工具说明明确指出，它的两个工具本身不会请求 `ctx.approval`，也没有持久 URL 或域名授权；需要确认的部署必须另外挂载策略。[Web tool](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/web/tool-web/README.md) 因此，不能仅凭“系统有 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](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/README.md) [开发指南](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/development.md) 扩展有两条路径。已有能力的轻量改造，可以先用 `dsh --profile web --dump-config` 查看最终配置，再按配置行 ID 用 patch 整体替换；新增模型、工具、策略、会话后端或 loop，则需要实现 Cordis 插件，把它加入 Bundle/Profile，并同时处理服务依赖、事件或 waterfall、effect 清理和测试。后者不是“放入一个脚本即可”的低成本插件：当前项目仍处于 Developer Preview，配置 inventory 又不能完整回答某一行由哪层引入，因此试点需要固定提交、锁定插件版本，并为每个自定义插件建立组合测试和升级回滚检查。 ## 与常见 Harness 的差异 下表比较的是同一生命周期上的架构边界，不是产品效果排名。冻结版本分别为 [Codex `053dda6`](https://github.com/openai/codex/tree/053dda6b897887c0bbd8efa5d4952a4380dbb5e4)、[Gemini CLI `1ac3377`](https://github.com/google-gemini/gemini-cli/tree/1ac3377395868295e128b96726d605a900b5946b) 与 [OpenHands `4f465f3`](https://github.com/All-Hands-AI/OpenHands/tree/4f465f3ccada5271a3bbe4a0148941b0c40d243b)。 | 维度 | 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，深度可替换性未必能抵消兼容与运维成本；如果团队正在建设多种执行器、策略、持久化或交互形态，它提供了值得借鉴的边界设计。 ## 相关评测与验证现状 ### 没有发现公开的 Agent 任务成绩 本文把“公开 Agent 能力评测结果”限定为同时具有明确任务或数据集、指标与分母、已测量结果。按此口径，在冻结提交的 README、`BENCHMARK.md`、文档、工作流和相关文件中，没有发现 SWE-bench、Terminal-Bench、AgentBench 或 GAIA 等任务的公开成绩。 [`BENCHMARK.md`](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/BENCHMARK.md) 只有一条运行说明：通过 Python SDK 启动 `jsonrpc-agent` minimal variant，并为独立任务使用不同 workspace 与 session ID。它是 benchmark 接入口，不是评测方案或成绩。这个结论严格限于 2026 年 8 月 14 日的冻结仓库与官方公开页面；准确表述是“在该范围内未发现”，不是“项目从未评测”。 ### 仓库已有三类相关评测资产 | 类型 | 任务与指标 | 是否有仓库内正式成绩 | 能说明什么 | |---|---|---|---| | 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 能力 | 仓库还包含单元测试、keyless snapshot、Web Chromium snapshot、真实组合测试与可选真实 API e2e。开发文档强调 CI 对 package source 执行逐文件 100% coverage，但也明确指出 coverage 只是必要条件，不能单独证明行为质量。[开发指南](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/development.md) ### 边界验证不能填补效果证据 冻结提交曾在 macOS arm64 上完成 typecheck；针对 Agent loop、工具管线、会话持久化和用户审批的 35 个测试文件、890 个用例通过；10 万 chunk 压力用例在补齐 Playwright Chromium 后通过，一次观测到的最大主线程延迟约 40.4 ms、计划交互延迟约 1.4 ms，低于仓库 250 ms 门槛。 这些结果只证明该提交在单台机器上的构建合约、定向组件测试与一次前端压力复现。没有运行真实模型任务、全量测试、Docker、跨平台矩阵或同任务对照；长历史性能脚本没有完成。因此它们不能填补 Agent 任务效果证据的缺口，也不应升级为官方成绩。 ## 风险与采用门槛 | 门槛 | 当前状态 | 证据 | 判断 | |---|---|---|---| | 观察 | 文档、源码和入口足以形成机制判断 | 架构文档、源码、冻结提交 | **通过** | | 隔离试点 | 需要固定版本、一次性 workspace、低风险任务、明确权限与恢复方案 | 构建/定向测试通过；权限与恢复机制可审计 | **有条件通过** | | 组织级采用 | 需要兼容/迁移承诺、目标任务复现评测、安全审查、升级回滚和责任人 | Developer Preview、格式 v0、无正式 Release、未发现公开 Agent 任务成绩 | **不通过** | 截至调研日，官方 README 明确标注 Developer Preview 并预告兼容性破坏；[GitHub Releases](https://github.com/deepseek-ai/deepseek-harness/releases) 页面没有正式 Release。版本与发布状态本身不否定技术价值，但会显著增加升级、会话迁移和插件兼容成本。 如果进入隔离试点，建议固定 `47f9438` 或新选定提交，使用可丢弃 workspace，保留默认 `workspace-write + ask`，逐项确认 Web、文件、shell 与外部服务能力是否真正接入审批策略，并把会话导出与版本切换当作可失败项。试点只能回答“它是否适合我们的具体任务和运维方式”，不能用一次成功演示替代采用评审。 ## 建议 现在可以把 dsh 纳入架构观察清单，并安排一个受限试点；不应直接替换现有生产 Harness。观察重点应放在三处：插件树对多产品形态的复用是否真的降低 fork 成本；事件日志能否让恢复、审计和 UI 投影保持一致；工具策略在自定义插件和 Web 能力接入后是否仍然 fail-closed。 从“试点”升级到“采用评估”至少要看到三项变化：项目给出更稳定的发布与迁移政策；在固定模型、工具、预算和任务集下产生可复现的目标任务结果；团队完成插件供应链、权限、数据与回滚审查。任一项缺失，都应继续停留在观察或隔离环境。 ## 来源与复现说明 - 目标仓库：[deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) - 冻结提交：[`47f943859bef60e4160492346772ded9b24f765a`](https://github.com/deepseek-ai/deepseek-harness/tree/47f943859bef60e4160492346772ded9b24f765a) - 主要官方文档：[README](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/README.md)、[Architecture](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/architecture.md)、[Persistence](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/session/session-persistence/README.md)、[Tools](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/core/tools/README.md)、[Benchmark entry](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/BENCHMARK.md) - 证据等级：官方声明与源码文档、冻结源码、仓库测试/CI、边界执行结果、明确标注的推断；不同等级不互相替代。 - 未核验：真实模型端到端效果、生产负载、跨版本迁移、第三方插件生态质量、组织级安全与运维成本。