feat: 添加魔搭创空间部署配置

app.py

@@ -0,0 +1,121 @@
+# -*- coding: utf-8 -*-
+"""
+人力V助手 (JinrikiHelper) - 云端部署入口
+适用于 Hugging Face Spaces / 魔塔社区
+"""
+
+import os
+import sys
+import subprocess
+import platform
+import logging
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+
+def setup_environment():
+    """初始化云端环境"""
+    
+    # 检测运行环境
+    is_cloud = any([
+        os.environ.get("SPACE_ID"),           # Hugging Face Spaces
+        os.environ.get("MODELSCOPE_SPACE"),   # 魔塔社区
+        os.environ.get("GRADIO_SERVER_NAME"), # 通用 Gradio 云端
+    ])
+    
+    if is_cloud:
+        logger.info("检测到云端环境，正在初始化...")
+        
+        # 设置临时目录
+        os.environ.setdefault("TMPDIR", "/tmp")
+        
+        # 安装 MFA (如果未安装)
+        if platform.system() != "Windows":
+            setup_mfa_linux()
+    else:
+        logger.info("本地环境运行")
+
+
+def setup_mfa_linux():
+    """Linux 环境下安装和配置 MFA"""
+    import shutil
+    
+    # 检查 mfa 是否已安装
+    if shutil.which("mfa"):
+        logger.info("MFA 已安装")
+        return
+    
+    logger.info("正在安装 MFA...")
+    
+    try:
+        # 尝试 pip 安装
+        subprocess.run(
+            [sys.executable, "-m", "pip", "install", 
+             "montreal-forced-aligner", "--quiet"],
+            check=True,
+            capture_output=True
+        )
+        logger.info("MFA 安装完成")
+        
+        # 下载中文模型
+        download_mfa_models()
+        
+    except subprocess.CalledProcessError as e:
+        logger.warning(f"MFA pip 安装失败: {e}")
+        logger.info("尝试使用 conda 安装...")
+        try:
+            subprocess.run(
+                ["conda", "install", "-c", "conda-forge", 
+                 "montreal-forced-aligner", "-y"],
+                check=True,
+                capture_output=True
+            )
+            download_mfa_models()
+        except Exception as e2:
+            logger.error(f"MFA 安装失败: {e2}")
+
+
+def download_mfa_models():
+    """下载 MFA 预训练模型"""
+    models = [
+        ("acoustic", "mandarin_mfa"),
+        ("dictionary", "mandarin_china_mfa"),
+    ]
+    
+    for model_type, model_name in models:
+        try:
+            logger.info(f"下载 MFA 模型: {model_type}/{model_name}")
+            subprocess.run(
+                ["mfa", "model", "download", model_type, model_name],
+                check=True,
+                capture_output=True,
+                timeout=300  # 5分钟超时
+            )
+        except Exception as e:
+            logger.warning(f"模型下载失败 {model_name}: {e}")
+
+
+def main():
+    """主入口"""
+    setup_environment()
+    
+    # 导入并启动 GUI
+    from src.gui import create_ui
+    
+    app = create_ui()
+    
+    # 云端配置
+    app.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False,
+        show_error=True,
+    )
+
+
+if __name__ == "__main__":
+    main()

deploy_schema.json

