# Flash 与内存容量分析、风险及后续开发建议

> 历史容量快照：文中远程日志、`logfs` 和独立 `gifpack` 分区已从当前固件移除。下文的“当前”“建议”和旧构建步骤仅针对当时版本，不能作为现行操作指南。现行分区以 `16m.csv` 与最新构建报告为准，资源操作见 [应用内嵌素材使用与添加指南](../应用内嵌素材使用与添加指南.md)。

本文记录当前固件的 Flash 分区使用情况、静态 RAM 使用情况、运行时内存风险、可优化内容和后续开发约束，用于功能评审、资源接入、OTA 设计和长期容量管理。

历史 LittleFS 资源流程归档见：

- [`docs/littlefs-resource-build-flash-mount.md`](littlefs-resource-build-flash-mount.md)

## 1. 分析基线与数据边界

本次分析基于：

```text
分支：feature/st7789p3-new-board
提交：d5409ea
目标：ESP32-S3
ESP-IDF：v5.5.4
Flash 配置：16 MiB
分区表：16m.csv
应用镜像：build/TQ_Cat_Code.bin
链接映射：build/TQ_Cat_Code.map
资源镜像：build/gifpack.bin
```

当前 `build/` 目录中的应用产物生成于 2026-08-03，资源镜像生成于 2026-08-04。后续代码或资源变化后，应重新构建并更新本文数据。

需要明确区分两类数据：

### 1.1 本地构建可以准确得到的数据

- Flash 分区的地址和容量；
- 应用程序二进制大小；
- `gifpack` 镜像大小；
- LittleFS 镜像内的文件数量、文件内容大小和已用块数；
- 静态 IRAM、D/IRAM、`.data`、`.bss` 使用量；
- 链接阶段放入 PSRAM 的静态 BSS 大小。

### 1.2 必须连接设备运行后才能得到的数据

- 芯片实际检测到的 PSRAM 总容量；
- 启动完成后的内部堆剩余量；
- PSRAM 剩余量；
- 最小历史空闲堆；
- 最大连续内部内存块；
- 最大连续 DMA 内存块；
- 每个任务的真实栈高水位；
- Wi-Fi、TLS、WebSocket、音频同时工作时的峰值占用；
- `logfs`、`model`、`coredump` 在具体设备上的真实内容和占用。

因此，本文的静态分析可以判断容量趋势和结构性风险，但不能替代真机峰值内存测试。

## 2. Flash 总体布局

设备使用 16 MiB Flash：

```text
16 MiB = 16,777,216 bytes = 0x1000000
```

`16m.csv` 已经把全部 16 MiB 空间分配完毕，没有未划分空间。

| 区域 | 地址范围 | 分配大小 | 占 Flash 比例 | 用途 |
| --- | ---: | ---: | ---: | --- |
| Bootloader、分区表、NVS、OTA data、PHY | `0x000000-0x010000` | 64 KiB | 0.39% | 系统启动和持久化基础数据 |
| `gifpack` | `0x010000-0xA90000` | 10.5 MiB | 65.63% | LCD 图片和提示音 LittleFS |
| `logfs` | `0xA90000-0xAD0000` | 256 KiB | 1.56% | 远程日志落盘队列 |
| `ota_0` | `0xAD0000-0xCA0000` | 1.8125 MiB | 11.33% | 应用 OTA 槽位 0 |
| `ota_1` | `0xCA0000-0xE70000` | 1.8125 MiB | 11.33% | 应用 OTA 槽位 1 |
| `model` | `0xE70000-0xFF0000` | 1.5 MiB | 9.38% | 模型数据分区 |
| `coredump` | `0xFF0000-0x1000000` | 64 KiB | 0.39% | 崩溃转储 |

Flash 布局可以简化为：

```text
0x000000
├── 系统区域        64 KiB
├── gifpack       10.5 MiB
├── logfs          256 KiB
├── ota_0        1.8125 MiB
├── ota_1        1.8125 MiB
├── model          1.5 MiB
└── coredump        64 KiB
0x1000000
```

## 3. 应用程序 Flash 使用情况

单个 OTA 应用分区大小：

```text
0x1d0000 = 1,900,544 bytes = 1.8125 MiB
```

当前应用二进制：

```text
build/TQ_Cat_Code.bin
实际文件大小：1,657,280 bytes
```

