DeepSeek Harness 架构：插件、Profile 与事件

DeepSeek Harness 是构建在 Cordis 之上的插件化编码 Agent 运行时。理解它时，不要把 dsh 看成一个巨大的单体程序，而应把它看作一棵插件树：Profile 选择一套具名组合，Bundle 挂载成组能力，核心 Service 提供稳定接口，事件则连接 Agent Loop、会话持久化和实时控制。

本文根据 DeepSeek Harness 官方中文架构文档 重新组织，重点回答“配置从哪里生效”“功能应该放在哪一层”“事件是否需要持久化”等实际问题。

Cordis 插件树是什么

Cordis 是 Harness 的底层插件框架。组件以插件形式挂载，并应当注册可撤销的副作用：插件被卸载时，它创建的 Service、监听器和资源也能被可靠清理。

编码 Agent 运行时往往需要同时组合模型服务商、工具、会话存储、Web 界面与策略层。插件树让每项职责拥有明确的注册位置和生命周期。排查问题时，可以先问两个问题：这个行为由哪个插件注册？该插件挂载在哪个上下文？通常比从单一入口文件向下盲目追踪更高效。

Profile、Bundle 与配置覆盖顺序

Profile 是存放在 Harness Home 中的一套具名组合，用来决定运行时安装哪些 Bundle 和 Patch。Bundle 则封装一组相关的配置与挂载逻辑，官方架构中列出的组合包括 dsh-base、dsh-web-app 和 dsh-headless。

配置按照以下顺序叠加：

1. Profile 中的 Bundle；
2. Profile Patch；
3. Harness Home Patch；
4. CLI Overlay。

越靠后的层可以细化前面的配置。与其猜测最终谁覆盖了谁，不如直接查看解析结果：

dsh --profile web --dump-config

Profile 适合定义 Web、Headless 等完整运行模式；本地 Patch 适合环境差异。不要为了改一个值复制整套 Bundle，否则后续很难继承上游更新。

Harness 核心服务有哪些

官方架构列出了挂在 Cordis Context 上的关键能力，包括 sessions、system prompt、tools、agents、agent loop、scope 与 LLM 等。它们是协作接口，而不是把实现永久锁死。

例如，工具包可以依赖 Tool Service，却不必知道当前使用 Web UI 还是终端；Agent Loop 可以调用 LLM 能力，却不负责保存服务商密钥；Session 负责持久化事件，也不需要接管界面的瞬时加载状态。这样的职责划分能控制包之间的依赖方向。

想从使用角度查看能力，可继续阅读 DeepSeek Harness 工具目录。

持久化事件与实时 Agent 事件

DeepSeek Harness 的事件不属于同一个用途：

• Session Event 是追加进会话日志的持久事实；
• agent/* Event 表示运行期间的实时控制、状态和拦截；
• 能力接缝事件负责让 Provider 与 Consumer 在不直接依赖的情况下协作。

如果某个“正在流式输出”的状态只需要在当前界面显示，就不应仅因为 UI 要用而写入会话历史。反过来，需要在重启后通过回放恢复的事实，也不能只存在于实时事件中。Agent 生命周期详解 会把这些事件放回完整执行流程中。

Turn、Step 与追加式会话日志

一个 Step 包含一次模型请求及其相关工具工作；一个 Turn 由输入触发，可以包含零个或多个 Step。模型请求工具后，工具结果可能促使它再次请求模型，因此“一条用户消息”并不等于“一次模型调用”。

Session 采用追加式事件日志：新事实追加到历史，而不是改写过去。这有利于回放和审计，但开发者必须判断什么值得持久化。用户消息和最终工具结果可能属于会话事实，“当前正在生成第几个 Token”则通常只是实时状态。

能力接缝（Capability Seam）

能力接缝把三类角色分开：

1. Service Definition 声明契约；
2. 一个或多个 Provider 提供实现；
3. Consumer 只依赖能力，不直接导入具体 Provider。

Shell 执行、LLM 访问等可替换能力适合这种设计：本地 Provider、远程 Provider 与测试 Provider 可以实现同一契约，调用方保持稳定。但并非所有函数都需要抽象成接缝；只有当跨包边界或替换 Provider 是真实需求时，它带来的生命周期与错误处理成本才值得承担。

新功能应该放在哪一层

可以用下面的判断路径：

• 可复用、可挂载的行为放入插件；
• 一组相互配合的插件与配置放入 Bundle；
• 面向用户的一套运行模式由 Profile 组合；
• 只有回放必须保留的事实才写入 Session Event；
• 运行中的状态与干预使用 agent/* Event；
• 明确需要替换 Provider 时才引入能力接缝。

如果功能跨越 Host 与 Client，还应阅读 API Gateway 远程调用指南；如果功能改变模型请求或工具调度，应先沿 Agent 生命周期 完整追踪。

官方原文

本文依据 DeepSeek Harness 官方架构文档（中文） 独立编写，核对日期为 2026-08-20。具体包名、Service 和事件实现请以官方仓库当前版本为准。