d-pet-ai-patterns - SKILL.md Agent Skill

name: d-pet-ai-patterns description: D-Pet-AI 项目编码模式和最佳实践 version: 1.0.0 source: local-project-analysis platform: ESP32-S3 + Arduino + PlatformIO

D-Pet-AI Coding Patterns

基于 ESP32-S3 的智能桌宠项目编码规范和模式。

Project Architecture

三层架构设计

src/
├── config/              # 配置文件
│   ├── pins.h          # GPIO 引脚定义
│   ├── settings.h      # 系统配置参数
│   └── secrets.h       # API 密钥（不提交）
├── hal/                # 硬件抽象层 (HAL)
│   ├── display/        # 显示屏驱动
│   ├── audio/          # 音频驱动
│   ├── camera/         # 摄像头驱动
│   ├── motor/          # 电机驱动
│   ├── imu/            # IMU 传感器
│   └── power/          # 电源管理
├── services/           # 服务层
│   ├── expression/     # 表情系统
│   ├── balance/        # 自平衡控制
│   ├── haptic/         # 力反馈
│   └── ai_local/       # 本地 AI
└── app/                # 应用层
    ├── pet_engine/     # 宠物 AI 引擎
    └── ui/             # UI 界面

架构原则:

HAL 层封装硬件细节，提供统一接口
Services 层实现业务逻辑和算法
App 层处理高层应用和用户交互
依赖方向：App → Services → HAL

Naming Conventions

文件命名

类型	命名规则	示例
类头文件	PascalCase.h	`ExpressionRenderer.h`
类实现文件	PascalCase.cpp	`ExpressionRenderer.cpp`
配置文件	snake_case.h	`pins.h`, `settings.h`
测试文件	test_*.cpp	`test_expression.cpp`

代码命名

类型	命名规则	示例
类名	PascalCase	`ExpressionManager`
枚举类型	PascalCase	`ExpressionType`
枚举值	UPPER_CASE	`HAPPY`, `SAD`
函数/方法	camelCase	`handleEvent()`, `updateAnimation()`
私有成员	_camelCase	`_renderer`, `_initialized`
常量	UPPER_CASE	`SCREEN_CENTER_X`
宏定义	UPPER_CASE	`DEG_TO_RAD`

Visual Style: Cozmo-Inspired Design

核心设计原则

极简几何化，灵感来自 Anki Cozmo 和 Gus 机器人：

🔵 蓝色圆角矩形眼睛（RGB565: 0x001F）
⚫ 纯黑色背景（RGB565: 0x0000）
📐 仅通过眼睛变形表达情感
🎭 无需嘴巴、眉毛、装饰符号

表情实现规范

// 7种核心表情
enum class ExpressionType {
    NEUTRAL,    // 中性 - 标准尺寸
    HAPPY,      // 开心 - 宽度 +30%
    SAD,        // 难过 - 宽度 -30%, 开合度 0.6
    CURIOUS,    // 好奇 - 尺寸 +12%
    SLEEPY,     // 困倦 - 宽度 -30%, 高度 -40%
    SURPRISED,  // 惊讶 - 尺寸 +25%
    ANGRY       // 生气 - 宽度 -30%, 开合度 0.4
};

眼睛位置（240×240 圆形屏幕）:

左眼: (80, 110)
右眼: (160, 110)
基础尺寸: 40×50 像素

Development Workflow

TDD 开发流程（强制）

所有新功能必须遵循 TDD 流程：

1. SCAFFOLD - 定义接口

// 先定义枚举、结构体、类接口
enum class EyeAnimationType : uint8_t {
    BLINK, MOVE_LEFT, MOVE_RIGHT
};

2. RED - 编写测试（测试失败）

void test_play_eye_animation(void) {
    renderer->playEyeAnimation(EyeAnimationType::BLINK, 300);
    TEST_ASSERT_TRUE(renderer->isAnimationPlaying());
}

3. GREEN - 实现代码（测试通过）

void ExpressionRenderer::playEyeAnimation(EyeAnimationType type, uint32_t duration) {
    _currentAnimation.type = type;
    _currentAnimation.isPlaying = true;
    // ... 实现
}

4. REFACTOR - 优化代码

提取重复代码
改进命名
添加注释

