From 09b46740986dc6fa567e1d093551da46a7384dd2 Mon Sep 17 00:00:00 2001 From: huyan Date: Mon, 3 Aug 2026 20:23:42 +0800 Subject: [PATCH 1/8] docs(readme): present Windup product and current delivery status Replace the placeholder README with the product positioning, production flow, core objects, current stage, local development, and documentation links. Reuse the existing Windup bird mark as the repository header artwork. Clarify shipped main-branch scope versus in-progress integration and delivery. --- .github/assets/windup-mark.svg | 16 +++++ README.md | 121 ++++++++++++++++++++++++++++++++- 2 files changed, 135 insertions(+), 2 deletions(-) create mode 100644 .github/assets/windup-mark.svg diff --git a/.github/assets/windup-mark.svg b/.github/assets/windup-mark.svg new file mode 100644 index 0000000..5b16f25 --- /dev/null +++ b/.github/assets/windup-mark.svg @@ -0,0 +1,16 @@ + + Windup + 侧视机械小鸟标志 + + + + + + + + + + + + + diff --git a/README.md b/README.md index 58c325b..cbf12e3 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,119 @@ -# game-asset-character -Generate high-quality 2D game characters. +

+ Windup 机械小鸟标志 +

+ +

Windup

+ +

+ 面向国产小游戏开发者的 2D 角色动态素材生成与资产工作台 +

+ +

交付的是资产，而不是图片。

+ +Windup 面向缺少美术产能的个人开发者和小型团队，把角色构思、动作生成、逐帧质检、试玩与引擎导出收进同一条生产链。用户从文字描述或参考图出发，最终得到可继续补动作、修缺陷、重新导出的角色资产，而不是一次性的生成结果。 + +## 产品链路 + +```text +文字描述 / 参考图 + ↓ +项目约束（风格、视角、精灵尺寸） + ↓ +角色母版 → 动作序列帧 → 逐帧审核 / 局部重生成 + ↓ +Playtest 试玩 → 透明 PNG / Sprite Sheet / 元数据 → 游戏引擎 +``` + +Windup 用角色母版约束跨帧、跨动作的视觉一致性，再用确定性的工程后处理完成去背景、切帧、对齐和打包。当某一帧出问题时，返工单位应该缩小到该帧或该节点，不让已经通过的结果陪着重做。 + +## 核心对象 + +| 对象 | 职责 | +| --- | --- | +| `Project` | 统一管理题材、美术风格、视角与精灵尺寸等项目级约束 | +| `Character` | 角色资产本体；造型、动作实例与帧属于它的资产树 | +| `ActionTemplate` | 可在不同角色间复用的动作规格与生产配方 | +| `Generation` | 一次生成任务及其输入、状态和结果，用于恢复与追溯 | +| `WorkflowRun` | 一次前端制作流程的运行记录，连接生成、确认、回退与导出 | + +产品提供两种入口：`Quick Start` 用自然语言建立标准生产流程；`Workflow Editor` 用画布编排节点、处理并行动作和局部返工。两者共用同一套流程状态和质量门禁，不是两套独立产品。 + +## 当前阶段 + +> [!IMPORTANT] +> `main` 当前是 MS2 工程基线，不是已完成前后端联调的正式产品。 + +| 状态 | 内容 | +| --- | --- | +| 已进入 `main` | 前端模块骨架、领域对象与 API 契约；后端分层骨架与 `project` / `character` / `generation` / `media` 边界；前后端 CI 门禁 | +| 正在开发 | Quick Start 纵向流程、WorkflowRun 编排与恢复、产物审核和节点回退、独立 Playtest | +| 尚未完整交付 | 真实生成链路的端到端联调、完整的质检与导出流程、Cocos 可直接导入的资产包 | + +当前进度以 [`main`](https://github.com/1024XEngineer/Windup/tree/main) 的已合并代码为准。Preview、候选 PR 和 Live Demo 只证明对应的交互或技术验证，不等同于完整产品已交付。 + +## 技术栈 + +- 前端：React 19、TypeScript 6、Vite 8、Tailwind CSS 4、Vitest +- 后端：Python 3.12、FastAPI、Pydantic、SQLAlchemy、uv workspace +- 工程约束：GitHub Actions、Ruff、Pytest、Import Linter、oxlint、oxfmt + +## 本地开发 + +前端使用 Node.js 24： + +```bash +cd frontend +npm ci +npm run dev +``` + +后端使用 Python 3.12 和 [uv](https://docs.astral.sh/uv/)： + +```bash +cd backend +uv sync --frozen +uv run uvicorn windup_app.bootstrap.app:create_app --factory --reload +``` + +## 质量检查 + +```bash +# frontend/ +npm run format:check +npm run lint +npm run typecheck +npm run test +npm run build + +# backend/ +uv run ruff check . +uv run lint-imports +uv run pytest -q +``` + +## 仓库结构 + +```text +Windup/ +├── frontend/ # React 前端、页面与制作流程 +├── backend/ # Python 工作区、领域服务与 API +├── docs/ # 后端模块划分等工程文档 +├── frontend-architecture-v3.md +└── README.md +``` + +## 相关文档 + +- [Windup 产品策划案](https://github.com/1024XEngineer/Windup/issues/37) +- [核心流程与工作流](https://github.com/1024XEngineer/Windup/issues/25) +- [前端架构与模块边界](frontend-architecture-v3.md) +- [前后端 API 契约差异](frontend/API_CONTRACT.md) +- [后端模块划分](docs/module-split.md) + +## 参与贡献 + +功能和核心改动按 `Proposal → Issue → Branch → Pull Request → Review` 推进。开发前请先查看对应 Issue 与领域契约，不要把 Mock 成功、页面预览或未合并 PR 当作主分支交付。 + +## License + +[Apache License 2.0](LICENSE) From 6697936ef1a4b7cb6ae7a5e75b6b93f80cd64915 Mon Sep 17 00:00:00 2001 From: huyan Date: Mon, 3 Aug 2026 20:30:55 +0800 Subject: [PATCH 2/8] docs(readme): expose repository health and contribution links The repository landing page should show live project health without collecting decorative badges. Add main-branch frontend CI, backend CI, and license badges with issue and contributor links. Visitors can verify checks, ask for help, and find project contributors from the README. --- README.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index cbf12e3..8424b5a 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,12 @@

