協議參考 - Qaptly Docs

協議概述

統一執行節點協議 (UPP) 使用 WebSocket 上的 JSON 訊息。所有訊息遵循標準結構，包含協議版本管理和訊息相關性。

連接詳細資訊

協議: WebSocket (ws://)
主機: <qaptly_desktop_ip> (區域網路 IP)
連接埠: 18765
路徑: /upp
完整 URL: ws://<qaptly_desktop_ip>:18765/upp

網路配置: <qaptly_desktop_ip> 代表執行 Qaptly Desktop 的機器在區域網路上的 IP 位址（例如：192.168.1.100、10.0.0.5）。⚠️ 僅限內部網路: UPP 專為區域網路部署而設計。請勿將 WebSocket 伺服器暴露到公共網際網路。

協議版本

目前版本: 1.0.0 (語義版本控制) 所有訊息必須包含 protocolVersion: "1.0.0" 以進行相容性檢查。

基礎訊息結構

每個 UPP 訊息遵循此格式:

{
  "id": "<message-uuid>",
  "protocolVersion": "1.0.0",
  "type": "<message_type>",
  "timestamp": "<ISO8601>",
  "payload": { ... }
}

欄位	型別	必需	描述
`id`	string	是	唯一訊息 ID (UUID v4)
`protocolVersion`	string	是	協議版本 (semver)
`type`	string	是	訊息類型 (見下方)
`timestamp`	string	是	ISO 8601 時間戳記 (附 Z)
`payload`	object	是	訊息特定的內容

訊息類型

類型	方向	描述
`register`	執行節點 → Qaptly	執行節點自我註冊
`register_response`	Qaptly → 執行節點	註冊回應
`command`	Qaptly → 執行節點	執行命令
`response`	執行節點 → Qaptly	命令執行結果
`event`	執行節點 → Qaptly	即時事件通知
`subscribe`	Qaptly → 執行節點	訂閱事件
`heartbeat`	雙向	保持連接活躍

註冊訊息

執行節點在連接後立即發送此訊息。方向: 執行節點 → Qaptly

首次連接 (無金鑰)

{
  "id": "msg-uuid-001",
  "protocolVersion": "1.0.0",
  "type": "register",
  "timestamp": "2026-01-21T10:30:00.000Z",
  "payload": {
    "pilot": {
      "id": "my-pilot-001",
      "name": "My WiFi Controller",
      "version": "1.0.0",
      "vendor": "My Company",
      "description": "Controls WiFi networks for testing"
    },
    "auth": {},
    "capabilities": [
      {
        "action": "wifi.scan",
        "name": "Scan WiFi Networks",
        "description": "Scans for available WiFi networks and returns their SSID, signal strength, and security type",
        "params": {
          "type": "object",
          "properties": {
            "timeout": {
              "type": "number",
              "description": "Scan timeout in seconds",
              "default": 10
            }
          },
          "required": []
        },
        "returns": {
          "type": "object",
          "properties": {
            "networks": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "ssid": { "type": "string" },
                  "signal": { "type": "number" },
                  "security": { "type": "string" }
                }
              }
            }
          }
        },
        "events": ["wifi.scan_complete"]
      }
    ]
  }
}

重新連接 (使用金鑰)

{
  "id": "msg-uuid-100",
  "protocolVersion": "1.0.0",
  "type": "register",
  "timestamp": "2026-01-21T15:00:00.000Z",
  "payload": {
    "pilot": {
      "id": "my-pilot-001",
      "name": "My WiFi Controller",
      "version": "1.0.0"
    },
    "auth": {
      "key": "abc123-generated-key-xyz789"
    },
    "capabilities": [...]
  }
}

執行節點資訊欄位

欄位	型別	必需	描述
`id`	string	是	唯一執行節點 ID (使用格式: `<type>-<instance>`)
`name`	string	是	人類可讀的名稱
`version`	string	是	執行節點版本 (semver)
`vendor`	string	否	開發人員/公司名稱
`description`	string	否	此執行節點的功能

認證欄位

欄位	型別	必需	描述
`key`	string	條件	預先共享的金鑰 (已知執行節點須此項)

功能欄位

欄位	型別	必需	描述
`action`	string	是	操作識別符 (格式: `domain.action`)
`name`	string	是	人類可讀的名稱
`description`	string	否	此操作的功能 (由 AI 使用)
`params`	JSON Schema	是	參數定義 (Draft 2020-12)
`returns`	JSON Schema	是	傳回值定義
`events`	string[]	否	此操作可能觸發的事件

註冊回應

Qaptly 在處理註冊後發送此訊息。方向: Qaptly → 執行節點

成功 (已知執行節點)

