1956 字
10 分钟
一个项目里同时有四个"真相"

HakusAgent 是我做了一年多的本地 AI 工作台。它现在能跑的东西不少:桌面端、终端、Android、SSH 和 WSL 远程工作区、语音、Live2D。

功能堆得越快,架构债越明显。最要命的一条是——这个项目同时有四个地方能声称自己记录了”对话里到底发生了什么”。

Python 的会话表里有消息行和事件行;Rust 运行时有自己的事件表;checkpoint 文件是一种恢复快照;还有 rollout 日志和长任务的 JSON 状态文件。

四套东西互相重叠,谁也不服谁。

具体的症状是:恢复会话时可能拼出两个版本的对话历史;桌面端改了状态但侧栏没跟上;同一个工具调用在一个界面显示成功、在另一个界面显示还在跑。

于是我停掉功能开发,先把这件事解决掉。

为什么会出现四个#

回头看,每一个都有自己的来历。

Python 那套是最早的,那时所有逻辑都在 Python 里,消息和事件写在一起很自然。

Rust 是后来为了性能和进程管理加的,它需要自己掌握执行状态,于是有了第二套表。

checkpoint 是为了”长任务能恢复”加的——一个正在跑的任务需要能快照下来,这看起来和消息历史是两回事。

rollout 日志最初是给调试用的,长任务的 JSON 状态是为了让进程重启后不丢东西。

单独看,每一个都解决了真问题。合在一起,问题就变成了:模型看到的历史应该从哪来,恢复的时候以谁为准,工具调用的”已开始”状态算谁的。

把答案定成一个#

重构的核心决定只有一句:Rust 是唯一的执行平面,事件账本是唯一的事实源。

具体到三个平面:

Rust 负责进程生命周期、工作区传输、文件和命令执行、沙箱、会话持久化、事件排序、对外协议。它是唯一真正执行动作的地方。

TypeScript 负责呈现:桌面面板、provider 和插件管理、工作流编写。它不能自己执行工作区工具。

Python 退到扩展层,负责语音、VTuber、旧模型适配这类事情。它不在默认的编码路径上,也不能直接改会话存储。

这个分工真正改变的是”谁能定义真相”。之前 Python 和 Rust 都能跑一轮对话,现在的规则是:所有模型可见的状态,必须先变成一条 Rust 侧的事件,才允许发给模型。

事件长什么样#

事件信封不算复杂:

{
"schema_version": 1,
"event_id": "evt_01J...",
"event_type": "tool_call_started",
"session_id": "ses_01J...",
"workspace_id": "ws_01J...",
"turn_id": "turn_01J...",
"correlation_id": "corr_01J...",
"seq": 42,
"timestamp": "2026-10-02T12:00:00.123Z",
"payload": {}
}

设计里有几条约束,每一条都是针对之前踩过的坑:

序号只能由写入方在单个事务里分配,客户端不许生成。 这条的意义是:追加失败即动作没有开始。不允许出现”界面显示已开始、账本里没有”的状态。

时间戳不参与排序。 墙钟会跳——时区、NTP 校正、系统休眠都算。排序一律用序号。

可见性字段只影响投影,不影响执行。 模型看得见什么、界面显示什么,是渲染层的事,不能反过来改变运行时行为。

核心事件类型是封闭集合。 扩展要加事件,必须用自己的命名空间声明。否则这个账本很快会变成什么都往里塞的垃圾桶。

消息列表不是真相#

这一条我花了些时间才真正接受。

之前我下意识地把”消息列表”当成对话的载体——它就是你在界面上看到的那个东西,怎么会不是事实源?

但在新模型里,消息列表、任务看板、Review 面板、用量统计、恢复摘要,全都是投影。每一个记录自己已经应用到哪个序号,随时可以删掉重建。

删掉重建这个性质很重要:如果某个界面显示错了,删掉它的状态重新投影就行,不需要去修账本。

桌面端可以做乐观渲染来压延迟,但重连时必须按事件 id 对齐并丢弃——它永远不能当恢复来源。

权限也只能有一个入口#

重构前有两套权限:Python 侧一套,Rust 侧一套。词表不一样,判定逻辑也不一样。

同一个危险命令,走不同路径可能得到不同结论。这不是理论问题,我在实测里遇到过。

新的模型把所有东西都当能力:工具、provider、工作区传输、沙箱、MCP、Skills、子代理。每个能力必须声明副作用范围、风险等级、需要的审批模式、支持的工作区类型。

决策集中在一处,只返回三种结果:允许、询问、拒绝,附带稳定的规则 id 和人类可读的理由。桌面、终端、远程 worker、Python 扩展全部走这个边界,任何适配器不得绕过。

另外把几类危险操作拆成独立维度:破坏性操作、工作区逃逸、凭据访问、网络出口、远程进程控制。它们各自判定,不会因为”整体模式宽松”被一起放行。

给自己定的硬指标#

重构如果只是”把结构整理得好看一点”,就没有验收标准。所以我定了一组可测量的门槛:

冷启动五秒内主窗口可用;空闲内存不超过 450 MB;提交后 300 毫秒内出现第一个事件;事件序号无重复无递减;取消确认后工具不得继续修改工作区;重放产生完全相同的模型可见历史;provider 健康检查不泄露凭据;远程重连不得分叉历史。

其中”取消后不得继续修改工作区”最麻烦,因为子进程可能已经跑起来了。要真正确认,得做 kill 加 trace 的测试,而不是只看接口返回成功。

迁移顺序不能乱#

拆成六步:

先稳定运行时边界,给本地工作区和 provider 健康检查补契约测试;再逐个接工作区适配器,SSH 然后 WSL 然后 Docker,每个都要先过假环境测试再上真机;然后让终端、桌面、Web 都只消费同一份账本,同时冻结新的 Python 会话格式;接着把页面式布局换成分栏工作台;再把语音、VTuber、旧 provider、Android 挪到带版本的可选协议后面;最后才删旧代码。

关键是第五步和第六步不能提前。在切片跑通之前,一个旧功能都不能删;中间任何时刻主分支都要能跑。

学到的#

先写契约再写代码。 这次我先写了一份四万字的规范,把事件信封、状态机、迁移门槛、删除规则全定下来。写文档的过程本身就暴露了三处设计矛盾——如果直接写代码,这些矛盾会变成三个月后的 bug。

参考别人的架构,但别抄目录结构。 这套边界设计参考了 DeepSeek Harness 的事件、能力、审批三个契约,交互和工作区参考了 ZCode。但我没有照搬它们的插件目录组织——那是为纯 runtime 设计的,套到有桌面、语音、VTuber 的产品上会畸形。


项目还在重构中。等垂直切片跑通、旧路径退休,再写一篇收尾。

一个项目里同时有四个"真相"
https://neko.aliceneko.xyz/posts/hakusagent-refactor/
作者
Alice Charlotte
发布于
2026-10-26
许可协议
CC BY-NC-SA 4.0