Sync from main: 3002239 docs: refresh dual-mode studio positioning

.dockerignore

@@ -0,0 +1,105 @@
+# Dependencies
+node_modules/
+frontend/node_modules/
+
+# Build output (will be created during build)
+dist/
+frontend/dist/
+frontend/build/
+
+# Environment files (use Docker env vars instead)
+.env
+.env.local
+.env.*.local
+.env.development
+.env.production
+
+# Generated videos (mounted as volume)
+public/videos/*.mp4
+public/videos/*.mov
+public/videos/*.avi
+
+# Git
+.git/
+.gitignore
+.gitattributes
+
+# IDE and editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.classpath
+.settings/
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# OS files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+Desktop.ini
+
+# Temp files
+tmp/
+temp/
+*.tmp
+*.temp
+.cache/
+
+# Test files
+coverage/
+.nyc_output/
+test-results/
+
+# Documentation and project files
+README.md
+CHANGELOG.md
+LICENSE
+*.md
+!src/prompts/templates/**/*.md
+docs/
+
+# Docker files
+docker-compose*.yml
+Dockerfile*
+.dockerignore
+
+# CI/CD
+.github/
+.gitlab-ci.yml
+.travis.yml
+
+# Python cache (from Manim)
+__pycache__/
+*.py[cod]
+*$py.class
+.Python
+
+# Redis dump
+dump.rdb
+*.rdb
+
+# Static assets (examples)
+static/gifs/
+
+# Other
+.editorconfig
+.prettierrc
+.eslintrc*
+tsconfig*.json
+vite.config.ts
+tailwind.config.js
+postcss.config.js

.env.example

@@ -0,0 +1,59 @@
+# ManimCat local development environment template
+
+# Runtime
+NODE_ENV=development
+PORT=3000
+HOST=0.0.0.0
+LOG_LEVEL=info
+# PROD_SUMMARY_LOG_ONLY=false
+
+# Redis
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_DB=0
+# REDIS_PASSWORD=
+
+# Recommended server-side upstream routing
+# One Bearer key mapped to one upstream profile.
+MANIMCAT_ROUTE_KEYS=demo-key
+MANIMCAT_ROUTE_API_URLS=https://api.example.com/v1
+MANIMCAT_ROUTE_API_KEYS=sk-example
+MANIMCAT_ROUTE_MODELS=gpt-4o-mini
+
+# Optional request-level AI tuning
+# AI_TEMPERATURE=0.7
+# AI_MAX_TOKENS=12000
+# AI_THINKING_TOKENS=20000
+# DESIGNER_TEMPERATURE=0.8
+# DESIGNER_MAX_TOKENS=12000
+# DESIGNER_THINKING_TOKENS=20000
+
+# Optional server behavior
+# REQUEST_TIMEOUT=600000
+# JOB_TIMEOUT=600000
+# MANIM_TIMEOUT=600000
+# CORS_ORIGIN=*
+
+# Optional media storage paths
+# VIDEO_OUTPUT_DIR=public/videos
+# TEMP_DIR=temp
+
+# Optional cleanup and retention
+# MEDIA_RETENTION_HOURS=72
+# MEDIA_CLEANUP_INTERVAL_MINUTES=60
+# JOB_RESULT_RETENTION_HOURS=24
+# USAGE_RETENTION_DAYS=90
+# METRICS_USAGE_RATE_LIMIT_MAX=30
+# METRICS_USAGE_RATE_LIMIT_WINDOW_MS=60000
+
+# Optional history persistence
+# ENABLE_HISTORY_DB=true
+# SUPABASE_URL=https://your-project.supabase.co
+# SUPABASE_KEY=your-supabase-key
+
+# Optional Studio persistence
+# ENABLE_STUDIO_DB=true
+
+# Optional render-failure export
+# ENABLE_RENDER_FAILURE_LOG=true
+# ADMIN_EXPORT_TOKEN=replace_with_long_random_token

.env.production

@@ -0,0 +1,46 @@
+# ManimCat production environment template
+
+# Runtime
+NODE_ENV=production
+PORT=3000
+LOG_LEVEL=info
+PROD_SUMMARY_LOG_ONLY=true
+
+# Redis
+REDIS_HOST=redis
+REDIS_PORT=6379
+REDIS_DB=0
+# REDIS_PASSWORD=
+
+# Recommended server-side upstream routing
+# One Bearer key mapped to one upstream profile.
+MANIMCAT_ROUTE_KEYS=demo-key
+MANIMCAT_ROUTE_API_URLS=https://api.example.com/v1
+MANIMCAT_ROUTE_API_KEYS=sk-example
+MANIMCAT_ROUTE_MODELS=gpt-4o-mini
+
+# Optional AI tuning
+# AI_TEMPERATURE=0.7
+# AI_MAX_TOKENS=12000
+# AI_THINKING_TOKENS=20000
+# DESIGNER_TEMPERATURE=0.8
+# DESIGNER_MAX_TOKENS=12000
+# DESIGNER_THINKING_TOKENS=20000
+
+# Optional media / retention
+# MEDIA_RETENTION_HOURS=72
+# MEDIA_CLEANUP_INTERVAL_MINUTES=60
+# JOB_RESULT_RETENTION_HOURS=24
+# USAGE_RETENTION_DAYS=90
+
+# Optional history persistence
+# ENABLE_HISTORY_DB=true
+# SUPABASE_URL=https://your-project.supabase.co
+# SUPABASE_KEY=your-supabase-key
+
+# Optional Studio persistence
+# ENABLE_STUDIO_DB=true
+
+# Optional render-failure export
+# ENABLE_RENDER_FAILURE_LOG=true
+# ADMIN_EXPORT_TOKEN=replace_with_long_random_token

.github/pull_request_template.md

@@ -0,0 +1,9 @@
+## Checklist
+
+- [ ] I have read and agree to `CLA.md`.
+- [ ] I confirm this PR content can be contributed under the project terms.
+
+## Notes
+
+By opening this PR, I understand this project uses a CLA process to keep commercial-use authorization manageable under a single maintainer workflow, while keeping the project open source and community-oriented.
+

.github/workflows/docker-publish.yml

@@ -0,0 +1,49 @@
+name: Publish Docker Image
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+env:
+  IMAGE_NAME: wingflow/manimcat
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'
+
+jobs:
+  docker:
+    if: github.event_name == 'workflow_dispatch' || contains(github.event.head_commit.message, 'docker')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3.12.0
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3.4.0
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5.10.0
+        with:
+          images: ${{ env.IMAGE_NAME }}
+          tags: |
+            type=raw,value=latest
+            type=sha,format=short
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6.18.0
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

.gitignore

