项目架构总览

整体架构

项目采用 “应用示例 + 通用组件” 的组织方式：application/edge_agent 是可直接编译运行的 ESP-IDF 示例工程，负责把 Wi-Fi、配置页面、Lua 模块和各类能力组装成一个完整设备；components 则沉淀可复用的运行时核心、能力插件和硬件/脚本扩展模块，便于后续在不同板型和场景下复用。

当前代码可以分为四个部分：

应用装配部分： main 与 common，负责启动入口、网络连接、参数配置、HTTP 配网页面以及 Demo 级模块注册。
能力部分： claw_capabilities，负责对外能力封装，包括 IM 通讯、MCP Client/Server、Lua 运行时、调度、文件、时间、Web 搜索等能力。
运行时核心部分： claw_modules，负责 Agent 基础设施，包括核心上下文、能力注册、事件路由、记忆管理与技能管理等。
设备与脚本扩展部分： lua_modules，负责把显示屏、摄像头、音频、按键、GPIO、PWM、存储等外设能力暴露给 Lua 和上层 Agent 使用。

项目目录结构

文件夹application/edge_agent/ 示例应用 — 把框架与 cap 装配成可烧录固件
- 文件夹main/ 启动入口（app_main）
  - main.c 固件入口
- 文件夹components/ 应用级组件
  - 文件夹app_config/ 配置持久化（NVS 读写）
    …
  - 文件夹http_server/ Web 管理界面与 JSON API
    …
  - 文件夹cmd_wifi/ Wi-Fi CLI 命令
    …
  - 文件夹gen_bmgr_codes/ [自动生成]开发板适配所需代码
    …
- 文件夹fatfs_image/ 出厂 FATFS 输入：router_rules、memory、scheduler、静态文件与应用自带 Skills
  - …
文件夹components/common/ 共享应用组件 — 多示例复用的装配逻辑
- 文件夹app_claw/ 应用启动与装配（app_claw_start、CLI、Lua 模块注册）
  - …
- 文件夹wifi_manager/ Wi-Fi 连接与网络配置
  - …
- 文件夹settings/ 本地设置持久化基础库
  - …
- 文件夹captive_dns/ Captive DNS（SoftAP 配网）
  - …
- 文件夹display_arbiter/ 显示所有权仲裁 [详情]
  - …
- 文件夹emote/ 表情显示与网络状态联动
  - …
- 文件夹esp_painter/ 轻量绘图
  - …
- 文件夹esp_video/ 视频处理封装
  - …
- 文件夹http_reuse/ HTTP 复用基础组件
  - …
- 文件夹lua_module_builder/ Lua 模块构建辅助
  - …
- 文件夹skill_builder/ Skill 构建辅助
  - …
文件夹components/
- 文件夹claw_modules/ 运行时核心
  - 文件夹claw_core/ Agent 核心 — Agent Loop、上下文组装管理、工具调用
    …
  - 文件夹claw_cap/ Capability 运行时 — 能力抽象、注册与管理
    …
  - 文件夹claw_event_router/ Event Router 与自动化 — 确定性事件路由
    …
  - 文件夹claw_memory/ 结构化记忆管理
    …
  - 文件夹claw_ramfs/ RAMFS 运行时文件系统支持
    …
  - 文件夹claw_skill/ Skills 系统 — 技能元数据与加载
    …
- 文件夹claw_capabilities/ 能力 Capability
  - 文件夹cap_im_platform/ 统一 IM 平台组件（飞书、QQ、Telegram、微信能力组）
    …
  - 文件夹cap_mcp_*/ MCP 协议（MCP Client、MCP Server）
    …
  - 文件夹cap_lua/ Lua 运行时管理
    …
  - 文件夹cap_skill_mgr/ claw_skill 的管理接口封装
    …
  - 文件夹cap_scheduler/ 调度器
    …
  - 文件夹cap_router_mgr/ claw_event_router 的管理接口封装
    …
  - … 其他工具类 Capability
