简体中文 | English

项目简介

很荣幸在这里介绍我的新项目ManimCat，它是一只猫

本项目基于 manim-video-generator 进行了大幅重构与再开发，现在已经不只是单一生成流程，而是一个更完整的 AI 数学教学可视化创作系统。

它面向课堂讲解、例题拆解与数形结合表达等场景，用户可以通过自然语言生成、修改、重渲染并组织动画与静态两类教学可视化内容，支持 video 与 image 两种输出。

项目现在可以从三个维度理解：双模式、双引擎、双 Studio。

• Workflow Mode 用于直接生成与渲染，适合快速产出
• Agent Mode 用于基于 Studio 的协作式创作、审阅、任务跟踪与迭代
• ManimGX 负责动画、镜头与时间线驱动的数学叙事
• matplotlib 负责 Plot Studio 中的静态数学图像、函数图、图表与教学插图
• Plot Studio 是目前更成熟的 Studio 路径，主要面向静态可视化与迭代编辑
• Manim Studio 面向动画创作，但目前仍处于相对更早期的阶段

界面

UI 界面

Workflow 界面

Plot Studio 界面

样例

快速开始

npm install
cd frontend && npm install
cd ..
npm run dev

访问 http://localhost:3000。环境变量见 .env.example，部署要点见下方部署。

本地动画渲染使用 ManimGX 0.1.1，需要 Python 3.13 或更新版本。Linux wheel 自带 lavapipe，可使用 CPU 渲染。

ManimGX 使用原生 Typst 排版，本地渲染无需安装外部 TeX。Typst 支持在同一表达式中混排中文与数学符号。

本地运行时请创建 Python 3.13+ 虚拟环境，运行 python -m pip install -r requirements.txt 安装依赖，再将 MANIMGX_PYTHON 设置为该环境的 Python 可执行文件路径，供应用调用渲染器。

如果你直接用 Docker 镜像部署，也可以从 wingflow/manimcat 开始，而不是自行本地构建。

技术

技术栈

• 产品结构：Workflow 模式用于直接生成，Agent 模式用于 Studio 协作式工作流
• 图形引擎：ManimGX 用于动画，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 3.14、ManimGX 0.1.1、matplotlib、ffmpeg；ManimGX 内置字体与排版组件
• 部署：Docker / Docker Compose、Hugging Face Spaces

Workflow Mode

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

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[工具、渲染 / 审查动作]
    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;

部署

Hugging Face Spaces（Docker）

使用仓库的 Dockerfile，监听端口为 7860。容器启动脚本会启动内置 Redis，无需在 Space 中运行 Docker Compose。

在 Space 的 Settings 中配置环境变量；敏感值放入 Secrets，勿写入仓库、Dockerfile 或前端：

配置	用途
STUDIO_DATA_MODE=client	单实例、浏览器保存会话的部署方式
STUDIO_EVENT_TRANSPORT=redis、STUDIO_RUN_COORDINATION=redis	事件推送与运行协调
SUPABASE_URL、SUPABASE_SERVICE_ROLE_KEY	启用 CatKey 时校验密钥、记录用量；Service Role Key 仅供后端使用
CATKEY_UPSTREAM_URL、CATKEY_UPSTREAM_API_KEY、CATKEY_UPSTREAM_MODEL	启用 CatKey 时指定兼容 OpenAI 的服务端上游

BYOK 用户在页面设置自己的上游。若需要服务端保存 Studio 会话，使用 STUDIO_DATA_MODE=server、ENABLE_STUDIO_DB=true，并配置 Supabase 和对应表结构；多副本部署还需要共享 Redis 与可访问的渲染文件存储。

同步到 Space 前，先将需要发布的改动提交到 main，再运行：

./scripts/sync-space.ps1

Linux/macOS 可运行 bash scripts/sync-space.sh。脚本默认发布已提交的 main 到 space、space-show 两个 remote，并覆盖其远端 main；请先核对 remote 地址。脚本会注入 Space 配置，未提交的改动不会进入发布快照。

部署注意：

• 未配置持久存储时，将容器中的视频、工作区和 Redis 数据视为临时数据，重建后可能丢失；数据库保存会话不等于保存视频文件。
• 上线前运行 npm audit --omit=dev 并处理安全告警。启动后检查 /health，再验证真实模型调用与视频播放。
• 本地 Docker 已验证网页、Manim、LaTeX、中文、Matplotlib 和 MiniLM 推理；HF 线上运行、CatKey 与 Supabase 联调仍需部署后验证。

在原项目基础上的主要扩展

这个项目是在原始基础上做的大幅重构与再开发。以下是我本人新增和重构的核心能力：

生成与渲染

• 在视频生成之外，新增了独立的图片工作流
• 新增 YON_IMAGE 锚点分块渲染，支持多图输出
• 新增两阶段 AI 生成架构：概念设计者生成场景方案，再由代码生成者产出 Manim 代码
• 新增 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 负责静态教学图像与图表

开源与版权声明

本项目当前版本以 AGPL-3.0-or-later 授权，全文见 LICENSE。

• 第三方来源与归属说明见 THIRD_PARTY_NOTICES.md。
• 中文版第三方来源与归属说明见 THIRD_PARTY_NOTICES.zh-CN.md。
• 贡献说明见 CONTRIBUTING.md。

历史版本

ManimCat 早期版本包含 manim-video-generator（MIT）的代码。历史 Commit 与历史发布继续受当时发布的许可条款约束。当前版本已删除或独立重写对应实现。

维护说明

由于作者精力有限（个人业余兴趣开发者，非专业背景），目前完全无法对外部代码进行有效的审查和长期维护。因此，本项目欢迎 PR，不过代码审查周期长。感谢理解。

如果你有好的建议或发现了 Bug，欢迎提交 Issue 进行讨论，我会根据自己的节奏进行改进。如果你希望在本项目基础上进行大规模修改，欢迎 Fork 出属于你自己的版本。

如果你觉得有启发与帮助，那是我的荣幸。

如果你觉得这个作品很好，也欢迎请作者喝可乐🥤

中国大陆用户：

海外用户：

感谢你的支持，我会更有动力维护这个项目！

Star History

致谢

• rohitg00/manim-video-generator
• anomalyco/opencode
• academa-labs/manimgx — 动画引擎与 Manim 兼容 API
• Linux.do
• 阿里云百炼