智能体上下文管理

是什么，为什么存在

智能体上下文是编程智能体为一次决策获得的有限工作集（working set）。其中可以包含任务、仓库指令、源文件、测试、配置、搜索结果、命令结果和先前对话。上下文管理决定哪些内容进入工作集、哪些留在外部，哪些陈述是观察或推断，以及何时必须更新旧条目。

工作集不等于仓库本身。它只是放进模型 上下文窗口（context window） 的临时视图；窗口容量有限，也不天然保证内容完整或新鲜。磁盘上的文件可能没有进入本次请求，而已经纳入的片段也可能来自旧版本。

这一区别解释了一种常见失败：智能体信心十足，局部推理也前后一致，却分析了错误的代码。它可能修改名字相近但没有启用的适配器，保留已经废弃的测试假设，或遗漏当前目录上层保存的项目规则。增加 token 数量并不能纠正选取边界错误。

有效上下文应提供足以选择下一步操作的证据，而不是收集以后也许会用到的所有事实。面对失败的结算测试，初始集合可以包含任务契约、适用指令、失败输出、测试和被测符号。数据库迁移、公共 API 改动或跨包重构需要更宽的集合，因为它们的 架构边界（architecture boundary） 和使用方也是正确性的一部分。

上下文需要在整个任务期间持续管理，不能只在开始时组装一次。搜索产生候选项，文件读取确认当前内容，执行增加观察结果，编辑使旧快照失效，新错误则指向另一项依赖。工作集应随证据变化而扩展和收缩。

上下文、记忆与仓库事实

对话历史属于 会话状态（conversation state） ，不是持久的仓库事实。它记录请求、选择和早先的观察，但模型可能概括它，宿主可能截断它，仓库也可能独立变化。可以用历史定位证据，随后仍要在来源处确认可变事实。

项目指令文件是一类特殊上下文。它可以定义命令、风格、目录级约束和必需的审查步骤。其作用域与优先级取决于智能体宿主的规则，而且它绝不能突破宿主策略，额外授予文件系统、网络或部署权限。

源码展示当前实现行为，测试展示被断言的行为，模式与规范展示预期契约，Issue 文本解释所请求的改动。它们没有一种永远高于其他来源。发生冲突时，应记录冲突，并依据任务负责人或仓库明文规定的权威关系解决，不能默默选择最方便修改的文件。

摘要是导航工具。它可以说明 src/tax.js 负责管辖区规则，并指向确切路径、符号和版本。如果下一步依赖某个精确条件、默认值、类型或错误消息，摘要就不能取代文件本身。

初始工作集应包含什么

先纳入同时约束范围和行为的证据：

1. 确切任务、验收条件、允许路径和明确的非目标。
2. 适用的仓库级与目录级指令。
3. 基线版本、工作目录、分支或 worktree，以及原有未提交文件。
4. 失败命令及其未经改写的输出，或另一项具体起始观察。
5. 与该观察直接相关的最小源码、测试、配置和契约集合。

凭据、依赖目录、构建产物、压缩 bundle、大型二进制 fixture 和无关日志通常应留在外部。排除这些内容既能节省容量，也能降低意外暴露秘密的风险。如果其中某项后来变得相关，应提取所需的狭窄事实，而不是整目录灌入。

初始集合只是对相关性的假设。它应当容易解释，也应当便于修改。把「这些就是相关文件」看成临时清单，不要承诺间接使用方一定不存在。

工作原理

上下文管理形成一个循环：锚定、选择、检查、操作、观察、更新。每轮都应留下足够的来源信息，以区分当前仓库事实与模型结论。下一轮复用稳定约束，同时重新取得因中间操作而失效的事实。

锚定任务与权威关系

广泛搜索前先写出任务契约。明确预期行为、复现方法、允许的改动范围、必需检查和非目标。这个锚点能防止一个看似可信的搜索结果，或 Issue 中嵌入的命令，悄悄重新定义任务。

按照宿主明文规定的规则，从仓库根目录向目标目录解析适用指令，并记录所用路径。如果两条指令冲突或作用域不清楚，应停止对应分支并暴露冲突，不能把它们混成一条新规则。

还要记录赋予路径和输出具体含义的环境。至少确认仓库根目录、当前版本、worktree 状态、包目录和声明的运行时。缺少目录与版本的测试结果证据很弱，因为同一命令可能运行另一个包或另一份源码。

根据具体信号选择

