modelscope · alcholiclg · Aug 12, 2026 · Aug 4, 2026 · Aug 4, 2026 · Aug 4, 2026
diff --git a/.env.example b/.env.example
@@ -0,0 +1,59 @@
+# Shared provider credentials for the whole repository.
+#
+#   cp .env.example .env      # then fill in only the providers you use
+#
+# This file is the FIRST of three dotenv layers the WebUI backend reads
+# (webui/backend/app/core/settings.py); later files override earlier ones and a
+# real process environment variable always wins:
+#
+#   1. <repo>/.env               <- this file: shared credentials
+#   2. webui/.env                <- optional, WebUI-wide overrides
+#   3. webui/backend/.env        <- backend-only settings (see .env.example there)
+#
+# Every value below is also published into os.environ at startup, which is where
+# the SDK's credential resolver and MCP `${VAR}` placeholders read from.
+#
+# Tags: [required] must be set for that provider to work · [optional] has a
+# usable default. Leave a provider blank to simply not use it.
+#
+# WARNING: .env is git-ignored, but the SDK also writes resolved credentials in
+# plaintext into <MS_AGENT_HOME>/settings.json. Never share that directory.
+
+# --- OpenAI-compatible default -------------------------------------------
+# [optional] Consumed by the WebUI bootstrap ONLY when
+# MS_AGENT_LLM_PROVIDER=openai. Point it at OpenAI itself, or at any
+# OpenAI-compatible gateway together with OPENAI_BASE_URL.
+OPENAI_API_KEY=
+OPENAI_BASE_URL=
+
+# --- Alibaba DashScope (Qwen) --------------------------------------------
+# [optional] Default pairing in webui/backend/.env.example
+# (MS_AGENT_LLM_PROVIDER=dashscope + MS_AGENT_LLM_MODEL=qwen3.7-plus).
+DASHSCOPE_API_KEY=
+DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
+
+# --- ModelScope ------------------------------------------------------------
+MODELSCOPE_API_KEY=
+MODELSCOPE_BASE_URL=https://api-inference.modelscope.cn/v1
+
+# --- Other OpenAI-protocol providers --------------------------------------
+# [optional] Each is picked up by the SDK's credential resolver by name, so
+# setting a key is all that is needed to select that provider in the UI.
+DEEPSEEK_API_KEY=
+DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
+GLM_API_KEY=
+GLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
+KIMI_API_KEY=
+KIMI_BASE_URL=https://api.moonshot.cn/v1
+MINIMAX_API_KEY=
+MINIMAX_BASE_URL=https://api.minimax.chat/v1
+
+# --- Anthropic -------------------------------------------------------------
+# [optional] Also used by any provider whose `protocol` is set to "anthropic"
+# (e.g. a DeepSeek /anthropic gateway).
+ANTHROPIC_API_KEY=
+
+# --- Tools -----------------------------------------------------------------
+# [optional] Required only by the built-in web_search tool (Exa), which stays
+# disabled until a key is present.
+EXA_API_KEY=
diff --git a/.gitignore b/.gitignore
@@ -20,6 +20,9 @@ eggs/
 .eggs/
 lib/
 lib64/