链接工具报告：

```text
Flash .text：   1,134,436 bytes
Flash .rodata：   388,744 bytes
其他：                256 bytes
Flash 非 RAM 合计：1,523,436 bytes
总镜像大小：      1,657,135 bytes
最终 .bin：       1,657,280 bytes
```

单个 OTA 槽位占用：

```text
使用率：87.20%
剩余：243,264 bytes
     ≈ 237.56 KiB
```

两个 OTA 槽位必须具有相同容量。`ota_1` 即使当前没有运行，也不能简单视为空闲空间，因为 OTA 升级需要把新固件完整写入另一个槽位，并保留切换和回滚能力。

### 3.1 应用分区风险判断

风险等级：**高**。

原因：

- 当前只剩约 238 KiB；
- 新增网络库、编解码库、证书、字体或大型只读表可能快速消耗空间；
- Debug 配置、日志字符串和完整证书包都会增加镜像；
- OTA 要求每个新版本都必须装入同样大小的备用槽；
- 链接成功不代表长期有充足增长空间。

建议设置容量门槛：

| 使用率 | 建议处理 |
| ---: | --- |
| `< 80%` | 正常 |
| `80%-85%` | 开始跟踪增长趋势 |
| `85%-90%` | 构建警告；每个新增依赖必须解释体积影响 |
| `>= 90%` | 阻止普通功能合入，先做容量治理 |

当前 87.20%，已经处于“必须持续跟踪”的区间。

## 4. `gifpack` 资源分区使用情况

`gifpack` 分区容量：

```text
0xa80000 = 11,010,048 bytes = 10.5 MiB
```

当前临时资源目录中：

| 资源类型 | 文件数 | 文件内容大小 |
| --- | ---: | ---: |
| LCD RLE | 41 | 9,379,380 bytes |
| Opus 提示音 | 30 | 378,918 bytes |
| 合计 | 71 | 9,758,298 bytes |

读取 `gifpack.bin` 的 LittleFS 块信息后：

```text
块大小：4,096 bytes
总块数：2,688
已用块：2,426
空闲块：262

LittleFS 已用：9,936,896 bytes ≈ 9.48 MiB
LittleFS 空闲：1,073,152 bytes ≈ 1.02 MiB
使用率：90.25%
```

资源文件内容为约 9.31 MiB，LittleFS 已用空间约 9.48 MiB，两者差值来自目录、索引、元数据、块对齐和文件系统管理开销。

`build/gifpack.bin` 的文件大小始终等于整个分区大小，即 10.5 MiB。不能通过 `ls -lh build/gifpack.bin` 判断资源真实占用，因为镜像会填充到分区全尺寸。

### 4.1 资源分区风险判断

风险等级：**高**。

原因：

- 当前使用率已经超过 90%；
- 理论空闲约 1.02 MiB，实际新增文件还需要 LittleFS 管理开销；
- 动画通常一次增加多帧，每帧可能为 200-380 KiB；
- 新增 3-5 张全屏 RLE 图片就可能耗尽剩余空间；
- 资源分区没有 A/B 设计，未来直接在线更新存在断电损坏风险；
- 普通应用 OTA 不会更新 `gifpack`，容易出现应用代码与资源版本不匹配。

建议容量门槛：

| 使用率 | 建议处理 |
| ---: | --- |
| `< 80%` | 正常 |
| `80%-90%` | 新增资源必须记录大小 |
| `90%-95%` | 高风险；新增动画前必须优化或清理 |
| `>= 95%` | 阻止资源合入 |

当前 90.25%，已经进入高风险区间。

## 5. 当前完整烧录包含什么

当前 `build/flasher_args.json` 登记：

```text
0x000000  bootloader/bootloader.bin
0x008000  partition_table/partition-table.bin
0x00D000  ota_data_initial.bin
0x010000  gifpack.bin
0xAD0000  TQ_Cat_Code.bin
```

常规完整烧录会写入：

- Bootloader；
- 分区表；
- OTA 初始状态；
- `gifpack` 资源镜像；
- `ota_0` 应用程序。

以下分区没有预生成镜像加入当前完整烧录清单：

- `logfs`：设备运行时挂载、格式化和写入；
- `ota_1`：应用 OTA 时写入；
- `model`：需要独立的模型写入流程；
- `coredump`：设备崩溃时写入。

