一个主动型助理要把话推到用户面前,常见做法是让它另写一份推送稿、再交给一套投递策略去裁决。MaxClaw 这次把这两样都拆了:notify 不再带内容,只给这一轮回复盖一个「现在送达」的章。

1. 改动前:一句话,三份拷贝,两套「看过了」⌗

MaxClaw 的 Main 是常驻的总管线程:任务结果、定时器、收件箱分拣都以事件的形式交给它,由它决定要不要开口。它开口有三个出口:

出口改动前的内容来源改动前的「看过没有」
Main 页里的回复这一轮的最终回复Main 线程的阅读水位 threads.last_read_at
网页上的浮层气泡notify 的 title + body,存进 main_bubbles 表main_bubbles.state:open → replied / snoozed / acknowledged
手机推送同一个 notify 的 title + body推送自己的投递 / 打开记录

也就是说,Main 想告诉用户一件事时,要在回复里写一遍,再在 notify 的参数里重新写一遍(受 pushMaxUnits 默认 100 字的限制,等于再写一份摘要),框架把后者存成气泡行、再推一份到手机。三份文字由模型分两次写出,很容易不一致:回复里说了三件事,推送只挑了一件;回复改了措辞,气泡还是旧的。

「看过没有」也有两套。用户在浮层里点了「知道了」,气泡状态变 acknowledged,但 Main 的水位没动,侧栏的未读数还亮着;反过来,他打开 Main 页看完了,浮层里那条还是 open。旧实现里有一整个 src/main-bubble/(store、service、routes、状态机,加上快捷回复 replies 和「稍后」)专门维护这第二套状态,这次连同它的 254 行测试一起删掉了。

投递上还有第二个决策者。Main 已经判断「这件事现在该告诉他」,推送层还要再过一遍:免打扰钟点、手机专注模式、每日预算、按类别统计的采纳率(最近 20 条采纳率 < 30% 就自动降成「只进简报」)。quiet 级别的气泡还要等当前对话的回合停下才弹。模型说「现在」,框架说「再等等」,最后谁说了算,要看哪条规则先命中。

还有一个按钟点触发的早报:免打扰结束时往 Main 投一个 proactive-due 唤醒,让它写当天第一条消息。

2. 改动后:话只有一份,notify 只是一个标记⌗

新的规则一句话:**Main 对用户说的话只有一份,就是它每一轮的最终回复,按空行拆成气泡。**要不要把这一轮推到用户面前,是给这一轮打一个标记,而不是再写一份内容。

             Main 的一轮(后台回合)
                     │
       回复:段落1 ␤␤ 段落2 ␤␤ 段落3      ← 唯一的一份话
       可选:notify({ level })           ← 只是标记,不带字
                     │ 回合结束、回复落库(onWebTurnEnd)
                     ▼
        MainDelivery.onTurnEnd ── 没标记 ──► 只留在 Main 页(结果,不计未读)
                     │ 有标记 + 有正文
                     ▼
        main_deliveries 记一行(不存内容,不存状态)
                     │
          用户此刻有网页在屏幕上?
           ├─ 是 → 浮层:直接读这条回复的气泡
           └─ 否 → 手机推送:正文 = 这条回复的气泡
                     │
       看没看到:只认 threads.last_read_at

2.1 notify 在 Main 里变成了「盖章」⌗

skills/notifications/tools.ts 里同一个 notify 工具,按调用的线程分两种形态。在 Main 里,带内容字段会被直接拒绝:

const PUSH_CONTENT_FIELDS = ['reason', 'carries', 'title', 'body', 'summary'] as const

if (fromMain) {
  const stray = PUSH_CONTENT_FIELDS.filter((key) => p[key] !== undefined)
  if (stray.length > 0) return { ok: false, error: `Main 的 notify 只标记「这一轮的回复现在送到他面前」,不收 ${stray.join('、')}:…` }
  // …
  return { ok: true, marked: true, level: p.level, …, note: MAIN_MARK_NOTE }
}

它只收 level(critical / normal / quiet)和几个元数据(signals 供收件箱学规则,behavior / loop / todo_task 给推送加按钮)。返回 marked: true,并在 note 里告诉模型:标记在回合结束后才生效,这一轮最后要是没有给用户的正文,就什么也不送。一轮里调多次,以最后一次为准。