5. DOCUMENT - 更新文档

更新 CLAUDE.md
添加使用示例

Code Style Guidelines

头文件结构

/**
 * @file ClassName.h
 * @brief 简短描述
 * @version 1.0
 * @date 2026-02-05
 */

#ifndef CLASS_NAME_H
#define CLASS_NAME_H

#include <Arduino.h>
#include "Dependencies.h"

// 类定义
class ClassName {
public:
    // 公共方法

private:
    // 私有成员（使用 _ 前缀）
};

#endif // CLASS_NAME_H

实现文件结构

/**
 * @file ClassName.cpp
 * @brief 实现文件
 */

#include "ClassName.h"

// 构造函数
ClassName::ClassName() {
}

// 公共方法实现
void ClassName::publicMethod() {
}

// 私有方法实现
void ClassName::_privateMethod() {
}

内存管理规范

ESP32-S3 内存限制:

RAM: 320KB
PSRAM: 8MB
Flash: 16MB

最佳实践:

// ✅ 使用 PSRAM 存储大缓冲区
uint8_t* buffer = (uint8_t*)ps_malloc(size);

// ✅ 避免频繁 malloc/free
class BufferPool {
    // 使用对象池
};

// ✅ 使用栈变量
void function() {
    ExpressionState state;  // 栈上分配
}

// ❌ 避免大数组在栈上
void badFunction() {
    uint8_t bigArray[10000];  // 太大！
}

Testing Standards

测试文件组织

test/
└── test_expression/
    └── test_expression.cpp

测试命名规范

// 测试函数命名：test_<功能>_<场景>
void test_create_happy_expression_state(void) {
    // Given-When-Then 模式
}

void test_play_eye_animation(void) {
    // 测试动画播放
}

测试覆盖率要求

最低覆盖率: 80%
关键模块: 100%（表情系统、平衡控制）

System Integration Patterns

事件驱动架构

使用 ExpressionManager 统一处理系统事件：

// 创建管理器
ExpressionManager manager(renderer);

// 处理各种系统事件
manager.handleEvent(SystemEvent::VISION_FACE_DETECTED);
manager.handleEvent(SystemEvent::POWER_LOW_BATTERY);
manager.handleEvent(SystemEvent::SENSOR_PICKED_UP);

// 主循环更新
void loop() {
    manager.update();
    delay(16);  // ~60 FPS
}

模块间通信

// ✅ 通过事件通信
void onFaceDetected() {
    expressionManager->handleEvent(SystemEvent::VISION_FACE_DETECTED);
}

// ❌ 避免直接耦合
void onFaceDetected() {
    renderer->render(happyState);  // 不推荐
}

Build and Deployment

PlatformIO 配置

[env:esp32-s3-devkitc-1]
platform = espressif32@6.5.0
board = esp32-s3-devkitc-1
framework = arduino

build_flags =
    -DBOARD_HAS_PSRAM
    -DARDUINO_USB_CDC_ON_BOOT=1
    -DCORE_DEBUG_LEVEL=3
    -DGC9A01_DRIVER=1
    -DTFT_WIDTH=240
    -DTFT_HEIGHT=240

常用命令

# 编译
pio run

# 上传
pio run --target upload

# 测试
pio test -e esp32-s3-devkitc-1

# 监视串口
pio device monitor

Performance Optimization

渲染性能

目标帧率: 60 FPS (16ms/frame)
动画更新: 在主循环调用 update()
避免阻塞: 使用非阻塞延迟

void loop() {
    manager.update();      // 非阻塞更新
    delay(16);             // 60 FPS
}

内存优化

Flash 使用: < 15% (避免超过 50%)
RAM 使用: < 30% (保留空间给运行时)
PSRAM: 用于大缓冲区（图像、音频）

Documentation

必读文档

CLAUDE.md: 项目概览和架构说明
docs/plan.md: 8 阶段实施计划
docs/requirements.md: 功能需求
SKILL.md: 本文档（编码规范）

更新文档规则

每次添加新功能时：

更新 CLAUDE.md 的相关章节
添加 API 使用示例
更新表情切换场景表（如适用）

版本: 1.0.0 最后更新: 2026-02-05 维护者: D-Pet-AI Team