DeepSeek Harness 的上下文管理、记忆和知识库剖析

DeepSeek Harness 里，上下文、记忆和知识库并没有被设计成三个彼此独立的重型系统。它们围绕 Session Log 协同工作。

用三句话概括：

  • 上下文管理负责决定当前这一轮模型能看到什么。系统提示词、动态环境、工具定义和会话消息，会在模型调用前完成装配。
  • 记忆机制负责在上下文窗口不足时折叠旧历史。原始会话日志继续保留，模型当前可见的历史被替换成结构化摘要。
  • 知识获取负责把仓库文件和外部信息送入模型。文件通过路径引用和读取工具进入，网络信息通过搜索、抓取工具进入，所有结果最终写回 Session Log。

三个模块共享一条约束：

模型看到的内容，需要拥有可追踪的来源，并且能够从会话记录中重新构造。

这条约束决定了 DeepSeek Harness 的整体形态。上下文不能由控制器随手拼接，工具结果不能停留在进程内存，压缩不能覆盖原始记录，检索结果也不能绕过会话日志直接塞给模型。

它由此形成了一条完整链路：

SystemPrompt.assemble() 组装当前上下文，ReactLoopAgent.preStep() 决定动态内容是否进入会话，Session.append() 保存事件，Session.deriveMessages() 生成模型历史，buildRequest() 构建最终请求，llm.stream() 完成模型调用。

理解了这条链路，就大概能了解 DeepSeek Harness 的知识和记忆相关的逻辑了。

上下文管理

上下文管理解决的是一个具体问题：每次调用模型时，系统应该选择、组织并发送哪些内容。

现在大多数 Agent 系统不会简单维护一个持续增长的字符串，而是使用结构化消息列表管理上下文。较成熟的系统还会根据任务状态，动态选择系统提示词、历史消息、工具定义、运行环境和检索结果。

真正的难的不是 「是否使用消息列表」，而在于：

  • 哪些内容应该进入本轮请求；
  • 不同内容由哪个模块提供；
  • 动态状态发生变化后如何更新；
  • 重复信息是否需要再次发送；
  • 长会话中哪些历史应该保留或压缩；
  • 服务重启后能否恢复模型当时看到的内容；
  • 最终请求能否被追踪、审计和重放。

DeepSeek Harness 同样以结构化消息为基础，但它没有让 AgentLoop 直接维护所有上下文，而是将上下文拆分为不同来源，在每个 step 开始前统一装配。

1. 分层组织上下文

DeepSeek Harness 中的上下文主要分为四类：

  • 系统规则：角色设定、行为约束和工具使用规范；
  • 动态状态：当前工作目录、运行环境和终端状态；
  • 会话历史：用户消息、模型回复和工具调用结果；
  • 工具定义：当前允许模型调用的工具及其参数结构。

这些内容分别由 SystemPrompt、Runtime Context、Session 和 ToolRuntime 管理，最后在模型调用前合并。

这种设计的重点不是改变消息格式，而是明确上下文的来源和职责。AgentLoop 只负责控制执行流程，不直接承担提示词拼接、历史管理和工具注册等工作。

2. 动态装配本轮内容

每个 step 开始前，ReactLoopAgent.preStep() 会调用 SystemPrompt.assemble()，收集本轮所需的系统提示、动态上下文和工具定义。

其中：

  • sections 保存相对稳定的系统提示；
  • contexts 提供会随运行状态变化的环境信息；
  • tools 描述当前可用的工具；
  • variables 提供提示词渲染需要的变量。

各插件只负责注册自己的内容，最终由 SystemPrompt 统一生成本轮快照。

这意味着上下文并不是固定不变的。例如，插件启停、工作目录变化或工具权限调整后，下一次模型调用可以获得最新状态，不需要由 AgentLoop 编写额外的业务分支。

3. 避免重复注入动态状态

动态上下文并不需要每个 step 都重复写入。

RuntimeContextProjection 会比较本轮快照和上一轮快照：

  • 如果内容没有变化，就继续沿用已有信息；
  • 如果内容发生变化，就生成新的上下文消息并写入 Session。

这种机制有两个作用。

第一，减少重复内容带来的 token 消耗。工作目录和运行环境可能连续多个 step 保持不变，没有必要反复加入会话历史。

第二，保留状态变化轨迹。当环境发生变化时，新快照会进入 Session，后续可以追踪模型从哪一轮开始看到了新的状态。