工具调用本身就是证据。onTurnEnd 不读任何内存状态,而是从这一轮落库的工具行里找最后一次成功的 notify,所以重启之后照样成立:

const marked = (await turnToolCalls(sql, MAIN_THREAD_ID, end.msgId))
  .filter((c) => c.name === NOTIFY_TOOL && c.ok && c.result?.marked === true && isLevel(c.result.level)).at(-1)

2.2 送达记录不存内容⌗

新表 main_deliveries(迁移 0675_main_deliveries)的全部列:

turn_id | message_id | via ('notify'|'reply') | reply_to | level | at | created_at

没有标题,没有正文,没有状态。浮层要显示什么,是拿 message_id 回 messages 表取那条回复,用 splitMainBubbles 现拆,和 Main 页的拆法是同一个函数。有一条测试专门钉住这一点:它断言 main_deliveries 的列表正好是上面七列,再扫一遍 src / skills / ui/src 下的全部 ts/tsx,确认除迁移外没有任何文件还提到 main_bubbles。

2.3 「看过了」只有一个水位⌗

浮层的列表查询是这样的:

SELECT … FROM main_deliveries d
  JOIN threads t ON t.id = 'max:main'
  LEFT JOIN messages m ON m.id = d.message_id
 WHERE t.last_read_at IS NOT NULL AND d.at > t.last_read_at

d.at 是回复落库的时间,跟 Main 的阅读水位比。用户点浮层的「知道了」,调的是 markMainReadThrough(messageId),把 Main 的水位推到这条;在浮层里回一句,也推水位;打开 Main 页看到尾部,同样推水位。三个动作改的是同一个值,所以浮层、侧栏未读数、Main 页三处的结论不会对不上,也就不需要维护什么状态机。

未读数的口径同样只有一处:数据库函数 quiet_turn() 判断一轮是不是「静默的后台结果」。以前它把 notify 结果里带 notification_id 的回合当作非静默;Main 的标记背后没有通知行,于是迁移给它加了一条等价条件:

AND (r.content_text LIKE '%"notification_id"%' OR r.content_text ~ '"marked"\s*:\s*true')

测试 a marked turn is a turn that called notify: its bubbles count as unseen, once each, and it floats on the same watermark 断言:一轮被标记的两段回复,未读数是 2,浮层是 1 个条目,两者读的是同一个水位。

2.4 推到手机的就是回复本身⌗

用户没有任何网页在屏幕上时,被标记的这一轮推一条:标题 Main,正文是这一轮的气泡。截断规则在 push-body.ts,原则是不切断气泡:

for (const bubble of bubbles) {
  if (kept.length + questions.length > 0 && [...kept, bubble, ...questions].join('\n\n').length > limit) break
  kept.push(bubble)
}
return [...kept, ...questions].join('\n\n')
输入(上限 300 字)推送正文
100 + 100两段都在
100 + 100 + 100前两段(第三段放不下,整段丢掉,不切半截)
400 + 10只留第一段(第一段永远保留,超长由推送载体去截)
200 + 150 + 一个提问第一段 + 提问
400 + 一个提问只有提问

提问优先于叙述:如果这一轮发了还没回答的提问卡,提问作为最后一个气泡一定保留,推送带上卡片的选项按钮和回复框,点按钮就是回答那张卡。卡片自己已经响过一次(存在 choice:<id> 的推送)就不重复。

注意这里不再套 pushMaxUnits 那个 100 字的上限。那个上限针对的是「agent 专门为推送写的一段字」;现在推的是回复本身,长度由载体预览(APNS_BODY_PREVIEW_CHARS = 300)和整段保留规则管。

3. 投递策略为什么可以拿掉⌗

这是这次改动里最容易被质疑的一步:免打扰、专注、预算、采纳率,对 Main 的推送全部不再生效。

if (req.initiatedBy !== 'main' && !critical && req.level !== 'record') {
  // 类别降级、每日预算……只对其他来源
}

理由是:这些规则原本就是在替「是否打扰」做决定,而 Main 本来就是那个做决定的角色。两边同时决定,结果不是更稳,而是谁也说不清最后为什么推了或者没推。现在 Main 每一轮开头都会收到一个 max-now 事件,里面是框架采集的事实:用户最近在哪个对话说话、网页开没开、手机的状态、今天已经找过他几次。Main 的提示词里写的是「没有哪个钟点一定不能找他」,由它看着这些事实自己掂量;它要是判断错了,问题在判断本身,而不是被另一套规则悄悄改写。

