fix: demos on win (#2092)

* fix: demo1

* fix: ten_gn

* fix: demo 1

* fix: tman check clang-cl

* fix: .env file markdown

* fix: install python deps

* fix: python3 alias

* fix: python3 symlink

* fix: refine codes

---------

Co-authored-by: Hu Yueh-Wei <[email protected]>

Author: FaithfulinLOVE

ai_agents/agents/examples/websocket-example/tenapp/scripts/install_python_deps.py

@@ -102,7 +102,7 @@ def main():
     print("Starting Python dependencies installation...")
 
     # Determine pip command
-    pip_cmd = ["uv", "pip", "install"]
+    pip_cmd = ["uv", "pip", "install", "--system"]
 
     # Try to install server requirements
     server_req = app_dir.parent / "server" / "requirements.txt"

core/src/ten_manager/src/check_env/check_cpp.rs

@@ -8,17 +8,16 @@ use anyhow::Result;
 
 use super::types::{CheckStatus, CppCheckResult, Suggestion, ToolInfo};
 
-/// Use vswhere.exe to locate cl.exe from the latest VS installation.
-/// vswhere.exe ships with every VS 2017+ install and lives at a fixed path,
-/// so this works even when the Developer Command Prompt has not been activated.
+/// Check whether Visual Studio (with any C++ workload) is installed by
+/// querying vswhere.exe.
 #[cfg(windows)]
-fn find_cl_exe_via_vswhere() -> Option<String> {
+fn is_vs_installed() -> bool {
     let vswhere = r"C:\Program Files (x86)\Microsoft Visual Studio\Installer\vswhere.exe";
     if !std::path::Path::new(vswhere).exists() {
-        return None;
+        return false;
     }
 
-    let vs_path = std::process::Command::new(vswhere)
+    std::process::Command::new(vswhere)
         .args([
             "-latest",
             "-products",
@@ -31,24 +30,51 @@ fn find_cl_exe_via_vswhere() -> Option<String> {
         .output()
         .ok()
         .filter(|o| o.status.success())
-        .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())?;
+        .map(|o| !String::from_utf8_lossy(&o.stdout).trim().is_empty())
+        .unwrap_or(false)
+}
 
-    // Read the default MSVC toolset version from the version file.
-    let version_file =
-        format!(r"{}\VC\Auxiliary\Build\Microsoft.VCToolsVersion.default.txt", vs_path);
-    let msvc_ver = std::fs::read_to_string(&version_file).ok()?;
-    let msvc_ver = msvc_ver.trim();
+#[cfg(not(windows))]
+fn is_vs_installed() -> bool {
+    false
+}
 
-    let cl = format!(r"{}\VC\Tools\MSVC\{}\bin\Hostx64\x64\cl.exe", vs_path, msvc_ver);
-    if std::path::Path::new(&cl).exists() {
-        Some(cl)
+/// Use vswhere.exe to locate clang-cl.exe from the latest VS installation.
+/// clang-cl.exe is available when the "C++ Clang tools" component is installed.
+#[cfg(windows)]
+fn find_clang_cl_exe_via_vswhere() -> Option<String> {
+    let vswhere = r"C:\Program Files (x86)\Microsoft Visual Studio\Installer\vswhere.exe";
+    if !std::path::Path::new(vswhere).exists() {
+        return None;
+    }
+
+    let vs_path = std::process::Command::new(vswhere)
+        .args([
+            "-latest",
+            "-products",
+            "*",
+            "-requires",
+            "Microsoft.VisualStudio.Component.VC.Llvm.Clang",
+            "-property",
+            "installationPath",
+        ])
+        .output()
+        .ok()
+        .filter(|o| o.status.success())
+        .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
+        .filter(|s| !s.is_empty())?;
+
+    let clang_cl =
+        format!(r"{}\VC\Tools\Llvm\x64\bin\clang-cl.exe", vs_path);
+    if std::path::Path::new(&clang_cl).exists() {
+        Some(clang_cl)
     } else {
         None
     }
 }
 
 #[cfg(not(windows))]
-fn find_cl_exe_via_vswhere() -> Option<String> {
+fn find_clang_cl_exe_via_vswhere() -> Option<String> {
     None
 }
 
@@ -308,40 +334,50 @@ pub fn check() -> Result<CppCheckResult> {
             });
         }
     } else if os == "windows" {
-        // On Windows, cl.exe is not in PATH unless running inside a Developer
-        // Command Prompt / Developer PowerShell. We use vswhere.exe (bundled
-        // with every VS installation) to locate it directly.
-        let cl_path = find_cl_exe_via_vswhere();
+        // Check whether Visual Studio is installed via vswhere.
+        let has_vs = is_vs_installed();
+
+        // Check clang-cl.exe (shipped with VS "C++ Clang tools" component).
+        let clang_cl_path = find_clang_cl_exe_via_vswhere();
 
-        let msvc_check = if let Some(ref path) = cl_path {
-            std::process::Command::new(path).arg("/?").output()
+        let clang_cl_check = if let Some(ref path) = clang_cl_path {
+            std::process::Command::new(path).arg("--version").output()
         } else {
             // Fallback: maybe the user already has it in PATH.
-            std::process::Command::new("cl.exe").arg("/?").output()
+            std::process::Command::new("clang-cl.exe")
+                .arg("--version")
+                .output()
         };
 
-        match msvc_check {
-            Ok(output) if output.status.success() || !output.stderr.is_empty() => {
-                // cl.exe prints version info to stderr, not stdout.
-                let version_str = String::from_utf8_lossy(&output.stderr);
-                let version = version_str.lines().next().map(|s| s.trim().to_string());
-
-                let resolved_path = cl_path.or_else(|| {
+        match clang_cl_check {
+            Ok(output) if output.status.success() => {
+                let version_str =
+                    String::from_utf8_lossy(&output.stdout);
+                let version = version_str
+                    .lines()
+                    .next()
+                    .map(|s| s.trim().to_string());
+
+                let resolved_path = clang_cl_path.or_else(|| {
                     std::process::Command::new("where.exe")
-                        .arg("cl.exe")
+                        .arg("clang-cl.exe")
                         .output()
                         .ok()
                         .and_then(|o| {
                             if o.status.success() {
-                                Some(String::from_utf8_lossy(&o.stdout).trim().to_string())
+                                Some(
+                                    String::from_utf8_lossy(&o.stdout)
+                                        .trim()
+                                        .to_string(),
+                                )
                             } else {
                                 None
                             }
                         })
                 });
 
                 compilers.push(ToolInfo {
-                    name: "cl.exe (MSVC)".to_string(),
+                    name: "clang-cl.exe".to_string(),
                     version,
                     path: resolved_path,
                     status: CheckStatus::Ok,
@@ -351,7 +387,7 @@ pub fn check() -> Result<CppCheckResult> {
             }
             _ => {
                 compilers.push(ToolInfo {
-                    name: "cl.exe (MSVC)".to_string(),
+                    name: "clang-cl.exe".to_string(),
                     version: None,
                     path: None,
                     status: CheckStatus::Error,
@@ -361,13 +397,37 @@ pub fn check() -> Result<CppCheckResult> {
         }
 
         if !has_compiler {
-            suggestions.push(Suggestion {
-                issue: "MSVC compiler not found".to_string(),
-                command: Some("Install Visual Studio with C++ build tools".to_string()),
-                help_text: Some(
-                    "Please install Visual Studio with C++ development tools".to_string(),
-                ),
-            });
+            if has_vs {
+                // VS is installed but the Clang component is missing.
+                suggestions.push(Suggestion {
+                    issue: "clang-cl.exe not found".to_string(),
+                    command: None,
+                    help_text: Some(
+                        "Visual Studio is installed but the C++ Clang tools \
+                         component is missing. Please open Visual Studio \
+                         Installer, click \"Modify\", and enable the \
+                         \"C++ Clang tools\" component under \
+                         \"Individual components\", then install it."
+                            .to_string(),
+                    ),
+                });
+            } else {
+                // VS is not installed at all.
+                suggestions.push(Suggestion {
+                    issue: "clang-cl.exe not found".to_string(),
+                    command: Some(
+                        "Install Visual Studio with C++ build tools"
+                            .to_string(),
+                    ),
+                    help_text: Some(
+                        "Please install Visual Studio with C++ development \
+                         tools. During installation, make sure to also enable \
+                         the \"C++ Clang tools\" component under \
+                         \"Individual components\"."
+                            .to_string(),
+                    ),
+                });
+            }
         }
     }
 

core/ten_gn

@@ -31,20 +31,11 @@ _portal_target: getting-started/quick-start.cn.md
 
 ### Python 3.10
 
-**Linux / macOS：**
-
 ```bash
 python3 --version
 # 应显示: Python 3.10.x
 ```
 
-**Windows：**
-
-```powershell
-python --version
-# 应显示: Python 3.10.x
-```
-
 > 💡 **重要**：TEN Framework 目前仅支持 Python 3.10。推荐使用 `pyenv` 或 `venv` 创建 Python 虚拟环境：
 >
 > **Linux / macOS：**
@@ -65,18 +56,40 @@ python --version
 >
 > 注意，点击Install Now前务必勾选 "Add Python to PATH"
 >
+> ```bash
+> # Windows平台需要配置python3命令：
+>
+> # 首先，确认python的安装路径：
+> where.exe python
+> # 输出示例: C:\Users\YourName\AppData\Local\Programs\Python\Python310\python.exe
+>
+> # 然后，以管理员身份打开 PowerShell，在python.exe同目录下创建symlink：
+> New-Item -ItemType SymbolicLink -Path "C:\Users\YourName\AppData\Local\Programs\Python\Python310\python3.exe" -Target "C:\Users\YourName\AppData\Local\Programs\Python\Python310\python.exe"
+> # 请将上面的路径替换为 where.exe python 的实际输出路径
+>
+> # 验证：
+> python3 --version
+> ```
+>
 > ```powershell
 > # 推荐安装后使用 venv 创建虚拟环境，在该环境中工作
 > py -3.10 -m venv $env:USERPROFILE\ten-venv
-> # 每次工作前，激活环境
+> # 激活环境
 > & "$env:USERPROFILE\ten-venv\Scripts\Activate.ps1"
+>
+> # 若有权限错误，关闭终端/IDE，右键选择“以管理员身份运行”重新打开
+> # 或者改变执行策略来允许ps1脚本执行
+> Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
 > ```
 
 ### Go 1.20+
 
 ```bash
 go version
 # 应显示: go version go1.20 或更高版本
+
+$env:CGO_ENABLED = "1"
+# Windows下需要显式启用CGO
 ```
 
 ### Node.js / npm
@@ -87,6 +100,25 @@ npm --version
 # 确保 node 和 npm 命令可用
 ```
 
+### GCC (MinGW)
+💡仅在windows上需要安装
+``` bash
+# 首先确定winget存在。
+winget --version
+
+# 若不存在则需要从 <https://apps.microsoft.com/detail/9nblggh4nns1?hl=en-US&gl=US> 安装。
+#（系统需要满足：Windows10 高于 1709 (Build 16299)，或者是Windows11）
+
+#安装MinGW
+winget install BrechtSanders.WinLibs.POSIX.MSVCRT
+
+# 或查找后自行选择合适版本安装
+winget search "mingw"
+
+#检查安装
+gcc --version
+```
+
 > 💡 **提示**：如果缺少上述环境，请先安装对应版本后再继续。
 
 ## 第二步：安装 TEN Manager (tman)
@@ -111,14 +143,6 @@ brew install TEN-framework/ten-framework/tman
 
 **Windows:**
 
-```powershell
-# 首先确定winget存在。
-winget --version
-```
-
-若不存在则需要从 <https://apps.microsoft.com/detail/9nblggh4nns1?hl=en-US&gl=US> 安装。
-（系统需要满足：Windows10 高于 1709 (Build 16299)，或者是Windows11）
-
 ```powershell
 winget install TEN-framework.tman
 ```
@@ -439,10 +463,13 @@ xcode-select --install
 ```powershell
 # 方式一：安装 Visual Studio Build Tools（推荐）
 # 从 https://visualstudio.microsoft.com/visual-cpp-build-tools/ 下载安装
-# 安装时选择 "使用 C++ 的桌面开发" 工作负载
 
 # 方式二：使用 winget 安装
 winget install Microsoft.VisualStudio.2022.BuildTools --override "--add Microsoft.VisualStudio.Workload.VCTools --includeRecommended --passive"
+
+# 💡注意：
+#  - 安装时选择 "使用 C++ 的桌面开发" 工作负载
+#  - 且务必勾选“适用于Windows的C++ Clang工具”
 ```
 
 验证编译器安装：
@@ -460,7 +487,7 @@ clang --version
 
 ```powershell
 # 在 "Developer PowerShell for VS" 中执行
-cl
+clang-cl --version
 ```
 
 ### 常见问题（C++ 扩展）
@@ -525,6 +552,12 @@ export DYLD_LIBRARY_PATH=/usr/local/opt/[email protected]/Frameworks/Python.framework/
 **解决方案**：
 
 ```bash
+# 设置代理
+# Linux/macOS
+export GOPROXY=https://goproxy.cn,direct
+# Windows PowerShell
+$env:GOPROXY = "https://goproxy.cn,direct"
+
 # 清理 Go module 缓存
 go clean -modcache
 
@@ -549,6 +582,12 @@ pip3 install --index-url https://pypi.tuna.tsinghua.edu.cn/simple -r requirement
 
 **解决方案**：检查.env文件中的配置是否正确，确保 AZURE_STT_KEY 和 AZURE_STT_REGION 填写无误
 
+### 7. Windows下权限问题
+
+**问题**：Windows下在访问文件时报PermissionError
+
+**解决方案**：右键点击PowerShell，选择“以管理员身份运行”
+
 ## 获取帮助
 
 - **GitHub Issues**：<https://github.com/TEN-framework/ten-framework/issues>