因此，本地构建无法判断具体设备上这几个动态分区的真实使用量。

## 6. 静态 RAM 使用情况

链接映射报告：

| RAM 区域 | 已使用 | 总容量 | 剩余 | 使用率 |
| --- | ---: | ---: | ---: | ---: |
| 独立 IRAM | 16,384 B | 16,384 B | 0 B | 100% |
| D/IRAM | 173,387 B | 341,760 B | 168,373 B | 50.73% |
| PSRAM 静态 BSS | 14,056 B | 取决于硬件 | 未知 | 未知 |

D/IRAM 组成：

```text
.data： 23,944 bytes
.bss：  56,072 bytes
.text： 93,371 bytes
合计： 173,387 bytes
剩余： 168,373 bytes ≈ 164.43 KiB
```

其中：

- `.data`：有初始值的全局和静态变量；
- `.bss`：零初始化的全局和静态变量；
- `.text`：必须驻留 RAM 执行的函数；
- 剩余 D/IRAM 会参与形成运行时可用内部内存，但启动后还会被任务栈、DMA、驱动和堆分配继续使用。

### 6.1 IRAM 风险

独立 IRAM 当前为：

```text
.text：    15,356 bytes
.vectors：  1,028 bytes
合计：     16,384 bytes
剩余：          0 bytes
```

风险等级：**高**。

这不表示设备运行时马上耗尽普通堆，但意味着独立 IRAM 链接区域没有静态增长余量。后续新增以下内容必须谨慎：

- `IRAM_ATTR` 函数；
- ISR 中必须执行的代码；
- Flash cache 关闭期间仍需运行的函数；
- 驱动要求放入 IRAM 的回调；
- 性能优化时强制进入 IRAM 的热点代码。

不要为了普通性能优化随意添加 `IRAM_ATTR`。添加后必须重新运行 size 分析并检查链接结果。

### 6.2 D/IRAM 风险

静态使用率约 50.7%，从链接角度尚可，但运行时内部 RAM 压力预计较高，因为以下内容不能完全依赖 PSRAM：

- Wi-Fi 和部分 lwIP 缓冲；
- SPI/I2S DMA 描述符和 DMA 缓冲；
- TLS 硬件 AES bounce buffer；
- 中断相关数据；
- 部分 FreeRTOS 和驱动对象；
- 显式创建在内部 RAM 的任务栈；
- 小于内部优先阈值的普通分配。

风险等级：**中高**，需要真机峰值数据确认。

## 7. PSRAM 配置与使用策略

当前配置启用：

```text
Octal PSRAM
80 MHz
启动初始化
加入 malloc 堆
允许 BSS 放入外部内存
允许任务栈放入外部内存
Wi-Fi/lwIP 尝试使用 PSRAM
```

关键参数：

```text
CONFIG_SPIRAM_USE_MALLOC=y
CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL=4096
CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL=32768
```

设计意图：

- 大型普通内存申请可以进入 PSRAM；
- 较小申请倾向内部 RAM；
- 为 DMA 和硬件驱动保留 32 KiB 内部 RAM；
- 音频、WebSocket、HTTP 等大栈和队列优先放入 PSRAM。

链接阶段已有约 13.7 KiB BSS 放入 PSRAM。

### 7.1 当前未知项

配置使用自动 PSRAM 类型检测，没有在项目中写死物理容量。必须查看真机启动日志或调用 `esp_psram_get_size()` 才能确认实际是 2、4 还是 8 MiB。

风险等级：**中**。

后续量产前必须把实际模组型号、PSRAM 容量和启动检测结果纳入硬件验收，避免开发板和量产板容量不同。

## 8. 运行时主要内存消费者

### 8.1 项目任务栈

当前较大的显式任务栈：

| 任务 | 配置栈 | 默认内存策略 |
| --- | ---: | --- |
| 音频采集 | 32 KiB | PSRAM 优先，失败回退内部 RAM |
| 音频发送 | 12 KiB | PSRAM 优先，失败回退内部 RAM |
| 音频播放 | 12 KiB | PSRAM 优先，失败回退内部 RAM |
| WebSocket ordered worker | 12 KiB | PSRAM 优先 |
| WebSocket client | 8-32 KiB 候选 | 第三方组件内部创建，主要消耗内部 RAM |
| LCD 渲染 | 12 KiB | 内部 RAM |
| Wi-Fi 状态 | 12 KiB | 内部 RAM |
| LAN HTTP | 8 KiB | PSRAM 优先 |
| 远程日志 | 8 KiB | 内部 RAM |
| 每日运势 | 6 KiB | 内部 RAM |
| 多模态 watchdog | 6 KiB | 内部 RAM |
| 系统事件 | 4 KiB | 内部 RAM |
| 按键 | 4 KiB | 内部 RAM |
| 模型命令 | 4 KiB | PSRAM 优先 |