+# The WebUI uses `app/lib` for checked-in TypeScript application code.
+!webui/frontend/app/lib/
+!webui/frontend/app/lib/**
 parts/
 sdist/
 var/
@@ -58,6 +61,7 @@ nosetests.xml
 coverage.xml
 *.cover
 *node_modules*
+.react-router/
 .hypothesis/
 .pytest_cache/
 
@@ -89,6 +93,9 @@ target/
 
 # pyenv
 .python-version
+# uv reads this to pin the WebUI backend to CPython 3.12. Without it uv only
+# honours requires-python (">=3.12") and can build the venv on 3.13/3.14.
+!webui/backend/.python-version
 
 # celery beat schedule file
 celerybeat-schedule
@@ -172,4 +179,9 @@ webui/work_dir/
 .ms_agent_snapshots/
 .ms_agent/
 
-webui/frontend/.react-router
+# React Router's generated route/type artefacts.
+webui/frontend/.react-router
+
+# Chrome DevTools probes this exact path on every page load; ignore the
+# file it asks for so a local 404-silencer never gets committed again.
+webui/frontend/public/.well-known/appspecific/com.chrome.devtools.json
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -7,11 +7,8 @@ recursive-include ms_agent/ *.yaml
 # Include projects
 recursive-include projects *
 
-# Include webui backend
-recursive-include webui/backend *.py
-
-# Include webui frontend dist (will be built during setup)
-recursive-include webui/frontend/dist *
+# The SSR WebUI is intentionally run from a Git source checkout. It is not
+# bundled into the framework's Python sdist/wheel by the minimal launcher.
 
 # Exclude development files
 global-exclude *.pyc

diff --git a/README.md b/README.md
@@ -41,7 +41,7 @@ MS-Agent is a lightweight framework designed to empower agents with autonomous e
 - **Code Generation**: Supports code generation tasks with artifacts.
 - **Short Video Generation**：Support video generation of about 5 minutes.
 - **Agent Skills**: Knowledge-driven skill system — skills provide reusable procedural knowledge that guides the model via standard tool integration, with multi-source loading, progressive disclosure, and runtime self-evolution. See [Agent Skills](ms_agent/skill/README.md).
-- **WebUI**: Modern web interface for agent interaction with real-time WebSocket communication.
+- **WebUI**: Local React Router and FastAPI workspace with SSE-streamed agent interaction.
 - **Lightweight and Extensible**: Easy to extend and customize for various applications.
 
 
@@ -65,13 +65,13 @@ MS-Agent is a lightweight framework designed to empower agents with autonomous e
   - **Multimodal Model Input**: Support image, video, and other multimodal inputs. See [Multimodal Docs](docs/zh/Components/multimodal-support.md).
 
 * 🚀 Feb 06, 2026: Release MS-Agent v1.6.0rc1, which includes the following updates:
-  - **Agentic Insight v2**: A fully refactored deep-research system with better performance, scalability, and trustworthiness, now available in WebUI. See [Agentic Insight v2](https://github.com/modelscope/ms-agent/tree/main/projects/deep_research/v2).
+  - **Agentic Insight v2**: A fully refactored deep-research system with better performance, scalability, and trustworthiness, available in the legacy WebUI (the current WebUI has no dedicated Deep Research view — run it from the CLI). See [Agentic Insight v2](https://github.com/modelscope/ms-agent/tree/main/projects/deep_research/v2).
 
 * 🚀 Feb 04, 2026: Release MS-Agent v1.6.0rc0, which includes the following updates:
   - **Code Genesis** for complex code generation tasks, refer to [Code Genesis](https://github.com/modelscope/ms-agent/tree/main/projects/code_genesis)
   - **Singularity Cinema** for animated video generation workflow, refactored version, refer to [Singularity Cinema](https://github.com/modelscope/ms-agent/tree/main/projects/singularity_cinema)
   - **Agent Skills v2**: Knowledge-driven skill system — skills as procedural knowledge with progressive disclosure, multi-source loading, and standard tool integration. Refer to [Agent Skills](https://github.com/modelscope/ms-agent/tree/main/ms_agent/skill).
-  - **WebUI**: A new WebUI has been added, featuring agentic chatting capabilities, complex code generation and video generation workflow.
+  - **WebUI**: A new WebUI has been added, featuring agentic chatting capabilities, complex code generation and video generation workflow. (Superseded — see the current [WebUI guide](webui/README.md).)
 
 
 * 🎬 Nov 13, 2025: Release Singularity Cinema, to support short video generation for complex scenarios, check [here](projects/singularity_cinema/README_EN.md)
@@ -518,51 +518,44 @@ aggregator:
 
 ### WebUI
 
-MS-Agent provides a modern web interface for interacting with agents. Built with React frontend and FastAPI backend, featuring real-time WebSocket communication.
+MS-Agent provides a local agent workspace built with a React Router frontend and a FastAPI backend. Chat responses are streamed with Server-Sent Events (SSE).
 
-#### Demo
+#### Quick Start
 
-<div align="center">
-  <img src="https://github.com/user-attachments/assets/62026584-6c96-4a84-a849-05ae49906f48" alt="LocalGradioApplication" width="750">
-  <p><em>Demo: WebUI</em></p>
-</div>
+The current launcher is intended for a source checkout. Install these tools first:
 
-#### Quick Start
+- [uv](https://docs.astral.sh/uv/)
+- Node.js 22.22.0 or newer
+- pnpm 10.x (`corepack prepare pnpm@10.17.1 --activate`)
 
-**Start WebUI:**
+From the repository root, install MS-Agent in editable mode and start the WebUI:
 
 ```bash
+pip install -e .
 ms-agent ui
 ```
 
-**Windows tip:** If the console shows garbled text, use the PowerShell helper:
+On the first run, the launcher creates the backend environment and installs the locked frontend dependencies. Later starts verify those local dependencies. The browser opens at <http://127.0.0.1:7860>.
 
-```powershell
-webui/scripts/start-webui.ps1
-```
-
-The browser will automatically open at http://localhost:7860
+Configure a model in **Settings → Models** before starting a real chat. Environment-variable bootstrap and manual development instructions are available in the [WebUI guide](webui/README.md).
 
-**Command Options:**
+**Windows tip:** If the console shows garbled text, use the UTF-8 PowerShell helper:
 
-| Option | Description | Default |
-|--------|-------------|---------|
-| `--host` | Server host | 0.0.0.0 |
-| `--port` | Server port | 7860 |
-| `--production` | Production mode | False |
-| `--no-browser` | Don't auto-open browser | False |
-| `--reload` | Enable auto-reload (dev) | False |
+```powershell
+.\webui\scripts\start-webui.ps1
+```
 
 **Examples:**
 
 ```bash
-# Custom port
+# Use another public frontend port
 ms-agent ui --port 8080
 
-# Production mode without auto browser
-ms-agent ui --production --no-browser
+# Keep the browser closed
+ms-agent ui --no-browser
 ```
 
+See the [complete WebUI guide](webui/README.md) for prerequisites, configuration precedence, all launcher options, Windows notes, and troubleshooting. This minimal launcher intentionally does not provide a production SSR mode.
 
 <br>
 

diff --git a/README_ZH.md b/README_ZH.md
@@ -41,6 +41,7 @@ MS-Agent是一个轻量级框架，旨在为智能体提供自主探索能力。
 - **代码生成**：支持复杂项目的代码生成任务。
 - **短视频生成**：支持5分钟左右的短视频生成。
 - **Agent Skills**：兼容Anthropic-Agent-Skills协议，实现智能体技能模块。
+- **WebUI**：基于 React Router 和 FastAPI 的本地工作台，通过 SSE 实时返回智能体交互。
 - **轻量级且可扩展**：易于扩展和定制以适应各种应用。
 
 > 历史存档版本，请参考：https://github.com/modelscope/ms-agent/tree/0.8.0
@@ -60,13 +61,13 @@ MS-Agent是一个轻量级框架，旨在为智能体提供自主探索能力。
   - **多模态模型输入**：支持图片、视频等多模态输入，详情请参考[多模态文档](docs/zh/Components/multimodal-support.md)。
 
 * 🚀 **2026年2月6日：发布 MS-Agent v1.6.0rc1，主要更新内容如下：**
-  - **Agentic Insight v2**：完整重构的深度研究系统，性能更优、可扩展性更强、可信度更高，支持在webui中使用，详情请参考 [Agentic Insight v2](https://github.com/modelscope/ms-agent/tree/main/projects/deep_research/v2)
+  - **Agentic Insight v2**：完整重构的深度研究系统，性能更优、可扩展性更强、可信度更高，可在旧版 WebUI 中使用（当前 WebUI 没有专门的 Deep Research 入口，请用 CLI 运行），详情请参考 [Agentic Insight v2](https://github.com/modelscope/ms-agent/tree/main/projects/deep_research/v2)
 
 * 🚀 **2026年2月4日：发布 MS-Agent v1.6.0rc0，主要更新内容如下：**
   - **Code Genesis**：针对复杂代码生成任务的专项功能，详情请参考 [Code Genesis](https://github.com/modelscope/ms-agent/tree/main/projects/code_genesis)
   - **Singularity Cinema**：动画视频生成工作流的重构版本，详情请参考 [Singularity Cinema](https://github.com/modelscope/ms-agent/tree/main/projects/singularity_cinema)
   - **全新技能框架 (Skills Framework)**：全新设计的技能系统，显著增强了系统的健壮性与可扩展性。详情请参考 [MS-Agent Skills](https://github.com/modelscope/ms-agent/tree/main/ms_agent/skill)
-  - **WebUI**：新增 Web 交互界面，支持智能体对话、复杂代码生成以及视频生成工作流。
+  - **WebUI**：新增 Web 交互界面，支持智能体对话、复杂代码生成以及视频生成工作流。（已被替换，当前版本见 [WebUI 完整指南](webui/README_ZH.md)。）
 
 * 🎬 2025.11.13: 发布了“奇点放映室”，用于进行知识类文档的复杂场景短视频制作，具体查看[这里](projects/singularity_cinema/README.md)
 
@@ -558,51 +559,45 @@ OPENAI_API_KEY=xxx-xxx T2I_API_KEY=ms-xxx-xxx MANIM_TEST_API_KEY=xxx-xxx ms-agen
 
 ### WebUI
 
-MS-Agent提供了一个简洁轻量的Web界面，用于与智能体进行交互。该界面由React前端和FastAPI后端构建，支持实时的WebSocket通信。
+MS-Agent 提供了一个本地智能体工作台，由 React Router 前端和 FastAPI 后端组成，对话通过 Server-Sent Events（SSE）实时返回。
 
-#### Demo
+#### 快速开始
 
-<div align="center">
-  <img src="https://github.com/user-attachments/assets/62026584-6c96-4a84-a849-05ae49906f48" alt="LocalGradioApplication" width="750">
-  <p><em>Demo: WebUI</em></p>
-</div>
+当前启动器面向源码仓库使用。请先安装：
 
-#### 快速开始
+- [uv](https://docs.astral.sh/uv/)
+- Node.js 22.22.0 或更高版本
+- pnpm 10.x（执行 `corepack prepare pnpm@10.17.1 --activate`）
 
-**启动WebUI:**
+在仓库根目录以 editable 模式安装 MS-Agent，然后启动 WebUI：
 
 ```bash
+pip install -e .
 ms-agent ui
 ```
 
-**Windows 提示：** 若控制台出现乱码，建议使用 PowerShell 启动脚本：
+第一次运行时，启动器会创建后端环境并安装前端锁定依赖；后续启动会校验这些本地依赖。浏览器默认打开 <http://127.0.0.1:7860>。
 
-```powershell
-webui/scripts/start-webui.ps1
-```
-
-浏览器打开： http://localhost:7860
+进行真实对话前，请先在 **设置 → 模型设置** 中配置模型。环境变量初始化和手动开发方式见 [WebUI 完整指南](webui/README_ZH.md)。
 
-**命令参数**
+**Windows 提示：** 若控制台出现乱码，建议使用 UTF-8 PowerShell 启动脚本：
 
-| 选项             | 描述                       | 默认值     |
-|----------------|--------------------------|---------|
-| `--host`       | Server host              | 0.0.0.0 |
-| `--port`       | Server port              | 7860    |
-| `--production` | Production mode          | False   |
-| `--no-browser` | Don't auto-open browser  | False   |
-| `--reload`     | Enable auto-reload (dev) | False   |
+```powershell
+.\webui\scripts\start-webui.ps1
+```
 
 **示例**
 
 ```bash
-# Custom port
+# 修改公开前端端口
 ms-agent ui --port 8080
 
-# Production mode without auto browser
-ms-agent ui --production --no-browser
+# 不自动打开浏览器
+ms-agent ui --no-browser
 ```
 
+依赖、配置优先级、完整参数、Windows 注意事项和排障方式请阅读 [WebUI 完整指南](webui/README_ZH.md)。这个最简启动器有意不提供生产环境 SSR 模式。
+
 ---
 
 ### 有趣的工作

diff --git a/docs/en/GetStarted/CLI.md b/docs/en/GetStarted/CLI.md
@@ -94,20 +94,24 @@ ms-agent tui --config path/to/agent.yaml
 
 ## ui — Web UI Server
 
-Launch the Web UI server.
+Launch the source-checkout WebUI development stack. The command supervises an internal FastAPI server and a public React Router development server.
 
 ```shell
-ms-agent ui --host 0.0.0.0 --port 7860
+ms-agent ui
 ```
 
 | Argument | Description | Default |
 | --- | --- | --- |
-| `--host` | The server host to bind to | `0.0.0.0` |
-| `--port` | The server port to bind to | `7860` |
-| `--reload` | Enable auto-reload for development (flag) | `false` |
-| `--production` | Run in production mode (serve built frontend, flag) | `false` |
+| `--host` | Public frontend host | `127.0.0.1` |
+| `--port` | Public frontend port | `7860` |
+| `--backend-port` | Internal FastAPI port | `8000` |
+| `--reload` | Reload the Python backend when its source changes (flag) | `false` |
+| `--skip-install` | Skip dependency synchronization; requires existing `.venv` and `node_modules` (flag) | `false` |
+| `--production` | Reserved compatibility flag; exits with an unsupported-mode error | `false` |
 | `--no-browser` | Do not automatically open the browser (flag) | `false` |
 
+The launcher requires uv, Node.js 22.22.0 or newer, and pnpm 10.x. It installs locked project-local dependencies on first use. See the [WebUI guide](https://github.com/modelscope/ms-agent/blob/main/webui/README.md) for setup, model configuration, environment variables, Windows support, and troubleshooting.
+
 ---
 
 ## app — Gradio App

diff --git a/docs/zh/GetStarted/cli.md b/docs/zh/GetStarted/cli.md
@@ -91,20 +91,24 @@ ms-agent tui --config path/to/agent.yaml
 
 ## ui — Web UI 服务
 
-启动 Web UI 服务。
+启动源码仓库中的 WebUI 开发栈。该命令同时管理内部 FastAPI 服务和公开的 React Router 开发服务。
 
 ```shell
-ms-agent ui --host 0.0.0.0 --port 7860
+ms-agent ui
 ```
 
 | 参数 | 说明 | 默认值 |
 | --- | --- | --- |
-| `--host` | 绑定的服务主机 | `0.0.0.0` |
-| `--port` | 绑定的服务端口 | `7860` |
-| `--reload` | 开发模式启用自动重载（开关） | `false` |
-| `--production` | 生产模式（服务已构建的前端，开关） | `false` |
+| `--host` | 公开前端绑定的主机 | `127.0.0.1` |
+| `--port` | 公开前端端口 | `7860` |
+| `--backend-port` | 内部 FastAPI 端口 | `8000` |
+| `--reload` | 后端源码变化时自动重载（开关） | `false` |
+| `--skip-install` | 跳过依赖同步；要求 `.venv` 和 `node_modules` 已存在（开关） | `false` |
+| `--production` | 兼容性保留参数；当前会提示不支持并退出 | `false` |
 | `--no-browser` | 不自动打开浏览器（开关） | `false` |
 
+启动器要求 uv、Node.js 22.22.0 或更高版本以及 pnpm 10.x，并会在首次使用时安装锁定的项目内依赖。安装、模型配置、环境变量、Windows 支持与排障说明见 [WebUI 完整指南](https://github.com/modelscope/ms-agent/blob/main/webui/README_ZH.md)。
+
 ---
 
 ## app — Gradio 应用