docs: 完善 README,精简 CLAUDE.md

- 重写 README:补充技术栈徽标、快速开始、项目结构、线上体验链接
- 简化 CLAUDE.md:目录结构和架构说明改为引用 docs/architecture.md
- 移除不存在的 lint/test 命令
- 删除无内容的 README.en.md
This commit is contained in:
2026-05-23 18:05:53 +08:00
parent a0823dc64d
commit e63165f898
3 changed files with 48 additions and 151 deletions
+2 -91
View File
@@ -8,35 +8,7 @@ gen2d — AI 驱动的 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
```
详见 [docs/architecture.md](docs/architecture.md) 中的后端分层结构与前端组件树。
## Common Commands
@@ -86,72 +58,11 @@ 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 获取结果。
详见 [docs/architecture.md](docs/architecture.md),涵盖多智能体管线、后端分层、前端组件树、API 设计、素材生成约束等。
## Conventions