@@ -0,0 +1,83 @@
+# Dependencies
+node_modules/
+.cursor/
+
+# Python
+venv/
+__pycache__/
+*.pyc
+
+# Build output
+dist/
+.motia/
+
+# Environment
+.env
+.env.local
+
+# Generated files
+public/videos/*
+public/videos/.gitkeep
+media/
+static/videos/
+static/gifs/
+
+# Logs
+*.log
+dump.rdb
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+
+# Temp files
+tmp/
+*.tmp
+.studio-workspace/
+.studio/
+.plot_env_smoke*.png
+circle.png
+triangle.png
+
+# AI/Dev tools
+.claude/
+.ruff_cache/
+
+# MD files (except README)
+*.md
+!README.md
+!README.zh-CN.md
+!frontend/README.md
+!static/gifs/README.md
+!LICENSE_POLICY.en.md
+!LICENSE_POLICY.md
+!THIRD_PARTY_NOTICES.md
+!THIRD_PARTY_NOTICES.zh-CN.md
+!DEPLOYMENT.md
+!DEPLOYMENT.zh-CN.md
+!CLA.md
+!CONTRIBUTING.md
+!.github/pull_request_template.md
+!src/prompts/templates/**/*.md
+!src/studio-agent/prompts/templates/**/*.md
+
+# Flow type files
+*.flow
+
+# Batch scripts
+*.bat
+
+public/images/*
+public/images/.gitkeep
+public/readme-images/*.png
+!public/readme-images/.gitkeep
+
+# Studio / test build artifacts
+dist-tests/
+public/assets/
+public/index.html
+

CLA.md

@@ -0,0 +1,98 @@
+# Contributor License Agreement (CLA)
+
+版本：v1.0  
+生效日期：2026-03-20
+
+本《贡献者许可协议》（"本协议"）由贡献者与项目维护方就向 `ManimCat` 项目提交代码、文档或其他材料之事项达成。
+
+## 1. 定义
+
+- "项目"：指 `ManimCat` 代码仓库及其衍生发布内容。
+- "贡献"：指贡献者提交、上传、推送或以其他方式提供给项目的任何作品，包括但不限于源代码、脚本、文档、设计、测试与配置。
+- "贡献者"：指签署本协议的个人，或其代表签署本协议的法人/组织。
+- "维护方"：指项目当前及未来的维护者、管理者、发布者及其授权主体。
+
+## 2. 版权许可
+
+贡献者同意：
+
+1. 其保留对自身贡献的著作权；
+2. 向维护方及项目接收者授予一项全球范围、免费、非排他、不可撤销、可再许可的许可，用于复制、修改、改编、发布、分发、公开展示、公开传播及以其他方式利用该贡献，并可将其与项目其他部分合并、再许可或商业化使用。
+
+## 3. 专利许可
+
+贡献者就其贡献中所包含并由其可授权的专利权，授予维护方及项目接收者一项全球范围、免费、非排他、不可撤销（但受本条终止约定约束）的专利许可，以制造、委托制造、使用、许诺销售、销售、进口及以其他方式处置该贡献及其与项目的组合。
+
+如贡献者就项目或贡献提起专利侵权诉讼（含反诉），则其在本条项下授予的专利许可自起诉之日起自动终止。
+
+## 4. 声明与保证
+
+贡献者声明并保证：
+
+1. 其有权签署本协议并作出相应授权；
+2. 其贡献为其原创，或其已取得提交与授权所需的全部权利；
+3. 其知悉贡献可能被公开发布并长期保留在版本历史中；
+4. 其贡献在其知情范围内不故意包含恶意代码、后门或违法内容。
+
+## 5. 第三方内容
+
+若贡献包含第三方代码或材料，贡献者应确保：
+
+1. 已遵守第三方许可条件；
+2. 已在提交说明或文件头中明确标注来源与许可；
+3. 该第三方许可与项目既有许可策略兼容。
+
+## 6. 无担保与责任限制
+
+除法律另有强制规定外，贡献按"现状"提供，不附带任何明示或默示担保。任何一方均不对间接、附带或后果性损失承担责任。
+
+## 7. 许可协议关系
+
+本协议仅处理贡献授权与权利声明，不替代项目对外发布所采用的开源或商业许可条款。项目接收者对项目的使用仍受相应发布许可约束。
+
+## 8. 适用范围与持续有效
+
+1. 本协议适用于贡献者在签署后提交的全部贡献；
+2. 若维护方接受，亦可适用于签署前已提交且由贡献者拥有权利的历史贡献；
+3. 本协议授予的版权许可为不可撤销（法律另有规定除外）。
+
+## 9. 法律适用
+
+本协议的订立、解释与争议解决，适用维护方主要运营地法律。若双方另有书面约定，以该约定为准。
+
+## 10. 签署方式
+
+以下任一方式视为有效签署：
+
+1. 在 Pull Request/Commit 中声明 "I have read and agree to CLA.md"；
+2. 在项目要求的 CLA 系统中点击同意；
+3. 提交书面或电子签署文本。
+
+## 11. 维护方声明（解释性说明）
+
+为避免误解，维护方公开声明如下：
+
+1. 引入 CLA 的目的，是集中管理项目商业使用授权，避免未来商业授权流程中必须逐一联系所有贡献者；
+2. 引入 CLA 并不意味着维护方计划成立 "ManimCat 公司" 或转型为企业管理者，维护方将继续以开发者身份维护本项目；
+3. 维护方承诺项目将长期保持开源，反对垄断；
+4. 因商业授权获得的资金，将优先回馈项目本身，包括但不限于基础设施、维护成本、文档与测试改进、社区活动组织，以及对作出重大贡献的开发者支持；
+5. 对于乐于开源、愿意回馈社区的小型商业公司，授权费用将以象征性标准为主。
+
+---
+
+## 个人签署信息（可选模板）
+
+- 姓名：
+- 邮箱：
+- GitHub/代码平台账号：
+- 签署日期：
+- 签名：
+
+## 组织签署信息（可选模板）
+
+- 组织名称：
+- 授权代表姓名：
+- 职务：
+- 邮箱：
+- 签署日期：
+- 组织盖章/签名：

CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# Contributing to ManimCat
+
+Thanks for considering a contribution.
+
+## CLA Requirement
+
+Before a Pull Request can be merged, contributors must agree to `CLA.md`.
+
+Accepted forms:
+
+1. Sign through the CLA bot flow in the PR.
+2. Include a statement in PR/commit: `I have read and agree to CLA.md`.
+
+## Why this CLA exists
+
+The CLA is used so the maintainer can centrally handle commercial-use authorization without needing to re-contact every contributor later.
+
+This is not a plan to turn ManimCat into a company-run project. The project remains open source, anti-monopoly, and community-oriented.
+
+Any commercial authorization income is intended to be reinvested into project development, major contributors, and community activities. For small companies that are open-source-friendly, authorization terms and fees are expected to be symbolic.
+

DEPLOYMENT.md

@@ -0,0 +1,326 @@
+# ManimCat Deployment Guide
+
+English | [简体中文](https://github.com/Wing900/ManimCat/blob/main/DEPLOYMENT.zh-CN.md)
+
+This guide only documents deployment paths that match the current repository state.
+
+## How the project actually runs
+
+- Backend: Node.js + Express
+- Frontend: built by Vite, then served by the backend
+- Queue and job state: Redis
+- Rendering runtime: Python + ManimCE + LaTeX + `ffmpeg`
+- AI upstreams: preferably configured with `MANIMCAT_ROUTE_*`, or passed per request through `customApiConfig`
+
+## Which path to choose
+
+- Run it on your own machine with the least abstraction: local native deployment
+- Keep the runtime closer to production: Docker Compose
+- Deploy to Hugging Face: Docker Space
+
+## 1. Local Native Deployment
+
+### Prerequisites
+
+- Node.js 18+
+- Redis 7+ reachable at `localhost:6379` by default
+- Python 3.11+
+- Manim Community Edition 0.19.x
+- `mypy`
+- LaTeX
+- `ffmpeg`
+
+### 1. Clone and configure
+
+```bash
+git clone https://github.com/Wing900/ManimCat.git
+cd ManimCat
+cp .env.example .env
+```
+
+Configure at least one routed upstream:
+
+```env
+MANIMCAT_ROUTE_KEYS=demo-key
+MANIMCAT_ROUTE_API_URLS=https://api.example.com/v1
+MANIMCAT_ROUTE_API_KEYS=sk-example
+MANIMCAT_ROUTE_MODELS=gpt-4o-mini
+```
+
+Common optional variables:
+
+```env
+PORT=3000
+LOG_LEVEL=info
+PROD_SUMMARY_LOG_ONLY=false
+```
+
+### 2. Install dependencies
+
+```bash
+npm install
+npm --prefix frontend install
+python -m pip install mypy
+```
+
+### 3. Start
+
+Development:
+
+```bash
+npm run dev
+```
+
+Production-style run:
+
+```bash
+npm run build
+npm start
+```
+
+Notes:
+
+- `npm run build` currently builds the frontend only.
+- `npm start` runs `tsx src/server.ts`, so the backend does not depend on precompiled JS output.
+
+### 4. Verify
+
+- App: `http://localhost:3000`
+- Health: `http://localhost:3000/health`
+
+---
+
+## 2. Docker Compose Deployment
+
+This is the most practical default. The repo already includes Redis, the Manim runtime, and the Node runtime in the deployment path.
+
+If you have already published the image, you can also deploy from `wingflow/manimcat` instead of rebuilding locally each time.
+
+### 1. Prepare environment variables
+
+```bash
+cp .env.production .env
+```
+
+Set at least one upstream profile:
+
+```env
+MANIMCAT_ROUTE_KEYS=demo-key
+MANIMCAT_ROUTE_API_URLS=https://api.example.com/v1
+MANIMCAT_ROUTE_API_KEYS=sk-example
+MANIMCAT_ROUTE_MODELS=gpt-4o-mini
+```
+
+If needed, change ports:
+
+```env
+PORT=3000
+REDIS_PORT=6379
+```
+
+### 2. Build and run
+
+```bash
+docker compose build
+docker compose up -d
+```
+
+If you want to use the published image directly, replace the `build` section in `docker-compose.yml` with:
+
+```yaml
+image: wingflow/manimcat
+```
+
+### 3. Verify
+
+```bash
+docker compose ps
+```
+
+- App: `http://localhost:3000`
+- Health: `http://localhost:3000/health`
+
+Notes:
+
+- Compose exposes port `3000` to the host.
+- Inside Compose, Redis is reached through service name `redis`.
+- Studio session workspaces are persisted in the `studio-workspace-data` volume at `/app/.studio-workspace`.
+- Generated and uploaded images are persisted in the `image-storage` volume at `/app/public/images`.
+- Generated videos are persisted in the `video-storage` volume at `/app/public/videos`.
+- Manim media cache and intermediate artifacts are persisted in the `manim-media` volume at `/app/media`.
+- Temporary render files are persisted in the `manim-tmp` volume at `/app/tmp`.
+
+Inspect volumes if needed:
+
+```bash
+docker volume ls
+docker volume inspect manimcat_studio-workspace-data
+```
+
+---
+
+## 3. Hugging Face Spaces Deployment
+
+### Requirements
+
+- Use a Docker Space.
+- The app port is `7860`.
+- Environment variables must be defined in Space Settings, not only in a checked-in `.env` file.
+
+### 1. Use the existing root `Dockerfile`
+
+The repository `Dockerfile` is already the Hugging Face compatible one:
+
+- based on `manimcommunity/manim:stable`
+- installs Node.js, Redis, CJK fonts, and `ffmpeg`
+- starts with `node start-with-redis-hf.cjs`
+- defaults to `PORT=7860`
+
+Do not follow older instructions that mention `Dockerfile.huggingface`. That file is not part of the current repo.
+
+If you have already published a Docker image, other environments can reference `wingflow/manimcat`; however, Hugging Face Spaces still builds from the repository `Dockerfile` rather than running a Docker Hub image directly.
+
+### 2. Configure Space Settings
+
+Minimum variables:
+
+```env
+PORT=7860
+NODE_ENV=production
+MANIMCAT_ROUTE_KEYS=demo-key
+MANIMCAT_ROUTE_API_URLS=https://api.example.com/v1
+MANIMCAT_ROUTE_API_KEYS=sk-example
+MANIMCAT_ROUTE_MODELS=gpt-4o-mini
+```
+
+Recommended:
+
+```env
+LOG_LEVEL=info
+PROD_SUMMARY_LOG_ONLY=true
+```
+
+### 3. Push
+
+```bash
+git add .
+git commit -m "Deploy ManimCat"
+git push
+```
+
+After deployment:
+
+- App: `https://YOUR_SPACE.hf.space/`
+- Health: `https://YOUR_SPACE.hf.space/health`
+
+---
+
+## Upstream Routing
+
+`MANIMCAT_ROUTE_*` is the recommended server-side routing mechanism. It acts as both:
+
+- the Bearer-key whitelist
+- the mapping from key to `apiUrl/apiKey/model`
+
+Example:
+
+```env
+MANIMCAT_ROUTE_KEYS=user_a,user_b
+MANIMCAT_ROUTE_API_URLS=https://api-a.example.com/v1,https://api-b.example.com/v1
+MANIMCAT_ROUTE_API_KEYS=sk-a,sk-b
+MANIMCAT_ROUTE_MODELS=gpt-4o-mini,gemini-2.5-flash
+```
+
+Rules:
+
+1. All four variables support comma-separated or newline-separated values.
+2. `MANIMCAT_ROUTE_KEYS` is the primary index.
+3. Entries missing `apiUrl` or `apiKey` are skipped.
+4. If a variable only provides one value, that value is reused for all entries.
+5. If `model` is empty, the key can still authenticate but has no usable model.
+
+Priority:
+
+1. request-body `customApiConfig`
+2. server-side `MANIMCAT_ROUTE_*`
+
+Use server-side routing when different users should always hit different upstreams. Use the frontend provider settings when one browser user wants to manage multiple providers locally.
+
+---
+
+## Optional: Supabase Persistence
+
+There are two optional persistence layers:
+
+- generation history: `ENABLE_HISTORY_DB=true`
+- Studio Agent session/work persistence: `ENABLE_STUDIO_DB=true`
+
+Shared connection variables:
+
+```env
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_KEY=your-supabase-key
+```
+
+### Generation history
+
+Apply:
+
+- `src/database/migrations/001_create_history.sql`
+
+If you also want render-failure export, apply:
+
+- `src/database/migrations/002_create_render_failure_events.sql`
+
+Then configure:
+
+```env
+ENABLE_HISTORY_DB=true
+ENABLE_RENDER_FAILURE_LOG=true
+ADMIN_EXPORT_TOKEN=replace_with_long_random_token
+```
+
+Export endpoint:
+
+- `GET /api/admin/render-failures/export`
+- header: `x-admin-token`
+
+### Studio Agent persistence
+
+Apply:
+
+- `src/database/migrations/003_create_studio_agent.sql`
+
+Then enable:
+
+```env
+ENABLE_STUDIO_DB=true
+```
+
+---
+
+## Troubleshooting
+
+### The UI loads, but jobs fail immediately
+
+Check:
+
+- `MANIMCAT_ROUTE_*` is fully configured
+- the request includes a valid Bearer key
+- the matched route entry does not have an empty `model`
+
+### `/health` shows unhealthy Redis or queue
+
+Check:
+
+- Redis is actually running
+- `REDIS_HOST` and `REDIS_PORT` match your environment
+- in Docker Compose, the backend is pointing to service `redis`
+
+### The container starts locally, but Hugging Face build fails
+
+Check:
+
+- the Space SDK is Docker
+- env vars were added in Space Settings
+- you did not follow stale instructions mentioning `Dockerfile.huggingface`

DEPLOYMENT.zh-CN.md

@@ -0,0 +1,326 @@
+# ManimCat 部署文档
+
+简体中文 | [English](https://github.com/Wing900/ManimCat/blob/main/DEPLOYMENT.md)
+
+这份文档只保留当前项目实际可用的部署路径，并尽量压缩为最短步骤。
+
+## 先确认项目怎么运行
+
+- 后端是 Node.js + Express。
+- 前端由 Vite 构建，产物由后端静态托管。
+- 任务队列和状态依赖 Redis。
+- 实际渲染依赖 Python、ManimCE、LaTeX、`ffmpeg`。
+- 上游 AI 不再依赖 `OPENAI_API_KEY` 这类单一全局变量，推荐使用 `MANIMCAT_ROUTE_*`，或由前端按请求传 `customApiConfig`。
+
+## 选择哪种部署方式
+
+- 只想本机跑起来：用“本地原生部署”。
+- 想减少环境差异：用“Docker Compose”。
+- 想部署到 Hugging Face Space：用“Hugging Face Spaces”。
+
+## 一、本地原生部署
+
+### 前置条件
+
+- Node.js 18+
+- Redis 7+，默认可通过 `localhost:6379` 访问
+- Python 3.11+
+- Manim Community Edition 0.19.x
+- `mypy`
+- LaTeX
+- `ffmpeg`
+
+### 1. 拉代码并准备环境变量
+
+```bash
+git clone https://github.com/Wing900/ManimCat.git
+cd ManimCat
+cp .env.example .env
+```
+
+至少配置一组服务端上游路由：
+
+```env
+MANIMCAT_ROUTE_KEYS=demo-key
+MANIMCAT_ROUTE_API_URLS=https://api.example.com/v1
+MANIMCAT_ROUTE_API_KEYS=sk-example
+MANIMCAT_ROUTE_MODELS=gpt-4o-mini
+```
+
+常用可选项：
+
+```env
+PORT=3000
+LOG_LEVEL=info
+PROD_SUMMARY_LOG_ONLY=false
+```
+
+### 2. 安装依赖
+
+```bash
+npm install
+npm --prefix frontend install
+python -m pip install mypy
+```
+
+### 3. 启动
+
+开发模式：
+
+```bash
+npm run dev
+```
+
+生产式启动：
+
+```bash
+npm run build
+npm start
+```
+
+说明：
+
+- `npm run build` 当前只构建前端。
+- `npm start` 直接用 `tsx src/server.ts` 启动后端，不依赖预编译 JS。
+
+### 4. 验证
+
+- 页面：`http://localhost:3000`
+- 健康检查：`http://localhost:3000/health`
+
+---
+
+## 二、Docker Compose 部署
+
+这是最推荐的部署方式，仓库已经内置 Redis、Manim 运行时和 Node 运行时。
+
+如果你已经将镜像推到了 Docker Hub，也可以直接使用 `wingflow/manimcat`，不必每次都本地 `build`。
+
+### 1. 准备环境变量
+
+```bash
+cp .env.production .env
+```
+
+至少填写一组上游：
+
+```env
+MANIMCAT_ROUTE_KEYS=demo-key
+MANIMCAT_ROUTE_API_URLS=https://api.example.com/v1
+MANIMCAT_ROUTE_API_KEYS=sk-example
+MANIMCAT_ROUTE_MODELS=gpt-4o-mini
+```
+
+如需改端口：
+
+```env
+PORT=3000
+REDIS_PORT=6379
+```
+
+### 2. 构建并启动
+
+```bash
+docker compose build
+docker compose up -d
+```
+
+如果改为直接使用已发布镜像，请把 `docker-compose.yml` 里的 `build` 段替换为：
+
+```yaml
+image: wingflow/manimcat
+```
+
+### 3. 验证
+
+```bash
+docker compose ps
+```
+
+- 页面：`http://localhost:3000`
+- 健康检查：`http://localhost:3000/health`
+
+说明：
+
+- Compose 对外暴露 `3000`。
+- 容器内 Redis 服务名固定为 `redis`。
+- Studio 会话工作目录会持久化到 `studio-workspace-data` volume，挂载到 `/app/.studio-workspace`。
+- 生成图片与上传的参考图会持久化到 `image-storage` volume，挂载到 `/app/public/images`。
+- 生成的视频会持久化到 `video-storage` volume，挂载到 `/app/public/videos`。
+- Manim 的媒体缓存与中间渲染文件会持久化到 `manim-media` volume，挂载到 `/app/media`。
+- 临时渲染目录会持久化到 `manim-tmp` volume，挂载到 `/app/tmp`。
+
+如需检查 volume：
+
+```bash
+docker volume ls
+docker volume inspect manimcat_studio-workspace-data
+```
+
+---
+
+## 三、Hugging Face Spaces 部署
+
+### 前提
+
+- Space 类型必须选 Docker。
+- 运行端口使用 `7860`。
+- 环境变量必须配置在 Space Settings，不是只写进仓库 `.env`。
+
+### 1. 直接使用仓库根目录的 `Dockerfile`
+
+当前仓库里的 `Dockerfile` 已经是 Hugging Face Space 可用版本：
+
+- 基于 `manimcommunity/manim:stable`
+- 容器内安装 Node.js、Redis、中文字体、`ffmpeg`
+- 启动命令是 `node start-with-redis-hf.cjs`
+- 默认监听 `PORT=7860`
+
+不需要再额外复制一个 `Dockerfile.huggingface`，仓库里也没有这个文件。
+
+如果你已经发布了 Docker 镜像，也可以让其他部署环境直接参考 `wingflow/manimcat` 的内容；但 Hugging Face Space 仍然是基于仓库内 `Dockerfile` 构建，不是直接拉 Docker Hub 镜像运行。
+
+### 2. 在 Space Settings 配置变量
+
+至少配置：
+
+```env
+PORT=7860
+NODE_ENV=production
+MANIMCAT_ROUTE_KEYS=demo-key
+MANIMCAT_ROUTE_API_URLS=https://api.example.com/v1
+MANIMCAT_ROUTE_API_KEYS=sk-example
+MANIMCAT_ROUTE_MODELS=gpt-4o-mini
+```
+
+建议再补上：
+
+```env
+LOG_LEVEL=info
+PROD_SUMMARY_LOG_ONLY=true
+```
+
+### 3. 推送代码
+
+```bash
+git add .
+git commit -m "Deploy ManimCat"
+git push
+```
+
+部署完成后访问：
+
+- 页面：`https://YOUR_SPACE.hf.space/`
+- 健康检查：`https://YOUR_SPACE.hf.space/health`
+
+---
+
+## 上游路由配置
+
+推荐使用 `MANIMCAT_ROUTE_*` 做服务端路由。它同时承担两件事：
+
+- Bearer key 白名单
+- key 到上游 `apiUrl/apiKey/model` 的映射
+
+示例：
+
+```env
+MANIMCAT_ROUTE_KEYS=user_a,user_b
+MANIMCAT_ROUTE_API_URLS=https://api-a.example.com/v1,https://api-b.example.com/v1
+MANIMCAT_ROUTE_API_KEYS=sk-a,sk-b
+MANIMCAT_ROUTE_MODELS=gpt-4o-mini,gemini-2.5-flash
+```
+
+规则：
+
+1. 四组变量都支持逗号或换行分隔。
+2. `MANIMCAT_ROUTE_KEYS` 是主索引。
+3. `apiUrl` 或 `apiKey` 缺失的条目会被跳过。
+4. 如果某一组变量只写了一个值，这个值会复用到全部条目。
+5. `model` 留空时，该 key 仍可认证，但当前没有可用模型。
+
+请求优先级：
+
+1. 请求体里的 `customApiConfig`
+2. 服务端 `MANIMCAT_ROUTE_*`
+
+如果要给不同用户固定分配不同上游，用服务端路由；如果只是单个浏览器本地切换多个 provider，用前端设置页即可。
+
+---
+
+## 可选：Supabase 持久化
+
+项目有两类可选持久化：
+
+- 生成历史：`ENABLE_HISTORY_DB=true`
+- Studio Agent 会话与工作流：`ENABLE_STUDIO_DB=true`
+
+公共连接配置：
+
+```env
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_KEY=your-supabase-key
+```
+
+### 生成历史
+
+先执行迁移：
+
+- `src/database/migrations/001_create_history.sql`
+
+如需渲染失败事件导出，再执行：
+
+- `src/database/migrations/002_create_render_failure_events.sql`
+
+对应变量：
+
+```env
+ENABLE_HISTORY_DB=true
+ENABLE_RENDER_FAILURE_LOG=true
+ADMIN_EXPORT_TOKEN=replace_with_long_random_token
+```
+
+导出接口：
+
+- `GET /api/admin/render-failures/export`
+- 请求头：`x-admin-token`
+
+### Studio Agent 持久化
+
+先执行迁移：
+
+- `src/database/migrations/003_create_studio_agent.sql`
+
+再开启：
+
+```env
+ENABLE_STUDIO_DB=true
+```
+
+---
+
+## 排查清单
+
+### 页面能开，但提交任务失败
+
+优先检查：
+
+- `MANIMCAT_ROUTE_*` 是否完整配置
+- 请求头里是否带了合法 Bearer key
+- 当前 key 对应的 `model` 是否为空
+
+### `/health` 里 `redis` 或 `queue` 不健康
+
+优先检查：
+
+- Redis 是否真的启动
+- `REDIS_HOST` / `REDIS_PORT` 是否匹配
+- Docker 部署时后端是否连到了容器内 `redis`
+
+### 容器能起，但 Space 一直构建失败
+
+优先检查：
+
+- Space SDK 是否选了 Docker
+- 是否把环境变量写到了 Space Settings
+- 是否错误照搬了旧文档里的 `Dockerfile.huggingface`

Dockerfile

@@ -0,0 +1,83 @@
+# =========================================
+# 阶段 1: 准备 Node 环境
+# =========================================
+FROM node:22-bookworm-slim AS node_base
+
+# =========================================
+# 阶段 2: 构建最终镜像 (基于 Manim)
+# =========================================
+FROM manimcommunity/manim:stable
+USER root
+
+# 1. 复制 Node.js (从 node_base 偷过来)
+COPY --from=node_base /usr/local/bin /usr/local/bin
+COPY --from=node_base /usr/local/lib/node_modules /usr/local/lib/node_modules
+
+# 2. 【关键】安装 Redis 和中文字体，并刷新字体缓存
+# 使用阿里云源加速
+RUN sed -i 's/deb.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources && \
+    apt-get update && \
+    apt-get install -y redis-server fontconfig \
+    fonts-noto-cjk fonts-noto-cjk-extra \
+    fonts-wqy-zenhei fonts-wqy-microhei fonts-lxgw-wenkai \
+    ffmpeg curl ca-certificates && \
+    fc-cache -f -v
+
+# 2.1 安装 Python 运行时与静态检查依赖
+#     显式声明 matplotlib，避免依赖基础镜像的隐式预装状态。
+RUN python -m pip install --no-cache-dir \
+    matplotlib \
+    mypy==1.19.1
+
+WORKDIR /app
+
+# 3. 复制 package.json
+COPY package.json package-lock.json* ./
+COPY frontend/package.json frontend/package-lock.json* ./frontend/
+
+# 4. 设置 npm 淘宝源
+RUN npm config set registry https://registry.npmmirror.com
+
+# 5. 安装依赖
+RUN npm install && npm --prefix frontend install
+
+# 6. 复制源码并构建 React
+COPY . .
+
+# 7. 下载 BGM 音频文件（HF Space 同步时可能排除二进制文件）
+#    之前写法使用了 `... && ... && ... || true`，会把前面下载失败静默吞掉。
+RUN set -eux; \
+    mkdir -p src/audio/tracks; \
+    for file in \
+      clavier-music-soft-piano-music-312509.mp3 \
+      the_mountain-soft-piano-background-444129.mp3 \
+      viacheslavstarostin-relaxing-soft-piano-music-431679.mp3; do \
+      rm -f "src/audio/tracks/$file"; \
+      for url in \
+        "https://raw.githubusercontent.com/Wing900/ManimCat/main/src/audio/tracks/$file" \
+        "https://github.com/Wing900/ManimCat/raw/main/src/audio/tracks/$file"; do \
+        echo "Downloading $file from $url"; \
+        if curl -fL --retry 8 --retry-delay 3 --connect-timeout 10 --max-time 120 -o "src/audio/tracks/$file" "$url"; then \
+          break; \
+        fi; \
+      done; \
+      if [ ! -s "src/audio/tracks/$file" ]; then \
+        echo "WARNING: failed to download $file"; \
+        rm -f "src/audio/tracks/$file"; \
+      fi; \
+    done; \
+    echo "Downloaded tracks:"; \
+    ls -lh src/audio/tracks || true; \
+    track_count="$(find src/audio/tracks -maxdepth 1 -type f -name '*.mp3' | wc -l)"; \
+    echo "BGM track count: $track_count"; \
+    if [ "$track_count" -eq 0 ]; then \
+      echo "ERROR: no BGM tracks available after download"; \
+      exit 1; \
+    fi
+
+RUN npm run build
+
+ENV PORT=7860
+EXPOSE 7860
+
+CMD ["node", "start-with-redis-hf.cjs"]

LICENSE

@@ -0,0 +1,7 @@
+ManimCat uses a mixed-license model.
+
+Please read `LICENSE_POLICY.md` for the binding license scope.
+
+- MIT full text: `LICENSES/MIT.txt`
+- ManimCat Non-Commercial License full text: `LICENSES/ManimCat-NC.txt`
+

LICENSES/MIT.txt

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2024 Rohit Ghumare
+Copyright (c) 2026 ManimCat Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

LICENSES/ManimCat-NC.txt

@@ -0,0 +1,27 @@
+ManimCat Non-Commercial License v1.0
+
+Copyright (c) 2026 ManimCat Author and Contributors
+
+1) Grant
+Permission is granted to use, copy, modify, and redistribute the licensed
+materials for personal, educational, research, and other non-commercial
+purposes.
+
+2) Commercial Restriction
+Without prior written permission from the copyright holder, you may not use
+the licensed materials for commercial purposes, including but not limited to:
+- selling products or services based on the licensed materials;
+- offering paid hosted/API/SaaS services based on the licensed materials;
+- embedding the licensed materials into paid subscription software or services;
+- redistributing for direct commercial gain.
+
+3) Attribution
+Redistributions must retain this license text and provide clear attribution to
+ManimCat.
+
+4) No Warranty
+THE LICENSED MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
+
+5) Scope Control
+This license applies only to files explicitly designated in `LICENSE_POLICY.md`.
+All other files follow the licenses designated there.

LICENSE_POLICY.en.md

@@ -0,0 +1,36 @@
+# LICENSE POLICY
+
+This file defines the binding license scope for the ManimCat repository.
+
+## 1) Priority
+
+1. `LICENSE_POLICY.md` (Chinese policy) and this English mirror define file/path-level boundaries.
+2. `LICENSES/MIT.txt` and `LICENSES/ManimCat-NC.txt` provide full license texts.
+3. Files not listed in the MIT list in `LICENSE_POLICY.md` are treated as `ManimCat-NC` (Non-Commercial) by default.
+
+## 2) MIT List (Commercial Use Allowed)
+
+The following files/paths are under MIT (because they include upstream-related parts or highly similar derivative chains):
+
+- `src/services/manim-templates.ts` (because it includes upstream-related template and matching chains)
+- `src/services/manim-templates/**` (because it includes upstream-related template and matching chains)
+- `src/services/openai-client.ts` (because it includes upstream-related call chains)
+- `src/services/job-store.ts` (because it includes upstream-related interface chains)
+- `src/utils/logger.ts` (because it includes upstream-related logging structures)
+- `src/middlewares/error-handler.ts` (because it includes upstream-related error-handling chains)
+
+Third-party notices:
+- `THIRD_PARTY_NOTICES.md`
+- `THIRD_PARTY_NOTICES.zh-CN.md`
+
+## 3) Non-Commercial Scope (Default)
+
+Except for the MIT list above, all other files in this repository default to `LICENSES/ManimCat-NC.txt`.
+
+## 4) Separate Commercial Licensing
+
+If you want to use files in the non-commercial scope for commercial purposes, a separate written license from the author is required.
+
+## 5) Historical Versions
+
+This policy defines the scope for current and future versions of this repository. If historical versions were released under different terms, refer to the license statement in those versions.

LICENSE_POLICY.md

@@ -0,0 +1,36 @@
+# LICENSE POLICY
+
+本文件为 ManimCat 仓库的授权范围说明文件（binding scope）。
+
+## 1) 适用优先级
+
+1. `LICENSE_POLICY.md`（本文件）定义文件/路径级授权边界。
+2. `LICENSES/MIT.txt` 与 `LICENSES/ManimCat-NC.txt` 提供完整协议文本。
+3. 未在本文件中列入 MIT 清单的文件，默认适用 `ManimCat-NC`（非商业）协议。
+
+## 2) MIT 清单（可商用）
+
+以下文件/路径适用 MIT（括号说明：因为包含原作者项目相关部分或高度相似衍生链路）：
+
+- `src/services/manim-templates.ts`（因包含原作者相关模板与匹配链路）
+- `src/services/manim-templates/**`（因包含原作者相关模板与匹配链路）
+- `src/services/openai-client.ts`（因包含原作者相关调用链路）
+- `src/services/job-store.ts`（因包含原作者相关接口链路）
+- `src/utils/logger.ts`（因包含原作者相关日志结构）
+- `src/middlewares/error-handler.ts`（因包含原作者相关错误处理链路）
+
+第三方来源说明见：
+- `THIRD_PARTY_NOTICES.md`
+- `THIRD_PARTY_NOTICES.zh-CN.md`
+
+## 3) 非商业清单（默认）
+
+除“MIT 清单”外，本仓库其余文件默认适用 `LICENSES/ManimCat-NC.txt`。
+
+## 4) 另行商业授权
+
+若需将非商业范围内文件用于商业用途，需与作者签署书面商业授权。
+
+## 5) 历史版本说明
+
+本政策用于定义本仓库当前与后续版本的授权边界；历史版本若已在其他条款下发布，请以对应版本中的授权声明为准。

README.md

@@ -0,0 +1,341 @@
+---
+title: ManimCat
+emoji: 🐱
+colorFrom: gray
+colorTo: blue
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+English | [简体中文](https://github.com/Wing900/ManimCat/blob/main/README.zh-CN.md)
+
+<div align="center">
+
+<!-- Top decorative wave -->
+<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=455A64&height=120&section=header" />
+
+<br>
+
+<img src="public/logo.svg" width="200" alt="ManimCat Logo" />
+
+<!-- Cat paw accent -->
+<div style="opacity: 0.3; margin: 20px 0;">
+  <img src="https://raw.githubusercontent.com/Tarikul-Islam-Anik/Animated-Fluent-Emojis/master/Emojis/Animals/Paw%20Prints.png" width="40" alt="paws" />
+</div>
+
+<h1>
+  <picture>
+    <img src="https://readme-typing-svg.herokuapp.com?font=Fira+Code&size=40&duration=3000&pause=1000&color=455A64&center=true&vCenter=true&width=435&lines=ManimCat+%F0%9F%90%BE" alt="ManimCat" />
+  </picture>
+</h1>
+
+<!-- Math symbol divider -->
+<p align="center">
+  <span style="font-family: monospace; font-size: 24px; color: #90A4AE;">
+    ∫ &nbsp; ∑ &nbsp; ∂ &nbsp; ∞
+  </span>
+</p>
+
+<p align="center">
+  <strong>Dual-Mode AI Workspace for Mathematical Visuals</strong>
+</p>
+
+<p align="center">
+  Combining direct workflow generation with agent-driven studio collaboration, powered by Manim and matplotlib
+</p>
+
+<!-- Geometric divider -->
+<div style="margin: 30px 0;">
+  <span style="color: #CFD8DC; font-size: 20px;">◆ &nbsp; ◆ &nbsp; ◆</span>
+</div>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/ManimCE-0.19.2-455A64?style=for-the-badge&logo=python&logoColor=white" alt="ManimCE" />
+  <img src="https://img.shields.io/badge/React-19.2.0-455A64?style=for-the-badge&logo=react&logoColor=white" alt="React" />
+  <img src="https://img.shields.io/badge/Node.js-18+-455A64?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js" />
+  <img src="https://img.shields.io/badge/License-Mixed-607D8B?style=for-the-badge" alt="License" />
+</p>
+
+<p align="center" style="font-size: 18px;">
+  <a href="#overview"><strong>Overview</strong></a> •
+  <a href="#examples"><strong>Examples</strong></a> •
+  <a href="#quick-start"><strong>Quick Start</strong></a> •
+  <a href="#technology"><strong>Technology</strong></a> •
+  <a href="#deployment"><strong>Deployment</strong></a> •
+  <a href="#major-additions"><strong>Additions</strong></a> •
+  <a href="#license-and-copyright"><strong>License</strong></a> •
+  <a href="#maintenance-notes"><strong>Maintenance</strong></a>
+</p>
+
+<br>
+
+<!-- Bottom decorative wave -->
+<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=455A64&height=100&section=footer" />
+
+</div>
+
+<br>
+
+## Overview
+
+I am happy to introduce my new project, ManimCat. It is, after all, a cat.
+
+Built on top of [manim-video-generator](https://github.com/rohitg00/manim-video-generator), ManimCat is now a much broader AI-assisted creation system for math teaching visuals rather than just a single generation flow.
+
+It is designed for classroom explanation, worked-example breakdowns, and visual reasoning tasks. You can use natural language to generate, modify, rerender, and organize both animated and static teaching visuals with `video` and `image` outputs.
+
+The project is now organized around three clear axes: `dual-mode`, `dual-engine`, and `dual-studio`.
+
+- `Workflow Mode` is for direct generation and rendering when you want fast outputs
+- `Agent Mode` is for Studio-based collaborative work with longer-lived sessions, task state, review, and iteration
+- `Manim` is used for animation and timeline-based mathematical storytelling
+- `matplotlib` is used in Plot Studio for static math visuals, charts, and teaching figures
+- `Plot Studio` is the more mature Studio path today for static visual work and iterative editing
+- `Manim Studio` is the animation-oriented Studio path and is still at an earlier stage
+
+### Interface
+
+#### UI
+
+<div align="center">
+  <img src="https://github.com/user-attachments/assets/5abd29f6-adcb-4047-b85c-aba1fa0808a5" width="40%" alt="ManimCat UI screenshot 1" />
+  <img src="https://github.com/user-attachments/assets/d18d0f27-15b4-4c59-8a4b-a8b8fb553020" width="40%" alt="ManimCat UI screenshot 2" />
+</div>
+
+<div align="center">
+  <img src="https://github.com/user-attachments/assets/2c70886f-c381-4995-8ca4-2d0db1974829" width="40%" alt="ManimCat UI screenshot 3" />
+  <img src="https://github.com/user-attachments/assets/ce3718e8-4bc4-44db-87fb-3fb486eed144" width="40%" alt="ManimCat UI screenshot 4" />
+</div>
+
+#### Workflow
+
+<div align="center">
+  <img src="https://github.com/user-attachments/assets/b831caaf-10fe-4238-8998-d574f42af524" width="46%" alt="ManimCat Workflow screenshot 1" />
+  <img src="https://github.com/user-attachments/assets/30583571-f038-4c7b-9362-c988a896d374" width="46%" alt="ManimCat Workflow screenshot 2" />
+</div>
+
+#### Plot Studio
+
+<div align="center">
+  <img src="https://github.com/user-attachments/assets/0812b601-b896-4137-8e20-a2d4b6feadb9" width="46%" alt="ManimCat Plot Studio screenshot 1" />
+  <img src="https://github.com/user-attachments/assets/99ae423f-4b15-431d-8e21-30a6b6171616" width="46%" alt="ManimCat Plot Studio screenshot 2" />
+</div>
+
+## Examples
+
+<div align="center">
+
+> *Prove that $1/4 + 1/16 + 1/64 + \dots = 1/3$ using a beautiful geometric method, elegant zooming, smooth camera movement, a slow pace, at least two minutes of duration, clear logic, a creamy yellow background, and a macaroon-inspired palette.*
+
+<br>
+
+<a href="https://github.com/user-attachments/assets/38dba3ba-e29f-458d-b8ea-baf10cade4f1">
+  <video src="https://github.com/user-attachments/assets/38dba3ba-e29f-458d-b8ea-baf10cade4f1" width="85%" autoplay loop muted playsinline>
+  </video>
+</a>
+
+<sub>▲ Generated with BGM · Geometric Series Proof · ManimCat</sub>
+
+</div>
+
+## Quick Start
+
+```bash
+npm install
+cd frontend && npm install
+cd ..
+npm run dev
+```
+
+Open `http://localhost:3000`. For environment variables and deployment-specific setup, see the [deployment guide](https://github.com/Wing900/ManimCat/blob/main/DEPLOYMENT.md).
+
+If you want a direct Docker deployment path, you can also start from the published image `wingflow/manimcat` instead of building locally first.
+
+
+## Technology
+
+### Tech Stack
+
+- Product structure: Workflow mode for direct generation, Agent mode for Studio-based collaborative work
+- Visual engines: Manim for animation, `matplotlib` for Plot Studio static figures
+- Backend: Express + TypeScript, Bull + Redis, OpenAI-compatible upstream routing, Studio agent runtime, optional Supabase history storage
+- Frontend: React 19, Vite, Tailwind CSS, classic generator UI, Studio workspace shell, Plot Studio minimal workspace UI
+- Agent state model: session / run / task / work / result lifecycle for longer-lived studio interactions
+- Realtime layer: polling for Workflow jobs, Server-Sent Events for Agent sessions, permission requests, and task updates
+- Rendering runtime: Python, Manim Community Edition, `matplotlib`, LaTeX, `ffmpeg`
+- Deployment: Docker / Docker Compose, Hugging Face Spaces
+
+### Workflow Mode
+
+```mermaid
+flowchart LR
+    classDef ui fill:#F6F7FB,stroke:#455A64,color:#263238,stroke-width:1.2px;
+    classDef logic fill:#FFF8E1,stroke:#A1887F,color:#4E342E,stroke-width:1.2px;
+    classDef api fill:#E8F5E9,stroke:#5D8A66,color:#1B4332,stroke-width:1.2px;
+    classDef state fill:#E3F2FD,stroke:#5C6BC0,color:#1A237E,stroke-width:1.2px;
+    classDef output fill:#FCE4EC,stroke:#AD5C7D,color:#6A1B4D,stroke-width:1.2px;
+
+    U[User prompt] --> P1
+    P1[Classic UI] --> P2[Problem framing]
+    P1 --> P3[Generate / Modify requests]
+    P2 --> A1[Workflow APIs]
+    P3 --> A1
+    A1 --> R1[Upstream routing + AI generation]
+    R1 --> C1[Static checks + retry / patch loop]
+    C1 --> B1[Queue + job state]
+    B1 --> B2[Render pipeline]
+    B2 --> O1[Video / images / code / timings]
+    P1 -. polling / cancel .-> B1
+    O1 --> P1
+
+    class P1 ui;
+    class P2,P3,R1,C1 logic;
+    class A1 api;
+    class B1,B2 state;
+    class O1 output;
+```
+
+### Agent Mode
+
+```mermaid
+flowchart LR
+    classDef ui fill:#F6F7FB,stroke:#455A64,color:#263238,stroke-width:1.2px;
+    classDef runtime fill:#FFF8E1,stroke:#A1887F,color:#4E342E,stroke-width:1.2px;
+    classDef api fill:#E8F5E9,stroke:#5D8A66,color:#1B4332,stroke-width:1.2px;
+    classDef state fill:#E3F2FD,stroke:#5C6BC0,color:#1A237E,stroke-width:1.2px;
+    classDef event fill:#FCE4EC,stroke:#AD5C7D,color:#6A1B4D,stroke-width:1.2px;
+
+    U[User instruction] --> S1
+    S1[Studio UI] --> A1[Session / run APIs]
+    A1 --> R1[Studio runtime service]
+    R1 --> K1[Manim Studio / Plot Studio]
+    K1 --> G1[Builder, Designer, Reviewer]
+    G1 --> T1[Tools, skills, render / review actions]
+    R1 --> S2[Session / run / task / work state]
+    R1 --> E1[SSE events + permissions]
+    S2 --> S1
+    E1 --> S1
+
+    class S1 ui;
+    class A1 api;
+    class R1,K1 runtime;
+    class G1,T1,S2 state;
+    class E1 event;
+```
+
+For environment variables, deployment modes, and upstream-routing examples, see the [deployment guide](https://github.com/Wing900/ManimCat/blob/main/DEPLOYMENT.md).
+
+## Deployment
+
+Please see the [deployment guide](https://github.com/Wing900/ManimCat/blob/main/DEPLOYMENT.md).
+
+## Major Additions
+
+This project is a substantial rework built on top of the original foundation. The main additions I personally designed and implemented are:
+
+### Generation and Rendering
+
+- Added a dedicated image workflow alongside video generation
+- Added `YON_IMAGE` anchor-based segmented rendering for multi-image outputs
+- Added two-stage AI generation: a concept designer produces a scene design, then a code generator writes the Manim code
+- Added a static analysis guard (`py_compile` + `mypy`) that checks generated code before rendering, with AI-powered auto-patching for up to 3 passes
+- Added AI-driven code retry: when a render fails, the error is fed back to the model to regenerate and re-render automatically
+- Added rerender-from-code and AI-assisted modify-and-render flows
+- Added stage timing breakdown shared by both image and video jobs
+- Added background music mixing for rendered videos
+- Added render-failure event collection and export for debugging and reliability work
+
+### Product and Interface
+
+- Rebuilt the frontend as a separate React + TypeScript + Vite application
+- Added problem framing before generation to help structure user requests
+- Added reference image upload support
+- Added a unified workspace for generation history and usage views
+- Added a usage metrics dashboard with daily charts, success rates, and timing breakdowns
+- Added a prompt template manager for viewing and overriding system prompts per role
+- Added dark / light theme toggle
+- Added a waiting-state 2048 mini-game
+- Added a refreshed visual style, settings panels, and provider configuration flows
+
+### Infrastructure and Routing
+
+- Reworked the backend around Express + Bull + Redis
+- Added retry, timeout, cancellation, and status-query flows
+- Added support for third-party OpenAI-compatible APIs and custom provider configuration
+- Added server-side upstream routing by ManimCat key
+- Kept optional multi-profile frontend provider rotation for local use
+- Added optional Supabase-backed persistent history storage
+
+### Studio Agent
+
+- Added a separate Agent Mode driven by a Studio runtime rather than the classic one-shot generation flow
+- Defined the long-lived Studio state model around session / run / task / work / result
+- Added builder, designer, and reviewer roles inside the Studio agent system
+- Added workspace tools, render tools, local skills, and subagent orchestration
+- Added Server-Sent Events for live Studio updates plus permission request / reply handling
+- Added Studio review, pipeline, work, and permission panels in the frontend
+
+### Plot Studio and Manim Studio
+
+- Added two distinct Studio workspaces: Plot Studio for `matplotlib`-based static visuals and Manim Studio for animation-oriented workflows
+- Added Plot Studio output history browsing, work reordering, and a minimal split workspace layout
+- Established the dual-engine product direction: Manim for animated mathematical storytelling, `matplotlib` for static teaching figures and charts
+
+## License and Copyright
+
+Licensing details are defined in `LICENSE_POLICY.md` (Chinese) and `LICENSE_POLICY.en.md` (English).
+
+- Third-party attribution and notices: `THIRD_PARTY_NOTICES.md`
+- Chinese third-party notices: `THIRD_PARTY_NOTICES.zh-CN.md`
+- Contribution agreement: `CLA.md`
+- Contribution guide: `CONTRIBUTING.md`
+
+### CLA Intent Statement
+
+This project uses a CLA so the maintainer can keep commercial-use authorization under a single workflow, instead of requiring separate consent from every contributor each time.
+
+This is not a statement of "project commercialization" as a company path. The maintainer remains a developer, the project stays open source, and the project stance is anti-monopoly.
+
+Any commercial authorization income is intended to be reinvested into project development itself, including support for major contributors and community activities. For small companies that are open-source-friendly, authorization terms and fees are expected to be symbolic.
+
+## Maintenance Notes
+
+Because my time is limited and I am an independent hobbyist rather than a full-time professional maintainer, I currently cannot provide fast review cycles or long-term maintenance for external contributions. Pull requests are welcome, but review may take time.
+
+If you have good suggestions or discover a bug, feel free to open an Issue for discussion. I will improve the project at my own pace. If you want to make large-scale changes on top of this work, you are also welcome to fork it and build your own version.
+
+If this project gave you useful ideas or helped you in some way, that is already an honor for me.
+
+<details>
+  <summary><b>If you like this project, you can also buy the author a Coke 🥤</b></summary>
+  <br />
+  <p>Mainland China:</p>
+  <img src="https://github.com/user-attachments/assets/09fd8c5f-9644-4c02-97c1-61f10b0fdd1f" width="360" alt="Support ManimCat" />
+  <br />
+  <p>International:</p>
+  <a href="https://afdian.com/a/wingflow/plan" target="_blank">
+    <img src="https://img.shields.io/badge/Support-Aifadian-635cff?style=for-the-badge&logo=shopee&logoColor=white" alt="Support on Aifadian" />
+  </a>
+  <p><i>Thank you. Your support gives me more energy to keep maintaining the project.</i></p>
+</details>
+
+## Star History
+
+<a href="https://www.star-history.com/?repos=Wing900%2FManimCat&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=Wing900/ManimCat&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=Wing900/ManimCat&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/image?repos=Wing900/ManimCat&type=date&legend=top-left" />
+ </picture>
+</a>
+
+## Acknowledgements
+
+- [rohitg00/manim-video-generator](https://github.com/rohitg00/manim-video-generator)
+- [anomalyco/opencode](https://github.com/anomalyco/opencode)
+- [Linux.do](https://linux.do)
+- [Alibaba Cloud Bailian](https://bailian.console.aliyun.com)
+
+
+

README.zh-CN.md

@@ -0,0 +1,332 @@
+简体中文 | [English](https://github.com/Wing900/ManimCat/blob/main/README.md)
+
+<div align="center">
+
+<!-- 顶部装饰线 - 统一为深灰色调 -->
+<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=455A64&height=120&section=header" />
+
+<br>
+
+<img src="public/logo.svg" width="200" alt="ManimCat Logo" />
+
+<!-- 装饰：猫咪足迹 -->
+<div style="opacity: 0.3; margin: 20px 0;">
+  <img src="https://raw.githubusercontent.com/Tarikul-Islam-Anik/Animated-Fluent-Emojis/master/Emojis/Animals/Paw%20Prints.png" width="40" alt="paws" />
+</div>
+
+<h1>
+  <picture>
+    <img src="https://readme-typing-svg.herokuapp.com?font=Fira+Code&size=40&duration=3000&pause=1000&color=455A64&center=true&vCenter=true&width=435&lines=ManimCat+%F0%9F%90%BE" alt="ManimCat" />
+  </picture>
+</h1>
+
+<!-- 装饰：数学符号分隔 -->
+<p align="center">
+  <span style="font-family: monospace; font-size: 24px; color: #90A4AE;">
+    ∫ &nbsp; ∑ &nbsp; ∂ &nbsp; ∞
+  </span>
+</p>
+
+<p align="center">
+  <strong>面向数学可视化创作的双模式 AI 工作台</strong>
+</p>
+
+<p align="center">
+  同时支持直接生成工作流与基于 Agent 的 Studio 协作，并由 Manim 与 matplotlib 双引擎支撑
+</p>
+
+<!-- 装饰：几何点阵分隔 -->
+<div style="margin: 30px 0;">
+  <span style="color: #CFD8DC; font-size: 20px;">◆ &nbsp; ◆ &nbsp; ◆</span>
+</div>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/ManimCE-0.19.2-455A64?style=for-the-badge&logo=python&logoColor=white" alt="ManimCE" />
+  <img src="https://img.shields.io/badge/React-19.2.0-455A64?style=for-the-badge&logo=react&logoColor=white" alt="React" />
+  <img src="https://img.shields.io/badge/Node.js-18+-455A64?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js" />
+  <img src="https://img.shields.io/badge/License-Mixed-607D8B?style=for-the-badge" alt="License" />
+</p>
+
+<p align="center" style="font-size: 18px;">
+  <a href="#项目简介"><strong>项目简介</strong></a> •
+  <a href="#样例"><strong>样例</strong></a> •
+  <a href="#快速开始"><strong>快速开始</strong></a> •
+  <a href="#技术"><strong>技术</strong></a> •
+  <a href="#部署"><strong>部署</strong></a> •
+  <a href="#在原项目基础上的主要扩展"><strong>主要扩展</strong></a> •
+  <a href="#开源与版权声明"><strong>版权</strong></a> •
+  <a href="#维护说明"><strong>维护</strong></a>
+</p>
+
+<br>
+
+<!-- 底部装饰线 - 统一为深灰色调 -->
+<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=455A64&height=100&section=footer" />
+
+</div>
+
+<br>
+
+## 项目简介
+
+很荣幸在这里介绍我的新项目ManimCat，它是~一只猫~
+
+本项目基于 [manim-video-generator](https://github.com/rohitg00/manim-video-generator) 进行了大幅重构与再开发，现在已经不只是单一生成流程，而是一个更完整的 AI 数学教学可视化创作系统。
+
+它面向课堂讲解、例题拆解与数形结合表达等场景，用户可以通过自然语言生成、修改、重渲染并组织动画与静态两类教学可视化内容，支持 `video` 与 `image` 两种输出。
+
+项目现在可以从三个维度理解：`双模式`、`双引擎`、`双 Studio`。
+
+- `Workflow Mode` 用于直接生成与渲染，适合快速产出
+- `Agent Mode` 用于基于 Studio 的协作式创作、审阅、任务跟踪与迭代
+- `Manim` 负责动画、镜头与时间线驱动的数学叙事
+- `matplotlib` 负责 Plot Studio 中的静态数学图像、函数图、图表与教学插图
+- `Plot Studio` 是目前更成熟的 Studio 路径，主要面向静态可视化与迭代编辑
+- `Manim Studio` 面向动画创作，但目前仍处于相对更早期的阶段
+
+### 界面
+
+#### UI 界面
+
+<div align="center">
+  <img src="https://github.com/user-attachments/assets/5abd29f6-adcb-4047-b85c-aba1fa0808a5" width="40%" alt="ManimCat UI 界面截图 1" />
+  <img src="https://github.com/user-attachments/assets/d18d0f27-15b4-4c59-8a4b-a8b8fb553020" width="40%" alt="ManimCat UI 界面截图 2" />
+</div>
+
+<div align="center">
+  <img src="https://github.com/user-attachments/assets/2c70886f-c381-4995-8ca4-2d0db1974829" width="40%" alt="ManimCat UI 界面截图 3" />
+  <img src="https://github.com/user-attachments/assets/ce3718e8-4bc4-44db-87fb-3fb486eed144" width="40%" alt="ManimCat UI 界面截图 4" />
+</div>
+
+#### Workflow 界面
+
+<div align="center">
+  <img src="https://github.com/user-attachments/assets/b831caaf-10fe-4238-8998-d574f42af524" width="46%" alt="ManimCat Workflow 界面截图 1" />
+  <img src="https://github.com/user-attachments/assets/30583571-f038-4c7b-9362-c988a896d374" width="46%" alt="ManimCat Workflow 界面截图 2" />
+</div>
+
+#### Plot Studio 界面
+
+<div align="center">
+  <img src="https://github.com/user-attachments/assets/0812b601-b896-4137-8e20-a2d4b6feadb9" width="46%" alt="ManimCat Plot Studio 界面���图 1" />
+  <img src="https://github.com/user-attachments/assets/99ae423f-4b15-431d-8e21-30a6b6171616" width="46%" alt="ManimCat Plot Studio 界面截图 2" />
+</div>
+
+## 样例
+
+<div align="center">
+
+> *$1/4 + 1/16 + 1/64 + \dots = 1/3$，证明这个等式，美丽的图形方法，优雅的缩放平稳镜头移动，慢节奏，至少两分钟，逻辑清晰，奶黄色背景，马卡龙色系*
+
+<br>
+
+<a href="https://github.com/user-attachments/assets/38dba3ba-e29f-458d-b8ea-baf10cade4f1">
+  <video src="https://github.com/user-attachments/assets/38dba3ba-e29f-458d-b8ea-baf10cade4f1" width="85%" autoplay loop muted playsinline>
+  </video>
+</a>
+
+<sub>▲ 含背景音乐 · 几何级数证明 · ManimCat 生成</sub>
+
+</div>
+
+## 快速开始
+
+```bash
+npm install
+cd frontend && npm install
+cd ..
+npm run dev
+```
+
+访问 `http://localhost:3000`。环境变量、部署方式以及上游路由示例请查看[部署文档](https://github.com/Wing900/ManimCat/blob/main/DEPLOYMENT.zh-CN.md)。
+
+如果你直接用 Docker 镜像部署，也可以从 `wingflow/manimcat` 开始，而不是自行本地构建。
+
+
+## 技术
+
+### 技术栈
+
+- 产品结构：Workflow 模式用于直接生成，Agent 模式用于 Studio 协作式工作流
+- 图形引擎：Manim 用于动画，`matplotlib` 用于 Plot Studio 静态图像
+- 后端：Express + TypeScript、Bull + Redis、兼容 OpenAI 的上游路由、Studio Agent 运行时、可选 Supabase 历史记录
+- 前端：React 19、Vite、Tailwind CSS、经典生成界面、Studio 工作台界面、Plot Studio 极简工作区 UI
+- Agent 状态模型：围绕 session / run / task / work / result 组织长生命周期 Studio 交互
+- 实时层：Workflow 任务使用轮询，Agent 会话使用 Server-Sent Events 推送事件、权限请求与任务更新
+- 渲染运行时：Python、Manim Community Edition、`matplotlib`、LaTeX、`ffmpeg`
+- 部署：Docker / Docker Compose、Hugging Face Spaces
+
+### Workflow Mode
+
+```mermaid
+flowchart LR
+    classDef ui fill:#F6F7FB,stroke:#455A64,color:#263238,stroke-width:1.2px;
+    classDef logic fill:#FFF8E1,stroke:#A1887F,color:#4E342E,stroke-width:1.2px;
+    classDef api fill:#E8F5E9,stroke:#5D8A66,color:#1B4332,stroke-width:1.2px;
+    classDef state fill:#E3F2FD,stroke:#5C6BC0,color:#1A237E,stroke-width:1.2px;
+    classDef output fill:#FCE4EC,stroke:#AD5C7D,color:#6A1B4D,stroke-width:1.2px;
+
+    U[用户输入] --> P1
+    P1[经典生成界面] --> P2[问题规划]
+    P1 --> P3[生成 / 修改请求]
+    P2 --> A1[Workflow API]
+    P3 --> A1
+    A1 --> R1[上游路由 + AI 生成]
+    R1 --> C1[静态检查 + 重试 / 修补循环]
+    C1 --> B1[队列 + 任务状态]
+    B1 --> B2[渲染流水线]
+    B2 --> O1[视频 / 图片 / 代码 / 耗时]
+    P1 -. 轮询 / 取消 .-> B1
+    O1 --> P1
+
+    class P1 ui;
+    class P2,P3,R1,C1 logic;
+    class A1 api;
+    class B1,B2 state;
+    class O1 output;
+```
+
+### Agent Mode
+
+```mermaid
+flowchart LR
+    classDef ui fill:#F6F7FB,stroke:#455A64,color:#263238,stroke-width:1.2px;
+    classDef runtime fill:#FFF8E1,stroke:#A1887F,color:#4E342E,stroke-width:1.2px;
+    classDef api fill:#E8F5E9,stroke:#5D8A66,color:#1B4332,stroke-width:1.2px;
+    classDef state fill:#E3F2FD,stroke:#5C6BC0,color:#1A237E,stroke-width:1.2px;
+    classDef event fill:#FCE4EC,stroke:#AD5C7D,color:#6A1B4D,stroke-width:1.2px;
+
+    U[用户指令] --> S1
+    S1[Studio 界面] --> A1[Session / Run API]
+    A1 --> R1[Studio Runtime Service]
+    R1 --> K1[Manim Studio / Plot Studio]
+    K1 --> G1[Builder、Designer、Reviewer]
+    G1 --> T1[工具、skills、渲染 / 审查动作]
+    R1 --> S2[Session / Run / Task / Work 状态]
+    R1 --> E1[SSE 实时事件 + 权限]
+    S2 --> S1
+    E1 --> S1
+
+    class S1 ui;
+    class A1 api;
+    class R1,K1 runtime;
+    class G1,T1,S2 state;
+    class E1 event;
+```
+
+## 部署
+
+请查看[部署文档](https://github.com/Wing900/ManimCat/blob/main/DEPLOYMENT.zh-CN.md)。
+
+## 在原项目基础上的主要扩展
+
+这个项目是在原始基础上做的大幅重构与再开发。以下是我本人新增和重构的核心能力：
+
+### 生成与渲染
+
+- 在视频生成之外，新增了独立的图片工作流
+- 新增 `YON_IMAGE` 锚点分块渲染，支持多图输出
+- 新增两阶段 AI 生成架构：概念设计者生成场景方案，再由代码生成者产出 Manim 代码
+- 新增静态检查守卫（`py_compile` + `mypy`），渲染前自动检查生成代码，并由 AI 自动修补，最多循环 3 轮
+- 新增 AI 驱动的代码重试：渲染失败后自动将错误反馈给模型，重新生成并再次渲染
+- 新增基于现有代码的重渲染，以及 AI 辅助修改后再渲染
+- 新增图片与视频共用的阶段耗时统计
+- 新增视频背景音乐自动混入
+- 新增渲染失败事件采集与导出能力，便于排错和稳定性改进
+
+### 产品与界面
+
+- 将前端重建为独立的 React + TypeScript + Vite 应用
+- 新增生成前的问题规划能力，帮助整理用户请求
+- 新增参考图上传能力
+- 新增统一的工作空间页面，整合生成历史与用量视图
+- 新增用量仪表盘，提供每日调用量、成功率与耗时趋势图表
+- 新增提示词模板管理，可按角色查看和覆盖系统提示词
+- 新增暗色 / 亮色主题切换
+- 新增长等待过程中的 2048 小游戏
+- 新增整体视觉风格、设置面板与 provider 配置流程
+
+### 基础设施与路由
+
+- 将后端重构为 Express + Bull + Redis 架构
+- 新增重试、超时、取消与状态查询链路
+- 新增对第三方 OpenAI-compatible API 与自定义 provider 的支持
+- 新增按 ManimCat key 的服务端上游路由能力
+- 保留并扩展前端多 profile provider 轮询能力，便于本地使用
+- 新增可选的 Supabase 持久化历史记录存储
+
+### Studio Agent
+
+- 新增独立的 Agent Mode，它不再只是经典生成流程的附属页面，而是单独的 Studio runtime 工作模式
+- 定义了围绕 session、run、task、work、result 的长生命周期 Studio 状态模型
+- 新增 builder、designer、reviewer 三种 Studio agent 角色
+- 新增工作区工具、渲染工具、本地 skills 与子代理编排能力
+- 新增基于 Server-Sent Events 的 Studio 实时更新，以及权限请求 / 回复链路
+- 新增 Studio 前端中的 review、pipeline、work、permission 等面板
+
+### Plot Studio 与 Manim Studio
+
+- 新增两个明确分化的 Studio 工作区：Plot Studio 面向 `matplotlib` 静态可视化，Manim Studio 面向动画工作流
+- 新增 Plot Studio 的历史产物浏览、工作项重排与极简分栏工作区布局
+- 明确形成双引擎产品方向：Manim 负责动态数学叙事，`matplotlib` 负责静态教学图像与图表
+
+##  开源与版权声明 
+
+本项目授权细则见 `LICENSE_POLICY.md`。
+
+*   第三方来源与归属说明见 `THIRD_PARTY_NOTICES.md`。
+*   中文版第三方来源与归属说明见 `THIRD_PARTY_NOTICES.zh-CN.md`。
+*   贡献者许可协议见 `CLA.md`。
+*   贡献说明见 `CONTRIBUTING.md`。
+
+### CLA 目的说明
+
+本项目引入 CLA，是为了让维护者能够集中管理项目的商业使用授权，避免每次商业授权都需要逐一联系所有贡献者。
+
+这不代表项目会走向公司化商业运营。维护者始终以开发者身份维护项目，不以成为 ManimCat 公司的老板或经理为目标。项目将长期保持开源立场，反对垄断。
+
+若存在商业授权收入，资金将优先回馈项目本身，包括对项目基础建设、文档与测试完善、社区活动组织，以及对作出重大贡献开发者的支持。对于乐于开源、愿意回馈社区的小型商业公司，授权条款与费用将以象征性为主。
+
+## 维护说明
+
+由于作者精力有限（个人业余兴趣开发者，非专业背景），目前完全无法对外部代码进行有效的审查和长期维护。因此，本项目欢迎 PR，不过代码审查周期长。感谢理解。
+
+如果你有好的建议或发现了 Bug，欢迎提交 Issue 进行讨论，我会根据自己的节奏进行改进。如果你希望在本项目基础上进行大规模修改，欢迎 Fork 出属于你自己的版本。
+
+如果你觉得有启发与帮助，那是我的荣幸。
+
+
+<details>
+  <summary><b>如果你觉得这个作品很好，也欢迎请作者喝可乐🥤</b></summary>
+  <br />
+  <p>中国大陆用户：</p>
+  <img src="https://github.com/user-attachments/assets/09fd8c5f-9644-4c02-97c1-61f10b0fdd1f" width="360" alt="赞助 ManimCat" />
+  <br />
+  <p>海外用户：</p>
+  <a href="https://afdian.com/a/wingflow/plan" target="_blank">
+    <img src="https://img.shields.io/badge/赞助-爱发电-635cff?style=for-the-badge&logo=shopee&logoColor=white" alt="爱发电赞助" />
+  </a>
+  <p><i>感谢你的支持，我会更有动力维护这个项目！</i></p>
+</details>
+
+## Star History
+
+<a href="https://www.star-history.com/?repos=Wing900%2FManimCat&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=Wing900/ManimCat&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=Wing900/ManimCat&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/image?repos=Wing900/ManimCat&type=date&legend=top-left" />
+ </picture>
+</a>
+
+## 致谢
+
+- [rohitg00/manim-video-generator](https://github.com/rohitg00/manim-video-generator)
+- [anomalyco/opencode](https://github.com/anomalyco/opencode)
+- [Linux.do](https://linux.do)
+- [阿里云百炼](https://bailian.console.aliyun.com)
+
+
+
+
+

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,18 @@
+# Third-Party Notices
+
+This project (`ManimCat`) references and builds on ideas and portions of code from:
+
+- `manim-video-generator` by Rohit Ghumare  
+  Repository: https://github.com/rohitg00/manim-video-generator  
+  License: MIT
+
+## Notice Scope
+
+- Any inherited or derivative portions from upstream remain subject to the upstream MIT license terms.
+- This repository is distributed under MIT (`LICENSE`).
+- Copyright for original contributions made in this repository remains with their respective authors.
+
+## Clarification
+
+If you need proprietary licensing for deliverables not included in this repository, contact the author for a separate written agreement.
+

THIRD_PARTY_NOTICES.zh-CN.md

@@ -0,0 +1,18 @@
+# 第三方声明
+
+本项目（`ManimCat`）参考并在部分代码层面基于以下项目：
+
+- `manim-video-generator`（作者：Rohit Ghumare）  
+  仓库：https://github.com/rohitg00/manim-video-generator  
+  许可证：MIT
+
+## 声明范围
+
+- 继承或衍生自上游的代码部分，继续受上游 MIT 许可证约束。
+- 本仓库以 MIT 协议发布（见 `LICENSE`）。
+- 本仓库中的原创贡献，其著作权归各自作者所有。
+
+## 补充说明
+
+若你需要对“未包含在本仓库中的交付物”进行专有商业授权，请与作者另行书面协商。
+

docker-compose.yml

@@ -0,0 +1,105 @@
+# Docker Compose for ManimCat
+# Production-ready with Redis for task queue and state management
+
+version: '3.8'
+
+services:
+  redis:
+    image: redis:7-alpine
+    container_name: manim-redis
+    ports:
+      - "${REDIS_PORT:-6379}:6379"
+    volumes:
+      - redis-data:/data
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 600s
+      retries: 10
+      start_period: 5s
+    command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
+    networks:
+      - manimcat-network
+
+  manimcat:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        - NODE_ENV=production
+    image: manimcat:latest
+    container_name: manimcat
+    ports:
+      - "${PORT:-3000}:3000"
+    environment:
+      - NODE_ENV=production
+      - PORT=3000
+      - LOG_LEVEL=${LOG_LEVEL:-info}
+      - PROD_SUMMARY_LOG_ONLY=${PROD_SUMMARY_LOG_ONLY:-true}
+      - HTTP_PROXY=${HTTP_PROXY:-}
+      - HTTPS_PROXY=${HTTPS_PROXY:-}
+      - NO_PROXY=${NO_PROXY:-}
+      - http_proxy=${http_proxy:-}
+      - https_proxy=${https_proxy:-}
+      - no_proxy=${no_proxy:-}
+      - REDIS_HOST=redis
+      - REDIS_PORT=6379
+      - REDIS_DB=${REDIS_DB:-0}
+      # Upstream routing (required for server-side generation unless frontend passes customApiConfig)
+      - MANIMCAT_ROUTE_KEYS=${MANIMCAT_ROUTE_KEYS:-}
+      - MANIMCAT_ROUTE_API_URLS=${MANIMCAT_ROUTE_API_URLS:-}
+      - MANIMCAT_ROUTE_API_KEYS=${MANIMCAT_ROUTE_API_KEYS:-}
+      - MANIMCAT_ROUTE_MODELS=${MANIMCAT_ROUTE_MODELS:-}
+      - DISPLAY=:99
+    volumes:
+      # Persist studio workspace sessions, generated code, and studio outputs
+      - studio-workspace-data:/app/.studio-workspace
+      # Persist generated images and uploaded reference images
+      - image-storage:/app/public/images
+      # Persist generated videos
+      - video-storage:/app/public/videos
+      # Persist Manim media cache and intermediate render artifacts
+      - manim-media:/app/media
+      # Temp directory for rendering
+      - manim-tmp:/app/tmp
+    depends_on:
+      redis:
+        condition: service_healthy
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "node -e \"require('http').get('http://localhost:3000/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))\""]
+      interval: 30s
+      timeout: 600s
+      retries: 3
+      start_period: 40s
+    networks:
+      - manimcat-network
+    # Resource limits (adjust based on your needs)
+    deploy:
+      resources:
+        limits:
+          cpus: '2'
+          memory: 4G
+        reservations:
+          cpus: '1'
+          memory: 2G
+
+networks:
+  manimcat-network:
+    driver: bridge
+
+volumes:
+  studio-workspace-data:
+    driver: local
+  image-storage:
+    driver: local
+  manim-tmp:
+    driver: local
+  manim-media:
+    driver: local
+  redis-data:
+    driver: local
+  video-storage:
+    driver: local
+

frontend/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

frontend/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

frontend/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <!-- 直接内嵌 SVG 作为 favicon -->
+    <link rel="icon" href="data:image/svg+xml,<svg viewBox='0 0 512 512' xmlns='http://www.w3.org/2000/svg'><rect width='512' height='512' fill='%23faf9f5'/><path d='M 100 400 V 140 L 230 300 L 360 140 V 260' fill='none' stroke='%23455a64' stroke-width='55' stroke-linecap='round' stroke-linejoin='round'/><g transform='translate(360, 340)'><path d='M -70 40 C -80 0, -80 -30, -50 -60 L -20 -30 L 20 -30 L 50 -60 C 80 -30, 80 0, 70 40 C 60 70, -60 70, -70 40 Z' fill='%23455a64'/><circle cx='-35' cy='-5' r='18' fill='%23ffffff'/><circle cx='35' cy='-5' r='18' fill='%23ffffff'/><circle cx='-38' cy='-5' r='6' fill='%23455a64'/><circle cx='32' cy='-5' r='6' fill='%23455a64'/></g></svg>" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>ManimCat</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

frontend/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "manim-cat-frontend",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@types/react-syntax-highlighter": "^15.5.13",
+    "jszip": "^3.10.1",
+    "katex": "^0.16.42",
+    "perfect-freehand": "^1.2.3",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-markdown": "^10.1.0",
+    "react-syntax-highlighter": "^16.1.0",
+    "rehype-katex": "^7.0.1",
+    "remark-gfm": "^4.0.1",
+    "remark-math": "^6.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.5",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "@vitest/coverage-v8": "^4.1.0",
+    "autoprefixer": "^10.4.23",
+    "eslint": "^9.39.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "globals": "^16.5.0",
+    "jsdom": "^29.0.1",
+    "postcss": "^8.5.6",
+    "tailwindcss": "^3.4.19",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.46.4",
+    "vite": "^7.2.4",
+    "vitest": "^4.1.0"
+  }
+}

frontend/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}

frontend/src/App.css

@@ -0,0 +1,42 @@
+#root {
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 2rem;
+  text-align: center;
+}
+
+.logo {
+  height: 6em;
+  padding: 1.5em;
+  will-change: filter;
+  transition: filter 300ms;
+}
+.logo:hover {
+  filter: drop-shadow(0 0 2em #646cffaa);
+}
+.logo.react:hover {
+  filter: drop-shadow(0 0 2em #61dafbaa);
+}
+
+@keyframes logo-spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  a:nth-of-type(2) .logo {
+    animation: logo-spin infinite 20s linear;
+  }
+}
+
+.card {
+  padding: 2em;
+}
+
+.read-the-docs {
+  color: #888;
+}

frontend/src/App.tsx

@@ -0,0 +1,322 @@
+import type { StudioKind } from './studio/protocol/studio-agent-types';
+import { useEffect, useRef, useState } from 'react';
+import type { JobResult, OutputMode, Quality, ReferenceImage } from './types/api';
+import { useGeneration } from './hooks/useGeneration';
+import { useProblemFraming } from './hooks/useProblemFraming';
+import { useGame2048 } from './hooks/useGame2048';
+import { useTabTitle } from './hooks/useTabTitle';
+import { AiModifyModal } from './components/AiModifyModal';
+import { SettingsModal } from './components/SettingsModal';
+import { DonationModal } from './components/DonationModal';
+import { ProviderConfigModal } from './components/ProviderConfigModal';
+import { Workspace } from './components/Workspace';
+import { StudioPage } from './pages/StudioPage';
+import { Game2048Page } from './pages/Game2048Page';
+import { PlotStudioShell } from './studio/PlotStudioShell';
+import { StudioShell } from './studio/StudioShell';
+import { StudioTransitionOverlay } from './studio/StudioTransitionOverlay';
+import { useI18n } from './i18n';
+
+type Screen = 'classic' | 'manim-studio' | 'plot-studio' | 'game';
+
+const STUDIO_TRANSITION_MS = 2000;
+const STUDIO_EXIT_DELAY_MS = 800;
+
+function createClassicRenderCacheKey(): string {
+  return `classic-${crypto.randomUUID()}`;
+}
+
+function App() {
+  const { status, result, error, jobId, stage, submittedAt, generate, renderWithCode, modifyWithAI, reset, cancel, cancelAndReset } = useGeneration();
+  const problemFraming = useProblemFraming();
+  const game = useGame2048();
+  useTabTitle(status, stage);
+  const { t } = useI18n();
+
+  const [settingsOpen, setSettingsOpen] = useState(false);
+  const [donationOpen, setDonationOpen] = useState(false);
+  const [providersOpen, setProvidersOpen] = useState(false);
+  const [workspaceOpen, setWorkspaceOpen] = useState(false);
+  const [aiModifyOpen, setAiModifyOpen] = useState(false);
+  const [currentCode, setCurrentCode] = useState('');
+  const [concept, setConcept] = useState('');
+  const [lastCompletedResult, setLastCompletedResult] = useState<JobResult | null>(null);
+  const [screen, setScreen] = useState<Screen>('classic');
+  const [activeStudioKind, setActiveStudioKind] = useState<StudioKind>('manim');
+  const [studioTransitionVisible, setStudioTransitionVisible] = useState(false);
+  const [studioIsExiting, setStudioIsExiting] = useState(false);
+  const [studioShellExiting, setStudioShellExiting] = useState(false);
+  const [isReturningFromStudio, setIsReturningFromStudio] = useState(false);
+  const [problemAdjustment, setProblemAdjustment] = useState('');
+  const studioTransitionTimerRef = useRef<number | null>(null);
+  const [lastRequest, setLastRequest] = useState<{
+    concept: string;
+    quality: Quality;
+    outputMode: OutputMode;
+    referenceImages?: ReferenceImage[];
+    renderCacheKey: string;
+  } | null>(null);
+
+  useEffect(() => {
+    return () => {
+      if (studioTransitionTimerRef.current) {
+        window.clearTimeout(studioTransitionTimerRef.current);
+      }
+    };
+  }, []);
+
+  useEffect(() => {
+    if (status === 'completed' && result) {
+      setLastCompletedResult(result);
+    }
+  }, [result, status]);
+
+  const resetAll = () => {
+    reset();
+    setCurrentCode('');
+    setConcept('');
+    setLastRequest(null);
+    setAiModifyOpen(false);
+    setLastCompletedResult(null);
+    setScreen('classic');
+    setActiveStudioKind('manim');
+    setStudioTransitionVisible(false);
+    setStudioIsExiting(false);
+    setStudioShellExiting(false);
+    setProblemAdjustment('');
+    if (studioTransitionTimerRef.current) {
+      window.clearTimeout(studioTransitionTimerRef.current);
+      studioTransitionTimerRef.current = null;
+    }
+    problemFraming.reset();
+  };
+
+  const handleOpenStudio = (studioKind: StudioKind) => {
+    if (studioTransitionVisible || screen === 'manim-studio' || screen === 'plot-studio') {
+      return;
+    }
+
+    setActiveStudioKind(studioKind);
+    setStudioIsExiting(false);
+    setStudioShellExiting(false);
+    setStudioTransitionVisible(true);
+    
+    studioTransitionTimerRef.current = window.setTimeout(() => {
+      setConcept('');
+      setScreen(studioKind === 'plot' ? 'plot-studio' : 'manim-studio');
+      
+      studioTransitionTimerRef.current = window.setTimeout(() => {
+        setStudioIsExiting(true);
+        
+        studioTransitionTimerRef.current = window.setTimeout(() => {
+          setStudioTransitionVisible(false);
+          setStudioIsExiting(false);
+          studioTransitionTimerRef.current = null;
+        }, STUDIO_EXIT_DELAY_MS);
+      }, 300);
+    }, STUDIO_TRANSITION_MS);
+  };
+
+  const handleExitStudio = () => {
+    if (studioTransitionVisible) return;
+
+    setStudioIsExiting(false);
+    setStudioShellExiting(true); // Studio 界面开始退场动画
+    setStudioTransitionVisible(true); // 遮罩开始升起
+
+    studioTransitionTimerRef.current = window.setTimeout(() => {
+      setScreen('classic');
+      setStudioShellExiting(false);
+      setIsReturningFromStudio(true); // 开启 Classic 入场动画
+      
+      studioTransitionTimerRef.current = window.setTimeout(() => {
+        setStudioIsExiting(true);
+        
+        studioTransitionTimerRef.current = window.setTimeout(() => {
+          setStudioTransitionVisible(false);
+          setStudioIsExiting(false);
+          setIsReturningFromStudio(false);
+          studioTransitionTimerRef.current = null;
+        }, STUDIO_EXIT_DELAY_MS);
+      }, 300);
+    }, STUDIO_TRANSITION_MS);
+  };
+
+  const handleSubmit = (data: {
+    concept: string;
+    quality: Quality;
+    outputMode: OutputMode;
+    referenceImages?: ReferenceImage[];
+  }) => {
+    setLastCompletedResult(null);
+    setConcept(data.concept);
+    setProblemAdjustment('');
+    void problemFraming.startPlan({ request: data });
+  };
+
+  const handleBackToHome = () => {
+    if (status === 'processing' || status === 'cancelling') {
+      cancelAndReset();
+      return;
+    }
+    setLastCompletedResult(null);
+    reset();
+  };
+
+  const handleProblemRetry = () => {
+    if (!problemAdjustment.trim()) {
+      return;
+    }
+    void problemFraming.refinePlan({ feedback: problemAdjustment.trim() });
+  };
+
+  const handleProblemGenerate = () => {
+    if (!problemFraming.draft || !problemFraming.plan) {
+      return;
+    }
+    const draft = problemFraming.draft;
+    const problemPlan = problemFraming.plan;
+    const renderCacheKey = createClassicRenderCacheKey();
+    setLastCompletedResult(null);
+    setLastRequest({ ...draft, renderCacheKey });
+    setConcept(draft.concept);
+    setCurrentCode('');
+    setProblemAdjustment('');
+    problemFraming.reset();
+    generate({ ...draft, problemPlan, renderCacheKey });
+  };
+
+  const handleProblemClose = () => {
+    setProblemAdjustment('');
+    problemFraming.reset();
+  };
+
+  const handleRerender = () => {
+    const code = currentCode.trim() || result?.code?.trim() || lastCompletedResult?.code?.trim() || '';
+    if (!lastRequest || !code) {
+      return;
+    }
+
+    setCurrentCode('');
+    renderWithCode({ ...lastRequest, code });
+  };
+
+  const handleAiModifySubmit = (instructions: string) => {
+    const code = currentCode.trim() || result?.code?.trim() || lastCompletedResult?.code?.trim() || '';
+    if (!lastRequest || !code) {
+      return;
+    }
+
+    setAiModifyOpen(false);
+    setCurrentCode('');
+    modifyWithAI({
+      concept: lastRequest.concept,
+      outputMode: lastRequest.outputMode,
+      quality: lastRequest.quality,
+      instructions,
+      code,
+      renderCacheKey: lastRequest.renderCacheKey,
+    });
+  };
+
+  const handleOpenGame = () => {
+    if (status !== 'processing' && status !== 'cancelling') {
+      return;
+    }
+    setScreen('game');
+  };
+
+  const isBusy = status === 'processing' || status === 'cancelling';
+  const displayResult = result ?? lastCompletedResult;
+
+  return (
+    <div className="min-h-screen bg-bg-primary transition-colors duration-300 overflow-x-hidden">
+      {screen === 'classic' ? (
+        <div className={isReturningFromStudio ? 'animate-classic-entrance' : ''}>
+          <StudioPage
+            status={status}
+            result={displayResult}
+            error={error}
+            jobId={jobId}
+            stage={stage}
+            submittedAt={submittedAt}
+            concept={concept}
+            currentCode={currentCode || result?.code || ''}
+            isBusy={isBusy}
+            lastRequest={lastRequest}
+            onConceptChange={setConcept}
+            onSecretStudioOpen={handleOpenStudio}
+            onSubmit={handleSubmit}
+            onCodeChange={setCurrentCode}
+            onRerender={handleRerender}
+            onAiModifyOpen={() => setAiModifyOpen(true)}
+            onResetAll={resetAll}
+            onBackToHome={handleBackToHome}
+            onCancel={cancel}
+            onOpenDonation={() => setDonationOpen(true)}
+            onOpenProviders={() => setProvidersOpen(true)}
+            onOpenWorkspace={() => setWorkspaceOpen(true)}
+            onOpenSettings={() => setSettingsOpen(true)}
+            onOpenGame={handleOpenGame}
+            problemOpen={problemFraming.status !== 'idle'}
+            problemStatus={problemFraming.status === 'idle' ? 'loading' : problemFraming.status}
+            problemPlan={problemFraming.plan}
+            problemError={problemFraming.error}
+            problemAdjustment={problemAdjustment}
+            onProblemAdjustmentChange={setProblemAdjustment}
+            onProblemRetry={handleProblemRetry}
+            onProblemClose={handleProblemClose}
+            onProblemGenerate={handleProblemGenerate}
+          />
+        </div>
+      ) : screen === 'manim-studio' ? (
+        <StudioShell
+          onExit={handleExitStudio}
+          isExiting={studioShellExiting}
+          studioKind={activeStudioKind}
+        />
+      ) : screen === 'plot-studio' ? (
+        <PlotStudioShell
+          onExit={handleExitStudio}
+          isExiting={studioShellExiting}
+        />
+      ) : (
+        <Game2048Page
+          board={game.board}
+          score={game.score}
+          bestScore={game.bestScore}
+          isGameOver={game.isGameOver}
+          hasWon={game.hasWon}
+          maxTile={game.maxTile}
+          generationStatus={status}
+          generationStage={stage}
+          onMove={game.move}
+          onRestart={game.restart}
+          onBackToStudio={() => setScreen('classic')}
+        />
+      )}
+
+      <StudioTransitionOverlay visible={studioTransitionVisible} isExiting={studioIsExiting} />
+
+      <style>{`
+        @keyframes fadeInUp {
+          0% { opacity: 0; transform: translateY(30px); }
+          100% { opacity: 1; transform: translateY(0); }
+        }
+      `}</style>
+
+      <SettingsModal key={`settings-${settingsOpen ? 'open' : 'closed'}`} isOpen={settingsOpen} onClose={() => setSettingsOpen(false)} onSave={() => undefined} />
+      <DonationModal key={`donation-${donationOpen ? 'open' : 'closed'}`} isOpen={donationOpen} onClose={() => setDonationOpen(false)} />
+      <ProviderConfigModal key={`providers-${providersOpen ? 'open' : 'closed'}`} isOpen={providersOpen} onClose={() => setProvidersOpen(false)} onSave={() => undefined} />
+      <Workspace key={`workspace-${workspaceOpen ? 'open' : 'closed'}`} isOpen={workspaceOpen} onClose={() => setWorkspaceOpen(false)} />
+      <AiModifyModal
+        isOpen={aiModifyOpen}
+        loading={isBusy}
+        onClose={() => setAiModifyOpen(false)}
+        onSubmit={handleAiModifySubmit}
+      />
+    </div>
+  );
+}
+
+export default App;

frontend/src/components/AiModifyModal.tsx

@@ -0,0 +1,96 @@
+// AI 修改对话框
+
+import { useEffect, useState } from 'react';
+import { useI18n } from '../i18n';
+import { useModalTransition } from '../hooks/useModalTransition';
+
+interface AiModifyModalProps {
+  isOpen: boolean;
+  loading?: boolean;
+  onClose: () => void;
+  onSubmit: (value: string) => void;
+}
+
+export function AiModifyModal({ isOpen, loading = false, onClose, onSubmit }: AiModifyModalProps) {
+  const { t } = useI18n();
+  const { shouldRender, isExiting } = useModalTransition(isOpen);
+  const [draft, setDraft] = useState('');
+
+  useEffect(() => {
+    if (isOpen) {
+      setDraft('');
+    }
+  }, [isOpen]);
+
+  if (!shouldRender) return null;
+
+  return (
+    <div className="fixed inset-0 z-[120] flex items-center justify-center p-4">
+      {/* 沉浸式背景 */}
+      <div 
+        className={`absolute inset-0 bg-bg-primary/60 backdrop-blur-md transition-opacity duration-300 ${
+          isExiting ? 'opacity-0' : 'animate-overlay-wash-in'
+        }`} 
+        onClick={onClose} 
+      />
+
+      {/* 模态框主体 */}
+      <div className={`relative w-full max-w-lg bg-bg-secondary rounded-[2.5rem] p-10 shadow-2xl border border-border/5 ${
+        isExiting ? 'animate-fade-out-soft' : 'animate-fade-in-soft'
+      }`}>
+        <div className="flex items-center justify-between mb-8">
+          <div className="flex items-center gap-3">
+            <div className="w-2 h-2 rounded-full bg-accent-rgb/40 animate-pulse" />
+            <h2 className="text-xl font-medium text-text-primary tracking-tight">{t('aiModify.title')}</h2>
+          </div>
+          <button
+            onClick={onClose}
+            className="p-2.5 text-text-secondary/50 hover:text-text-primary hover:bg-bg-primary/50 rounded-2xl transition-all"
+          >
+            <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
+            </svg>
+          </button>
+        </div>
+
+        <p className="text-text-secondary text-[15px] mb-8 leading-relaxed font-light">
+          {t('aiModify.description')}
+        </p>
+
+        <div className="relative mb-10 group">
+          <textarea
+            id="aiModifyInput"
+            rows={5}
+            value={draft}
+            onChange={(e) => setDraft(e.target.value)}
+            placeholder={t('aiModify.placeholder')}
+            className="w-full px-6 py-6 bg-bg-secondary/50 border border-border/5 rounded-3xl text-base text-text-primary placeholder-text-secondary/30 focus:outline-none focus:border-accent-rgb/30 focus:bg-bg-secondary/80 transition-all resize-none shadow-inner"
+          />
+          <label
+            htmlFor="aiModifyInput"
+            className="absolute right-6 -bottom-3 px-3 py-1 bg-bg-secondary border border-border/5 rounded-full text-[10px] uppercase tracking-widest text-text-secondary/40 group-focus-within:text-accent-rgb/60 group-focus-within:border-accent-rgb/20 transition-all"
+          >
+            {t('aiModify.label')}
+          </label>
+        </div>
+
+        <div className="flex gap-4">
+          <button
+            onClick={onClose}
+            disabled={loading}
+            className="flex-1 py-4 text-sm text-text-secondary hover:text-text-primary bg-bg-primary/50 hover:bg-bg-tertiary rounded-2xl transition-all active:scale-95 disabled:opacity-50"
+          >
+            {t('common.cancel')}
+          </button>
+          <button
+            onClick={() => onSubmit(draft.trim())}
+            disabled={loading || draft.trim().length === 0}
+            className="flex-1 py-4 text-sm text-bg-primary bg-text-primary hover:bg-accent-hover-rgb rounded-2xl transition-all active:scale-95 disabled:opacity-50 shadow-lg font-medium"
+          >
+            {loading ? t('aiModify.submitting') : t('aiModify.submit')}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

