项目架构总览

整体架构

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

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

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

项目目录结构

• 文件夹application/basic_demo/ 示例应用 — 把框架与 cap 装配成可烧录固件

  • 文件夹main/ 启动、Wi‑Fi、HTTP 配置页、app_claw_start

    • main.c 固件入口
    • app_claw.c 应用启动与装配
    • app_expression_emote.* 表情显示与网络状态联动
    • basic_demo_wifi.* Wi-Fi 连接与网络配置
    • basic_demo_settings.* 本地设置持久化
    • config_http_server.* Web 配置服务
    • basic_demo_lua_modules.* Lua 模块注册
    • 文件夹web/ 设备配置前端资源

      • …
  • 文件夹components/display_arbiter/ 显示所有权仲裁 [详情]

    • …
  • 文件夹fatfs_image/ 出厂 FATFS：skills、router_rules、memory、scripts 样例

    • …
• 文件夹components/

  • 文件夹claw_modules/ 运行时核心

    • 文件夹claw_core/ Agent 核心 — Agent Loop、上下文组装管理、工具调用

      • …
    • 文件夹claw_cap/ Capability 运行时 — 能力抽象、注册与管理

      • …
    • 文件夹claw_event_router/ Event Router 与自动化 — 确定性事件路由

      • …
    • 文件夹claw_memory/ 结构化记忆管理

      • …
    • 文件夹claw_skill/ Skills 系统 — 技能元数据与加载

      • …
  • 文件夹claw_capabilities/ 能力 Capability

    • 文件夹cap_im_*/ 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_module_mcpwm/ PWM

      • …
    • 文件夹lua_module_button/ 按键

      • …
    • 文件夹lua_module_gpio/ GPIO

      • …
    • 文件夹lua_module_led_strip/ 灯带

      • …
    • 文件夹lua_module_storage/ 存储

      • …
    • 文件夹lua_module_delay/ 延时

      • …
    • 文件夹lua_module_system/ 系统时间/内存/网络状态

      • …
    • 文件夹lua_module_event_publisher/ 事件发布

      • …
    • 文件夹esp_painter/ 轻量绘图

      • …
• 文件夹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/

    • skills_list.json Skills 清单（id、file、summary、cap_groups）
    • *.md 各 Skill 文档
  • 文件夹scripts/

    • hello.lua 出厂示例脚本
    • audio_fft_2.lua 音频采集与频谱分析示例
    • mcpwm_servo.lua 舵机 PWM 控制示例
    • *.lua 自定义 Lua 脚本
  • 文件夹router_rules/

    • router_rules.json 自动化规则
  • 文件夹scheduler/

    • schedules.json 调度任务配置
    • schedules.json.state 调度任务运行时状态（自动生成）
  • 文件夹inbox/

    • … IM 附件

备份与重置

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