# Gateway 升级说明

适用范围：`remote-vibecoding-gateway`

## 升级前确认

- 现有数据目录已经保留
- `.env` 中的账号、密码、token、挂载目录配置已确认
- 新镜像 tag 或新代码版本已经准备好

## 标准升级步骤

### Docker 部署

1. 更新镜像版本

把 `.env` 里的：

```bash
RCODEX_GATEWAY_IMAGE=rcodexlab/rcodex-gateway:<旧版本>
GATEWAY_VERSION=<旧版本>
```

改成目标版本，例如：

```bash
RCODEX_GATEWAY_IMAGE=rcodexlab/rcodex-gateway:1.2.40
GATEWAY_VERSION=1.2.40
```

2. 拉取并重启

```bash
docker compose pull
docker compose up -d
```

3. 验证服务

```bash
curl http://127.0.0.1:8787/healthz
curl http://127.0.0.1:8787/rcodex/version.json
```

### 脚本常驻启动

如果你是直接在 Ubuntu 主机里跑仓库代码：

```bash
cd /data/remote_vibecoding_app
./scripts/gateway_service.sh restart
./scripts/gateway_service.sh status
```

## 这次版本需要注意什么

`1.2.40` 是一次 App 与 Gateway 联合重要更新：Gateway 修复启动阶段全量加载历史事件导致的 OOM 问题，不再读取所有会话 JSONL；会话事件、摘要、控制台和小组件统一使用近期轮次读取，token 统计继续使用持久化账本。Docker 部署建议升级到 `rcodexlab/rcodex-gateway:1.2.40`；App 同步发布 `1.2.40`。

`1.2.39` 是一次 App 端发布版本：本次版本优化首页主色一致性、小组件 token 汇总展示和会话状态密度。 Gateway 可继续保持 `1.2.38`。

`1.2.38` 是一次 Gateway 发布入口补齐版本：Gateway 新增 `/rcodex/*.ipa` 发布文件下载支持，版本清单新增 `app.ipaUrl`，官网下载区新增 iOS IPA 入口和二维码。App latest 继续保持 `1.2.35`，Android APK 入口不变。

`1.2.37` 是一次 Gateway 状态机修复版本：修正 `1.2.36` 中授权待办和会话运行生命周期耦合过紧的问题。手动批准、自动授权和底层 active 事件都会让会话回到执行中；其他 pending 授权仍保留在授权列表里，不再把会话卡成待授权或影响空闲/进行中判断。App 可继续使用 `1.2.35`。

`1.2.36` 是一次 Gateway 授权流程修复版本：同一会话同时出现多个授权请求时，批准其中一个不会再把其他待授权请求自动结算为拒绝；Gateway 会在仍有待授权项时继续保持等待授权状态，旧数据中处于运行态但仍 pending 的授权也可以继续处理。App 可继续使用 `1.2.35`。

`1.2.35` 是一次 App 端发布版本：本次版本修复小组件和通知图标展示。 Gateway 可继续保持 `1.2.31`。

`1.2.34` 是一次 App 端发布版本：本次版本优化 App 端品牌图标、桌面小组件和后台通知展示。 Gateway 可继续保持 `1.2.31`。

`1.2.33` 是一次 App 端发布版本：移动端图标安全距离优化：Android 与 iOS App 图标还原内缩白色圆角卡片效果。 Gateway 可继续保持 `1.2.31`。

`1.2.32` 是一次 App 端发布版本：品牌图标更新：App 使用新版 rCodex Logo，并同步优化登录与桌面端显示。 Gateway 可继续保持 `1.2.31`。

`1.2.31` 是一次 Gateway 端生成图片自动展示版本：Gateway 会在每轮任务开始前记录 `~/.codex/generated_images` 快照，助手最终回复完成时把本轮新增图片复制到当前会话工作区 `.rcodex/generated-images/<sessionId>/`，并追加成 Markdown 图片。移动端 App `1.2.30` 已支持 Markdown 图片和会话图片代理，因此无需重新打 APK；升级 Gateway 后即可让 LLM 生成图片自动显示在聊天气泡里。

