DeepSeek Harness 源码深度解析（上）：从 API 调用到 Agent 运行时的核心机制

调用大语言模型的 API 看似简单——几行代码就能获得一段回复。但当任务升级为"让 AI 自主完成复杂工作"时，比如读取文件、定位 bug、执行测试、循环修复，很多人会发现无从下手。这并非 API 调用本身有难度，而是缺少一层关键的中间能力——Harness（驾驭框架）。DeepSeek 开源的大模型工具链 DeepSeek Harness（简称 dsh）正是这一层能力的工业级实现，将原本需要数百行工程代码才能搭建的 Agent 基础设施，做成了可复用的成熟框架。

概述

Harness 的本质：模型的操作系统

理解 dsh 的第一步，是摒弃"它是模型封装"的误解。在 dsh 的架构中，Model（模型）、Harness（框架）、Agent（智能体）是三层独立结构：模型负责"思考"——接收文字、返回文字；框架负责"驾驭"——提供工具、循环、记忆、权限和日志等运行时能力；智能体则是两者结合后的"能干活的东西"。dsh 的设计哲学围绕两条核心暗线展开：第一是可追溯性，即"模型看到的一切必须被记录"，这是框架的运行时断言；第二是可替换性，即"没有特权核心"，主循环、模型、UI 统统可插拔替换。这两条暗线贯穿整个 20 万行源码，是理解所有设计的钥匙。

会话日志：事件溯源架构

传统 Agent 实现的会话管理通常采用简单的消息列表：messages = [{'role': 'user', 'content': '...'}, ...]。然而这种方法存在致命缺陷——进程崩溃后无法恢复执行状态，无法回答"模型在某一步究竟看到了什么"，更无法将一次会话"分叉"或精确重放。dsh 采用了事件溯源（Event Sourcing）架构：所有交互都作为不可变事件追加到日志末尾，已有的历史事件永远不被修改，状态仅是从日志重放计算出的投影。 这一设计的核心不变量是"模型看到的一切必被记录"。抵达模型的请求——包括系统提示词、历史消息、工具 schema、注入的上下文——都必须能从会话日志重建。这确保了日志成为唯一事实来源，所有高级能力都是日志的派生品：deriveMessages() 生成模型历史、Inbox 构造时重放构建待处理队列、持久化后端支持磁盘存储、UI 渲染基于日志数据、fork/resume/replay 则从日志派生新会话。

轮次与步骤：状态机驱动的执行模型

dsh 的 Agent 执行模型围绕 Turn（轮次）和 Step（步骤）展开。一次 Step 包含一次模型请求及其引发的工具调用；一个 Turn 则是一个任务的完整过程，可能包含零个或多个 Step。当 Step 内无工具调用或无更多待处理的工具结果时，当前 Turn 即告完成。 框架使用显式的 Phase 状态机管理并发场景：idle 状态表示空闲、maintenance 用于处理维护任务、running 表示正在执行。这种设计解决了常见难题——运行中用户发送新消息时，wakeRequested 信号会锁存请求，待当前活动结束后再唤醒；插件需要执行维护任务时，maintenance 模式直接拒绝非 idle 的新驱动；取消操作则通过 AbortController 信号链协作式传播。 工具调度的设计同样精妙。工具调用按并发模式分组：声明为并发安全的工具（如读文件）可以并行执行，不安全的工具（如执行 shell 命令）则强制串行。结果严格按模型原始顺序提交——即使调用2先完成，也必须等待调用1完成后才能提交。中止时，未开始执行的调用会被标记为"已跳过"，而非抹去事实，

如有侵权，请联系删除。