@flyidea/ai-go-mcp

AI GO 桌面代理 — 讓 AI GO Web 即時控制本地 CLI 與螢幕。

概述

@flyidea/ai-go-mcp 是 AI GO 平台的桌面代理程式。安裝後，AI GO Web 可以透過安全的 SSE（Server-Sent Events）連線即時操控您的電腦，包括：

• CLI 控制：執行終端命令、即時串流輸出
• 螢幕控制：截圖、滑鼠移動/點擊、鍵盤輸入（需安裝選用套件）
• 檔案操作：讀取、寫入檔案，列出目錄

所有操作都經過本地安全策略保護，危險命令會被阻擋，高風險操作需經使用者確認。

系統需求

• Node.js >= 18
• Windows / macOS / Linux
• 螢幕控制功能需額外安裝 @nut-tree-fork/nut-js（自動嘗試安裝，失敗時功能降級）

快速開始

1. 登入授權

npx @flyidea/ai-go-mcp auth login

瀏覽器將自動開啟 AI GO 授權頁面，登入後 Token 會自動儲存至本機。

2. 啟動代理

npx @flyidea/ai-go-mcp start

Agent 啟動後會透過 SSE 連線到 AI GO 伺服器，等待 Web 端的操作指令。

3. 查看狀態

npx @flyidea/ai-go-mcp status

顯示授權狀態、系統資訊、支援能力等。

4. 登出

npx @flyidea/ai-go-mcp auth logout

功能說明

CLI 控制

• 基於 node-pty 偽終端，支援完整的互動式 shell
• 支援 Windows (PowerShell) 和 Unix (Bash)
• 即時串流輸出至 Web 端
• 支援終端大小調整
• 可管理多個同時進行的 session

螢幕控制（選用）

• 基於 @nut-tree-fork/nut-js 桌面自動化（optionalDependencies，安裝失敗不影響其他功能）
• 截圖壓縮為 WebP（品質 75%，最大寬度 1920px）
• 支援動作：移動、點擊、雙擊、右鍵、捲動、輸入文字、按鍵、組合鍵

檔案操作

• 讀取 / 寫入檔案
• 列出目錄內容（名稱、大小、是否目錄、修改時間）
• 路徑安全性檢查（禁止存取系統關鍵目錄）

通訊架構

Agent 使用 SSE（Server-Sent Events） 作為主要通訊方式：

| 方向 | 協定 | 說明 | |------|------|------| | 後端 → Agent | SSE | 透過 GET /agent-stream 接收指令串流 | | Agent → 後端 | HTTP POST | 透過 POST /agent-report 回報結果 |

認證方式

連線認證支援兩種模式（優先使用 Ticket）：

1. Ticket 認證（推薦）：先 POST /ws-ticket 取得一次性 30 秒 ticket，避免 JWT 暴露在 URL
2. JWT Token（向後相容）：直接在 query parameter 傳入 JWT

安全策略

Agent 端內建多層安全防護：

| 層級 | 說明 | 範例 | |------|------|------| | 封鎖 | 危險命令直接阻擋 | rm -rf /, format C:, shutdown | | 封鎖 | 間接執行偵測 | python -c "...", powershell -e, bash -c | | 確認 | 命令串接需確認 | echo hello; rm -rf /, cmd1 && cmd2 | | 確認 | 高風險操作需核准 | rm -r, pip install, sudo | | 放行 | 一般操作直接執行 | ls, cat, echo, dir |

路徑安全：

| 層級 | 說明 | |------|------| | 封鎖 | 系統目錄（System32, /etc, /proc） | | 封鎖 | 敏感檔案（.ssh/, .env, credentials） | | 封鎖 | 路徑遍歷攻擊（../../../etc/passwd） |

環境變數

| 變數名稱 | 說明 | 預設值 | |----------|------|--------| | AIGO_API_URL | AI GO API 伺服器 URL | https://ai-go.app | | AIGO_APP_URL | AI GO Web 前端 URL（登入用） | https://ai-go.app |

本地開發：設定 AIGO_API_URL=http://localhost:8000 即可連線至本地後端。

常見問題

安裝失敗（原生模組編譯錯誤）

node-pty 需要 C++ 編譯環境：

• Windows：安裝 Visual Studio Build Tools
• macOS：xcode-select --install
• Linux：sudo apt install build-essential python3

螢幕控制不可用

@nut-tree-fork/nut-js 是選用套件，安裝失敗時 Agent 仍可正常運作（僅 CLI + 檔案功能）。如需螢幕控制：

npm install -g @nut-tree-fork/nut-js

授權

MIT License (c) Urfit Tech