4、终端升级代理（Agent）设计：Agent的模块划分、状态机设计、与主应用的交互模式
好，咱们今天聊聊终端上的升级代理，也就是 Agent。这个模块是整个 OTA 系统的「前线指挥官」。我见过不少团队，把升级逻辑直接塞进主应用里，结果每次改升级策略都得跟着发版，苦不堪言。
Agent 的核心价值就一句话：把升级这件事，从主应用中解耦出来。让它成为一个独立的、可自升级的守护进程。
4.1 Agent 的模块划分
我个人习惯把 Agent 拆成四个核心模块。你想想看，一个升级任务从触发到完成，无非就是：收到指令、下载包、校验、然后执行安装。每个环节独立成一个模块，后期维护起来特别清爽。
| 模块名称 | 职责描述 | 我踩过的坑 |
|---|---|---|
| 通信模块 | 负责与云端 MQTT/CoAP 网关交互，接收升级指令，上报进度 | 曾经因为 MQTT 心跳超时设置太短，导致频繁断连重连，升级指令丢失 |
| 下载管理模块 | 管理固件包的断点续传、分片校验、存储空间预检 | 遇到过下载到一半存储满了，系统直接挂掉的情况 |
| 校验与安全模块 | 验签、哈希校验、版本号防回滚检查 | 嗯，这里要注意，验签失败一定要有明确的错误码上报 |
| 安装执行模块 | 负责切换系统分区、调用 bootloader 执行升级 | 这个模块一旦出问题，设备就变砖了，所以必须做双备份 |
4.2 状态机设计：别让 Agent 迷路
Agent 的核心灵魂就是状态机。说白了，就是让 Agent 知道自己「现在该干嘛」。我见过最糟糕的设计，是用一堆 if-else 来管理升级流程，结果状态一多，逻辑就乱成一锅粥。
我推荐用有限状态机（FSM），状态定义如下：
// 状态定义
typedef enum {
AGENT_IDLE, // 空闲态
AGENT_CHECKING, // 检查更新
AGENT_DOWNLOADING, // 下载中
AGENT_VERIFYING, // 校验中
AGENT_READY_TO_INSTALL, // 待安装
AGENT_INSTALLING, // 安装中
AGENT_ROLLBACK, // 回滚中
AGENT_ERROR // 错误态
} agent_state_t;状态流转的核心逻辑是这样的：
- IDLE → CHECKING：收到云端推送的升级通知，或者定时检查触发
- CHECKING → DOWNLOADING：确认有可用升级包，且版本号合法
- DOWNLOADING → VERIFYING：下载完成，开始校验完整性
- VERIFYING → READY_TO_INSTALL：校验通过，等待用户确认或静默安装窗口
- READY_TO_INSTALL → INSTALLING：条件满足，开始安装
- 任何状态 → ERROR：出现不可恢复的错误
- ERROR → IDLE：错误处理完毕，或者超时重置
4.3 与主应用的交互模式
Agent 和主应用怎么配合？这是个老生常谈的问题。我见过三种主流模式，各有优劣。
4.3.1 模式一：独立进程 + Socket 通信
Agent 作为一个独立进程运行，主应用通过本地 Socket 或 Unix Domain Socket 与它通信。这是我最推荐的方式。
- 优点： 完全解耦，Agent 崩溃不影响主应用，主应用卡死也不影响升级
- 缺点： 需要定义一套通信协议，稍微增加开发量
- 我常用的协议： 简单的 JSON 字符串，包含 cmd 和 payload 字段
// 主应用发送查询指令
{
"cmd": "query_status",
"seq": 12345
}
// Agent 返回状态
{
"cmd": "status_report",
"seq": 12345,
"state": "DOWNLOADING",
"progress": 67,
"error_code": 0
}4.3.2 模式二：共享内存 + 信号量
适合对实时性要求极高的场景。Agent 和主应用通过共享内存交换状态，用信号量做同步。
- 优点： 延迟极低，微秒级响应
- 缺点： 调试困难，容易出内存竞争问题
- 我的经验： 除非是车载或工业控制这种硬实时场景，否则别用这个模式
4.3.3 模式三：回调函数注册（单进程内）
Agent 作为主应用的一个线程运行，主应用注册回调函数给 Agent 调用。
- 优点： 实现简单，适合资源极度受限的 MCU
- 缺点： 一旦 Agent 线程卡死，整个主应用都受影响
- 我的建议： 只在 Flash 小于 1MB 的芯片上用这个模式
核心原则： 无论用哪种模式，主应用和 Agent 之间一定要有「心跳机制」。主应用定期向 Agent 发送「我还活着」的信号，Agent 如果连续几次没收到心跳，就要主动进入安全模式，防止主应用挂了之后升级流程失控。
4.4 交互中的关键设计细节
说几个我实际项目中遇到的细节问题，希望能帮你少走弯路。
第一，升级过程中的业务暂停。 安装阶段通常需要重启系统或长时间占用 CPU。主应用应该在收到 Agent 的「准备安装」通知后，主动保存用户数据，然后进入休眠或降级模式。我曾经见过一个智能门锁，升级过程中主应用还在处理开锁指令，结果升级写到一半，Flash 被业务数据写坏了。
第二，升级失败后的回滚通知。 Agent 执行回滚后，一定要主动通知主应用「我已经回到旧版本了」。主应用需要重新加载旧版本的配置和状态。否则会出现版本不匹配导致的诡异 bug。
第三，用户交互的时机。 如果设备有屏幕或指示灯，主应用应该负责展示升级进度，而不是 Agent 直接操作硬件。Agent 只负责把进度通过通信接口传给主应用。这样主应用可以自由决定展示方式——是显示进度条，还是闪灯，还是语音播报。
好了，关于 Agent 的设计，核心就是模块化、状态机驱动、以及与主应用保持清晰的通信边界。你想想看，只要把这三点做好，不管云端怎么变，不管硬件平台怎么换，Agent 都能稳如泰山地完成升级任务。