DeepSeek Harness 的上下文、记忆与知识协同架构

在大模型应用开发中，上下文管理、记忆机制与知识获取往往是三个独立演进的技术议题，各自形成复杂系统却难以形成合力。DeepSeek Harness 作为一款面向编程场景的 Agent 运行时框架，采取了截然不同的设计思路：它没有为这三个能力分别构建重型系统，而是围绕一条统一的数据主线——Session Log，让上下文装配、历史压缩与外部知识注入共享同一套机制。这种架构选择带来的核心优势在于可回放、可审计，以及模块边界清晰。本文将逐层剖析这三个模块的设计逻辑与协作方式。

上下文分层装配机制

上下文管理解决的是一个具体问题：每次调用模型时，系统应该选择、组织并发送哪些内容。DeepSeek Harness 将上下文划分为四类：系统规则负责角色设定和行为约束；动态状态追踪当前工作目录和运行环境；会话历史记录用户消息和模型回复；工具定义描述当前允许模型调用的工具及其参数结构。这些内容分别由 SystemPrompt、Runtime Context、Session 和 ToolRuntime 管理，最后在模型调用前统一合并。在每个 step 开始前，ReactLoopAgent.preStep() 会调用 SystemPrompt.assemble()，收集本轮所需的系统提示、动态上下文和工具定义。各插件只负责注册自己的内容，最终由 SystemPrompt 统一生成本轮快照。RuntimeContextProjection 则会比较本轮快照和上一轮快照：如果内容没有变化，就继续沿用已有信息；如果内容发生变化，就生成新的上下文消息并写入 Session。这种机制减少了重复内容带来的 token 消耗，同时保留了状态变化轨迹。

会话记忆压缩策略

当会话历史逐渐增长时，Compaction 模块通过折叠旧历史来控制 token 消耗。它保留了原始事件在 Log 中，模型当前看到的历史则由结构化摘要替代。压缩触发条件由 tokenMeter 估算当前会话的 token 压力，再与模型的 contextWindow 比较。压缩区域由 selectCompactableRange() 选择，优先折叠较旧历史，同时保留近期上下文，因为近期消息通常包含当前修改进度、最新工具结果和下一步操作。区域选择还需要保护工具调用链，validateSurfaceRegion() 会检查压缩区域，避免破坏 tool-call 与 tool-result 的配对关系。摘要生成采用固定模板，包含主要请求与意图、文件与代码变更、错误与修复、下一步计划、关键上下文。结构化模板可以防止摘要退化成普通的对话概述，提高文件名、错误信息和失败尝试等关键信息的保留概率。压缩完成后，旧 surface 被替换为检查点，整个过程记录了压缩开始、摘要内容、被覆盖的事件序列和压缩结束，确保事务完整性。

外部知识获取链路

DeepSeek Harness 没有传统意义上的统一向量知识库，其知识入口由文件路径引用、Web 搜索与抓取、工具结果写入 Session 三部分组成。对于文件操作，file-reference-local 根据当前工作目录提供文件和目录候选，结果只包含路径和类型。用户选择文件后，输入框插入路径引用，模型需要通过 read 工具显式读取内容。这种分层处理避免了提前塞入大文件的问题，同时保留了用户意图和实际读取行为的完整记录。WorkspaceFileSearch 还控制目录边界、排除路径、最大条目，并拒绝通过符号链接跳出 workspace。对于精确检索，文件路径补全只能解决大致知道文件在哪里的问题，但大型仓库中经常需要回答接口定义位于哪个文件、某个符号有哪些引用等结构化查询。这类问题适合交给 LSP，项目已包含 packages/lsp 模块，可提供跳转到定义、查找引用、工作区符号搜索和调用关系查询。仓库检索分成四层：已知路径直接读取文件；已知文本使用 grep；已知符号使用 LSP；只有概念描述时才考虑语义检索。这种逻辑优先消耗确定性信息，因为代码仓库已经提供路径和符号结构，没有必要先把问题转换成向量相似度。外部知识还通过 Web 搜索和抓取引入，搜索结果格式化后带 URL 提示，抓取的 HTML 转换为 Markdown。HTTP provider 包含严格的安全限制，防止模型生成的不可信 URL 造成安全风险。

三者协同与架构启示

上下文、记忆和知识获取分别控制模型输入的三个阶段。上下文决定当前输入——SystemPrompt 收集系统约束、动态状态和工具 schema，preStep() 判断动态内容是否变化，buildRequest() 构建最终模型请求。记忆控制历史体积——Compaction 观察 token 压力，选择旧历史区域，生成结构化摘要，再替换当前 surface。知识补充外部信息——文件引用帮助定位路径，读取工具获得仓库内容，Web 工具获取外部信息。所有模块最终都回到 Session。动态上下文通过 user/message 进入日志，工具信息通过 tool/result 进入日志，压缩通过 compaction/* 事件和 replacement message 改写 surface，后续模型输入由 Session.deriveMessages() 统一派生。这种设计带来了三个核心优势：模型看到的每段内容都有明确来源和记录，可以从 Session 恢复和追踪；动态信息不会被无意义地重复发送，压缩不会覆盖原始事件；模块边界清晰，插件可以增加新的上下文来源、工具和压缩策略，但不能绕过 Session Log 主线。这对智能体开发平台的设计具有重要参考价值——在构建复杂 Agent 系统时，数据主线和可回放能力往往比具体使用哪种模型、搜索服务或向量数据库更影响系统的长期维护成本。

DeepSeek Harness 的设计表明，上下文管理、记忆压缩与知识获取并非三个独立的重型系统，而是围绕 Session Log 协同工作的有机整体。上下文管理负责装配当前输入，Compaction 负责压缩会话历史，文件和 Web 工具负责补充缺失信息，三者共享 Session Log 作为数据主线，形成可回放、可审计的完整链路。现有设计的优势集中在可追踪性和模块边界清晰，主要缺口包括 Compaction 的语义损失、压缩调用的同步延迟、符号级检索的完善，以及跨 Session 长期记忆的独立体系。对于构建高质量 Agent 系统的实践者而言，深入理解这种协同架构的设计逻辑，比关注具体技术选型更具长期价值。