仅项目显式任务的配置栈总量已经超过 130 KiB。除此之外，ESP-IDF 还会创建：

- main task；
- 两个 IDLE task；
- timer task；
- system event task；
- Wi-Fi task；
- TCP/IP task；
- HTTP/WebSocket 内部任务；
- 驱动相关任务。

不能把所有配置栈简单相加后与静态剩余 RAM 比较，因为：

- 一部分任务不同时存在；
- 一部分栈优先放入 PSRAM；
- 任务控制块和队列还有额外开销；
- 第三方组件可能自行创建内部任务。

但这些数据说明，任务栈是运行时内存治理的重点。

### 8.2 音频队列

音频上行发送队列：

```text
长度：24
单项数据容量：约 1 KiB
队列数据：约 24 KiB
分配策略：PSRAM 优先
```

音频下行播放队列：

```text
长度：1,024
队列项保存长度和数据指针
队列描述符约 16 KiB
音频正文另外动态分配
分配策略：PSRAM 优先
```

下行正文占用取决于服务器下发速度、网络抖动和播放消费速度。极端积压时，真实内存占用会明显高于队列描述符本身。

### 8.3 WebSocket 队列

```text
消息队列上限：512
单个描述符约 20 bytes
描述符队列约 10 KiB
消息正文动态分配，单条最大值可达数 KiB
```

描述符队列优先放入 PSRAM，但正文积压量仍可能成为峰值风险。

### 8.4 远程日志静态队列

远程日志启用：

```text
CONFIG_TQ_REMOTE_LOG_ENABLE=y
队列长度：128
单条文本容量：256 bytes
```

`remote_log_entry_t` 每项还包含时间戳、日志等级和状态字段，整个静态队列约占 33 KiB 内部 BSS。这是当前 `control_plane` 静态 BSS 约 37.8 KiB 的主要来源。

风险等级：**中高**。

这块内存在启用远程日志后始终常驻，即使没有积压日志也不会释放。

### 8.5 LCD 缓冲

LCD 采用分行读取，不加载整张 320×240 图片：

```text
行缓冲：320 × 8 × 2 bytes = 5,120 bytes
RLE chunk：128 × 4 bytes = 512 bytes
```

这部分设计较合理。若整帧 RGB565 全部加载，将需要：

```text
320 × 240 × 2 = 153,600 bytes
```

因此，后续不要轻易把当前流式绘制改成整帧内部 RAM 缓冲。确实需要双缓冲时，应评估 PSRAM、DMA 约束和帧率收益。

## 9. 运行时内存风险

### 9.1 内部连续内存不足

风险等级：**高**。

系统可能出现以下情况：

```text
总 free_heap 看起来很多
但 largest_internal 或 largest_dma 很小
导致 TLS、AES、SPI、I2S 或 Wi-Fi 分配失败
```

重点场景：

- Wi-Fi 刚连接时进行 HTTPS Token 请求；
- TLS 握手和 WebSocket 建连重叠；
- 音频采集、编码、播放同时工作；
- LCD 正在 SPI DMA 传输；
- 远程日志同时上传 HTTPS；
- LAN HTTP 服务同时处理请求。

判断内存是否健康，不能只看 `esp_get_free_heap_size()`，还必须观察：

```text
free_internal
largest_internal
largest_dma
free_spiram
largest_spiram
minimum_free_heap
```

### 9.2 内存碎片

风险等级：**中高**。

TLS、JSON、WebSocket 消息、音频包和 HTTP body 都会产生不同大小、不同生命周期的动态分配。长时间连接、重连、失败重试后，可能出现总空闲量尚可但最大连续块下降的情况。

判断方法：

