「它在等谁」只能有一个答案:一张不复制的交接视图

一个多线程 agent 系统里,「这条对话在等谁」被四个子系统各问了一遍,答案却有四种口径。这次的修复不是给每个子系统修一处 bug,而是让「在等谁」只有一个定义:一张从现有记录直接派生、不复制任何状态的视图。
1. 同一个问题,被问了四遍⌗
MaxClaw 不是一个对话框,而是一堆线程:Max 直接对话的主线程 Main、按话题开出的 side chat、各自派出去的后台任务、负责验收落地的 Maintainer。一条线程在没有回合在跑的时候,它的下一步通常在别人手里:派出去的任务还没回来、问 Max 的提问卡还没答、约好的复查还没到点。
这个「在等谁」,系统里至少有四处要用:
| 读者 | 它为什么要知道 | 改动前怎么算 |
|---|---|---|
turn-delivery | side chat 的回复算不算「最终结果」、要不要计未读 | 自己一条 SQL:在跑的任务 + 未结案的 Maintainer 单 + 在跑的第二意见 + 进程内 shell |
active-work | 对话压缩成新一代后,提醒它「你之前交出去的东西还开着」 | 自己一条 SQL:在跑的任务(任务线程未归档)+ shell + task_wait |
progress_board | Main 看各对话全貌 | 只有进度报告,没有机械记录 |
max-now | Main 每回合开头的现状快照 | 没有这一项 |
把前两行并排看就有意思了:
| 情况 | 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,每段从本来就存在的表里按条件挑行:
| holder | kind | 来源与条件 |
|---|---|---|
| self | turn | in_flight_turns(running / parked) |
| self | queued-wake | pending_injections 的 pending 与 dispatched |
| machine | task | tasks.result_status='running'、任务线程未归档 |
| machine | maintainer | maintainer_submissions.state 在开放状态集 |
| machine | second-opinion | second_opinions.state='running' |
| machine | fix-wait | fix_waits.state='waiting' |
| clock | next-check | next_checks.state='open',due = due_at |
| max | card / confirmation / decision | 直接读已有视图 needs_max_items |
| main | card | message_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 的状态问题,很少出在某一个查询写错了,而是出在同一个问题有多个作者。每个作者都在自己需要的那一刻写下一个「够用」的答案,然后系统长出来一个新的交接方式,答案们开始分叉,没有任何一个测试会发现,因为每个答案都只和自己一致。
这次的做法可以概括成三条:
- 一个定义:「在等谁」只在一处回答,读者只做过滤和判断。
- 派生不复制:定义是从原始记录派生的视图,没有副本,也就没有同步义务;已有的定义(
needs_max_items)直接被读,而不是被抄。 - 集合与判断分开:定义只陈述「有记录开着」,不说「卡住」「闲着」。
做到这三条,「谁的球没人接」才第一次成为一个可以回答的问题。