拿不出原文就不算数:把查资料整个移出主 agent 的上下文

一次工具面改动:主 agent 不再亲自搜索、亲自读网页。它提一个事实问题,拿回几条带出处的结论。搜索、抓取、抽取都在一个便宜模型的循环里做完,而那个循环交的每条结论都要过一道字符串匹配。
1. 主模型亲自查资料,贵在哪里⌗
agent 查资料的常见做法是给主模型两个工具:search 和 fetch。主模型搜一下,挑几个 URL 抓下来读,再自己总结。看着很自然,算一笔账就不对了:
| 进入主上下文的东西 | 体积 | 之后还有用吗 |
|---|---|---|
| 每次搜索的标题 + URL + 摘要 | 每次几百到上千 token | 基本没用,只是用来找页面 |
| 每个抓下来的网页正文 | 动辄上万 token | 真正有用的通常就一两段 |
| 读完没用、换个关键词再搜的那几轮 | 叠加 | 完全没用 |
| 最后的结论 | 几十 token | 有用 |
主模型是整个系统里最贵的那个,它的上下文也最值钱:后面的每一步推理都要带着它。用最贵的上下文去装一堆用完就该扔的网页正文,等于用工作台堆废纸。这些东西还不会自己走:之后每个回合都在重复付这些 token 的钱,等压缩把它们清掉为止。
第二个问题不是钱,是出处。主模型读完网页写「据某官方文档……」,这句话是它说的,没有任何东西去核对文档里到底有没有这句。上下文一长,模型把 A 页的数字安到 B 页头上、把搜索摘要里的半句话当成正文引用,都不稀奇。
2. 改成什么样⌗
这次改动把两件事一起解决:查资料搬到一个独立的子循环里做,子循环交出来的结论要过框架的逐字核对。
主 agent
│ web_research({ question: "一个可查证的事实问题" })
▼
┌──────────────────── 研究子循环(廉价模型)────────────────────┐
│ 只有两个工具:search(找页面) fetch(抓正文 + 抽取原文段落)│
│ │
│ 搜索结果、网页全文、抽取段落、模型自己的来回 ── 全留在这里 │
│ │
│ 最终答案(JSON): │
│ facts[]: statement / website / sourceType / │
│ evidence[{ page: "p3", excerpt: "原文" }] │
│ missing, links │
└───────────────┬───────────────────────────────────────────────┘
│ 框架核对:excerpt 是不是 page 正文里的连续子串?
▼
主 agent 收到:
- 结论一(来源站点;来源类型)
- 结论二(……)
没查到的部分,一句话
id: 3f9a1c0b7e42
工具面也跟着改:web_research 变成常驻工具,所有角色(主对话、侧聊、后台任务、维护者……)的工具表里,原来的 maxclaw_web_search 和 web_fetch 都换成了它。两个原语没有删,挪进 web-search skill 变成 deferred,激活之后才出现,留给确实要看原始结果的场合,比如调试抓取链路本身。skill-residency.test.ts 把这一条钉死了:
test('web research is resident; raw search and fetch activate together through web-search', async () => {
const direct = await buildMaxClawDirectToolRegistry(registry, { skills: loader.getAll() })
expect(direct.get('web_research')).toBeDefined()
for (const name of ['maxclaw_web_search', 'web_fetch']) {
expect(direct.get(name)).toBeUndefined()
}
await direct.execute('activate_skill', { skills: ['web-search'] })
expect(direct.get('maxclaw_web_search')).toBeDefined()
expect(direct.get('web_fetch')).toBeDefined()
})
把原语从常驻表里拿掉是关键的一步。原语还留在手边,主模型就会顺手自己搜,隔离也就形同虚设。
3. 核对规则:一个子串判断⌗
整套设计的承重墙就这么几行(src/runtime/web-research.ts):
export function factHasEvidence(fact: Fact, pages: readonly ResearchPage[]): boolean {
return [fact.statement, fact.website, fact.sourceType ?? ''].every(presentationValid)
&& fact.evidence.every(evidence => {
const body = pages.find(page => page.id === evidence.page)?.body
const excerpt = normalizeResearchWhitespace(evidence.excerpt)
return body !== undefined && excerpt.length > 0
&& normalizeResearchWhitespace(body).includes(excerpt)
})
}
拆开说:
- 页面必须是抓过的。
page是 fetch 时框架分配的 id(p1、p2……),对应的正文在抽取模型看到之前就整份存下。模型编不出一个存在的页面,也没法拿搜索摘要充数:摘要从来不进pages。 - 原文必须是连续子串。 只把连续空白压成一个空格,别的一律不放宽。改写不行,
40.0写成40不行,用省略号拼两段也不行。 - 每条证据都要过。 一条结论挂了三段证据,其中一段是编的,整条不过。
- 结论字段不许夹带原文。
statement/website/sourceType里出现 URL、引用块、代码块或临时文件路径,同样判不过。这条是为了守住「主上下文里没有原文」的承诺,防模型把正文塞进结论字段。
测试里的几个反例就是规格:
expect(factHasEvidence(fact('The score\n increased from 40.0 to 55.0 percent.'), pages)).toBeTrue() // 空白差异:过
expect(factHasEvidence(fact('The score increased from 40 to 55 percent.'), pages)).toBeFalse() // 数字改写:不过
expect(factHasEvidence(fact('40.0 ... 55.0'), pages)).toBeFalse() // 省略号拼接:不过
expect(factHasEvidence(fact(''), pages)).toBeFalse() // 空证据:不过
这道检查证明的是出处,不是推理。 文档写得很直白:子串匹配不保证结论真的从那段话推得出来,怎么理解原文、挑哪个一手来源、冲突怎么判,仍然是研究模型的事。它能保证的是:结论引用的那段话确实存在,确实出自它声称的那个页面。凭空编出处、张冠李戴这一大类错误,在这一步被机械地挡掉;剩下的才需要信任模型。
4. 不过怎么办:在循环里改,改不了就删⌗
核对失败不是直接报错,而是借 CanoLoop 的 reviewFinalMessage 把问题退回子循环本身:
最终答案
├─ JSON 解析失败 / 字段不对 ──→ 退回改(最多 2 次)
│ 仍不对 → 明确失败 + 保留 id,可续
└─ 结构合法,证据核对
├─ 全过 ─────────────────→ 放行
└─ 有不过的 ─→ 退回一次:"补真原文、再去抓,或者删掉这条"
└─ 第二次仍不过的条目 → 直接丢弃,
并在输出里写「部分结论没有可核对的出处,未予返回。」
几处设计选择:
| 选择 | 理由 |
|---|---|
| 格式修正和证据修正各算各的次数 | 测试 format corrections and provenance corrections do not consume each other:一次 JSON 写坏不该吃掉核对出处的机会 |
| 证据只给一次修正 | 模型手里有正文,补得出原文早就补了;再给机会多半是换个说法继续编 |
| 不过的条目丢掉,不是整份作废 | 测试 uncorrectable facts are discarded while supported facts survive:一真一假,真的那条照常返回,discardedFacts 记 1 |
| 丢了要明说 | 主 agent 知道「有东西被删了」,不会把残缺的结果当完整的 |
| 工具参数错在执行前拦下 | count: "5" 这种不会真去调搜索,而是作为工具结果告诉模型哪个字段该是什么类型,改对了再执行 |
| 格式最终失败时不吐原始输出 | 返回的是可读的字段说明 + id,不是 Zod 异常,更不是模型原文 |
最后一条容易被忽视。一个「失败时把模型原文兜底返回」的实现,会让隔离在最需要它的时候破功:原始输出恰恰是最可能夹带大段网页文本的东西。
5. 主 agent 到底拿到什么⌗
返回值是框架渲染出来的,模型输出不会整段透传:
const lines = answer.facts.map(fact => `- ${fact.statement}(${fact.website}${fact.sourceType ? `;${fact.sourceType}` : ''})`)
if (answer.missing) lines.push(answer.missing)
if (metrics.discardedFacts) lines.push('部分结论没有可核对的出处,未予返回。')
// ……
lines.push(`id: ${id}`)
也就是:每条结论一行,后面括号注明来源网站和类型(官方文档 / 新闻 / 个人博客 / 社交媒体);查不到的一句话;最后一行是研究 id。**没有 URL,没有原文引用,没有全文路径。**测试 corrects a failed excerpt inside the same CanoLoop, never exposes evidence 逐项断言输出里不含 https://、/tmp/、原文片段和页面 id p1。
那主 agent 想核实怎么办?工具描述里给的答案是:不要自己去抓。这是整个设计最反直觉的地方,也是它成立的前提。核对已经由框架做过了;主模型再去抓一遍,省下的上下文又全花回去。不够就带 id 追问,追问在同一个子循环里接着做。
链接是唯一的例外,而且是被刻意设计得很窄的例外:
- 只有带 id 的追问、且问题里明确要「链接 / 网址 / 地址 / link / url」才会输出 URL;
- 子循环里的模型只能交 page id,URL 由框架从存下的抓取记录里查出来;
- 模型交了一个没抓过的 id,直接被忽略。
expect(await f.run('给我第一条结论的来源链接', id)).toBe(`https://example.org/doc\nid: ${id}`)
// 模型交的 links 是 ['p1', 'not-fetched'],只有 p1 变成了 URL
所以返回的链接不可能是模型生成的 URL。在 agent 系统里,编造链接大概是最常见、也最容易被人当场戳穿的幻觉之一。这里没去训练模型别编,而是让它根本没有地方写 URL。
6. 子循环为什么要「常驻」⌗
「常驻」有两层意思:工具常驻在主 agent 手边,研究状态在库里一直留着。
研究状态存在 PG 的 web_research_sessions 里:冻结的系统提示、选中的 provider、完整对话、每个抓过页面的全文。几个性质:
| 性质 | 实现 | 好处 |
|---|---|---|
| 追问延续全部上下文 | 带 id 调用时从库里恢复 messages 和 pages | 第二问不用重搜重抓;测试断言追问时 fetch 总共只被调了 1 次 |
| 重启不丢 | 每个模型 / 工具边界走 persistSuffix 先写库;正文在抽取前就落盘 | 进程重启、调用方上下文换代之后照样能续 |
| 归属发起线程 | load 带 thread_id 过滤;后台任务的研究归任务自己的线程,不归派它的人 | 别的线程拿着 id 也读不到,测试里换个 threadId 直接 Unknown |
| 不设过期 | 没有 TTL;外键 ON DELETE CASCADE 跟着线程走 | 线程活着研究就在,线程删了研究和计量记录一起没 |
| 多问可指代 | 每个问题按时间编号 (a)、(b)…… | 第三次追问说「(a) 那条结论的链接」,不会被理解成最近那条 |
最后一条是个小细节,但很说明问题:一个会话里可能问了五个问题,「给我那条的链接」里的「那条」指哪个,靠「最近一次回答」去猜是会猜错的。
7. 便宜模型怎么选:只在「坏了」时升级⌗
子循环用的是调色盘里的 free → light → mid 三档。升级规则写得很克制:
请求报错 / provider 不可用 / 返回空或非文本 → 换下一档
诚实地回答「没找到」 → 不换,就此结束
三档都挂了 → 明确失败,列出每档的错误
测试 no quality-based escalation: an honest no-evidence answer stops on free 专门保证第二行:模型说找不到,模型调用次数就是 1。
为什么不在「答得不好」时升级?因为「不好」没有可靠的判据;拿「没找到」当升级信号,会让每个确实查不到的问题都跑满三档,还会奖励更会编的模型。在这套设计里,「查不到」是一个合法的、有价值的答案,出处核对就是为了让模型敢这么说。
另外两点:选中能用的 provider 之后,后续步骤和追问都留在它上面,不每步重选;没有搜索轮数或步数上限,由模型自己决定何时停,调用方的 abort 信号负责兜底取消。
8. 计量:记下来的是什么,没说的是什么⌗
每次调用(包括失败的)往 web_research_calls 写一行:问题、是否追问、用过的 provider、模型调用次数、输入 / 输出 token、新抓页面数、返回给调用方的字符数、被核对丢掉的结论数、错误。抽取模型的消耗也算在同一行里,测试 extractor usage is included 断言研究模型和抽取模型的 token 合计到了一起(3 次调用,输入 30、输出 9)。
returnedChars 和 discardedFacts 是这个设计特有的两个数:前者衡量主上下文实际付出的代价,后者衡量核对挡掉了多少东西。
文档对计量的边界说得很老实:这些记录衡量的是子循环的内部成本和最终交付的体积,不声称能还原「如果让主 agent 自己查要花多少 token」的反事实。省了多少,只能拿这两组数去对比,不能直接读出来。
9. 和常见做法的对照⌗
| 主模型直接 search + fetch | 子 agent 自由总结 | web_research | |
|---|---|---|---|
| 网页正文进主上下文 | 进 | 不进 | 不进 |
| 谁付检索的 token | 最贵的模型 | 子 agent 的模型 | 廉价模型 |
| 出处可信度 | 靠主模型自觉 | 靠子 agent 自觉 | 框架逐字核对 |
| 编造 URL | 可能 | 可能 | 模型无处写 URL |
| 追问 | 主模型自己记 | 通常重来一遍 | 同 id 续上,页面不重抓 |
| 失败时 | 主上下文里一地碎片 | 一段说不清的总结 | 明确失败 + 可续的 id |
中间那一列值得单独说一句:「派一个子 agent 去查」这件事本身不新鲜,很多系统都这么做。差别在于子 agent 交回来的东西主模型能不能直接用。一个自由总结的子 agent 省了上下文,却把「它说的对不对」这个问题原样交还给主模型;主模型想放心,只能自己再抓一遍。这次的改动加的就是那道机械核对:子循环交的每条结论都附了可检验的原文,框架替主模型检验过了,主模型才可以真的不看。
10. 代价与没解决的⌗
- 信任转移到了便宜模型的理解力上。 出处是真的,不代表结论是从出处正确推出来的。一段原文被断章取义,子串匹配照样通过。这是有意接受的取舍:机械核对挡住伪造出处,语义判断留给模型。
- 核对只认字面。 页面正文要是换了排版(例如表格被拆成多行),模型就得逐字照抄原文,换个说法就过不了核对。宁可漏掉,不可编造,代价是偶尔会把真结论也丢掉,丢了会明说。
- 「要链接」靠一个正则判断。 中英文几个关键词,够用,但不精致。
- 研究状态不过期。 页面全文全量入库,靠线程删除级联回收;长寿线程里研究多了,表会长大。
这几条都写在设计里,不是事后发现的。对一个查资料的工具来说,它把最常见的两类问题:上下文被网页撑爆、出处张口就来,变成了一个子串判断和一个工具表调整,这笔交易我觉得划算。