但拿掉的范围卡得很死,几个细节值得一提:

来源靠发起路径标记,不靠目标线程。NotifyRequest.initiatedBy = 'main' 只由两处设置:送达 Main 被标记的一轮(src/main-delivery/),以及 Main 自己的提问卡。仅仅 threadId = max:main 不算,因为收件箱、确认门、框架决策也会以 Main 为目标发通知。如果按线程判断,等于给框架开了一个绕过全部策略的后门。

**Main 不挤占别人的配额。**被标记的推送写入 metadata.pushInitiatedBy,预算计数和采纳率样本的查询都加了 IS DISTINCT FROM 'main'。否则 Main 推得多一点,别的来源就会因为「今天的预算用完了」而被降级,这是另一种隐性耦合。

其他来源一律不变。docs/push-contract.md 为此列了一张表:side chat 的 notify 仍要带 carries,仍受免打扰、专注、预算和类别约束;任务里的 notify 仍转交给派出它的线程;确认请求、收件箱的显式规则推送、cron 报告、框架决策各走原路。去重、字数上限、敏感内容处理、投递重试对所有来源保留。

**不标记就不推。**测试 an unmarked background turn does not float, push or light the sidebar number 断言:一轮没调 notify 的后台回合,浮层为空,推送为空,main_deliveries 没有行,未读数为 0。拿掉的只是「标记了还要被拦一道」的那部分,「默认不打扰」没变。

4. 由状态变化唤醒,而不是钟点⌗

早报的钟点触发整条删除(src/proactive/ 11 个文件 +45 / −393,迁移 0674_retire_morning_briefing 取消旧的待执行触发、撤回未投递的唤醒)。替代它的是 src/mainctx/state-changes.ts:把观测到的状态变化作为 max-state-changed 事件投给 Main。

变化判定(默认值,[mainStateWake] 热配置)
activity-resumed距上次活动 ≥ 120 分钟后的第一次活动
activity-stopped一段连续活动 ≥ 20 分钟(相邻间隔 ≤ 5 分钟)之后,10 分钟没有活动;每段只触发一次
place-changed手机伴侣应用已去抖的进入 / 离开已知区域信号
focus-ended手机专注模式关闭(开启或未知都不触发)

活动判定是一个很小的状态机:

activity(at: number): StateChange[] {
  const changes = this.stopped(at)                       // 先结算可能已经发生的「停止」
  const gap = this.last === null ? null : at - this.last
  if (gap !== null && gap >= c.inactiveMinutes * 60_000) changes.push({ type: 'activity-resumed', … })
  if (gap === null || gap > c.activityGapMinutes * 60_000) { this.began = at; this.dense = false }
  if (at - this.began >= c.denseMinutes * 60_000) this.dense = true
  this.last = at
  return changes
}

有几处克制:

  • **没有基线就不冒称「长时间无活动」。**启动时用最近一条本人消息当基线;没有基线时,第一次观测到活动不触发 activity-resumed(gap === null)。
  • **事件只陈述事实。**正文是「<时刻>:N 分钟无活动后首次记录到活动」,不写「他起床了」「可以打扰了」。activity-stopped 也只说「已 10 分钟未记录到活动」,不推断成「在休息」。
  • **Main 正忙时不插话。**变化在回合边界合成一次唤醒;2 分钟内同类变化只保留最新一条,较远的仍在同一批里保留。这个窗口只用于合并待送达的事实,不是冷却期。
  • **没有每日次数上限,没有固定晨间钟点。**提示词里改成「每天第一次开口没有固定时刻,等事实显示他已经开始活动、接得住话的时候」。

关键在于:唤醒和送达是两件独立的事。状态变化只是把 Main 叫醒去看一眼,Main 醒来之后照样走第 2 节那条路:有话说就写回复,要用户现在看到就标记,没话说就什么都不留。state-wake-outcome.ts 在唤醒行上记一个 spoke(这一轮有没有留下正文、提问卡或确认门),并特意写明它不等于送达:没标记的回复 spoke 为真,但不浮出也不推。测试把三种情况分开钉住:标记了→送达且 spoke=true;没标记→只留在 Main 页、spoke=true;什么都没留→spoke=false、无送达。

