本地大脑与 hub 大脑:同一个循环,两种宿主

0 阅读6分钟

本地大脑与 hub 大脑:同一个循环,两种宿主

先说结论。

「agent 装在手机上」这句话底下藏着两个完全不同的产品。区别不在 UI,也不在模型,而在回合循环被构造在哪台机器上。我们的实现里,这个选择收敛到启动函数开头的一处判断:大脑不是本地的,LocalBrain 这个类就根本不会被 new 出来。设备退化成一份工具 schema 加一个 WebSocket 客户端。

这篇讲这道缝长什么样、两边各要付出什么,以及在真正把它拆开的时候踩到的那个洞。

契约:一个 160 行的接口,两个 173 行的实现

core/ 是纯 JVM,Android 和 macOS 两个身体共用。共用的是 LocalBrain——2169 行,agent loop、提示词拼装、历史裁剪、工具分派全在里面。它看不到任何平台类型,因为身体通过 BrainHost 把需要的东西喂进去:

interface BrainHost {
    fun text(key: BrainText, vararg args: Any): String
    fun locale(): Locale
    fun maxSteps(): Int
    fun notebookIndex(): String
    fun scrollback(): List<ScrollRow>
    fun toolLists(): List<JSONArray>
    fun methodOf(toolName: String): String?
    fun dispatch(method: String, params: JSONObject,
                 callId: String, silent: Boolean, untrusted: Boolean): Any?
    fun foldTopic(title: String, summary: String, rows: List<ScrollRow>, text: String): FoldedTopic?
    fun traceDir(): File
    // ……另有若干带默认实现的成员
}

两个实现分别是 AndroidBrainHost 和 DesktopBrainHost,都是 173 行。这个相等是巧合,但巧合得有道理:接口摊开之后,两个平台要回答的问题是同一批。

有几个设计细节值得单拎出来,因为它们决定了这个拆法能不能长期活下去:

文案不是字符串常量,是枚举。 BrainText 是个 enum,NARRATE_TAP、ERROR_429、MAX_STEPS 这些键各平台必须一条条映射到自己的资源文件。少映射一个,是编译错误,不是设备上一句空白。这条约束很便宜,但它挡住了跨平台项目最常见的腐烂方式:新加一句提示,只在一个平台上出现。

平台差异用默认参数隔离,不用分支。 platformPrompt() 默认返回空串——手机身体不覆盖它,所以手机的提示词一个字节都不变;只有 Mac 那具身体在前面插一段说明「你这具身体不是手机」。同理 gearIndex()、planIndex()、friendsIndex() 都有空默认值,没有这个能力的身体不需要写一行代码。

滚动回溯传的是不透明句柄。 ScrollRow 里有一个 handle: Any?,平台自己的行对象原样带过去,改话题归档时再原样带回来。大脑不解析它,也就不会因为某个平台改了数据库列名而崩。

装载:一处 early return 决定了两种产品

startBrain() 的前半段是这样的:

val bc = VoiceConfig.brainConfig(this)
if (!bc.isLocal) {
    if (VoiceConfig.hubConfig(this).url.isEmpty()) {
        reportNoBrain(AppLocale.str(this, R.string.svc_no_brain_hub), announce)
    }
    startHubClient()
    catchUpPromises()
    Scheduler.syncPlan(this)
    return
}
// 本机分支:构造 MarketTools、构造 LocalBrain、
// 挂 peers.tasks.brain、catchUpPromises、syncPlan、catchUpSweep

注意 hub 分支里那两行看起来无关的调用:catchUpPromises() 和 Scheduler.syncPlan()。它们在 return 之前,因为待办和计划的闹钟跟用哪个大脑毫无关系——App 被覆盖安装、设备重启之后,AlarmManager 里的闹钟会丢,重新武装它是身体自己的责任。hub 模式下没有本地循环,这个补齐只能做一件事:发一条通知告诉你「这条到期了,但我现在没法替你做」。注释里写得很清楚,这比一个永远不会响的闹钟强。

这就是「身体」这个说法落到代码上的样子:手和脑可以分开,闹钟不能。

传输:hub 那边收到的是什么

hub 模式下,设备做三件事。

