增加文件系统

AGENTS.md

@@ -1,5 +1,7 @@
 # STM32F4-Base
 
+> **⚠️ 编译验证：所有代码修改后必须执行 `@build` 验证编译通过（0 错误 0 警告），否则不要提交。**
+
 ## 项目概述
 
 STM32F407ZGTx (Cortex-M4 FPU) 基础固件项目，集成 CH395F 以太网控制器 SPI 驱动、GD5F2GQ5UE SPI NAND Flash 存储（含 FlashDB KVDB/TSDB 数据库）和 TPAFE5160 16位8通道同步采样 ADC 并行接口驱动。
@@ -58,33 +60,19 @@ STM32F4-Base/
 
 仅支持 Keil MDK-ARM v5 (ARMCC)。打开 `MDK-ARM/STM32F407-Demo.uvprojx` 编译。
 
-- 编译器：ARMCC V5.06 update 7
-- 优化等级：`-O4` (项目级)，`spi.c`/`usart.c` / HAL 源文件使用 `-O0`
-- C 标准：C99
-- 全局宏定义：`USE_HAL_DRIVER, STM32F407xx`
+- 编译器：ARMCC V5.06 update 7，优化 `-O4`（`spi.c`/`usart.c`/HAL 源文件 `-O0`），C99，`USE_HAL_DRIVER, STM32F407xx`
 
 ### 命令行编译（Agent 使用）
 
-修改代码后必须执行命令行编译验证，编译脚本位于 `MDK-ARM/build.bat`：
+修改代码后必须执行命令行编译验证，**仅使用** `@build`，不得直接调用 UV4.exe：
 
 ```
-cmd /c "cd /d "工作目录" && build.bat"
+@build
 ```
 
-实际执行示例（从项目根目录）：
+该命令定义在 `.opencode/command/build.md`，自动执行 `MDK-ARM/build.bat` 进行全量编译（`-r`）。
 
-```
-cmd /c "cd /d "D:\Code\DTU 程序\STM32F4-Base\MDK-ARM" && build.bat"
-```
-
-**编译结果判读：**
-- 退出码 0：无错误无警告，编译成功
-- 退出码 1：有警告无错误，编译失败（警告不可接受，需修复）
-- 退出码 2+：编译失败，需查看 `MDK-ARM/build_log.txt` 定位错误
-
-**UV4.exe 路径：** `C:\Keil_v5\UV4\UV4.exe`
-**工程文件：** `MDK-ARM/STM32F407-Demo.uvprojx`
-**目标名称：** `STM32F407-Demo`
+**退出码：** 0 = 成功（0 Error, 0 Warning）| 1 = 有警告（同样不通过）| 2+ = 错误，需查看 `MDK-ARM/build_log.txt` 定位
 
 ## 硬件配置
 
@@ -158,12 +146,17 @@ HAL_Init() → SystemClock_Config() → MX_GPIO_Init() → MX_USART1_UART_Init()
 - 块擦除（D8h）参数是字节地址（块编号 × 128KB），不是块编号
 - 读取 ID（9Fh）返回 3 字节，第 0 字节无意义，第 1 字节 MID，第 2 字节 DID
 
-## FlashDB 分区规划
+## Flash 分区规划（256MB GD5F2GQ5UE）
 
-| 分区名 | 偏移 | 大小 | 用途 |
-|--------|------|------|------|
-| fdb_kvdb1 | 0 | 64MB | KVDB 键值数据库 |
-| fdb_tsdb1 | 64MB | 64MB | TSDB 时序数据库 |
+| 分区名 | 偏移 | 大小 | 块范围 | 用途 |
+|--------|------|------|--------|------|
+| fdb_kvdb1 | 0 | 64MB | Block 0~511 | FlashDB KVDB 键值数据库 |
+| fdb_tsdb1 | 64MB | 64MB | Block 512~1023 | FlashDB TSDB 时序数据库 |
+| ftl_fatfs | 128MB | 128MB | Block 1024~2047 | dhara FTL + FatFS 文件系统 |
+
+- FlashDB 通过 FAL 层访问 `fdb_kvdb1` / `fdb_tsdb1`（`Drivers/BSP/GD5F2GQ5UE/fal_cfg.h`）
+- FatFS 通过 dhara FTL 访问 `ftl_fatfs` 分区，`nand_ftl.c` 中 `FTL_START_BLOCK = FTL_FATFS_OFFSET / GD5F_BLOCK_SIZE`（与 `fal_cfg.h` 联动）
+- 三个分区物理隔离，互不重叠，分区配置统一在 `fal_cfg.h:25-30`
 
 ## TPAFE5160 驱动关键点