读一个 110 行的文件,送你一份 2.8 万字的说明书:给项目文档注入设上限

项目文档的注入要有上限,触发要看意图:超限时只推大纲和受管区,全文让 agent 按行号自己读;只读调用不再重发整份文件。
证据口径:机制来自该次落地的源码、设计文档与测试(9 个文件,+209 / −35,1 个分支提交;构建这次改动的任务跑了 30 个模型步、31 个工具结果)。出处写成 文件 或测试名,源码仓库不公开。标「推断」的是我的解读。
1. 问题:一份越写越长的契约⌗
这个 agent 系统里,每个项目根目录有一份 AGENTS.md,它是项目的契约。文件里有一段由工具维护的受管区(<!-- project-state:start --> 到 <!-- project-state:end -->),分「当前状态」「证据」「文档索引」三节,其中「当前状态」是项目现状的唯一真值。受管区之外是人写的稳定规则。
为了让 agent 始终按最新契约干活,系统有两条通道把这份文件送进上下文:
| 通道 | 何时触发 | 发什么(改动前) |
|---|---|---|
| 安全点注入 | 声明工作目录后的模型调用间隙,文件哈希变了就补发 | 每代首次发全文;之后发相对上次注入版本的 unified diff,diff 不比全文小就改发全文 |
工具结果里的 agents_md 字段 | read_file / file_edit / SSH 读写编辑碰到项目里的任意文件 | 本代首次碰到发全文;之后哈希一变就再发全文 |
文件短的时候,这两条都没问题。问题出在文件变长以后。设计文档里记着起因:系统自己仓库的根文档长到 11.8 万字符,agent 只读一个源码文件,工具结果里就带上了被截断到 2.8 万字符的整份文档。
拆开看,这里有两个错,而且是两个不同的错:
错 1:量没有上限
「全文」= 文件有多大就发多大 → 契约越完善,每次注入越贵
被全局截断后还丢掉了尾部(受管区通常在文件尾部)
错 2:触发不看意图
「哈希变了」→ 不管这次调用是读还是写,一律重发
而读的那个文件本身可能只有 110 行
第一个错让注入失控,第二个错让注入出现在最不该出现的地方:本来是一个读文件的工具调用,结果里 9 成是项目说明书,真正要读的那段源码反而被淹在里面。
2. 为什么「变了就整份重发」看起来合理⌗
这类设计的出发点不是蠢,是保守:agent 一旦在过时的规则下写代码,后果比多花几千 token 严重得多。所以每次都发全文、每次变化都告诉它,听起来是最安全的。
但这个安全有两个前提,它们在长文档上都不成立:
- 全文能完整送到。 实际上超长的工具结果会被全局截断。文件尾部的受管区恰恰是当前状态的真值,最先被截掉。
- 模型读得完全文。 上下文里塞了 2.8 万字,模型对每一段的注意力都被摊薄。关键的那条「当前状态」并不会因为全文都在就更醒目。
推断:大到被截断的全文,可靠性比不上一份完整的、带指针的大纲。前者是「每样都给了,但关键那段可能丢了」,后者是「只给了关键的,其余明确告诉你在哪」。
3. 改法一:8000 字符上限,超限发大纲⌗
新文件 src/project-docs/outline.ts 定义了一个常量和一个渲染函数:
export const PROJECT_DOCUMENT_INJECTION_CHARS = 8_000
export const fitsInjection = (text: string) => text.length <= PROJECT_DOCUMENT_INJECTION_CHARS
文档没超限时,行为和以前一样。超限时,「全文」换成 projectDocumentOutline 生成的大纲。它在 8000 字符的预算里按优先级往里装:
┌─ 头部:路径、全文字符数与行数、「超过上限,只给受管区与目录,
│ 需要某一节时用 read_file 按行号读(远端项目带 device 参数)」
│
├─ ① 受管区「当前状态」原文 ← 最先装,真值优先
│
├─ ② 预留:其余受管区节的「未附」占位行
│
├─ ③ 一级、二级标题目录,每条带行号 ← 逐条装,装不下就写
│ - L17 ## 某一节 「…另有 N 个标题未列出」
│ (代码块里的 # 不算标题)
│
└─ ④ 「证据」「文档索引」:放得下就附原文,放不下写成
## 证据(第 a–b 行,N 字符,未附)
几个细节值得说一下:
- 顺序就是优先级。 当前状态最先装,因为它是唯一真值。目录比证据先装,因为目录告诉 agent 去哪儿读,证据只是记录。
- 占位行先预留。 算目录预算时先扣掉其余受管区节占位行的长度(
reserveForOmissions),这样目录不会把预算吃光,导致连「证据在第几行」都写不下。 - 行号就是指针。
- L17 ## 某一节可以直接换算成read_file的offset。agent 要细节就自己去读,系统不替它猜需要哪一节。 - 基线不变。 注入事件的
sourceMeta.documentSnapshot仍然保存完整原文,所以下一次变化还是对着完整文件算 diff,不会对着大纲算。
增量部分的逻辑也跟着改了(src/project-docs/injection.ts):
const changes = parts.join('\n\n')
if (fitsInjection(raw)) return smallerDocumentBody(full, changes) // 小文档:老规则,谁小发谁
return fitsInjection(changes) ? changes : full // 大文档:diff 放得下发 diff,否则发大纲
| 文档 | 变化 | 发什么 |
|---|---|---|
| ≤ 8000 | 首次 / 新一代 | 全文 |
| ≤ 8000 | 有变化 | diff 和全文按 UTF-8 字节比,发小的 |
| > 8000 | 首次 / 新一代 | 大纲 |
| > 8000 | 小变化 | diff(只要 diff ≤ 8000) |
| > 8000 | 大改写 | 大纲 |
对应的测试:
a document over the limit is sent as managed region plus line outline with a read_file pointer:40 节的大文档,输出 ≤ 8000,包含路径、read_file、state A和- L<n> ## Section 17的准确行号,不含正文的重复句。a small change to a large document is still a diff; a change too large for the limit falls back to the outline:只改状态时输出里有+state B,没有「目录(行号)」;整篇改写后退回大纲,且仍 ≤ 8000。a managed region larger than the limit keeps the current state and points at the omitted sections:塞 200 条证据,当前状态保住,证据节变成## 证据(第 a–b 行,N 字符,未附)。runtime.test.ts里的端到端用例:首次注入是大纲,快照等于完整原文;改了状态后推送的是 diff,长度 < 2000。
4. 改法二:读不重发,写才重发⌗
第二个错改在 src/shared/agents-md-tracker.ts。所有文件工具调用都要标上自己是读还是写:
/** read = the call only looked at the project; write = it changed a file in it. */
export type ProjectAccess = 'read' | 'write'
function announce(sessionId, device, path, raw, access): boolean {
const hash = sha256(raw)
const seen = state(sessionId).get(key(device, path))
if (seen === hash) return false
state(sessionId).set(key(device, path), hash) // 无论读写,基线都前移
return seen === undefined || access === 'write' // 首次接触必发;之后只有写才发
}
调用方:read_file 传 'read',file_edit 传 'write';SSH 那边远端读传 'read',远端写和编辑传 'write'(src/runtime/remote-files.ts)。工具结果里的 agents_md 和安全点注入共用同一份大纲渲染,所以这条通道也受 8000 的上限约束。
测试 a read after the document changed stays quiet and only moves the baseline 把语义写得很清楚:
v1 写入磁盘 → read → 附 v1 (首次接触)
v2 写入磁盘 → read → null (只读,基线移到 v2)
→ write → null (v2 已见过)
v3 写入磁盘 → write → 附 v3 (写入,且有新变化)
为什么读要「静默前移基线」,而不是「什么都不做,等下次写再补」?设计文档给了分工:变化的增量同步由安全点注入负责,不在工具结果里重复。 工具结果这条通道的职责缩成两件事:首次接触时让 agent 知道这里有份契约;要动手写的时候,如果契约又变了,再提醒一次。推断:写入是违反契约代价最大的时刻,提醒放在这里性价比最高;读错了顶多再读一遍,写错了要回滚。
同一个变化以前可能出现两次,一次在安全点 diff 里,一次在下一个读调用的结果里以全文出现。现在只出现一次,而且是 diff 的形式。
5. 对比:两种思路⌗
| 「变了就整份塞」 | 有界 + 按意图 | |
|---|---|---|
| 单次注入成本 | 和文件大小成正比 | ≤ 8000 字符 |
| 当前状态是否保证送达 | 否,长文件会被截断,受管区在尾部 | 是,最先装 |
| 细节怎么拿 | 已经在上下文里,但可能被截掉 | 带行号的指针,read_file 自取 |
| 只读调用 | 每次变化都带一份全文 | 不附,只移动基线 |
| 写入调用 | 同上 | 有新变化才附 |
| 基线 / diff 正确性 | 对着上次注入的全文 | 对着快照里的完整原文,不受大纲影响 |
核心的转变是:注入不再假装替 agent 读完了文档,而是告诉它文档长什么样、真值是什么、其余在哪儿。 这和人类工程师用一份大型规范的方式一样:先看目录和现状,要细节再翻到那一页。没有人会在每次打开一个源文件时把整本规范重读一遍。
6. 还没解决的⌗
- 上限是常量,不是测出来的。 8000 的依据只有那次 11.8 万 / 2.8 万的事故,没有实验说明 6000 或 12000 更好。而且它按 JS 字符数计,小文档的「diff 还是全文」比较按 UTF-8 字节数计,两个口径不一样。8000 个中文字符大约是 24KB,比同字数的英文贵得多。
- 受管区外的规则变成了「可读」而不是「已读」。 大纲只给标题和行号,稳定规则的正文不再自动出现。agent 会不会在需要时真的去读那一节,取决于模型自觉,这次改动没有任何机制保证这一点。
- 只读路径上的变化可能没人推。 读会静默前移基线,增量交给安全点注入。可安全点注入只对声明过(或因写入自动加入)的工作目录生效。如果 agent 只是读一个没声明为工作目录的项目,文档中途变了,它要等到下一次写才可能看到,而那次写也会因为基线已经前移而不提醒。这是我从代码推出来的空档,没有对应的测试。
- 测试的松紧不一样。 单元测试断言 ≤ 8000,
runtime.test.ts的端到端用例放宽到 8000 + 200,因为运行时外面还包了一层文案。所以「8000 上限」严格来说是正文的上限,不是整条事件的上限。
文档总会越写越长,契约越完善越长。注入策略不能因为契约写得认真就惩罚它。