diff --git a/docs/frontend-module-breakdown.md b/docs/frontend-module-breakdown.md
new file mode 100644
index 0000000..5e6b372
--- /dev/null
+++ b/docs/frontend-module-breakdown.md
@@ -0,0 +1,504 @@
+# Windup MS2 前端模块拆分（完善版）
+
+本文以业务功能拆分 Windup 前端模块，结合现有 Windup 工作台能力、`frontend-module-breakdown.md` 和已确认的产品方向整理。模块划分用于明确功能与依赖，不代表代码必须按相同目录拆分。
+
+阶段标识：
+
+- **MS2**：本阶段需要形成完整用户闭环。
+- **MS2 支撑**：本阶段为核心流程提供基础能力，但后续可能替换实现方式。
+- **后续**：保留产品位置，本阶段不要求落地。
+
+## 主线流程
+
+`Quick Start / 从项目开始 → 创建固定工作流运行 → 项目约束 → 角色与造型基准帧 → 动作生成 → 系统质检 → 人工确认入库 → 逐帧审核与修复 →（建议：网页手感模拟质检）→ 导出`
+
+Quick Start 只简化输入和生成过程。生成完成后，候选确认、入库、资产管理、逐帧审核、修复、网页手感模拟和导出仍由人工完成。
+
+## 核心术语
+
+- **角色**：游戏中的人物身份，如“守夜人”。
+- **造型**：角色的一套装扮。MS2 每个角色只支持一套造型。
+- **造型基准帧（母版）**：该造型的定妆参考，后续动作必须继承其身份、比例、服装和色彩。
+- **动作**：Idle、Walk、Run、Jump 等动画语义及其帧序列。
+- **候选资产**：生成完成但尚未被用户确认入库的结果。
+- **项目资产**：用户确认进入项目资产库的结果；入库后仍可能处于待审核状态。
+- **工作流运行**：一次具体生产过程，包含节点状态、任务、候选和人工操作。
+- **工作流模板**：可复用的配置，不包含旧任务和候选产物。
+
+## A. 应用基座模块（MS2 支撑）
+
+`为所有页面提供统一的应用外壳、导航、当前上下文和服务访问入口。`
+
+前端功能：
+
+- 应用外壳：统一顶部导航、侧栏、工作区和全局操作区。
+- 页面路由：项目、创作、工作流、生成、资产、审核、手感模拟和导出页面导航。
+- 当前上下文：展示并维护当前项目、角色、造型、动作和工作流运行。
+- 全局反馈：成功提示、错误提示、确认弹窗和全局加载状态。
+- 统一请求：封装请求、错误映射、凭据会话和资产 URL。
+- 运行时配置：管理 API 地址、网页预览地址和通信命名空间。
+- 契约读取：统一视角、动作、FPS、模型和生成方式定义。
+- 页面恢复：通过 URL 和服务端 ID 恢复项目、任务和审核位置。
+
+功能边界：
+
+- 应用基座不保存具体业务规则。
+- 项目、任务、审核和资产的权威状态来自服务端，浏览器缓存只用于改善交互。
+
+## B. 创作入口与工作流编排模块（MS2）
+
+`负责创建工作流运行、展示固定节点、处理节点连接和同步各业务步骤状态，不重复实现项目、生成、审核或导出的具体业务。`
+
+### B1. Quick Start
+
+前端功能：
+
+- 输入自然语言描述角色、风格、视角、方向、动作和交付要求。
+- 提供示例指令和参考图上传入口。
+- 回显识别出的角色名称、造型描述、项目约束、动作和画布参数。
+- 允许用户在提交前修正识别结果。
+- 确认后创建一条固定工作流运行，并自动执行可自动完成的生成步骤。
+- 实时展示母版、Idle 帧和 Walk 帧的到达过程。
+- 在候选生成和系统质检结束后停止，等待人工确认。
+- 人工确认后进入项目资产库，后续管理和审核不由 Quick Start 自动完成。
+
+需要后端能力：
+
+- 解析自然语言需求。
+- 创建工作流运行和生成任务。
+- 按 Job ID 返回任务状态与产物。
+
+### B2. 从项目开始
+
+前端功能：
+
+- 选择项目或创建项目。
+- 选择已有角色，或创建新角色。
+- 选择已有动作模板或新增动作要求。
+- 选择从零创建、上传参考图或复用当前项目资产。
+- 确认后创建工作流运行并进入画布。
+
+需要后端能力：
+
+- 获取项目、角色、造型和动作列表。
+- 创建工作流运行。
+
+### B3. 固定工作流画布
+
+前端功能：
+
+- 展示项目、角色、造型基准帧、动作、生成、审核、建议手感模拟和导出阶段节点。
+- 展示节点连线、先后关系和当前运行位置。
+- 支持画布拖动、缩放、适应视图和节点位置调整。
+- 允许建立系统预定义的连接，非法连接显示原因。
+- 展示节点状态：锁定、可处理、运行中、等待确认、已完成和失败。
+- 点击节点进入对应业务模块处理当前步骤。
+- 展示生成中的中间产物和任务进度，不只显示最终结果。
+- 上游连接有效且运行结果已确认后，才解锁下游节点。
+
+当前边界：
+
+- MS2 使用固定节点和允许连接，不支持任意新增、删除或组合节点。
+- 自定义节点、复杂分支、自定义端口、撤销重做和通用低代码能力属于后续。
+
+### B4. 工作流运行状态
+
+前端功能：
+
+- 展示工作流总体进度和每个节点的完成情况。
+- 区分图结构连接状态和业务运行状态。
+- 保存节点人工确认结果和当前处理位置。
+- 页面刷新后根据运行 ID 恢复状态。
+- 失败节点提供错误原因和重新处理入口。
+
+需要后端能力：
+
+- 获取工作流运行和节点状态。
+- 提交节点处理结果。
+- 恢复未完成运行。
+
+## C. 项目、角色与动作模块（MS2）
+
+`管理项目约束以及项目内的角色、造型基准帧和动作定义。`
+
+### C1. 项目
+
+前端功能：
+
+- 查看、创建、编辑和切换项目。
+- 设置项目名称、题材、美术风格和补充说明。
+- 上传、预览、替换和删除风格参考图。
+- 设置侧视、俯视或 2.5D 视角。
+- 设置单向、四向或八向，并校验与视角的兼容关系。
+- 设置角色资产画布尺寸。
+- 在工作台顶栏展示当前项目约束。
+- 修改已有项目约束时展示对现有资产的影响并要求确认。
+
+需要后端能力：
+
+- 获取项目列表和详情。
+- 创建和修改项目。
+
+### C2. 角色、造型与基准帧
+
+前端功能：
+
+- 创建或选择角色。
+- 填写角色名称、身份、定位和外观描述。
+- 选择从零创建、上传参考图或使用已有角色。
+- 默认继承当前项目的风格、视角、方向和画布约束。
+- 按项目的视角与方向组合展示和管理对应的造型基准帧。
+- 提交造型基准帧生成要求，实际生成交给生成任务模块。
+- 展示候选基准帧，支持选择、重新生成和人工确认；候选数量不写死。
+- 查看已确认基准帧和角色已有动作。
+
+当前边界：
+
+- MS2 每个角色只支持一套造型。
+- 单造型表示一套装扮；四向或八向项目仍可为同一造型保存多个方向基准帧。
+- 多造型切换、换装继承和造型版本比较属于后续。
+
+需要后端能力：
+
+- 获取、创建和修改角色。
+- 获取候选基准帧并保存人工确认结果。
+
+### C3. 动作
+
+前端功能：
+
+- 查看动作模板和动作说明。
+- 选择动作模板应用到当前造型基准帧。
+- 展示动作是否循环、默认 FPS 和目标帧数。
+- 查看动作生成、审核、修复和可导出状态。
+- 从角色详情发起补充动作。
+
+当前边界：
+
+- MS2 基础角色包默认生成 Idle 和 Walk，各 8 帧、8 FPS。
+- Run、Jump 和其他动作可作为扩展动作接入，但不作为基础包完成标准。
+- 网页手感模拟按实际已审核动作动态提供绑定，不假设每个角色都已有跳跃或攻击。
+
+需要后端能力：
+
+- 获取动作模板。
+- 创建动作并获取动作详情。
+
+## D. AI 服务接入与生成任务模块（MS2 支撑）
+
+`统一管理 Provider 连接、模型选择、基准帧生成、动作生成、任务进度和失败重试。前端不直接执行底层 AI 请求。`
+
+### D1. Provider 连接与模型设置
+
+前端功能：
+
+- 输入并提交用户自己的 Provider API Key。
+- 展示未连接、验证中、已连接和连接失败状态。
+- 读取并过滤后端返回的可用模型。
+- 选择本次生成使用的模型。
+- 展示服务健康状态和重新连接入口。
+- 区分密钥无效、模型不可用、服务异常和网络错误。
+
+安全边界：
+
+- API Key 提交后立即清空输入框。
+- API Key 不写入浏览器存储、任务、流程、日志或导出文件。
+- 凭据由后端内存和安全会话管理。
+- 平台模型积分模式上线后，普通用户不再接触 Provider API Key。
+
+### D2. 生成确认
+
+前端功能：
+
+- 基准帧生成前展示项目、角色、造型和参考图。
+- 动作生成前展示已确认基准帧、动作模板和生成要求。
+- 展示模型、生成方式和预计产物。
+- 平台积分模式上线后展示预计积分；当前 BYOK 模式不展示虚假扣费。
+- 用户确认后发起生成任务。
+
+### D3. 生成进度与产物
+
+前端功能：
+
+- 展示任务状态：排队、生成、处理中、系统质检、等待人工确认、完成和失败。
+- 基准帧任务展示需求理解、生成和系统质检步骤。
+- 动作任务展示动作生成、动作条切分或逐帧到达、归一化和系统质检步骤。
+- 按实际到达顺序展示候选基准帧和候选动作帧。
+- 展示 Job ID、模型、生成方式、来源入口、耗时和错误原因。
+- 页面刷新后通过 Job ID 恢复任务状态。
+
+### D4. 重试与修复任务
+
+前端功能：
+
+- 失败任务保留原参数并创建新的重试任务。
+- 支持完整动作条重新生成。
+- 支持单帧修复，并提交原帧、相邻帧、动作约束和人工修改意见。
+- 新候选返回后回到原审核位置继续人工审核。
+
+需要后端能力：
+
+- 创建基准帧、动作和单帧修复任务。
+- 获取任务状态和增量产物。
+- 执行模型路由、回退、图像处理、任务持久化和成本统计。
+
+## E. 资产库模块（MS2）
+
+`管理用户确认进入项目的角色基准帧和动作资产，并提供浏览、审核、补充和修复入口。`
+
+前端功能：
+
+- 按项目展示角色列表、基准帧、动作组数和总帧数。
+- 展示角色身份、造型、视角、方向和项目约束。
+- 按角色、视角、动作和审核状态浏览资产。
+- 展示动作帧数、FPS、循环类型、生成批次和当前状态。
+- 展示来源 Job ID、工作流运行、模型、生成时间和质检摘要。
+- 从动作资产进入审核台。
+- 为当前角色继续补充动作。
+- 从需要修复的资产进入修复流程。
+- 提供空状态、加载状态和错误重试。
+
+资产状态：
+
+- **候选**：属于生成任务，尚未进入项目资产库。
+- **待审核**：用户确认入库，但尚未完成逐帧审核。
+- **需要修复**：存在退回帧或动作问题。
+- **逐帧审核通过**：所有目标帧已通过人工审核，可以导出；建议先完成网页手感模拟。
+
+网页手感模拟结果作为独立验收记录，分为未验收、通过和发现问题。它不改变资产的导出资格，但发现问题时应突出提示并建议返回审核或修复。
+
+当前边界：
+
+- 候选资产不得直接出现在项目资产库。
+- 删除角色或动作、跨项目复用和复杂版本回滚属于后续。
+
+需要后端能力：
+
+- 获取项目资产概览、角色详情和动作资产。
+- 获取生成来源和状态。
+
+## F. 审查与修复模块（MS2）
+
+`负责动作预览、自动质检结果展示、逐帧人工审核和退回修复。`
+
+### F1. 审核对象与动画预览
+
+前端功能：
+
+- 切换角色、视角和动作。
+- 大尺寸展示当前帧和完整动作。
+- 播放、暂停、循环、上一帧和下一帧。
+- 默认按 8 FPS 播放，并显示动作循环属性。
+- 提供洋葱皮、透明背景、脚底线和锚点辅助检查。
+
+### F2. 系统质检结果
+
+前端统一展示 7 项检查：
+
+1. 画布尺寸一致性。
+2. 透明背景有效性。
+3. 脚底线偏差。
+4. 主体高度偏差。
+5. 相邻帧位移连续性。
+6. 轮廓面积波动。
+7. 循环首尾接缝；非循环动作显示“不适用”。
+
+系统质检只检查可计算的文件和几何问题。动作语义、解剖、衣装细节和跨帧身份一致性仍由人工判断。
+
+### F3. 逐帧人工审核
+
+前端功能：
+
+- 在时间轴中区分待审核、通过和退回帧。
+- 单帧通过、单帧退回和填写修改意见。
+- 批量通过确认无问题的帧。
+- 展示审核进度和未处理问题。
+- 保存并恢复未完成的审核会话。
+- 所有帧通过后，将动作标记为“逐帧审核通过”。
+
+### F4. 退回修复
+
+前端功能：
+
+- 选择需要修复的单帧；单段修复作为后续扩展。
+- 填写修改要求并发起修复任务。
+- 查看修复进度和新候选。
+- 采用新帧后继续原审核流程。
+
+需要后端能力：
+
+- 获取动作帧、系统质检和审核状态。
+- 保存单帧或批量审核结果。
+- 创建修复任务并返回修复后的帧。
+
+## G. 网页手感模拟质检模块（MS2 建议验收）
+
+`在浏览器中模拟角色试玩，检查按键触发、动作循环、动作衔接、方向和锚点。它是建议执行的导出验收标准，不是导出硬门禁，也不是目标游戏引擎中的最终运行验证。`
+
+### G1. 动作与按键绑定
+
+前端功能：
+
+- 选择已通过逐帧审核的动作参与模拟。
+- 为移动、待机和其他实际可用动作绑定按键。
+- 展示并修改当前按键映射。
+- 检测按键冲突并提供恢复默认映射。
+
+### G2. 浏览器内模拟
+
+前端功能：
+
+- 在独立预览页面中试玩角色。
+- 使用 WASD 和已绑定按键触发动作。
+- 展示当前按键、当前动作、方向和循环状态。
+- 检查动作循环、切换衔接、锚点漂移和操作反馈。
+- 时间轴切帧与 WASD 操作分离，避免输入冲突。
+
+### G3. 手感质检结论
+
+前端功能：
+
+- 记录手感模拟是否完成、是否通过，以及测试动作和按键映射。
+- 将问题定位到具体动作；能定位到帧时携带帧信息返回审核台。
+- 发现问题时建议回到审核或修复流程。
+- 未执行或发现问题时，在导出页展示提醒，但不自动锁定导出。
+
+需要后端能力：
+
+- 获取可模拟动作及资源。
+- 获取和保存按键绑定。
+- 保存手感模拟质检结果。
+
+当前边界：
+
+- MS2 基础包至少验证 Idle 和 Walk。
+- Jump、Attack 等动作只有在资产真实存在并通过逐帧审核后才出现在绑定列表。
+- Cocos、Unity 等真实引擎运行验证属于引擎适配阶段。
+
+## H. 导出模块（MS2）
+
+`将通过逐帧人工审核的动作导出为 GIF、SpriteSheet PNG 和 JSON metadata。网页手感模拟是建议验收标准，不是导出硬门禁。`
+
+前端功能：
+
+- 从资产详情、手感质检结果或工作流导出节点进入导出流程。
+- 仅选择“逐帧审核通过”的动作。
+- 导出前展示角色、视角、动作、帧数、FPS、循环方式和文件列表。
+- 展示网页手感模拟状态；未验收或发现问题时给出明确提醒，用户确认后仍可继续导出。
+- 生成 GIF，用于动画预览和分享。
+- 将动作帧合成为透明背景的 SpriteSheet PNG。
+- 生成与 SpriteSheet 对应的 JSON metadata。
+- 展示导出进度、成功结果和失败原因。
+- 分别下载 GIF、PNG 和 JSON。
+- 导出后返回项目、资产详情或当前工作流。
+
+JSON metadata 内容：
+
+- 角色、造型、视角和动作标识。
+- FPS 和循环标记。
+- 帧名称、帧序号、坐标和尺寸。
+- `sourceSize`、`spriteSourceSize` 和锚点。
+
+当前边界：
+
+- MS2 不提供独立序列帧压缩包、目标引擎包或一键导入插件。
+- Cocos、Unity、Godot 等引擎专用包结构和导入步骤属于后续。
+
+需要后端能力：
+
+- 获取可导出动作及其质检状态。
+- 如果导出在服务端执行，则创建导出任务并返回下载链接。
+
+## I. 流程库模块（MS2 后）
+
+`保存并复用经过验证的项目约束和固定工作流配置。现有原型已具备部分能力，但不作为 MS2 交付范围。`
+
+前端功能：
+
+- 查看流程名称、版本、项目规格、动作、节点摘要和运行次数。
+- 保存已验证流程。
+- 加载项目约束、角色来源、动作参数、节点连接、位置和视口。
+- 由用户明确启动模板运行，每次创建新的工作流运行和生成任务。
+- 自动运行仍在人工确认前停止。
+
+模板不保存 API Key、会话 Cookie、上传原图、候选图片、旧 Job 输出或正式资产副本。
+
+后续能力：
+
+- 流程编辑、删除、版本比较、跨角色重放和团队共享。
+
+## J. 用户账户模块（后续）
+
+`提供注册、登录、会话恢复、登出和账户设置。MS2 保留产品位置，不落地完整账户系统。`
+
+前端功能：
+
+- 邮箱密码和邮箱验证码登录。
+- GitHub/Google OAuth 登录。
+- 用户注册、忘记密码和重置密码。
+- 当前用户、登录状态和自动恢复。
+- 未登录访问拦截和登录后返回原页面。
+- 个人资料和修改密码。
+
+安全边界：
+
+- 登录态优先使用后端设置的 `HttpOnly Cookie`。
+- 前端不保存可被脚本读取的长期 Token。
+
+## K. 积分与计费模块（后续）
+
+`平台统一提供模型后，为用户展示积分余额、生成报价、套餐购买和消费记录。`
+
+前端功能：
+
+- 展示当前余额、可用额度和余额不足提醒。
+- 生成前展示预计积分并在余额不足时拦截任务。
+- 生成完成后展示实际积分消耗。
+- 展示套餐、当前套餐和购买入口。
+- 按时间、任务、模型和消费类型查看记录。
+
+功能边界：
+
+- 支付确认、积分扣减和余额计算由后端完成。
+- 积分按模型、生成方式、分辨率、动作数量和实际调用成本计算。
+
+## 跨模块状态规则
+
+不同对象使用独立状态，不能混成一个“成功/失败”：
+
+- **工作流节点**：锁定、可处理、运行中、等待确认、已完成、失败。
+- **生成任务**：排队、生成中、处理中、系统质检中、等待人工确认、完成、失败。
+- **候选资产**：等待确认、已放弃、已确认入库。
+- **项目动作资产**：待审核、需要修复、逐帧审核通过。
+- **网页手感模拟**：未验收、通过、发现问题；作为建议验收记录，不决定导出资格。
+- **导出任务**：准备中、生成中、可下载、失败。
+
+关键门禁：
+
+- Quick Start 和从项目开始必须复用同一工作流运行和生成任务机制。
+- 候选资产经人工确认后才能进入项目资产库。
+- 入库不等于审核通过；后续资产管理和逐帧审核仍由人工完成。
+- 全部目标帧通过人工审核后，即可导出 GIF、SpriteSheet PNG 和 JSON metadata。
+- 导出前建议完成网页手感模拟；未验收或发现问题时显示提醒，但不阻止用户导出。
+- 系统质检和人工审核结果必须分开展示，自动分数不能代替人工通过。
+- API Key 不得进入浏览器存储、任务、模板、日志或导出文件。
+
+## MS2 范围汇总
+
+MS2 纳入：
+
+- 应用基座和项目上下文。
+- Quick Start、从项目开始和固定工作流画布。
+- 项目、角色、单造型及其方向基准帧和基础动作。
+- BYOK Provider 连接和统一生成任务。
+- 候选人工确认、资产库、7 项系统质检、逐帧人工审核和单帧修复。
+- 网页手感模拟质检及建议验收记录。
+- GIF、SpriteSheet PNG 和 JSON metadata 导出。
+
+MS2 不纳入：
+
+- 流程库正式交付、跨角色模板重放和灵活工作流。
+- 完整用户账户和积分计费。
+- 多造型、跨项目复用和复杂版本管理。
+- 独立序列帧包、多引擎专用包和一键导入插件。
+- 生产级分布式任务队列和多人协作。