feat: 添加 WebUI 静态资源包提示和相关错误处理逻辑

Author: DrSmoothl

locales/en-US/startup.json

@@ -80,13 +80,15 @@
   "startup.webui_auto_build_tool_missing": "❌ No supported frontend build tool was found, cannot auto-build WebUI",
   "startup.webui_cors_configured": "✅ CORS middleware configured",
   "startup.webui_dashboard_source_missing": "❌ WebUI frontend source directory not found: {dashboard_root}",
+  "startup.webui_dashboard_package_hint": "💡 Install the prebuilt WebUI static asset package first, for example: {command}",
   "startup.webui_disabled": "WebUI is disabled",
   "startup.webui_index_missing": "❌ index.html not found: {index_path}",
   "startup.webui_manual_build_hint": "💡 Automatic recovery could not restore the frontend assets. Install dependencies and build manually in the dashboard directory: {command}",
   "startup.webui_path_traversal_detected": "🚫 Suspicious path traversal request detected: {full_path}",
   "startup.webui_robots_route_register_failed": "❌ Failed to register robots.txt route: {error}",
   "startup.webui_robots_route_registered": "✅ robots.txt route registered",
   "startup.webui_server_init_failed": "Failed to initialize WebUI server: {error}",
+  "startup.webui_static_assets_unavailable": "❌ No usable WebUI static assets were found (installed maibot-dashboard package or local dashboard/dist)",
   "startup.webui_static_assets_try_auto_build": "⚠️ WebUI static assets are unavailable, attempting to auto-build the frontend...",
   "startup.webui_static_dir_missing": "❌ WebUI static directory does not exist",
   "startup.webui_static_dir_missing_with_path": "❌ WebUI static directory does not exist: {static_path}",

locales/ja-JP/startup.json

@@ -80,13 +80,15 @@
   "startup.webui_auto_build_tool_missing": "❌ 利用可能なフロントエンドビルドツールが見つからず、WebUI を自動ビルドできません",
   "startup.webui_cors_configured": "✅ CORS ミドルウェアを設定しました",
   "startup.webui_dashboard_source_missing": "❌ WebUI フロントエンドのソースディレクトリが見つかりません: {dashboard_root}",
+  "startup.webui_dashboard_package_hint": "💡 事前ビルド済みの WebUI 静的リソースパッケージを先にインストールしてください。例: {command}",
   "startup.webui_disabled": "WebUI は無効です",
   "startup.webui_index_missing": "❌ index.html が見つかりません: {index_path}",
   "startup.webui_manual_build_hint": "💡 自動復旧でフロントエンド資産を復旧できなかったため、dashboard ディレクトリで依存関係をインストールして手動ビルドしてください: {command}",
   "startup.webui_path_traversal_detected": "🚫 パストラバーサルの疑いがあるリクエストを検出しました: {full_path}",
   "startup.webui_robots_route_register_failed": "❌ robots.txt ルートの登録に失敗しました: {error}",
   "startup.webui_robots_route_registered": "✅ robots.txt ルートを登録しました",
   "startup.webui_server_init_failed": "WebUI サーバーの初期化に失敗しました: {error}",
+  "startup.webui_static_assets_unavailable": "❌ 利用可能な WebUI 静的アセットが見つかりません（インストール済みの maibot-dashboard パッケージまたはローカルの dashboard/dist）",
   "startup.webui_static_assets_try_auto_build": "⚠️ WebUI の静的アセットが利用できないため、フロントエンドの自動ビルドを試行します...",
   "startup.webui_static_dir_missing": "❌ WebUI の静的ディレクトリが存在しません",
   "startup.webui_static_dir_missing_with_path": "❌ WebUI の静的ディレクトリが存在しません: {static_path}",

locales/ko/startup.json

@@ -80,13 +80,15 @@
   "startup.webui_auto_build_tool_missing": "❌ 사용 가능한 프론트엔드 빌드 도구를 찾을 수 없어 WebUI를 자동으로 빌드할 수 없습니다",
   "startup.webui_cors_configured": "✅ CORS 미들웨어 설정 완료",
   "startup.webui_dashboard_source_missing": "❌ WebUI 프론트엔드 소스 디렉터리를 찾을 수 없습니다: {dashboard_root}",
+  "startup.webui_dashboard_package_hint": "💡 미리 빌드된 WebUI 정적 리소스 패키지를 먼저 설치하세요. 예: {command}",
   "startup.webui_disabled": "WebUI가 비활성화되었습니다",
   "startup.webui_index_missing": "❌ index.html을 찾을 수 없습니다: {index_path}",
   "startup.webui_manual_build_hint": "💡 자동 복구로 프론트엔드 리소스를 수정하지 못했습니다. dashboard 디렉터리에서 의존성을 설치하고 수동으로 빌드하세요: {command}",
   "startup.webui_path_traversal_detected": "🚫 경로 탐색 공격이 의심되는 요청 감지됨: {full_path}",
   "startup.webui_robots_route_register_failed": "❌ robots.txt 라우트 등록 실패: {error}",
   "startup.webui_robots_route_registered": "✅ robots.txt 라우트 등록 완료",
   "startup.webui_server_init_failed": "WebUI 서버 초기화 실패: {error}",
