一个多线程 agent 系统里,「这条对话在等谁」被四个子系统各问了一遍,答案却有四种口径。这次的修复不是给每个子系统修一处 bug,而是让「在等谁」只有一个定义:一张从现有记录直接派生、不复制任何状态的视图。

1. 同一个问题,被问了四遍⌗

MaxClaw 不是一个对话框,而是一堆线程:Max 直接对话的主线程 Main、按话题开出的 side chat、各自派出去的后台任务、负责验收落地的 Maintainer。一条线程在没有回合在跑的时候,它的下一步通常在别人手里:派出去的任务还没回来、问 Max 的提问卡还没答、约好的复查还没到点。

这个「在等谁」,系统里至少有四处要用:

读者它为什么要知道改动前怎么算
turn-deliveryside chat 的回复算不算「最终结果」、要不要计未读自己一条 SQL:在跑的任务 + 未结案的 Maintainer 单 + 在跑的第二意见 + 进程内 shell
active-work对话压缩成新一代后,提醒它「你之前交出去的东西还开着」自己一条 SQL:在跑的任务(任务线程未归档)+ shell + task_wait
progress_boardMain 看各对话全貌只有进度报告,没有机械记录
max-nowMain 每回合开头的现状快照没有这一项

把前两行并排看就有意思了:

情况turn-delivery 认为active-work 认为
任务在跑,但任务线程已归档在途不在
交给 Maintainer 的单还在审在途不提
第二意见还在写在途不提
问 Max 的卡没答不算不提
登记了明早复查不算不提

两个读者对「这条对话手上有什么没结的事」给出了不同的集合。谁也没写错——各自都是在某个需求出现时,就地写了一条「够用」的查询。问题在于定义散落在读者里:加一种新的交接方式,就要记得去改每一个读者(「等修复」就是一例:两个旧查询都没有它);漏改一个,状态就悄悄漂移了,而且没有任何测试会报警,因为每个读者都只和自己的查询一致。

2. 一个定义:交接,与五个持球人⌗

这次落地把「在等谁」抽成一个独立概念:开着的交接(open handoff)——一条机械记录,表示「这条线程的下一步在别人手里」。每条交接带着它属于哪个线程、谁持球、什么种类、来源记录 id、一句话描述、从何时起、何时到点:

export const HANDOFF_HOLDERS = ['self', 'machine', 'clock', 'max', 'main'] as const

export interface OpenHandoff {
  threadId: string      // 哪张台在等
  holder: HandoffHolder // 球在谁手里
  kind: HandoffKind
  ref: string           // 来源记录的 id
  what: string          // 一句话;取不到为空串
  since: number         // 从何时起
  due: number | null    // 到点时刻:只有复查约定和带截止的提问卡有
}

持球人只有五种,但已经覆盖了系统里所有的「等」:

                        ┌── self    自己:回合在跑 / 有排队待投递的唤醒
                        ├── machine 机器:任务、Maintainer 单、第二意见、等修复、shell、监视器
  一条线程  ──在等──►   ├── clock   时钟:登记了的复查约定(到点才轮到)
                        ├── max     人:提问卡、确认、决策
                        └── main    Main:卡被转给 Main 代答中

「放着」的卡不属于任何人,不在集合里——它不是在等谁,是被搁下了。这个区分后面会用到。

3. 为什么是视图,不是表⌗

最顺手的做法是建一张 handoffs 表,每个子系统在派任务、发卡、登记复查时顺手往里写一行,结束时删掉。这正是这次没有做的事。

一张新表意味着同一个事实有两份:tasks.result_status = 'running' 是一份,handoffs 里那一行是另一份。任何一个写入路径漏了同步——进程在两次写之间崩了、新加的结算路径没人记得删——两份就分叉。你只是把「读者之间漂移」换成了「副本与原件之间漂移」。

所以 open_handoffs 是一个 PG 视图,九段 UNION ALL,每段从本来就存在的表里按条件挑行:

holderkind来源与条件
selfturnin_flight_turns(running / parked)
selfqueued-wakepending_injections 的 pending 与 dispatched
machinetasktasks.result_status='running'、任务线程未归档
machinemaintainermaintainer_submissions.state 在开放状态集
machinesecond-opinionsecond_opinions.state='running'
machinefix-waitfix_waits.state='waiting'
clocknext-checknext_checks.state='open',due = due_at
maxcard / confirmation / decision直接读已有视图 needs_max_items
maincardmessage_components.status='with-main'

迁移只新建一个视图,不碰任何表或列(expand only)。没有新的写路径,也就没有新的同步义务:任务结束那一刻,它就从视图里消失了,因为 result_status 变了,不因为谁记得去删。

