DeepSeek's Agent Framework: Even the Agent Loop Is a Plugin

August 19, 2026

AI AgentArchitectureDeveloper Tools

DeepSeek open-sourced an Agent Harness. 40+ packages, 20+ capability seams — the most notable thing: the Agent Loop itself is a plugin, swappable from a YAML config.

This article breaks down how “everything is a plugin” works, from the bottom up.

Everything-is-a-plugin concept

The one-liner

DeepSeek Harness is a plugin-architecture-based Agent runtime. The entire product — including the core Agent Loop — is assembled from plugins. There is no privileged core whose implementation you’re stuck with.

Want a different LLM adapter? Write a plugin. A different filesystem backend? Write a plugin. A different Agent Loop? Write a plugin.

# One line to start the Web UI, default http://127.0.0.1:3080
npx @deepseek-ai/dsh web

But “plugin-ization” isn’t something you achieve by shouting a slogan. It requires a complete design from the lowest-level mechanism to the highest-level application. Let’s work our way up, layer by layer.

1. The foundation: Cordis plugin framework

The foundation of “everything is a plugin” is a framework called Cordis. DeepSeek Harness vendors Cordis in its entirety — all plugin capabilities are built on top of its mechanisms.

Cordis has a small set of core concepts:

flowchart TD
    Plugin["Plugin<br/>object implementing a Service interface"]
    Context["Context<br/>service registry ctx.key"]
    Inject["Inject<br/>declarative dependency injection"]
    Events["Typed Events<br/>type-safe event communication"]
    Effects["Effects<br/>reversible registration = cleanable"]

    Plugin -->|"mounts to"| Context
    Plugin -->|"declares needs"| Inject
    Context -->|"dispatches"| Events
    Plugin -->|"registers via effect/on"| Effects
    Effects -->|"auto-cleaned on unmount"| Context

    style Plugin fill:#e3f2fd
    style Context fill:#e8f5e9
    style Events fill:#fff3e0
    style Effects fill:#fce4ec

The most interesting bit is the reversibility of Effects. Everything a plugin registers — tools, prompt snippets, event listeners — goes through ctx.effect() or ctx.on(), and gets cleaned up automatically on unmount. That sounds simple, but read through enough Agent framework plugin systems and you’ll find almost none of them actually do it — either the registration lives forever, or unmounting leaves state behind.

Cordis provides the effect mechanism at the base layer; DeepSeek Harness is the first framework I’ve seen apply it at the Agent-framework level: registration is a side effect, unmount is cleanup, guaranteed at the framework level. This is the prerequisite for the entire “replaceability” story — if plugins can’t clean up after themselves, who would risk swapping components?

Cordis plugin architecture

2. The pattern: Capability Seam (three-role separation)

With a plugin framework in place, the next question is: how do you organize “capabilities” using the plugin framework?

“Adding a capability” in most frameworks means writing a function and registering it in a tool table. When something breaks you dig through source to find the interface, and switching backends means touching the Consumer.

DeepSeek Harness formalizes “capability” into three roles, called a Seam:

flowchart LR
    SD["Service Definition<br/>declares interface + ctx key<br/>(abstract class / registry)"]
    SP["Service Provider<br/>implements interface<br/>(can be several)"]
    Consumer["Consumer<br/>uses interface<br/>(usually a model tool)"]

    SD -->|"implemented by"| SP
    SD -->|"injected into"| Consumer
    SP -->|"supplies"| Consumer

    style SD fill:#e3f2fd
    style SP fill:#e8f5e9
    style Consumer fill:#fff3e0

Taking the Shell capability as an example:

Role	Package	Responsibility
Service Definition	`dsh-shell`	Declares the `ctx.shell` interface and types
Service Provider	`dsh-bash-local`	Local bash execution
Service Provider	`dsh-bash-sandbox`	Sandboxed bash execution
Consumer	`dsh-tool-bash`	The bash tool the model sees

Swapping a Provider doesn’t touch the Consumer. To go from local execution to an E2B remote sandbox, swap one provider package — the tool definition stays exactly as it is. This is where “replaceability” lands in the code.

The repo has 20+ such seams:

Domain	Seam	Provider count
Model	`ctx.llm`	3 (DeepSeek / pi-agents / replay)
Filesystem	`ctx.fs`	3 (local / e2b / sandbox)
Subprocess	`ctx.subprocess`	2 (local / e2b)
Shell	`ctx.shell`	2 (bash-local / bash-sandbox) + pwsh
Terminal	`ctx.terminals`	1 (terminal-bash)
Subagents	`ctx.subagents`	6 (spawn/fork/sdk/ACP/Codex/Claude Code)
Sandbox	`ctx.sandbox`	3 backends (bwrap / Landlock / Seatbelt)
Web	`ctx.web`	4 (Exa / Perplexity / DeepSeek search / HTTP fetch)
LSP	`ctx.lsp`	1 (stdio)
Persistence	`ctx.sessionPersistence`	2 (JSONL / SQLite)

The 6 subagent backends include providers that talk directly to Codex and Claude Code. The sandbox also comes in three flavors (bwrap / Landlock / Seatbelt), covering Linux, macOS’s newer security module, and the classic macOS sandbox.

3. The application: Agent Loop is a plugin

With Cordis’s plugin mechanism and the Seam three-role pattern, “Agent Loop is a plugin” is no surprise — it’s the most natural outcome of the system.

In most Agent frameworks the loop is hard-coded — changing execution strategy means changing core code. DeepSeek Harness makes the Loop a ctx.agentLoop service, on equal footing with every other service. You specify which implementation to use in cordis.yml.

Extending it doesn’t require editing source or writing monkey patches:

Swap the LLM adapter → register a new ctx.llm provider
Swap the filesystem backend → swap the ctx.fs provider (local → E2B sandbox)
Swap the Agent Loop → swap ctx.agentLoop
Add an approval policy → listen to agent/* events

Agent event flow

A single agent interaction splits into two layers, Turn and Step:

Turn — one complete input consumption, from model through tool execution to the end
Step — one model request plus the tool calls it triggers

sequenceDiagram
    participant User as User/Input
    participant AgentLoop as Agent Loop
    participant Prompt as Prompt Assembly
    participant LLM as LLM Adapter
    participant Tools as Tool Pipeline

    User->>AgentLoop: turn/start
    AgentLoop->>AgentLoop: claim input + queue messages
    AgentLoop->>Prompt: assemble prompt sections + tool schemas
    AgentLoop->>AgentLoop: agent/pre-step (waterfall)
    AgentLoop->>LLM: step/start → agent/request → llm/stream
    LLM-->>AgentLoop: assistant/chunk* → assistant/message
    AgentLoop->>Tools: tool/call → pre-execute → execute → post-execute → result
    Tools-->>AgentLoop: tool/result
    AgentLoop->>AgentLoop: step/end
    alt more tool requests or new input
        AgentLoop->>AgentLoop: next step
    end
    AgentLoop->>AgentLoop: agent/turn-stopping (serial)
    AgentLoop-->>User: turn/end

Events live in three domains:

Event domain	Persisted?	Purpose
`session/*`	✅ written to log	facts that survive restarts
`agent/*`	❌ real-time	observe/intercept a live Agent
Capability-domain events	❌ real-time	attach policy and adapters to seams

Waterfall events (agent/pre-step, agent/request, llm/stream, tools/*) are around-middleware — listeners must delegate via next(), and the chain short-circuits if they don’t. Same pattern as Express/Koa middleware, but type-safe.

4. Operations: Session Log as the single source of truth

Components are replaceable, the runtime runs — but how do you trace problems when things go wrong?

What does the model actually see during a run? Most frameworks only keep a prompt log; session history, tool calls, and context injection are scattered around.

DeepSeek Harness builds an append-only event stream called the Session Log, and derives every fact from it:

flowchart TD
    subgraph SessionLog["Session Event Log"]
        direction TB
        E1["user/message"]
        E2["assistant/chunk"]
        E3["assistant/message"]
        E4["tool/call"]
        E5["tool/result"]
        E6["turn/start · turn/end"]
        E7["step/start · step/end"]
    end

    Model["model request"] -->|"deriveMessages()<br/>built-in message derivation"| SessionLog
    UI["Web UI rendering"] -->|"session/event"| SessionLog
    Persist["persistence<br/>JSONL / SQLite"] -->|"write"| SessionLog
    Fork["Fork / Resume"] -->|"copy from"| SessionLog
    Telemetry["telemetry"] -->|"derive"| SessionLog

    style SessionLog fill:#e3f2fd

There’s one rule that’s enforced especially hard: model-visible must be logged.

This isn’t a “suggestion” — there’s a runtime invariant assertion in the code. If something reaches a model request but can’t be rebuilt from the session log, it errors out.

Practical payoff: you changed a context-injection rule — how do you confirm the model actually saw it? Check the log. No corresponding event in the log, and the model definitely didn’t see it. Fork, Resume, telemetry — all derived from that one stream, no second set of state to maintain.

The “model-visible ⟺ logged” invariant is the single most portable Agent design principle I’ve come across. It turns “what the model sees must be traceable” from a best practice into a runtime check.

5. Configuration: Profile + Bundle + Patch

Components are replaceable, the log is traceable — but how do you compose all these pieces into a working Agent?

Agent run modes differ a lot: the Web UI needs a server plus frontend, Headless is a one-shot runner, ACP speaks JSON-RPC. Most frameworks either hard-code a few modes or cobble them together from env vars.

DeepSeek Harness uses three layers:

flowchart TD
    Profile["Profile<br/>named composition<br/>(web / headless / acp)"]
    Bundle["Bundle<br/>installable plugin layers<br/>(base / web-app / headless)"]
    Patch["Patch<br/>config overrides<br/>(cordis.patch.yml)"]

    Profile -->|"includes multiple"| Bundle
    Profile -->|"stacks"| Patch

    Base["dsh-base<br/>model + tools + persistence + sandbox"]
    WebApp["dsh-web-app<br/>browser app"]
    Headless["dsh-headless<br/>one-shot runner"]

    Bundle -.-> Base
    Bundle -.-> WebApp
    Bundle -.-> Headless

    style Profile fill:#e3f2fd
    style Bundle fill:#e8f5e9
    style Patch fill:#fff3e0

Profile — a named composition; web and headless ship out of the box
Bundle — a distributable plugin layer; a profile stacks multiple bundles
Patch — a YAML override; replace any config line or insert new ones

Boot order: Bundle → profile-level patch → home-level patch → --patch CLI override.

# Inspect the actual config tree that boots
dsh --profile web --dump-config

Any line of the output can be replaced by a patch. Editing YAML has a lower bar than editing code, so operators can tune Agent behavior without touching source.

6. Quality: docs as code

Architecture, operations, and configuration are all in place — but what’s the biggest fear for an open-source project? Docs and code drifting apart. Over time, the docs say one thing and the code does another. New contributors walk in confused.

DeepSeek Harness’s answer isn’t “people should be disciplined” — it’s making doc consistency a CI gate:

A type definition pasted into the docs doesn’t match the source? CI fails. A broken link? CI fails. An exported function missing JSDoc? CI fails. Docs over the word budget? CI fails.

Any non-trivial code change must ship with an Agent Note (a design-decision doc) in the same PR. Not a suggestion — a gate. No note, no merge.

This level of quality control is rare in open source. But it has a prerequisite — the architecture layers above must be stable first, so there’s bandwidth for this kind of engineering infrastructure. Don’t treat “docs as code” as step one. It’s the last step.

7. Comparison and trade-offs

If you were to place DeepSeek Harness on a coordinate system, the opposite end would be Pi Agent — a minimalist coding agent.

Dimension	Pi	DeepSeek Harness
Design philosophy	Cut what you can	Split what you can
Agent Loop	Hard-coded	Replaceable, configurable from YAML
Plugin-ization	Light extension	Everything-as-a-service, 40+ packages
Self-modification	Human configures it	Agent can mount/unmount its own plugins
Learning curve	Low	High (40+ packages)

Neither direction is right or wrong — it depends on the scenario.

Where this is worth referencing

Building a highly-customizable Agent platform — the three-role capability seam separation ports directly
Need multi-backend switching (local / sandbox / remote) — the Provider pattern is the standard answer
Session reliability matters — the “model-visible ⟺ logged” invariant
Team-grade agents need access control — approvals + sandbox backends combined

Where it’s not a fit

Lightweight personal tools — Pi’s “light Harness” fits better; 40+ packages is over-engineering for a personal tool
Rapid prototyping — the declarative config + three-layer composition learning curve doesn’t suit fast trial-and-error
Non-TypeScript stacks — it’s deeply tied to the TypeScript type system; porting cost is high

Directly reusable design principles

Build capabilities as three-role seams — split Service Definition / Provider / Consumer so swapping a Provider never touches the Consumer
Make the session log the single source of truth — what the model sees must be reconstructible from one log stream
Registration as side effect, unmount as cleanup — don’t manage lifecycle by hand
Keep config declarative — YAML composition over code if-else
Turn “model-visible ⟺ logged” into a runtime assertion — a gate, not a guideline

Closing

Pi is “cut what you can”, DeepSeek Harness is “split what you can”. What they share is having thought hard about “what belongs in the framework and what doesn’t” — Pi’s answer is “as little as possible”, DeepSeek’s is “everything pluggable”.

If you’re building an Agent platform, three design ideas are worth taking with you:

Capability Seam three-role separation — Providers are replaceable, Consumers don’t change
Session Log as source of truth — what the model sees must be traceable, enforced as a runtime invariant
Replaceable Agent Loop — even the most “core” component doesn’t have to be a privileged core

Appendix: Basics

Item	Value
Repo	deepseek-ai/deepseek-harness
Version	`0.1.0-rc.5` (developer preview)
License	MIT
Runtime	Node.js 22.19+ / 24+
Package manager	pnpm 11.7 workspaces
Underlying framework	Cordis (vendored, has a paper)
Package count	40+ npm packages (`@deepseek-ai/dsh-*`)
Build	tsc + tsdown
Testing	5 layers, including a 100% line-coverage gate

References

DeepSeek Harness repo — verified: README, AGENTS.md, architecture.md, development.md, cordis-primer.md, packages/README.md
Cordis framework
Cordis paper: A Programming Paradigm for Spatiotemporal Composability (not line-by-line verified)
Comparison reference: Pi Agent Design Philosophy

DeepSeek 开源了一个 Agent Harness。40+ 包、20+ 个能力接缝，最值得注意的是——Agent Loop 本身是个插件，可以从 YAML 配置里换掉。

这篇文章从底层到上层，拆解”一切皆插件”是怎么做到的。

一切皆插件示意

一句话定位

DeepSeek Harness 是一个基于插件架构的 Agent 运行时。整个产品——包括最核心的 Agent Loop——都是插件拼出来的，没有一个”特权核心”是必须接受其实现的。

想换 LLM 适配器？写一个插件。想换文件系统后端？写一个插件。想换 Agent Loop 本身？写一个插件。

# 想试一把的话，一行启动 Web UI，默认 http://127.0.0.1:3080
npx @deepseek-ai/dsh web

但”插件化”不是喊一句口号就能实现的。它需要从底层机制到上层应用的一整套设计。下面从最底层开始，一层层往上讲。

1. 地基：Cordis 插件框架

一切皆插件的根基，是一个叫 Cordis 的插件框架。DeepSeek Harness 把 Cordis 整个 vendored 进来，所有插件能力都建立在它的机制之上。

Cordis 的核心概念不多，四个：

flowchart TD
    Plugin["Plugin<br/>实现 Service 接口的对象"]
    Context["Context<br/>服务仓库 ctx.key"]
    Inject["Inject<br/>声明式依赖注入"]
    Events["Typed Events<br/>类型化事件通信"]
    Effects["Effects<br/>可逆注册 = 可清理"]
    
    Plugin -->|"挂载到"| Context
    Plugin -->|"声明需要"| Inject
    Context -->|"分发"| Events
    Plugin -->|"通过 effect/on 注册"| Effects
    Effects -->|"卸载时自动清理"| Context

    style Plugin fill:#e3f2fd
    style Context fill:#e8f5e9
    style Events fill:#fff3e0
    style Effects fill:#fce4ec

最值得说的是 Effects 的可逆性。插件注册的东西（工具、prompt 片段、事件监听器）都走 ctx.effect() 或 ctx.on()，卸载时自动清理。听起来简单，但翻过不少 Agent 框架的插件系统就知道，真正做到的几乎没有——要么注册了就一直在，要么卸载了但状态没清干净。

Cordis 在底层提供了 effect 机制，DeepSeek Harness 是第一个在 Agent 框架层面把它用到位的：注册即副作用，卸载即清理，做成框架级保证。这一条是整个”可替换”能力的前提——如果插件卸载不干净，谁敢换组件？

Cordis 插件架构

2. 模式：Capability Seam 三层接缝

有了插件框架，下一个问题是：怎么用插件框架来组织”能力”？

大部分框架的”加一个能力”就是写个函数注册到工具表。出了问题翻源码找接口，想换后端得改 Consumer。

DeepSeek Harness 把”能力”规范化为三层角色，称为 Seam（接缝）：

flowchart LR
    SD["Service Definition<br/>声明接口 + ctx key<br/>（抽象类/注册表）"]
    SP["Service Provider<br/>实现接口<br/>（可以多个）"]
    Consumer["Consumer<br/>使用接口<br/>（通常是模型工具）"]
    
    SD -->|"实现"| SP
    SD -->|"注入"| Consumer
    SP -->|"供给"| Consumer

    style SD fill:#e3f2fd
    style SP fill:#e8f5e9
    style Consumer fill:#fff3e0

拿 Shell 能力举例：

角色	包	职责
Service Definition	`dsh-shell`	声明 `ctx.shell` 接口和类型
Service Provider	`dsh-bash-local`	本地 bash 执行
Service Provider	`dsh-bash-sandbox`	沙箱内 bash 执行
Consumer	`dsh-tool-bash`	模型面对的 bash 工具

换 Provider 不用动 Consumer。 想从本地执行切到 E2B 远程沙箱，换一个 provider 包就行，工具定义完全不需要改动。这是”可替换”在代码层面的落点。

仓库里有 20+ 个这样的接缝：

领域	接缝	Provider 数
模型	`ctx.llm`	3（DeepSeek / pi-agents / replay）
文件系统	`ctx.fs`	3（local / e2b / sandbox）
子进程	`ctx.subprocess`	2（local / e2b）
Shell	`ctx.shell`	2（bash-local / bash-sandbox）+ pwsh
终端	`ctx.terminals`	1（terminal-bash）
子代理	`ctx.subagents`	6（spawn/fork/sdk/ACP/Codex/Claude Code）
沙箱	`ctx.sandbox`	3 后端（bwrap / Landlock / Seatbelt）
Web	`ctx.web`	4（Exa / Perplexity / DeepSeek 搜索 / HTTP fetch）
LSP	`ctx.lsp`	1（stdio）
持久化	`ctx.sessionPersistence`	2（JSONL / SQLite）

子代理有 6 种后端，包括直接对接 Codex 和 Claude Code 的 provider。沙箱也做了三种，分别对应 Linux / macOS 新版 / macOS 传统。

3. 应用：Agent Loop 是插件

有了 Cordis 的插件机制和 Seam 的三层模式，“Agent Loop 是插件”就不意外了——它是这套体系最自然的产物。

大多数 Agent 框架的 Loop 是写死的——你想改执行策略就得改核心代码。DeepSeek Harness 把 Loop 做成了一个 ctx.agentLoop 服务，跟其他服务平级。你可以在 cordis.yml 里指定用哪个实现。

实际扩展的时候不用改源码，不用写 monkey patch：

替换 LLM 适配器 → 注册新的 ctx.llm provider
替换文件系统后端 → 换 ctx.fs provider（本地 → E2B 沙箱）
替换 Agent Loop → 换 ctx.agentLoop
添加审批策略 → 监听 agent/* 事件

Agent 事件流

一次 Agent 交互拆成 Turn 和 Step 两层：

Turn — 一次完整的输入消耗，模型 + 工具执行到结束
Step — 一次模型请求 + 触发的工具调用

sequenceDiagram
    participant User as 用户/输入
    participant AgentLoop as Agent Loop
    participant Prompt as Prompt 组装
    participant LLM as LLM 适配器
    participant Tools as 工具管道
    
    User->>AgentLoop: turn/start
    AgentLoop->>AgentLoop: 认领输入 + 队列消息
    AgentLoop->>Prompt: 组装 prompt sections + tool schemas
    AgentLoop->>AgentLoop: agent/pre-step (waterfall)
    AgentLoop->>LLM: step/start → agent/request → llm/stream
    LLM-->>AgentLoop: assistant/chunk* → assistant/message
    AgentLoop->>Tools: tool/call → pre-execute → execute → post-execute → result
    Tools-->>AgentLoop: tool/result
    AgentLoop->>AgentLoop: step/end
    alt 工具需要更多请求 或 有新输入
        AgentLoop->>AgentLoop: 下一个 step
    end
    AgentLoop->>AgentLoop: agent/turn-stopping (serial)
    AgentLoop-->>User: turn/end

事件分三种域：

事件域	持久化？	用途
`session/*`	✅ 写入日志	跨重启存活的事实
`agent/*`	❌ 实时	观察/拦截工作中的 Agent
能力域事件	❌ 实时	给接缝附加策略和适配器

Waterfall 事件（agent/pre-step、agent/request、llm/stream、tools/*）是 around-middleware，监听者必须调 next() 委托，不调就短路。与 Express/Koa 中间件模式相同，但增加了类型安全。

4. 运营：Session Log 唯一事实源

组件可替换了，运行也跑起来了，但出问题怎么追溯？

Agent 运行过程中模型看到了什么？大部分框架只有 prompt 日志，Session 历史、工具调用、上下文注入散落各处。

DeepSeek Harness 做了一条 append-only 的事件流，叫 Session Log，所有事实从这条流里派生：

flowchart TD
    subgraph SessionLog["Session Event Log"]
        direction TB
        E1["user/message"]
        E2["assistant/chunk"]
        E3["assistant/message"]
        E4["tool/call"]
        E5["tool/result"]
        E6["turn/start · turn/end"]
        E7["step/start · step/end"]
    end
    
    Model["模型请求"] -->|"deriveMessages()<br/>框架内置消息派生"| SessionLog
    UI["Web UI 渲染"] -->|"session/event"| SessionLog
    Persist["持久化<br/>JSONL / SQLite"] -->|"write"| SessionLog
    Fork["Fork / Resume"] -->|"copy from"| SessionLog
    Telemetry["遥测"] -->|"derive"| SessionLog

    style SessionLog fill:#e3f2fd

有一条规则写得特别硬：模型可见的（model-visible），必须来自日志。

这不是”建议”——代码里有运行时不变量断言。如果有东西到达了模型请求但不能从 session log 重建，直接报错。

实际用途：你改了一个上下文注入逻辑，怎么确认模型真的看到了？看日志。日志里没有对应事件，模型就一定没看到。Fork、Resume、遥测——全部从这条流里派生，不用维护第二套状态。

“model-visible ⟺ logged”这条断言，是我见过最有传播价值的一个 Agent 设计原则。 它把”模型看到的东西必须可追溯”从一条最佳实践变成了一个运行时检查。

5. 配置：Profile + Bundle + Patch

组件可替换了，日志可追溯了，但这么多组件怎么组合成一个可运行的 Agent？

Agent 的运行模式差异很大：Web UI 要服务器 + 前端，Headless 只要一次性执行，ACP 要 JSON-RPC。大部分框架要么写死几种模式，要么靠环境变量拼。

DeepSeek Harness 用了三层：

flowchart TD
    Profile["Profile<br/>命名组合<br/>（web / headless / acp）"]
    Bundle["Bundle<br/>可安装的插件层<br/>（base / web-app / headless）"]
    Patch["Patch<br/>覆盖配置<br/>（cordis.patch.yml）"]
    
    Profile -->|"包含多个"| Bundle
    Profile -->|"可叠加"| Patch
    
    Base["dsh-base<br/>模型 + 工具 + 持久化 + 沙箱"]
    WebApp["dsh-web-app<br/>浏览器应用"]
    Headless["dsh-headless<br/>一次性运行器"]
    
    Bundle -.-> Base
    Bundle -.-> WebApp
    Bundle -.-> Headless

    style Profile fill:#e3f2fd
    style Bundle fill:#e8f5e9
    style Patch fill:#fff3e0

Profile — 命名组合方案，web 和 headless 出厂自带
Bundle — 可分发的插件层，一个 profile 堆叠多个 bundle
Patch — YAML 覆盖，替换任意配置行或插入新行

启动顺序：Bundle → profile 级 patch → home 级 patch → --patch 命令行覆盖。

# 看实际启动的配置树
dsh --profile web --dump-config

输出的任何一行都可以被 patch 替换。改 YAML 比改代码门槛低，运营也能调 Agent 行为。

6. 质量：文档即代码

架构、运营、配置都到位了，但开源项目最怕什么？文档和代码分家。 时间一长，文档说的跟代码做的不一样，新贡献者进来一脸懵。

DeepSeek Harness 的解法不是靠人自觉，是把文档一致性做成了 CI 门禁：

文档里粘贴的类型定义跟源码不一致？CI 挂。链接断了？CI 挂。导出的函数没写 JSDoc？CI 挂。文档超字数预算？CI 挂。

非平凡的代码变更必须在同一 PR 附带 Agent Note（设计决策文档）。不是建议，是门禁——没有就合不了。

这种程度的质量控制在开源项目里不常见。但要注意：它是有前提的——前面几层架构设计已经稳定了，才有余力做这种工程基建。别把”文档即代码”当成第一步，它是最后一步。

7. 对比与取舍

如果用一个坐标系定位 DeepSeek Harness，另一端是 Pi Agent——一个极简主义的 coding agent。

维度	Pi	DeepSeek Harness
设计哲学	能砍就砍	能拆就拆
Agent Loop	写死	可替换，可从 YAML 配
插件化程度	轻扩展	一切皆服务，40+ 包
自修改能力	人去配置	Agent 可自挂载/卸载插件
学习曲线	低	高（40+ 包）

两个方向没有对错，看场景。

适合参考的场景

自研 Agent 平台需要高度可定制 — 能力接缝的三层角色分离可以直接搬
需要多后端切换（本地/沙箱/远程）— Provider 模式是标准答案
Session 可靠性要求高 — “model-visible ⟺ logged”断言
团队级 Agent 需要权限控制 — 审批 + 沙箱后端组合

不适合的场景

轻量级个人工具 — Pi 的”轻 Harness”更合适，40+ 包的复杂度对个人工具是过度工程
快速原型 — 声明式配置 + 三层组合的学习曲线不适合快速试错
非 TypeScript 技术栈 — 深度绑定 TypeScript 类型系统，移植成本高

可直接复用的设计原则

能力做三层接缝，Service Definition / Provider / Consumer 拆开，换 Provider 不影响 Consumer
Session 日志是唯一事实源，模型看到的东西必须能从一条日志流重建
注册即副作用，卸载即清理，别手动管生命周期
配置声明式，YAML 组合 > 代码 if-else
“model-visible ⟺ logged”做成运行时断言，不当建议当门禁

收尾

Pi 是”能砍就砍”，DeepSeek Harness 是”能拆就拆”。共同点是都想清楚了”什么该在框架里，什么不该在”——Pi 的答案是”尽量少”，DeepSeek 的答案是”全部可插拔”。

如果你在做 Agent 平台，值得带走的三个设计思路：

Capability Seam 三层分离 — Provider 可替换，Consumer 不用改
Session Log 事实源 — 模型看到的东西必须可追溯，且做成运行时断言
Agent Loop 可替换 — 最”核心”的组件也可以不是特权核心

附录：基本面

项	值
仓库	deepseek-ai/deepseek-harness
版本	`0.1.0-rc.5`（开发者预览）
许可	MIT
运行时	Node.js 22.19+ / 24+
包管理	pnpm 11.7 workspaces
底层框架	Cordis（vendored，有论文）
包数量	40+ npm 包（`@deepseek-ai/dsh-*`）
构建工具	tsc + tsdown
测试策略	5 层，含 100% 行覆盖门禁

参考

DeepSeek Harness 仓库：github.com/deepseek-ai/deepseek-harness（已核对：README、AGENTS.md、architecture.md、development.md、cordis-primer.md、packages/README.md）
Cordis 框架：github.com/cordiverse/cordis
Cordis 论文：A Programming Paradigm for Spatiotemporal Composability（未逐字核对）
Pi Agent 设计哲学剖析（对照参考）：Pi Agent