+  "startup.webui_static_assets_unavailable": "❌ 사용할 수 있는 WebUI 정적 리소스를 찾을 수 없습니다(설치된 maibot-dashboard 패키지 또는 로컬 dashboard/dist)",
   "startup.webui_static_assets_try_auto_build": "⚠️ WebUI 정적 리소스를 사용할 수 없어 프론트엔드 자동 빌드를 시도합니다...",
   "startup.webui_static_dir_missing": "❌ WebUI 정적 파일 디렉터리가 존재하지 않습니다",
   "startup.webui_static_dir_missing_with_path": "❌ WebUI 정적 파일 디렉터리가 존재하지 않습니다: {static_path}",

locales/zh-CN/startup.json

@@ -80,13 +80,15 @@
   "startup.webui_auto_build_tool_missing": "❌ 未找到可用的前端构建工具，无法自动构建 WebUI",
   "startup.webui_cors_configured": "✅ CORS 中间件已配置",
   "startup.webui_dashboard_source_missing": "❌ 未找到 WebUI 前端源码目录: {dashboard_root}",
+  "startup.webui_dashboard_package_hint": "💡 请安装预构建的 WebUI 静态资源包，例如: {command}",
   "startup.webui_disabled": "WebUI 已禁用",
   "startup.webui_index_missing": "❌ 未找到 index.html: {index_path}",
   "startup.webui_manual_build_hint": "💡 自动恢复未能修复前端资源，请在 dashboard 目录安装依赖并手动构建: {command}",
   "startup.webui_path_traversal_detected": "🚫 检测到疑似路径穿越请求: {full_path}",
   "startup.webui_robots_route_register_failed": "❌ 注册 robots.txt 路由失败: {error}",
   "startup.webui_robots_route_registered": "✅ robots.txt 路由已注册",
   "startup.webui_server_init_failed": "初始化 WebUI 服务器失败: {error}",
+  "startup.webui_static_assets_unavailable": "❌ 未找到可用的 WebUI 静态资源（已安装的 maibot-dashboard 包或本地 dashboard/dist）",
   "startup.webui_static_assets_try_auto_build": "⚠️ WebUI 静态资源不可用，尝试自动构建前端...",
   "startup.webui_static_dir_missing": "❌ WebUI 静态文件目录不存在",
   "startup.webui_static_dir_missing_with_path": "❌ WebUI 静态文件目录不存在: {static_path}",

pyproject.toml