`1.2.30` 是一次 App 与 Gateway 联合聊天图片显示版本：App 会在会话中展示用户上传图片附件的缩略图和全屏预览，也会直接渲染助手回复里的 Markdown 图片；Gateway 新增受登录态保护的 `/sessions/:id/images?path=...` 图片代理接口，只允许读取当前会话工作区内的图片文件，并限制为 `png/jpg/jpeg/gif/webp`。App `1.2.30` 依赖 Gateway `1.2.30` 的相对路径图片代理能力，建议 App 与 Gateway 同步升级。

`1.2.29` 是一次 App 与 Gateway 联合登录安全加固版本：Gateway 新增 `/auth/captcha`，`/auth/login` 统一要求 `captchaId/captchaAnswer`；Web 管理台和移动端 App 登录页都会展示并提交同一套图形验证码。验证码为短时一次性挑战，服务端只保存加盐 hash。App `1.2.29` 依赖 Gateway `1.2.29` 的验证码接口，旧 App 也无法通过新 Gateway 登录，建议 App 与 Gateway 同步升级。

`1.2.15` 是一次 Gateway Web 战报页修复版本：`/console-api/summary` 新增 `usagePeriods`，可按 Today、7 天、14 天、30 天和 All 聚合真实 token 用量；Web 战报页修复缺失 DOM 导致部分数据不填充的问题，并让 Token 轨道时间范围切换真正刷新总量、成本、会话数、均值、峰值和趋势图。建议使用 Web 管理台的用户升级 Gateway 到 `1.2.15`，App 可继续使用 `1.2.28`。

`1.2.14` 是一次 Gateway Web 管理台版本：Gateway 新增 `/console` 静态管理台和 `/console-api/summary` 聚合接口，可在浏览器里查看总览、任务、用量、工作区、模型、授权和体检视图；管理台沿用现有 Gateway 登录认证，首版保持只读，不新增写操作。需要在浏览器访问 Web 管理台的用户建议升级 Gateway 到 `1.2.14`，App 可继续使用 `1.2.28`。

`1.2.28` 是一次 App 端发布版本：移动端修复英文界面会话概览固定中文残留。 Gateway 可继续保持 `1.2.13`。

`1.2.27` 是一次 App 端发布版本：移动端补齐双语遗留中文文案，并收敛设置与模型标签来源。 Gateway 可继续保持 `1.2.13`。

`1.2.26` 是一次 App 端发布版本：移动端新增中英文界面切换，并优化英文紧凑文案。 Gateway 可继续保持 `1.2.13`。

`1.2.13` 是一次 Gateway 与桌面看板联动版本：Gateway 会记录看板 `boardUrl`，配对结果会把看板地址回传给 App；桌面信息台摘要补齐 provider/model 字段，ESP32 大屏可展示更完整的当前任务信息。建议使用桌面看板固件的用户同步升级 Gateway 到 `1.2.13`，App 可继续使用 `1.2.25`。

`1.2.25` 是一次 App 端发布版本：修复桌面看板扫码可靠性。 Gateway 可继续保持 `1.2.12`。

`1.2.24` 是一次 App 端发布版本：修复桌面看板扫码初始化异常。 Gateway 可继续保持 `1.2.12`。

`1.2.23` 是一次 App 端发布版本：新增桌面看板扫码绑定能力。 Gateway 可继续保持 `1.2.12`。

`1.2.22` 是一次 App 端发布版本：本次版本新增会话概览和文件改动审阅能力。 Gateway 可继续保持 `1.2.12`。

`1.2.12` 是一次 App 与 Gateway 联合会话概览和文件改动审阅版本：Gateway 新增 `/sessions/:id/summary`、`/sessions/:id/changes` 和 `/sessions/:id/changes/diff`，App 会话详情将“信息”升级为“概览”，文件页拆为“改动 / 文件”，默认只加载轻量摘要和改动 metadata，单文件 diff 需要点开后按需分页加载。建议 App 升级到 `1.2.22` 时同步升级 Gateway 到 `1.2.12`。