投影状态还可以从已有 Session 中恢复。因此，即使服务重启，系统也能判断某段动态上下文是否已经注入，避免因为进程内状态丢失而重复写入。

4. 统一派生会话历史

用户消息、模型回复和工具结果不会由控制器临时拼入请求，而是先写入 Session Log，再由 Session.deriveMessages() 派生为模型协议需要的消息列表。

这使系统能够区分三个层次：

  • Log：完整保存原始会话事件；
  • Surface：决定当前哪些事件参与模型上下文；
  • Messages：最终发送给模型的结构化消息。

例如，工具执行结果先作为 tool/result 写入 Session，下一轮再由 deriveMessages() 转换成模型可以读取的消息。上下文压缩也只调整 Surface，不直接删除原始事件。

因此，模型输入不是由多个模块临时修改的消息数组，而是由统一的会话记录派生出来的。

5. 构建并记录最终请求

上下文装配完成后，buildRequest() 会生成最终的模型请求，主要包括：

  • system：系统提示；
  • messages：会话历史和动态上下文；
  • tools：当前可用的工具定义；
  • sessionId：当前会话标识；
  • signal：调用控制信号。

同时，系统会记录 request/header 和 request/context，保存本次调用使用的关键上下文信息。

这样可以回答几个重要问题：

  • 模型当时看到了哪些历史；
  • 使用了哪一版系统提示；
  • 当时有哪些可用工具；
  • 动态环境是否已经发生变化；
  • 某次异常是模型推理问题，还是输入上下文问题。

DeepSeek Harness 的上下文管理并不是简单地将内容放进消息列表，而是围绕分层管理、动态装配、变化检测和统一派生建立完整流程。

其核心链路可以概括为：

各模块提供上下文 → SystemPrompt 动态装配 → RuntimeContextProjection 检测变化 → Session 派生历史消息 → buildRequest 构建并记录最终请求。

这样，每段上下文都有明确来源，动态信息不会被无意义地重复发送，模型输入可以从 Session 中恢复和追踪，AgentLoop 也不需要承载复杂的提示词与历史管理逻辑。

记忆压缩

DeepSeek Harness 当前的记忆能力主要由 Compaction 提供。

这里需要控制术语。Compaction 服务于当前会话的连续运行，它会把旧历史折叠成结构化检查点。跨 Session 的用户偏好、项目经验和长期事实存储，目前没有形成完整系统。

因此，我更愿意把它称为「会话记忆」。

1. 压缩对象

Session 内部存在三个层次：

  • Log：所有原始事件组成的追加日志；
  • Surface：当前参与模型消息派生的事件视图；
  • Messages：发送给模型的协议消息。

Compaction 修改的是 surface。

原始事件仍然保留在 Log 中，模型当前看到的历史则由摘要节点替代。这个结构同时满足了两个要求：

  • 模型输入得到缩短；
  • 原始会话记录没有被覆盖。

它比直接删除前 N 条消息安全很多。

删除历史以后，调试系统无法知道模型之前看过什么。线上出现问题时，只剩下截断后的残缺记录。Compaction 保留原始事件，后续仍可审计压缩范围和摘要来源。

2. 触发条件

BasicCompactionEngine 会通过 tokenMeter.measure(session) 估算当前会话的 token 压力，再与模型的 contextWindow 比较。

自动压缩拥有两个主要触发入口：

  • agent/pre-step 阶段的常规压力检查；
  • 模型返回上下文溢出错误后的重试处理。

常规检查负责提前处理窗口压力，错误重试负责兜底。

压缩区域由 selectCompactableRange() 选择。它会优先折叠较旧历史，并保留近期上下文。近期消息通常包含当前修改进度、最新工具结果和下一步操作，保留它们可以减少摘要对短期推理的影响。

区域选择还需要保护工具调用链。

Assistant 发出的 tool-call 和对应的 tool-result 属于一组完整语义。若压缩边界将它们切开，后续模型可能看到孤立的调用或孤立的结果。部分模型适配器甚至会直接拒绝这种消息结构。

validateSurfaceRegion() 会检查压缩区域，避免破坏工具调用与结果的配对关系。

这类结构校验比简单的「保留最近 N 条消息」可靠。Agent 历史已经超出普通聊天记录的范畴，消息之间存在协议级关联，切割时必须理解这些关联。

3. 摘要生成

