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

社区整理已复核原始来源

架构总览

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

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

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

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

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

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

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

dsh --profile web --dump-config

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

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

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

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

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

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

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

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

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

本文根据以下原始资料整理。版本变化后，请以官方资料和页面标注的验证日期为准。