交付的是资产，而不是图片。

+

+ Frontend CI + Backend CI + License +

+ Windup 面向缺少美术产能的个人开发者和小型团队，把角色构思、动作生成、逐帧质检、试玩与引擎导出收进同一条生产链。用户从文字描述或参考图出发，最终得到可继续补动作、修缺陷、重新导出的角色资产，而不是一次性的生成结果。 ## 产品链路 @@ -112,7 +118,9 @@ Windup/ ## 参与贡献 -功能和核心改动按 `Proposal → Issue → Branch → Pull Request → Review` 推进。开发前请先查看对应 Issue 与领域契约，不要把 Mock 成功、页面预览或未合并 PR 当作主分支交付。 +问题、需求和实验记录统一进入 [Issues](https://github.com/1024XEngineer/Windup/issues)。功能和核心改动按 `Proposal → Issue → Branch → Pull Request → Review` 推进。开发前请先查看对应 Issue 与领域契约，不要把 Mock 成功、页面预览或未合并 PR 当作主分支交付。 + +项目的维护与历史贡献见 [Contributors](https://github.com/1024XEngineer/Windup/graphs/contributors)。 ## License From 07034e103e0d4f019da07ab6b0b74176dc20d89e Mon Sep 17 00:00:00 2001 From: huyan Date: Mon, 3 Aug 2026 20:35:10 +0800 Subject: [PATCH 3/8] docs(readme): add bilingual section headings Public repository navigation should remain understandable to both Chinese and English readers. Translate every second-level heading with a consistent Chinese / English pattern. GitHub's generated outline now exposes the same bilingual structure throughout the README. --- README.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 8424b5a..26a39bf 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ Windup 面向缺少美术产能的个人开发者和小型团队，把角色构思、动作生成、逐帧质检、试玩与引擎导出收进同一条生产链。用户从文字描述或参考图出发，最终得到可继续补动作、修缺陷、重新导出的角色资产，而不是一次性的生成结果。 -## 产品链路 +## 产品链路 / Product Workflow ```text 文字描述 / 参考图 @@ -32,7 +32,7 @@ Playtest 试玩 → 透明 PNG / Sprite Sheet / 元数据 → 游戏引擎 Windup 用角色母版约束跨帧、跨动作的视觉一致性，再用确定性的工程后处理完成去背景、切帧、对齐和打包。当某一帧出问题时，返工单位应该缩小到该帧或该节点，不让已经通过的结果陪着重做。 -## 核心对象 +## 核心对象 / Core Concepts | 对象 | 职责 | | --- | --- | @@ -44,7 +44,7 @@ Windup 用角色母版约束跨帧、跨动作的视觉一致性，再用确定 产品提供两种入口：`Quick Start` 用自然语言建立标准生产流程；`Workflow Editor` 用画布编排节点、处理并行动作和局部返工。两者共用同一套流程状态和质量门禁，不是两套独立产品。 -## 当前阶段 +## 当前阶段 / Project Status > [!IMPORTANT] > `main` 当前是 MS2 工程基线，不是已完成前后端联调的正式产品。 @@ -57,13 +57,13 @@ Windup 用角色母版约束跨帧、跨动作的视觉一致性，再用确定 当前进度以 [`main`](https://github.com/1024XEngineer/Windup/tree/main) 的已合并代码为准。Preview、候选 PR 和 Live Demo 只证明对应的交互或技术验证，不等同于完整产品已交付。 -## 技术栈 +## 技术栈 / Tech Stack - 前端：React 19、TypeScript 6、Vite 8、Tailwind CSS 4、Vitest - 后端：Python 3.12、FastAPI、Pydantic、SQLAlchemy、uv workspace - 工程约束：GitHub Actions、Ruff、Pytest、Import Linter、oxlint、oxfmt -## 本地开发 +## 本地开发 / Local Development 前端使用 Node.js 24： @@ -81,7 +81,7 @@ uv sync --frozen uv run uvicorn windup_app.bootstrap.app:create_app --factory --reload ``` -## 质量检查 +## 质量检查 / Quality Checks ```bash # frontend/ @@ -97,7 +97,7 @@ uv run lint-imports uv run pytest -q ``` -## 仓库结构 +## 仓库结构 / Repository Structure ```text Windup/ @@ -108,7 +108,7 @@ Windup/ └── README.md ``` -## 相关文档 +## 相关文档 / Documentation - [Windup 产品策划案](https://github.com/1024XEngineer/Windup/issues/37) - [核心流程与工作流](https://github.com/1024XEngineer/Windup/issues/25) @@ -116,12 +116,12 @@ Windup/ - [前后端 API 契约差异](frontend/API_CONTRACT.md) - [后端模块划分](docs/module-split.md) -## 参与贡献 +## 参与贡献 / Contributing 问题、需求和实验记录统一进入 [Issues](https://github.com/1024XEngineer/Windup/issues)。功能和核心改动按 `Proposal → Issue → Branch → Pull Request → Review` 推进。开发前请先查看对应 Issue 与领域契约，不要把 Mock 成功、页面预览或未合并 PR 当作主分支交付。 项目的维护与历史贡献见 [Contributors](https://github.com/1024XEngineer/Windup/graphs/contributors)。 -## License +## 许可证 / License [Apache License 2.0](LICENSE) From 06bfc40c1f15724a0c06aa214032b6785bae5dac Mon Sep 17 00:00:00 2001 From: huyan Date: Mon, 3 Aug 2026 20:39:09 +0800 Subject: [PATCH 4/8] docs(readme): remove repository badges The landing page should keep attention on the product instead of build metadata. Remove the frontend CI, backend CI, and license badge row from the header. The header now contains only the brand mark, product positioning, and core statement. --- README.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/README.md b/README.md index 26a39bf..df45046 100644 --- a/README.md +++ b/README.md @@ -10,12 +10,6 @@