`1.2.21` 是一次 App 端发布版本：本次版本优化会话消息气泡的显示密度和用户消息配色。 Gateway 可继续保持 `1.2.11`。

`1.2.11` 是一次 Gateway 端补齐版本：新增 `/filesystem/workspace/search`，并支持继续会话/运行中插话携带 `workspaceFileRefs`。Gateway 会在服务端校验引用路径必须位于当前会话工作区内，拒绝路径穿越、符号链接和超限文件，再把文件内容按边界追加到本轮 prompt。建议使用 App `1.2.20` 的工作区文件引用功能时同步升级到 Gateway `1.2.11`。

`1.2.20` 是一次 App 端发布版本：本次版本支持会话内引用工作区文件，并修复消息气泡浅色主题显示。基础会话和主题修复可继续使用 Gateway `1.2.10`；工作区文件引用需要 Gateway `1.2.11` 后才完整可用。

`1.2.19` 是一次 App 端发布版本：本次版本优化会话详情交互、消息复制和深色模式可读性。 Gateway 可继续保持 `1.2.10`。

`1.2.18` 是一次 App 与 Gateway 联合后台守候状态展示版本：App 后台守候常驻通知会展示当前主任务标题和最新活动摘要；Gateway `/widget/summary` 同步增强 `activitySummary`，会优先返回待处理、最新回复、命令输出、命令完成、代码变更和线程状态。建议 App 升级到 `1.2.18`，Gateway 同步升级到 `1.2.10`。

`1.2.17` 是一次 App 端发布版本：Android 后台守候常驻通知稳定性修复版本。 Gateway 可继续保持 `1.2.9`。

`1.2.16` 是一次 App 端发布版本：登录连接和首页刷新体验优化版本。 Gateway 可继续保持 `1.2.9`。

`1.2.15` 是一次 App 端发布版本：本次版本回退液态玻璃 UI，恢复会话详情页玻璃化前的稳定布局。 Gateway 可继续保持 `1.2.9`。

`1.1.15` 是一次 App 端发布版本：本次版本重点优化会话详情页液态玻璃视觉体验。 Gateway 可继续保持 `1.2.9`。

`1.1.14` 是一次 App 端发布版本：移动端界面与主题体验优化小版本。 Gateway 可继续保持 `1.2.9`。

`1.1.13` 是一次 App 端发布版本：回滚后的独立 APK 包，用于刷新下载地址与缓存。 Gateway 可继续保持 `1.2.9`。

`1.2.9` 是一次 App 与 Gateway 联合文件浏览和授权状态修复版本：App 会话详情页新增当前工作区文件浏览入口，可在“信息 / 诊断”后进入目录树并按需阅读 `md/markdown/txt/log` 文档；Gateway 新增受登录态保护的工作区文件列表与读取接口，只允许访问当前会话 `workspacePath` 内的相对路径，并拒绝绝对路径、上探、符号链接和非文档文件。同时 Gateway 会清理已离开等待授权态会话中的过期 pending approval，App 在授权提交失败后会重新同步状态，避免前端授权卡片卡住。建议 App 与 Gateway 同步升级到 `1.2.9`。

`1.2.8` 是一次 Gateway 端补丁版本：Gateway 会在输出 `item/completed` 正文时自动把白名单相对路径转成显式 `rcodex-doc:` 链接，方便 App 直接点开私有项目文档。App 可继续保持 `1.2.7+58`，无需同步升级。建议 Docker / 离线包用户升级到 `1.2.8`。

`1.2.7` 是一次 App 与 Gateway 联合私有文档阅读版本：Gateway 新增受登录态保护的 `/documents/private/read` 接口，会按当前会话的 `workspacePath` 读取项目内白名单 Markdown / 文本文档；App 会把对话中的 `docs/plans`、`docs/research`、`docs/ops` 和 `process_log.md` 引用转成可点击入口，点击后再拉取正文并用内置阅读器展示。私有项目文档不走公开静态目录，也不会提前预加载正文。建议 App 与 Gateway 同步升级到 `1.2.7`。

