diff --git a/README.md b/README.md index ae6e3f01..4013a55a 100644 --- a/README.md +++ b/README.md @@ -20,51 +20,62 @@

windup.xin status + Windup v1.0.0 Frontend CI Backend CI Test coverage

-

Windup 已上线，现已开放注册。

+

Windup 已于 2026 年 8 月完成 v1.0.0 结项交付，在线体验与开源代码继续开放。

Windup 角色从线稿、母版到游戏资产的生成旅程

-Windup 面向缺少美术产能的个人开发者和小型团队，把角色构思、动作生成、逐帧审核、试玩与引擎导出收进同一条生产链。用户从文字描述或参考图出发，最终得到可以持续补充动作、修正缺陷和重新导出的角色资产。 +Windup 面向缺少美术产能的个人开发者和小型团队，把角色构思、动作生成、逐帧审核、试玩与引擎导出收进同一条生产链。用户从文字描述、参考图或已有资产出发，最终得到可以持续补充动作、修正缺陷和重新导出的角色资产。 ## 当前能力 / What You Can Do -| 能力 | 当前可用内容 | +以下为项目结项时已经进入 `main` 的能力： + +| 能力 | 已交付内容 | | --- | --- | -| 项目与资产库 | 管理项目约束、角色、造型、动作与帧，继续扩展已有角色资产 | -| Quick Start | 用自然语言描述角色和动作，由系统建立标准制作流程 | -| Workflow Editor | 在真实节点画布中确认角色母版、动作首帧、生成方式、完整动画与审核状态 | -| 角色与动作生成 | 接入真实生成任务，保存任务状态与产物，支持失败恢复与结果追溯 | -| 审核与局部返工 | 对候选图和动作结果进行确认，在具体节点重试而不必重做整条流程 | -| Playtest 与导出 | 在浏览器中预览动作，并导出透明 PNG、Sprite Sheet、动画 JSON 与 ZIP 资源包 | +| 项目与资产库 | 管理项目画风、视角与精灵尺寸，以及角色、造型、动作和分方向帧；已有角色可以继续增加动作 | +| Quick Start | 通过自然语言、参考图或已有角色建立标准制作流程，保存并恢复每一次制作记录 | +| Workflow Editor | 在节点画布中确认单向、四向或八向母版，选择生成方式，并处理动作首帧、完整动画与审核状态 | +| 生成与后处理 | 支持图像、视频与可选三渲二路线，完成去背景、切帧、对齐和可选像素网格重建 | +| 审核与恢复 | 确认候选图与动作结果，按节点或方向局部重试，并保留已经确认的资产 | +| Playtest 与导出 | 在浏览器中试玩单向、四向或八向动作，导出透明 PNG、Sprite Sheet、GIF、动画 JSON 与 ZIP 资源包 | +| Cocos Creator | 为 Cocos Creator 3.8.x 提供本机配对、一键导入与离线资源包回退 | -三渲二、多方向资产和更多引擎适配仍在推进。相关基础能力进入仓库不等于已进入在线产品主流程；当前进度以 [`main`](https://github.com/1024XEngineer/Windup/tree/main) 与 [Issues](https://github.com/1024XEngineer/Windup/issues) 为准。 +[`v1.0.0`](https://github.com/1024XEngineer/Windup/releases/tag/v1.0.0) 是本次结项交付的版本基线；[`main`](https://github.com/1024XEngineer/Windup/tree/main) 还包含发布后合入的收尾改动。三渲二、模型选择与高质量抠图依赖部署配置和硬件条件，不代表所有实例默认启用。 ## 产品链路 / Product Workflow ```text -新角色：文字描述 / 参考图 → 项目约束 → 角色母版 -已有角色：从资产库继续生产 ─────────────┘ - ↓ - 动作序列帧 → 审核 / 局部重生成 - ↓ - Playtest 试玩 → PNG / Sprite Sheet / 元数据 → 游戏引擎 +文字描述 / 参考图 / 已有角色 + ↓ +项目约束 → 单向 / 四向 / 八向角色母版 + ↓ +图像生成 / 视频生成 / 可选三渲二 + ↓ +分方向动作帧 → 审核 / 局部重生成 / 可选像素网格重建 + ↓ +Playtest → PNG / Sprite Sheet / GIF / JSON / ZIP + ↓ +Cocos Creator 3.8.x 一键导入 / 其他游戏工程 ``` -Windup 用角色母版约束跨帧、跨动作的视觉一致性，再用确定性的工程后处理完成去背景、切帧、对齐和打包。出现缺陷时，返工可以缩小到具体节点，已经确认的结果继续保留。 +Windup 用角色母版约束跨方向、跨帧和跨动作的视觉一致性，再用确定性的工程后处理完成去背景、切帧、对齐、网格重建和打包。出现缺陷时，返工可以缩小到具体节点或方向，已经确认的结果继续保留。 ## 核心对象 / Core Concepts | 对象 | 职责 | | --- | --- | | `Project` | 统一管理题材、美术风格、视角与精灵尺寸等项目级约束 | -| `Character` | 角色资产本体；造型、动作实例与帧属于它的资产树 | +| `Character` | 角色的稳定身份；造型、动作与帧属于它的长期资产树 | +| `CharacterOutfit` | 角色的一套造型及其母版视图，可选关联复用的 3D 资产 | +| `CharacterAction` | 某套造型下的一组动作帧，保存方向、帧序、时长与循环语义 | | `Generation` | 一次生成任务及其输入、状态和结果，用于恢复与追溯 | | `WorkflowRun` | 一次制作流程的持久化运行记录，连接生成、确认、回退与导出 | @@ -72,21 +83,28 @@ Windup 用角色母版约束跨帧、跨动作的视觉一致性，再用确定 ## 技术栈 / Tech Stack -- 前端：React 19、TypeScript 6、Vite 8、Tailwind CSS 4、Vitest +- 前端：React 19、TypeScript 6、Vite 8、Tailwind CSS 4、Three.js、Vitest - 后端：Python 3.12、FastAPI、Pydantic、SQLAlchemy、uv workspace +- 原生与引擎工具：Rust 像素网格重建器、Cocos Creator 3.8.x 扩展与 Node.js 导入工具 - 基础设施：PostgreSQL、Redis、Docker Compose、Nginx - 工程约束：GitHub Actions、Ruff、Pytest、Import Linter、oxlint、oxfmt ## 本地开发 / Local Development -需要 Node.js 24、Python 3.12、[uv](https://docs.astral.sh/uv/)、PostgreSQL 与 Redis。 +需要 Node.js 24、Python 3.12、[uv](https://docs.astral.sh/uv/)、PostgreSQL 16 与 Redis 7。 -先准备本地配置和依赖服务： +先准备应用配置。`POSTGRES_*`、`REDIS_URL` 与 `JWT_SECRET` 是启动后端所需的基础配置；生成、存储与邮件能力还需要各自的服务凭据。 ```bash cp .env.example .env -# 在 .env 中配置 POSTGRES_PASSWORD、JWT_SECRET（至少 32 字符）及所需服务凭据 -docker compose up -d postgres redis +# 修改 POSTGRES_* 与 REDIS_URL，并新增至少 32 字符的 JWT_SECRET +``` + +PostgreSQL 与 Redis 已从应用层 Compose 拆出。需要复用仓库的数据层配置时，复制 `.env.db.example`，让应用 `.env` 中的 `POSTGRES_PASSWORD`、`POSTGRES_PORT` 与 `REDIS_URL` 对应同一组连接信息，再启动独立数据层： + +```bash +cp .env.db.example .env.db +docker compose --env-file .env.db -f docker-compose.db.yml up -d ``` 启动后端： @@ -97,19 +115,26 @@ uv sync --frozen uv run uvicorn windup_app.bootstrap.app:create_app --factory --reload ``` -另开一个终端启动前端： +另开一个终端启动 Worker。生成任务与验证码邮件都通过 Redis Stream 消费；不启动 Worker 时，任务会停在排队状态。 + +```bash +cd backend +uv run python -m windup_app.worker +``` + +再启动前端： ```bash cd frontend npm ci -npm run dev +VITE_API_BASE_URL=http://localhost:8000 npm run dev ``` -前端开发服务器默认访问 `http://localhost:5173`，后端健康检查为 `http://localhost:8000/health`。前端需要指向其他后端时，通过构建期变量 `VITE_API_BASE_URL` 配置。 +前端开发服务器默认访问 `http://localhost:5173`，后端健康检查为 `http://localhost:8000/health`。`VITE_API_BASE_URL` 是构建期变量，连接其他后端时需要在启动或构建前设置。 ## 质量检查 / Quality Checks -以下命令与 GitHub Actions 的主要检查保持一致： +按改动影响范围运行对应目录的检查： ```bash # frontend/ @@ -124,6 +149,17 @@ uv run ruff check . uv run python -m scripts.export_openapi uv run lint-imports uv run pytest -q --cov=packages + +# native/pixel-perfect/crates/reconstructor/ +cargo fmt --check +cargo test --release --locked + +# tools/cocos-importer/ +npm test +cd extension +npm test +npm run build +npm run verify-package ``` ## 仓库结构 / Repository Structure @@ -132,20 +168,29 @@ uv run pytest -q --cov=packages Windup/ ├── frontend/ # React 前端、产品页面与制作流程 ├── backend/ # FastAPI 应用、领域服务、生成引擎与基础设施 +├── native/ # Rust 原生像素网格重建器 +├── tools/ # Cocos Creator 导入器等独立工具 +├── docs/ # 规格、计划与验收材料 ├── openapi.json # 从后端自动生成的接口契约 -└── docker-compose.yml # PostgreSQL、Redis、后端与前端构建任务 +├── VERSION # 当前产品版本 +├── docker-compose.yml # 后端、Worker 与前端应用层 +└── docker-compose.db.yml # PostgreSQL 与 Redis 数据层 ``` ## 相关文档 / Documentation - [在线产品](https://windup.xin) +- [产品使用手册](https://windup.xin/guide) +- [v1.0.0 结项版本](https://github.com/1024XEngineer/Windup/releases/tag/v1.0.0) - [Windup 产品策划案](https://github.com/1024XEngineer/Windup/issues/37) - [核心流程与工作流](https://github.com/1024XEngineer/Windup/issues/25) +- [Cocos Creator 一键导入](tools/cocos-importer/README.md) +- [像素网格重建器](native/pixel-perfect/crates/reconstructor/README.md) - [OpenAPI 接口契约](openapi.json) ## 参与贡献 / Contributing -Bug、需求和实验建议统一进入 [Issues](https://github.com/1024XEngineer/Windup/issues)。功能和核心改动按 `Proposal → Issue → Branch → Pull Request → Review` 推进，开发前请先查看对应 Issue 与领域契约。 +Bug、需求和实验建议统一进入 [Issues](https://github.com/1024XEngineer/Windup/issues)。功能和核心改动按 `Proposal → Issue → Branch → Pull Request → Review` 推进，详细流程见 [CONTRIBUTING.md](CONTRIBUTING.md)。 项目的维护与历史贡献见 [Contributors](https://github.com/1024XEngineer/Windup/graphs/contributors)。