交付的是资产，而不是图片。

-

- Frontend CI - Backend CI - License -

- Windup 面向缺少美术产能的个人开发者和小型团队，把角色构思、动作生成、逐帧质检、试玩与引擎导出收进同一条生产链。用户从文字描述或参考图出发，最终得到可继续补动作、修缺陷、重新导出的角色资产，而不是一次性的生成结果。 ## 产品链路 / Product Workflow From 051912ebca6943a4dfab37267115aeaf9c6da6e1 Mon Sep 17 00:00:00 2001 From: huyan Date: Mon, 3 Aug 2026 20:42:00 +0800 Subject: [PATCH 5/8] docs(readme): replace defensive delivery language The repository introduction had internal validation language that interrupted the product narrative. Rewrite product, status, workflow, and contribution copy as direct reader-facing statements. Progress remains accurate while the README reads as a public product page. --- README.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index df45046..a11e73c 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@

交付的是资产，而不是图片。

-Windup 面向缺少美术产能的个人开发者和小型团队，把角色构思、动作生成、逐帧质检、试玩与引擎导出收进同一条生产链。用户从文字描述或参考图出发，最终得到可继续补动作、修缺陷、重新导出的角色资产，而不是一次性的生成结果。 +Windup 面向缺少美术产能的个人开发者和小型团队，把角色构思、动作生成、逐帧质检、试玩与引擎导出收进同一条生产链。用户从文字描述或参考图出发，最终得到可以持续补充动作、修正缺陷和重新导出的角色资产。 ## 产品链路 / Product Workflow @@ -24,7 +24,7 @@ Windup 面向缺少美术产能的个人开发者和小型团队，把角色构 Playtest 试玩 → 透明 PNG / Sprite Sheet / 元数据 → 游戏引擎 ``` -Windup 用角色母版约束跨帧、跨动作的视觉一致性，再用确定性的工程后处理完成去背景、切帧、对齐和打包。当某一帧出问题时，返工单位应该缩小到该帧或该节点，不让已经通过的结果陪着重做。 +Windup 用角色母版约束跨帧、跨动作的视觉一致性，再用确定性的工程后处理完成去背景、切帧、对齐和打包。出现缺陷时，返工可以缩小到具体帧或节点，已通过的结果继续保留。 ## 核心对象 / Core Concepts @@ -36,20 +36,19 @@ Windup 用角色母版约束跨帧、跨动作的视觉一致性，再用确定 | `Generation` | 一次生成任务及其输入、状态和结果，用于恢复与追溯 | | `WorkflowRun` | 一次前端制作流程的运行记录，连接生成、确认、回退与导出 | -产品提供两种入口：`Quick Start` 用自然语言建立标准生产流程；`Workflow Editor` 用画布编排节点、处理并行动作和局部返工。两者共用同一套流程状态和质量门禁，不是两套独立产品。 +产品提供两种入口：`Quick Start` 用自然语言建立标准生产流程；`Workflow Editor` 用画布编排节点、处理并行动作和局部返工。两者共用同一套流程状态和质量门禁，分别服务快速创建与精细编排。 ## 当前阶段 / Project Status -> [!IMPORTANT] -> `main` 当前是 MS2 工程基线，不是已完成前后端联调的正式产品。 +Windup 目前处于 MS2 开发阶段，当前重点是将前后端模块骨架接成一条可演示的角色资产生产链。 | 状态 | 内容 | | --- | --- | -| 已进入 `main` | 前端模块骨架、领域对象与 API 契约；后端分层骨架与 `project` / `character` / `generation` / `media` 边界；前后端 CI 门禁 | +| 主仓现状 | 前端模块骨架、领域对象与 API 契约；后端分层骨架与 `project` / `character` / `generation` / `media` 边界；前后端 CI 门禁 | | 正在开发 | Quick Start 纵向流程、WorkflowRun 编排与恢复、产物审核和节点回退、独立 Playtest | -| 尚未完整交付 | 真实生成链路的端到端联调、完整的质检与导出流程、Cocos 可直接导入的资产包 | +| 下一步 | 打通真实生成链路的端到端联调，补齐质检与导出流程，生成 Cocos 可直接导入的资产包 | -当前进度以 [`main`](https://github.com/1024XEngineer/Windup/tree/main) 的已合并代码为准。Preview、候选 PR 和 Live Demo 只证明对应的交互或技术验证，不等同于完整产品已交付。 +项目进度见 [`main`](https://github.com/1024XEngineer/Windup/tree/main) 与 [Issues](https://github.com/1024XEngineer/Windup/issues)。 ## 技术栈 / Tech Stack @@ -112,7 +111,7 @@ Windup/ ## 参与贡献 / Contributing -问题、需求和实验记录统一进入 [Issues](https://github.com/1024XEngineer/Windup/issues)。功能和核心改动按 `Proposal → Issue → Branch → Pull Request → Review` 推进。开发前请先查看对应 Issue 与领域契约，不要把 Mock 成功、页面预览或未合并 PR 当作主分支交付。 +问题、需求和实验记录统一进入 [Issues](https://github.com/1024XEngineer/Windup/issues)。功能和核心改动按 `Proposal → Issue → Branch → Pull Request → Review` 推进，开发前请先查看对应 Issue 与领域契约。 项目的维护与历史贡献见 [Contributors](https://github.com/1024XEngineer/Windup/graphs/contributors)。 From 19216d7094d16cf02893c2998d25077bd7c7cc09 Mon Sep 17 00:00:00 2001 From: huyan Date: Mon, 3 Aug 2026 20:43:41 +0800 Subject: [PATCH 6/8] docs(readme): update the current milestone to MS3 The project has moved beyond the milestone named in the repository overview. Replace the stale MS2 reference with the current MS3 development stage. The README now reflects the milestone confirmed by the project team. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a11e73c..62cc1cf 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ Windup 用角色母版约束跨帧、跨动作的视觉一致性，再用确定 ## 当前阶段 / Project Status -Windup 目前处于 MS2 开发阶段，当前重点是将前后端模块骨架接成一条可演示的角色资产生产链。 +Windup 目前处于 MS3 开发阶段，当前重点是将前后端模块骨架接成一条可演示的角色资产生产链。 | 状态 | 内容 | | --- | --- | From 59a40042b12cd50e792d8631d610fdb46cdb5316 Mon Sep 17 00:00:00 2001 From: huyan Date: Mon, 3 Aug 2026 20:48:00 +0800 Subject: [PATCH 7/8] docs(readme): redefine the MS3 product focus MS2 delivered the product MVP, so the README should no longer frame the current work as assembling a demo. Recast MS3 around extending existing characters through a constrained workflow, local reruns, and persistent runs. Align the product flow and editor description with the current milestone decisions. --- README.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 62cc1cf..0c47df8 100644 --- a/README.md +++ b/README.md @@ -15,13 +15,12 @@ Windup 面向缺少美术产能的个人开发者和小型团队，把角色构 ## 产品链路 / Product Workflow ```text -文字描述 / 参考图 - ↓ -项目约束（风格、视角、精灵尺寸） - ↓ -角色母版 → 动作序列帧 → 逐帧审核 / 局部重生成 - ↓ -Playtest 试玩 → 透明 PNG / Sprite Sheet / 元数据 → 游戏引擎 +新角色：文字描述 / 参考图 → 项目约束 → 角色母版 +已有角色：从资产库继续生产 ─────────────┘ + ↓ + 动作序列帧 → 逐帧审核 / 局部重生成 + ↓ + Playtest 试玩 → PNG / Sprite Sheet / 元数据 → 游戏引擎 ``` Windup 用角色母版约束跨帧、跨动作的视觉一致性，再用确定性的工程后处理完成去背景、切帧、对齐和打包。出现缺陷时，返工可以缩小到具体帧或节点，已通过的结果继续保留。 @@ -36,17 +35,18 @@ Windup 用角色母版约束跨帧、跨动作的视觉一致性，再用确定 | `Generation` | 一次生成任务及其输入、状态和结果，用于恢复与追溯 | | `WorkflowRun` | 一次前端制作流程的运行记录，连接生成、确认、回退与导出 | -产品提供两种入口：`Quick Start` 用自然语言建立标准生产流程；`Workflow Editor` 用画布编排节点、处理并行动作和局部返工。两者共用同一套流程状态和质量门禁，分别服务快速创建与精细编排。 +产品提供两种入口：`Quick Start` 用自然语言建立标准生产流程；`Workflow Editor` 在系统预置的成熟管线上追加动作分支、微调参数和局部返工。两者共用同一套流程状态和质量门禁，分别服务快速创建与精细控制。 ## 当前阶段 / Project Status -Windup 目前处于 MS3 开发阶段，当前重点是将前后端模块骨架接成一条可演示的角色资产生产链。 +MS2 已完成 Windup 的产品 MVP，验证了角色资产生产的核心链路。MS3 的重点从“完成一次生成”转向“持续完善已有角色资产”：用户可以从资产库回到已有角色，为它补充动作、重做有问题的分支，并保留未受影响的资产。 | 状态 | 内容 | | --- | --- | -| 主仓现状 | 前端模块骨架、领域对象与 API 契约；后端分层骨架与 `project` / `character` / `generation` / `media` 边界；前后端 CI 门禁 | -| 正在开发 | Quick Start 纵向流程、WorkflowRun 编排与恢复、产物审核和节点回退、独立 Playtest | -| 下一步 | 打通真实生成链路的端到端联调，补齐质检与导出流程，生成 Cocos 可直接导入的资产包 | +| MS2 产出 | 完成产品 MVP，跑通并验证角色资产生产的核心体验 | +| MS3 产品主线 | 已有角色补动作；工作流采用固定成熟管线，通过卡片加号追加分支，支持参数微调与局部重跑 | +| MS3 工程重点 | 持久化 `WorkflowRun` 并关联角色，串起工作流编辑、产物审核、节点回退与 Playtest | +| 后续探索 | Quick Start Agent、3D 动作生成路线、多视角资产与项目级导出 | 项目进度见 [`main`](https://github.com/1024XEngineer/Windup/tree/main) 与 [Issues](https://github.com/1024XEngineer/Windup/issues)。 From 890bd739ce16be24f338f19c02d3f0bc4482a923 Mon Sep 17 00:00:00 2001 From: huyan Date: Mon, 3 Aug 2026 21:04:26 +0800 Subject: [PATCH 8/8] docs(readme): clarify supported Node.js versions The README currently presents Node.js 24 as the only supported frontend runtime. Document the dependency-supported ranges and keep Node.js 24 as the CI runtime. Contributors can distinguish supported local runtimes from the version used by CI. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0c47df8..947814d 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,7 @@ MS2 已完成 Windup 的产品 MVP，验证了角色资产生产的核心链路 ## 本地开发 / Local Development -前端使用 Node.js 24： +前端支持 Node.js `^20.19.0`、`^22.12.0` 或 `>=24.0.0`；CI 使用 Node.js 24： ```bash cd frontend