feat: integrate verified Windup source snapshot

[xyh202131]

本次内容

• 从 Windup-source-20260805-160651.zip 解压并恢复当前已核验的完整源码快照。
• 整合前端页面、WorkflowRun 编排、Quick Start、Workflow Editor、Playtest、资产导出与登录界面。
• 整合项目、角色、媒体上传、生成任务、Playtest 核验及 Redis 可选配置等后端实现。
• 同步架构、接口和模块拆分文档。
• 增加 Windows start.bat 与 macOS/Linux start.command 两个一键启动入口。

范围说明

• 本 PR 以最新 main 为基线，作为独立整合 PR 提交。
• 不包含 chaifen 目录。
• 不包含 node_modules、dist/build、Python 虚拟环境、缓存、数据库、日志、本地 .env 或 Git 元数据。
• 这是一次较大的源码整合快照，建议按前端、后端、文档和启动脚本分块审查。

验证

• 前端：59 个测试文件、362 个测试全部通过。
• 前端：TypeScript 类型检查、Oxlint、格式检查和生产构建通过。
• 后端：65 个 Pytest 测试全部通过。
• 后端：Ruff 检查通过。
• 后端：Import Linter 两项分层约束全部通过。
• 已核验 start.bat 与 start.command 均包含在提交中。
• 已核验提交范围中没有 chaifen 和构建产物。

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
windup	Ignored	Preview	Aug 5, 2026 8:50am

[johnnyzhang-eng]

整合工作量很大，CI 四项全绿（Branch name / Commit messages / Frontend checks / lint-and-test），前后端测试数也很扎实。下面按「合并前必须处理」和「合并顺序」分开列，每条都给了可复核的位置。

当前状态先说一句：mergeable: false、mergeable_state: dirty，base 是 711e739 而 main 已到 795b51e，所以无论如何都要先 rebase 一次——下面第二条正好是 rebase 时会撞上的东西。

---

一、合并前建议处理

1. providers/sufy.py 会把一个已实测的烧钱缺陷带进主仓

新增文件 backend/packages/framework/src/windup_framework/providers/sufy.py，diff 里这一行：

return client.get(url).raise_for_status().content

这是取已经生成完毕的视频成品那一步——提交任务、轮询、等待都已成功，钱已经付了，只差把 bytes 取回来。单次读取、无重试、不校验长度，读 body 断一次整单就废：

peer closed connection without sending complete message body
(received 720450 bytes, expected 929531)

2026-08-05 实测同一角色连续两单都死在这里，各烧一次生成费用，第三单一次成功——是概率性中断，不是稳定失败。

主仓 main 目前没有这个文件（framework/providers/ 下只有 chat.py / image.py / video.py 三个 OpenAI SDK 客户端工厂），所以这不是「主仓已有的问题」，而是这个 PR 会引入的问题。

已建 Issue #129 记录，修复提在后端开发线 xiaocheny214#33（重试 + Content-Length 校验，81 tests 全过，并用旧实现做过控制样本验证）。建议本 PR 合并前带上该修复，或等它合入后同步过来。

2. 与一小时前刚合并的 #128 直接对冲：工程文档重新入仓

#128 今天 02:35 合入，删掉 docs/module-split.md，理由写得很清楚：内容已迁到 Issue。

本 PR 的文件列表里：

状态	文件
modified	docs/module-split.md ← #128 刚删掉的那份
added	docs/module-split-plan.md
added	docs/sse-generation-flow.md
added	docs/superpowers/plans/2026-08-05-home-auth-account.md
added	docs/superpowers/plans/2026-08-05-uploaded-template-shortcut.md
added	docs/superpowers/specs/2026-08-05-home-auth-account-design.md
added	docs/superpowers/specs/2026-08-05-uploaded-template-shortcut-design.md

《GitHub 过程管理规范》里「设计/架构决策等工程文档写进 Issue，不 commit 成主仓 md；用户文档才入库」是明确条款。superpowers/plans 与 specs 那四份更像是生成过程的中间产物。

另外 frontend/API_CONTRACT.md、ARCHITECTURE_GUARDRAILS.md、MODULES.md、api-reference.md 也是同一类，是否保留可以讨论——但 docs/module-split.md 这一份是刚被显式移除的，重新加回来需要说明理由。

3. root_motion 单位：同一个 PR 内前后端不一致

• 前端 frontend/src/entities/character/index.ts：

  /** 单帧相对动作首帧的根位移，单位为像素。 */
  export interface FrameRootMotion { dx: number; /** 正值表示向上。 */ dy: number }

• 后端 server/character/model.py：

  class CharacterRootMotion(BaseModel):
      """单帧相对动作首帧的根位移。"""
      dx: float
      dy: float

后端没写单位，也没写 dy 的符号约定，而它是存储端。#81 第一节里这个量用的是另一套口径（以角色总高 = 1.0 归一化），渲染出帧那条线产出的就是归一化值。

