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 IntentFiles and CodeErrors and FixesNext StepCritical 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，然后扫描当前工作区。结果只包含：
pathkind
用户在前端选择文件后，输入框里会插入 @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 返回的是语言服务器维护的定义和引用关系，适合代码修改场景。
可以把仓库检索分成四层：
- 已知路径，直接读取文件；
- 已知文本，使用
grep； - 已知符号，使用 LSP；
- 只有概念描述时，再考虑语义检索。
这个逻辑会优先消耗确定性信息。代码仓库已经提供路径和符号结构，没有必要先把问题转换成向量相似度。
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 抓取获得的信息，都通过同一条工具链进入模型。
流程可以概括为：
- ToolRuntime 把工具 schema 注册到 SystemPrompt；
- 模型返回 tool-call；
- AgentLoop 调用
executeToolCalls()； - Session 写入
tool/call； - ToolRuntime 执行工具；
- Session 写入
tool/result； - 下一轮
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 控制模型当前看到的历史，工具负责按需获取信息。三个模块沿着这条数据链协作，系统才能在上下文窗口、运行延迟和信息完整性之间保持可控。
以上。
