项目文档的注入要有上限,触发要看意图:超限时只推大纲和受管区,全文让 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 严重得多。所以每次都发全文、每次变化都告诉它,听起来是最安全的。

但这个安全有两个前提,它们在长文档上都不成立:

  1. 全文能完整送到。 实际上超长的工具结果会被全局截断。文件尾部的受管区恰恰是当前状态的真值,最先被截掉。
  2. 模型读得完全文。 上下文里塞了 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 上限」严格来说是正文的上限,不是整条事件的上限。

文档总会越写越长,契约越完善越长。注入策略不能因为契约写得认真就惩罚它。