核心摘要

DeepSeek Harness（dsh）是 DeepSeek AI 开源的 Agent Harness，不是模型，也不是固定的 Coding Agent。它基于 Cordis 插件系统，将模型适配器、工具、会话、沙箱、循环、调度和界面组合为可替换能力。真正重要的工程结论不是“一切都应该插件化”，而是每个可替换能力都必须有明确接口、生命周期、策略边界与测试契约。

目录

DeepSeek Harness 是什么

DeepSeek Harness 是一个面向工具使用型 Agent 的运行时。官方将其描述为由 Cordis 驱动的开源 Agent Harness：各种能力均以插件形式存在，Agent 由模型和 Harness 共同构成。模型适配器负责生成提案；Harness 则提供模型理解环境、请求工具、接收结果并持续执行任务所需的运行边界。

这个边界不能被忽略。模型提供方、工具 Schema 和聊天界面都不能单独提供持久化执行、权限控制或故障恢复。这些职责属于 Agent Harness；即使框架提供了相应扩展点，最终的安全与业务责任仍在应用团队。

DeepSeek 当前将 dsh 标为开发者预览，并明确说明未来会有破坏性兼容变更。因此应以已锁定的源码提交或发布包及其官方文档作为兼容契约，不能从演示页面或内部包名推断稳定 API。

Cordis 的组合模型

Cordis 是 DeepSeek Harness 底层的框架。一个 Cordis 插件可向共享上下文注册服务、类型化事件和可逆副作用。消费者依赖 ctx.tools、ctx.sessions 这类能力接口，而不是直接导入某一个具体工具注册表或持久化实现。

flowchart LR P["Profile"] --> B["Bundle"] B --> C["Cordis 插件树"] C --> M["模型适配器"] C --> T["工具注册表"] C --> S["会话日志"] C --> X["沙箱与审批"] C --> U["Web 或协议界面"]

这套架构包含三类关联但不同的扩展机制：

机制 职责 应先回答的问题
服务 在 ctx 上提供具名能力 这个能力需要什么接口和责任边界？
类型化事件 观察或拦截生命周期接缝 这是观测、策略决策还是持久化事实？
可逆副作用 注册监听器、工具、Provider 或资源，并在卸载时清理 插件卸载时，哪些资源必须关闭或撤销？

这不只是依赖注入。工具插件可以注册 Schema，策略插件可以拦截执行，观测插件可以消费结果事件，而不必修改 Agent Loop。但可组合不等于可信：能够读取文件、修改系统提示词或决定工具权限的插件，本身就是 Agent 供应链的一部分，应被审查、锁定版本并限制权限。

Profile、Bundle 与 Patch

一个运行中的 dsh 会被组装为有顺序的插件树。官方架构文档区分：

  • Profile：Harness Home 中的具名组合，列出 Bundle、安装的外部插件和用户 Patch。
  • Bundle：可分发的 Cordis 配置行及其挂载代码。
  • Patch：替换或插入配置行的覆盖层。

启动顺序具有语义：先按 Profile 中的顺序应用 Bundle，再应用 Profile 和 Home 的 Patch，最后应用命令行 Patch。后面的层可以替换前面层加入的配置行。不要猜测实际启用了哪个 Provider 或 Sandbox，先检查真实启动树：

sh 
dsh --profile web --dump-config

该输出可用于人工审查，但不是完整的生产审批记录。部署时还应锁定 deepseek-harness 版本、插件版本、模型路由、凭证来源、工作区挂载、沙箱后端、出网策略和审批策略。

一次 Agent Turn 如何流过运行时

默认 Loop 中，一次 Turn 可以包含零到多次 Step。一次 Step 对应一次模型请求及其请求的工具执行。运行时组装 Prompt Section 和 Tool Schema，流式接收模型响应，让工具经过执行管线，再判断是否还需要下一次 Step。

sequenceDiagram participant U as 用户或事件源 participant A as Agent Loop participant L as 模型适配器 participant T as 工具管线 participant S as 会话日志 U->>A: 入队消息 A->>S: 追加 Turn 与用户事件 A->>L: 组装后的提示词与 Schema L->>S: 追加助手流与消息 L->>T: 请求工具调用 T->>S: 追加工具结果 T-->>A: 返回结果或策略决定