@@ -0,0 +1,112 @@
+{
+"$schema": "https://modelscope.cn/api/v1/studios/deploy_schema.json",
+"type": "object",
+"properties": {
+    "sdk_type": {
+    "type": "string",
+    "enum": ["gradio", "streamlit", "static", "docker"],
+    "description": "The application's frontend SDK or deployment mode. \n- **gradio**: Use this when the project uses the gradio framework. Requires an `app.py` in the repository root. Uses a base image and runs directly (no build step required). Requires specifying `sdk_version` and `base_image`. \n- **streamlit**: Use this when the project uses the streamlit framework. Requires an `app.py` in the repository root. Runs directly from a base image (no build step required). Requires specifying `base_image`. \n- **static**: Serves pre-built static files (e.g., HTML, CSS, JS) via Nginx, using the system's default environment. Cannot support projects that require a build step (e.g., Node.js projects). Requires an `index.html` in the repository root. **No build or compilation steps are performed**—files must already be built and committed to the repository. If your frontend requires building (e.g., via `npm run build`), use the `docker` mode instead. Requires specifying `base_image`. \n- **docker**: Builds and runs a custom container from a `Dockerfile` in the repository root. The resulting image must expose the service on `0.0.0.0:7860`. Does not use `sdk_version` or `base_image`; instead, `port` must be exactly `7860`. For projects where you’re unsure which other SDK types to use, `docker` is always recommended."
+    },
+    "sdk_version": {
+    "type": "string",
+    "enum": [
+        "3.29.0", "3.39.0", "3.47.1", "4.8.0", "4.14.0", "4.19.1", "4.31.3", "4.38.1",
+        "4.44.0", "5.3.0", "5.4.0", "5.12.0", "5.20.1", "5.29.0", "5.34.1", "5.42.0",
+        "5.49.1", "6.2.0"
+    ],
+    "default": "6.2.0",
+    "description": "Version of Gradio SDK. Required only when sdk_type is 'gradio'. Recommended to use the latest version."
+    },
+    "resource_configuration": {
+    "type": "string",
+    "enum": [
+        "platform/2v-cpu-16g-mem",
+        "xgpu/8v-cpu-32g-mem-16g",
+        "xgpu/8v-cpu-64g-mem-48g"
+    ],
+    "description": "Cloud instance type with predefined resources. The 'platform/2v-cpu-16g-mem' instance is available to all users at no cost. The 'xgpu' instances require eligibility and approval; see https://modelscope.cn/docs/studios/xGPU for details. Note: Resources from personal cloud accounts cannot be configured via this JSON schema. "
+    },
+    "base_image": {
+    "type": "string",
+    "enum": [
+        "ubuntu20.04-py37-torch1.11.0-tf1.15.5-modelscope1.6.1",
+        "ubuntu20.04-py38-torch1.11.0-tf1.15.5-modelscope1.6.1",
+        "ubuntu20.04-py38-torch2.0.1-tf1.15.5-modelscope1.8.1",
+        "ubuntu20.04-py38-torch2.0.1-tf2.13.0-modelscope1.9.5",
+        "ubuntu22.04-py310-torch2.1.0-tf2.14.0-modelscope1.10.0",
+        "ubuntu22.04-py310-torch2.1.2-tf2.14.0-modelscope1.13.1",
+        "ubuntu22.04-py310-torch2.1.2-tf2.14.0-modelscope1.13.3",
+        "ubuntu22.04-py310-torch2.1.2-tf2.14.0-modelscope1.14.0",
+        "ubuntu22.04-py310-torch2.3.0-modelscope1.15.0",
+        "ubuntu22.04-py310-torch2.3.0-modelscope1.16.1",
+        "ubuntu22.04-py310-torch2.3.0-modelscope1.17.1",
+        "ubuntu22.04-py310-torch2.3.0-modelscope1.18.0",
+        "ubuntu22.04-py310-torch2.3.0-modelscope1.19.2",
+        "ubuntu22.04-py310-torch2.3.1-modelscope1.20.0",
+        "ubuntu22.04-py310-torch2.3.1-modelscope1.21.0",
+        "ubuntu20.04-py310-paddle3.0.0-modelscope1.24.0",
+        "ubuntu22.04-py311-torch2.3.1-modelscope1.24.0",
+        "ubuntu22.04-py311-torch2.3.1-modelscope1.25.0",
+        "ubuntu22.04-cuda12.4.0-py311-torch2.6.0-modelscope1.25.0-LLM",
+        "ubuntu22.04-cuda12.4.0-py311-torch2.8.0-modelscope1.31.0-LLM",
+        "ubuntu22.04-py311-torch2.3.1-modelscope1.31.0"
+    ],
+    "default": "ubuntu22.04-py311-torch2.3.1-modelscope1.31.0",
+    "description": "Prebuilt runtime environment (Docker base image). Required for 'gradio', 'streamlit', and 'static' deployments. Not used for 'docker' type."
+    },
+    "environment_variables": {
+    "type": "array",
+    "items": {
+        "type": "object",
+        "properties": {
+        "name": { "type": "string" },
+        "value": { "type": "string" }
+        },
+        "required": ["name", "value"]
+    },
+    "description": "List of environment variables to inject at runtime. Please ensure the names and values of the environment variables required for runtime are provided directly here."
+    },
+    "port": {
+    "type": "integer",
+    "description": "The port the application listens on. Required only when sdk_type is 'docker', and must be exactly 7860."
+    }
+},
+"required": ["sdk_type", "resource_configuration"],
+"allOf": [
+    {
+    "if": {
+        "properties": { "sdk_type": { "const": "gradio" } },
+        "required": ["sdk_type"]
+    },
+    "then": {
+        "required": ["sdk_version", "base_image"]
+    }
+    },
+    {
+    "if": {
+        "properties": { "sdk_type": { "enum": ["streamlit", "static"] } },
+        "required": ["sdk_type"]
+    },
+    "then": {
+        "required": ["base_image"]
+    }
+    },
+    {
+    "if": {
+        "properties": { "sdk_type": { "const": "docker" } },
+        "required": ["sdk_type"]
+    },
+    "then": {
+        "not": {
+        "required": ["sdk_version"]
+        },
+        "required": ["port"],
+        "properties": {
+        "port": {
+            "const": 7860
+        }
+        }
+    }
+    }
+]
+}