@@ -19,6 +19,7 @@ dependencies = [
     "jieba>=0.42.1",
     "json-repair>=0.47.6",
     "maim-message>=0.6.2",
+    "maibot-dashboard==1.0.0.dev2026040439",
     "maibot-plugin-sdk>=2.3.0",
     "mcp",
     "msgpack>=1.1.2",

pytests/webui/test_app.py

@@ -1,3 +1,4 @@
+from pathlib import Path
 from unittest.mock import patch
 
 import pytest
@@ -10,54 +11,42 @@ def test_ensure_static_path_ready_uses_existing_static_path(tmp_path) -> None:
     static_path.mkdir()
     (static_path / "index.html").write_text("<html></html>", encoding="utf-8")
 
-    with (
-        patch.object(webui_app, "_resolve_static_path", return_value=static_path),
-        patch.object(webui_app, "_try_build_dashboard") as build_mock,
-    ):
+    with patch.object(webui_app, "_resolve_static_path", return_value=static_path):
         result = webui_app._ensure_static_path_ready()
 
     assert result == static_path
-    build_mock.assert_not_called()
-
 
-def test_ensure_static_path_ready_retries_after_auto_build(tmp_path) -> None:
-    static_path = tmp_path / "dist"
-    static_path.mkdir()
-    (static_path / "index.html").write_text("<html></html>", encoding="utf-8")
 
+def test_ensure_static_path_ready_logs_install_hint_when_static_assets_are_missing() -> None:
     with (
-        patch.object(webui_app, "_resolve_static_path", side_effect=[None, static_path]),
-        patch.object(
-            webui_app,
-            "_try_build_dashboard",
-            return_value=webui_app.DashboardAutoRecoveryResult(succeeded=True),
-        ) as build_mock,
+        patch.object(webui_app, "_resolve_static_path", return_value=None),
+        patch.object(webui_app.logger, "warning") as warning_mock,
     ):
         result = webui_app._ensure_static_path_ready()
 
-    assert result == static_path
-    build_mock.assert_called_once_with()
+    assert result is None
+    warning_mock.assert_any_call(webui_app.t("startup.webui_static_assets_unavailable"))
+    warning_mock.assert_any_call(
+        webui_app.t("startup.webui_dashboard_package_hint", command=webui_app._MANUAL_INSTALL_COMMAND)
+    )
 
 
-def test_ensure_static_path_ready_logs_manual_hint_when_auto_build_fails() -> None:
+def test_ensure_static_path_ready_logs_index_error_when_static_path_is_invalid(tmp_path) -> None:
+    static_path = tmp_path / "dist"
+    static_path.mkdir()
+
     with (
-        patch.object(webui_app, "_resolve_static_path", return_value=None),
-        patch.object(
-            webui_app,
-            "_try_build_dashboard",
-            return_value=webui_app.DashboardAutoRecoveryResult(
-                succeeded=False,
-                manual_recovery_command=webui_app._MANUAL_BUILD_COMMAND,
-            ),
-        ),
+        patch.object(webui_app, "_resolve_static_path", return_value=static_path),
         patch.object(webui_app.logger, "warning") as warning_mock,
     ):
         result = webui_app._ensure_static_path_ready()
 
     assert result is None
-    warning_mock.assert_any_call(webui_app.t("startup.webui_auto_recovery_failed"))
     warning_mock.assert_any_call(
-        webui_app.t("startup.webui_manual_build_hint", command=webui_app._MANUAL_BUILD_COMMAND)
+        webui_app.t("startup.webui_index_missing", index_path=static_path / "index.html")
+    )
+    warning_mock.assert_any_call(
+        webui_app.t("startup.webui_dashboard_package_hint", command=webui_app._MANUAL_INSTALL_COMMAND)
     )
 
 
@@ -73,43 +62,21 @@ def test_setup_static_files_does_not_duplicate_warning_when_static_path_is_unava
     warning_mock.assert_not_called()
 
 
-def test_get_dashboard_build_command_defaults_to_npm(tmp_path) -> None:
-    (tmp_path / "package.json").write_text("{}", encoding="utf-8")
+def test_resolve_static_path_prefers_installed_dashboard_package(monkeypatch, tmp_path) -> None:
+    package_dist = tmp_path / "site-packages" / "maibot_dashboard" / "dist"
+    package_dist.mkdir(parents=True)
 
-    with patch.object(
-        webui_app.shutil,
-        "which",
-        side_effect=lambda tool_name: "/usr/bin/npm" if tool_name == "npm" else None,
-    ):
-        command = webui_app._get_dashboard_build_command(tmp_path)
+    class _DashboardModule:
+        @staticmethod
+        def get_dist_path() -> Path:
+            return package_dist
 
-    assert command == ["npm", "run", "build"]
-
-
-def test_try_build_dashboard_installs_missing_dependencies_before_build(monkeypatch, tmp_path) -> None:
-    (tmp_path / "package.json").write_text("{}", encoding="utf-8")
-    run_results = [
-        webui_app.CompletedProcess(args=["npm", "install", "--no-package-lock"], returncode=0, stdout="", stderr=""),
-        webui_app.CompletedProcess(args=["npm", "run", "build"], returncode=0, stdout="", stderr=""),
-    ]
+    monkeypatch.setattr(webui_app, "_get_project_root", lambda: tmp_path)
 
-    monkeypatch.setattr(webui_app, "_get_dashboard_root", lambda: tmp_path)
-    monkeypatch.setattr(webui_app, "_should_auto_install_dashboard_dependencies", lambda dashboard_root: True)
+    with patch.object(webui_app, "import_module", return_value=_DashboardModule()):
+        resolved_path = webui_app._resolve_static_path()
 
-    with (
-        patch.object(webui_app, "_get_dashboard_build_command", return_value=["npm", "run", "build"]),
-        patch.object(webui_app, "run", side_effect=run_results) as run_mock,
-    ):
-        result = webui_app._try_build_dashboard()
-
-    assert result.succeeded is True
-    assert run_mock.call_count == 2
-    install_call = run_mock.call_args_list[0]
-    build_call = run_mock.call_args_list[1]
-    assert install_call.args[0] == ["npm", "install", "--no-package-lock"]
-    assert install_call.kwargs["cwd"] == tmp_path
-    assert build_call.args[0] == ["npm", "run", "build"]
-    assert build_call.kwargs["cwd"] == tmp_path
+    assert resolved_path == package_dist
 
 
 def test_resolve_static_path_uses_dashboard_dist(monkeypatch, tmp_path) -> None: