CursorBot 文件

完整的 CursorBot 使用指南，從安裝設定到進階 API 整合，幫助您快速上手。

系統需求

在開始之前，請確保您的系統符合以下需求：

必要條件

選擇性需求

安裝方式

環境設定

CursorBot 使用環境變數進行設定。以下是主要的設定項目：

必要設定

# Telegram Bot（至少需要一個平台）
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_ALLOWED_USERS=your_user_id

# AI 提供者（至少需要一個）
OPENAI_API_KEY=sk-xxx
# 或
ANTHROPIC_API_KEY=sk-ant-xxx
# 或
GOOGLE_GENERATIVE_AI_API_KEY=AIza-xxx

AI 模型設定

Gateway 設定（原生應用）

# Gateway Token（正式環境必須設定）
GATEWAY_TOKEN=your_secret_token

# 功能開關
GATEWAY_CHAT_ENABLED=true
GATEWAY_CANVAS_ENABLED=true
GATEWAY_PAIRING_ENABLED=true

首次執行

驗證安裝

使用以下指令確認服務正常運行：

# 檢查健康狀態
curl http://localhost:8000/health

# 應該返回
{"status": "healthy", "version": "1.0.0"}

常用 Bot 指令

API 概覽

CursorBot 提供 RESTful API 和 WebSocket 端點，方便整合與監控。

健康檢查

{
  "status": "healthy",
  "timestamp": "2026-01-28T10:00:00Z",
  "version": "1.0.0"
}

{
  "status": "healthy",
  "timestamp": "2026-01-28T10:00:00Z",
  "version": "1.0.0",
  "components": {
    "telegram": { "status": "healthy", "latency_ms": 50 },
    "discord": { "status": "healthy", "latency_ms": 30 },
    "llm": { "status": "healthy", "providers": ["openai", "anthropic"] }
  },
  "system": {
    "cpu_percent": 25.5,
    "memory_percent": 45.2,
    "disk_percent": 60.0
  }
}

Webhook 端點

各平台的 Webhook 端點用於接收訊息和事件。

Content-Type: application/json
X-Line-Signature: {HMAC-SHA256 signature}

{
  "events": [
    {
      "type": "message",
      "replyToken": "xxx",
      "source": { "userId": "U123456", "type": "user" },
      "message": { "type": "text", "text": "/help" }
    }
  ]
}

REST API

{
  "nodes": [
    {
      "id": "node-abc123",
      "device_type": "macos",
      "device_name": "MacBook Pro",
      "connected_at": "2026-01-28T10:00:00Z"
    }
  ],
  "count": 1
}

{
  "total_requests": 1000,
  "total_tokens": 500000,
  "by_provider": {
    "openai": { "requests": 500, "tokens": 250000 },
    "anthropic": { "requests": 300, "tokens": 150000 }
  }
}

{
  "message": "系統維護通知",
  "user_ids": ["user1", "user2"],
  "platforms": ["telegram", "discord"]
}

WebSocket

原生應用透過 WebSocket 即時連線到 CursorBot。

const ws = new WebSocket('ws://localhost:8000/ws/node');

ws.onopen = () => {
  console.log('Connected to CursorBot');
};

// 發送聊天訊息
ws.send(JSON.stringify({
  type: 'chat',
  payload: {
    message: '你好！'
  }
}));

// 建立 Canvas
ws.send(JSON.stringify({
  type: 'canvas',
  payload: {
    action: 'create',
    name: 'My Canvas'
  }
}));

// 接收回應
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

錯誤處理

HTTP 狀態碼

錯誤回應格式

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "請求格式錯誤",
    "details": {
      "field": "message",
      "reason": "required"
    }
  }
}

基礎指令

AI 指令

任務指令

進階指令

Telegram 設定

1. 建立 Bot

   在 Telegram 中搜尋 @BotFather，發送 /newbot 建立新 Bot。

2. 取得 Token

   BotFather 會給您一個 Token，格式如：123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

3. 取得您的 User ID

   搜尋 @userinfobot，發送任意訊息取得您的 User ID。

4. 設定環境變數

   env

   TELEGRAM_BOT_TOKEN=your_bot_token
   TELEGRAM_ALLOWED_USERS=your_user_id

Discord 設定

1. 建立 Application

   前往 Discord Developer Portal，點擊 "New Application"。

2. 建立 Bot

   進入 "Bot" 頁面，點擊 "Add Bot"，啟用 "Message Content Intent"。

3. 邀請到伺服器

   在 "OAuth2" > "URL Generator" 選擇 bot 和 applications.commands 權限。

4. 設定環境變數

   env

   DISCORD_ENABLED=true
   DISCORD_BOT_TOKEN=your_bot_token
   DISCORD_ALLOWED_GUILDS=your_guild_id

LINE 設定

1. 建立 Channel

   前往 LINE Developers 建立 Provider 和 Messaging API Channel。

2. 設定 Webhook

   在 "Messaging API" 頁面設定 Webhook URL：https://your-domain/webhook/line

3. 設定環境變數

   env

   LINE_ENABLED=true
   LINE_CHANNEL_ACCESS_TOKEN=your_token
   LINE_CHANNEL_SECRET=your_secret

Slack 設定

1. 建立 App

   前往 Slack API 建立新 App。

2. 設定 Event Subscriptions

   Webhook URL：https://your-domain/webhook/slack

   訂閱事件：message.channels、message.im

3. 設定環境變數

   env

   SLACK_ENABLED=true
   SLACK_BOT_TOKEN=xoxb-xxx
   SLACK_SIGNING_SECRET=xxx

原生應用

CursorBot 提供 macOS、iOS、Android 原生應用程式碼，位於 apps/ 目錄。

macOS App

cd apps/macos/CursorBot
swift build
swift run

iOS App

使用 Xcode 開啟 apps/ios/CursorBotNode.xcodeproj 進行建置。

Android App

使用 Android Studio 開啟 apps/android 目錄進行建置。