docs/公开部署方案.md

@@ -1,5 +1,38 @@
 # 人力V助手 在线部署方案
 
+## 快速部署指南 (魔搭创空间)
+
+### 部署文件清单
+
+| 文件 | 说明 |
+|------|------|
+| `ms_deploy.json` | 魔搭创空间部署配置 |
+| `requirements_cloud.txt` | 云端依赖文件 |
+| `app.py` | 云端入口 (已就绪) |
+
+### 部署步骤
+
+1. **注册魔搭账号**: https://modelscope.cn
+2. **创建创空间**: 
+   - 进入「创空间」→「创建创空间」
+   - 选择「Gradio」类型
+   - 填写名称和描述
+3. **上传代码**:
+   - 方式一: 直接上传 zip 包
+   - 方式二: 关联 GitHub/Gitee 仓库
+4. **配置部署**:
+   - 上传 `ms_deploy.json` 或在界面配置
+   - 将 `requirements_cloud.txt` 重命名为 `requirements.txt` (或在部署时指定)
+5. **启动应用**: 点击「部署」等待构建完成
+
+### 注意事项
+
+- 首次启动需要下载模型，可能需要 5-10 分钟
+- 云端数据不持久，处理完成后请及时下载结果
+- 免费配额为 2vCPU/16GB 内存，适合小规模处理
+
+---
+
 ## 一、平台对比与选择
 
 | 平台 | 免费配额 | GPU | 存储 | 国内访问 | 推荐度 |

docs/流程文档_AI用.md

@@ -164,9 +164,11 @@
 
 | 模块 | 文件 | 功能 |
 |------|------|------|
-| MFA 运行器 | `mfa_runner.py` | 外挂模式调用 MFA 引擎 |
+| MFA 运行器 | `mfa_runner.py` | 跨平台调用 MFA 引擎 |
 
-MFA 采用 Sidecar Pattern，通过 subprocess 调用独立的 Python 环境 (`tools/mfa_engine`)，避免依赖冲突。
+MFA 支持两种运行模式:
+- **Windows**: Sidecar Pattern，通过 subprocess 调用独立的 Python 环境 (`tools/mfa_engine`)
+- **Linux**: 直接调用系统安装的 `mfa` 命令 (pip install montreal-forced-aligner)
 
 ### 4. 导出插件系统
 