{
  "id": "msg-uuid-002",
  "protocolVersion": "1.0.0",
  "type": "register_response",
  "timestamp": "2026-01-21T10:30:00.100Z",
  "payload": {
    "success": true,
    "pilotId": "my-pilot-001",
    "message": "Pilot registered successfully",
    "heartbeat": {
      "interval": 30000,
      "timeout": 90000
    }
  }
}

待核准 (新執行節點)

{
  "id": "msg-uuid-002",
  "protocolVersion": "1.0.0",
  "type": "register_response",
  "timestamp": "2026-01-21T10:30:00.100Z",
  "payload": {
    "success": false,
    "pending": true,
    "message": "Waiting for user approval"
  }
}

已核准 (附金鑰)

{
  "id": "msg-uuid-003",
  "protocolVersion": "1.0.0",
  "type": "register_response",
  "timestamp": "2026-01-21T10:30:15.000Z",
  "payload": {
    "success": true,
    "pilotId": "my-pilot-001",
    "assignedKey": "abc123-generated-key-xyz789",
    "message": "Pilot approved and registered",
    "heartbeat": {
      "interval": 30000,
      "timeout": 90000
    }
  }
}

失敗

{
  "id": "msg-uuid-002",
  "protocolVersion": "1.0.0",
  "type": "register_response",
  "timestamp": "2026-01-21T10:30:00.100Z",
  "payload": {
    "success": false,
    "error": {
      "code": "AUTH_FAILED",
      "message": "Invalid authentication key"
    }
  }
}

錯誤代碼

代碼	描述
`AUTH_FAILED`	金鑰驗證失敗
`USER_REJECTED`	使用者拒絕了執行節點
`DUPLICATE_PILOT_ID`	執行節點 ID 已註冊
`INVALID_PILOT_INFO`	執行節點資訊遺漏或無效
`INVALID_CAPABILITY`	功能定義無效
`PROTOCOL_VERSION_MISMATCH`	協議版本不支援

命令訊息

Qaptly 發送命令以執行操作。方向: Qaptly → 執行節點

{
  "id": "msg-uuid-010",
  "protocolVersion": "1.0.0",
  "type": "command",
  "timestamp": "2026-01-21T10:31:00.000Z",
  "payload": {
    "commandId": "cmd-uuid-12345",
    "action": "wifi.scan",
    "params": {
      "timeout": 15
    },
    "timeout": 20000
  }
}

欄位

欄位	型別	必需	描述
`commandId`	string	是	唯一命令 ID (UUID)
`action`	string	是	要執行的操作
`params`	object	是	參數 (符合功能架構)
`timeout`	number	否	逾時時間 (毫秒,預設值: 30000)

回應訊息

執行節點以執行結果回應。方向: 執行節點 → Qaptly

成功

{
  "id": "msg-uuid-011",
  "protocolVersion": "1.0.0",
  "type": "response",
  "timestamp": "2026-01-21T10:31:05.000Z",
  "payload": {
    "commandId": "cmd-uuid-12345",
    "success": true,
    "data": {
      "networks": [
        {
          "ssid": "HomeWiFi",
          "signal": -45,
          "security": "wpa2"
        }
      ]
    }
  }
}

失敗

{
  "id": "msg-uuid-011",
  "protocolVersion": "1.0.0",
  "type": "response",
  "timestamp": "2026-01-21T10:31:05.000Z",
  "payload": {
    "commandId": "cmd-uuid-12345",
    "success": false,
    "error": {
      "code": "wifi.SCAN_FAILED",
      "message": "WiFi adapter is disabled"
    }
  }
}

欄位

欄位	型別	必需	描述
`commandId`	string	是	必須符合命令的 commandId
`success`	boolean	是	命令是否成功
`data`	object	成功時	傳回資料 (符合功能架構)
`error`	object	失敗時	錯誤詳細資訊
`error.code`	string	是	錯誤代碼 (使用 `domain.ERROR_NAME` 格式)
`error.message`	string	是	人類可讀的錯誤訊息

事件訊息

執行節點為訂閱的監聽器發送事件。方向: 執行節點 → Qaptly

{
  "id": "msg-uuid-020",
  "protocolVersion": "1.0.0",
  "type": "event",
  "timestamp": "2026-01-21T10:35:00.000Z",
  "payload": {
    "event": "wifi.disconnected",
    "data": {
      "reason": "signal_lost",
      "lastSsid": "HomeWiFi"
    }
  }
}

重要: 只發送 Qaptly 已訂閱的事件。未訂閱的事件會被忽略。

訂閱訊息

Qaptly 訂閱特定事件。方向: Qaptly → 執行節點

訂閱事件