先使用精度高的信号：失败测试路径、堆栈帧、诊断位置、具名符号、变更路径或明确的 API 契约（API contract） 。搜索定义和引用，再检查导入、调用点、配置读取和相邻测试。只看文件名经常会遇到歧义。

所选集合应包含不同角色。指令说明约束，实现提供机制，测试给出示例与断言，配置选择运行时行为，命令输出报告观察到的状态。来自同一角色的十个片段，也无法弥补缺失的关键契约。

记录每个条目进入上下文的原因。「堆栈中出现 calculateTotal，因此匹配到它」比「看起来相关」更有用。有了原因，审查者才能质疑路径、替换弱匹配，并在假设不成立时删除该条目。

沿代码关系扩展

仓库内的代码关系比主题相似度更可靠。沿目标实际使用的导入模块、调用方、类型定义、路由注册、模式使用方或测试 fixture 前进。搜索要覆盖两个方向：目标依赖什么，以及什么依赖目标。

每次围绕一个问题扩展。如果税费断言失败，就读取足以判断问题属于算术、管辖区配置、舍入还是测试预期的内容。在提出这个问题前就加载所有结算文件，只会增加噪声，并不能保证覆盖完整。

当前决策获得足够支持后就停止扩展。局部编辑前，需要理解实现契约、相关调用方、边界情况和验证路径。公共接口改动的停止条件更宽，因为所有使用方和兼容性要求都很重要。

区分事实与推断

把仓库读取和命令结果标为观察，并记录来源与取得时点。把架构结论、疑似原因和修复方案标为推断。把用户要求与仓库规则标为约束。

证据冲突时，这种区分尤其重要。「格式化工具通过」是观察；「补丁正确」则是格式化工具无法支持的推断。「不存在调用方」只有在记录搜索范围与方式、并考虑动态查找后，才可能有充分支持。

可以用小型证据账本追踪这些差异：

在关键推理前更新

只要发生可能影响某个条目的变化，就要更新它。一次编辑会让早先的片段与符号摘要变得可疑；切换分支会使路径到内容的对应关系失效；安装依赖可能使构建输出失效；即使代码不变，新的用户约束也可能使计划失效。

打补丁前，重新读取目标以及补丁依赖的精确指令或契约。准备应用基于旧快照计算的补丁时，应比较当前文本或摘要值，不匹配就拒绝应用。摘要值只能检测差异，不能证明内容安全或正确。

打补丁后检查实际差异，不要依赖预期中的编辑。随后重新运行所有受代码、配置、依赖或环境变化影响的检查。旧的绿色输出只是历史证据，不是当前验收证据。

压缩时保留决策依据

长会话最终需要压缩。应保留确切验收条件、当前权限、适用指令、已改文件、未解决假设和原始工具输出的引用。这些细节会约束后续操作，一旦重建错误，代价很高。

可以更大幅度压缩已经走完的探索岔路。像「路由注册表选择 src/checkout.js，因此排除旧适配器」这样的短注释，保留了决定及其原因。一旦有可追溯来源保存了有效结论，重复搜索列表和已被取代的解释就可以移出工作集。

跨越多个包或把工作交给另一会话时， 决策日志（decision log） 很有帮助。它应记录决定、证据、被拒绝的替代方案和更新条件。它不能用流畅的措辞把不确定猜测写成既定事实。

示例

下面的 JavaScript 示例模拟智能体周围由宿主管理的记录逻辑；它们不调用模型，也不规定唯一的检索算法。每个文件都在本地使用 Node 24 执行，紧随其后的 text 代码块是实际输出。

构建小型上下文清单

第一个示例为候选项指定角色和明确优先级，排除生成的 bundle，并纳入四项内容。在真实仓库中，候选项来自搜索与依赖工具；这份可见清单让选择过程可以接受审查。

输出解释了每条纳入路径存在的原因。这里并没有把 README.md 判为无用；它只是排在更能约束当前决策的证据之后。dist/app.js 继续排除，因为应该找到并编辑它的来源。

数字优先级只是一种示例策略，不是判断相关性的预言机。生产选择器还应验证路径范围、指令优先级、文件大小、敏感性，以及候选项是否仍然存在。即使所有条目都由人选择，清单仍然有价值。

从具体线索扩展

下一个示例从失败测试开始沿依赖边前进。初始的一层视图会到达实现；后来出现税费行为线索，才有理由进一步遍历并纳入协作模块与管辖区配置。