frontend/src/components/CodeView.tsx

@@ -0,0 +1,140 @@
+// 代码预览组件
+
+import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
+import { oneLight, vscDarkPlus } from 'react-syntax-highlighter/dist/esm/styles/prism';
+import { memo, useEffect, useState } from 'react';
+import { useI18n } from '../i18n';
+
+interface CodeViewProps {
+  code: string;
+  editable?: boolean;
+  onChange?: (value: string) => void;
+  disabled?: boolean;
+}
+
+export const CodeView = memo(function CodeView({ code, editable = false, onChange, disabled = false }: CodeViewProps) {
+  const { t } = useI18n();
+  const [copied, setCopied] = useState(false);
+  const [isEditing, setIsEditing] = useState(false);
+  const [isDark, setIsDark] = useState(
+    typeof document !== 'undefined' && document.documentElement.classList.contains('dark')
+  );
+
+  useEffect(() => {
+    if (typeof document === 'undefined') {
+      return;
+    }
+
+    const updateThemeState = () => {
+      setIsDark(document.documentElement.classList.contains('dark'));
+    };
+
+    updateThemeState();
+
+    const observer = new MutationObserver(updateThemeState);
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['class']
+    });
+
+    return () => observer.disconnect();
+  }, []);
+
+  const handleCopy = async () => {
+    await navigator.clipboard.writeText(code);
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+  };
+
+  const textareaClassName = [
+    'w-full h-full resize-none bg-transparent p-4 text-[0.75rem] leading-relaxed overflow-auto',
+    'font-mono text-text-primary/90 focus:outline-none',
+    disabled ? 'opacity-60 cursor-not-allowed' : ''
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <div className="h-full flex flex-col bg-bg-secondary/30 rounded-2xl overflow-hidden">
+      {/* 顶部工具栏 */}
+      <div className="flex items-center justify-between px-4 py-2.5">
+        <h3 className="text-xs font-medium text-text-secondary/80 uppercase tracking-wide">{t('codeView.title')}</h3>
+        <div className="flex items-center gap-3">
+          {editable && (
+            <button
+              onClick={() => setIsEditing((prev) => !prev)}
+            disabled={disabled}
+            className="text-xs text-text-secondary/70 hover:text-accent transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+          >
+              {isEditing ? t('common.preview') : t('common.edit')}
+            </button>
+          )}
+          <button
+            onClick={handleCopy}
+            className="text-xs text-text-secondary/70 hover:text-accent transition-colors flex items-center gap-1.5"
+          >
+            {copied ? (
+              <>
+                <svg className="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
+                </svg>
+                {t('common.copied')}
+              </>
+            ) : (
+              <>
+                <svg className="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z" />
+                </svg>
+                {t('common.copy')}
+              </>
+            )}
+          </button>
+        </div>
+      </div>
+
+      {/* 代码区域 */}
+      <div className="flex-1 overflow-hidden">
+        {editable && isEditing ? (
+          <textarea
+            value={code}
+            onChange={(event) => onChange?.(event.target.value)}
+            className={textareaClassName}
+            disabled={disabled}
+            spellCheck={false}
+          />
+        ) : (
+          <div className="h-full overflow-auto">
+            <SyntaxHighlighter
+              language="python"
+              style={isDark ? vscDarkPlus : oneLight}
+              customStyle={{
+                margin: 0,
+                padding: '1rem',
+                fontSize: '0.75rem',
+                lineHeight: '1.6',
+                minHeight: '100%',
+                width: '100%',
+                boxSizing: 'border-box',
+                fontFamily: 'Monaco, Cascadia Code, Roboto Mono, monospace',
+                background: 'transparent',
+                whiteSpace: 'pre',
+                wordBreak: 'normal',
+                overflow: 'visible'
+              }}
+              codeTagProps={{
+                style: {
+                  fontFamily: 'Monaco, Cascadia Code, Roboto Mono, monospace',
+                  whiteSpace: 'pre',
+                  wordBreak: 'normal'
+                }
+              }}
+              showLineNumbers
+            >
+              {code}
+            </SyntaxHighlighter>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+});

frontend/src/components/CustomSelect.tsx

@@ -0,0 +1,104 @@
+// 自定义下拉选择组件 - MD3 风格
+
+import { useState, useRef, useEffect } from 'react';
+
+export interface SelectOption<T = string> {
+  value: T;
+  label: string;
+}
+
+interface CustomSelectProps<T = string> {
+  options: SelectOption<T>[];
+  value: T;
+  onChange: (value: T) => void;
+  label: string;
+  className?: string;
+  disabled?: boolean;
+}
+
+export function CustomSelect<T = string>({
+  options,
+  value,
+  onChange,
+  label,
+  className = '',
+  disabled = false
+}: CustomSelectProps<T>) {
+  const [isOpen, setIsOpen] = useState(false);
+  const dropdownRef = useRef<HTMLDivElement>(null);
+
+  const selectedOption = options.find(opt => {
+    if (typeof opt.value === 'number' && typeof value === 'number') {
+      return opt.value === value;
+    }
+    return opt.value === value;
+  });
+
+  // 点击外部关闭下拉菜单
+  useEffect(() => {
+    function handleClickOutside(event: MouseEvent) {
+      if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
+        setIsOpen(false);
+      }
+    }
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => document.removeEventListener('mousedown', handleClickOutside);
+  }, []);
+
+  return (
+    <div className={`relative ${className}`} ref={dropdownRef}>
+      <label className="absolute left-3 -top-2 px-1.5 bg-bg-secondary text-xs font-medium text-text-secondary">
+        {label}
+      </label>
+
+      {/* 触发按钮 */}
+      <button
+        type="button"
+        onClick={() => !disabled && setIsOpen(!isOpen)}
+        disabled={disabled}
+        className="w-full px-4 py-3.5 pr-10 bg-bg-secondary/50 rounded-2xl text-left text-text-primary focus:outline-none focus:ring-2 focus:ring-accent/20 focus:bg-bg-secondary/70 transition-all cursor-pointer disabled:opacity-50 disabled:cursor-not-allowed hover:bg-bg-secondary/60"
+      >
+        <span>{selectedOption?.label}</span>
+      </button>
+
+      {/* 下拉箭头 */}
+      <svg
+        className={`absolute right-4 top-1/2 -translate-y-1/2 w-5 h-5 text-text-secondary pointer-events-none transition-transform duration-200 ${
+          isOpen ? 'rotate-180' : ''
+        }`}
+        fill="none"
+        stroke="currentColor"
+        viewBox="0 0 24 24"
+      >
+        <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 9l-7 7-7-7" />
+      </svg>
+
+      {/* 下拉菜单 */}
+      {isOpen && (
+        <div className="absolute top-full left-0 right-0 mt-2 bg-bg-secondary rounded-2xl shadow-xl shadow-black/10 overflow-hidden z-50 animate-in fade-in slide-in-from-top-1 duration-200">
+          {options.map((option) => {
+            const isSelected = typeof option.value === 'number' && typeof value === 'number'
+              ? option.value === value
+              : option.value === value;
+
+            return (
+              <button
+                key={String(option.value)}
+                type="button"
+                onClick={() => {
+                  onChange(option.value);
+                  setIsOpen(false);
+                }}
+                className={`w-full px-4 py-3.5 text-left transition-colors hover:bg-bg-secondary/70 ${
+                  isSelected ? 'bg-bg-secondary/50' : ''
+                }`}
+              >
+                <span className="text-text-primary">{option.label}</span>
+              </button>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}

frontend/src/components/DonationModal.tsx

@@ -0,0 +1,117 @@
+// 支持作者对话框组件
+
+import { useState } from 'react';
+import { useI18n } from '../i18n';
+import { useModalTransition } from '../hooks/useModalTransition';
+
+interface DonationModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+}
+
+const WECHAT_QR_URL = 'https://github.com/user-attachments/assets/09fd8c5f-9644-4c02-97c1-61f10b0fdd1f';
+const AFDIAN_URL = 'https://afdian.com/a/wingflow/plan';
+
+export function DonationModal({ isOpen, onClose }: DonationModalProps) {
+  const { t } = useI18n();
+  const { shouldRender, isExiting } = useModalTransition(isOpen);
+  const [showQR, setShowQR] = useState(false);
+  const [imgLoaded, setImgLoaded] = useState(false);
+
+  if (!shouldRender) return null;
+
+  return (
+    <div className="fixed inset-0 z-[120] flex items-center justify-center p-4">
+      {/* 遮罩层 */}
+      <div 
+        className={`absolute inset-0 bg-bg-primary/60 backdrop-blur-md transition-opacity duration-300 ${
+          isExiting ? 'opacity-0' : 'animate-overlay-wash-in'
+        }`} 
+        onClick={onClose} 
+      />
+
+      {/* 模态框内容 */}
+      <div className={`relative bg-bg-secondary rounded-[2.5rem] p-10 max-w-sm w-full shadow-2xl border border-border/5 overflow-hidden ${
+        isExiting ? 'animate-fade-out-soft' : 'animate-fade-in-soft'
+      }`}>
+        {!showQR ? (
+          <div className="flex flex-col">
+            <div className="flex items-center gap-3 mb-6">
+              <div className="p-2.5 rounded-2xl bg-accent-rgb/5 text-accent-rgb/60">
+                <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M17 8h1a1 1 0 011 1v5a1 1 0 01-1 1h-1m-6.854 8.03l-1.772-1.603a4.5 4.5 0 00-6.267 0L6.97 21h8.13l-.648-.57a4.5 4.5 0 00-6.267 0l-.94.85M14.5 9l-1-4h-5l-1 4h7z" />
+                </svg>
+              </div>
+              <h2 className="text-xl font-medium text-text-primary tracking-tight">{t('donation.title')}</h2>
+            </div>
+
+            <p className="text-text-secondary text-[15px] mb-10 leading-8 font-light">
+              {t('donation.description')}
+            </p>
+
+            <div className="flex flex-col gap-3">
+              <button
+                onClick={() => setShowQR(true)}
+                className="w-full py-4 text-sm text-bg-primary bg-accent hover:bg-accent/90 rounded-2xl transition-all active:scale-95 font-medium shadow-md shadow-accent/10"
+              >
+                {t('donation.support')}
+              </button>
+              <button
+                onClick={onClose}
+                className="w-full py-4 text-sm text-text-secondary hover:text-text-primary bg-bg-primary/50 hover:bg-bg-tertiary rounded-2xl transition-all active:scale-95"
+              >
+                {t('donation.maybeLater')}
+              </button>
+            </div>
+          </div>
+        ) : (
+          <div className="flex flex-col items-center animate-fade-in">
+            <div className="w-full flex items-center justify-between mb-8">
+               <button 
+                 onClick={() => setShowQR(false)}
+                 className="p-2 -ml-2 text-text-secondary/50 hover:text-text-primary transition-colors"
+               >
+                 <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                   <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M15 19l-7-7 7-7" />
+                 </svg>
+               </button>
+               <span className="text-[11px] uppercase tracking-[0.3em] text-text-secondary/40 font-medium">
+                 {t('donation.wechatTitle')}
+               </span>
+               <div className="w-9" />
+            </div>
+
+            <div className="relative w-56 h-56 mb-8 rounded-3xl bg-bg-primary/50 border border-border/5 flex items-center justify-center overflow-hidden shadow-inner group">
+              {!imgLoaded && (
+                <div className="absolute inset-0 flex items-center justify-center">
+                  <div className="w-6 h-6 border-2 border-accent-rgb/20 border-t-accent-rgb/60 rounded-full animate-spin" />
+                </div>
+              )}
+              <img 
+                src={WECHAT_QR_URL} 
+                alt="WeChat Pay"
+                className={`w-full h-full object-contain transition-all duration-700 p-4 ${
+                  imgLoaded ? 'opacity-100 scale-100' : 'opacity-0 scale-95 blur-sm'
+                }`}
+                onLoad={() => setImgLoaded(true)}
+              />
+            </div>
+
+            <p className="text-[13px] text-text-secondary/70 font-light mb-10">
+              {t('donation.wechatHint')}
+            </p>
+
+            <a
+              href={AFDIAN_URL}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="text-[11px] text-text-secondary/30 hover:text-accent-rgb underline underline-offset-4 transition-colors"
+            >
+              {t('donation.afdianLink')}
+            </a>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

frontend/src/components/ExampleButtons.tsx

@@ -0,0 +1,84 @@
+// 自动滚动示例组件
+
+import { useState, useEffect } from 'react';
+
+interface ExampleButtonsProps {
+  onSelect: (example: string) => void;
+  disabled: boolean;
+}
+
+/** 示例列表 */
+const EXAMPLES = [
+  '演示勾股定理，带动画三角形和正方形',
+  '可视化二次函数及其属性并带动画',
+  '在单位圆上展示正弦和余弦的关系，带动画角度',
+  '创建 3D 曲面图，展示 z = x² + y²',
+  '计算并可视化半径为 r 的球体体积',
+  '展示如何用动画求立方体的表面积',
+  '将导数可视化切线斜率',
+  '用动画展示曲线下面积的工作原理',
+  '用动画变换演示矩阵运算',
+  '可视化 2x2 矩阵的特征值和特征向量',
+  '展示复数乘法使用旋转和缩放',
+  '动画展示简单微分方程的解',
+];
+
+export function ExampleButtons({ onSelect, disabled }: ExampleButtonsProps) {
+  const [currentIndex, setCurrentIndex] = useState(0);
+
+  useEffect(() => {
+    if (disabled) return;
+
+    const interval = setInterval(() => {
+      setCurrentIndex((prev) => (prev + 1) % EXAMPLES.length);
+    }, 3000);
+
+    return () => clearInterval(interval);
+  }, [disabled]);
+
+  return (
+    <div className="w-full">
+      {/* 自动滚动示例卡片 */}
+      <div className="relative overflow-hidden rounded-2xl bg-bg-secondary/40">
+        {/* 当前显示的示例 */}
+        <div className="p-5 sm:p-6 min-h-[80px] flex items-center justify-center transition-all duration-500">
+          <button
+            type="button"
+            onClick={() => onSelect(EXAMPLES[currentIndex])}
+            disabled={disabled}
+            className="text-center text-sm sm:text-base text-text-primary/90 hover:text-text-primary transition-all disabled:opacity-50 disabled:cursor-not-allowed active:scale-[0.98]"
+          >
+            {EXAMPLES[currentIndex]}
+          </button>
+        </div>
+
+        {/* 左右导航按钮 */}
+        <div className="absolute top-1/2 left-3 -translate-y-1/2">
+          <button
+            type="button"
+            onClick={() => setCurrentIndex((prev) => (prev - 1 + EXAMPLES.length) % EXAMPLES.length)}
+            disabled={disabled}
+            className="w-8 h-8 flex items-center justify-center rounded-full bg-bg-secondary text-text-secondary hover:text-accent hover:bg-bg-secondary/80 disabled:opacity-30 disabled:cursor-not-allowed transition-all"
+          >
+            <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M15 19l-7-7 7-7" />
+            </svg>
+          </button>
+        </div>
+
+        <div className="absolute top-1/2 right-3 -translate-y-1/2">
+          <button
+            type="button"
+            onClick={() => setCurrentIndex((prev) => (prev + 1) % EXAMPLES.length)}
+            disabled={disabled}
+            className="w-8 h-8 flex items-center justify-center rounded-full bg-bg-secondary text-text-secondary hover:text-accent hover:bg-bg-secondary/80 disabled:opacity-30 disabled:cursor-not-allowed transition-all"
+          >
+            <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 5l7 7-7 7" />
+            </svg>
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

frontend/src/components/HistoryPanel.tsx

@@ -0,0 +1,206 @@
+/**
+ * 历史记录面板 - 工作空间内嵌模块
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { getHistoryList, deleteHistoryRecord } from '../lib/api';
+import type { HistoryRecord } from '../types/api';
+import { useI18n } from '../i18n';
+
+interface HistoryPanelProps {
+  isActive: boolean;
+  onReusePrompt?: (prompt: string) => void;
+}
+
+export function HistoryPanel({ isActive, onReusePrompt }: HistoryPanelProps) {
+  const { t } = useI18n();
+  const [records, setRecords] = useState<HistoryRecord[]>([]);
+  const [page, setPage] = useState(1);
+  const [hasMore, setHasMore] = useState(true);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [expandedId, setExpandedId] = useState<string | null>(null);
+  const [confirmDeleteId, setConfirmDeleteId] = useState<string | null>(null);
+  const loadedRef = useRef(false);
+
+  const loadHistory = useCallback(async (pageNum: number, append = false) => {
+    setLoading(true);
+    setError(null);
+    try {
+      const data = await getHistoryList(pageNum, 12);
+      setRecords(prev => append ? [...prev, ...data.records] : data.records);
+      setHasMore(data.hasMore);
+      setPage(pageNum);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : t('history.loadFailed'));
+    } finally {
+      setLoading(false);
+    }
+  }, [t]);
+
+  useEffect(() => {
+    if (isActive && !loadedRef.current) {
+      loadedRef.current = true;
+      void loadHistory(1);
+    }
+  }, [isActive, loadHistory]);
+
+  const handleLoadMore = () => {
+    if (!loading && hasMore) {
+      void loadHistory(page + 1, true);
+    }
+  };
+
+  const handleDelete = async (id: string) => {
+    try {
+      await deleteHistoryRecord(id);
+      setRecords(prev => prev.filter(r => r.id !== id));
+      setConfirmDeleteId(null);
+    } catch {
+      // silently fail
+    }
+  };
+
+  const formatDate = (dateStr: string) => {
+    const date = new Date(dateStr);
+    return date.toLocaleDateString(undefined, {
+      month: 'short',
+      day: 'numeric',
+      hour: '2-digit',
+      minute: '2-digit',
+    });
+  };
+
+  return (
+    <div className="animate-fade-in">
+      <h2 className="text-2xl font-light text-text-primary mb-8">{t('history.title')}</h2>
+
+      {error && (
+        <div className="rounded-2xl bg-red-50/80 dark:bg-red-900/20 border border-red-200/50 dark:border-red-700/40 p-4 text-sm text-red-600 dark:text-red-300 mb-6">
+          {error}
+        </div>
+      )}
+
+      {!loading && records.length === 0 && !error && (
+        <div className="flex flex-col items-center justify-center py-24 text-center">
+          <svg className="w-16 h-16 text-text-secondary/20 mb-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z" />
+          </svg>
+          <p className="text-text-secondary/50 text-sm">{t('history.empty')}</p>
+          <p className="text-text-secondary/30 text-xs mt-1">{t('history.emptyHint')}</p>
+        </div>
+      )}
+
+      {records.length > 0 && (
+        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-5">
+          {records.map(record => (
+            <div
+              key={record.id}
+              className="group rounded-2xl bg-bg-secondary/25 border border-bg-tertiary/30 overflow-hidden hover:border-bg-tertiary/60 transition-colors"
+            >
+              {/* 卡片头部：状态 + 时间 */}
+              <div className="px-4 pt-4 pb-3 flex items-center justify-between">
+                <div className="flex items-center gap-2">
+                  <span className={`w-2 h-2 rounded-full ${record.status === 'completed' ? 'bg-green-400/80' : 'bg-red-400/80'}`} />
+                  <span className="text-[11px] text-text-secondary/60">{formatDate(record.created_at)}</span>
+                </div>
+                <div className="flex items-center gap-1">
+                  <span className="text-[10px] uppercase tracking-wider text-text-secondary/40 bg-bg-tertiary/30 px-2 py-0.5 rounded">
+                    {record.output_mode}
+                  </span>
+                  <span className="text-[10px] uppercase tracking-wider text-text-secondary/40 bg-bg-tertiary/30 px-2 py-0.5 rounded">
+                    {record.quality}
+                  </span>
+                </div>
+              </div>
+
+              {/* 提示词预览 */}
+              <div className="px-4 pb-3">
+                <p className="text-sm text-text-primary/80 line-clamp-3 leading-relaxed">{record.prompt}</p>
+              </div>
+
+              {/* 代码展开区 */}
+              {expandedId === record.id && record.code && (
+                <div className="px-4 pb-3">
+                  <pre className="text-[11px] text-text-secondary/70 bg-bg-primary/50 rounded-lg p-3 max-h-48 overflow-auto font-mono leading-relaxed">
+                    {record.code}
+                  </pre>
+                </div>
+              )}
+
+              {/* 操作栏 */}
+              <div className="px-4 py-3 border-t border-bg-tertiary/20 flex items-center gap-2 opacity-0 group-hover:opacity-100 transition-opacity">
+                {record.code && (
+                  <button
+                    onClick={() => setExpandedId(expandedId === record.id ? null : record.id)}
+                    className="text-[11px] text-text-secondary/60 hover:text-text-primary px-2 py-1 rounded hover:bg-bg-tertiary/30 transition-colors"
+                  >
+                    {t('history.viewCode')}
+                  </button>
+                )}
+                {onReusePrompt && (
+                  <button
+                    onClick={() => onReusePrompt(record.prompt)}
+                    className="text-[11px] text-text-secondary/60 hover:text-text-primary px-2 py-1 rounded hover:bg-bg-tertiary/30 transition-colors"
+                  >
+                    {t('history.reuse')}
+                  </button>
+                )}
+                <div className="flex-1" />
+                {confirmDeleteId === record.id ? (
+                  <div className="flex items-center gap-1">
+                    <button
+                      onClick={() => void handleDelete(record.id)}
+                      className="text-[11px] text-red-400 hover:text-red-300 px-2 py-1 rounded hover:bg-red-500/10 transition-colors"
+                    >
+                      {t('common.confirm')}
+                    </button>
+                    <button
+                      onClick={() => setConfirmDeleteId(null)}
+                      className="text-[11px] text-text-secondary/60 hover:text-text-primary px-2 py-1 rounded hover:bg-bg-tertiary/30 transition-colors"
+                    >
+                      {t('common.cancel')}
+                    </button>
+                  </div>
+                ) : (
+                  <button
+                    onClick={() => setConfirmDeleteId(record.id)}
+                    className="text-[11px] text-text-secondary/40 hover:text-red-400 px-2 py-1 rounded hover:bg-red-500/10 transition-colors"
+                  >
+                    {t('history.delete')}
+                  </button>
+                )}
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+
+      {/* 加载更多 */}
+      {records.length > 0 && (
+        <div className="flex justify-center mt-8">
+          {hasMore ? (
+            <button
+              onClick={handleLoadMore}
+              disabled={loading}
+              className="px-6 py-2 text-xs text-text-secondary/70 hover:text-text-primary bg-bg-secondary/30 hover:bg-bg-secondary/50 rounded-lg transition-colors disabled:opacity-50"
+            >
+              {loading ? t('common.loading') : t('history.loadMore')}
+            </button>
+          ) : (
+            <span className="text-xs text-text-secondary/30">{t('history.noMore')}</span>
+          )}
+        </div>
+      )}
+
+      {/* 初始加载 */}
+      {loading && records.length === 0 && (
+        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-5 animate-pulse">
+          {Array.from({ length: 6 }).map((_, i) => (
+            <div key={i} className="rounded-2xl bg-bg-secondary/25 border border-bg-tertiary/30 h-40" />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

frontend/src/components/ImageInputModeModal.tsx

@@ -0,0 +1,84 @@
+import { useI18n } from '../i18n';
+import { useModalTransition } from '../hooks/useModalTransition';
+
+interface ImageInputModeModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  onImport: () => void;
+  onDraw: () => void;
+}
+
+export function ImageInputModeModal({ isOpen, onClose, onImport, onDraw }: ImageInputModeModalProps) {
+  const { t } = useI18n();
+  const { shouldRender, isExiting } = useModalTransition(isOpen);
+
+  if (!shouldRender) {
+    return null;
+  }
+
+  return (
+    <div className="fixed inset-0 z-[120] flex items-center justify-center p-4">
+      <div
+        className={`absolute inset-0 bg-bg-primary/60 backdrop-blur-md transition-opacity duration-300 ${
+          isExiting ? 'opacity-0' : 'animate-overlay-wash-in'
+        }`}
+        onClick={onClose}
+      />
+
+      <div
+        className={`relative w-full max-w-sm bg-bg-secondary rounded-[2.25rem] p-7 shadow-2xl border border-border/5 ${
+          isExiting ? 'animate-fade-out-soft' : 'animate-fade-in-soft'
+        }`}
+      >
+        <div className="flex items-center mb-6">
+          <button
+            type="button"
+            onClick={onClose}
+            className="inline-flex items-center gap-2 px-3 py-2 text-sm text-text-secondary hover:text-text-primary hover:bg-bg-primary/50 rounded-2xl transition-all"
+          >
+            <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M15 19l-7-7 7-7" />
+            </svg>
+            {t('canvasMode.back')}
+          </button>
+        </div>
+
+        <div className="mb-6">
+          <div className="flex items-center gap-3 mb-2">
+            <div className="w-2 h-2 rounded-full bg-accent-rgb/40 animate-pulse" />
+            <h2 className="text-lg font-medium text-text-primary tracking-tight">{t('canvasMode.title')}</h2>
+          </div>
+        </div>
+
+        <div className="grid grid-cols-2 gap-3">
+          <button
+            type="button"
+            onClick={onImport}
+            className="group flex flex-col items-center justify-center rounded-2xl bg-bg-primary/45 hover:bg-bg-primary/65 px-4 py-4 text-center transition-all"
+          >
+            <div className="mb-2 inline-flex h-9 w-9 items-center justify-center rounded-xl bg-accent/10 text-accent">
+              <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 16V4m0 0l-4 4m4-4l4 4M4 20h16" />
+              </svg>
+            </div>
+            <div className="text-sm font-medium text-text-primary">{t('canvasMode.import')}</div>
+          </button>
+
+          <button
+            type="button"
+            onClick={onDraw}
+            className="group flex flex-col items-center justify-center rounded-2xl bg-bg-primary/45 hover:bg-bg-primary/65 px-4 py-4 text-center transition-all"
+          >
+            <div className="mb-2 inline-flex h-9 w-9 items-center justify-center rounded-xl bg-accent/10 text-accent">
+              <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 20h9" />
+                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M16.5 3.5a2.121 2.121 0 013 3L7 19l-4 1 1-4 12.5-12.5z" />
+              </svg>
+            </div>
+            <div className="text-sm font-medium text-text-primary">{t('canvasMode.draw')}</div>
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

frontend/src/components/ImagePreview.tsx

@@ -0,0 +1,123 @@
+import { memo, useState, type MouseEvent as ReactMouseEvent } from 'react';
+import { ImageLightbox } from './image-preview/lightbox';
+import { useImageDownload } from './image-preview/use-image-download';
+import { useI18n } from '../i18n';
+
+interface ImagePreviewProps {
+  imageUrls: string[];
+}
+
+export const ImagePreview = memo(function ImagePreview({ imageUrls }: ImagePreviewProps) {
+  const { t } = useI18n();
+  const [activeIndex, setActiveIndex] = useState(0);
+  const [isLightboxOpen, setIsLightboxOpen] = useState(false);
+  const [zoom, setZoom] = useState(1);
+  const { isDownloadingSingle, isDownloadingAll, handleDownloadAll, handleDownloadSingle } = useImageDownload(imageUrls);
+  const safeActiveIndex = Math.min(activeIndex, Math.max(0, imageUrls.length - 1));
+  const activeImage = imageUrls[safeActiveIndex];
+  const hasImages = imageUrls.length > 0;
+
+  return (
+    <div className="h-full flex flex-col bg-bg-secondary/30 rounded-2xl overflow-hidden">
+      <div className="flex items-center justify-between px-4 py-2.5">
+        <h3 className="text-xs font-medium text-text-secondary/80 uppercase tracking-wide">{t('image.title')}</h3>
+        <div className="flex items-center gap-3">
+          <button
+            onClick={() => setIsLightboxOpen(true)}
+            disabled={!hasImages}
+            className="text-xs text-text-secondary/70 hover:text-accent transition-colors flex items-center gap-1.5 disabled:opacity-40 disabled:cursor-not-allowed"
+          >
+            <svg className="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M15 3h6m0 0v6m0-6l-7 7M9 21H3m0 0v-6m0 6l7-7" />
+            </svg>
+            {t('image.openLightbox')}
+          </button>
+          <button
+            onClick={() => void handleDownloadSingle(activeImage, safeActiveIndex)}
+            disabled={!hasImages || isDownloadingSingle || isDownloadingAll}
+            className="text-xs text-text-secondary/70 hover:text-accent transition-colors flex items-center gap-1.5 disabled:opacity-40 disabled:cursor-not-allowed"
+          >
+            <svg className="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 16v1a3 3 0 003 3h10a3 3 0 003-3v-1m-4-4l-4 4m0 0l-4-4m4 4V4" />
+            </svg>
+            {isDownloadingSingle ? t('image.downloading') : t('common.download')}
+          </button>
+          <button
+            onClick={() => void handleDownloadAll(imageUrls)}
+            disabled={!hasImages || isDownloadingAll || isDownloadingSingle}
+            className="text-xs text-text-secondary/70 hover:text-accent transition-colors flex items-center gap-1.5 disabled:opacity-40 disabled:cursor-not-allowed"
+          >
+            <svg className="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 16v1a3 3 0 003 3h10a3 3 0 003-3v-1m-4-4l-4 4m0 0l-4-4m4 4V4" />
+            </svg>
+            {isDownloadingAll ? t('image.zipping') : t('image.downloadAll')}
+          </button>
+        </div>
+      </div>
+
+      <div className="flex-1 bg-black/90 flex items-center justify-center">
+        {activeImage ? (
+          <div
+            role="button"
+            tabIndex={0}
+            onClick={(event: ReactMouseEvent<HTMLDivElement>) => {
+              if (event.button !== 0) {
+                return;
+              }
+              setIsLightboxOpen(true);
+            }}
+            onKeyDown={(event) => {
+              if (event.key === 'Enter' || event.key === ' ') {
+                event.preventDefault();
+                setIsLightboxOpen(true);
+              }
+            }}
+            className="w-full h-full cursor-zoom-in"
+            title={t('image.openTitle')}
+          >
+            <img src={activeImage} alt={t('image.itemAlt', { index: safeActiveIndex + 1 })} className="w-full h-full object-contain" />
+          </div>
+        ) : (
+          <p className="text-xs text-text-secondary/60">{t('image.empty')}</p>
+        )}
+      </div>
+
+      {imageUrls.length > 1 && (
+        <div className="px-3 py-2 bg-bg-secondary/40">
+          <div className="flex gap-2 overflow-x-auto">
+            {imageUrls.map((url, index) => (
+              <button
+                key={`${url}-${index}`}
+                type="button"
+                onClick={() => setActiveIndex(index)}
+                className={`shrink-0 rounded-md overflow-hidden border transition-all ${
+                  index === safeActiveIndex ? 'border-accent' : 'border-border/50 opacity-80 hover:opacity-100'
+                }`}
+              >
+                <img
+                  src={url}
+                  alt={t('image.thumbAlt', { index: index + 1 })}
+                  className="w-16 h-12 object-cover"
+                />
+              </button>
+            ))}
+          </div>
+        </div>
+      )}
+
+      <ImageLightbox
+        isOpen={isLightboxOpen}
+        activeImage={activeImage}
+        activeIndex={safeActiveIndex}
+        total={imageUrls.length}
+        zoom={zoom}
+        maxZoom={3}
+        onZoomChange={setZoom}
+        onClose={() => {
+          setIsLightboxOpen(false);
+          setZoom(1);
+        }}
+      />
+    </div>
+  );
+});

frontend/src/components/InputForm.tsx

@@ -0,0 +1,254 @@
+// 输入表单组件 - MD3 风格
+
+import type { StudioKind } from '../studio/protocol/studio-agent-types';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type { OutputMode, Quality, ReferenceImage } from '../types/api';
+import { loadSettings } from '../lib/settings';
+import { FormToolbar } from './input-form/form-toolbar';
+import { ReferenceImageList } from './input-form/reference-image-list';
+import { useReferenceImages } from './input-form/use-reference-images';
+import { useI18n } from '../i18n';
+import { ImageInputModeModal } from './ImageInputModeModal';
+import { CanvasWorkspaceModal } from './canvas/CanvasWorkspaceModal';
+
+interface InputFormProps {
+  concept: string;
+  onConceptChange: (value: string) => void;
+  onSecretStudioOpen?: (studioKind: StudioKind) => void;
+  onSubmit: (data: {
+    concept: string;
+    quality: Quality;
+    outputMode: OutputMode;
+    referenceImages?: ReferenceImage[];
+  }) => void;
+  loading: boolean;
+}
+
+const STUDIO_KEYWORDS: Record<string, StudioKind> = {
+  hellomanim: 'manim',
+  helloplot: 'plot',
+};
+const TRIGGER_DELAY_MS = 1200;
+
+export function InputForm({ concept, onConceptChange, onSecretStudioOpen, onSubmit, loading }: InputFormProps) {
+  const { t } = useI18n();
+  const [localError, setLocalError] = useState<string | null>(null);
+  const [quality, setQuality] = useState<Quality>(loadSettings().video.quality);
+  const [outputMode, setOutputMode] = useState<OutputMode>('video');
+  const [isRecognizing, setIsRecognizing] = useState(false);
+  const [isImageModeOpen, setIsImageModeOpen] = useState(false);
+  const [isCanvasOpen, setIsCanvasOpen] = useState(false);
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+  const studioKeywordTriggeredRef = useRef(false);
+  const triggerTimerRef = useRef<number | null>(null);
+
+  const {
+    images,
+    imageError,
+    isDragging,
+    fileInputRef,
+    addImages,
+    appendImages,
+    removeImage,
+    handleDrop,
+    handleDragOver,
+    handleDragEnter,
+    handleDragLeave,
+  } = useReferenceImages();
+
+  const derivedError = useMemo(() => {
+    const trimmed = concept.trim();
+    if (!trimmed) {
+      return null;
+    }
+    if (trimmed.length < 5) {
+      return t('form.error.minLengthShort');
+    }
+    return null;
+  }, [concept, t]);
+
+  const handleSubmit = useCallback(() => {
+    if (concept.trim().length < 5) {
+      setLocalError(t('form.error.minLength'));
+      textareaRef.current?.focus();
+      return;
+    }
+
+    setLocalError(null);
+    onSubmit({
+      concept: concept.trim(),
+      quality,
+      outputMode,
+      referenceImages: images.length > 0 ? images : undefined,
+    });
+  }, [concept, quality, outputMode, images, onSubmit, t]);
+
+  const handleTextareaKeyDown = (event: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (event.key === 'Enter' && event.shiftKey && !loading) {
+      event.preventDefault();
+      handleSubmit();
+    }
+  };
+
+  // 组件卸载时清理定时器
+  useEffect(() => {
+    return () => {
+      if (triggerTimerRef.current) clearTimeout(triggerTimerRef.current);
+    };
+  }, []);
+
+  const handleFormSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    handleSubmit();
+  };
+
+  const handleOpenImageMode = useCallback(() => {
+    setIsImageModeOpen(true);
+  }, []);
+
+  const handleCloseImageMode = useCallback(() => {
+    setIsImageModeOpen(false);
+  }, []);
+
+  const handleImportImages = useCallback(() => {
+    setIsImageModeOpen(false);
+    fileInputRef.current?.click();
+  }, [fileInputRef]);
+
+  const handleDrawMode = useCallback(() => {
+    setIsImageModeOpen(false);
+    setIsCanvasOpen(true);
+  }, []);
+
+  const handleCanvasComplete = useCallback((nextImages: ReferenceImage[]) => {
+    appendImages(nextImages);
+    setIsCanvasOpen(false);
+  }, [appendImages]);
+
+  const handleConceptChange = (value: string) => {
+    onConceptChange(value);
+
+    const normalizedConcept = value.trim().toLowerCase();
+    const matchedStudioKind = STUDIO_KEYWORDS[normalizedConcept];
+    if (matchedStudioKind && !loading) {
+      if (!studioKeywordTriggeredRef.current) {
+        studioKeywordTriggeredRef.current = true;
+        setIsRecognizing(true);
+        triggerTimerRef.current = window.setTimeout(() => {
+          onSecretStudioOpen?.(matchedStudioKind);
+          setIsRecognizing(false);
+        }, TRIGGER_DELAY_MS);
+      }
+      return;
+    }
+
+    if (studioKeywordTriggeredRef.current && !matchedStudioKind) {
+      studioKeywordTriggeredRef.current = false;
+      setIsRecognizing(false);
+      if (triggerTimerRef.current) {
+        clearTimeout(triggerTimerRef.current);
+        triggerTimerRef.current = null;
+      }
+    }
+
+    setLocalError(null);
+  };
+
+  return (
+    <div className="w-full max-w-2xl mx-auto">
+      <form onSubmit={handleFormSubmit} className="space-y-6">
+        <div
+          className={`relative transition-all duration-200 ${isDragging ? 'scale-[1.02]' : ''}`}
+          onDrop={handleDrop}
+          onDragOver={handleDragOver}
+          onDragEnter={handleDragEnter}
+          onDragLeave={handleDragLeave}
+        >
+          <label
+            htmlFor="concept"
+            className={`absolute left-4 -top-2.5 px-2 bg-bg-primary text-xs font-medium transition-all z-10 ${
+              isDragging || isRecognizing ? 'text-accent' : (localError || derivedError) ? 'text-red-500' : 'text-text-secondary'
+            }`}
+          >
+            {isDragging ? t('form.label.dragging') : isRecognizing ? '暗号确认中...' : localError || derivedError || t('form.label.default')}
+          </label>
+          <textarea
+            ref={textareaRef}
+            id="concept"
+            name="concept"
+            rows={4}
+            placeholder={t('form.placeholder')}
+            disabled={loading || isRecognizing}
+            value={concept}
+            onChange={(e) => handleConceptChange(e.target.value)}
+            onKeyDown={handleTextareaKeyDown}
+            className={`w-full px-4 py-4 bg-bg-secondary/50 rounded-2xl text-text-primary placeholder-text-secondary/40 focus:outline-none focus:ring-2 transition-all resize-none ${
+              isDragging
+                ? 'ring-2 ring-accent/50 bg-accent/5 border-2 border-dashed border-accent/30'
+                : isRecognizing
+                  ? 'ring-2 ring-accent/40 bg-accent/[0.03] animate-pulse'
+                  : (localError || derivedError)
+                    ? 'focus:ring-red-500/20 bg-red-50/50 dark:bg-red-900/10'
+                    : 'focus:ring-accent/20 focus:bg-bg-secondary/70'
+            }`}
+          />
+        </div>
+
+        <FormToolbar
+          loading={loading || isRecognizing}
+          quality={quality}
+          outputMode={outputMode}
+          imageCount={images.length}
+          fileInputRef={fileInputRef}
+          onChangeQuality={setQuality}
+          onChangeOutputMode={setOutputMode}
+          onOpenImageMode={handleOpenImageMode}
+          onUploadFiles={addImages}
+        />
+
+        <ReferenceImageList images={images} loading={loading || isRecognizing} onRemove={removeImage} />
+
+        {imageError && <p className="text-xs text-red-500">{imageError}</p>}
+
+        <div className="flex justify-center pt-4">
+          <button
+            type="submit"
+            disabled={loading || isRecognizing || concept.trim().length < 5}
+            className="px-12 py-3.5 bg-accent/85 text-white font-medium rounded-full shadow-sm shadow-accent/5 transition-colors duration-200 disabled:opacity-50 disabled:cursor-not-allowed hover:bg-accent/90 active:bg-accent-hover/90"
+          >
+            <span className="flex items-center gap-2">
+              {loading || isRecognizing ? (
+                <>
+                  <svg className="animate-spin w-4 h-4" fill="none" viewBox="0 0 24 24">
+                    <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+                    <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
+                  </svg>
+                  {isRecognizing ? '正在启动...' : t('form.submitting')}
+                </>
+              ) : (
+                t('form.submit.plan')
+              )}
+            </span>
+          </button>
+        </div>
+
+        <p className="text-center text-xs text-text-secondary/50">
+          {t('form.shortcutPrefix')} <kbd className="px-1.5 py-0.5 bg-bg-secondary/50 rounded text-[10px]">Shift</kbd> + <kbd className="px-1.5 py-0.5 bg-bg-secondary/50 rounded text-[10px]">Enter</kbd> {t('form.shortcutSuffix')}
+        </p>
+      </form>
+
+      <ImageInputModeModal
+        isOpen={isImageModeOpen}
+        onClose={handleCloseImageMode}
+        onImport={handleImportImages}
+        onDraw={handleDrawMode}
+      />
+
+      <CanvasWorkspaceModal
+        isOpen={isCanvasOpen}
+        onClose={() => setIsCanvasOpen(false)}
+        onComplete={handleCanvasComplete}
+      />
+    </div>
+  );
+}

frontend/src/components/LoadingSpinner.tsx

@@ -0,0 +1,255 @@
+// 加载动画组件 - 大猫头 + 波浪猫爪
+
+import { useEffect, useState, useRef } from 'react';
+import { useI18n } from '../i18n';
+
+type Stage = 'analyzing' | 'generating' | 'refining' | 'rendering' | 'still-rendering';
+
+interface LoadingSpinnerProps {
+  stage: Stage;
+  jobId?: string;
+  submittedAt?: string;
+  onCancel?: () => void;
+  onOpenGame?: () => void;
+}
+
+const STAGE_CONFIG = {
+  analyzing:         { key: 'loading.analyzing', start: 0, target: 20 },
+  generating:        { key: 'loading.generating', start: 20, target: 66 },
+  refining:          { key: 'loading.refining', start: 66, target: 85 },
+  rendering:         { key: 'loading.rendering', start: 85, target: 97 },
+  'still-rendering': { key: 'loading.stillRendering', start: 85, target: 97 },
+} as const;
+
+function usePerceivedProgress(stage: Stage): number {
+  const [progress, setProgress] = useState(0);
+  const prevStageRef = useRef(stage);
+  const stageStartProgressRef = useRef(0);
+  const enteredAtRef = useRef<number | null>(null);
+
+  useEffect(() => {
+    if (enteredAtRef.current === null) {
+      enteredAtRef.current = Date.now();
+    }
+
+    if (stage !== prevStageRef.current) {
+      prevStageRef.current = stage;
+      enteredAtRef.current = Date.now();
+      stageStartProgressRef.current = Math.max(stageStartProgressRef.current, progress, STAGE_CONFIG[stage].start);
+    }
+  }, [stage, progress]);
+
+  useEffect(() => {
+    const id = setInterval(() => {
+      const enteredAt = enteredAtRef.current ?? Date.now();
+      const elapsed = (Date.now() - enteredAt) / 1000;
+      const { target } = STAGE_CONFIG[stage];
+      const start = Math.max(stageStartProgressRef.current, STAGE_CONFIG[stage].start);
+      const range = Math.max(0, target - start);
+      const quickGain = range * 0.72 * (1 - Math.exp(-elapsed / 5));
+      const comfortGain = elapsed > 10 ? Math.floor((elapsed - 10) / 4) : 0;
+      const next = Math.min(target, start + quickGain + comfortGain);
+      setProgress((current) => Math.max(current, next));
+    }, 120);
+    return () => clearInterval(id);
+  }, [stage]);
+
+  return Math.min(97, progress);
+}
+
+/** 大猫头 SVG - 眼睛灵敏转动 */
+function CatHead() {
+  const [eyeOffset, setEyeOffset] = useState({ x: 0, y: 0 });
+  const containerRef = useRef<SVGSVGElement>(null);
+
+  useEffect(() => {
+    const handleMouseMove = (e: MouseEvent) => {
+      if (!containerRef.current) return;
+      const rect = containerRef.current.getBoundingClientRect();
+      const centerX = rect.left + rect.width / 2;
+      const centerY = rect.top + rect.height / 2;
+      
+      const dx = e.clientX - centerX;
+      const dy = e.clientY - centerY;
+      const dist = Math.sqrt(dx * dx + dy * dy);
+      
+      // 灵敏算法：减小阻尼，增大范围
+      const limit = 6; 
+      const sensitivity = 20; // 越小越灵敏
+      const moveX = (dx / (dist + sensitivity)) * limit;
+      const moveY = (dy / (dist + sensitivity)) * limit;
+      
+      setEyeOffset({ x: moveX, y: moveY });
+    };
+
+    window.addEventListener('mousemove', handleMouseMove);
+    return () => window.removeEventListener('mousemove', handleMouseMove);
+  }, []);
+
+  return (
+    <svg 
+      ref={containerRef}
+      width={100} height={100} viewBox="0 0 140 140" 
+      className="drop-shadow-lg"
+    >
+      <g transform="translate(70, 70)">
+        <path
+          d="M -70 40 C -80 0, -80 -30, -50 -60 L -20 -30 L 20 -30 L 50 -60 C 80 -30, 80 0, 70 40 C 60 70, -60 70, -70 40 Z"
+          fill="#455a64"
+        />
+        <circle cx="-35" cy="-5" r="18" fill="#fff" />
+        <circle cx="35" cy="-5" r="18" fill="#fff" />
+        <circle 
+          cx="-38" cy="-5" r="6" fill="#455a64" 
+          style={{ transform: `translate(${eyeOffset.x}px, ${eyeOffset.y}px)`, transition: 'transform 0.08s ease-out' }}
+        />
+        <circle 
+          cx="32" cy="-5" r="6" fill="#455a64" 
+          style={{ transform: `translate(${eyeOffset.x}px, ${eyeOffset.y}px)`, transition: 'transform 0.08s ease-out' }}
+        />
+      </g>
+    </svg>
+  );
+}
+
+function FloatingCat() {
+  const [y, setY] = useState(0);
+  useEffect(() => {
+    let t = 0;
+    let id: number;
+    const animate = () => {
+      t += 0.02;
+      setY(Math.sin(t) * 5);
+      id = requestAnimationFrame(animate);
+    };
+    id = requestAnimationFrame(animate);
+    return () => cancelAnimationFrame(id);
+  }, []);
+  return <div style={{ transform: `translateY(${y}px)` }}><CatHead /></div>;
+}
+
+function WavingPaw({ index, total }: { index: number; total: number }) {
+  const [scale, setScale] = useState(1);
+  const [y, setY] = useState(0);
+  const [opacity, setOpacity] = useState(0.25);
+
+  useEffect(() => {
+    let t = 0;
+    const phase = (index / total) * Math.PI * 2;
+    let id: number;
+    const animate = () => {
+      t += 0.04;
+      setY(Math.sin(t + phase) * 4);
+      setScale(1 + Math.sin(t + phase) * 0.15);
+      setOpacity(0.55 + Math.sin(t + phase) * 0.25);
+      id = requestAnimationFrame(animate);
+    };
+    id = requestAnimationFrame(animate);
+    return () => cancelAnimationFrame(id);
+  }, [index, total]);
+
+  return (
+    <div style={{ transform: `translateY(${y}px) scale(${scale})`, opacity }}>
+      <svg width="24" height="24" viewBox="0 0 24 24">
+        <ellipse cx="12" cy="15" rx="5" ry="4" className="fill-text-secondary" />
+        <circle cx="7" cy="9" r="2.2" className="fill-text-secondary" />
+        <circle cx="12" cy="7" r="2.2" className="fill-text-secondary" />
+        <circle cx="17" cy="9" r="2.2" className="fill-text-secondary" />
+      </svg>
+    </div>
+  );
+}
+
+export function LoadingSpinner({ stage, jobId, submittedAt, onCancel, onOpenGame }: LoadingSpinnerProps) {
+  const { t } = useI18n();
+  const progress = usePerceivedProgress(stage);
+  const { key } = STAGE_CONFIG[stage];
+  const [confirmCancelOpen, setConfirmCancelOpen] = useState(false);
+  const [elapsedMs, setElapsedMs] = useState(0);
+
+  useEffect(() => {
+    if (!submittedAt) {
+      setElapsedMs(0);
+      return;
+    }
+
+    const submittedTime = Date.parse(submittedAt);
+    if (!Number.isFinite(submittedTime)) {
+      setElapsedMs(0);
+      return;
+    }
+
+    const updateElapsed = () => {
+      setElapsedMs(Math.max(0, Date.now() - submittedTime));
+    };
+
+    updateElapsed();
+    const timer = window.setInterval(updateElapsed, 250);
+    return () => window.clearInterval(timer);
+  }, [submittedAt]);
+
+  return (
+    <div className="flex flex-col items-center justify-center py-6">
+      <div className="relative">
+        <FloatingCat />
+        {onOpenGame && (
+          <div className="absolute left-[100px] -top-[50px] flex flex-col-reverse items-start">
+            <div className="w-[50px] h-[30px] border-l border-t border-text-secondary/35 rounded-tl-[4px] mt-1" />
+            <p className="text-[13px] leading-snug tracking-[0.08em] font-light text-text-secondary/85 whitespace-nowrap">
+              {t('game.invite.bubble')}{' '}
+              <a href="#" onClick={(e) => { e.preventDefault(); onOpenGame(); }} className="font-semibold text-text-primary underline underline-offset-4">
+                2048
+              </a>?
+            </p>
+          </div>
+        )}
+      </div>
+
+      <div className="mt-3">
+        <div className="flex items-center justify-center gap-2">
+          {Array.from({ length: 7 }, (_, i) => <WavingPaw key={i} index={i} total={7} />)}
+        </div>
+      </div>
+
+      <div className="mt-4 text-center">
+        <p className="text-base text-text-primary/80">{t(key)}</p>
+        <p className="text-sm text-text-secondary/60 tabular-nums mt-1">{Math.round(progress)}%</p>
+        {elapsedMs > 0 && (
+          <p className="text-xs text-text-secondary/50 tabular-nums mt-1">
+            {formatElapsed(elapsedMs)}
+          </p>
+        )}
+      </div>
+
+      <div className="flex items-center gap-3 mt-3">
+        {jobId && <span className="text-xs text-text-secondary/40 font-mono">{jobId.slice(0, 8)}</span>}
+        {onCancel && (
+          <button onClick={() => setConfirmCancelOpen(true)} className="text-xs text-text-secondary/40 hover:text-red-500">
+            {t('common.cancel')}
+          </button>
+        )}
+      </div>
+
+      {confirmCancelOpen && onCancel ? (
+        <div className="fixed inset-0 z-50 flex items-center justify-center pb-[10vh] p-4">
+          <div className="absolute inset-0 bg-bg-primary/60 backdrop-blur-md animate-overlay-wash-in" onClick={() => setConfirmCancelOpen(false)} />
+          <div className="relative w-full max-w-md bg-bg-secondary rounded-2xl p-8 shadow-xl border border-bg-tertiary/30">
+             <h2 className="text-base font-medium text-text-primary">中止任务？</h2>
+             <p className="text-sm text-text-secondary mt-2">猫猫已经跑了一半了，确定要停下来吗？</p>
+             <div className="flex items-center justify-end gap-3 mt-6">
+               <button onClick={() => setConfirmCancelOpen(false)} className="px-4 py-2 text-sm text-text-secondary bg-bg-primary rounded-xl">取消</button>
+               <button onClick={() => { setConfirmCancelOpen(false); onCancel(); }} className="px-4 py-2 text-sm text-white bg-red-500 rounded-xl">确定停止</button>
+             </div>
+          </div>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+function formatElapsed(ms: number): string {
+  const totalSeconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return `${minutes}:${seconds.toString().padStart(2, '0')}`;
+}

frontend/src/components/ManimCatLogo.tsx

@@ -0,0 +1,29 @@
+const ManimCatLogo = ({ className }: { className?: string }) => (
+  <svg
+    viewBox="0 0 512 512"
+    xmlns="http://www.w3.org/2000/svg"
+    className={className}
+  >
+    <rect width="512" height="512" fill="#faf9f5"/>
+    <path
+      d="M 100 400 V 140 L 230 300 L 360 140 V 260"
+      fill="none"
+      stroke="#455a64"
+      strokeWidth="55"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+    <g transform="translate(360, 340)">
+      <path
+        d="M -70 40 C -80 0, -80 -30, -50 -60 L -20 -30 L 20 -30 L 50 -60 C 80 -30, 80 0, 70 40 C 60 70, -60 70, -70 40 Z"
+        fill="#455a64"
+      />
+      <circle cx="-35" cy="-5" r="18" fill="#ffffff" />
+      <circle cx="35" cy="-5" r="18" fill="#ffffff" />
+      <circle cx="-38" cy="-5" r="6" fill="#455a64" />
+      <circle cx="32" cy="-5" r="6" fill="#455a64" />
+    </g>
+  </svg>
+);
+
+export default ManimCatLogo;

frontend/src/components/ProblemFramingOverlay.tsx

@@ -0,0 +1,519 @@
+import { useEffect, useRef, useState } from 'react';
+import type { PointerEvent as ReactPointerEvent } from 'react';
+import type { ProblemFramingPlan } from '../types/api';
+import { useI18n } from '../i18n';
+
+interface ProblemFramingOverlayProps {
+  open: boolean;
+  status: 'loading' | 'ready' | 'error';
+  plan: ProblemFramingPlan | null;
+  error: string | null;
+  adjustment: string;
+  generating: boolean;
+  onAdjustmentChange: (value: string) => void;
+  onRetry: () => void;
+  onGenerate: () => void;
+  onClose: () => void;
+}
+
+const CARD_LAYOUTS = [
+  { x: 6, y: 14, rotate: -6 },
+  { x: 21, y: 57, rotate: 4 },
+  { x: 42, y: 22, rotate: -4 },
+  { x: 62, y: 52, rotate: 5 },
+  { x: 79, y: 18, rotate: -3 },
+  { x: 74, y: 66, rotate: 3 },
+];
+
+const COLLAPSED_CARD = { width: 120, height: 86 };
+const EXPANDED_CARD = { width: 272, height: 236 };
+const ACTIVE_REPEL_DISTANCE = 14;
+const ACTIVE_CARD_CENTER_PULL = 0.28;
+
+type CardPosition = {
+  x: number;
+  y: number;
+  rotate: number;
+};
+
+type DragState = {
+  index: number;
+  pointerId: number;
+  startClientX: number;
+  startClientY: number;
+  originX: number;
+  originY: number;
+  moved: boolean;
+};
+
+function PawStamp({ delay = 0 }: { delay?: number }) {
+  return (
+    <div
+      className="problem-paw text-text-secondary/55"
+      style={{ animationDelay: `${delay}s` }}
+    >
+      <svg width="34" height="34" viewBox="0 0 24 24" fill="currentColor">
+        <ellipse cx="12" cy="15" rx="5.2" ry="4.1" />
+        <circle cx="7" cy="9.1" r="2.15" />
+        <circle cx="12" cy="6.8" r="2.15" />
+        <circle cx="17" cy="9.1" r="2.15" />
+      </svg>
+    </div>
+  );
+}
+
+function WaitingPaws() {
+  return (
+    <div className="pointer-events-none absolute right-6 top-5 flex items-center gap-2 opacity-80">
+      <PawStamp />
+      <PawStamp delay={0.18} />
+      <PawStamp delay={0.36} />
+    </div>
+  );
+}
+
+function CanvasTransition() {
+  return (
+    <div className="pointer-events-none absolute inset-0">
+      <div className="absolute left-[12%] top-[24%] h-28 w-28 rounded-full bg-bg-primary/35 blur-2xl animate-pulse" />
+      <div className="absolute right-[16%] top-[18%] h-20 w-36 rounded-full bg-bg-primary/30 blur-2xl animate-pulse [animation-delay:180ms]" />
+      <div className="absolute left-[36%] bottom-[18%] h-24 w-40 rounded-full bg-bg-primary/28 blur-2xl animate-pulse [animation-delay:320ms]" />
+    </div>
+  );
+}
+
+export function ProblemFramingOverlay({
+  open,
+  status,
+  plan,
+  error,
+  adjustment,
+  generating,
+  onAdjustmentChange,
+  onRetry,
+  onGenerate,
+  onClose,
+}: ProblemFramingOverlayProps) {
+  if (!open) {
+    return null;
+  }
+
+  const planKey = plan
+    ? `${status}-${plan.summary}-${plan.steps.map((step) => `${step.title}:${step.content}`).join('|')}`
+    : `empty-${status}`;
+
+  return (
+    <ProblemFramingOverlayContent
+      key={planKey}
+      status={status}
+      plan={plan}
+      error={error}
+      adjustment={adjustment}
+      generating={generating}
+      onAdjustmentChange={onAdjustmentChange}
+      onRetry={onRetry}
+      onGenerate={onGenerate}
+      onClose={onClose}
+    />
+  );
+}
+
+interface ProblemFramingOverlayContentProps {
+  status: 'loading' | 'ready' | 'error';
+  plan: ProblemFramingPlan | null;
+  error: string | null;
+  adjustment: string;
+  generating: boolean;
+  onAdjustmentChange: (value: string) => void;
+  onRetry: () => void;
+  onGenerate: () => void;
+  onClose: () => void;
+}
+
+function ProblemFramingOverlayContent({
+  status,
+  plan,
+  error,
+  adjustment,
+  generating,
+  onAdjustmentChange,
+  onRetry,
+  onGenerate,
+  onClose,
+}: ProblemFramingOverlayContentProps) {
+  const { t } = useI18n();
+  const [confirmDiscardOpen, setConfirmDiscardOpen] = useState(false);
+  const [activeStepIndex, setActiveStepIndex] = useState<number | null>(null);
+  const [draftSteps, setDraftSteps] = useState<Array<{ title: string; content: string }>>(() =>
+    plan ? plan.steps.map((step) => ({ title: step.title, content: step.content })) : []
+  );
+  const [cardPositions, setCardPositions] = useState<CardPosition[]>(() =>
+    plan
+      ? plan.steps.map((_, index) => {
+          const layout = CARD_LAYOUTS[index] || CARD_LAYOUTS[index % CARD_LAYOUTS.length];
+          return { x: layout.x, y: layout.y, rotate: layout.rotate };
+        })
+      : []
+  );
+  const canvasRef = useRef<HTMLDivElement | null>(null);
+  const dragStateRef = useRef<DragState | null>(null);
+  const statusKey =
+    status === 'loading'
+      ? 'problem.status.loading'
+      : status === 'ready'
+        ? 'problem.status.ready'
+        : 'problem.status.error';
+
+  useEffect(() => {
+    dragStateRef.current = null;
+  }, []);
+
+  const stepCount = plan?.steps.length || 4;
+
+  const updateCardPosition = (index: number, clientX: number, clientY: number) => {
+    const canvas = canvasRef.current;
+    const current = cardPositions[index];
+    if (!canvas || !current) {
+      return;
+    }
+
+    const rect = canvas.getBoundingClientRect();
+    const isActive = activeStepIndex === index;
+    const cardSize = isActive ? EXPANDED_CARD : COLLAPSED_CARD;
+    const maxX = Math.max(0, rect.width - cardSize.width);
+    const maxY = Math.max(0, rect.height - cardSize.height);
+    const nextX = Math.min(Math.max(0, clientX), maxX);
+    const nextY = Math.min(Math.max(0, clientY), maxY);
+
+    setCardPositions((previous) =>
+      previous.map((item, itemIndex) =>
+        itemIndex === index
+          ? {
+              ...item,
+              x: rect.width > 0 ? (nextX / rect.width) * 100 : item.x,
+              y: rect.height > 0 ? (nextY / rect.height) * 100 : item.y,
+            }
+          : item
+      )
+    );
+  };
+
+  const getRenderedPosition = (index: number, position: CardPosition): CardPosition => {
+    if (activeStepIndex === index) {
+      const centeredX = position.x + (50 - position.x) * ACTIVE_CARD_CENTER_PULL;
+      const centeredY = position.y + (44 - position.y) * ACTIVE_CARD_CENTER_PULL;
+
+      return {
+        x: Math.max(2, Math.min(72, centeredX)),
+        y: Math.max(3, Math.min(58, centeredY)),
+        rotate: 0,
+      };
+    }
+
+    if (activeStepIndex === null || activeStepIndex === index) {
+      return position;
+    }
+
+    const active = cardPositions[activeStepIndex];
+    if (!active) {
+      return position;
+    }
+
+    const dx = position.x - active.x;
+    const dy = position.y - active.y;
+    const distance = Math.hypot(dx, dy) || 1;
+    const push = ACTIVE_REPEL_DISTANCE / distance;
+
+    return {
+      x: Math.max(0, Math.min(88, position.x + dx * push)),
+      y: Math.max(0, Math.min(78, position.y + dy * push)),
+      rotate: position.rotate,
+    };
+  };
+
+  const handleCardPointerDown = (index: number, event: ReactPointerEvent<HTMLElement>) => {
+    const target = event.target as HTMLElement;
+    if (target.closest('textarea')) {
+      return;
+    }
+
+    const canvas = canvasRef.current;
+    const current = cardPositions[index];
+    if (!canvas || !current) {
+      return;
+    }
+
+    const rect = canvas.getBoundingClientRect();
+    const pointerOriginX = (current.x / 100) * rect.width;
+    const pointerOriginY = (current.y / 100) * rect.height;
+
+    dragStateRef.current = {
+      index,
+      pointerId: event.pointerId,
+      startClientX: event.clientX,
+      startClientY: event.clientY,
+      originX: pointerOriginX,
+      originY: pointerOriginY,
+      moved: false,
+    };
+
+    event.currentTarget.setPointerCapture(event.pointerId);
+  };
+
+  const handleCardPointerMove = (event: ReactPointerEvent<HTMLElement>) => {
+    const dragState = dragStateRef.current;
+    if (!dragState || dragState.pointerId !== event.pointerId) {
+      return;
+    }
+
+    const deltaX = event.clientX - dragState.startClientX;
+    const deltaY = event.clientY - dragState.startClientY;
+    if (!dragState.moved && Math.abs(deltaX) + Math.abs(deltaY) > 3) {
+      dragState.moved = true;
+    }
+
+    updateCardPosition(dragState.index, dragState.originX + deltaX, dragState.originY + deltaY);
+  };
+
+  const handleCardPointerUp = (index: number, event: ReactPointerEvent<HTMLElement>) => {
+    const dragState = dragStateRef.current;
+    if (!dragState || dragState.pointerId !== event.pointerId) {
+      return;
+    }
+
+    if (!dragState.moved) {
+      setActiveStepIndex((current) => (current === index ? null : index));
+    }
+
+    if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+      event.currentTarget.releasePointerCapture(event.pointerId);
+    }
+    dragStateRef.current = null;
+  };
+
+  return (
+    <div className="fixed inset-0 z-[80]">
+      <div className="animate-overlay-wash-in absolute inset-0 bg-bg-primary/28 backdrop-blur-[6px]" />
+
+      <div className="relative flex min-h-screen items-center justify-center p-4 sm:p-8">
+        <div className="animate-fade-in-soft relative flex h-[min(82vh,760px)] w-full max-w-5xl flex-col overflow-hidden rounded-[2rem] border border-bg-tertiary/30 bg-bg-secondary">
+          <div className="absolute inset-0 opacity-35 bg-[radial-gradient(circle_at_1px_1px,rgba(0,0,0,0.05)_1px,transparent_0)] bg-[length:24px_24px]" />
+          <WaitingPaws />
+
+          <div className="relative flex flex-1 flex-col px-5 pb-5 pt-6 sm:px-8 sm:pb-6 sm:pt-7">
+            <div className="flex items-start justify-between gap-4 pb-2">
+              <button
+                type="button"
+                onClick={() => setConfirmDiscardOpen(true)}
+                className="inline-flex items-center gap-2 px-1 py-1 text-sm text-text-secondary transition-colors hover:text-text-primary"
+              >
+                <span aria-hidden="true">←</span>
+                {t('problem.back')}
+              </button>
+            </div>
+
+            <div className="mt-2 flex min-h-0 flex-1 flex-col overflow-hidden">
+              <section className="min-h-0 flex-1 overflow-hidden px-4 pb-2 pt-2 sm:px-6 sm:pb-3 sm:pt-3">
+                <div className="mx-auto h-full max-w-5xl">
+                  <div className="h-full">
+                    {status === 'loading' && (
+                      <div ref={canvasRef} className="relative h-full min-h-[470px] overflow-hidden">
+                        <CanvasTransition />
+                        <p className="absolute right-0 top-0 text-sm text-text-secondary">{t(statusKey)}</p>
+                        <svg className="pointer-events-none absolute inset-0 h-full w-full opacity-35" viewBox="0 0 1100 620" preserveAspectRatio="none">
+                          <path d="M 40 220 C 180 90, 280 90, 370 230 S 560 420, 670 250 S 860 90, 1060 250" fill="none" stroke="currentColor" strokeWidth="1.2" strokeDasharray="6 8" className="text-text-secondary/35" />
+                        </svg>
+                        {Array.from({ length: stepCount }, (_, index) => {
+                          const layout = CARD_LAYOUTS[index] || CARD_LAYOUTS[CARD_LAYOUTS.length - 1];
+                          return (
+                            <div
+                              key={index}
+                              className="absolute h-[86px] w-[120px] rounded-[1.2rem] border border-dashed border-text-secondary/35 bg-bg-primary/76 p-4"
+                              style={{
+                                left: `${layout.x}%`,
+                                top: `${layout.y}%`,
+                                transform: `rotate(${layout.rotate}deg)`,
+                                animation: `fadeInUp 0.38s ease-out ${0.28 + index * 0.16}s both`
+                              }}
+                            >
+                              <div className="h-4 w-14 animate-pulse rounded-full bg-bg-secondary/80" />
+                              <div className="mt-3 h-3 w-full animate-pulse rounded-full bg-bg-secondary/70" />
+                              <div className="mt-2 h-3 w-4/5 animate-pulse rounded-full bg-bg-secondary/60" />
+                            </div>
+                          );
+                        })}
+                      </div>
+                    )}
+
+                    {status !== 'loading' && plan && (
+                      <div ref={canvasRef} className="relative h-full min-h-[470px] overflow-hidden">
+                        <p className="absolute right-0 top-0 text-sm text-text-secondary">{t(statusKey)}</p>
+                        <svg className="pointer-events-none absolute inset-0 h-full w-full opacity-35" viewBox="0 0 1100 620" preserveAspectRatio="none">
+                          <path d="M 40 220 C 180 90, 280 90, 370 230 S 560 420, 670 250 S 860 90, 1060 250" fill="none" stroke="currentColor" strokeWidth="1.2" strokeDasharray="6 8" className="text-text-secondary/35" />
+                        </svg>
+
+                        {draftSteps.map((step, index) => {
+                          const isActive = index === activeStepIndex;
+                          const position = cardPositions[index] || CARD_LAYOUTS[index] || CARD_LAYOUTS[CARD_LAYOUTS.length - 1];
+                          const renderedPosition = getRenderedPosition(index, position);
+                          const collapsedTitle = step.title.slice(0, 6);
+
+                          return (
+                            <article
+                              key={`${step.title}-${index}`}
+                              onPointerDown={(event) => handleCardPointerDown(index, event)}
+                              onPointerMove={handleCardPointerMove}
+                              onPointerUp={(event) => handleCardPointerUp(index, event)}
+                              onPointerCancel={(event) => handleCardPointerUp(index, event)}
+                              className={`absolute rounded-[1.2rem] border border-dashed bg-bg-primary/78 p-4 transition-all duration-500 ease-out ${
+                                isActive
+                                  ? 'z-20 h-[236px] w-[272px] border-accent/45'
+                                  : 'z-10 h-[86px] w-[120px] border-text-secondary/35 cursor-grab select-none'
+                              }`}
+                              style={{
+                                left: `${renderedPosition.x}%`,
+                                top: `${renderedPosition.y}%`,
+                                transform: isActive ? 'rotate(0deg)' : `rotate(${position.rotate}deg)`,
+                                animation: `fadeInUp 0.32s ease-out ${index * 0.12}s both`
+                              }}
+                            >
+                              <p className="pointer-events-none text-[11px] uppercase tracking-[0.24em] text-text-secondary/55">
+                                {String(index + 1).padStart(2, '0')}
+                              </p>
+                              <h3 className="pointer-events-none mt-1 text-sm leading-5 text-text-primary">
+                                {isActive ? step.title : collapsedTitle}
+                              </h3>
+
+                              {isActive ? (
+                                <textarea
+                                  value={step.content}
+                                  onChange={(event) => {
+                                    const nextSteps = draftSteps.map((item, itemIndex) =>
+                                      itemIndex === index ? { ...item, content: event.target.value } : item
+                                    );
+                                    setDraftSteps(nextSteps);
+                                  }}
+                                  rows={7}
+                                  spellCheck={false}
+                                  className="mt-3 min-h-[140px] w-full resize-none bg-transparent text-sm leading-6 text-text-secondary outline-none overflow-hidden"
+                                />
+                              ) : null}
+                            </article>
+                          );
+                        })}
+
+                        {status === 'error' && (
+                          <div className="absolute bottom-0 left-0 text-sm leading-6 text-red-700">
+                            {error || t('generation.problemFramingFailed')}
+                          </div>
+                        )}
+                      </div>
+                    )}
+                  </div>
+                </div>
+              </section>
+
+              <aside className="px-5 pb-5 pt-1 sm:px-7 sm:pb-6">
+                <div className="mx-auto grid max-w-[860px] gap-4 lg:grid-cols-[minmax(0,520px)_auto] lg:items-center lg:translate-x-8">
+                  <div className="lg:translate-y-3">
+                    <textarea
+                      value={adjustment}
+                      onChange={(event) => onAdjustmentChange(event.target.value)}
+                      rows={2}
+                      placeholder={t('problem.adjustPlaceholder')}
+                      className="mt-3 min-h-[68px] w-full resize-none rounded-2xl bg-bg-secondary/50 px-4 py-3 text-sm leading-6 text-text-primary placeholder-text-secondary/40 outline-none transition-all focus:bg-bg-secondary/70 focus:ring-2 focus:ring-accent/20"
+                    />
+                  </div>
+
+                  <div className="flex items-center justify-center gap-5 lg:justify-start lg:translate-x-3 lg:translate-y-3">
+                    <button
+                      type="button"
+                      onClick={onRetry}
+                      disabled={status === 'loading' || !adjustment.trim()}
+                      className="px-6 py-3.5 text-sm font-medium text-text-secondary hover:text-text-primary bg-bg-secondary/50 hover:bg-bg-secondary/70 rounded-2xl transition-all disabled:cursor-not-allowed disabled:opacity-45 focus:outline-none focus:ring-2 focus:ring-accent/20"
+                    >
+                      {t('problem.adjustAction')}
+                    </button>
+                    <button
+                      type="button"
+                      onClick={onGenerate}
+                      disabled={!plan || status === 'loading' || generating}
+                      className="group relative px-5 py-2.5 bg-accent hover:bg-accent-hover text-white text-sm font-medium rounded-full shadow-sm shadow-accent/10 transition-all duration-300 disabled:opacity-50 disabled:cursor-not-allowed hover:shadow-md hover:shadow-accent/15 active:scale-[0.97] overflow-hidden"
+                    >
+                      <span className="relative z-10 flex items-center gap-2">
+                        {generating ? (
+                          <>
+                            <svg className="animate-spin w-4 h-4" fill="none" viewBox="0 0 24 24">
+                              <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+                              <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
+                            </svg>
+                            {t('form.submitting')}
+                          </>
+                        ) : (
+                          <>
+                            {t('problem.start')}
+                            <svg className="w-4 h-4 transition-transform duration-300 group-hover:translate-x-1" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13 7l5 5m0 0l-5 5m5-5H6" />
+                            </svg>
+                          </>
+                        )}
+                      </span>
+                      <div className="absolute inset-0 bg-gradient-to-r from-transparent via-white/10 to-transparent -translate-x-full group-hover:animate-shimmer" />
+                    </button>
+                  </div>
+                </div>
+              </aside>
+            </div>
+          </div>
+
+          {confirmDiscardOpen && (
+            <div className="absolute inset-0 z-50 flex items-center justify-center p-4">
+              <div
+                className="absolute inset-0 bg-black/50 backdrop-blur-sm"
+                onClick={() => setConfirmDiscardOpen(false)}
+              />
+              <div className="relative w-full max-w-sm rounded-2xl border border-bg-tertiary/30 bg-bg-secondary p-6 shadow-xl">
+                <div className="flex items-start justify-between gap-3">
+                  <div>
+                    <h3 className="text-base font-medium text-text-primary">{t('problem.discardTitle')}</h3>
+                    <p className="mt-2 text-sm leading-relaxed text-text-secondary">{t('problem.discardDescription')}</p>
+                  </div>
+                  <button
+                    type="button"
+                    onClick={() => setConfirmDiscardOpen(false)}
+                    className="rounded-full p-1.5 text-text-secondary/70 transition-all hover:bg-bg-primary/50 hover:text-text-secondary"
+                    aria-label={t('common.close')}
+                    title={t('common.close')}
+                  >
+                    <svg className="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
+                    </svg>
+                  </button>
+                </div>
+                <div className="mt-6 flex items-center justify-end gap-3">
+                  <button
+                    type="button"
+                    onClick={() => setConfirmDiscardOpen(false)}
+                    className="rounded-xl bg-bg-primary px-4 py-2 text-sm text-text-secondary transition-all hover:bg-bg-tertiary hover:text-text-primary"
+                  >
+                    {t('common.cancel')}
+                  </button>
+                  <button
+                    type="button"
+                    onClick={() => {
+                      setConfirmDiscardOpen(false);
+                      onClose();
+                    }}
+                    className="rounded-xl bg-red-500 px-4 py-2 text-sm font-medium text-bg-primary transition-all hover:bg-red-600"
+                  >
+                    {t('common.confirm')}
+                  </button>
+                </div>
+              </div>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

frontend/src/components/PromptInput.tsx

@@ -0,0 +1,88 @@
+// 提示词输入组件
+// 提供统一的提示词编辑界面
+
+interface PromptInputProps {
+  value: string;
+  onChange: (value: string) => void;
+  label: string;
+  placeholder?: string;
+  maxLength?: number;
+  disabled?: boolean;
+  showWordCount?: boolean;
+  onSave?: () => void;
+  onRestoreDefault?: () => void;
+}
+
+export function PromptInput({
+  value,
+  onChange,
+  label,
+  placeholder,
+  maxLength = 20000,
+  disabled = false,
+  showWordCount = true,
+  onSave,
+  onRestoreDefault
+}: PromptInputProps) {
+  const wordCount = value.length;
+  const isMaxLength = wordCount >= maxLength;
+
+  return (
+    <div className="w-full space-y-4">
+      {/* 标签和操作按钮 */}
+      <div className="flex items-center justify-between">
+        <label className="text-sm font-medium text-text-primary">
+          {label}
+        </label>
+        <div className="flex gap-2">
+          {onRestoreDefault && (
+            <button
+              onClick={onRestoreDefault}
+              disabled={disabled}
+              className="px-3 py-1.5 text-xs text-text-secondary hover:text-text-primary hover:bg-bg-secondary/50 rounded-lg transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+            >
+              恢复默认
+            </button>
+          )}
+          {onSave && (
+            <button
+              onClick={onSave}
+              disabled={disabled}
+              className="px-3 py-1.5 text-xs bg-accent text-white hover:bg-accent-hover rounded-lg transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+            >
+              保存
+            </button>
+          )}
+        </div>
+      </div>
+
+      {/* 输入区域 */}
+      <textarea
+        value={value}
+        onChange={(e) => {
+          if (e.target.value.length <= maxLength) {
+            onChange(e.target.value);
+          }
+        }}
+        placeholder={placeholder}
+        disabled={disabled}
+        rows={20}
+        className={`w-full px-4 py-3 bg-bg-secondary/50 border border-bg-secondary/50 rounded-xl text-sm text-text-primary placeholder-text-secondary/40 focus:outline-none focus:ring-2 focus:ring-accent/20 focus:bg-bg-secondary/70 focus:border-accent/30 transition-all resize-y min-h-[480px] ${
+          isMaxLength
+            ? 'border-red-500/30 focus:ring-red-500/20 focus:border-red-500/50'
+            : ''
+        }`}
+      />
+
+      {/* 字符计数 */}
+      {showWordCount && (
+        <div className="flex items-center justify-between text-xs text-text-secondary/60">
+          <span>{wordCount} / {maxLength} 字符</span>
+          {isMaxLength && (
+            <span className="text-red-500">已达到字符限制</span>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

frontend/src/components/PromptSidebar.tsx

@@ -0,0 +1,112 @@
+/**
+ * 提示词侧边栏 - 简洁风格
+ */
+
+import type { RoleType, SharedModuleType } from '../types/api';
+import type { SelectionType } from '../hooks/usePrompts';
+import { useI18n } from '../i18n';
+
+// ============================================================================
+// 配置
+// ============================================================================
+
+interface Props {
+  selection: SelectionType;
+  onSelect: (sel: SelectionType) => void;
+}
+
+export function PromptSidebar({ selection, onSelect }: Props) {
+  const { t } = useI18n();
+
+  const roleLabels: Record<RoleType, string> = {
+    problemFraming: t('prompts.role.problemFraming'),
+    conceptDesigner: t('prompts.role.conceptDesigner'),
+    codeGeneration: t('prompts.role.codeGeneration'),
+    codeRetry: t('prompts.role.codeRetry'),
+    codeEdit: t('prompts.role.codeEdit')
+  };
+
+  const sharedLabels: Record<SharedModuleType, string> = {
+    apiIndex: t('prompts.shared.apiIndex'),
+    specification: t('prompts.shared.specification')
+  };
+
+  const isRoleSelected = (role: RoleType, promptType: 'system' | 'user') =>
+    selection.kind === 'role' &&
+    selection.role === role &&
+    selection.promptType === promptType;
+
+  const isSharedSelected = (module: SharedModuleType) =>
+    selection.kind === 'shared' && selection.module === module;
+
+  return (
+    <div className="w-56 bg-bg-secondary/20 border-r border-bg-tertiary/30 overflow-y-auto">
+      <div className="p-3 space-y-4">
+        {/* 角色提示词 */}
+        <div>
+          <h3 className="px-3 py-1.5 text-xs font-medium text-text-secondary/50 uppercase tracking-wider">
+            {t('prompts.roleSection')}
+          </h3>
+          <div className="space-y-0.5">
+            {(Object.keys(roleLabels) as RoleType[]).map(role => (
+              <div key={role}>
+                {/* 角色名 */}
+                <div className="px-3 py-1.5 text-xs text-text-secondary/70">
+                  {roleLabels[role]}
+                </div>
+                {/* System / User 按钮 */}
+                <div className="flex gap-1 px-3 pb-1">
+                  <button
+                    onClick={() => onSelect({ kind: 'role', role, promptType: 'system' })}
+                    className={`flex-1 px-2 py-1 text-xs rounded transition-colors ${
+                      isRoleSelected(role, 'system')
+                        ? 'bg-accent/20 text-accent'
+                        : 'text-text-secondary/60 hover:bg-bg-tertiary/50 hover:text-text-secondary'
+                    }`}
+                  >
+                    {t('common.system')}
+                  </button>
+                  <button
+                    onClick={() => onSelect({ kind: 'role', role, promptType: 'user' })}
+                    className={`flex-1 px-2 py-1 text-xs rounded transition-colors ${
+                      isRoleSelected(role, 'user')
+                        ? 'bg-accent/20 text-accent'
+                        : 'text-text-secondary/60 hover:bg-bg-tertiary/50 hover:text-text-secondary'
+                    }`}
+                  >
+                    {t('common.user')}
+                  </button>
+                </div>
+              </div>
+            ))}
+          </div>
+        </div>
+
+        {/* 分隔线 */}
+        <div className="border-t border-bg-tertiary/30" />
+
+        {/* 共享模块 */}
+        <div>
+          <h3 className="px-3 py-1.5 text-xs font-medium text-text-secondary/50 uppercase tracking-wider">
+            {t('prompts.sharedSection')}
+          </h3>
+          <div className="space-y-0.5">
+            {(Object.keys(sharedLabels) as SharedModuleType[]).map(module => (
+              <button
+                key={module}
+                onClick={() => onSelect({ kind: 'shared', module })}
+                className={`w-full px-3 py-2 text-left text-sm rounded transition-colors ${
+                  isSharedSelected(module)
+                    ? 'bg-accent/20 text-accent'
+                    : 'text-text-secondary/70 hover:bg-bg-tertiary/50 hover:text-text-secondary'
+                }`}
+              >
+                {sharedLabels[module]}
+              </button>
+            ))}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

frontend/src/components/PromptsManager.tsx

@@ -0,0 +1,147 @@
+/**
+ * 提示词管理器 - 简洁风格
+ */
+
+import { PromptSidebar } from './PromptSidebar';
+import { usePrompts } from '../hooks/usePrompts';
+import type { RoleType, SharedModuleType } from '../types/api';
+import { useI18n } from '../i18n';
+
+// ============================================================================
+// 配置
+// ============================================================================
+
+interface Props {
+  isOpen: boolean;
+  onClose: () => void;
+}
+
+export function PromptsManager({ isOpen, onClose }: Props) {
+  const { t } = useI18n();
+  const {
+    isLoading,
+    selection,
+    setSelection,
+    getCurrentContent,
+    setCurrentContent,
+    restoreCurrent,
+    hasOverride
+  } = usePrompts();
+
+  // 获取当前标题
+  const getTitle = () => {
+    const roleLabels: Record<RoleType, string> = {
+      problemFraming: t('prompts.role.problemFraming'),
+      conceptDesigner: t('prompts.role.conceptDesigner'),
+      codeGeneration: t('prompts.role.codeGeneration'),
+      codeRetry: t('prompts.role.codeRetry'),
+      codeEdit: t('prompts.role.codeEdit')
+    };
+
+    const sharedLabels: Record<SharedModuleType, string> = {
+      apiIndex: t('prompts.shared.apiIndex'),
+      specification: t('prompts.shared.specification')
+    };
+
+    if (selection.kind === 'role') {
+      const roleLabel = roleLabels[selection.role];
+      return selection.promptType === 'system'
+        ? t('prompts.role.systemTitle', { role: roleLabel })
+        : t('prompts.role.userTitle', { role: roleLabel });
+    }
+    return sharedLabels[selection.module];
+  };
+
+  // 获取当前描述
+  const getDescription = () => {
+    if (selection.kind === 'role') {
+      if (selection.promptType === 'system') {
+        return t('prompts.role.systemDescription');
+      }
+      return t('prompts.role.userDescription');
+    }
+    return selection.module === 'apiIndex'
+      ? t('prompts.shared.apiIndexDescription')
+      : t('prompts.shared.specificationDescription');
+  };
+
+  if (!isOpen) return null;
+
+  const content = getCurrentContent();
+  const isModified = hasOverride();
+
+  return (
+    <div
+      className={`fixed inset-0 z-50 flex flex-col bg-bg-primary transition-all duration-300 ${
+        'opacity-100'
+      }`}
+    >
+      {/* 顶栏 */}
+      <div className="h-14 bg-bg-secondary/50 border-b border-bg-tertiary/30 flex items-center justify-between px-4">
+        <div className="flex items-center gap-3">
+          <button
+            onClick={onClose}
+            className="p-2 text-text-secondary/70 hover:text-text-primary hover:bg-bg-tertiary/50 rounded-lg transition-colors"
+          >
+            <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M15 19l-7-7 7-7" />
+            </svg>
+          </button>
+          <span className="text-sm text-text-primary font-medium">{t('prompts.title')}</span>
+        </div>
+
+        {/* 修改状态 + 恢复按钮 */}
+        <div className="flex items-center gap-2">
+          {isModified && (
+            <>
+              <span className="text-xs text-accent/70">{t('prompts.modified')}</span>
+              <button
+                onClick={restoreCurrent}
+                className="px-3 py-1.5 text-xs text-text-secondary/70 hover:text-text-primary hover:bg-bg-tertiary/50 rounded-lg transition-colors"
+              >
+                {t('prompts.restore')}
+              </button>
+            </>
+          )}
+        </div>
+      </div>
+
+      {/* 主内容 */}
+      <div className="flex-1 flex overflow-hidden">
+        {/* 侧边栏 */}
+        <PromptSidebar selection={selection} onSelect={setSelection} />
+
+        {/* 编辑区 */}
+        <div className="flex-1 flex flex-col overflow-hidden">
+          {/* 标题区 */}
+          <div className="px-6 py-4 border-b border-bg-tertiary/30">
+            <h2 className="text-base font-medium text-text-primary">{getTitle()}</h2>
+            <p className="text-xs text-text-secondary/60 mt-1">{getDescription()}</p>
+          </div>
+
+          {/* 编辑器 */}
+          <div className="flex-1 p-4 overflow-hidden">
+            {isLoading ? (
+              <div className="h-full flex items-center justify-center text-text-secondary/50 text-sm">
+                {t('common.loading')}
+              </div>
+            ) : (
+              <textarea
+                value={content}
+                onChange={e => setCurrentContent(e.target.value)}
+                className="w-full h-full px-4 py-3 bg-bg-secondary/30 border border-bg-tertiary/30 rounded-lg text-sm text-text-primary font-mono leading-relaxed resize-none focus:outline-none focus:border-accent/30 focus:ring-1 focus:ring-accent/20 transition-colors"
+                placeholder={t('prompts.placeholder')}
+              />
+            )}
+          </div>
+
+          {/* 底栏 */}
+          <div className="px-6 py-3 border-t border-bg-tertiary/30 flex items-center justify-between text-xs text-text-secondary/50">
+            <span>{t('prompts.characters', { count: content.length })}</span>
+            <span>{t('prompts.autosave')}</span>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}