官方架构将 agent/pre-step、agent/request、模型流式输出和工具执行事件视为扩展接缝。应按职责选择接缝：

  • 可以拒绝或要求审批的策略应位于真正执行之前。
  • 超时、重试和计量应包裹实际派发的完整生命周期。
  • 指标与审计应观察不可变的最终结果。
  • 新增的模型可见输入必须进入持久化会话事件模型。

这与 Agent Runtime 和应用控制平面的边界一致。运行时让策略 Hook 成为可能；应用仍需负责租户身份、资源级授权、业务不变量和事故处置。

哪些可以配置，哪些仍由应用负责

DeepSeek Harness 可以组合模型路由、工具集合、沙箱后端、会话存储和界面，但不能把宽松配置自动变成安全系统。下表区分框架能力和应用责任：

领域 Harness 可以提供 应用仍需负责
工具访问 注册表、Schema、执行 Hook 用户与租户授权、对象级策略、消费限额
沙箱 后端接缝与进程封装 工作区范围、Secret Broker、出网控制、镜像来源
会话 事件模型和可回放历史接缝 保留、脱敏、加密、删除和访问审计
模型路由 Adapter 注册和路由设置 Provider 契约、成本上限、回退策略、质量评测
插件 挂载、依赖与清理 审查、版本锁定、兼容测试和回滚

例如，模型给出格式正确的工具参数，不代表它拥有修改仓库或云资源的权限。模型提案、授权决定、外部副作用和已对账结果应保留为不同记录。通用实现原则可参阅 Agent Harness 实战 和 工具使用。

如何评估是否接入

评估 DeepSeek Harness 时，应将其视为运行时集成，而不是模型排行榜。先在受限工作区中建立最小任务集，证据充分后再扩展。

  1. 锁定制品：记录 Git Commit 或发布包版本、Node.js 版本、Profile、Bundle、Patch 和 Provider 设置。
  2. 测试能力边界：确认被禁止的路径、网络目标、Secret 和写操作，即使由模型提议也会被拒绝。
  3. 测试生命周期：挂载并卸载一个自定义插件，确认监听器、定时器和资源都被释放。
  4. 测试恢复语义：分别在只读工具和存在副作用的工具期间中断。可回放 Session 并不能证明外部系统没有提交。
  5. 单独测试升级：项目处于开发者预览阶段，每次升级 DSH 或插件都应重新运行测试集。

Agent Harness 评测指南 说明了如何将这些检查转化为回放、故障注入和发布门禁。一次成功 Demo 不能证明插件树已经适合连接高权限生产工具。

常见问题 (FAQ)

DeepSeek Harness 只能搭配 DeepSeek 模型吗？

不是。项目文档将模型适配器定义为插件接缝，Web UI 文档也说明可配置自定义 OpenAI 兼容端点。不同 Provider 的流式输出、工具调用、Token 计量和错误语义仍应针对具体 Adapter 与模型路由测试。

“一切皆插件”是否意味着可以安全替换 Agent Loop？

不意味着。插件可以扩展文档化接缝，但替换 Loop、策略或持久化能力会改变运行时契约。兼容实现必须保留生命周期、日志、取消、授权和恢复语义。

DSH Patch 可以直接改生产配置吗？

只能在审查和测试后进行。Patch 能替换配置行，因此可能改变 Provider、工具或策略。应把它当作部署代码：审查差异、锁定引用插件、在隔离环境测试，并保留回滚路径。

DeepSeek Harness 默认安全吗？

没有框架能够独自提供应用安全。DSH 提供沙箱和审批接缝，但部署仍需要最小权限、作用域凭证、出网策略、租户隔离、输入防护、审计和业务审批。

团队应该从哪里开始？

先运行官方 Web UI Quickstart，再使用 --dump-config 检查真实 Profile。先在一次性工作区写一个小插件，再连接真实仓库、凭证或生产工具。

相关资源