`1.2.6` 是一次 App 端发布版本：新增移动端字体大小设置。 Gateway 可继续保持 `1.2.5`。

`1.2.5` 是一次 App 与 Gateway 联合模型选择体验版本：App 模型配置弹层改为打开后在弹层内加载模型列表，选择模型不再导致列表跳动，并显示具体默认模型名；Gateway Docker 镜像同步发布 `rcodexlab/rcodex-gateway:1.2.5`，`/models` 会优先通过 `codex debug models` 读取服务器 Codex 当前真实可用模型目录，失败时再回退到环境变量和历史会话模型。

`1.2.4` 是一次 App 与 Gateway 联合模型配置升级版本：Gateway 新增 `/models` 认证接口，会按 provider 下发 `CODEX_AVAILABLE_MODELS`、`CLAUDE_AVAILABLE_MODELS`、`CLAUDE_DEFAULT_MODEL` 和历史会话中出现过的模型；App 的新建会话与会话详情模型配置弹层改为从 Gateway 拉取模型并单选，不再手输模型 ID。本轮按要求暂不构建 Gateway Docker 离线包，Docker 部署用户请等待后续镜像包发布；源码或本机脚本部署可同步升级到 `1.2.4` 测试。

`1.2.3` 是一次 App 端发布版本：会话详情操作条视觉优化 Gateway 可继续保持 `1.2.1`。

`1.2.2` 是一次 App 端发布版本：会话详情顶部栏优化 Gateway 可继续保持 `1.2.1`。

`1.2.1` 是一次 App 与 Gateway 联合会话管理升级版本：Gateway 新增会话级模型配置、推理强度透传、会话恢复失败显式状态、历史重建、同会话并发保护和本轮 token 统计口径修正；App 端提供操作式模型配置入口，并在会话详情页按整轮需求过程展示 token 消耗。本次 Gateway Docker runtime 继续按无源码分发口径裁剪，最终镜像不携带项目 `src/`、测试构建产物和 TypeScript 源文件。建议 App 与 Gateway 同步升级到 `1.2.1`。

`1.1.50` 是一次 Gateway Docker 分发修复版本：多阶段构建后的 runtime 镜像不再携带 `services/gateway/src` 等源码，只保留 `dist`、生产依赖和运行时必需的 `deploy/version` 文档；同时修正容器内工作目录，确保版本清单与升级说明仍可正常读取。建议所有使用 Docker / 离线镜像包部署 Gateway 的用户尽快升级到 `1.1.50`。Android App 可继续保持 `1.1.49`。

`1.1.49` 是一次 App 与 Gateway 联合传输优化版本：Gateway 默认轻量下发会话事件，历史事件会压缩流式 delta、重复状态快照、diff 和命令输出；App 端默认关闭原始事件并在发送任务后立即显示等待反馈。建议 App 与 Gateway 同步升级到 `1.1.49`。

`1.1.48` 是一次 App 端发布版本：本次版本修复首页设置菜单和二级页面重复打开问题。 Gateway 可继续保持 `1.1.45`。

`1.1.47` 是一次 App 端发布版本：本次版本优化移动端操作层级和更新说明阅读体验。 Gateway 可继续保持 `1.1.45`。

`1.1.46` 是一次 App 端发布版本：本次版本优化会话信息与会话诊断的阅读体验。 Gateway 可继续保持 `1.1.45`。

`1.1.45` 是一次 App 与 Gateway 联合连接体验版本：App 设置页新增“网关连接”，可配置主地址和局域网地址，并支持自动优先局域网、只用主地址、只用局域网三种模式；HTTP 请求、WebSocket、后台守候和 Android 桌面小组件统一使用同一套连接策略。Gateway 同步发布 `1.1.45` 镜像和离线包，便于 Docker 部署、回滚和诊断时保持 App/Gateway 版本一致。

`1.1.44` 是一次 App 与 Gateway 联合小组件可靠性版本：Android 小组件在 Gateway 瞬时不可达时会保留最近一次成功状态并在恢复后主动刷新；Gateway usage ledger 升级为 v2，新增原始 token 的总累计、7 日累计、今日累计和最近 12 小时趋势，避免 cached input 被扣除后累计明显偏小。建议 App 与 Gateway 同步升级到 `1.1.44`。本次默认只本地构建 Gateway 镜像和离线包，不自动推送 Docker Hub。

