From 98b9f2fc29175a773f53636d4b7a008a3f802dfe Mon Sep 17 00:00:00 2001
From: dabaotongxue <297390763@qq.com>
Date: Tue, 11 Nov 2025 23:45:36 +0800
Subject: [PATCH 1/2] feat: Add Windows support with PowerShell integration

- Add Windows/PowerShell support to bash_tool.py with automatic OS detection
- Create setup-config.ps1 script for Windows users
- Update README.md and README_CN.md with Windows installation instructions
- Add troubleshooting section for common issues (SSL, module not found)
- Maintain full backward compatibility with macOS/Linux

Changes:
* mini_agent/tools/bash_tool.py: Auto-detect OS and use PowerShell on Windows
* scripts/setup-config.ps1: New PowerShell setup script
* README.md: Add Windows commands for all installation steps
* README_CN.md: Add Windows commands (Chinese version)
---
 README.md                     |  52 +++++++++++++-
 README_CN.md                  |  52 +++++++++++++-
 mini_agent/tools/bash_tool.py |  91 ++++++++++++++++++++-----
 scripts/setup-config.ps1      | 123 ++++++++++++++++++++++++++++++++++
 4 files changed, 298 insertions(+), 20 deletions(-)
 create mode 100644 scripts/setup-config.ps1

diff --git a/README.md b/README.md
index 7c834c4..6e4c2dc 100644
--- a/README.md
+++ b/README.md
@@ -69,8 +69,13 @@ pipx ensurepath
 sudo apt install pipx  # Debian/Ubuntu
 pipx ensurepath
 
+# Windows (PowerShell)
+python -m pip install --user pipx
+python -m pipx ensurepath
+# Restart PowerShell after installation
+
 # After installation, restart your terminal or run:
-source ~/.bashrc  # or ~/.zshrc
+source ~/.bashrc  # or ~/.zshrc (macOS/Linux)
 ```
 
 We offer two usage modes - choose based on your needs:
@@ -86,7 +91,12 @@ Perfect for users who want to quickly try Mini Agent without cloning the reposit
 pipx install git+https://github.com/MiniMax-AI/Mini-Agent.git
 
 # 2. Run setup script (automatically creates config files)
+# macOS/Linux:
 curl -fsSL https://raw.githubusercontent.com/MiniMax-AI/Mini-Agent/main/scripts/setup-config.sh | bash
+
+# Windows (PowerShell):
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/MiniMax-AI/Mini-Agent/main/scripts/setup-config.ps1" -OutFile "$env:TEMP\setup-config.ps1"
+powershell -ExecutionPolicy Bypass -File "$env:TEMP\setup-config.ps1"
 ```
 
 > 💡 **Tip**: If you want to develop locally or modify code, use "Development Mode" below
@@ -129,16 +139,26 @@ git clone https://github.com/MiniMax-AI/Mini-Agent.git
 cd Mini-Agent
 
 # 2. Install uv (if you haven't)
+# macOS/Linux:
 curl -LsSf https://astral.sh/uv/install.sh | sh
+# Windows (PowerShell):
+irm https://astral.sh/uv/install.ps1 | iex
+# Restart terminal after installation
 
 # 3. Sync dependencies
 uv sync
 
+# Alternative: Install dependencies manually (if not using uv)
+# pip install -r requirements.txt
+# Or install required packages:
+# pip install tiktoken pyyaml httpx pydantic requests prompt-toolkit mcp
+
 # 4. Initialize Claude Skills (Optional)
 git submodule update --init --recursive
 
 # 5. Copy config template
-cp mini_agent/config/config-example.yaml mini_agent/config/config.yaml
+cp mini_agent/config/config-example.yaml mini_agent/config/config.yaml  # macOS/Linux
+Copy-Item mini_agent\config\config-example.yaml mini_agent\config\config.yaml  # Windows
 
 # 6. Edit config file
 vim mini_agent/config/config.yaml  # Or use your preferred editor
@@ -220,6 +240,34 @@ pytest tests/test_agent.py tests/test_note_tool.py -v
 - ✅ **External Services** - Git MCP Server loading
 
 
+## Troubleshooting
+
+### SSL Certificate Error
+
+If you encounter `[SSL: CERTIFICATE_VERIFY_FAILED]` error:
+
+**Quick fix for testing** (modify `mini_agent/llm.py`):
+```python
+# Line 50: Add verify=False to AsyncClient
+async with httpx.AsyncClient(timeout=120.0, verify=False) as client:
+```
+
+**Production solution**:
+```bash
+# Update certificates
+pip install --upgrade certifi
+
+# Or configure system proxy/certificates
+```
+
+### Module Not Found Error
+
+Make sure you're running from the project directory:
+```bash
+cd Mini-Agent
+python -m mini_agent.cli
+```
+
 ## Related Documentation
 
 - [Development Guide](docs/DEVELOPMENT_GUIDE.md) - Detailed development and configuration guidance
