让 agent 在正文里写路径就能交文件,收尾检查点得先分清哪些路径只是顺口一提、哪些是真要交的,还得允许交付失败成为一个结局。

1. 一个看起来很顺手的设计⌗

MaxClaw 给用户交文件只有一种方式:agent 在正文里按 markdown 写出路径。

截图在这:![现场](/tmp/shot.png)
报告给你:[报告](~/out/report.pdf)
远端那份:[日志](build-box:/srv/out/run.log)

没有 attach 工具,也没有 send_file。回合收尾时框架在正文里找路径,取文件、上传,附件落在路径写的那个位置。好处很实在:模型本来就会写 markdown,交付和叙述放在同一段文字里,读者在哪儿读到「给你」,就在哪儿看到文件。

检查点挂在 prepareFinalReview 上(src/runtime/direct-loop-host.ts),时机是模型给出最终回复、不再调用工具的那一刻,ui-verification、detached-launch、push-preview 这几道收尾检查也在这里。每次模型调用结束,它产出的文字都记进 BodyReferenceDelivery;最终回复一到,就把本回合文字里没交付过的路径逐个交付。有一处失败,框架就追加一条 attachment-delivery-nudge 事件,把这条回复退回去,回合继续。

改动前,这套设计有两个前提没写出来:

  1. 正文里出现的每个文件链接,都是要交出去的文件;
  2. 交不出去,就是路径写错了,让 agent 改对就行。

这两条都不成立。

2. 第一个错:把「提到」当成「要交」⌗

一个回合里,agent 写的不只是最终回复。调用工具之前它通常会先说一句在做什么:

[调用前的叙述]  先看下构建日志 [日志](/var/log/build.log),再查配置。
  → read_file ...
  → shell ...
[最终回复]      查完了,配置没问题。

第一行的 [日志](...) 是什么意思?agent 是在告诉人它要去看哪份文件,并没有要把这份日志交出去。可旧实现用 fileReferencesOf 扫遍本回合每一段文字,凡是文件链接就交付。结果分两种:

情况旧行为实际效果
被提到的文件存在取文件、上传、登记用户收到一个没人要的附件,大文件还要先在 NAS 上建分享
被提到的文件不存在(agent 正要去创建,或者只是举个例子)判为失败,退回一句对的回复被打回去,叫 agent「改成正确路径」

第二种更麻烦。agent 收到退回消息,只能改写或删掉中间那句叙述里的链接,可那句话本来没错。

2.1 怎么区分:看写的是什么形式、写在哪一段⌗

靠语义去猜「这里是不是想交付」不可靠,所以这次用了两条机械规则,实现是 src/shared/attachment-ref.ts 里的 deliveryRequestsOf,九行:

/** An image is shown wherever it is written; any other file is handed over only from the reply that ends the turn — elsewhere its link is a mention. */
export function deliveryRequestsOf(text: string, finalReply: boolean): string[] {
  const refs: string[] = []
  for (const piece of splitAttachmentRefs(text)) {
    if (piece.kind !== 'attachment' || refs.includes(piece.ref) || fileReferenceOf(piece.ref) === null) continue
    if (piece.image || finalReply) refs.push(piece.ref)
  }
  return refs
}
写法中间叙述里最终回复里
![说明](路径)(图片语法)交付交付
[名字](路径)(普通链接)提及:不取文件、不登记、不分享、不算失败交付

图片为什么写在哪儿都交付?! 这个语法本身就表示「把它显示出来」,没有人会用图片语法去「提一句」某张图。所以图片按语法判断,跟扩展名无关;写成 ![x](/a.pdf) 也会按要交付处理,因为写的人选了「显示」这个意思。普通链接有两种用法,既可以是「给你」,也可以是「我在看这个」,只能靠位置区分:最终回复是给读者的结论,中间叙述是过程。

「是不是最终回复」也不用另外判断,接线只改了一处:

bodyDelivery.noteText(result.content, !result.toolCalls?.length)

这次模型调用没带工具调用,它的正文就是最终回复。这个判定和收尾检查点用的是同一个,所以两边不会出现分歧。

2.2 界面上也要能看出是「提及」⌗

只改服务端还不够。WebUI 原来的逻辑是:正文里的引用在 bodyAttachments 里找不到对应附件,就显示一个「(不可用)」小条。提及本来就不会交付,照这个逻辑,每条提及都会被画成坏掉的附件。

PlacedAttachment 现在多了一个 image 参数,从 markdown 语法一路传过来:

if (!image && fileReferenceOf(attachmentRef)) return <span title={attachmentRef}>{name}</span>

没交付的普通文件链接只显示名字,鼠标悬停能看到路径。没交付的图片还是显示「(不可用)」,因为图片写出来就是要给人看的,看不到就是出了问题。测试把两种情况写得很直接:

expect(placed('/var/log/run.log', false)).toBe('<span title="/var/log/run.log">名字</span>')
expect(placed('/tmp/shot.png', true)).toContain('(不可用)')