`1.1.43` 是一次 App 与 Gateway 联合传输优化版本：会话详情页 WebSocket 会按当前会话订阅，减少其他 session 输出误传；App 设置页新增“详细原始事件”开关，默认开启，用户主动关闭后 Gateway 会保留聊天、命令、代码变更、授权摘要等主阅读内容，同时减少底层 raw payload 传输。建议 App 与 Gateway 同步升级到 `1.1.43`。

`1.1.42` 是一次 App 端发布版本：本次版本修复继续追问后的标题和通知文案展示。 Gateway 可继续保持 `1.1.37`。

`1.1.41` 是一次 App 端发布版本：本次版本优化会话详情页系统事件单行视觉，让标签、摘要和展开图标对齐更舒适。 Gateway 可继续保持 `1.1.37`。

`1.1.40` 是一次 App 端发布版本：本次版本进一步压缩会话详情页系统事件展示，减少长会话滚动占用。 Gateway 可继续保持 `1.1.37`。

`1.1.39` 是一次 App 端长会话阅读和提醒增强版本：会话详情页的系统事件统一改为更紧凑的日志行，减少大块卡片背景对正文阅读的干扰；提示音链路也扩展为“声音 + 震动”，Android 前台提醒、后台守候提醒和 iOS 前台触感反馈均已覆盖。Gateway 可继续保持 `1.1.37`。

`1.1.38` 是一次 App 端长会话浏览体验优化版本：会话详情页顶部标题区域支持点击回到顶部，右下角“回到最新”继续负责返回底部。Gateway 可继续保持 `1.1.37`。

`1.1.37` 是一次附件体验修复版本：Gateway 会按 UTF-8 解析 multipart 文件名，修复中文附件名被保存成乱码、进而污染 prompt 附件标题的问题；App 会话输入区和用户消息气泡中的附件名称改为最多 3 行展示，长文件名不再只露出一小段。建议 App 与 Gateway 同步升级到 `1.1.37`。

`1.1.36` 是一次附件能力增强版本：Gateway 会允许 `.docx`、`.xlsx` 上传，并在附件落盘后生成 `.extracted.txt` 可读文本；Word 抽取正文，Excel 按 sheet 抽取表格行，prompt 会同时提供原始文件和抽取文本路径。建议 App 与 Gateway 同步升级到 `1.1.36`。旧版 `.doc`、`.xls` 暂未支持，请先另存为现代 Office 格式。

`1.1.35` 是一次 App 与 Gateway 联合版本：会话详情页新增附件选择和发送能力；Gateway 新增 `/sessions/:id/attachments` 上传接口，附件保存到当前 workspace 的 `.rcodex/attachments/<sessionId>/`，继续会话和运行中插话会把附件路径注入 prompt；Codex 图片附件会额外传入 `localImage` 获得原生视觉理解。建议 App 与 Gateway 同步升级到 `1.1.35`。本次仍不自动推送 Docker Hub 镜像。

`1.1.34` 是一次 App 端后台提醒增强版本：新增可手动开启/关闭的“后台守候”前台服务，通知栏常驻展示执行中和待处理状态，并复用 `/widget/summary` 在锁屏后尽量同步任务信息；同时补齐会话详情页通过轮询看到完成态时不播放提示音的问题。Gateway 可继续保持 `1.1.32`。

`1.1.33` 是一次 App 端声音修复版本：确认 `1.1.32` APK 已包含通知权限和通知通道代码，但会话完成事件只依赖通知渠道发声，部分 ROM 或通知渠道设置会导致“试听有声、完成无声”。本版改为事件到达时主动播放系统默认通知音，并用静音通知渠道展示通知卡片。Gateway 可继续保持 `1.1.32`。