- 多轮重连后比较 `free_internal`；
- 比较 `largest_internal` 是否持续下降；
- 比较 `largest_dma` 是否持续下降；
- 比较连接前、握手中、交互中、断开后的数值能否恢复；
- 重复语音交互 100 次以上观察最低值和趋势。

### 9.3 PSRAM 回退导致内部 RAM 突增

很多任务和队列采用“PSRAM 优先，失败回退内部 RAM”。如果 PSRAM 初始化失败、容量不足或碎片严重，多个对象可能同时回退到内部 RAM，使内部堆瞬间恶化。

必须关注日志：

```text
PSRAM allocation failed
fallback to internal
Task create with PSRAM stack failed
```

量产版本不应把这些日志当成无害告警。

### 9.4 任务栈过大或过小

风险等级：**中**。

- 栈过大：浪费内部 RAM 或 PSRAM；
- 栈过小：发生栈溢出、随机崩溃；
- 只在正常路径测量不足以覆盖 TLS 错误、JSON 大包、日志上传等深调用路径。

当前 `CONFIG_TQ_TASK_MONITOR_ENABLE` 关闭，缺少持续任务栈可观测性。建议在压力测试固件中启用，不一定默认用于量产版本。

## 10. 跨 Flash 与 RAM 的组合风险

### 10.1 资源与应用版本不一致

普通应用 OTA 只更新 `ota_0/ota_1`，不更新 `gifpack`。如果新代码引用新资源路径，而设备仍保留旧 `gifpack`，会出现：

```text
open LCD asset failed
Open prompt failed
```

建议：

- 应用中声明资源包版本；
- `gifpack` 中保存资源 manifest；
- 启动时比较应用要求版本和资源版本；
- 不匹配时进入明确降级路径，不要反复尝试打开不存在的文件。

### 10.2 单份资源分区在线更新风险

当前只有一个 `gifpack` 分区。若未来在线覆盖更新：

- 更新中断电可能损坏整个资源文件系统；
- 新镜像校验失败时没有旧资源可回退；
- 应用和资源切换无法原子完成。

在没有完整方案前，不建议直接实现“边运行边覆盖单个 gifpack”。可选方向：

1. 资源仅随工厂完整烧录更新；
2. 下载到备用区域，校验后再切换；
3. 设计 `gifpack_0/gifpack_1` 双资源分区；
4. 使用版本化资源容器和原子状态记录；
5. 将少量新增资源并入应用，但需评估 OTA 槽容量。

### 10.3 LittleFS 挂载依赖开机音流程

当前 `/littlefs` 主要由播放开机音前的 `voice_prompt_play_file()` 触发挂载。LCD 随后假定 `/littlefs` 已经可用。

如果开机音被关闭或音频初始化提前失败，LCD 可能在文件系统未挂载时读取资源。

建议把 `platform_mount_littlefs()` 提升为明确的启动阶段，由 `app_composition` 在音频和 LCD 之前编排，并保持调用幂等。

风险等级：**中高**。

## 11. 优化建议与优先级

### P0：立即建立容量门禁

在 CI 或构建检查中记录并比较：

```text
应用 .bin 大小
应用分区使用率
gifpack LittleFS 已用块数
gifpack 使用率
IRAM 使用量
D/IRAM 静态使用量
```

建议规则：

- 应用分区达到 85% 发出警告；
- 应用分区达到 90% 阻止合入；
- `gifpack` 达到 90% 发出高风险警告；
- `gifpack` 达到 95% 阻止合入；
- IRAM 增长必须在 PR 中说明；
- 新增库必须附带 size diff；
- 新增动画必须附带新增资源字节数和预计剩余空间。

### P0：采集真机峰值内存

至少在以下时间点采集：

1. Bootloader 后、应用初始化前；
2. NVS 和 LittleFS 挂载后；
3. Wi-Fi 初始化后；
4. Wi-Fi 已连接；
5. TLS Token 请求前和握手中；
6. WebSocket 已连接；
7. 音频采集和播放同时进行；
8. LCD 动画播放中；
9. 远程日志上传中；
10. 所有业务进入稳态后；
11. 多次断线重连后；
12. 长时间运行 24 小时后。

每次至少记录：

```text
esp_get_free_heap_size()
esp_get_minimum_free_heap_size()
heap_caps_get_free_size(MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT)
heap_caps_get_largest_free_block(MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT)
heap_caps_get_largest_free_block(MALLOC_CAP_DMA)
heap_caps_get_free_size(MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT)
heap_caps_get_largest_free_block(MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT)
```