一,拨号。指数退避,INITIAL_BACKOFF_MS = 500,MAX_BACKOFF_MS = 30_000,连上就重置。

二,登记。发一帧 register,带上 device_id、device_name、以及一整份工具 schema 数组。这份数组是 ToolSchemas.forHub() 加上扩展注册的工具,内置的排在前面——不是为了顺序,是为了扩展万一撞名,撞出来的重复项会出现在尾部,肉眼能看见。

三,等。对面发 request 下来,带 id、method、params。这里有个两名转换:线上跑的是模型看得懂的名字(tap_screen),内部走的是 screen.tap,中间由 ToolSchemas.methodOf() 翻译;扩展工具不参与这套翻译,注册时是什么名,分派时就是什么名。

真正容易踩的是线程。dispatchGesture 会阻塞几秒,如果直接在 WebSocket 的收包线程上执行,ping/pong 就会被拖住直到超时掉线。所以请求被丢进一个单线程 worker,收包线程只负责解析和应答。同一个 socket 上收到请求这件事本身还会调一次 dispatcher.beginTask()——因为只有传输层分得清「这是大脑在驱动」和「这是顶栏按钮或 9008 调试客户端在点」,后两者走同一条分派路径,但都不是谁的任务。

事件:同一个事实,两种投递方式

通知是个好例子,因为它同时暴露了两种大脑的形状差异。

分流判定「这条值得看」,或者用户点了「看看」,最后都进同一个函数。有 hub client,就把 notification 事件发上去;有本地大脑,就把同样的事实写成一句散文,交给 notified()。

hub 保留的是事件类型,因为对面的 prompt 早就学会处理 kind = notification。本地大脑没有事件管道——没有管道也就没有管道丢失这回事——所以本地大脑收到的是一段话。

而 notified() 和 submit() 只差三个字,语义差很远:

fun submit(...) {
    host.touchActivity()          // 用户真的说话了:静默时钟重置
    launch(text, TurnKind.USER, images)
}

fun notified(text: String) {
    if (cfg.apiKey.isEmpty()) return          // 静默失败,连日志都没有
    val epoch = stopEpoch.get()
    loop.execute {
        if (stoppedSince(epoch, t, TurnKind.NOTIFY)) return@execute
        if (busy.get()) { pendingWakes.addLast(Queued(t, TurnKind.NOTIFY)); return@execute }
        launch(t, TurnKind.NOTIFY)
    }
}

三处不同,每一处都是故意的:不重置静默时钟(一条通知不是用户开口,否则这条通知会把自己的触发条件一直往后推);排在正在跑的那一轮后面,而不是打断它;受 stoppedSince 约束,用户刚按停止,这条就不许再起来。再加上 TurnKind.NOTIFY 会让整轮以 untrusted 身份跑,保险箱是关着的。

代价:三条现在不行

hub 模式没有本机循环。 这是那个 return 的直接后果。它意味着断网时这具身体只剩手,没有判断力——不是降级,是另一种架构。

事件不排队。 往 hub 推事件的函数在 conn == null 或 socket 未打开时直接返回。注释解释了原因:重连后补投一批「新消息」会把过期的打断灌进去,比丢掉更糟。副作用是断网期间发生的一切,对面永远不知道。

前台服务的类型提升失败是静默的。

runCatching {
    startForeground(NOTIFY_BODY, buildNotification(), type)
}.onFailure {
    Log.w(TAG, "while-in-use promotion refused (type=$type)", it)
}

只写日志。targetSdk 还是 34;往 35 以上走之后,后台启动前台服务的豁免会收窄,这条路径会变得更常走。表现不会是崩溃,是「他今天怎么不在了」。

什么样的问题该问「循环在哪」

如果你在给一个 agent 挑宿主,这三个问题比看架构图快:

断网之后他是变慢还是变哑;关掉另一台设备他还活不活;没人说话的时候他会不会自己动一下。

第三个最硬。一个不在设备上的循环,不可能在你没开口时醒过来——醒需要一个本地的计时器,和一份本地存的、他在意的东西。

代码在 github.com/kuafuai/andee,Apache-2.0 加附加条件。版本号是 0.x,这个数字是准确的,不是谦虚。