这样做的好处是阈值可以按真实数据调。设计文档附了一条只读 SQL,一周后按类型统计「唤醒了几轮、其中几轮开了口」;还有一个强制 PG 只读的回放脚本 scripts/replay-main-state-wakes.ts,拿历史消息时刻重跑同一个状态机。文档也写明了回放的边界:网页在场心跳没有历史日志,回放只用消息时间戳驱动,不是线上触发次数的精确复现,这组默认值只是起始值。

5. 「没话可说」必须是一个正常结局⌗

上面的设计有个前提:Main 被叫醒以后,可以什么都不说。这在运行时里原本是一个故障。

一个模型调用既没有文本也没有工具调用,direct-loop-host 会当作空响应重试,Anthropic 适配器会改用非流式再请求一次,回合最终返回 EMPTY_RESPONSE,写一条 turn-empty 事件,界面上挂一个失败标记。对等用户回复的场景来说这是对的;但对一个「被状态变化叫醒、看了一眼发现没事」的后台回合来说,这等于逼它要么硬说一句「我看过了,一切正常」,要么被当成故障再跑一遍。前者正是这次想消灭的噪音,后者白白多花一次模型调用。

所以新增了一个 silentEndAllowed,只对 Main 的后台回合打开:

const silentEndAllowed = isBackgroundTurn && toolThread.role === 'main'
// …
const finalResponse = response || (silentEndAllowed ? '' : EMPTY_RESPONSE)

它一路传下去:运行时不重试,LLMCallOptions.allowEmptyResponse 让 Anthropic 适配器把 empty_response 当正常返回、不做非流式兜底。端到端测试 a Main background turn with nothing to say ends with no text 断言只有 1 次模型请求、没有新增 turn-empty、没有推送、没有送达、spoke=false;紧接着的一条测试断言 side chat 遇到同样的空响应仍然会发第 2 次请求。用户在等回复的地方,空响应仍然是故障。

提示词也配合改了:「你在这里写下的每一段话,都是发给他的一个气泡。这一轮没有话要对他说,就什么都不留。『我看过了,没到要告诉你的程度』不是一句要对他说的话。」这句提示属于冻结进触发行 modelView 的回合提示(首写赢),只有部署后新起的后台回合带新措辞,已有的行逐字节回放旧措辞,不动已缓存的请求前缀。

6. 退役的方式⌗

删一张表比建一张表难。main_bubbles 这次没有 DROP:上一版代码的 notify 还会往里写,guardian 如果把生产回滚到上一版,表不在就会在 schema 上报错。所以迁移把它留成一张不读不写的空表,并在注释里写明保留原因(回滚窗口)、剩余依赖(仅上一版代码)、删除触发条件(这一版过完试用期、不再有更老的回滚目标)和目标阶段(下一版迁移 DROP TABLE)。上面提到的那条扫描测试保证这期间没有代码偷偷又用上它。

早报的历史也一样。quiet_turn() 和界面里对旧 proactive-due + morning-briefing 回合的例外保留,只为了已有历史回合的显示和未读数不变;删除条件是这类行全部压缩出回放窗口。

7. 为什么这比「另写一份推送」好⌗

把两种做法放在一起比:

推送是第二份内容推送是对回复的标记
内容一致性模型写两遍,靠自觉保持一致结构上只有一份,浮层和推送现拆同一条回复
「看过了」每个出口一套状态,需要互相同步一个水位,三个动作推同一个值
谁决定打扰模型决定一次,策略层再裁决一次模型决定;策略只管其他来源
唤醒钟点驱动,到点必须写点什么状态变化驱动,醒了可以什么都不说
回滚 / 重启气泡状态在独立表里,要单独迁移标记就是落库的工具行,重启后照样成立

已知边界也写在设计文档里:用户在 Main 正跑着一轮时从浮层回复,这条消息按插话在下一个安全点送达,如果那一轮先收尾了,回答会出现在随后重放的新一轮里;浮层里的条目不过期,长时间不开网页会在下次打开时排队出现,直到水位越过它们。

说到底,主动型助理最容易犯的错,是把「说什么」和「要不要让你看到」做成两个系统,各自有内容、有状态、有规则,最后互相打架。这次的做法是把后者降成前者上的一个比特:话还是那一份话,只是这一轮盖了个章。

写作时在主干上重跑了 main-delivery、state-changes、turn-delivery.e2e 三个测试文件:48 pass / 0 fail,198 个断言。