提到一个路径,不等于要把文件交出去

让 agent 在正文里写路径就能交文件,收尾检查点得先分清哪些路径只是顺口一提、哪些是真要交的,还得允许交付失败成为一个结局。
1. 一个看起来很顺手的设计⌗
MaxClaw 给用户交文件只有一种方式:agent 在正文里按 markdown 写出路径。
截图在这:
报告给你:[报告](~/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 事件,把这条回复退回去,回合继续。
改动前,这套设计有两个前提没写出来:
- 正文里出现的每个文件链接,都是要交出去的文件;
- 交不出去,就是路径写错了,让 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
}
| 写法 | 中间叙述里 | 最终回复里 |
|---|---|---|
(图片语法) | 交付 | 交付 |
[名字](路径)(普通链接) | 提及:不取文件、不登记、不分享、不算失败 | 交付 |
图片为什么写在哪儿都交付?! 这个语法本身就表示「把它显示出来」,没有人会用图片语法去「提一句」某张图。所以图片按语法判断,跟扩展名无关;写成  也会按要交付处理,因为写的人选了「显示」这个意思。普通链接有两种用法,既可以是「给你」,也可以是「我在看这个」,只能靠位置区分:最终回复是给读者的结论,中间叙述是过程。
「是不是最终回复」也不用另外判断,接线只改了一处:
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) 工具 | 交付和叙述又分开了,附件不再落在说「给你」的那个位置;而且模型照样会在正文里写路径,那些路径又该怎么算 |
| 用小模型判断每个链接「是不是想交付」 | 收尾路径上多了一次不确定的调用;同一段文字可能这次判交付、下次判提及,测试也写不成断言 |
| 失败一律退回、设一个次数上限 | 上限到了怎么办?放行就是假成功,不放行就卡死。上限只是把这个二选一往后推,问题还在 |
| 环境故障时静默跳过 | 用户永远不知道少了一个文件 |
| 环境故障时在框架里自动重试 | 回合会被一次长超时拖住;同一回合里连续撞同一个故障,第二次大概率还是一样的结果 |
这次的做法对应地有三点:
- 「要不要交付」由写法和位置决定,不靠猜意图。 普通链接只有写在最终回复里才算要求交付,这条规则 agent 自己能预测,测试也能写成断言。
- 按异常类型分类,未知情况默认归为环境故障。 分错的代价是一次如实的失败报告,而不是假成功。
- 失败可以作为回合的结局。 框架只负责把失败送到 agent 那里,告诉用户的话由 agent 自己写。重试放到下一个回合,那时情况可能已经变了。
6. 还没解决的部分⌗
这次改动之后,下面这些问题依然存在:
- 最终回复里的「提及」还是会被交付。 如果 agent 在最终回复里写「我参考了 配置」,这个文件会被交出去。规则只按位置判断,最终回复里的普通链接一律算要求交付。退路是退回消息里那句提示:「不是要交给 Max 的文件……就改成行内代码」,前提是这个文件交付失败了;如果交付成功,就是多交了一个文件。这个代价是规则可预测换来的。
- 引用错误仍然不限次退回。 理论上 agent 可能每次都换一个错的路径。之所以没设上限,是因为每次重写都是一次新的、可能正确的决定;一旦设了上限,又会回到「上限到了放不放行」这个问题。
- 跨回合的重试要靠 agent 主动再写一次路径。 框架不会在下个回合自动补交。这是有意的:上一回合的失败已经如实告诉用户了,要不要重交由这次对话的走向决定。
改动规模:14 个文件,+202 / −56,其中 4 个是测试文件,新增或改写的用例覆盖了上面每一种结局:提及不碰文件、最终回复里的同一链接会交付、环境故障本回合只试一次、Tool Host 离线和文件缺失分属两类、只有环境故障时退回消息不要求改路径,以及 UI 上提及显示名字、图片显示「(不可用)」。