DeepSeek Harness 解决的核心问题，是多轮模型调用、工具执行与会话状态之间的协调：输入何时进入请求，工具结果如何写回历史，请求失败后从哪里重试，上下文压缩后保留哪些信息，以及任务中断后能够恢复到什么状态。
围绕这些问题，框架将运行过程拆分为插件装配、回合驱动、会话日志、工具管道和异常处理。分析其架构的关键，在于各部分的状态边界，以及这些边界提供的保证与限制。
本篇文章限定在提交 477b4f4205（2026 年 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. Session
Session 机制实现了运行记录与模型历史分离。
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/start
- compaction/summary
- compaction/end
随后，系统将选中的连续历史区间替换为一个 checkpoint 用户消息。
这里发生的是 surface replace：模型可见历史缩短，原始日志仍然保留。因此，压缩减少的是请求上下文，不等于同步减少持久化存储。
压缩也引入了信息损失的可能。原始约束即使仍在日志中，只要没有进入摘要或剩余 surface，后续模型就无法直接使用。压缩是否有效，除了看上下文长度，还取决于任务目标、限制条件和未完成事项是否得到保留。
6.3 取消
通过取消来传递停止信号，而非撤销既有结果。
AbortSignal 贯穿回合、请求和工具，使取消信号能够沿执行链传递。
但信号传递不等于立即停止所有动作。工具是否及时退出，取决于其是否检查并响应取消；已经完成的文件写入或远端操作，也不会因 AbortSignal 自动回滚。
取消机制提供的是停止继续执行的控制路径，外部副作用的撤销仍需要独立实现。
7. 小结
DSH 的 Harness 实际上是一种架构的取舍，其取舍考量的是可追溯性与运行成本。
如下的机制共同形成了 DeepSeek Harness 的主要工程取舍：
DeepSeek Harness 的核心价值，是将 Agent 执行中的关键状态显式化：输入有队列，执行有边界，请求有可见历史，工具有调度与审批，失败有独立的处理路径。
这些机制使多轮任务能够被追踪、检查和恢复，同时也明确了框架的能力边界：日志恢复不能替代副作用确认，顺序提交不能替代并发安全，权限审批不能替代环境隔离，上下文压缩也不能保证信息无损。
以上。
本文由 AI图鉴自动抓取并翻译，版权归原作者所有；如需查看原文请点下方链接。
The core issues addressed by DeepSeek Harness are the coordination of multi-wheel model calls, tool execution conversation status: when to enter requests, how to write back the results of the tools, what to keep after the request failed, and what to return to after retry, context compression.
With these issues in mind, the framework makes the running process split a plugin assembly, round drive, session log, tool conduit and anomaly processing. The key to analysing its structure lies in the state-of-the-art boundaries of the components and the guarantees and limitations they provide.
This article is limited to the corresponding submission of 477 b4f4205 (25 September 2026).
1. Plugin assembly
The plugin is the core capacity of DeepSeek Harness, and the configuration of the plugin determines the capacity of Agent to operate.
DeepSeek Harness organises operational capability through the Cordis plugin. Cordis provides abstractions such as Context, Service, Plugin and Event, with plugins that rely on injections to collaborate with the event system and manage the life cycle within the framework.
LLM services, Session, Agent, AgentLoop and Tool Registration Forms, basic components, are mounted by the bookle. On startup, dsh loads the configuration as an entry, positions the configuration line by id and replaces the corresponding whole paragraph config.
The semantic of the configuration here is the whole paragraph replacement, not the field-class merger. When you cover the configuration of a component, field, which was not retained in the original configuration, may also disappear.
Plugin assembly therefore directly affects the actual behaviour of Agent: the availability of model services, which tools are registered and which event processors are involved in implementation depend on the eventual loading of the plugin and configuration. The warehouse contains a capability that does not mean that the current example of operation has enabled it.
This design facilitates the replacement of components and combination capabilities, but also allows the logical distribution of the execution in multiple plugins. An analysis of the behaviour of a request requires a simultaneous view of the core cycle, the plug-in registration relationship and the configuration of the final validity.
2. Core cycle
The Agent cycle is the core logic of Agent, which distinguishes between round, step and request retry.
In practical work logic, angent-loop is responsible for driving the cycle between models and tools. Its main implementation paths include:
- Prepare model requests, interpret configurations and select adapters.
- Projection system prompt, submission of user input for this entry into history.
- Construct requests from sessions, receive and accumulate current responses.
Other Organiser
- Implement the model ' s tool call and submit the results to the follow-up model request.
- Closure of the current round of implementation in the absence of tool call or when the conditions for completion have been met.
Understanding this path requires three levels:
- turn: round driven by user input.
-step: Implementation boundaries within the Round.
- Request to try: a call actually sent to the model, which can be retry in the same step after failure.
Therefore, step cannot simply be equated with a web request. retry may have attempted multiple requests, but should not repeat consumer input or repeat user messages.
Agent maintains the next-turn and the next-step queues, which take over the next round of input with next step, respectively. Queue changes to write to the session with ant/inbox/spliced events, and pending input can be restored from the log projection.
The design distinguishes between "the system has received news" and "models have consumed news".
Additional requirements to arrive in the course of implementation require subsequent requests to enter the respective border. It cannot automatically change the model requests that have been made, nor can it revoke the tool side effects that have occurred. Enter the queue and execute the cancellation and therefore the mechanism is different.
Writing a queue change into the log also avoids recovering only chat records while losing unprocessed inputs.
3. Session
The Ssession mechanism separates operational records from model history.
Session is designed to be an additional event log, which is sequenced by an incremental sequence number to type the type to save the content as body.
Logs record not only user and ansistant messages, but also running facts such as failed requests, queue changes, tool execution and compression processes.
However, events in the log do not necessarily enter the model context.
The real message sent to the model is recreated by the session's surface through deve-Messages() and frozen as an immutable request. Only news events that enter Surface are involved in the historical projection; running records such as ansistant/attempt do not automatically become model messages.
This separation has two effects:
- Maintaining information on the barrier: failure of the request and the recovery process can be fully documented without the need to occupy context window in full.
- Allows adjustment to Visible History: to keep the original event while compressing or replacing model context.
The session's append will also check the legitimacy of JSON's serialization, event rules and surface replacements to reduce data entry that cannot be sustained or correctly projected.
Log restoration does not mean external action rollback
The addition of the logs provides the basis for auditing and re-establishment of the status quo ante, but there can be no independent assurance that there will be no disruption at any point of interruption.
For example, the tool has modified the document, but the result has not been written to the Ssession before the process exits, and there may be a state difference between the external environment and the log. The restoration log can restore the records that have been submitted, but it cannot be judged by a mere lack of results that the tool is not being implemented.
Thus, resilience needs to be distinguished from:
- The events submitted and the restoration of their projection;
- Identification and treatment of external side effects.
The latter also rely on the homogeneity of the tool, the state-checking capacity or additional service mechanisms, which cannot be derived from the supplementary design of the Ssession alone.
4. Tool pipelines
Tool conduits have been achieved from model intent to controlled execution.
The tool registration form only exposes the model to white lists field such as name, description, parameters. Execute the functions, timeout settings and simultaneous properties while running.
This separates the tool description on the side of the model from the performance control at the time of operation: the model proposes a call, the framework determines whether and how the call is implemented.
One tool call pass by:
- Parameters generated by the parse model.
- A tool to find current Agent visible.
- Allows or refuses to call a pre-execution check through ols/pre-execute.
- Enter the chain of packing.
- Processing results through ols/post-execute.
- Write back the results to the Ssession for subsequent model requests.
permission inspects, executes packaging and results processing, thus having an independent intervention position, and does not have to be written in all tool functions.
Disconnect execution with sequence
The same asistant message may present multiple tool calls. Scheduler through the tool 's isConcurencySafe attribute classification:
- Revert explicitly the true call into the parallel pool.
- Other calls for treatment as a barrier of isolation.
The ability to make simultaneous statements is such that undeclared security instruments do not acquiesce in parallel implementation.
The tool capital can be sent in parallel, but prepare, process, document/result to write and attach a group to submit in the order in which the model calls. This avoids random changes in the order of outcomes in sessions when the tool is finished.
The price is the possibility of waiting: even if the latter tool is completed, it will have to wait for the previous call. Complementarity would reduce the time for partial implementation without ensuring that the results would enter history immediately; the results of early completion might need to be saved.
In addition, a stable sequence of submissions does not amount to an external side effect determination. The true security of the simultaneous tools remains dependent on their access to shared status, the existence of enforcement reliance and the accuracy of the accompanying statements.
5. Safe isolation
DSH achieves security by giving effect to approval and enforcement restrictions, respectively.
The sandbox models of Harness include:
type SandboxMode =
| 'read-only'
| 'workspace-write'
| 'danger-full-access'
The strategy involves file path permission, command execution restrictions and permission upgrades. The tool can be requested to upgrade permission through justification and Sandbox missions, and then processed and approved by the Approval mechanism.
Basic bundle Default mounts workspace-write file sandbox and ask approval policy; Sandbox-policy resolves the current file operating mode to the actual backend.
This structure has three different levels:
- Tool Visibility: What the model can suggest to call.
- Enforcement approval: whether a call is authorized.
- Back-end segregation: what resources are actually available for implementation.
There is no substitute for one another. Approval is granted by means of a description of actions, which does not mean that the implementation environment has unlimited permission; the model does not see a tool and does not prove that other tools cannot access the same resources.
Ultimately, a secure border depends on a combination of tactical configuration and actual back-end constraints, not just the name of the sandbox model.
6. Abnormal contraction
Anomalous is the most common thing in the application, and the main object of Harness.
DSH addresses different issues through retry, compression and cancellation.
6.1 Request retry
Keeps a record of failure by requesting retry and does not duplicate the submission of input.
After the model request fails, the system is written to ansistant/attempt and handed over to angent/request-error Falls Chain.
llm-retry determines the type of error, the number of retrys and the mode of withdrawal, based on the retry policy provided by the adaptor. Plan retry is recorded as llm/retry and llm/retry-starded respectively.
retry is reprepared in the same step and does not repeat the first user message. This boundary avoids the re-entry of network layer retry into session layer.
The separate recording of the retry program and its launch also allows the log to distinguish between “decision retry” and “the next attempt has already begun”.
6.2 context Compression
The context compression has replaced the Visible History and kept the original event.
Automatically compress context pressure at anent/pre-step and record:
- compaction/start
- compaction/summary
- compaction/end
The system then replaces the selected continuum with a checkpoint user message.
What happened here was surface replace: the model is shorter and the original log remains. Therefore, the reduction in compression is the request for context, which does not amount to a simultaneous reduction of the persistent storage.
Compression also introduces the possibility of loss of information. Even if the original constraint is still in the log, the subsequent model cannot be used directly as long as it does not enter summary or the remaining surface. The effectiveness of compression depends, in addition to the length of context, on the retention of mission objectives, restrictions and unfinished business.
6.3 Cancelled
Sending a stop signal by cancellation, rather than revoking the results.
AbortSignal runs through rounds, requests and tools, enabling cancellation signals to be transmitted along the implementation chain.
However, transmission does not mean that all movements are stopped immediately. The prompt exit of the tool depends on whether it checks and responds to cancellation; a completed file is written or a remote operation and does not automatically roll back because of AbortSignal.
The elimination mechanism provides a path of control to stop continued implementation, and the removal of external side effects still needs to be achieved independently.
Summary
DSH's Harness is in fact a structural trade-off, which is based on traceability and operating costs.
The main engineering trade-offs for DeepSeek Harness were made by the following mechanisms:
The core value of DeepSeek Harness is the visualization of the critical state in Agent implementation: input is queued, execution is borderline, requests have a visible history, tools are dispatch and approval and failure has an independent processing path.
These mechanisms enable multiple rounds of missions to be tracked, inspected and restored, while also clarifying the framework ' s capacity boundaries: restoration of logs cannot be a substitute for confirmation of side effects, sequential submission cannot be a substitute for simultaneous safety, permission approvals cannot be a substitute for environmental isolation, and context compression does not guarantee that information will not be compromised.
Over.
Auto-fetched and translated by AI Atlas. All rights belong to the original author.