diff --git a/README_CN.md b/README_CN.md
index 0613da3..de630de 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -67,8 +67,13 @@ pipx ensurepath
 sudo apt install pipx  # Debian/Ubuntu
 pipx ensurepath
 
+# Windows (PowerShell)
+python -m pip install --user pipx
+python -m pipx ensurepath
+# 安装后需要重启 PowerShell
+
 # 安装完成后，重启终端或运行：
-source ~/.bashrc  # 或 ~/.zshrc
+source ~/.bashrc  # 或 ~/.zshrc (macOS/Linux)
 ```
 
 ### 2. 选择使用模式
@@ -86,7 +91,12 @@ source ~/.bashrc  # 或 ~/.zshrc
 pipx install git+https://github.com/MiniMax-AI/Mini-Agent.git
 
 # 2. 运行配置脚本（自动创建配置文件）
+# macOS/Linux:
 curl -fsSL https://raw.githubusercontent.com/MiniMax-AI/Mini-Agent/main/scripts/setup-config.sh | bash
+
+# Windows (PowerShell):
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/MiniMax-AI/Mini-Agent/main/scripts/setup-config.ps1" -OutFile "$env:TEMP\setup-config.ps1"
+powershell -ExecutionPolicy Bypass -File "$env:TEMP\setup-config.ps1"
 ```
 
 > 💡 **提示**：如果您希望在本地进行开发或修改代码，请使用下方的“开发模式”。
@@ -129,16 +139,26 @@ git clone https://github.com/MiniMax-AI/Mini-Agent.git
 cd Mini-Agent
 
 # 2. 安装 uv（如果尚未安装）
+# macOS/Linux:
 curl -LsSf https://astral.sh/uv/install.sh | sh
+# Windows (PowerShell):
+irm https://astral.sh/uv/install.ps1 | iex
+# 安装后需要重启终端
 
 # 3. 同步依赖
 uv sync
 
+# 替代方案: 手动安装依赖（如果不使用 uv）
+# pip install -r requirements.txt
+# 或者安装必需的包:
+# pip install tiktoken pyyaml httpx pydantic requests prompt-toolkit mcp
+
 # 4. 初始化 Claude Skills（可选）
 git submodule update --init --recursive
 
 # 5. 复制配置模板
-cp mini_agent/config/config-example.yaml mini_agent/config/config.yaml
+cp mini_agent/config/config-example.yaml mini_agent/config/config.yaml  # macOS/Linux
+Copy-Item mini_agent\config\config-example.yaml mini_agent\config\config.yaml  # Windows
 
 # 6. 编辑配置文件
 vim mini_agent/config/config.yaml  # 或使用您偏好的编辑器
@@ -221,6 +241,34 @@ pytest tests/test_agent.py tests/test_note_tool.py -v
 - ✅ **外部服务** - Git MCP 服务器加载
 
 
+## 常见问题
+
+### SSL 证书错误
+
+如果遇到 `[SSL: CERTIFICATE_VERIFY_FAILED]` 错误:
+
+**测试环境快速修复** (修改 `mini_agent/llm.py`):
+```python
+# 第 50 行: 给 AsyncClient 添加 verify=False
+async with httpx.AsyncClient(timeout=120.0, verify=False) as client:
+```
+
+**生产环境解决方案**:
+```bash
+# 更新证书
+pip install --upgrade certifi
+
+# 或配置系统代理/证书
+```
+
+### 模块未找到错误
+
+确保从项目目录运行:
+```bash
+cd Mini-Agent
+python -m mini_agent.cli
+```
+
 ## 相关文档
 
 - [开发指南](docs/DEVELOPMENT_GUIDE_CN.md) - 详细的开发和配置指引
diff --git a/mini_agent/tools/bash_tool.py b/mini_agent/tools/bash_tool.py
index b93324e..49c4318 100644
--- a/mini_agent/tools/bash_tool.py
+++ b/mini_agent/tools/bash_tool.py
@@ -1,6 +1,10 @@
-"""Bash command execution tool with background process management."""
+"""Shell command execution tool with background process management.
+
+Supports both bash (Unix/Linux/macOS) and PowerShell (Windows).
+"""
 
 import asyncio
+import platform
 import re
 import time
 import uuid
