RAM File System

概述

claw_ramfs 是 ESP-Claw 中的一个 RAM-backed 文件系统实现，通过 ESP-IDF VFS 接口注册，使应用可以像操作普通文件一样读写内存中的文件。相比 FATFS（Flash 存储），RAMFS 提供更快的读写速度并且减少 Flash 磨损，适合临时文件、缓存和运行时生成的数据。

主要用途

临时文件缓存：LLM 推理过程中的中间数据
快速交换区：Lua 脚本运行时产出的临时文件
跨组件数据共享：通过文件路径在不同组件间传递数据
多层级读写：支持将 RAMFS 内容同步到 FATFS，或从 FATFS 加载到 RAMFS

API

挂载与卸载

#include "claw_ramfs.h"

claw_ramfs_config_t config = {
    .base_path = "/ram",
    .max_files = 8,
    .max_bytes = 64 * 1024,
    .caps = MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT,
};
esp_err_t err = claw_ramfs_register(&config);

配置项	说明
`base_path`	VFS 挂载点（如 `/ram`），必须以 `/` 开头且不以 `/` 结尾
`max_files`	同时打开的最大文件数（不是存储文件总数）
`max_bytes`	文件内容可用的最大总字节数（不含目录元数据）
`caps`	堆分配标志，必须包含 `MALLOC_CAP_8BIT`

卸载：

claw_ramfs_unregister("/ram");

容量查询

size_t total, used;
claw_ramfs_info("/ram", &total, &used);

FATFS 同步

RAMFS 与 FATFS 之间支持双向文件/目录同步：

// 单文件同步到 FATFS
claw_ramfs_sync_file_to_fatfs("/ram/output.json", "/fatfs/backup/output.json");

// 整个目录树同步到 FATFS
claw_ramfs_sync_tree_to_fatfs("/ram/results", "/fatfs/backup/results");

// 从 FATFS 加载文件到 RAMFS
claw_ramfs_load_file_from_fatfs("/fatfs/config.json", "/ram/config.json");

// 从 FATFS 加载目录树到 RAMFS
claw_ramfs_load_tree_from_fatfs("/fatfs/cache", "/ram/cache");

与其他组件的关系

cap_files：文件操作工具可以同时管理 FATFS 和 RAMFS 路径下的文件
cap_lua：Lua 脚本可以读写 RAMFS 路径下的文件，用于高速临时存储
claw_memory：部分运行时内存数据可缓存在 RAMFS 中

内存选择建议

场景	推荐 `caps`
小型临时文件（< 32KB）	`MALLOC_CAP_INTERNAL \| MALLOC_CAP_8BIT`
大型缓存文件	`MALLOC_CAP_SPIRAM \| MALLOC_CAP_8BIT`