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

---
{
  "title": "DeepSeek Harness 插件化架构与工程评估",
  "summary": "说明 Cordis 如何装配插件，插件如何通信，服务提供方如何选择，以及插件开发、测试和发布如何进行。",
  "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 把模型、工具、会话和执行循环都做成可组合插件。它的架构值得研究，但公开证据目前只支持受限试点，不支持组织级默认采用。

调研冻结在 2026 年 8 月 14 日。目标代码为提交 [`47f943859bef60e4160492346772ded9b24f765a`](https://github.com/deepseek-ai/deepseek-harness/tree/47f943859bef60e4160492346772ded9b24f765a)，该提交与调研日的远端 `HEAD` 一致。本文只评价 Harness 架构、工程流程和公开评测，不评价 DeepSeek 模型能力。

## 一、DeepSeek Harness 的插件化架构

### 1.1 Cordis 插件运行时

DeepSeek Harness 的命令名是 `dsh`。它是一套 Agent 运行外壳：接收请求，调用模型，执行工具，保存会话，并向 Web、ACP 和 SDK 暴露入口。

dsh 主要使用 TypeScript 编写，运行在 Node.js ESM 环境。TypeScript 让插件作者共享类型，但运行时真正加载的是 JavaScript 模块。插件通常导出 `apply(ctx, config)`，或导出一个 `Service` 子类。[根 package.json](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/package.json) [Cordis 插件教程](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/cordis-tutorial/01-first-plugin.zh.md)

| 概念 | 作用 |
|---|---|
| Profile | 选择一种产品形态，例如 Web 或 headless |
| Bundle | 提供一组可复用的默认插件 |
| patch | 增加、替换、禁用或删除配置行 |
| Context | 插件访问 Service、Event 和子插件的入口 |
| Loader | 按有效配置加载插件模块 |
| Fiber | 一次插件挂载的运行实例 |
| Service | 插件向其他插件提供的具名能力 |
| effect | 与 Fiber 同生共死的注册、监听器或资源 |
| Agent loop | 在模型、工具和最终回答之间推进一次任务 |
| SessionEvent | 记录用户消息、模型消息和工具结果等事实 |

Cordis 负责前八项。它把配置变成一组可管理的插件实例，检查服务依赖，并在配置或依赖变化时卸载、重建相关实例。Agent loop 负责每次请求的执行。两者不在同一层。

### 1.2 插件运行时的启动流程

![配置先生成插件运行时](/articles/deepseek-harness-architecture-evaluation/dsh-startup-assembly.png)

启动时，dsh 按顺序合并 Bundle、Profile patch、Harness home patch 和命令行 `--patch`。最终配置由带稳定 `id` 的配置行组成。后层命中同一 `id` 时，会替换该行的完整 `config`，不会做字段级深合并。[CLI 组合参考](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/apps/cli/reference/README.md)

Loader 为每一行创建 Fiber。Fiber 指一次插件挂载的运行实例，与线程和用户请求无关。它保存配置、父 Context、依赖、状态、effect 和清理逻辑。

Fiber 常见状态为 `PENDING → LOADING → ACTIVE → UNLOADING`。插件声明 `inject = ['tools', 'shell']` 后，缺少任一 Service 都会停在 `PENDING`。服务出现后才执行 `apply`；服务被替换或消失时，Cordis 会卸载依赖它的 Fiber，再按新依赖重建。YAML 中的先后顺序不决定启动顺序，Service 是否可用才决定。[Cordis 服务教程](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/cordis-tutorial/03-services.zh.md)

`inject` 只声明硬依赖。插件在某项能力缺失时仍可工作，就不应把它放进 `inject`，而应在使用处调用 `ctx.get('serviceName')`。未挂载 provider 时它返回 `undefined`，Fiber 仍可保持 `ACTIVE`。硬依赖的 provider 被替换时，消费方会重载；可选依赖是否响应变化，则由插件自己的监听和调用方式决定。

插件通过 `ctx.on()` 注册监听器、通过 `ctx.tools.register()` 注册工具，或通过 `ctx.effect()` 管理连接和定时器。这些操作都会返回或绑定清理逻辑。Fiber 卸载时，Cordis 自动撤销它们。插件树表达的正是这种所有权和生命周期关系。

### 1.3 Agent 请求的执行流程

![请求在模型和工具之间循环](/articles/deepseek-harness-architecture-evaluation/dsh-request-flow.png)

一次请求发生在插件全部就绪之后：

1. Web、ACP 或 SDK 把输入交给 Agent inbox。
2. Agent loop 读取会话历史、系统提示和可用工具。
3. 模型直接回答，或发出结构化工具调用。
4. Tools Runtime 校验参数、执行策略和工具。
5. 工具结果回到 Agent loop，模型继续生成。
6. Agent loop 提交最终消息。

`SessionEvent` 在这条链路旁边记录事实。它保存用户消息、step、模型消息、工具调用、工具结果和最终回答，用于历史、恢复、fork 和 UI 投影；工具结果仍由 Agent loop 送回模型。[会话持久化](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/session/session-persistence/README.md)

### 1.4 插件树、依赖图与调用链

插件树、依赖图和调用链分别描述不同关系：

| 关系 | 回答的问题 | 示例 |
|---|---|---|
| 插件树 | 谁挂载谁，谁随谁卸载 | Loader 挂载 `tool-bash` Fiber |
| 依赖图 | 谁必须等待哪项能力 | `tool-bash` 等待 `tools` 和 `shell` |
| 调用链 | 一次请求经过哪些活跃组件 | Agent loop → LLM → Tools Runtime → shell → LLM |

## 二、插件协作的三类接口

![插件通过三类接口协作](/articles/deepseek-harness-architecture-evaluation/dsh-interaction-contracts.png)

Cordis 提供 Service 和 Event。dsh 在此基础上增加 Tool。三类接口解决的问题不同。

| 接口 | 调用者 | 接收者 | 适合的关系 |
|---|---|---|---|
| Service | 另一个插件 | 唯一服务提供方 | 需要返回值的直接调用 |
| Event | 发布事件的插件 | 零到多个监听器 | 通知、策略和中间件 |
| Tool | 模型 | Tools Runtime 和工具插件 | 模型发起的结构化动作 |

### 2.1 Service 接口

定义包声明服务名和方法，provider 实现它，consumer 通过 `ctx.<name>` 调用。consumer 依赖服务名，不依赖具体 provider 包。一个 Context 内重复注册同名 Service 会直接报错，避免两个实现静默争用。

### 2.2 Event 接口

发布者只知道事件名、参数和分发语义，不知道谁在监听。监听器通过 `ctx.on()` 注册；它属于 effect，插件卸载时自动注销。

| 模式 | 执行方式 | 适用场景 |
|---|---|---|
| `emit` | 同步通知所有监听器 | 无返回值广播 |
| `parallel` | 并发执行并等待全部结果 | 相互独立的异步任务 |
| `serial` | 依次执行，首个有效结果结束 | 异步查询或策略裁决 |
| `bail` | `serial` 的同步形式 | 同步查询或短路 |
| `waterfall` | 监听器包装、修改或短路下一层 | 请求改写、guard 和中间件 |

`waterfall` 的关键是 `next()`。监听器调用 `next()` 才会继续后续链路；不调用就会短路。选择错误的模式会改变执行顺序和失败语义，所以 Event 契约不只有参数类型，还必须说明分发模式。

### 2.3 Tool 接口

插件用 `defineTool` 注册名称、描述、输入 Schema、输出 Schema 和 handler。模型只看到公开 Schema。调用进入 Tools Runtime 后，依次经过 `tools/pre-execute`、审批与 guard、`tools/execute`、handler、`tools/post-execute` 和结果固化。[Tools Runtime](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/core/tools/README.md)

### 2.4 接口契约的保障机制

TypeScript 接口只提供编译期检查，运行时会被擦除。交互由四层共同保障：

1. Definition package 固定名称、方法和类型。
2. Cordis 检查 Service 唯一性、`inject` 依赖和生命周期。
3. Tools Runtime 用 Schema 校验模型输入和输出。
4. 文档、组合测试和 snapshot 检查类型无法表达的行为语义。

代码里的 `interface` 也不一定都是“给其他插件的 API”。判断方式如下：

| 定义位置 | 主要对象 | 含义 |
|---|---|---|
| `declare module ... interface Context` | Service consumer | `ctx` 上存在什么服务 |
| `declare module ... interface Events` | 事件发布者和监听器 | 事件名、参数和返回值 |
| 插件导出的 `Config` | Profile 和部署者 | 这个插件接受什么配置 |
| `defineTool` 的 Schema | 模型和 Tools Runtime | 模型可以传什么、得到什么 |
| 普通内部 `interface` | 当前包实现 | 可能只是内部数据结构 |

只有前四类可能构成跨插件或外部契约。是否公开还要看它是否从 Definition package 导出，并在 subsystem 文档中出现。

## 三、服务提供方的配置机制

### 3.1 shell 服务的分层结构

官方 shell 链路可以完整说明插件之间怎样协作。它分为 Definition（契约）、Provider（提供方）和 Consumer（使用方）三层。

Definition 包 `@deepseek-ai/dsh-shell` 定义 `ctx.shell`：

```ts
declare module '@deepseek-ai/cordis' {
  interface Context {
    shell: ShellExecutor
  }
}

export abstract class ShellExecutor extends Service {
  constructor(ctx: Context) {
    super(ctx, 'shell')
  }
  abstract resolve(request: ShellExecRequest): ShellExecSpec
  abstract run(spec: ShellExecSpec): Promise<ShellRunResult>
}
```

Provider 实现这项服务。默认基础 Bundle 在非 Windows 环境挂载 `@deepseek-ai/dsh-bash-sandbox`；`@deepseek-ai/dsh-bash-local` 是另一种实现。两者最终都注册名为 `shell` 的 Service。

Consumer `@deepseek-ai/dsh-tool-bash` 不导入具体 provider。它只导入 Definition 包中的类型，并声明服务依赖：

```ts
export const inject = ['tools', 'shell', 'systemPrompt', 'shellEnv']

ctx.tools.register(defineTool({
  name: 'bash',
  execute: async (args) => {
    const spec = ctx.shell.resolve(args)
    return ctx.shell.run(spec)
  },
}))
```

默认 Profile 的关键配置是：

```yaml
- id: bash-sandbox
  name: '@deepseek-ai/dsh-bash-sandbox'

- id: tool-bash
  name: '@deepseek-ai/dsh-tool-bash'
```

这条链路可以读成一句话：Profile 选择 provider，provider 注册 `shell`，Cordis 让 consumer 等待 `shell`，consumer 只调用 `ctx.shell`。因此它没有硬编码 `dsh-bash-local` 或 `dsh-bash-sandbox`。

### 3.2 服务提供方的追查方法

用户可以查看实际挂载结果，但目前没有一条命令直接输出完整的 `Service → Provider → 配置来源` 映射：

1. `dsh --profile web --dump-default-config` 查看 Profile 默认配置。
2. `dsh --profile web --patch ./extra.yml --dump-config` 查看叠加 patch 后的有效配置和来源注释。
3. 运行时 plugin inventory 查看模块名、启用状态和 Fiber phase。
4. 对照 Definition 或 subsystem 文档，确认该模块注册了哪项 Service。

`dump-config` 解决“配置选择了什么”，inventory 解决“当前启动了什么”。inventory 不保留完整配置来源，也不直接反推 Service provider。这是当前排障能力的明确缺口。[Plugin inventory](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/host/plugin-inventory/README.md)

## 四、自定义插件的接入流程

### 4.1 扩展类型与接入点

开发新插件应先确定自己使用哪类扩展接口，再查对应的 Definition 和生成文档，无需遍历所有实现包。

| 目标 | 首选接入点 |
|---|---|
| 替换一项核心能力 | 实现对应 Service Definition |
| 监听或改变现有流程 | 订阅 Event 或 waterfall |
| 增加模型可调用动作 | 注册 Tool |
| 组合已有能力 | 编写 Profile 或 patch |
| 接入外部工具服务器 | 使用 MCP client |
| 从外部控制 Agent | 使用 ACP 或 SDK |

仓库提供三类索引：`cordis-surface` 文档列出 Service；`event-producer-consumer` 列出事件、分发模式、发布者和监听器；`tool-catalog` 列出模型可见 Tool Schema。高级 Cordis 组合还提供 `cordis_inspect_list/query`，可从当前仓库和运行时服务存储中查询 Service、Event、Tool 和 Slot。它们比遍历每个插件 README 更适合作为入口，但仍需要阅读目标 Definition 的语义和测试。

### 4.2 自定义插件开发流程

一个正常的自定义插件流程是：

1. 选择扩展接口。
   - 直接调用使用 Service。
   - 广播或中间件使用 Event。
   - 模型动作使用 Tool。
2. 导入 Definition 包，只依赖公开类型和服务名。
3. 声明运行约束。
   - 硬依赖写入 `inject`。
   - 插件配置定义运行时 Schema。
   - 监听器、工具和资源注册为 effect。
4. 用 patch 挂载插件。
   - 用 `--dump-config` 检查有效配置。
   - 用 inventory 确认 Fiber 已进入 `ACTIVE`。
5. 补齐工程测试。
   - 增加单元测试和一次真实组合测试。
   - 影响模型或用户的行为增加 keyless snapshot。
6. 固定兼容提交，再发布插件包。

动态 `cordis_define/run` 适合在当前进程里试验，但定义只存在于内存。进程重启后会消失，也不会生成插件包、安装依赖或写入 Profile。正式接入仍要落到插件包、配置和测试。

### 4.3 外部协议与进程边界

外部边界与进程内插件也应分开理解：Cordis 是进程内组合机制；Web 使用 HTTP 与 WebSocket；ACP 使用基于 stdio 的 newline-delimited JSON-RPC；SDK 使用项目自己的 line JSON-RPC 2.0；MCP 把外部工具注册进 Tools Runtime。MCP 当前主要桥接 Tool，Cordis 插件仍由进程内模块接口管理。[ACP](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/acp/acp/README.md) [SDK 协议](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/sdk/protocol/README.md) [MCP client](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/mcp/mcp-client/README.md)

## 五、插件变更与重启机制

### 5.1 配置变更

Profile 和 Harness home 的 `cordis.patch.yml` 会被监听。有效配置变化会事务式重算，相关 Fiber 和 effect 随之卸载或重建，通常不需要重启整个 dsh 进程。

### 5.2 代码变更

代码变更只有在挂载 `@deepseek-ai/cordis-plugin-hmr` 并覆盖目标路径时才会热替换。Web 客户端插件还需要 `pnpm run dev:web` 重建前端 bundle。生产环境升级 npm 包时，不能假设 HMR 一定覆盖新文件；除非部署明确启用了完整 watcher 链，否则应重启进程。

HMR 的行为是卸载旧 Fiber、加载新模块，再重建依赖方。前端新模块加载失败时，Fiber 会进入 `FAILED`，不会自动回滚到旧代码。因此关键插件更新仍需保留固定版本、健康检查和回退方案。[组合与 HMR](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/cordis-tutorial/06-composition-and-hmr.zh.md)

## 六、仓库质量保障流程

![代码改动先经过仓库质量链](/articles/deepseek-harness-architecture-evaluation/dsh-contribution-flow.png)

仓库同时约束单包行为、真实组合、跨平台兼容和发布产物。

### 6.1 代码与文档的同步要求

代码按责任分区：`packages/*/*` 保存官方 Service、provider 和 consumer；`apps/*` 保存 CLI 与 Web 产品入口；`docs/` 和 `.agents/notes/` 保存公开契约与设计记录；`scripts/` 和 `.github/workflows/` 保存生成器、门禁和 CI。修改一项能力时，应从所属 package 开始，再同步它的 README、JSDoc、测试和必要的 Agent Note。[仓库布局](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/AGENTS.md)

### 6.2 本地验证的三个层级

1. 验证单包行为。
   - 运行 `pnpm run test`。
   - 按改动运行 `typecheck`、`lint`、`doc-sync` 和 `build`。
2. 验证真实组合。
   - 产品可见插件必须经过 Loader、应用或进程入口。
   - 只手工构造 `ctx.plugin` 不能替代组合测试。
3. 验证模型和真实服务边界。
   - 模型、协议或用户行为增加 `test:snapshot`。
   - 真实 provider 才选择带密钥的 `test:e2e`。

### 6.3 提交、合并与发布流程

1. Git hooks 先检查翻译、lint、空白、生成文件和 typecheck。
2. 内部 PR 拆分独立改动；非 Draft PR 关联同仓 Issue，并填写变更、验证和标签。
3. CI 覆盖 static、逐文件 100% coverage、snapshot、Node 兼容、Python、Wine 和 Windows。
4. `all checks passed` 聚合通过后，改动才能进入 master 工作流。
5. 发布先构建和打包全部 DSH 成员，再验证安装产物；tag 和 environment 由人工触发。

逐文件 100% coverage 只是一项仓库门槛。行为质量还依赖真实组合测试和 keyless snapshot。真实 API e2e 使用密钥，只在可信事件运行；fork 和 Dependabot 会跳过，避免泄露 secret。[开发指南](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/development.md)

公开工作流只能证明 CI 已配置。required checks、reviewer 数量、merge method 和发布 environment 审批名单没有从公开仓库设置中取得，本文将它们标为未知。

本轮按要求没有重新运行 Harness 本地测试。上表描述冻结仓库定义的开发流程，不代表本轮测试已经通过。

## 七、外部插件的发布方式

当前 [`CONTRIBUTING.md`](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/CONTRIBUTING.md) 明确说明项目仍处早期，暂不接受外部 Pull Request。官方建议外部开发者创建独立插件仓库，并使用 GitHub topic `dsh-plugin` 供用户发现。

现在可以让 Codex 在 fork 或独立仓库中完成插件、测试、文档和补丁，也可以准备一份可供维护者参考的变更记录。创建本地分支和提交需要用户明确授权；推送 fork 或创建 PR 还需要已登录的 GitHub 身份、目标仓库权限和外部写入授权。官方仓库当前不接受外部 PR，具备工具权限也不能绕过这项政策。

如果目标是扩展 dsh，当前可执行路径是：基于公开 Definition 开发独立插件，锁定兼容提交，完成组合测试，发布自己的包和 `dsh-plugin` 仓库。只有官方重新开放外部 PR 后，主仓贡献链才成立。

## 八、公开评测与证据边界

### 8.1 公开 Agent 任务评测

本文把“公开 Agent 评测”限定为同时给出任务或数据集、指标与分母、已测量结果。在冻结范围内，没有发现 SWE-bench、Terminal-Bench、AgentBench 或 GAIA 等 Agent 任务的公开成绩。

[`BENCHMARK.md`](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/BENCHMARK.md) 只说明怎样用 Python SDK 启动 minimal agent，并为独立任务设置 workspace 和 session ID。它提供评测接入口，没有给出评测结果。

### 8.2 工程评测资产

仓库包含工程评测资产：

| 资产 | 指标 | 当前证据 |
|---|---|---|
| Web 长历史 runner | 侧边栏、长对话、轨迹和 soak 的 wall time、p95 等 | 有脚本，未发现正式结果 |
| reasoning chunk 压力 | 10 万 chunk；主线程和交互延迟门槛 250 ms | 有断言，未发现官方汇总 |
| CI runner benchmark | 不同平台和 core 数下的检查耗时 | 用于 CI 容量，与 Agent 能力评测无关 |
| 单元、snapshot、e2e | 类型、行为、组合和真实 API 链路 | 证明工程链路，不证明任务成功率 |

### 8.3 评测缺口

缺失的评测至少包括：

- 固定模型和预算下的任务成功率。
- 工具调用正确率。
- 权限拒绝与恢复率。
- 断点恢复正确率。
- 长会话质量。
- 插件组合兼容性。
- 相同任务上的对照 Harness。

没有这些结果，就不能从高覆盖率推导出 Agent 效果。

## 九、采用建议

### 9.1 当前采用判断

| 阶段 | 当前判断 | 条件 |
|---|---|---|
| 架构观察 | 通过 | 源码和文档足以解释主要机制 |
| 受限试点 | 有条件通过 | 固定提交、隔离 workspace、低风险任务、明确权限和回退 |
| 组织级采用 | 不通过 | 缺少稳定发布、迁移承诺、安全审查和目标任务评测 |

DeepSeek Harness 当前标注 Developer Preview，会主动发生兼容性变化；会话格式仍为 v0；调研日未见正式 GitHub Release。这些事实不否定架构价值，但会放大插件兼容、会话迁移和运维成本。

### 9.2 受限试点要求

合理的下一步是选择一个低风险任务做隔离试点：

1. 固定版本。
2. 保留 `workspace-write + ask`。
3. 逐项确认 shell、文件、Web 和外部服务是否进入审批策略。
4. 保存有效配置和 plugin inventory。
5. 把升级、会话导出和插件回退都当作可能失败的步骤。

只有在固定任务集上取得可复现结果，并补齐安全、发布和迁移责任后，才应重新讨论默认采用。

## 十、调研范围与证据

- 目标仓库：[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)、[Tools](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/core/tools/README.md)、[Persistence](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/packages/session/session-persistence/README.md)、[Development](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/docs/development.md)、[Contributing](https://github.com/deepseek-ai/deepseek-harness/blob/47f943859bef60e4160492346772ded9b24f765a/CONTRIBUTING.md)
- 已核验：冻结源码、官方文档、仓库测试与 CI 配置、调研日远端 `HEAD`
- 未核验：真实模型端到端效果、生产负载、在线保护设置、跨版本迁移和第三方插件质量