{
  "id": "msg-uuid-030",
  "protocolVersion": "1.0.0",
  "type": "subscribe",
  "timestamp": "2026-01-21T10:30:05.000Z",
  "payload": {
    "subscribe": ["wifi.connected", "wifi.disconnected"],
    "unsubscribe": []
  }
}

取消訂閱事件

{
  "id": "msg-uuid-031",
  "protocolVersion": "1.0.0",
  "type": "subscribe",
  "timestamp": "2026-01-21T10:30:06.000Z",
  "payload": {
    "subscribe": [],
    "unsubscribe": ["wifi.signal_changed"]
  }
}

萬用字元支援

訂閱所有事件: ["*"]
訂閱網域: ["wifi.*"] (所有 WiFi 事件)

心跳訊息

保持連接活躍。雙方每 30 秒發送一次。方向: 雙向

{
  "id": "msg-uuid-100",
  "protocolVersion": "1.0.0",
  "type": "heartbeat",
  "timestamp": "2026-01-21T10:32:00.000Z",
  "payload": {}
}

心跳策略

參數	值	描述
間隔	30 秒	每 30 秒發送一次心跳
逾時	90 秒	90 秒無訊息 = 斷線
發起者	兩者	Qaptly 和執行節點都發送
回應	無	火力和遺忘,不需回應

如果您的執行節點 90 秒內未發送心跳,Qaptly 將關閉連接。

操作命名慣例

操作使用格式: domain.action

標準網域

網域	範例	描述
`wifi`	`scan`, `connect`, `disconnect`, `status`	WiFi 控制
`bluetooth`	`scan`, `pair`, `unpair`	Bluetooth 控制
`network`	`ping`, `traceroute`, `dns_lookup`	網路診斷
`gpio`	`read`, `write`, `mode`	GPIO 控制
`sensor`	`temperature`, `humidity`, `pressure`	感應器讀取
`system`	`reboot`, `shutdown`, `info`	系統操作

自訂網域

為自訂網域使用廠商字首:

vendor.domain.action

範例:

acme.motor.rotate
acme.motor.stop
mycompany.led.set_color

連接生命週期

斷線

正常斷線: 正常關閉 WebSocket
逾時: 90 秒無訊息
寬限期: 5 分鐘內重新連接 (使用相同金鑰)

最佳實踐

訊息 ID

為所有訊息 ID 使用 UUID v4:

import uuid
message_id = str(uuid.uuid4())

時間戳記

使用 ISO 8601 格式 (附 ‘Z’ 後綴,UTC):

from datetime import datetime
timestamp = datetime.utcnow().isoformat() + "Z"
# "2026-01-21T10:30:00.000000Z"

錯誤處理

始終包含有意義的錯誤代碼和訊息:

{
  "code": "wifi.AUTHENTICATION_FAILED",
  "message": "WiFi password is incorrect"
}

事件篩選

只發送 Qaptly 已訂閱的事件:

if event_manager.is_subscribed("wifi.connected"):
    await send_event("wifi.connected", {...})

後續步驟

認證

安全模型和金鑰管理

功能

使用 JSON Schema 定義功能

示例

完整的工作實現

快速開始

建立您的首個執行節點

​協議概述

​連接詳細資訊

​協議版本

​基礎訊息結構

​訊息類型

​註冊訊息

​首次連接 (無金鑰)

​重新連接 (使用金鑰)

​執行節點資訊欄位

​認證欄位

​功能欄位

​註冊回應

​成功 (已知執行節點)

​待核准 (新執行節點)

​已核准 (附金鑰)

​失敗

​錯誤代碼

​命令訊息

​欄位

​回應訊息

​成功

​失敗

​欄位

​事件訊息

​訂閱訊息

​訂閱事件

​取消訂閱事件

​萬用字元支援

​心跳訊息

​心跳策略

​操作命名慣例

​標準網域

​自訂網域

​連接生命週期

​斷線

​最佳實踐

​訊息 ID

​時間戳記

​錯誤處理

​事件篩選

​後續步驟

認證

功能

示例

快速開始

協議概述

連接詳細資訊

協議版本

基礎訊息結構

訊息類型

註冊訊息

首次連接 (無金鑰)

重新連接 (使用金鑰)

執行節點資訊欄位

認證欄位

功能欄位

註冊回應

成功 (已知執行節點)

待核准 (新執行節點)

已核准 (附金鑰)

失敗

錯誤代碼

命令訊息

欄位

回應訊息

成功

失敗

欄位

事件訊息

訂閱訊息

訂閱事件

取消訂閱事件

萬用字元支援

心跳訊息

心跳策略

操作命名慣例

標準網域

自訂網域

連接生命週期

斷線

最佳實踐

訊息 ID

時間戳記

錯誤處理

事件篩選

後續步驟