压缩区域选定后，buildSummarizationInput() 会恢复对应的模型消息，并取回当时的 system 和 tools。summarizeWithLlm() 随后调用 LLM 生成摘要。

摘要受到固定模板约束，主要包含：

  • Primary Request and Intent
  • Files and Code
  • Errors and Fixes
  • Next Step
  • Critical Context

结构化模板可以防止摘要退化成普通的对话概述。

编程 Agent 的历史里，有用的信息通常集中在几类内容：

  • 用户最初要解决的问题；
  • 已经读取或修改的文件；
  • 执行过的命令；
  • 失败原因和修复过程；
  • 当前未完成步骤；
  • 不能违反的环境约束。

如果只要求模型「概括以上对话」，输出往往会省略文件名、错误信息和失败尝试。摘要读起来流畅，后续执行却接不上。

固定结构会提高这些信息的保留概率，但无法保证语义完整。

4. 替换事务

摘要生成以后，会被包装进 <compacted-summary>，随后作为新的 user/message 写入 Session，并通过 surfaceOp: replace 替换旧区域。

参考实现中的主流程如下：

// compaction-basic/region.ts 的逻辑简化
session.append('compaction/start', { ... })

const summary = await summarizeWithLlm(ctx, config, input, agent, signal)
const framed = frameSummary(summary.summary)

const summaryEvent = session.append('compaction/summary', { ... })

session.append(
  'user/message',
  createUserMessage({
    content: framed,
    source: compactCheckpointSource(...),
  }),
  {
    surfaceOp: { op: 'replace', start, end },
    sourceEventSeqs: [startEvent.seq, summaryEvent.seq, ...shadowedSeqs],
  },
)

session.append('compaction/end', { ... })

整个过程会记录：

  • 压缩开始；
  • 摘要内容；
  • replacement message；
  • 被覆盖的事件序列；
  • 压缩结束。

sourceEventSeqs 建立了检查点与原始历史之间的关联。排查错误摘要时，开发者可以反查它覆盖了哪些事件。

Session.deriveMessages() 检测到 replaceGeneration 发生变化后，会重建消息缓存。后续模型看到的是新检查点和保留下来的近期历史。

当前的设计保证了事务的完整性。压缩失败时，旧 surface 仍然可以继续使用。摘要生成成功且提交完成后，模型视图才发生变化。

5. 有损风险

Compaction 无法绕开有损问题。

假设旧历史中出现过一条约束：测试环境使用特定环境变量，变量为空时必须跳过某项操作。摘要模型漏掉这条信息以后，后续 Agent 可能执行错误命令。

原始事件虽然还在 Log 中，当前模型无法自动访问。对推理过程而言，这条信息已经离开热上下文。

因此，Session Log 的完整性解决了审计问题，没有完全解决信息恢复问题。

我会在现有 Compaction 上增加一层历史召回能力。摘要中保留关键事件引用，模型缺少细节时，可以调用类似 recall_history 的工具读取旧历史。

召回参数可以采用结构化维度：

  • turn 范围；
  • step 范围；
  • event seq；
  • tool call id；
  • 文件路径；
  • compaction id。

这种方式比单纯的语义搜索更稳定一些。Session 已经拥有完整事件顺序和来源关系，应优先利用现有结构。

召回结果也要写成 tool/result。这样系统可以知道模型恢复了哪段历史，以及这段历史怎样影响后续决策。

6. 调度延迟

当前压缩会调用一次 LLM。压缩发生在主流程上时，用户需要等待摘要完成。

会话较短时，这个延迟可以接受。长会话的摘要输入很大，调用时间会明显增加。编程 Agent 还可能连续执行多个工具，压缩恰好卡在下一步之前，交互体验会出现停顿。

可以引入两级水位：

  • 接近窗口上限时，后台生成候选 checkpoint；
  • 到达硬上限时，提交已有 checkpoint；
  • 候选结果过期时放弃；
  • 没有可用结果时回退到同步压缩。

异步压缩的难点集中在一致性。

生成摘要期间，Session 还会继续追加事件。提交前必须校验它对应的 surface generation，确保被压缩区域没有发生冲突。检查点过期后不能强行替换，否则可能覆盖新的工具结果或用户输入。

当前已有的压缩重入保护、surface generation 和事务事件，为异步化提供了基础。早期保持同步更稳，长任务比例上升以后，再逐步引入后台 checkpoint。

知识获取

DeepSeek Harness 没有传统意义上的统一向量知识库。