`1.1.32` 是一次 App 与 Gateway 联合版本：Gateway 新增本地 token usage ledger，重启后会从历史 events 重建用量账本，并持续写入 `usage-ledger.json`；Android 小组件改为优先展示全局累计 token 和今日用量，不再把主会话 token 当作总量。App 同时包含 `1.1.31` 的系统通知音修复和后台会话完成提醒修复。建议 App 与 Gateway 同步升级到 `1.1.32`。本次仍不自动推送 Docker Hub 镜像。

`1.1.31` 是一次 App 端通知体验版本：关键状态提示音从媒体流短 beep 切换为 Android 系统默认通知音，并补齐 Android 13+ 通知权限申请；授权申请、任务完成、任务失败会走系统通知渠道提醒。Gateway 可继续保持 `1.1.30`。

`1.1.30` 是一次 App 与 Gateway 联合体验版本：Android 小组件升级为“小伙伴 + 任务摘要 + token 曲线”的任务雷达，App 前台事件会主动刷新小组件；Gateway `/widget/summary` 增加活动摘要，并把小组件 token 趋势改为有效 token 统计。建议同步升级 Gateway 到 `1.1.30`。Docker Hub 镜像不再随每次发版自动推送，除非明确执行镜像发布。

`1.1.29` 是一次 App 与 Gateway 联合版本：App 新增 Android 桌面小组件首版，可在桌面查看待处理、执行中、主任务和 token 摘要；Gateway 新增 `/widget/summary` 聚合接口供小组件使用；提示音节奏也做了延长，授权、完成、失败提示更容易被感知。

`1.1.28` 是一次 App 与 Gateway 联合修复版本：Gateway 修复重启后把 App 内新建的 Claude Code 会话误判成“仅回看”的问题；App 把关键状态提示音改为更可靠的 Android 原生 ToneGenerator，解决部分国产 Android 机型试听无声的问题；同时继续保留 Claude Code 流式 JSON 过滤能力。建议同步升级 Gateway 到 `1.1.28`。

`1.1.27` 是一次 App 与 Gateway 联合修复版本：App 过滤 Claude Code 流式输出里的 `threadId/turnId/itemId` 结构化 JSON，只展示助手正文；Gateway 修复重启后把 App 内新建的 Claude Code 会话误判成“仅回看”的问题；同时 App 把关键状态提示音改为更可靠的 Android 原生 ToneGenerator，并在诊断页增加试听入口。建议同步升级 Gateway 镜像到 `rcodexlab/rcodex-gateway:1.1.27`。

`1.1.26` 是一次 App 端体验优化版本，整理首页设置入口、自动授权规则页列表/loading，以及会话详情页首次进入贴底滚动。

`1.1.25` 是 `1.1.24` 的清理重构建版本，用于修复发布流程中 Gradle 二次 assemble 复用旧 Flutter native 产物导致的“版本号新、UI 旧”问题。

`1.1.24` 是一次 App 端首页和诊断入口整理版本，自动授权规则改为首页独立入口，诊断页去掉网关概况和规则卡。

`1.1.23` 是 `1.1.22` 的清理重构建版本，用于排除安装包缓存和 Flutter/Gradle 增量构建缓存导致的旧 UI 残留。

`1.1.22` 是一次 App 端体验优化小版本，主要调整会话详情页滚动策略、前台关键状态提示音，以及首页新建会话输入区样式。

`1.1.21` 是本轮 Claude Code provider 正式并入主线后的统一发布版本，建议同时升级 App 安装包和 `rcodexlab/rcodex-gateway:1.1.21` 镜像，确保 provider 选择、Claude 历史导入、首页创建入口和版本清单保持一致。

从 `1.1.15` 开始，首页概览固定为单行四列，聊天流水中的授权结果改成折叠卡片，详细事件里不再展示助手回复流碎片。

从 `1.1.16` 开始，首页任务卡默认更紧凑，长任务描述会收进两行摘要；授权申请流水和授权处理弹窗也改成更清晰的折叠与审批面板样式。

从 `1.1.17` 开始，会话详情页右上角信息入口改为“会话信息”面板，当前进展、任务信息和用量会分区展示，不再显示研发过程说明。