后果很具体：两条生成路线往同一个 character_data 写 root_motion，一条写像素、一条写归一化，两边都不会报错，要到 Playtest 里角色位移大得离谱或几乎不动才发现。而这个字段已经会随导出包的 metadata JSON 发出去。

建议在后端字段的 description 里把单位与符号写死（沿用前端的「像素、dy 正值向上」最省事，因为前端已经在用），归一化那套由产出方在写入前换算。

4. 两个 ActionType，宽度不一样

本 PR 里有两处定义：

位置	取值
app 层 common/enums	walk / idle / jump / attack / custom（本 PR 新增 jump）
ai_engine 层	idle / walk / run / jump / attack / hit / custom
前端 union	'walk' | 'idle' | 'attack' | 'jump' | 'custom'

run 与 hit 在 ai_engine.strategy.ROUTE_MATRIX 里有对应策略，但 API 入参枚举里没有、前端类型里也没有，当前从外部无法触达。

如果 ai_engine 那份是内部路由枚举、不打算对外，建议在 docstring 里写明并说明 run/hit 的触达路径；如果打算对外，三处要一起加。

顺带一提，本 PR 把前端 ActionType 从 string 收窄成闭合 union，并删掉了原注释「PR #75 将动作类型定义为字符串；已知类型之外的后端扩展也应原样保留」。收窄本身我赞成（string 拿不到任何类型保护），但那条注释描述的是后端扩展新类型时前端不该炸——收窄之后这个保障没了，建议在解析处补一个 fallback，而不是让未知类型直接失配。

---

二、需要定合并顺序，不是对错问题

5. CORS 与 #115 改同一个 create_app()

本 PR 的 bootstrap/app.py：

allow_origins=[
    "http://localhost:5173", ... "http://localhost:5177",
    "http://127.0.0.1:5173", ... "http://127.0.0.1:5177",
],
allow_credentials=True,

先说清楚：这个白名单本身没有安全问题，列举式的 localhost 来源不存在通配放权。两个实际问题：

1. 没有环境变量入口。 部署环境要放行别的来源就得改代码、重新构建镜像。
2. 没有 4173。 那是 vite preview 的端口，也就是生产构建在本地跑演示时用的端口；5173 是 dev server，两者不同。

#115 做的是同一个函数：来源走 WINDUP_CORS_ORIGINS 覆盖、默认值含 4173，另有 WINDUP_CORS_ORIGIN_REGEX 供预览域名用且默认不开（避免 allow_credentials=True 配上通配正则把带凭证的跨域权限放给整个域）。

两个 PR 必然文本冲突。建议 #115 先合（它只动部署面，范围小、CI 全绿、机器评审两条已修），本 PR rebase 后保留 env 入口并把 5174–5177 并进默认值；反过来也行，但那样这两条能力要在本 PR 里重做一遍。

6. SSE 事件名：本 PR 是对的，建议改 #124 的正文

本 PR 的实现是单一事件：

return f"event: task_update\ndata: {json.dumps(payload, ensure_ascii=False)}\n\n"

这与线上实际抓到的行为和前端已落地的实现一致。而 #124 正文第 129–131 行定义的是三事件 progress / completed / failed，评论里也说了「现使用本 issue 定义好的版本」。

我的建议是以本 PR 与线上为准，回头修 #124 的正文——已实现且线上验证过的那套优先。但这需要在 #124 那边确认一下，否则按三事件去改前端会一个事件都收不到，而且不报错，表现为任务永远不动。

（顺带：线上实测服务端发完终态就关流但带了 retry: 3000，浏览器原生 EventSource 会每 3 秒重连、45 秒内重连 15 次并重复触发业务回调。不确定本 PR 是否已处理，如果没有，终态需要一个明确的收尾信号或由前端手动 close()。）

---

三、一个想确认意图的地方

删除的三个文件里有两个是两天前刚落地的品牌视觉：

• frontend/src/pages/home/brand-bird.tsx ← feat(home): add the first screen on the current architecture #91（08-04）
• .github/assets/windup-mark.svg ← docs(readme): present Windup product and MS3 focus #93（08-04）

我核过了：README 里那行 <img src=".github/assets/windup-mark.svg"> 和 home/index.tsx 里的引用在本 PR 里也一并删了，所以不会出现坏图或构建失败，这点没问题。

只是「撤掉品牌标识」是个产品决策，夹在一个标题为「integrate verified source snapshot」的 PR 里不太容易被看见。如果是有意的，建议在 PR 描述里单列一句；如果是快照来源分支本来就没有这两个文件而被顺带覆盖了，那更需要确认。

---

建议的推进顺序

1. feat(deploy): 容器化后端 + /health 探针（已按评审拆出 CORS 到 #140） #115 先合（部署面，范围最小）
2. 本 PR rebase 到最新 main（会带上 docs: remove migrated module split doc #128 的 docs 删除），处理上面第 1、2 条
3. 第 3、4 条可以在本 PR 里改，也可以作为紧跟的小 PR——但建议在 root_motion 随导出包发出去之前定掉

上面每条的位置我都写了，需要的话我可以针对某一条直接提改动。