不要一开始就设定绝对通过阈值。先收集多台设备、多种网络条件的基线，再根据 TLS、DMA 和音频最大单次申请量设定安全阈值。

### P1：优化远程日志静态队列

当前约 33 KiB 内部 BSS 常驻，可考虑：

1. 将队列动态分配到 PSRAM；
2. PSRAM 失败时回退到更短内部队列，而不是同等大小回退；
3. 将 `CONFIG_TQ_REMOTE_LOG_QUEUE_LEN` 从 128 调低；
4. 将单条文本上限从 256 调低；
5. 使用变长块池或分层队列；
6. 评估是否需要在所有构建类型中默认启用远程日志。

修改时要保持日志钩子并发安全，不能为了省内存破坏日志回调的锁和生命周期。

### P1：基于高水位调整任务栈

压力测试时开启任务监控，记录所有任务最小剩余栈。

调优原则：

- 不以一次正常启动数据为依据；
- 覆盖错误路径、重连、超时和大 JSON；
- 保留安全余量；
- 优先优化长期存活且栈明显过大的任务；
- 对 ISR、DMA、Flash cache 关闭相关任务，不要盲目迁移到 PSRAM；
- 修改后执行长时间和异常路径测试。

### P1：治理资源体积

当前 LCD 资源占 `gifpack` 的绝大部分。建议：

- 清理白名单中已不再播放的资源；
- 检查是否存在内容重复的帧；
- 对相邻帧考虑差分、局部刷新或共享背景；
- 检查 RLE 色彩和扫描方向是否影响压缩率；
- 避免把相同首帧复制到多个动画组；
- 新增资源时记录原图大小、RLE 大小、run 数和压缩率；
- 建立资源 manifest，自动检查 CMake 白名单和代码映射一致性。

当前 `tools/png_to_rle.py` 生成标准 TGA RLE，而 `lcd_direct` 读取原始 `uint16_t color + uint16_t count` 数据，两者不兼容。应统一并验证资源转换工具，避免开发者误用。

### P1：确认 `model` 分区是否仍需要 1.5 MiB

当前 `model` 分区没有进入常规烧录清单。需要确认：

- 是否由工厂工具单独烧录；
- 当前功能是否读取该分区；
- 量产设备中是否有有效模型数据；
- 1.5 MiB 是否为未来预留；
- 能否缩减并重新分配给应用或资源。

如果确认未使用，可以评估重新分区。但调整前必须同时考虑：

- 两个 OTA 分区需要同步增大；
- 已出货设备变更分区表的迁移风险；
- OTA 是否能够安全改变分区布局；
- 模型恢复和工厂烧录流程；
- Flash 擦除和回滚策略。

不要只修改 CSV 就认为升级安全。

### P2：优化队列和积压策略

音频和 WebSocket 队列容量较大。建议根据真实峰值观测：

- 最大队列深度；
- 平均排队时间；
- 丢包数量；
- 消费速率；
- 网络抖动时的峰值；
- 语音播放延迟。

如果队列长期只使用很小比例，可以缩短；如果积压很深，应优先解决背压和消费速率，不要单纯继续增大队列。

### P2：增加资源版本和完整性校验

在 `gifpack` 中增加小型 manifest，例如：

```json
{
  "resource_version": "1.3.0",
  "format_version": 1,
  "target": "esp32s3-st7789p3",
  "files": {
    "lcd/jichubiaoqing0.rle": {
      "size": 21644,
      "run_count": 5411,
      "sha256": "..."
    }
  }
}
```

启动时不必校验所有大文件，但至少应检查：

- manifest 可读取；
- 资源版本兼容；
- 关键启动资源存在；
- 文件格式版本正确；
- 必要时抽样或按需校验哈希。

## 12. 后续开发准入要求

### 12.1 新增普通代码或第三方库

PR 中应记录：

- 应用 `.bin` 增量；
- Flash `.text` 和 `.rodata` 增量；
- IRAM 增量；
- D/IRAM `.data/.bss/.text` 增量；
- 是否新增长期任务；
- 任务栈配置和内存区域；
- 是否新增大队列或大缓冲；
- 是否在 TLS、音频、LCD 并发路径中运行。