它的知识入口由三部分组成：

  • 文件路径引用；
  • Web 搜索与抓取；
  • 工具结果写入 Session。

这种组合适合编程 Agent。代码仓库里的信息具有路径、符号、定义和引用关系。统一切块并写入向量数据库，会损失一部分结构信息，还要承担索引更新成本。

1. 文件引用

file-reference-local 提供工作区文件和目录候选。

它会根据 session.header.cwd 创建 WorkspaceFileSearch，然后扫描当前工作区。结果只包含：

  • path
  • kind

用户在前端选择文件后，输入框里会插入 @path 或 @"path with spaces"。

文件内容不会在这个阶段进入模型。

系统提示会告诉模型，@ token 表示工作区路径。模型需要读取内容时，应调用 read 工具。

这个分层处理了两个不同问题：

  • file-reference-local 负责找到路径；
  • read 工具负责读取内容。

如果选择路径时就把整个文件自动塞进消息，系统会遇到几类麻烦。

第一，大文件会快速占满上下文。

第二，用户无法知道系统展开了多少内容。

第三，读取行为缺少独立记录。

第四，文件权限和读取范围可能绕过工具 guard。

第五，文件修改以后，很难判断模型当时看到的是哪个版本。

路径引用保留了用户意图，工具调用保留了实际读取行为。两类信息都会进入 Session，审计链更完整。

WorkspaceFileSearch 还会控制目录边界、排除路径、最大条目和候选数量，并拒绝通过 .. 或符号链接跳出 workspace。

这些限制属于安全边界。文件路径来自用户输入，也可能由模型生成，不能默认可信。

2. 精确检索

文件路径补全只能解决「大致知道文件在哪里」的问题。

大型仓库中，开发者和模型经常需要回答另一类问题：

  • 接口定义位于哪个文件；
  • 某个符号有哪些引用；
  • 哪些实现依赖当前类型；
  • 一次修改会影响哪些调用点；
  • 编译诊断关联到哪些符号。

这些查询适合交给 LSP。

项目已经存在 packages/lsp/，可以继续扩展为代码检索能力。优先提供：

  • Go to Definition；
  • Find References；
  • Workspace Symbols；
  • Diagnostics；
  • 调用关系。

向量检索依赖语义相似度。两个函数命名和注释很接近，并不能证明它们具有依赖关系。LSP 返回的是语言服务器维护的定义和引用关系，适合代码修改场景。

可以把仓库检索分成四层：

  1. 已知路径，直接读取文件；
  2. 已知文本，使用 grep；
  3. 已知符号，使用 LSP；
  4. 只有概念描述时，再考虑语义检索。

这个逻辑会优先消耗确定性信息。代码仓库已经提供路径和符号结构，没有必要先把问题转换成向量相似度。

LSP 也有运行成本。语言服务器需要启动和预热，多语言仓库要维护多个进程，大型 monorepo 的全局引用查询可能很慢。它适合作为工具按需调用，不适合把所有结果常驻上下文。

查询结果仍然要通过 ToolRuntime 写入 Session。这样模型读取过哪些定义、哪些引用，可以在后续回放中找到。

3. Web 检索

外部知识通过 web_search 和 web_fetch 进入模型。

整体分为三层：

  • WebRuntime 定义统一能力；
  • search/fetch provider 负责具体请求；
  • tool-web 把能力注册成模型可见工具。

这种分层使工具 schema 与供应商解耦。模型只需要理解 web_search 和 web_fetch。底层可以选择 DeepSeek、Exa、Perplexity 或 HTTP fetch provider。

Provider 选择规则保持严格：

  • 配置了 provider id，使用指定 provider；
  • 未配置时，系统要求只有一个可用 provider；
  • 多个 provider 同时可用时直接报错。

这可以避免插件加载顺序影响线上行为。

Web 搜索结果会被格式化成模型可见文本，并带有外部内容不可信和引用 URL 的提示。Web fetch 会把 HTML 转换成 Markdown，普通文本则直接进入结果。

提示只能影响模型行为，网络边界还要由 provider 控制。HTTP fetch provider 已经包含多项限制：

  • 只允许 HTTP(S)；
  • 拒绝 URL credentials；
  • 拒绝私网和非公网地址；
  • 控制同源重定向；
  • 限制重定向次数；
  • 限制响应字节数；
  • 限制正文长度；
  • 固定经过校验的 DNS 地址；
  • timeout 由部署配置管理。