@@ -218,7 +220,7 @@ MFA 采用 Sidecar Pattern，通过 subprocess 调用独立的 Python 环境 (`t
 
 ## 使用流程
 
-### 方式一: Web UI 界面
+### 方式一: 本地 Web UI
 
 1. 运行 `python main.py` 启动 Web UI
 2. 浏览器自动打开 http://127.0.0.1:7860
@@ -235,10 +237,21 @@ MFA 采用 Sidecar Pattern，通过 subprocess 调用独立的 Python 环境 (`t
    - 选择已制作的音源
    - 选择导出插件
    - 配置导出选项并执行
+   - 点击下载按钮获取结果
 
 > 注: 旧版 CustomTkinter 桌面 GUI 已移至 `src/gui_old.py`
 
-### 方式二: 命令行/脚本
+### 方式二: 云端部署 (HF Spaces / 魔塔社区)
+
+1. 使用 `app.py` 作为入口文件
+2. 云端环境自动安装 MFA 和下载模型
+3. 处理完成后通过下载按钮获取结果 (云端数据不持久)
+
+支持的云平台:
+- Hugging Face Spaces (Gradio SDK)
+- 魔塔社区 ModelScope (推荐，国内访问快)
+
+### 方式三: 命令行/脚本
 
 ```python
 from src.pipeline import PipelineConfig, VoiceBankPipeline
@@ -273,5 +286,47 @@ success, msg = pipeline.run_make_pipeline()
 > 注: 旧版桌面 GUI 使用 `customtkinter`，代码保留在 `src/gui_old.py`
 
 MFA 环境:
-- 独立打包在 `tools/mfa_engine/`
-- 包含 Python 3.11 + montreal-forced-aligner
+- **Windows**: 独立打包在 `tools/mfa_engine/`，包含 Python 3.11 + montreal-forced-aligner
+- **Linux**: 通过 pip 安装 `montreal-forced-aligner`
+
+## 云端部署说明
+
+### 目录结构 (云端)
+
+```
+项目根目录/
+├── app.py                  # 云端入口 (自动初始化环境)
+├── main.py                 # 本地入口
+├── requirements.txt
+├── src/
+│   ├── gui.py              # 支持云端环境检测和下载功能
+│   ├── mfa_runner.py       # 跨平台 MFA 调用
+│   └── ...
+└── ...
+```
+
+### 平台差异
+
+| 功能 | 本地 (Windows) | 云端 (Linux) |
+|------|----------------|--------------|
+| MFA 调用 | tools/mfa_engine 外挂 | 系统 mfa 命令 |
+| 数据存储 | 本地持久化 | 临时目录，需下载 |
+| GPU 加速 | 本地显卡 | 取决于平台配置 |
+| 模型缓存 | models/ 目录 | 首次运行自动下载 |
+
+### 魔搭创空间部署配置
+
+部署配置文件 `ms_deploy.json`:
+```json
+{
+  "sdk_type": "gradio",
+  "sdk_version": "6.2.0",
+  "resource_configuration": "platform/2v-cpu-16g-mem",
+  "base_image": "ubuntu22.04-py311-torch2.3.1-modelscope1.31.0"
+}
+```
+
+云端依赖文件 `requirements_cloud.txt`:
+- 移除 Windows 专用依赖 (customtkinter)
+- 添加 `montreal-forced-aligner` (Linux pip 安装)
+- 保持 gradio 版本与 sdk_version 一致

ms_deploy.json

@@ -0,0 +1,20 @@
+{
+  "sdk_type": "gradio",
+  "sdk_version": "6.2.0",
+  "resource_configuration": "platform/2v-cpu-16g-mem",
+  "base_image": "ubuntu22.04-py311-torch2.3.1-modelscope1.31.0",
+  "environment_variables": [
+    {
+      "name": "MODELSCOPE_SPACE",
+      "value": "true"
+    },
+    {
+      "name": "GRADIO_SERVER_NAME",
+      "value": "0.0.0.0"
+    },
+    {
+      "name": "GRADIO_SERVER_PORT",
+      "value": "7860"
+    }
+  ]
+}

requirements_cloud.txt

@@ -0,0 +1,30 @@
+# 魔搭创空间云端依赖
+# 基于 requirements.in，移除本地专用依赖，添加云端必需依赖
+
+# GUI框架 (与 ms_deploy.json 中 sdk_version 保持一致)
+gradio==6.2.0
+
+# Whisper 语音识别
+transformers>=4.25.0
+torch
+torchaudio
+accelerate
+
+# Silero VAD 语音活动检测
+silero-vad>=5.1
+onnxruntime
+
+# 音频处理
+textgrid
+audiofile
+soundfile
+
+# 文本处理
+pypinyin
+pykakasi
+
+# 工具
+tqdm
+
+# MFA 强制对齐 (Linux 环境通过 pip 安装)
+montreal-forced-aligner

src/gui.py

@@ -2,6 +2,7 @@
 """
 人力V助手 (JinrikiHelper) Web UI
 基于 Gradio 6.2.0 构建
+支持本地运行和云端部署 (HF Spaces / 魔塔社区)
 作者：TNOT
 """
 
@@ -11,9 +12,19 @@ import logging
 import os
 import sys
 import json
+import platform
+import tempfile
+import zipfile
+import shutil
 from pathlib import Path
 from typing import Optional, List, Dict, Callable
 
+# 环境检测
+IS_CLOUD = any([
+    os.environ.get("SPACE_ID"),           # Hugging Face Spaces
+    os.environ.get("MODELSCOPE_SPACE"),   # 魔塔社区
+])
+
 # 配置日志
 logging.basicConfig(
     level=logging.INFO,
@@ -382,14 +393,42 @@ def run_full_pipeline(source_name: str, input_path: str, output_dir: str,
 
 # ==================== 导出音源功能 ====================
 
+def create_download_zip(source_dir: str, zip_name: str) -> Optional[str]:
+    """
+    打包目录为 zip 文件供下载
+    
+    参数:
+        source_dir: 要打包的目录
+        zip_name: zip 文件名 (不含扩展名)
+    
+    返回:
+        zip 文件路径，失败返回 None
+    """
+    if not os.path.isdir(source_dir):
+        return None
+    
+    try:
+        zip_path = os.path.join(tempfile.gettempdir(), f"{zip_name}.zip")
+        with zipfile.ZipFile(zip_path, 'w', zipfile.ZIP_DEFLATED) as zf:
+            for root, dirs, files in os.walk(source_dir):
+                for file in files:
+                    file_path = os.path.join(root, file)
+                    arcname = os.path.relpath(file_path, source_dir)
+                    zf.write(file_path, arcname)
+        return zip_path
+    except Exception as e:
+        logger.error(f"打包失败: {e}")
+        return None
+
+
 def run_export(voice_bank: str, plugin_name: str, options: dict, progress=gr.Progress()):
     """执行导出"""
     if not voice_bank or voice_bank.startswith("("):
-        return "❌ 请选择有效的音源", ""
+        return "❌ 请选择有效的音源", "", None
     
     plugins = load_export_plugins()
     if plugin_name not in plugins:
-        return f"❌ 未找到插件: {plugin_name}", ""
+        return f"❌ 未找到插件: {plugin_name}", "", None
     
     plugin = plugins[plugin_name]
     bank_dir = config_manager.get("bank_dir")
@@ -406,14 +445,38 @@ def run_export(voice_bank: str, plugin_name: str, options: dict, progress=gr.Pro
     success, msg = plugin.export(voice_bank, bank_dir, options)
     progress(1, desc="完成")
     
+    download_file = None
     if success:
         log_callback(f"✅ {msg}")
+        # 打包导出结果供下载
+        export_dir = os.path.join(
+            os.path.dirname(bank_dir), "export", voice_bank, plugin_name.replace(" ", "_")
+        )
+        if os.path.isdir(export_dir):
+            zip_name = f"{voice_bank}_{plugin_name.replace(' ', '_')}"
+            download_file = create_download_zip(export_dir, zip_name)
+            if download_file:
+                log_callback(f"📦 已打包: {os.path.basename(download_file)}")
     else:
         log_callback(f"❌ {msg}")
     log_callback("=" * 50)
     
     status = "✅ 导出完成" if success else f"❌ {msg}"
-    return status, "\n".join(logs)
+    return status, "\n".join(logs), download_file
+
+
+def download_voice_bank(voice_bank: str) -> Optional[str]:
+    """打包音源数据供下载"""
+    if not voice_bank or voice_bank.startswith("("):
+        return None
+    
+    bank_dir = config_manager.get("bank_dir")
+    source_dir = os.path.join(bank_dir, voice_bank)
+    
+    if not os.path.isdir(source_dir):
+        return None
+    
+    return create_download_zip(source_dir, f"{voice_bank}_音源数据")
 
 
 # ==================== 构建界面 ====================
@@ -427,11 +490,25 @@ def create_ui():
     dict_files = mfa_models["dictionary"] if mfa_models["dictionary"] else ["(未找到字典文件)"]
     acoustic_files = mfa_models["acoustic"] if mfa_models["acoustic"] else ["(未找到声学模型)"]
     voice_banks = scan_voice_banks()
-    mfa_status = "✅ MFA 环境已就绪" if check_mfa_available() else "❌ MFA 环境不可用，请检查 tools/mfa_engine"
+    
+    # MFA 状态检测 (区分平台)
+    if check_mfa_available():
+        mfa_status = "✅ MFA 环境已就绪"
+    elif platform.system() == "Windows":
+        mfa_status = "❌ MFA 环境不可用，请检查 tools/mfa_engine"
+    else:
+        mfa_status = "❌ MFA 未安装，请运行: pip install montreal-forced-aligner"
+    
+    # 云端环境提示
+    env_notice = ""
+    if IS_CLOUD:
+        env_notice = "> ☁️ 当前为云端环境，处理完成后请及时下载结果"
     
     with gr.Blocks(title="人力V助手 (JinrikiHelper)") as app:
         gr.Markdown("# 🎤 人力V助手 (JinrikiHelper)")
         gr.Markdown("语音数据集处理工具 - 自动化制作语音音源库")
+        if env_notice:
+            gr.Markdown(env_notice)
         
         with gr.Tabs():
             # ==================== 模型下载页 ====================
@@ -661,10 +738,27 @@ def create_ui():
                 export_status = gr.Textbox(label="状态", interactive=False)
                 export_log = gr.Textbox(label="日志输出", lines=8, interactive=False)
                 
+                # 下载区域
+                gr.Markdown("---")
+                gr.Markdown("### 下载结果")
+                with gr.Row():
+                    export_download = gr.File(label="导出结果下载", interactive=False)
+                    bank_download_btn = gr.Button("📥 下载音源数据", variant="secondary")
+                bank_download = gr.File(label="音源数据下载", interactive=False)
+                
+                if IS_CLOUD:
+                    gr.Markdown("> 💡 云端环境数据不会持久保存，请及时下载处理结果")
+                
                 export_btn.click(
                     fn=run_export,
                     inputs=[voice_bank_select, plugin_select, plugin_options],
-                    outputs=[export_status, export_log]
+                    outputs=[export_status, export_log, export_download]
+                )
+                
+                bank_download_btn.click(
+                    fn=download_voice_bank,
+                    inputs=[voice_bank_select],
+                    outputs=[bank_download]
                 )
             
             # ==================== 设置页 ====================

src/mfa_runner.py

@@ -1,10 +1,12 @@
 # -*- coding: utf-8 -*-
 """
-MFA 外挂调用模块
-采用 Sidecar Pattern，通过 subprocess 调用独立的 MFA 环境
+MFA 调用模块
+支持 Windows (外挂模式) 和 Linux (系统安装) 双平台
 """
 
 import os
+import platform
+import shutil
 import subprocess
 import logging
 from pathlib import Path
@@ -22,30 +24,75 @@ DEFAULT_DICT_PATH = BASE_DIR / "models" / "mandarin.dict"
 DEFAULT_MODEL_PATH = BASE_DIR / "models" / "mandarin.zip"
 DEFAULT_TEMP_DIR = BASE_DIR / "mfa_temp"
 
+# 平台检测
+IS_WINDOWS = platform.system() == "Windows"
+
 
 def check_mfa_available() -> bool:
-    """检查 MFA 外挂环境是否可用"""
-    if not MFA_ENGINE_DIR.exists():
-        logger.warning(f"MFA 引擎目录不存在: {MFA_ENGINE_DIR}")
-        return False
-    if not MFA_PYTHON.exists():
-        logger.warning(f"MFA Python 不存在: {MFA_PYTHON}")
+    """
+    检查 MFA 是否可用
+    Windows: 检查外挂 Python 环境
+    Linux: 检查系统 mfa 命令
+    """
+    if IS_WINDOWS:
+        if not MFA_ENGINE_DIR.exists():
+            logger.warning(f"MFA 引擎目录不存在: {MFA_ENGINE_DIR}")
+            return False
+        if not MFA_PYTHON.exists():
+            logger.warning(f"MFA Python 不存在: {MFA_PYTHON}")
+            return False
+        return True
+    else:
+        # Linux/macOS: 检查系统命令
+        mfa_path = shutil.which("mfa")
+        if mfa_path:
+            logger.info(f"找到系统 MFA: {mfa_path}")
+            return True
+        # 尝试检查 conda 环境中的 mfa
+        try:
+            result = subprocess.run(
+                ["mfa", "version"],
+                capture_output=True,
+                text=True,
+                timeout=10
+            )
+            if result.returncode == 0:
+                logger.info(f"MFA 版本: {result.stdout.strip()}")
+                return True
+        except Exception as e:
+            logger.warning(f"MFA 检查失败: {e}")
         return False
-    return True
+
+
+def _get_mfa_command() -> list:
+    """
+    获取 MFA 命令前缀
+    Windows: 使用外挂 Python 调用
+    Linux: 直接使用 mfa 命令
+    """
+    if IS_WINDOWS:
+        return [str(MFA_PYTHON), "-m", "montreal_forced_aligner"]
+    else:
+        return ["mfa"]
 
 
 def _build_mfa_env() -> dict:
     """构造 MFA 专用环境变量"""
     env = os.environ.copy()
     
-    # 必须把 Library\bin 加入 PATH，否则 Kaldi DLL 找不到
-    mfa_paths = [
-        str(MFA_ENGINE_DIR),
-        str(MFA_ENGINE_DIR / "Library" / "bin"),
-        str(MFA_ENGINE_DIR / "Scripts"),
-        str(MFA_ENGINE_DIR / "bin"),
-    ]
-    env["PATH"] = ";".join(mfa_paths) + ";" + env.get("PATH", "")
+    if IS_WINDOWS:
+        # Windows: 必须把 Library\bin 加入 PATH，否则 Kaldi DLL 找不到
+        mfa_paths = [
+            str(MFA_ENGINE_DIR),
+            str(MFA_ENGINE_DIR / "Library" / "bin"),
+            str(MFA_ENGINE_DIR / "Scripts"),
+            str(MFA_ENGINE_DIR / "bin"),
+        ]
+        env["PATH"] = ";".join(mfa_paths) + ";" + env.get("PATH", "")
+    else:
+        # Linux: 确保 conda 环境变量正确
+        # 通常不需要额外设置，但保留扩展点
+        pass
     
     return env
 
@@ -83,7 +130,8 @@ def run_mfa_alignment(
     
     # 检查环境
     if not check_mfa_available():
-        return False, "MFA 外挂环境不可用，请检查 tools/mfa_engine 目录"
+        platform_hint = "tools/mfa_engine 目录" if IS_WINDOWS else "pip install montreal-forced-aligner"
+        return False, f"MFA 环境不可用，请检查 {platform_hint}"
     
     # 设置默认路径
     dict_path = dict_path or str(DEFAULT_DICT_PATH)
@@ -103,24 +151,26 @@ def run_mfa_alignment(
     os.makedirs(temp_dir, exist_ok=True)
     
     # 构造命令
-    cmd = [
-        str(MFA_PYTHON),
-        "-m", "montreal_forced_aligner",
+    cmd = _get_mfa_command() + [
         "align",
         str(corpus_dir),
         str(dict_path),
         str(model_path),
         str(output_dir),
         "--temp_directory", str(temp_dir),
-        "--use_mp", "false",  # 禁用多进程，避免Windows问题
     ]
     
+    # Windows 禁用多进程避免问题，Linux 可以启用
+    if IS_WINDOWS:
+        cmd.extend(["--use_mp", "false"])
+    
     if clean:
         cmd.append("--clean")
     if single_speaker:
         cmd.append("--single_speaker")
     
     log(f"正在启动 MFA 对齐引擎...")
+    log(f"运行平台: {'Windows (外挂模式)' if IS_WINDOWS else 'Linux (系统安装)'}")
     log(f"输入目录: {corpus_dir}")
     log(f"输出目录: {output_dir}")
     
@@ -145,7 +195,7 @@ def run_mfa_alignment(
             return False, error_msg
             
     except FileNotFoundError as e:
-        msg = f"找不到 MFA Python: {e}"
+        msg = f"找不到 MFA 命令: {e}"
         log(msg)
         return False, msg
     except Exception as e:
@@ -176,13 +226,11 @@ def run_mfa_validate(
             progress_callback(msg)
     
     if not check_mfa_available():
-        return False, "MFA 外挂环境不可用"
+        return False, "MFA 环境不可用"
     
     dict_path = dict_path or str(DEFAULT_DICT_PATH)
     
-    cmd = [
-        str(MFA_PYTHON),
-        "-m", "montreal_forced_aligner",
+    cmd = _get_mfa_command() + [
         "validate",
         str(corpus_dir),
         str(dict_path),
@@ -207,3 +255,83 @@ def run_mfa_validate(
         
     except Exception as e:
         return False, str(e)
+
+
+def install_mfa_model(
+    model_type: str,
+    model_name: str,
+    progress_callback: Optional[Callable[[str], None]] = None
+) -> tuple[bool, str]:
+    """
+    下载 MFA 预训练模型 (仅 Linux 支持)
+    
+    参数:
+        model_type: 模型类型 ("acoustic" 或 "dictionary")
+        model_name: 模型名称 (如 "mandarin_mfa", "mandarin_china_mfa")
+        progress_callback: 进度回调函数
+    
+    返回:
+        (成功标志, 输出信息)
+    """
+    def log(msg: str):
+        logger.info(msg)
+        if progress_callback:
+            progress_callback(msg)
+    
+    if IS_WINDOWS:
+        return False, "Windows 平台请手动下载模型文件"
+    
+    if not check_mfa_available():
+        return False, "MFA 环境不可用"
+    
+    cmd = _get_mfa_command() + [
+        "model", "download", model_type, model_name
+    ]
+    
+    log(f"正在下载 MFA 模型: {model_type}/{model_name}")
+    
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            encoding='utf-8',
+            errors='replace'
+        )
+        
+        if result.returncode == 0:
+            log(f"模型下载完成: {model_name}")
+            return True, result.stdout
+        else:
+            error_msg = result.stderr or result.stdout or "未知错误"
+            log(f"模型下载失败: {error_msg}")
+            return False, error_msg
+            
+    except Exception as e:
+        return False, str(e)
+
+
+def get_mfa_model_path(model_type: str, model_name: str) -> Optional[str]:
+    """
+    获取 MFA 模型路径
+    Linux: 返回 MFA 内置模型名称 (mfa 会自动查找)
+    Windows: 返回本地文件路径
+    
+    参数:
+        model_type: 模型类型 ("acoustic" 或 "dictionary")
+        model_name: 模型名称
+    
+    返回:
+        模型路径或名称，不存在返回 None
+    """
+    if IS_WINDOWS:
+        # Windows: 使用本地文件
+        mfa_dir = BASE_DIR / "models" / "mfa"
+        if model_type == "acoustic":
+            path = mfa_dir / f"{model_name}.zip"
+        else:
+            path = mfa_dir / f"{model_name}.dict"
+        return str(path) if path.exists() else None
+    else:
+        # Linux: 直接返回模型名称，mfa 会从缓存中查找
+        return model_name