---
title: 项目架构总览
description: ESP-Claw 仓库分层、运行时数据流与文档导航。
---

import { FileTree, Aside } from '@astrojs/starlight/components';
import ClawRunDiagram from "@/assets/images/claw_run.svg?url";

## 整体架构

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

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

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

## 项目目录结构

<FileTree>
- application/edge_agent/ **示例应用** — 把框架与 cap 装配成可烧录固件
  - main/ 启动入口（`app_main`）
    - main.c 固件入口
  - components/ 应用级组件
    - app_config/ 配置持久化（NVS 读写）
    - http_server/ Web 管理界面与 JSON API
  - 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/ 显示所有权仲裁 [\[详情\]](@lang/reference-cap/lua-modules#显示模块)
  - emote/ 表情显示与网络状态联动
- 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_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_module_button/ 按键
    - lua_driver_gpio/ GPIO
    - lua_driver_i2c/ I2C 总线
    - 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 串口收发
    - esp_painter/ 轻量绘图
- docs/ 项目文档与图片
</FileTree>

## 运行时图

<img src={ClawRunDiagram} alt="运行时图" />

---

## 运行时数据目录

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

<FileTree>
- 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 调度任务运行时状态（自动生成）
  - inbox/
    - ... IM 附件
</FileTree>

## 备份与重置

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