DeepSeek Harness

August 13, 2026 · View on GitHub

DeepSeek Harness 技术架构报告 —— 围绕 DeepSeek 模型构建的智能体评测 / 编排框架（Agent Harness）。

本仓库包含 DeepSeek Harness 的整体架构图、单轮运行流程图以及完整的技术架构报告（PDF）。

整体架构

目录

项目简介

DeepSeek Harness 是一套围绕 DeepSeek 大语言模型构建的智能体（Agent）编排与评测框架。它的核心目标是：

  • 把 DeepSeek 模型包装成一个可调用工具、可多轮循环、可观测、可评测的完整 Agent；
  • 提供统一的模型适配层，屏蔽底层 API 差异，使上层逻辑聚焦于编排与评测；
  • 通过**结构化的单轮循环（Turn Loop）**驱动“推理 → 工具调用 → 结果回填 → 再推理”的闭环；
  • 内建权限控制、沙箱执行与完整日志，支撑安全、可复现的评测。

核心特性

能力说明
🔁 Agent 主循环标准化的“推理—工具—反馈”循环，支持多轮迭代直至任务完成
🧰 工具系统工具注册、声明式描述、参数校验与受控执行
🧩 模型适配层统一封装 DeepSeek API，解耦模型与上层编排
📝 上下文管理会话状态与上下文窗口的组装、压缩与维护
🛡️ 安全与权限工具调用鉴权、沙箱隔离、敏感操作拦截
📊 可观测 / 可评测全链路日志、指标采集与评测结果落盘
🔌 多端接入CLI / API / Web 多种接入方式

系统架构

整体采用分层架构，自上而下分为接入层、编排核心层、能力层与基础设施层：

整体架构

  • 接入层（Interface）：CLI、HTTP API、Web UI 等多种入口，统一转换为标准请求。
  • 编排核心层（Harness Core）：系统的大脑，包含 Agent 主循环、任务编排与会话调度。
  • 能力层（Capability）：
    • 模型适配 —— DeepSeek 模型调用、Prompt 与参数管理；
    • 工具系统 —— 工具注册表、声明式描述、执行调度；
    • 上下文/记忆 —— 会话与上下文窗口维护。
  • 基础设施层（Infrastructure）：权限与安全（鉴权 / 沙箱）、存储（日志 / 评测结果）、可观测性（指标 / 追踪）。

各层之间通过明确的接口解耦，便于独立替换与演进。

单轮运行流程（Turn Flow）

Agent 的运行由一个个“轮次（Turn）”驱动。单轮流程如下图所示：

单轮运行流程

一个完整的 Turn 包含以下步骤：

  1. 用户输入 / 任务接入 —— 接收用户指令或上一轮的延续请求。
  2. 上下文组装 —— 汇总会话历史、系统指令、工具描述，构建模型输入。
  3. 模型推理（DeepSeek） —— 模型输出回复文本和 / 或工具调用请求。
  4. 工具调用决策 —— 解析模型输出，判断是否需要调用工具，并做权限校验。
  5. 工具执行 —— 在受控环境（沙箱）中执行工具，获取结果。
  6. 结果回填 —— 将工具执行结果作为新的上下文，进入下一轮。
  7. 终止判断 —— 任务完成或达到停止条件则输出最终结果，否则回到步骤 2。

该闭环是 Harness 的运行核心，也是评测可复现性的基础。

核心模块说明

  • Agent 主循环（Main Loop）：驱动整个“推理—行动—观察”的迭代过程，控制轮次、超时与停止条件。
  • 模型适配层（Model Adapter）：封装 DeepSeek 的请求 / 响应、流式输出、重试与降级，向上提供统一接口。
  • 工具系统（Tool System）：基于声明式描述（名称 / 参数 schema / 用途）注册工具，统一调度执行并回收结果。
  • 上下文管理（Context / Memory）：负责历史消息维护、上下文窗口裁剪与压缩，避免超出模型长度限制。
  • 安全与权限（Security）：对工具调用进行鉴权与沙箱隔离，拦截高风险操作。
  • 可观测与评测（Observability）：记录每一轮的输入 / 输出 / 工具调用，输出结构化日志与评测指标。

仓库文件

文件说明
deepseek-harness-architecture.png / .drawio整体分层架构图（可编辑源文件 + 导出图）
deepseek-harness-turn-flow.png / .drawio单轮运行流程图（可编辑源文件 + 导出图）
deepseek-harness-technical-report.pdf完整技术架构报告（21 页）
README.md本说明文档

.drawio 文件可用 draw.io / diagrams.net 打开编辑。

技术报告

完整的架构设计、模块拆解与实现细节请参阅：

📄 deepseek-harness-technical-report.pdf

报告涵盖：架构总览、Agent 主循环设计、工具系统、模型适配层、上下文管理、安全与权限、可观测性与评测等。