3. 第二个错:失败只有一种⌗

另一个前提是「交不出去就是路径错了」。

可交付要经过一串环节:路径解析、stat、在 Tool Host 上读文件、ssh 到远端取字节、往 NAS 上建分享、上传。这些环节都可能出错,但出错的原因分成两类,处理方式完全不同:

类别例子agent 改回复能不能修好
引用本身有问题文件不存在、不是普通文件、空文件、超过 inline 上限、机器名不合法、没有文件名能:改路径、先生成文件,或者把它改成行内代码
环境出了故障NAS 不可达、ssh 连不上、Tool Host 离线、传输出错、预演模式拒绝不能:路径是对的,换个写法还是同一个结果

旧实现把这两类混在一起处理,退回消息只有一种措辞(「路径写错了就改成正确路径……」),也没有次数上限。碰上环境故障,agent 能做的只有几种,没有一种是好的:

                  环境故障,退回
                       │
      ┌────────────────┼───────────────────┐
      ▼                ▼                   ▼
 原样再交一次      删掉这个链接         换一条路径瞎试
      │                │                   │
 再次失败,再退回   回合结束,看上去       可能交出一个
 (没有上限)      一切正常 ← 假成功       不对的文件 ← 误发

中间那条最危险。agent 被一再要求「修正引用」,最省事的修正就是把引用删掉。回复通过检查,回合正常结束,可文件根本没送到,用户也不知道有过一个文件。收尾检查点本来是用来保证交付的,结果反而把失败掩盖了。

3.1 失败要分类,分类看异常类型⌗

这次给每一处要交付的引用都定了结局:要么交付成功,要么失败并附上原因。ReferenceFailure 多了一个字段:

/** reference = the path / file is wrong and a corrected reply can fix it; environment = the file could not be fetched or handed over (machine, NAS, transfer). */
export type ReferenceFailureCause = 'reference' | 'environment'

分类不去匹配错误消息的文字,而是看抛出的是哪种异常。凡是「引用本身有问题」的地方,都改为抛专门的类型:

export function failureCauseOf(error: unknown): ReferenceFailureCause {
  if (error instanceof ReferenceFault || error instanceof RemoteFileUnfit) return 'reference'
  if (error instanceof FileXferError && error.code === 'not-found') return 'reference'
  return 'environment'
}
  • ReferenceFault(src/channels/attachment-delivery.ts):不是文件引用、没有文件名、Tool Host 上没有这个文件或不是普通文件、空文件、超过 inline 上限;
  • RemoteFileUnfit(src/runtime/remote-files.ts):ssh 机器名不合法、远端不是普通文件、远端文件超过上限;
  • FileXferError 里 code === 'not-found' 的那一种。

其他情况一律算环境故障。 默认值选哪边是这次的关键取舍。如果把没见过的错误默认归为「引用错了」,又会回到原来的问题:叫 agent 去改一个本来没错的路径。默认归为「环境」,最坏的结果是 agent 把一个其实能修好的问题如实报告成「没交付成功」,这只是不够理想,不会造成假成功或误发。

3.2 环境故障:记一次失败,退回一次,本回合不再试⌗

两类失败在 BodyReferenceDelivery 里的走向不同:

for (const failure of failures) if (failure.cause === 'environment') this.undelivered.set(failure.target, failure)
const wrong = new Set(failures.filter(f => f.cause === 'reference').map(f => f.target))
if (wrong.size > 0) this.segments = this.segments.filter(segment => !requestsOf(segment).some(target => wrong.has(target)))
  • 引用错误:含有这处引用的文字段退出后续检查,因为已经报告过,只有新的回复才能改正。仍然没有次数上限,每一次改写都是 agent 新做的决定,可能真改对了。

  • 环境故障:这个路径进入 undelivered。每次交付之前先过滤:

    .filter(target => !this.delivered.has(target) && !this.undelivered.has(target))
    

    同一回合里之后的回复再引用这个路径,不会重新去取,也不会再被判失败。所以每处环境故障最多只退回一次。

undelivered 只存在于这一个回合。之后的回合再引用同一路径,会重新交付一次,这就是重试的入口。故障可能是暂时的,过几分钟网络恢复了,下一轮自然能交上去,但不在同一个回合里反复撞。

测试原样写出了这个约定:NAS 第一次就超时;agent 第二次回复如实说明「没能发出去」,同时又带上了那个链接;结果没有新的失败,createShare 一共只调用了一次,附件列表为空:

delivery.noteText('报告:[报告](box:/srv/out/report.pdf)', true)
expect(failures).toEqual([{ target: 'box:/srv/out/report.pdf', reason: 'NAS 不可达: connect ETIMEDOUT', cause: 'environment' }])
delivery.noteText('报告没能发出去:NAS 不可达。[报告](box:/srv/out/report.pdf)', true)
expect(await delivery.deliver({})).toEqual([])
expect(attempts).toBe(1)

