a4phone 内置版本更新检查：守护进程周期查询 npm registry，发现新版本时推送手机提醒；其他命令发现新版本时终端提示 + 手机推送，确保你不会错过更新。检查带限频与去重（同一新版本只提醒一次），默认开启且可配置关闭。本文章介绍更新检查的机制、提醒渠道、缓存与限频规则。

1. 功能概述

维度 说明
检查对象 npm registry 上 a4phone 的最新版本
查询源 npmmirror 优先，registry.npmjs.org 兜底
守护进程提醒 启动时 + 每 updateIntervalHours 小时（默认 6）检查，新版本推送手机
命令级提醒 其余命令（a4p status / a4p resume 等）检查，终端提示 + 手机推送
默认开关 开启（checkUpdates: true）
版本要求 自 1.3.0 起（守护进程推手机），命令级手机推送自 1.4.0 起
缓存文件 ~/.a4phone/update-cache.json

1.1 检查流程

graph LR A[命令执行
或守护进程周期] --> B{开启检查
checkUpdates} B -->|否| C[跳过] B -->|是| D{限频未到期
且版本未变} D -->|是| E[跳过
不访问网络] D -->|否| F[查询 npm registry
npmmirror 优先] F --> G{查询成功} G -->|否| H[记录背退时间
30 分钟后重试] G -->|是| I{有新版本
且未提醒过} I -->|是| J[提醒
手机 / 终端] J --> K[记录 knownLatest
同版本不再提醒] I -->|否| L[仅记录检查时间] style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style C fill:#fdebd0,stroke:#b7950b,stroke-width:2px style D fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style E fill:#fdebd0,stroke:#b7950b,stroke-width:2px style F fill:#ffecd6,stroke:#e67e22,stroke-width:2px style G fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style H fill:#fadbd8,stroke:#c0392b,stroke-width:2px style I fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style J fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style K fill:#fdebd0,stroke:#b7950b,stroke-width:2px style L fill:#fdebd0,stroke:#b7950b,stroke-width:2px

2. 提醒渠道

场景 提醒方式 消息内容
守护进程（a4p listen） 推送手机（标题 a4phone） 新版本号 + 升级命令
其他命令（a4p status / a4p resume 等） 终端提示 + 推送手机 新版本号 + 升级命令
跳过场景 不检查 hook（AI 热路径）、--version、help、listen --daemon-child（守护进程自管）

手机提醒示例：

a4phone
检测到新版本 1.4.2（当前 1.3.0）

请运行：npm install -g a4phone 升级

3. 限频与去重

3.1 限频规则

规则 说明
检查间隔 updateIntervalHours（默认 6 小时），守护进程周期检查与命令级限频共用
命令级超时 命令路径使用 3 秒短超时，避免离线/慢网下命令进程被挂起的 fetch 拖住退出
查询失败背退 失败后 30 分钟（FAIL_RETRY_MS）内不重试网络，避免每次命令都访问网络

3.2 去重规则

  • 缓存 knownLatest 记录已提醒过的版本，同一新版本只提醒一次
  • 提醒失败（手机推送失败）不标记已提醒，下次检查自动重试
  • 查询失败不记录检查时间（下个周期仍会尝试）

3.3 版本升级后忽略限频

自 1.4.2 起，缓存会记录本地版本号（version 字段）。当本地版本升级后，忽略旧的 lastCheck 限频立即检查——避免旧缓存把升级后的首次检查推迟一整个间隔（否则升级后要等 6 小时才能收到下一次更新提醒）。

4. 配置

在 ~/.a4phone/config.json 中调整：

{
  "checkUpdates": true,
  "updateIntervalHours": 6
}
配置项 默认值 说明
checkUpdates true 设为 false 完全关闭更新检查
updateIntervalHours 6 检查间隔（小时）

关闭检查或升级后，需用新版本代码运行守护进程/命令（升级后 a4p listen --stop && a4p listen 重启守护进程）。

5. 常见问题

问：收不到更新提醒的常见原因？

答：最常见的原因是本地 a4p 版本低于 1.3.0（更新提醒功能本身未加入）；其次检查 checkUpdates 是否被设为 false，以及更新缓存 lastCheck 是否把升级后的首次检查推迟了（1.4.2 已修复该问题）。

问：查询失败会影响正常功能吗？

答：不会。registry 查询失败静默跳过（国内网络可能连不上 npm 官方源，npmmirror 优先已尽量规避），不影响任何正常功能。

问：守护进程与命令会重复提醒吗？

答：不会。两者共用同一 update-cache.json 的 knownLatest 去重，同一新版本只会提醒一次。