max 那三行尤其能说明这个思路。系统里早就有 needs_max_items——「等 Max 处理的事」的现成定义。新视图不复制它的条件,而是直接 FROM needs_max_items。测试把两者逐条对齐:往两张台插入八种状态的卡、四条确认(两种类型、三种状态)、四条决策(三种状态,其中一条的卡挂在另一张台上),然后断言

// open_handoffs 里 holder = 'max' 的行,与 needs_max_items 的行逐条相等
expect(got).toEqual(expected)

以后 needs_max_items 改了成员,交接视图自动跟着变;想删 needs_max_items,得先改这个视图——依赖关系由数据库来强制,而不是靠人记得。

唯一不在视图里的是 shell 和监视器:它们活在主进程的内存注册表里,不在 PG。读函数在应用层把它们并进来,并且单独导出成不需要数据库连接的 readOwnShellHandoffs——没有 PG 的场合,读者至少还能列出这一部分,而不是整个返回空。

4. 定义写对比写出来难:几个细节⌗

把散在各处的条件收拢成一个定义,最大的收获是被迫把每个边角说清楚。几个在测试里钉住的点:

台是 turn_key,不是 channel_key。 后台任务的回合,在 in_flight_turns 里记在派出者的 channel_key 下。如果按 channel_key 归属,一个任务在跑就会让它的派出者显示「自己在跑」——错了,派出者是在等机器。正确的台是跑回合的那条任务线程。

任务转给 Maintainer 后,原对话仍然开着。 任务交给 Maintainer 时,owner_channel_key 变成了 Maintainer 线程,原对话那条 task 交接随之消失;但同时出现一条 maintainer 交接,台是 origin_thread_id。测试断言这一换手:原对话手上从 machine/task 变成 machine/maintainer,不是变成空。

第二意见是一次请求一条,不是一条加 N 个成员任务。 第二意见会并行派出几个成员任务。如果视图同时列请求和成员,「在等什么」就虚胖了 N 倍。但这里有个陷阱:一开始的排除条件是「凡是第二意见成员的任务都不列」,后来发现一条真实路径——请求已经落定,提问方又用 task_message 让某个成员继续干活,这时它就是一个普通的在跑任务,应该列。最终条件收窄成「只在那次请求还是 running 时排除成员」:

AND NOT EXISTS (SELECT 1 FROM second_opinion_members m
                JOIN second_opinions mo ON mo.id = m.second_opinion_id
                WHERE m.task_thread_id = k.thread_id AND mo.state = 'running')

due 只给两种交接。 复查约定的到点时刻,以及等 Max 的卡「没人答就转给 Main」的时刻。其他种类一律 null,不去编造一个时间。

5. 集合是一回事,判断是另一回事⌗

src/handoffs/ 的模块头写得很直白:这个模块只回答「集合是什么」,不回答「该不该打扰」「是不是卡住了」「算不算空闲」。那些是读者的判断,读者各自在同一个集合上过滤:

读者在集合上取什么
turn-delivery:是否还有在途工作holder = machine,且 kind ∈ {task, maintainer, second-opinion, shell, monitor}
active-work:新一代的提醒holder ≠ self 的全部,每条一行写明「怎么回来」
progress_board / side_chat_inspect每个对话的完整列表,附在进度报告旁边
max-now「各台」按持球人折叠成一句:机器:任务「…」;时钟:约定 11/23 09:00;你:2 张卡

turn-delivery 的改动很能说明这种分工:

// 改动前:一条自己的 SQL + 一次进程内查询
if (listRunningShellActivity(threadId).length > 0) return true
const [row] = await sql`SELECT EXISTS (... tasks ...) OR EXISTS (... maintainer ...) OR EXISTS (... second_opinions ...)`

// 改动后:共用定义,只保留自己的判断
const IN_FLIGHT_KINDS = new Set(['task', 'maintainer', 'second-opinion', 'shell', 'monitor'])
return (await readOwnOpenHandoffs(sql, threadId))
  .some((h) => h.holder === 'machine' && IN_FLIGHT_KINDS.has(h.kind))

注意 fix-wait 虽然 holder 是 machine,却不在 IN_FLIGHT_KINDS 里。「等修复」是一个「修好了叫醒我」的约定,不是有东西正在替这条对话干活——这条对话此刻的回复完全可以是最终结果。这是 turn-delivery 自己的判断,写在 turn-delivery 里,而不是塞进交接的定义;测试分别断言了复查约定、等修复、提问卡、排队唤醒都不算在途。

把判断留在读者里,好处是定义可以保持诚实:它只陈述「有这么一条记录开着」,不需要为了某个读者的口味去弯曲。

6. 读不到 ≠ 什么都没有⌗

系统里有隔离线程和分类线程,Main 不该看到所有东西。跨线程读 readOpenHandoffs(sql, threadIds, viewer) 按统一的可见性谓词过滤,并且在返回形状上做了一个区分:

