一次工具面改动:主 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. 代价与没解决的⌗

  • 信任转移到了便宜模型的理解力上。 出处是真的,不代表结论是从出处正确推出来的。一段原文被断章取义,子串匹配照样通过。这是有意接受的取舍:机械核对挡住伪造出处,语义判断留给模型。
  • 核对只认字面。 页面正文要是换了排版(例如表格被拆成多行),模型就得逐字照抄原文,换个说法就过不了核对。宁可漏掉,不可编造,代价是偶尔会把真结论也丢掉,丢了会明说。
  • 「要链接」靠一个正则判断。 中英文几个关键词,够用,但不精致。
  • 研究状态不过期。 页面全文全量入库,靠线程删除级联回收;长寿线程里研究多了,表会长大。

这几条都写在设计里,不是事后发现的。对一个查资料的工具来说,它把最常见的两类问题:上下文被网页撑爆、出处张口就来,变成了一个子串判断和一个工具表调整,这笔交易我觉得划算。