const imports = new Map([
  ["tests/checkout.test.js", ["src/checkout.js"]],
  ["src/checkout.js", ["src/money.js", "src/tax.js"]],
  ["src/tax.js", ["config/jurisdictions.json"]],
]);

function expand(start, maxDepth) {
  const queue = [{ path: start, depth: 0 }];
  const seen = new Set();

  while (queue.length > 0) {
    const current = queue.shift();
    if (seen.has(current.path) || current.depth > maxDepth) continue;
    seen.add(current.path);
    for (const dependency of imports.get(current.path) ?? []) {
      queue.push({ path: dependency, depth: current.depth + 1 });
    }
  }

  return [...seen];
}

console.log("initial:", expand("tests/checkout.test.js", 1));
console.log("after tax clue:", expand("tests/checkout.test.js", 3));

initial: [ 'tests/checkout.test.js', 'src/checkout.js' ]
after tax clue: [
  'tests/checkout.test.js',
  'src/checkout.js',
  'src/money.js',
  'src/tax.js',
  'config/jurisdictions.json'
]

遍历过程带有已访问集合，因此遇到循环也不会无限运行。深度只是教学控制手段。真实扩展应沿能够回答当前问题的关系前进，还应根据语言机制检查反向引用、注册关系、生成映射和运行时配置。

真正重要的变化是扩展理由：出现了税费线索。没有这个线索，更长的列表只代表更多文字。有了它，新文件才能确认或否定一个具体假设。

拒绝过期快照

最后一个示例在 src/retry.js 进入上下文时记录简短的 SHA-256 摘要值。另一个参与者在编辑前修改了仓库映射。保护逻辑发现快照已经过期，并重新取得当前文本。

import { createHash } from "node:crypto";

const repository = new Map([
  ["src/retry.js", "export const retryLimit = 3;\n"],
]);

function digest(text) {
  return createHash("sha256").update(text).digest("hex").slice(0, 10);
}

function readSnapshot(path) {
  const text = repository.get(path);
  return { path, text, digest: digest(text) };
}

let context = readSnapshot("src/retry.js");
console.log(`selected ${context.path} @ ${context.digest}`);

repository.set("src/retry.js", "export const retryLimit = 5;\n");

const currentDigest = digest(repository.get(context.path));
if (currentDigest !== context.digest) {
  console.log(`stale ${context.digest} -> ${currentDigest}`);
  context = readSnapshot(context.path);
}

console.log(`ready ${context.path} @ ${context.digest}`);
console.log(context.text.trim());

selected src/retry.js @ bb31e24fcc
stale bb31e24fcc -> 4394708645
ready src/retry.js @ 4394708645
export const retryLimit = 5;

这个保护逻辑可以防止基于 retryLimit = 3 的编辑覆盖较新的值。生产补丁工具通常通过要求旧文本完全匹配或指定基线版本，获得同样的性质。如果前置条件失败，就重新读取并计算，不能强行把旧补丁套到新内容上。

十个字符的摘要值适合生成易读的演示输出，不适用于对抗性完整性检查或身份判断。需要抗碰撞能力时，应使用仓库版本标识符或完整且合适的摘要。无论采用哪一种方式，新鲜度都不同于正确性：当前文件仍然可能有缺陷。

陷阱

整个仓库全部装入

**修复：**定义默认排除项，从任务信号出发，并为每个纳入条目记录角色与原因。只有具体线索要求时才检查被忽略内容或生成内容，并尽可能选择它们的原始来源。

把检索结果当作当前事实

**修复：**用检索寻找候选项，再在编辑前重新读取权威文件。为计算得到的补丁附加版本、摘要值或精确文本前置条件；不匹配时更新推理。

只读取最显眼的目标

**修复：**双向搜索定义与引用。读取相关契约、调用方、测试和运行时选择点，再说明已经检查哪些关系、哪些动态关系仍然不确定。

把摘要变成证据

**修复：**区分约束、观察与推断。保留路径、符号、版本、命令、退出码和原始输出引用，并重新取得控制下一次编辑或完成声明的任何精确事实。

失效后仍复用证据

**修复：**把观察与环境及更新触发条件关联起来。发生相关编辑或环境变化后，检查当前差异，并从记录的目录重新运行受影响的检查，然后才能宣告任务完成。

延伸阅读

• OpenAI Codex 文档：AGENTS.md
• GitHub 文档：为 GitHub Copilot 添加仓库自定义指令
• Claude Code 文档：Claude 如何记住项目
• Git 文档：git status
• Git 文档：git diff