@@ -211,7 +215,17 @@ async def terminate(cls, bash_id: str) -> BackgroundShell:
 
 
 class BashTool(Tool):
-    """Execute bash commands in foreground or background."""
+    """Execute shell commands in foreground or background.
+    
+    Automatically detects OS and uses appropriate shell:
+    - Windows: PowerShell
+    - Unix/Linux/macOS: bash
+    """
+
+    def __init__(self):
+        """Initialize BashTool with OS-specific shell detection."""
+        self.is_windows = platform.system() == "Windows"
+        self.shell_name = "PowerShell" if self.is_windows else "bash"
 
     @property
     def name(self) -> str:
@@ -219,7 +233,27 @@ def name(self) -> str:
 
     @property
     def description(self) -> str:
-        return """Execute bash commands in foreground or background.
+        shell_examples = {
+            "Windows": """Execute PowerShell commands in foreground or background.
+
+For terminal operations like git, npm, docker, etc. DO NOT use for file operations - use specialized tools.
+
+Parameters:
+  - command (required): PowerShell command to execute
+  - timeout (optional): Timeout in seconds (default: 120, max: 600) for foreground commands
+  - run_in_background (optional): Set true for long-running commands (servers, etc.)
+
+Tips:
+  - Quote file paths with spaces: cd "My Documents"
+  - Chain dependent commands with semicolon: git add . ; git commit -m "msg"
+  - Use absolute paths instead of cd when possible
+  - For background commands, monitor with bash_output and terminate with bash_kill
+
+Examples:
+  - git status
+  - npm test
+  - python -m http.server 8080 (with run_in_background=true)""",
+            "Unix": """Execute bash commands in foreground or background.
 
 For terminal operations like git, npm, docker, etc. DO NOT use for file operations - use specialized tools.
 