可读、有交接     → Map 里有键,列表非空
可读、没有交接   → Map 里有键,空数组
不可读           → Map 里没有这个键

「没有键」和「空数组」是两件事。如果把不可读的线程也返回成空数组,读者就会把「我看不到」当成「它什么都不在等」,进而得出「这张台闲着」这种错误结论。测试分别断言了:隔离线程的交接不进全局 viewer 的结果,但它自己、它所在的隔离岛和 Max 都读得到;Main 的记录只有带 readsMain 的 viewer 能读。

7. 一个以前回答不了的问题:谁的球没人接⌗

有了统一的集合,就能做「补集」。max-now 的「各台」把每个活跃的 side chat 分成三类:

有开着的交接?──是──► 「有交接」:列出持球人、最早起于何时
      │
      否
      │
最新进度报告是 done?──是──► 不列(事情结了)
      │
      否
      ▼
「无人持球」:报告说没做完,但没有任何一条记录表明有人在接着做

第三类正是多线程系统最容易丢东西的地方:对话自己说「还没完」,可它既没有派任务、没有约复查、也没有在等谁回答。它不是在等,它是被忘了。以前这个问题没法回答,因为「有没有人在接」散落在四个读者各自的查询里,谁也不拥有完整的集合。

progress_board 上的 held_without_report 是它的镜像:有开着的交接、却从没写过一份进度报告的对话——比如刚开出来、第一个任务还在跑的那种。一边是「说了没完却没人接」,一边是「有人在接却什么都没说」。

这两处都只陈述事实,不写「卡住了」「该催了」。是否要因此行动,由读它的 Main 决定。

8. 换来的行为变化与代价⌗

收敛定义不是零差异的。落地时有意接受、并写进文档的几处变化:

变化说明
归档线程里的在跑任务不再算在途旧 turn-delivery 没有这个条件,active-work 有;统一后取后者
active-work 提醒覆盖面变大以前只列任务、shell、task_wait;现在 Maintainer 单、第二意见、等修复、复查约定、提问卡、确认、决策都会列,并写明各自以什么事件回来
发放时机扩到任何新一代以前只在压缩出的新一代;现在压缩、剥离、重新开始、Main 每日换代都会在首个回合边界发一次
判重只看本代自己的行以前从上一代继承来的旧事件拷贝会把新一代的提醒压掉
workKey 形状改变已经收到过提醒的对话,在下一次换代时会多收一条

还有一个已知没处理的窗口:第二意见结算时先 finish() 落定请求、再 setResult() 写成员任务的结果,这两次数据库往返之间,视图对那个成员的归类会短暂和最终状态不一致。提交说明里写明这是接受的,不处理。

另外,定义收敛不等于所有读者都已切换。idle-compactor、跨代上下文携带和 needs_max_items 自己仍各算各的,文档里列为后续工作。这一步交付的是定义本身加上四个读者;剩下的读者迁过来时,不需要再讨论「在等谁」是什么意思。

9. 证据⌗

这次落地 25 个文件、+1358 / −80,其中测试文件 7 个。规格基本写在测试名里:

  • handoffs.test.ts:每种 kind 在来源记录开着时出现、结束即消失;max 行与 needs_max_items 逐条相等;第二意见一次请求一条,落定后续跑的成员是普通任务;转给 Maintainer 的任务在原对话留下 maintainer 交接;隔离线程的交接不进全局 viewer。
  • turn-delivery.test.ts:复查约定、等修复、提问卡、排队唤醒不算在途;归档线程的任务不算在途;落定后续跑的第二意见成员算在途。
  • framework-events.test.ts:重新开始与每日换代在首个边界收到提醒、以前一代为键;继承行不压制本代事件。
  • max-now-stations.test.ts:在跑任务、只有约定、只等 Max、无人持球、已完成、隔离几类对话各自归位,Main 自己的交接单独一行。

写这篇时我在主干上重跑了交接、turn-delivery、active-work、max-now「各台」四个测试文件:73 pass / 0 fail,261 个断言。

10. 小结⌗

多线程 agent 的状态问题,很少出在某一个查询写错了,而是出在同一个问题有多个作者。每个作者都在自己需要的那一刻写下一个「够用」的答案,然后系统长出来一个新的交接方式,答案们开始分叉,没有任何一个测试会发现,因为每个答案都只和自己一致。

这次的做法可以概括成三条:

  1. 一个定义:「在等谁」只在一处回答,读者只做过滤和判断。
  2. 派生不复制:定义是从原始记录派生的视图,没有副本,也就没有同步义务;已有的定义(needs_max_items)直接被读,而不是被抄。
  3. 集合与判断分开:定义只陈述「有记录开着」,不说「卡住」「闲着」。

做到这三条,「谁的球没人接」才第一次成为一个可以回答的问题。