- 文件夹lua_modules/ 设备与脚本扩展层
  - 文件夹lua_module_display/ 显示屏
    …
  - 文件夹lua_module_camera/ 摄像头
    …
  - 文件夹lua_module_audio/ 音频
    …
  - 文件夹lua_driver_mcpwm/ PWM
    …
  - 文件夹lua_driver_pcnt/ 脉冲计数器
    …
  - 文件夹lua_module_button/ 按键
    …
  - 文件夹lua_driver_gpio/ GPIO
    …
  - 文件夹lua_driver_i2c/ I2C 总线
    …
  - 文件夹lua_driver_touch/ 触摸
    …
  - 文件夹lua_driver_adc/ ADC 采样
    …
  - 文件夹lua_module_led_strip/ 灯带
    …
  - 文件夹lua_module_storage/ 存储
    …
  - 文件夹lua_module_delay/ 延时
    …
  - 文件夹lua_module_system/ 系统时间/内存/网络状态
    …
  - 文件夹lua_module_event_publisher/ 事件发布
    …
  - 文件夹lua_driver_uart/ UART 串口收发
    …
  - 文件夹lua_module_ble_hid/ 蓝牙 HID
    …
  - 文件夹lua_module_board_manager/ 板级管理
    …
  - 文件夹lua_module_call_capability/ 能力调用桥接
    …
  - 文件夹lua_module_environmental_sensor/ 环境传感器
    …
  - 文件夹lua_module_fuel_gauge/ 电量计
    …
  - 文件夹lua_module_http_server/ 本地 HTTP 服务
    …
  - 文件夹lua_module_image/ 图像处理
    …
  - 文件夹lua_module_imu/ IMU 传感器
    …
  - 文件夹lua_module_ir/ 红外
    …
  - 文件夹lua_module_json/ JSON 工具
    …
  - 文件夹lua_module_knob/ 旋钮
    …
  - 文件夹lua_module_lcd/ LCD
    …
  - 文件夹lua_module_lcd_touch/ LCD 触摸
    …
  - 文件夹lua_module_lvgl/ LVGL UI
    …
  - 文件夹lua_module_magnetometer/ 磁力计
    …
  - 文件夹lua_module_sci/ 串口外设集成
    …
  - 文件夹lua_module_thread/ 线程支持
    …
  - 文件夹lua_module_vision/ 视觉能力
    …
文件夹docs/ 项目文档与图片
- …

运行时图

运行时数据目录

所有运行时数据均挂载在 FATFS 文件系统 /fatfs 之下：

文件夹fatfs/
- 文件夹sessions/ 会话历史（按 session id 拆文件）
  - …
- 文件夹memory/
  - MEMORY.md 供人类阅读的记忆视图（只读）
  - memory_records.jsonl 结构化记忆记录
  - memory_index.json 摘要标签与关键词索引
  - memory_digest.log 记忆操作摘要日志
  - user.md 用户画像
  - soul.md 人设
  - identity.md 身份
- 文件夹skills/
  - 文件夹skill_id/
    SKILL.md Skill 元数据与正文
    文件夹scripts/ Skill 自带脚本（可选）
    …
- 文件夹scripts/
  - 文件夹builtin/ 内置 Lua 测试脚本与库
    …
  - 文件夹docs/ 内置 Lua 模块文档
    …
  - *.lua 自定义 Lua 脚本
- 文件夹router_rules/
  - router_rules.json 自动化规则
- 文件夹scheduler/
  - schedules.json 调度任务配置
  - schedules.json.state 调度任务运行时状态（自动生成）
- 文件夹static/
  - ESP-Claw.png 示例静态资源（出厂预置）
- 文件夹inbox/
  - … IM 附件

备份与重置

备份：将 /fatfs 下的子目录（sessions/、memory/、skills/、scripts/、router_rules/、scheduler/、static/、inbox/）整体拷贝到外部即可。
重置：重新烧录 storage 分区或重新烧录完整固件。