从 `1.1.18` 开始，会话信息和详细事件弹窗都有固定关闭按钮，首页和会话详情页统一使用空闲、执行中、等待处理、阻塞四态状态小伙伴。

从 `1.1.19` 开始，Gateway 会从 Codex 本地 session jsonl 中解析真实模型名并下发给 App；会话详情页底部输入区会常驻显示状态小伙伴、模型名和 token 摘要。

从 `1.1.20` 开始，会话详情页底部输入区优先展示总用量，空闲态等状态说明改为短标签，避免长文案挤掉 token 摘要。

从 `1.1.21` 开始，Gateway 正式支持 Codex 与 Claude Code 双 provider 编排；首页新建会话入口支持直接选择 provider，并将原大创建卡片收敛为更紧凑的内联创建条。Claude Code 历史导入也已并入正式主线，但当前仍以“历史回看”为主，不支持继续执行。

从 `1.1.22` 开始，App 会在前台为授权申请、执行完成、执行失败播放关键状态提示音；会话详情页支持“离开底部后暂停自动滚动”，首页新建会话输入区也统一成与会话页一致的一体式输入框样式。

从 `1.1.23` 开始，App 安装包使用 clean build 重新产出，功能范围与 `1.1.22` 一致，主要用于解决手机侧仍看到旧 UI 的缓存问题。

从 `1.1.30` 开始，Android 小组件会展示小伙伴状态图、最近活动摘要和 token 曲线；App 在前台收到关键事件时会主动刷新小组件，桌面状态会比 `1.1.29` 更及时。

从 `1.1.29` 开始，Android 桌面可以添加 rCodex 小组件查看当前任务状态；小组件只展示状态并打开 App，不在桌面直接处理授权。Gateway 需要提供 `/widget/summary`，所以 App 和 Gateway 建议一起升级。

从 `1.1.28` 开始，App 内新建的 Claude Code 会话在 Gateway 重启后会保持“可继续”，只有从 Claude 本地归档导入的历史会话仍然是“仅回看”；关键状态提示音改为 Android 原生 ToneGenerator，优先走媒体音量通道。

从 `1.1.27` 开始，Claude Code 会话的流式助手消息会优先读取 `jsonPayload.delta`，不会再把包含 `threadId` 的结构化 `chunk` JSON 展示在对话气泡里；App 内新建的 Claude Code 会话在 Gateway 重启后也会继续保持“可继续”，只有从 Claude 本地归档导入的历史会话仍然是“仅回看”；如果手机听不到提示音，可在诊断页点击“试听提示音”验证媒体音量和静音状态。

从 `1.1.26` 开始，自动授权规则入口收敛到首页设置面板，规则列表增加卡片间距和骨架 loading；会话详情页首次进入会在 Markdown/卡片布局稳定后多次校准到底部。

从 `1.1.25` 开始，发布包必须以 clean 后的 `flutter build apk --release --flavor prod` 产物作为最终安装包，避免 `apps/mobile/android` 下单独执行 Gradle assemble 后覆盖成旧 Flutter AOT 内容。

从 `1.1.24` 开始，首页顶部状态胶囊只展示状态，设置入口统一承接诊断和账号动作；自动授权规则独立为首页按钮，任务筛选也改为更轻的横向文字 tab。

如果代码已经更新，但 gateway 没有重启到新进程，App 里点击文档入口时可能会看到：

- 网关接口不存在
- 文档加载失败

这通常不是地址填错，而是后台还在跑旧版本进程。重启 gateway 后即可恢复。

## 升级完成后的检查项

- `/protocol` 返回里应包含 `/documents/render`
- `/rcodex/version.json` 能返回最新版本清单
- `/rcodex/deploy.html` 能打开升级说明
- `/rcodex/releases/1.2.1.html` 能打开当前版本更新说明

## 回滚建议

如果升级后需要快速回退：

1. 回退镜像 tag 或代码版本
2. 同时回退 `GATEWAY_VERSION`
3. 重启 gateway
4. 确认 `version.json` 中的版本信息也一起回退，避免 App 继续提示错误版本