DeepSeek Harness 解决的核心问题是多轮模型调用、工具执行与会话状态之间的协调输入何时进入请求工具结果如何写回历史请求失败后从哪里重试上下文压缩后保留哪些信息以及任务中断后能够恢复到什么状态。围绕这些问题框架将运行过程拆分为插件装配、回合驱动、会话日志、工具管道和异常处理。分析其架构的关键在于各部分的状态边界以及这些边界提供的保证与限制。本篇文章限定在提交 477b4f42052026 年 9 月 25 日对应的实现。1. 插件装配插件是 DeepSeek Harness 的核心能力插件的配置决定 Agent 的运行能力。DeepSeek Harness 通过 Cordis 插件组织运行能力。Cordis 提供 Context、Service、Plugin 和 Event 等抽象插件通过依赖注入与事件系统协作并由框架管理生命周期。LLM 服务、Session、Agent、AgentLoop 和工具注册表等基础组件由 bundle 统一挂载。启动时dsh以 profile 为入口加载配置按 id 定位配置行并替换对应的整段 config。这里的配置语义是整段替换而非字段级合并。覆盖某个组件的配置时原配置中未被保留的字段也可能随之消失。插件装配因此直接影响 Agent 的实际行为模型服务是否可用、哪些工具被注册、哪些事件处理器参与执行都取决于最终加载的插件与配置。仓库包含某项能力并不等于当前运行实例已经启用该能力。这种设计便于替换组件和组合能力但也让执行逻辑分布在多个插件中。分析一次请求的行为需要同时查看核心循环、插件注册关系和最终生效的配置。2. 核心循环Agent 循环是 Agent 的核心逻辑其主要区分回合、步骤与请求重试。从实际的工作逻辑上来看agent-loop负责驱动模型与工具之间的循环。其主要执行路径包括准备模型请求解析配置并选择适配器。投影系统提示词提交本次需要进入历史的用户输入。从会话构造请求接收并累积流式响应。将 assistant 消息写入 Session。执行模型提出的工具调用并将结果交给后续模型请求。在没有工具调用或满足结束条件时结束本轮执行。理解这条路径需要分三个层次turn由用户输入驱动的回合。step回合内部的执行边界。请求尝试一次实际发往模型的调用失败后可以在同一个 step 内重试。因此step 不能简单等同于一次网络请求。重试可能产生多次请求尝试但不应重复消费输入或重复提交用户消息。Agent 维护next-turn和next-step两个队列分别承接下一回合与下一步的输入。队列修改以agent/inbox/spliced事件写入 Session待处理输入可以从日志投影恢复。这一设计区分了「系统已经收到消息」和「模型已经消费消息」。执行过程中到达的补充要求需要在相应边界进入后续请求。它不能自动改变已经发出的模型请求也不能撤销已经发生的工具副作用。输入排队与执行取消因此属于不同机制。将队列变化写入日志还能避免恢复时只找回聊天记录却丢失尚未处理的输入。3. SessionSession 机制实现了运行记录与模型历史分离。Session 被设计为只追加的事件日志事件通过递增序列号确定顺序以type区分类型以body保存内容。日志不仅记录用户与 assistant 消息也记录请求失败、输入队列变化、工具执行和压缩过程等运行事实。但日志中存在的事件不一定进入模型上下文。真正发送给模型的messages由 Session 的 surface 通过deriveMessages()重建再冻结为不可变请求。只有进入 surface 的消息事件参与历史投影assistant/attempt等运行记录不会自动成为模型消息。这一分离有两个作用保留排障信息请求失败与恢复过程可以完整记录而不必全部占用上下文窗口。允许调整可见历史压缩或替换模型上下文时仍能保留原始事件。Session 的 append 还会检查 JSON 可序列化性、事件规则及 surface 替换的合法性以减少无法持久化或无法正确投影的数据进入日志。日志恢复不等于外部动作回滚只追加日志为审计与状态重建提供了基础但不能单独保证任意中断点都能无损恢复。例如工具已经修改文件但结果尚未写入 Session 时进程退出外部环境与日志之间就可能出现状态差异。恢复日志可以还原已提交的记录却不能仅凭「缺少结果」判断工具没有执行。因此恢复能力需要区分已提交事件及其投影的恢复外部副作用的确认与处理。后者还依赖工具的幂等性、状态检查能力或额外的事务机制不能仅由 Session 的追加式设计推导出来。4. 工具管道工具管道实现了从模型意图到受控执行。工具注册表只向模型暴露 name、description、parameters 等白名单字段。执行函数、超时设置和并发属性保留在运行时。这将模型侧的工具描述与运行时的执行控制分开模型负责提出调用框架负责判断调用是否可执行以及如何执行。一次工具调用依次经过解析模型生成的参数。查找当前 Agent 可见的工具。通过tools/pre-execute进行执行前检查允许或拒绝调用。进入tools/execute包装链。通过tools/post-execute处理结果。将结果写回 Session供后续模型请求使用。权限检查、执行包装和结果处理因而拥有独立的介入位置不必全部写进工具函数。并发执行与顺序提交分离同一条 assistant 消息可能提出多个工具调用。调度器通过工具的isConcurrencySafe属性分类明确返回true的调用进入并行池。其他调用作为独占屏障处理。并发是显式声明的能力未声明安全的工具不会默认并行执行。工具本体可以并发但准备、后处理、tool/result写入及附加 context 入队按模型调用顺序提交。这样可以避免工具完成时间的随机性直接改变会话中的结果顺序。代价是可能出现等待后面的工具即使先完成也需要等待前面的调用提交。并发能够缩短部分执行时间却不保证结果可以立即进入历史提前完成的结果还可能需要暂存。此外提交顺序稳定不等于外部副作用确定。并发工具是否真正安全仍取决于它们是否访问共享状态、是否存在执行依赖以及并发声明是否准确。5. 安全隔离DSH 在实现上让审批与执行限制分别生效以实现安全隔离。Harness 的沙箱模式包括type SandboxMode | read-only | workspace-write | danger-full-access策略涉及文件路径权限、命令执行限制和权限提升。工具可以通过justification与sandbox_permissions请求提升权限再由 approval 机制处理审批。基础 bundle 默认挂载workspace-write文件沙箱与ask审批策略sandbox-policy将当前文件操作模式解析给实际后端。这一结构包含三个不同层次工具可见性模型能够提出哪些调用。执行审批某次调用是否获得许可。后端隔离获准执行后实际能够访问哪些资源。三者不能相互替代。审批通过只说明动作获得许可不代表执行环境具有无限权限模型看不到某个工具也不能据此证明其他工具无法访问相同资源。安全边界最终取决于策略配置与实际后端的共同约束而不只是沙箱模式的名称。6. 异常收敛异常是应用中很常见的东西也是 Harness 的重点处理对象。DSH 通过重试、压缩与取消各自处理不同问题。6.1 请求重试通过请求重试来保留失败记录避免重复提交输入。模型请求失败后系统先写入assistant/attempt再交给agent/request-error瀑布链处理。llm-retry根据适配器提供的 retry policy判断错误类型、重试次数与退避方式。计划重试与实际启动分别记录为llm/retry和llm/retry-started。重试在同一个 step 中重新准备请求不重复提交首次用户消息。这一边界避免了网络层重试演变成会话层的重复输入。分别记录重试计划与启动也使日志能够区分“决定重试”与“已经开始下一次尝试”。6.2 上下文压缩上下文压缩实现了替换可见历史保留原始事件。自动压缩在agent/pre-step检测上下文压力并记录compaction/startcompaction/summarycompaction/end随后系统将选中的连续历史区间替换为一个 checkpoint 用户消息。这里发生的是surface replace模型可见历史缩短原始日志仍然保留。因此压缩减少的是请求上下文不等于同步减少持久化存储。压缩也引入了信息损失的可能。原始约束即使仍在日志中只要没有进入摘要或剩余 surface后续模型就无法直接使用。压缩是否有效除了看上下文长度还取决于任务目标、限制条件和未完成事项是否得到保留。6.3 取消通过取消来传递停止信号而非撤销既有结果。AbortSignal 贯穿回合、请求和工具使取消信号能够沿执行链传递。但信号传递不等于立即停止所有动作。工具是否及时退出取决于其是否检查并响应取消已经完成的文件写入或远端操作也不会因 AbortSignal 自动回滚。取消机制提供的是停止继续执行的控制路径外部副作用的撤销仍需要独立实现。7. 小结DSH 的 Harness 实际上是一种架构的取舍其取舍考量的是可追溯性与运行成本。如下的机制共同形成了 DeepSeek Harness 的主要工程取舍机制提供的能力成本或边界Cordis 插件装配组件替换与能力组合行为分布在配置和多个处理器中turn / step 与输入队列明确输入归属和执行边界增加队列状态与事件维护追加式 Session审计与已提交状态重建日志持续增长不保证外部动作恰好执行一次surface 投影分离运行记录与模型上下文需要维护投影一致性与替换规则并发执行、顺序提交利用并发同时稳定历史顺序可能产生提交等待与结果暂存沙箱与审批分层控制动作权限实际保证依赖配置和执行后端自动压缩降低上下文窗口压力增加摘要成本并可能丢失任务信息AbortSignal统一传递取消意图依赖工具配合不能自动回滚副作用DeepSeek Harness 的核心价值是将 Agent 执行中的关键状态显式化输入有队列执行有边界请求有可见历史工具有调度与审批失败有独立的处理路径。这些机制使多轮任务能够被追踪、检查和恢复同时也明确了框架的能力边界日志恢复不能替代副作用确认顺序提交不能替代并发安全权限审批不能替代环境隔离上下文压缩也不能保证信息无损。以上。