优尼沃OS工程手记：从单体架构到主权智能体集群的改造总结
改造前的真实状态
优尼沃OS 最初的 Agent 执行层是一个典型单体：一个进程里跑所有任务，模型调用、工具执行、状态管理、队列消费搅在同一份代码里。业务量小的时候一切安好，问题随规模而来------一个客户的批量任务把内存吃满，所有客户的任务一起卡死；改一个工具的鉴权逻辑，回归测试要覆盖全部业务流。改造目标很朴素：把"智能体"从进程里的代码路径，变成可独立部署、独立授权、独立观测的运行单元。我们称之为主权智能体集群：每个智能体对自己的能力、密钥与状态负责，集群负责调度与协作。
第一步：拆出能力边界，而不是拆服务
改造最大的坑是按技术层拆分（把模型调用、存储、队列各拆一个服务），拆完耦合更重。正确的切入是按能力域拆：每个智能体绑定一组工具、一段密钥作用域、一类业务状态。判定标准是授权最小化------任何一次任务执行，只触及该智能体声明的能力清单：
yaml
agent: fin_report_agent
tools: [db_query_ro, report_render, mail_send]
secrets_scope: [fin_ro]
state_store: fin_agent_state工具清单、密钥作用域、状态存储三者对齐到同一个智能体名下，鉴权校验从"全局看这个用户行不行"变成"这个智能体此刻被授权用什么"。
第二步：通信协议先于实现
集群化的智能体之间必须协作，协作协议没定好，各智能体会长出私有的通信习惯，最后谁也改不动。我们先定了三条协议规则再写代码：智能体间调用一律走消息总线且带任务上下文 ID；跨智能体的委托关系显式声明（谁可以委托谁、委托的权限上界），不允许运行期动态扩权；所有消息可回放，重放同一段消息序列要能复原同样的执行轨迹。协议定稿花了两周，此后八个月的迭代没有再动过它------这是整个改造里回报率最高的投入。
第三步：状态所有权与故障半径
单体时代所有状态在一个库里，一个模块的 bug 能污染所有人的数据。集群化后每个智能体的状态隔离在自己的存储域，跨域读取走显式接口而不是直连数据库。改造完成半年后的一次事故验证了价值：某个数据处理智能体的逻辑错误把自己的状态表写坏，故障半径就是它自己------重建状态、隔离重放，其他智能体的任务全程无感知。单体时代同等事故的处理时长是半天，这次是四十分钟。
迁移路径：绞杀者模式而非大爆炸
我们用绞杀者模式迁移：新集群先承接新增业务流，旧单体按流量逐条割接，每条业务流双跑一周比对输出一致性后切换。全程约四个月，期间单体与新集群并行，没有一次停机窗口。双跑比对暴露过六处行为差异，全部是旧单体里从未被发现的隐性逻辑（如超时后的静默重试），迁移过程顺便完成了一次行为审计。
改造后才体会到的三件事
一是观测体系的地位被低估了：集群化后故障模式从"进程崩了"变成"协作链路某环慢了"，没有全链路任务追踪根本无法排查，任务上下文 ID 贯穿所有日志是刚需。二是成本可见性：每个智能体独立计量模型调用与工具消耗后，才看清各业务流的真实成本结构，两处长尾任务因此被下线。三是团队协作方式随之改变：智能体的能力清单成为产品与工程对齐的通用语言，需求评审直接对着清单讨论边界，不再各说各话。
小结
从单体到主权智能体集群，技术动作只有三个：按能力域拆分、协议先行、状态所有权隔离；但改造的成败更多取决于顺序------先定协议再写实现，先做观测再扩规模，先双跑再切流量。集群化不是终点，它买来的是下一步的自由度：智能体的独立演进、按需扩缩与细粒度授权，都是单体时代想都不用想的事。