publish DeepSeek Harness architecture research

content/posts/deepseek-harness-architecture-evaluation.md

@@ -0,0 +1,134 @@
+---
+{
+  "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、边界执行结果、明确标注的推断；不同等级不互相替代。
+- 未核验：真实模型端到端效果、生产负载、跨版本迁移、第三方插件生态质量、组织级安全与运维成本。

public/articles/deepseek-harness-architecture-evaluation/dsh-agent-flow.svg

@@ -0,0 +1,32 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1440" height="820" viewBox="0 0 1440 820" role="img" aria-labelledby="title desc">
+  <title id="title">DeepSeek Harness 从配置组合到会话持久化的主链路</title>
+  <desc id="desc">Profile 与 patch 生成 Cordis 插件树。用户输入进入 Agent inbox，组装系统提示和工具 schema，调用模型，工具调用经过审批和执行管线，结果写入 SessionEvent 日志并驱动下一步、恢复和界面。</desc>
+  <defs>
+    <style>
+      .bg{fill:#f7f4ec}.ink{fill:#20211f}.muted{fill:#666b62}.box{fill:#fffdf7;stroke:#2b5d50;stroke-width:2}.box2{fill:#eef5ef;stroke:#2b5d50;stroke-width:2}.warn{fill:#fff2df;stroke:#b66a2b;stroke-width:2}.line{stroke:#2b5d50;stroke-width:3;fill:none;marker-end:url(#arrow)}.dash{stroke:#8a8f86;stroke-width:2;stroke-dasharray:8 8;fill:none;marker-end:url(#arrow2)}.t{font:600 24px -apple-system,BlinkMacSystemFont,"PingFang SC",sans-serif}.s{font:400 18px -apple-system,BlinkMacSystemFont,"PingFang SC",sans-serif}.tiny{font:400 16px -apple-system,BlinkMacSystemFont,"PingFang SC",sans-serif}.cap{font:700 15px ui-monospace,SFMono-Regular,monospace;letter-spacing:1px}
+    </style>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="#2b5d50"/></marker>
+    <marker id="arrow2" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="#8a8f86"/></marker>
+  </defs>
+  <rect class="bg" width="1440" height="820" rx="32"/>
+  <text x="72" y="68" class="t ink">DeepSeek Harness 主链路：组合、执行、记录</text>
+  <text x="72" y="101" class="s muted">配置决定运行时；事件日志连接执行、恢复与界面。</text>
+  <rect x="70" y="150" width="280" height="145" rx="18" class="box2"/>
+  <text x="95" y="184" class="cap muted">BOOT / COMPOSITION</text><text x="95" y="224" class="t ink">Profile + Bundles</text><text x="95" y="257" class="s muted">home patch · --patch</text>
+  <rect x="420" y="150" width="300" height="145" rx="18" class="box"/>
+  <text x="445" y="184" class="cap muted">CORDIS CONTEXT</text><text x="445" y="224" class="t ink">插件树</text><text x="445" y="257" class="s muted">services · events · effects</text>
+  <rect x="790" y="150" width="300" height="145" rx="18" class="box"/>
+  <text x="815" y="184" class="cap muted">TURN INPUT</text><text x="815" y="224" class="t ink">Agent inbox</text><text x="815" y="257" class="s muted">prompt · followup · steer</text>
+  <rect x="1160" y="150" width="210" height="145" rx="18" class="box"/>
+  <text x="1185" y="184" class="cap muted">PRE-STEP</text><text x="1185" y="224" class="t ink">上下文组装</text><text x="1185" y="257" class="tiny muted">history + tools</text>
+  <path d="M350 222 H420" class="line"/><path d="M720 222 H790" class="line"/><path d="M1090 222 H1160" class="line"/>
+  <rect x="1070" y="390" width="300" height="150" rx="18" class="box2"/><text x="1095" y="425" class="cap muted">MODEL STEP</text><text x="1095" y="465" class="t ink">LLM stream</text><text x="1095" y="500" class="s muted">assistant chunks / message</text>
+  <rect x="600" y="390" width="390" height="150" rx="18" class="warn"/><text x="625" y="425" class="cap muted">GUARDED TOOL PIPELINE</text><text x="625" y="465" class="t ink">pre → approval → execute → post</text><text x="625" y="500" class="s muted">缺审批通道时 ask 退化为 deny</text>
+  <rect x="70" y="390" width="450" height="150" rx="18" class="box"/><text x="95" y="425" class="cap muted">DURABLE FACTS</text><text x="95" y="465" class="t ink">append-only SessionEvent log</text><text x="95" y="500" class="s muted">user · assistant · tool · turn · policy</text>
+  <path d="M1265 295 V390" class="line"/><path d="M1070 465 H990" class="line"/><path d="M600 465 H520" class="line"/>
+  <rect x="70" y="650" width="300" height="100" rx="18" class="box2"/><text x="95" y="690" class="t ink">派生模型历史</text><text x="95" y="720" class="s muted">下一步请求使用</text>
+  <rect x="470" y="650" width="300" height="100" rx="18" class="box2"/><text x="495" y="690" class="t ink">恢复与分叉</text><text x="495" y="720" class="s muted">resume · fork · repair</text>
+  <rect x="870" y="650" width="300" height="100" rx="18" class="box2"/><text x="895" y="690" class="t ink">Web / SDK 投影</text><text x="895" y="720" class="s muted">trajectory · UI · API</text>
+  <path d="M210 540 V650" class="dash"/><path d="M295 540 C360 600 560 590 620 650" class="dash"/><path d="M420 540 C600 590 980 580 1020 650" class="dash"/>
+  <text x="70" y="790" class="tiny muted">图源：DeepSeek Harness 冻结提交 47f9438 的 architecture、agent-loop、tools 与 session-persistence；2026-08-14 重绘。</text>
+</svg>