@@ -238,15 +272,18 @@ def description(self) -> str:
   - git status
   - npm test
   - python3 -m http.server 8080 (with run_in_background=true)"""
+        }
+        return shell_examples["Windows"] if self.is_windows else shell_examples["Unix"]
 
     @property
     def parameters(self) -> dict[str, Any]:
+        cmd_desc = f"The {self.shell_name} command to execute. Quote file paths with spaces using double quotes."
         return {
             "type": "object",
             "properties": {
                 "command": {
                     "type": "string",
-                    "description": "The bash command to execute. Quote file paths with spaces using double quotes.",
+                    "description": cmd_desc,
                 },
                 "timeout": {
                     "type": "integer",
@@ -268,10 +305,10 @@ async def execute(
         timeout: int = 120,
         run_in_background: bool = False,
     ) -> ToolResult:
-        """Execute bash command with optional background execution.
+        """Execute shell command with optional background execution.
 
         Args:
-            command: The bash command to execute
+            command: The shell command to execute
             timeout: Timeout in seconds (default: 120, max: 600)
             run_in_background: Set true to run command in background
 
@@ -286,16 +323,31 @@ async def execute(
             elif timeout < 1:
                 timeout = 120
 
+            # Prepare shell-specific command execution
+            if self.is_windows:
+                # Windows: Use PowerShell with appropriate encoding
+                shell_cmd = ["powershell.exe", "-NoProfile", "-Command", command]
+            else:
+                # Unix/Linux/macOS: Use bash
+                shell_cmd = command
+
             if run_in_background:
                 # Background execution: Create isolated process
                 bash_id = str(uuid.uuid4())[:8]
 
                 # Start background process with combined stdout/stderr
-                process = await asyncio.create_subprocess_shell(
-                    command,
-                    stdout=asyncio.subprocess.PIPE,
-                    stderr=asyncio.subprocess.STDOUT,  # Redirect stderr to stdout
-                )
+                if self.is_windows:
+                    process = await asyncio.create_subprocess_exec(
+                        *shell_cmd,
+                        stdout=asyncio.subprocess.PIPE,
+                        stderr=asyncio.subprocess.STDOUT,
+                    )
+                else:
+                    process = await asyncio.create_subprocess_shell(
+                        shell_cmd,
+                        stdout=asyncio.subprocess.PIPE,
+                        stderr=asyncio.subprocess.STDOUT,
+                    )
 
                 # Create background shell and add to manager
                 bg_shell = BackgroundShell(bash_id=bash_id, command=command, process=process, start_time=time.time())
@@ -319,11 +371,18 @@ async def execute(
 
             else:
                 # Foreground execution: Create isolated process
-                process = await asyncio.create_subprocess_shell(
-                    command,
-                    stdout=asyncio.subprocess.PIPE,
-                    stderr=asyncio.subprocess.PIPE,
-                )
+                if self.is_windows:
+                    process = await asyncio.create_subprocess_exec(
+                        *shell_cmd,
+                        stdout=asyncio.subprocess.PIPE,
+                        stderr=asyncio.subprocess.PIPE,
+                    )
+                else:
+                    process = await asyncio.create_subprocess_shell(
+                        shell_cmd,
+                        stdout=asyncio.subprocess.PIPE,
+                        stderr=asyncio.subprocess.PIPE,
+                    )
 
                 try:
                     stdout, stderr = await asyncio.wait_for(process.communicate(), timeout=timeout)
diff --git a/scripts/setup-config.ps1 b/scripts/setup-config.ps1
new file mode 100644
index 0000000..edeae84
--- /dev/null
+++ b/scripts/setup-config.ps1
@@ -0,0 +1,123 @@
+# Mini Agent Configuration Setup Script for Windows
+# This script helps you set up Mini Agent configuration files
+
+# Error handling
+$ErrorActionPreference = "Stop"
+
+# Colors for output
+function Write-ColorOutput {
+    param(
+        [string]$Message,
+        [string]$Color = "White"
+    )
+    
+    $colorMap = @{
+        "Red" = [ConsoleColor]::Red
+        "Green" = [ConsoleColor]::Green
+        "Yellow" = [ConsoleColor]::Yellow
+        "Blue" = [ConsoleColor]::Blue
+        "Cyan" = [ConsoleColor]::Cyan
+        "White" = [ConsoleColor]::White
+    }
+    
+    Write-Host $Message -ForegroundColor $colorMap[$Color]
+}
+
+# Configuration directory
+$CONFIG_DIR = Join-Path $env:USERPROFILE ".mini-agent\config"
+
+Write-ColorOutput "╔════════════════════════════════════════════════╗" -Color "Cyan"
+Write-ColorOutput "║   Mini Agent Configuration Setup              ║" -Color "Cyan"
+Write-ColorOutput "╚════════════════════════════════════════════════╝" -Color "Cyan"
+Write-Host ""
+
+# Step 1: Create config directory
+Write-ColorOutput "[1/2] Creating configuration directory..." -Color "Blue"
+if (Test-Path $CONFIG_DIR) {
+    # Auto backup existing config
+    $timestamp = Get-Date -Format "yyyyMMdd_HHmmss"
+    $BACKUP_DIR = Join-Path $env:USERPROFILE ".mini-agent\config.backup.$timestamp"
+    Write-ColorOutput "   Configuration directory exists, backing up to:" -Color "Yellow"
+    Write-ColorOutput "   $BACKUP_DIR" -Color "Yellow"
+    Copy-Item -Path $CONFIG_DIR -Destination $BACKUP_DIR -Recurse
+    Write-ColorOutput "   ✓ Backup created" -Color "Green"
+} else {
+    New-Item -Path $CONFIG_DIR -ItemType Directory -Force | Out-Null
+    Write-ColorOutput "   ✓ Created: $CONFIG_DIR" -Color "Green"
+}
+
+# Step 2: Download configuration files from GitHub
+Write-ColorOutput "[2/2] Downloading configuration files..." -Color "Blue"
+
+$FILES_COPIED = 0
+$GITHUB_RAW_URL = "https://raw.githubusercontent.com/MiniMax-AI/Mini-Agent/main/mini_agent/config"
+
+# Download config-example.yaml as config.yaml
+try {
+    $configUrl = "$GITHUB_RAW_URL/config-example.yaml"
+    $configPath = Join-Path $CONFIG_DIR "config.yaml"
+    Invoke-WebRequest -Uri $configUrl -OutFile $configPath -UseBasicParsing
+    Write-ColorOutput "   ✓ Downloaded: config.yaml" -Color "Green"
+    $FILES_COPIED++
+} catch {
+    Write-ColorOutput "   ✗ Failed to download: config.yaml" -Color "Red"
+}
+
+# Download mcp.json (optional)
+try {
+    $mcpUrl = "$GITHUB_RAW_URL/mcp.json"
+    $mcpPath = Join-Path $CONFIG_DIR "mcp.json"
+    Invoke-WebRequest -Uri $mcpUrl -OutFile $mcpPath -UseBasicParsing
+    Write-ColorOutput "   ✓ Downloaded: mcp.json" -Color "Green"
+    $FILES_COPIED++
+} catch {
+    # Optional file, don't show error
+}
+
+# Download system_prompt.md (optional)
+try {
+    $promptUrl = "$GITHUB_RAW_URL/system_prompt.md"
+    $promptPath = Join-Path $CONFIG_DIR "system_prompt.md"
+    Invoke-WebRequest -Uri $promptUrl -OutFile $promptPath -UseBasicParsing
+    Write-ColorOutput "   ✓ Downloaded: system_prompt.md" -Color "Green"
+    $FILES_COPIED++
+} catch {
+    # Optional file, don't show error
+}
+
+if ($FILES_COPIED -eq 0) {
+    Write-ColorOutput "   ✗ Failed to download configuration files" -Color "Red"
+    Write-ColorOutput "   Please check your internet connection" -Color "Yellow"
+    exit 1
+}
+
+Write-ColorOutput "   ✓ Configuration files ready" -Color "Green"
+
+Write-Host ""
+Write-ColorOutput "╔════════════════════════════════════════════════╗" -Color "Green"
+Write-ColorOutput "║   Setup Complete! ✨                          ║" -Color "Green"
+Write-ColorOutput "╚════════════════════════════════════════════════╝" -Color "Green"
+Write-Host ""
+Write-Host "Configuration files location:"
+Write-ColorOutput "  $CONFIG_DIR" -Color "Cyan"
+Write-Host ""
+Write-Host "Files:"
+Get-ChildItem $CONFIG_DIR -ErrorAction SilentlyContinue | ForEach-Object {
+    Write-Host "  📄 $($_.Name)"
+}
+Write-Host ""
+Write-ColorOutput "Next Steps:" -Color "Yellow"
+Write-Host ""
+Write-ColorOutput "1. Install Mini Agent:" -Color "Yellow"
+Write-ColorOutput "   pipx install git+https://github.com/MiniMax-AI/Mini-Agent.git" -Color "Green"
+Write-Host ""
+Write-ColorOutput "2. Configure your API Key:" -Color "Yellow"
+Write-Host "   Edit config.yaml and add your MiniMax API Key:"
+Write-ColorOutput "   notepad $CONFIG_DIR\config.yaml" -Color "Green"
+Write-ColorOutput "   code $CONFIG_DIR\config.yaml" -Color "Green"
+Write-Host ""
+Write-ColorOutput "3. Start using Mini Agent:" -Color "Yellow"
+Write-ColorOutput "   mini-agent                              # Use current directory" -Color "Green"
+Write-ColorOutput "   mini-agent --workspace C:\path\to\project # Specify workspace" -Color "Green"
+Write-ColorOutput "   mini-agent --help                      # Show help" -Color "Green"
+Write-Host ""

From bc3fcd720e2fa38585f33c044ca54f6670729713 Mon Sep 17 00:00:00 2001
From: dabaotongxue <297390763@qq.com>
Date: Wed, 12 Nov 2025 15:18:06 +0800
Subject: [PATCH 2/2] fix: Separate platform-specific commands into distinct
 code blocks

- Split macOS/Linux and Windows commands into separate markdown code blocks
- Improve readability by using proper code block formatting
- Address maintainer feedback on documentation format
---
 README.md    | 12 ++++++++++--
 README_CN.md | 12 ++++++++++--
 2 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 6e4c2dc..6ddc589 100644
--- a/README.md
+++ b/README.md
@@ -157,8 +157,16 @@ uv sync
 git submodule update --init --recursive
 
 # 5. Copy config template
-cp mini_agent/config/config-example.yaml mini_agent/config/config.yaml  # macOS/Linux
-Copy-Item mini_agent\config\config-example.yaml mini_agent\config\config.yaml  # Windows
+```
+
+**macOS/Linux:**
+```bash
+cp mini_agent/config/config-example.yaml mini_agent/config/config.yaml
+```
+
+**Windows:**
+```powershell
+Copy-Item mini_agent\config\config-example.yaml mini_agent\config\config.yaml
 
 # 6. Edit config file
 vim mini_agent/config/config.yaml  # Or use your preferred editor
diff --git a/README_CN.md b/README_CN.md
index de630de..e250879 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -157,8 +157,16 @@ uv sync
 git submodule update --init --recursive
 
 # 5. 复制配置模板
-cp mini_agent/config/config-example.yaml mini_agent/config/config.yaml  # macOS/Linux
-Copy-Item mini_agent\config\config-example.yaml mini_agent\config\config.yaml  # Windows
+```
+
+**macOS/Linux:**
+```bash
+cp mini_agent/config/config-example.yaml mini_agent/config/config.yaml
+```
+
+**Windows:**
+```powershell
+Copy-Item mini_agent\config\config-example.yaml mini_agent\config\config.yaml
 
 # 6. 编辑配置文件
 vim mini_agent/config/config.yaml  # 或使用您偏好的编辑器