### 12.2 新增 LCD 或音频资源

PR 中应记录：

- 新增文件数；
- 新增资源总字节数；
- 新 `gifpack` 使用率；
- 预计剩余空间；
- LCD `run_count` 是否更新；
- CMake 白名单是否更新；
- 平台资源映射是否更新；
- domain 播放顺序是否更新；
- 完整 `idf.py flash` 硬件验证结果。

### 12.3 新增长期任务

必须定义：

- 明确 owner 层；
- 创建、启动、停止和销毁流程；
- 栈大小依据；
- 内部 RAM 或 PSRAM 选择依据；
- PSRAM 失败回退行为；
- 有界停止时间；
- 栈高水位观测方式；
- 队列和动态内存上限。

### 12.4 新增大型动态缓冲

必须回答：

- 最大申请尺寸是多少；
- 是否要求 DMA 能力；
- 是否必须在内部 RAM；
- 生命周期多长；
- 是否会与 TLS、音频、LCD 同时存在；
- PSRAM 失败时如何降级；
- 是否存在无上限增长；
- 分配失败是否能安全恢复。

### 12.5 修改分区表

必须进行完整评审：

- 总大小是否仍为 16 MiB；
- 两个 OTA 槽是否等大；
- 当前和历史固件是否兼容；
- 已部署设备如何迁移；
- 工厂烧录脚本是否更新；
- OTA、资源、模型和 coredump 流程是否更新；
- 地址变化是否影响任何硬编码工具；
- 断电和回滚是否安全。

## 13. 推荐测试矩阵

| 测试场景 | 重点观察 |
| --- | --- |
| 冷启动 | PSRAM 检测、LittleFS 挂载、初始内部堆 |
| 无网络启动 | 重试期间是否泄漏、LCD 是否仍能读资源 |
| Wi-Fi 弱网 | 队列积压、重连内存恢复 |
| HTTPS Token | `largest_dma`、`largest_internal` |
| WebSocket 重连 100 次 | 内存碎片、任务和队列是否释放 |
| 连续语音交互 | 音频队列峰值、PSRAM 趋势 |
| 上下行音频同时工作 | 内部 DMA 和 PSRAM 峰值 |
| LCD 动画和语音同时工作 | SPI/I2S DMA 竞争 |
| 远程日志上传 | TLS 与日志 body 峰值 |
| LAN HTTP 并发访问 | HTTP task 和响应缓冲 |
| 运行 24/72 小时 | 最小堆、碎片、任务泄漏 |
| 人为断电资源更新 | 资源完整性和恢复策略 |

每轮测试都应保存：

- 固件提交；
- `sdkconfig`；
- 应用和资源镜像大小；
- 完整串口日志；
- 各阶段堆快照；
- 任务栈高水位；
- 崩溃转储；
- 是否出现 PSRAM 回退。

## 14. 建议的持续观测指标

当前代码已经在认证、WebSocket、音频和远程日志路径中记录部分堆信息。建议统一成一个结构化内存快照接口，由 platform 层负责采集，control_plane 决定在何时上报。

推荐字段：

```text
timestamp
phase
free_heap
minimum_free_heap
free_internal
largest_internal
largest_dma
free_spiram
largest_spiram
task_count
active_audio_state
websocket_state
lcd_state
```

避免多个模块重复实现不同格式的 heap 日志。长期应形成单一内存观测入口，并支持：

- 启动阶段快照；
- 关键操作前后快照；
- 低内存阈值告警；
- 崩溃前最近快照保留；
- Debug 构建中的任务栈报表。

## 15. 当前风险汇总

