---
title: "DeepSeek Harness 架构解析：Cordis、Profile、Bundle 与 Session"
description: "从官方源码解释 DSH 的一切皆插件架构、Cordis 插件树、Profile 与 Bundle 配置层、Session 事件日志和工具执行流程。"
canonical: https://52dsh.com/tutorials/deepseek-harness-architecture/
authors: ["52DSH 编辑部"]
published_at: 2026-08-18
updated_at: 2026-08-18
verified_on: 2026-08-18
maintenance_status: community
verification_level: source_reviewed
risk_level: low
---

# DeepSeek Harness 架构解析：Cordis、Profile、Bundle 与 Session

从官方源码解释 DSH 的一切皆插件架构、Cordis 插件树、Profile 与 Bundle 配置层、Session 事件日志和工具执行流程。

## 架构总览

DeepSeek Harness 的核心不是一个固定功能清单，而是一棵由 Cordis 组装的插件树。模型适配器、系统提示、工具、Agent Loop、Session、持久化、沙箱和 Web UI 都以插件或可替换能力接入。官方把这一原则概括为“一切皆插件”。

## Cordis 承担什么角色

Cordis 向共享上下文贡献服务、类型化事件和可撤销副作用。插件挂载时注册能力，卸载时撤销对应注册，因此扩展 DSH 的正常方式是增加或替换插件，而不是修改一个特权内核。

可以把它理解为三层：服务定义声明能力接口；Provider 提供具体实现；Consumer 使用该能力。官方把这种可替换边界称为 capability seam。同一接口后可以替换本地、远程或其他产品的实现，而上层 Agent 继续使用相同工具契约。

## Profile 和 Bundle 有什么区别

Profile 是一套具名运行组装，存放在 `$DSH_HOME/profiles/<name>`。官方随发行版提供 `web` 与 `headless` 模板：前者加入浏览器应用，后者用于一次性运行且不启动服务器。

Bundle 是一组 Cordis 配置和挂载代码的分发格式。运行时配置按顺序叠加：

```text
Profile 声明的 Bundle
→ Profile 的 cordis.patch.yml
→ $DSH_HOME/cordis.patch.yml
→ 命令行 --patch 覆盖层
```

后应用的层优先。Patch 对目标配置项执行整项替换，而不是对内部字段做深度合并。要查看实际启动的配置树，可运行：

```bash
dsh --profile web --dump-config
```

因此，“安装一个 npm 包”和“让它进入 DSH 配置树”不是同一件事。插件若声明 Bundle，插件管理器会把它加入 Profile 的 Bundle 栈；普通依赖则只作为依赖保留。

## 一次 Agent 任务如何流动

一次 turn 可以包含多个 step；一个 step 是一次模型请求加上它触发的工具执行。简化的数据流是：

```text
用户输入
→ 组装提示词与工具 schema
→ 模型请求
→ assistant 输出或 tool/call
→ 工具权限检查与执行
→ tool/result 写入 Session
→ 模型继续处理
→ turn 结束
```

工具执行前后都有事件扩展点，插件可以应用策略、改写请求或记录结果。这也是 DSH 能把权限、审批、遥测和外部工具组合进同一条执行链的基础。

## Session 为什么重要

Session 是类型化 `SessionEvent` 组成的仅追加日志，也是 Agent 交互历史的唯一真源。模型消息历史不是另外保存的一份数据，而是从日志派生；回放、恢复、fork、transcript 和持久化也从同一事件流派生。

一个关键原则是“模型可见即已记录”：进入模型请求的上下文必须能够由事件日志重建。这样做提高了回放和审计的一致性，但不等于所有外部副作用都能自动撤销；文件、命令和网络操作仍要依赖对应工具和权限策略。

## MCP、Skills 和子 Agent 在哪里接入

MCP client 会把外部服务器发现的工具注册到工具服务；Skills 主要向 Agent 注入可复用的任务说明和资源；子 Agent Provider 则通过统一接口把工作委派给另一个 Agent 或产品。它们都是扩展点，但信任边界不同。

官方 CLI 虽随附 MCP client 包，却默认不运行任何 MCP server；配置的服务器命令在 Agent 沙箱之外作为受信任可执行代码运行。概念边界可继续阅读[Skills 与 MCP 的区别](/plugins/skills-mcp-boundary/)，实际插件管理见[DSH 插件、Profile 与 Bundle](/plugins/dsh-plugin-profile-guide/)。

## 这套架构带来的维护要求

DSH 当前处于 Developer Preview。配置层和插件接口可能发生破坏性变化，因此教程需要同时记录 DSH 版本、Profile、Bundle、Patch、Provider 和验证日期。只描述“装了某插件就能用”而不说明它如何进入配置树，无法形成可复现结果。

## 原始来源

- https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/session.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/reference/README.zh.md