模型生成的 URL也属于不可信输入。网页中的 Prompt Injection 可能诱导模型请求内网地址、云元数据地址或带有凭证的 URL。网络策略需要在模型之外执行。

4. 工具入库

文件读取、Web 搜索和 Web 抓取获得的信息，都通过同一条工具链进入模型。

流程可以概括为：

  1. ToolRuntime 把工具 schema 注册到 SystemPrompt；
  2. 模型返回 tool-call；
  3. AgentLoop 调用 executeToolCalls()；
  4. Session 写入 tool/call；
  5. ToolRuntime 执行工具；
  6. Session 写入 tool/result；
  7. 下一轮 deriveMessages() 把结果投影给模型。

参考实现中的调用路径如下：

// 模型返回 tool-call
const toolCalls = message.content.filter(block => block.type === 'tool-call')

// Agent 执行工具
const { concluded } = await executeToolCalls(
  this.loopCtx,
  turn,
  step,
  toolCalls,
  signal,
  context => this.inbox.splice('next-step', this.inbox.nextStep.length, 0, [context]),
)

// 工具结果进入 session log，下一 step 被 deriveMessages() 投影给模型

工具结果不会只停留在当前执行栈，也不会直接修改临时 messages 数组。

这对 Web 信息尤其关键。搜索结果和网页内容会随时间变化。如果系统只记录搜索参数，重放时重新请求一次，模型得到的内容可能已经不同。

文件读取也一样。Agent 可能在读取后修改文件。历史推理需要保留当时真正发送给模型的内容。

当然，完整保存所有工具输出会增加 Session 体积。工程上可以保存模型实际看到的渲染结果，同时在 meta 中记录：

  • 是否截断；
  • 原始内容长度；
  • 来源路径或 URL；
  • content type；
  • 工具调用参数；
  • provider 信息。

模型没有看到的正文，无须全部伪装成上下文历史。回放能力关注的是当时的模型输入。

三者关系

上下文、记忆和知识获取分别控制模型输入的三个阶段。

  • 上下文决定当前输入： SystemPrompt 收集系统约束、动态状态和工具 schema。preStep() 判断动态内容是否变化，buildRequest() 构建最终模型请求。它解决的是「这一轮应该携带什么」。
  • 记忆控制历史体积： Compaction 观察 token 压力，选择旧历史区域，生成结构化摘要，再替换当前 surface。它解决的是「历史太长以后保留什么」。
  • 知识补充外部信息：文件引用帮助定位路径，读取工具获得仓库内容，Web 工具获取外部信息，未来还可以用 LSP 提供符号级查询。它解决的是「当前会话缺少的信息从哪里获得」。

三者最终都回到 Session。

动态上下文通过 user/message 进入日志，工具信息通过 tool/result 进入日志，压缩通过 compaction/* 事件和 replacement message 改写 surface。

所以，DeepSeek Harness 的数据主线可以压缩为：

装配上下文，记录事件，派生消息，调用模型，执行工具，写回结果，必要时折叠 surface。

插件可以增加新的上下文来源、新的工具和新的压缩策略，但不能绕过这条主线。

直接向 GenerateOptions.messages 塞内容，会产生无法回放的隐形上下文。

检索模块绕过 ToolRuntime，会失去权限、审计和结果记录。

压缩模块覆盖原始事件，会破坏历史追踪。

这几条边界比具体使用哪种模型、搜索服务或向量数据库更影响系统的维护成本。

小结

DeepSeek Harness 的三个模块可以归纳为三句话：

  • 上下文管理负责装配当前输入。
  • Compaction 负责压缩当前会话历史。
  • 文件和 Web 工具负责补充当前缺失的信息。

三者共享 Session Log：

  • 模型看到的动态状态要进入日志；
  • 模型获得的工具结果要进入日志；
  • 压缩只调整 surface，原始事件继续保留；
  • 后续模型输入由 Session.deriveMessages() 统一派生。

现有设计的优势集中在可回放、可审计和模块边界。主要缺口也很具体：Compaction 存在语义损失，压缩调用会阻塞主流程，文件路径检索缺少符号级能力，跨 Session 长期记忆尚未形成独立体系。

Session Log 继续保存事实，surface 控制模型当前看到的历史，工具负责按需获取信息。三个模块沿着这条数据链协作，系统才能在上下文窗口、运行延迟和信息完整性之间保持可控。

以上。