| 风险 | 等级 | 当前证据 | 建议 |
| --- | --- | --- | --- |
| `gifpack` 空间不足 | 高 | 已用 90.25%，仅余约 1.02 MiB | 资源门禁、清理和压缩 |
| OTA 应用槽空间不足 | 高 | 已用 87.20%，仅余约 238 KiB | 代码 size 门禁、评估重新分区 |
| 独立 IRAM 无余量 | 高 | 16 KiB 已用 100% | 限制新增 `IRAM_ATTR` |
| 内部连续/DMA 内存不足 | 高 | Wi-Fi、TLS、音频、LCD 并发竞争 | 真机峰值监控和压力测试 |
| 应用和资源版本不一致 | 高 | 普通 OTA 不更新 `gifpack` | 资源 manifest 和兼容检查 |
| 单资源分区更新断电风险 | 高 | `gifpack` 无 A/B | 不直接在线覆盖；设计安全更新机制 |
| 远程日志常驻内部 BSS 较大 | 中高 | 静态队列约 33 KiB | PSRAM 化或缩小队列 |
| LittleFS 挂载依赖开机音 | 中高 | 挂载由提示音路径触发 | 独立启动阶段显式挂载 |
| 动态内存真实峰值未知 | 中高 | 尚无本次真机数据 | 建立基线和长稳测试 |
| PSRAM 实际容量未固化 | 中 | 自动检测，项目未声明容量 | 量产硬件验收和启动校验 |
| 任务栈缺少持续观测 | 中 | task monitor 默认关闭 | 压测构建启用并调优 |
| RLE 转换工具格式不一致 | 中 | TGA RLE 与 raw RLE 不兼容 | 统一转换和自动校验工具 |

## 16. 推荐执行顺序

### 第一阶段：立即完成

1. 将应用和 `gifpack` 大小检查加入构建或 CI；
2. 在真机完成一次全流程内存快照；
3. 确认实际 PSRAM 容量；
4. 统计所有任务栈高水位；
5. 清点 `gifpack` 中是否存在未使用资源；
6. 确认 `model` 分区真实用途；
7. 将 LittleFS 挂载改为明确启动阶段。

### 第二阶段：容量治理

1. 优化或迁移远程日志静态队列；
2. 根据高水位缩减过大的任务栈；
3. 根据实测调整音频/WebSocket 队列；
4. 统一 RLE 转换工具和格式检查；
5. 增加资源 manifest；
6. 建立应用和资源版本兼容规则。

### 第三阶段：量产和长期升级

1. 决定资源是否需要 OTA；
2. 如需要，设计资源 A/B 或安全下载切换机制；
3. 评审并冻结量产分区表；
4. 建立 24/72 小时长稳测试；
5. 建立多轮 Wi-Fi/WebSocket 重连压力测试；
6. 保存每个发布版本的 Flash/RAM 基线报告。

## 17. 复现本分析的方法

### 17.1 应用镜像

完整构建后检查：

```text
build/TQ_Cat_Code.bin
build/TQ_Cat_Code.map
```

使用当前 ESP-IDF v5.5.4 环境运行 size 工具：

```bash
idf.py size
idf.py size-components
```

### 17.2 Flash 分区

检查：

```text
16m.csv
build/partition_table/partition-table.bin
build/flasher_args.json
```

不要假定空 Offset 分区的地址永久不变，应以当前构建生成结果为准。

### 17.3 LittleFS 资源

检查临时目录文件总量：

```text
build/esp-idf/platform/asset_image/
```

使用构建环境中的 `littlefs-python` 查看：

```bash
build/littlefs_py_venv/bin/littlefs-python list \
    build/gifpack.bin \
    --block-size 4096 \
    --name-max 64
```

真实空闲块应通过 LittleFS API或设备挂载后的 `esp_littlefs_info()` 获取，不能只依据资源文件内容之和。

### 17.4 真机运行时内存

关注串口日志中的：

```text
Heap before_ws_client_start
free_internal
largest_internal
largest_dma
free_spiram
largest_spiram
stack headroom
PSRAM allocation failed
fallback to internal
```

## 18. 当前结论

目前 16 MiB Flash 的规划已经非常紧凑：`gifpack` 占整个 Flash 的 65.63%，自身使用率达到 90.25%；两个 OTA 槽位合计占 22.66%，当前应用已占单槽 87.20%。Flash 没有未划分空间，任何扩容都必须以压缩或缩减其他分区为代价。

静态 RAM 方面，D/IRAM 使用率约 50.7%，表面仍有空间，但独立 IRAM 已经 100% 使用。真正的运行风险集中在内部连续内存和 DMA 内存：Wi-Fi、TLS、音频、LCD 和远程日志同时工作时，即使 PSRAM 仍有余量，也可能因为内部连续块不足而失败。

后续开发应把容量视为正式约束，而不是等链接或运行失败后再处理。最优先的工作是建立容量门禁、收集真机峰值内存、优化远程日志静态队列、清理资源、确认 `model` 分区用途，并为应用与资源版本建立明确兼容机制。