From b34f8a57962f1d21eb761b17ab440577b31c7ef2 Mon Sep 17 00:00:00 2001
From: wonder <hezhaohui0807@163.com>
Date: Sat, 23 May 2026 11:36:34 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=9A=E4=B9=89=20CLAUDE.md=20?=
 =?UTF-8?q?=E6=96=87=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CLAUDE.md | 162 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 162 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..5faf4ca
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,162 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+gen2d — AI 驱动的 2D 游戏素材生成工具。用户通过文本提示词或可视化参数，生成风格一致、管线友好的 Sprite、背景、UI 元素与动画帧。目标是无缝融入 Unity / Godot 等主流 2D 游戏引擎的工作流。
+
+## Directory Structure
+
+```
+gen2d/
+├── backend/          # Go + Gin API 服务
+│   ├── cmd/          # 入口 (main.go)
+│   ├── internal/     # 业务逻辑（不对外暴露）
+│   │   ├── handler/  # HTTP handlers
+│   │   ├── service/  # 业务 service 层
+│   │   ├── model/    # 数据模型 / DTO
+│   │   ├── middleware/
+│   │   └── config/
+│   ├── pkg/          # 可复用的公共库
+│   ├── go.mod
+│   └── go.sum
+├── frontend/         # Vite + React 前端
+│   ├── src/
+│   │   ├── components/
+│   │   ├── pages/
+│   │   ├── hooks/
+│   │   ├── services/ # API 调用层
+│   │   ├── stores/   # 状态管理
+│   │   ├── types/
+│   │   └── utils/
+│   ├── public/
+│   ├── index.html
+│   ├── vite.config.ts
+│   ├── tsconfig.json
+│   └── package.json
+└── CLAUDE.md
+```
+
+## Common Commands
+
+### Backend (Go + Gin)
+
+```bash
+cd backend
+
+# 安装依赖
+go mod tidy
+
+# 运行开发服务器
+go run cmd/main.go
+
+# 构建
+go build -o bin/gen2d cmd/main.go
+
+# 运行全部测试
+go test ./...
+
+# 运行单个包的测试
+go test ./internal/service/...
+
+# 运行单个测试函数
+go test -run TestFunctionName ./internal/service/
+
+# 代码检查
+golangci-lint run
+```
+
+### Frontend (Vite + React)
+
+```bash
+cd frontend
+
+# 安装依赖
+npm install
+
+# 开发服务器
+npm run dev
+
+# 构建生产版本
+npm run build
+
+# 预览生产构建
+npm run preview
+
+# 类型检查
+npm run typecheck
+
+# Lint
+npm run lint
+
+# 运行测试
+npm run test
+
+# 运行单个测试文件
+npm run test -- src/components/AssetCard.test.tsx
+```
+
+## Architecture
+
+### 后端分层
+
+- **Handler** — 解析 HTTP 请求，调用 service，返回响应。不包含业务逻辑。
+- **Service** — 核心业务逻辑：提示词处理、AI 模型调用、素材后处理。
+- **Model** — 请求/响应 DTO、数据库实体（如有）。
+- **Pkg** — 通用工具：图片处理、颜色分析、sprite 切片等。
+
+### 前端架构
+
+- 使用 React + TypeScript，状态管理使用 zustand 或 React Context。
+- API 调用集中在 `services/` 目录，组件不直接发请求。
+- 素材预览和参数调整是核心交互，需要关注 Canvas/WebGL 渲染性能。
+
+### 前后端通信
+
+- RESTful API，JSON 格式。
+- 前端开发时通过 Vite proxy 转发到后端 `localhost:PORT`。
+- 图片素材通过 base64 或对象存储 URL 传输，大文件走 OSS/COS。
+
+## 2D 游戏素材生成约束
+
+### 素材类型
+
+项目需要覆盖以下常见 2D 游戏素材类型：
+
+- **Sprite / 角色** — 像素风、卡通、手绘风等，需支持多帧动画序列
+- **Tilemap / 地形瓦片** — 可无缝拼接的地形纹理（草地、水域、道路等）
+- **UI 元素** — 按钮、血条、对话框、图标等
+- **背景 / 场景** — 横版卷轴背景、俯视视角场景
+- **特效** — 火焰、烟雾、魔法等粒子效果帧
+
+### 风格一致性
+
+- 提供**风格种子 (Style Seed)** 机制：用户选定一套风格后，后续生成继承相同的色板、线条风格、分辨率。
+- 支持**参考图上传**：以已有素材作为风格参考。
+- 生成时返回**风格向量 / 特征参数**，可用于后续生成的风格锁定。
+
+### 管线兼容性
+
+生成的素材需满足主流游戏引擎的导入要求：
+
+- **Sprite Sheet** — 输出标准的 spritesheet 拆分格式，附带 JSON/CSV 元数据（frame 位置、锚点、碰撞框）。
+- **透明通道** — PNG 格式，带 alpha 通道，背景透明。
+- **尺寸规范** — 支持常见尺寸（16×16, 32×32, 48×48, 64×64, 128×128, 256×256），可自定义。
+- **命名规范** — 输出文件遵循 `{category}_{name}_{index}.png` 格式，便于引擎批量导入。
+- **Unity / Godot 导出** — 可选生成 `.aseprite` 元数据或 Unity Sprite Editor 兼容的 `.meta` 信息。
+
+### 生成效率与成本
+
+- 支持**批量生成**：一次请求生成多个变体（如角色的行走 8 方向 × 4 帧）。
+- 提供**低分辨率预览 → 高分辨率出图**的两阶段流程，减少无效生成。
+- 后端应做**请求去重与缓存**：相同提示词 + 参数的结果缓存复用。
+- AI 模型调用支持**异步队列**，前端轮询或 WebSocket 获取结果。
+
+## Conventions
+
+- 后端 Go 代码遵循 [Effective Go](https://go.dev/doc/effective_go) 和 Go 官方 style。
+- 前端使用 ESLint + Prettier，提交前自动格式化。
+- API 路径统一使用 `/api/v1/` 前缀。
+- 错误响应统一格式：`{"code": int, "message": string, "data": any}`。
+- Git commit message 使用中文或英文均可，但需要清晰描述变更内容。