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()，收集本轮所需的系统提示、动态上下文和工具定义。
其中：
contexts 提供会随运行状态变化的环境信息；
各插件只负责注册自己的内容，最终由 SystemPrompt 统一生成本轮快照。
这意味着上下文并不是固定不变的。例如，插件启停、工作目录变化或工具权限调整后，下一次模型调用可以获得最新状态，不需要由 AgentLoop 编写额外的业务分支。
3. 避免重复注入动态状态
动态上下文并不需要每个 step 都重复写入。
RuntimeContextProjection 会比较本轮快照和上一轮快照：
- 如果内容发生变化，就生成新的上下文消息并写入 Session。
这种机制有两个作用。
第一，减少重复内容带来的 token 消耗。工作目录和运行环境可能连续多个 step 保持不变，没有必要反复加入会话历史。
第二，保留状态变化轨迹。当环境发生变化时，新快照会进入 Session，后续可以追踪模型从哪一轮开始看到了新的状态。
投影状态还可以从已有 Session 中恢复。因此，即使服务重启，系统也能判断某段动态上下文是否已经注入，避免因为进程内状态丢失而重复写入。
4. 统一派生会话历史
用户消息、模型回复和工具结果不会由控制器临时拼入请求，而是先写入 Session Log，再由 Session.deriveMessages() 派生为模型协议需要的消息列表。
这使系统能够区分三个层次：
例如，工具执行结果先作为 tool/result 写入 Session，下一轮再由 deriveMessages() 转换成模型可以读取的消息。上下文压缩也只调整 Surface，不直接删除原始事件。
因此，模型输入不是由多个模块临时修改的消息数组，而是由统一的会话记录派生出来的。
5. 构建并记录最终请求
上下文装配完成后，buildRequest() 会生成最终的模型请求，主要包括：
同时，系统会记录 request/header 和 request/context，保存本次调用使用的关键上下文信息。
这样可以回答几个重要问题：
DeepSeek Harness 的上下文管理并不是简单地将内容放进消息列表，而是围绕分层管理、动态装配、变化检测和统一派生建立完整流程。
其核心链路可以概括为：
各模块提供上下文 → SystemPrompt 动态装配 → RuntimeContextProjection 检测变化 → Session 派生历史消息 → buildRequest 构建并记录最终请求。
这样，每段上下文都有明确来源，动态信息不会被无意义地重复发送，模型输入可以从 Session 中恢复和追踪，AgentLoop 也不需要承载复杂的提示词与历史管理逻辑。
记忆压缩
DeepSeek Harness 当前的记忆能力主要由 Compaction 提供。
这里需要控制术语。Compaction 服务于当前会话的连续运行，它会把旧历史折叠成结构化检查点。跨 Session 的用户偏好、项目经验和长期事实存储，目前没有形成完整系统。
因此，我更愿意把它称为「会话记忆」。
1. 压缩对象
Session 内部存在三个层次：
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
结构化模板可以防止摘要退化成普通的对话概述。
编程 Agent 的历史里，有用的信息通常集中在几类内容：
如果只要求模型「概括以上对话」，输出往往会省略文件名、错误信息和失败尝试。摘要读起来流畅，后续执行却接不上。
固定结构会提高这些信息的保留概率，但无法保证语义完整。
4. 替换事务
摘要生成以后，会被包装进 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', { ... })
整个过程会记录：
sourceEventSeqs 建立了检查点与原始历史之间的关联。排查错误摘要时，开发者可以反查它覆盖了哪些事件。
Session.deriveMessages() 检测到 replaceGeneration 发生变化后，会重建消息缓存。后续模型看到的是新检查点和保留下来的近期历史。
当前的设计保证了事务的完整性。压缩失败时，旧 surface 仍然可以继续使用。摘要生成成功且提交完成后，模型视图才发生变化。
5. 有损风险
Compaction 无法绕开有损问题。
假设旧历史中出现过一条约束：测试环境使用特定环境变量，变量为空时必须跳过某项操作。摘要模型漏掉这条信息以后，后续 Agent 可能执行错误命令。
原始事件虽然还在 Log 中，当前模型无法自动访问。对推理过程而言，这条信息已经离开热上下文。
因此，Session Log 的完整性解决了审计问题，没有完全解决信息恢复问题。
我会在现有 Compaction 上增加一层历史召回能力。摘要中保留关键事件引用，模型缺少细节时，可以调用类似 recall_history 的工具读取旧历史。
召回参数可以采用结构化维度：
这种方式比单纯的语义搜索更稳定一些。Session 已经拥有完整事件顺序和来源关系，应优先利用现有结构。
召回结果也要写成 tool/result。这样系统可以知道模型恢复了哪段历史，以及这段历史怎样影响后续决策。
6. 调度延迟
当前压缩会调用一次 LLM。压缩发生在主流程上时，用户需要等待摘要完成。
会话较短时，这个延迟可以接受。长会话的摘要输入很大，调用时间会明显增加。编程 Agent 还可能连续执行多个工具，压缩恰好卡在下一步之前，交互体验会出现停顿。
可以引入两级水位：
- 接近窗口上限时，后台生成候选 checkpoint；
异步压缩的难点集中在一致性。
生成摘要期间，Session 还会继续追加事件。提交前必须校验它对应的 surface generation，确保被压缩区域没有发生冲突。检查点过期后不能强行替换，否则可能覆盖新的工具结果或用户输入。
当前已有的压缩重入保护、surface generation 和事务事件，为异步化提供了基础。早期保持同步更稳，长任务比例上升以后，再逐步引入后台 checkpoint。
知识获取
DeepSeek Harness 没有传统意义上的统一向量知识库。
它的知识入口由三部分组成：
这种组合适合编程 Agent。代码仓库里的信息具有路径、符号、定义和引用关系。统一切块并写入向量数据库，会损失一部分结构信息，还要承担索引更新成本。
1. 文件引用
file-reference-local 提供工作区文件和目录候选。
它会根据 session.header.cwd 创建 WorkspaceFileSearch，然后扫描当前工作区。结果只包含：
用户在前端选择文件后，输入框里会插入 @path 或 @"path with spaces"。
文件内容不会在这个阶段进入模型。
系统提示会告诉模型，@ token 表示工作区路径。模型需要读取内容时，应调用 read 工具。
这个分层处理了两个不同问题：
file-reference-local 负责找到路径；
如果选择路径时就把整个文件自动塞进消息，系统会遇到几类麻烦。
第一，大文件会快速占满上下文。
第二，用户无法知道系统展开了多少内容。
第三，读取行为缺少独立记录。
第四，文件权限和读取范围可能绕过工具 guard。
第五，文件修改以后，很难判断模型当时看到的是哪个版本。
路径引用保留了用户意图，工具调用保留了实际读取行为。两类信息都会进入 Session，审计链更完整。
WorkspaceFileSearch 还会控制目录边界、排除路径、最大条目和候选数量，并拒绝通过 .. 或符号链接跳出 workspace。
这些限制属于安全边界。文件路径来自用户输入，也可能由模型生成，不能默认可信。
2. 精确检索
文件路径补全只能解决「大致知道文件在哪里」的问题。
大型仓库中，开发者和模型经常需要回答另一类问题：
这些查询适合交给 LSP。
项目已经存在 packages/lsp/，可以继续扩展为代码检索能力。优先提供：
向量检索依赖语义相似度。两个函数命名和注释很接近，并不能证明它们具有依赖关系。LSP 返回的是语言服务器维护的定义和引用关系，适合代码修改场景。
可以把仓库检索分成四层：
这个逻辑会优先消耗确定性信息。代码仓库已经提供路径和符号结构，没有必要先把问题转换成向量相似度。
LSP 也有运行成本。语言服务器需要启动和预热，多语言仓库要维护多个进程，大型 monorepo 的全局引用查询可能很慢。它适合作为工具按需调用，不适合把所有结果常驻上下文。
查询结果仍然要通过 ToolRuntime 写入 Session。这样模型读取过哪些定义、哪些引用，可以在后续回放中找到。
3. Web 检索
外部知识通过 web_search 和 web_fetch 进入模型。
整体分为三层：
- search/fetch provider 负责具体请求；
这种分层使工具 schema 与供应商解耦。模型只需要理解 web_search 和 web_fetch。底层可以选择 DeepSeek、Exa、Perplexity 或 HTTP fetch provider。
Provider 选择规则保持严格：
- 配置了 provider id，使用指定 provider；
- 未配置时，系统要求只有一个可用 provider；
这可以避免插件加载顺序影响线上行为。
Web 搜索结果会被格式化成模型可见文本，并带有外部内容不可信和引用 URL 的提示。Web fetch 会把 HTML 转换成 Markdown，普通文本则直接进入结果。
提示只能影响模型行为，网络边界还要由 provider 控制。HTTP fetch provider 已经包含多项限制：
模型生成的 URL也属于不可信输入。网页中的 Prompt Injection 可能诱导模型请求内网地址、云元数据地址或带有凭证的 URL。网络策略需要在模型之外执行。
4. 工具入库
文件读取、Web 搜索和 Web 抓取获得的信息，都通过同一条工具链进入模型。
流程可以概括为：
- ToolRuntime 把工具 schema 注册到 SystemPrompt；
- AgentLoop 调用
executeToolCalls()； - 下一轮
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 中记录：
模型没有看到的正文，无须全部伪装成上下文历史。回放能力关注的是当时的模型输入。
三者关系
上下文、记忆和知识获取分别控制模型输入的三个阶段。
上下文决定当前输入： 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 的三个模块可以归纳为三句话：
三者共享 Session Log：
- 后续模型输入由
Session.deriveMessages() 统一派生。
现有设计的优势集中在可回放、可审计和模块边界。主要缺口也很具体：Compaction 存在语义损失，压缩调用会阻塞主流程，文件路径检索缺少符号级能力，跨 Session 长期记忆尚未形成独立体系。
Session Log 继续保存事实，surface 控制模型当前看到的历史，工具负责按需获取信息。三个模块沿着这条数据链协作，系统才能在上下文窗口、运行延迟和信息完整性之间保持可控。
以上。
粤ICP备14082021号
免费POC，
零成本试错