另一条测试把两类故障放进同一条回复:一台 Tool Host 不在线(环境),另一台机器上文件不存在(引用),断言两者各归各类。

3.3 退回消息也分两部分⌗

只退回一次,是为了让 agent 有机会把失败告诉用户,而不是去修路径。所以退回消息按类别分开写:

你这个回合的正文里有 2 处文件引用没能交付给 Max(回合结束时框架按路径取文件并上传):
引用本身有问题:
- `/tmp/a.png`:本机文件不存在: /tmp/a.png
逐个处理:路径写错了就改成正确路径;文件还没生成就先生成;……
交付失败(取文件或上传时出错,不是路径写法的问题,本回合不再重试):
- `box:/x.pdf`:ssh 失败
在回复里如实告诉 Max 哪些文件交付失败、原因是什么;之后的回复里再次引用同一路径会重新交付。
请重新回复。已经交付成功的引用不用重复。

还有一条测试专门检查:如果只有环境故障,退回消息里不会出现「改成正确路径」。告诉 agent 去改一个没写错的路径,就等于在引导它删掉链接,然后假装交付成功。

4. 合起来看:收尾检查点现在有四种结局⌗

最终回复到来
     │
     ▼
deliveryRequestsOf(每段文字, 是否最终回复)
     │
     ├─ 中间叙述里的普通链接 ──────────────▶ 提及:不碰文件,UI 显示名字
     │
     ▼ 要求交付、且本回合没交付过、没记过失败的路径(并行)
deliverFileReference
     │
     ├─ 成功 ─────────────────────────────▶ 已交付:写进 bodyAttachments
     ├─ ReferenceFault / RemoteFileUnfit
     │  / not-found ──────────────────────▶ 引用错误:退回改正(不限次)
     └─ 其他 ─────────────────────────────▶ 交付失败:记入 undelivered,
                                             退回一次,让 agent 如实说明
结局回合会不会结束用户看到什么
提及不受影响一个名字,悬停显示路径
已交付结束图片或文件 badge
引用错误退回,等 agent 改正改正后的回复
交付失败退回一次,第二次回复就能结束agent 写出的「X 没交付成功,原因是 Y」

改动前,检查点遇到交不出去的文件只能二选一:一直退回,直到 agent 删掉链接(假成功);或者 agent 换路径硬交(可能误发)。现在多了「交付失败」这个结局,这件事可以诚实地结束。

5. 为什么不选更省事的做法⌗

几种常见的替代方案,以及它们分别在哪儿出问题:

方案问题
加一个显式的 attach(path) 工具交付和叙述又分开了,附件不再落在说「给你」的那个位置;而且模型照样会在正文里写路径,那些路径又该怎么算
用小模型判断每个链接「是不是想交付」收尾路径上多了一次不确定的调用;同一段文字可能这次判交付、下次判提及,测试也写不成断言
失败一律退回、设一个次数上限上限到了怎么办?放行就是假成功,不放行就卡死。上限只是把这个二选一往后推,问题还在
环境故障时静默跳过用户永远不知道少了一个文件
环境故障时在框架里自动重试回合会被一次长超时拖住;同一回合里连续撞同一个故障,第二次大概率还是一样的结果

这次的做法对应地有三点:

  1. 「要不要交付」由写法和位置决定,不靠猜意图。 普通链接只有写在最终回复里才算要求交付,这条规则 agent 自己能预测,测试也能写成断言。
  2. 按异常类型分类,未知情况默认归为环境故障。 分错的代价是一次如实的失败报告,而不是假成功。
  3. 失败可以作为回合的结局。 框架只负责把失败送到 agent 那里,告诉用户的话由 agent 自己写。重试放到下一个回合,那时情况可能已经变了。

6. 还没解决的部分⌗

这次改动之后,下面这些问题依然存在:

  • 最终回复里的「提及」还是会被交付。 如果 agent 在最终回复里写「我参考了 配置」,这个文件会被交出去。规则只按位置判断,最终回复里的普通链接一律算要求交付。退路是退回消息里那句提示:「不是要交给 Max 的文件……就改成行内代码」,前提是这个文件交付失败了;如果交付成功,就是多交了一个文件。这个代价是规则可预测换来的。
  • 引用错误仍然不限次退回。 理论上 agent 可能每次都换一个错的路径。之所以没设上限,是因为每次重写都是一次新的、可能正确的决定;一旦设了上限,又会回到「上限到了放不放行」这个问题。
  • 跨回合的重试要靠 agent 主动再写一次路径。 框架不会在下个回合自动补交。这是有意的:上一回合的失败已经如实告诉用户了,要不要重交由这次对话的走向决定。

改动规模:14 个文件,+202 / −56,其中 4 个是测试文件,新增或改写的用例覆盖了上面每一种结局:提及不碰文件、最终回复里的同一链接会交付、环境故障本回合只试一次、Tool Host 离线和文件缺失分属两类、只有环境故障时退回消息不要求改路径,以及 UI 上提及显示名字、图片显示「(不可用)」。