# 伴侶應用程式

## 什麼是伴侶應用程式？

伴侶應用程式是 iOS、Android 和 macOS 的原生應用程式，作為**節點**連接至您的 Gateway。節點將裝置功能, , 相機、畫布、螢幕錄製、位置、語音和系統執行, , 暴露給您的代理程式。

換個角度來想：Gateway 是大腦，伴侶應用程式是您裝置上的手和眼睛。

## 節點如何運作

1. **連接**, 伴侶應用程式透過 WebSocket 連接至您的 Gateway
2. **配對**, 新裝置要經過配對核准程序
3. **註冊功能**, 應用程式告訴 Gateway 它能做什麼（相機、畫布、位置等）
4. **代理程式呼叫**, 在對話期間，代理程式可以請求節點拍照、錄製螢幕、渲染畫布等

節點**不是 Gateway**, , 它們不執行自己的 AI。它們是擴展代理程式功能的周邊裝置。

## macOS 伴侶應用程式

macOS 應用程式位於選單列中，同時作為伴侶節點和 Gateway 管理器。

### 功能
- **畫布**, 在原生視窗中渲染互動式網頁內容
- **相機**, 拍攝照片和影片片段（前置/後置）
- **螢幕錄製**, 全螢幕或按應用程式錄製
- **系統執行**, 在 Mac 上執行 shell 命令（受執行核准管控）
- **通知**, 傳送具有優先級選項的原生 macOS 通知
- **位置**, 可用時提供 GPS

### 附加功能
- **Gateway 管理**, 啟動、停止和監控 Gateway
- **權限所有權**, 管理 macOS TCC 權限（通知、輔助功能、螢幕錄製、麥克風、語音辨識、AppleScript）
- **深度連結**, `neotask://` URL 方案，用於以參數啟動代理程式
- **CLI 安裝**, 安裝 `neotask` 命令列工具

## iOS 應用程式

iOS 應用程式作為節點連接至您的 Gateway，為您的代理程式帶來行動裝置功能。

### 功能
- **畫布**, 基於 SwiftUI 的互動式內容渲染
- **相機**, 照片和影片片段（前置/後置相機）
- **音訊錄製**, 麥克風擷取
- **位置**, 支援精確度選擇的 GPS
- **通知**, 原生 iOS 推送通知

### 特性
- **探索**, 透過 Bonjour（區域網路）、Tailscale（VPN）或手動輸入尋找 Gateway
- **配對**, 安全的裝置配對，需要 Gateway 核准
- **語音喚醒**, 喚醒詞啟動，實現免手持互動
- **通話模式**, 連續語音對話
- **分享延伸**, 從其他應用程式直接分享內容至您的代理程式
- **A2UI**, 在裝置畫布上進行代理程式驅動的 UI 渲染

### 限制
- 前景優先設計（iOS 在背景中暫停 WebSocket 連接）
- 嚴格的背景命令限制
- 目前處於內部預覽階段

## Android 應用程式

Android 應用程式作為節點連接，具有與 iOS 類似的功能。

### 功能
- **畫布**, 基於 Jetpack Compose 的 UI 渲染
- **相機**, 照片和影片（前置/後置，需要權限）
- **螢幕錄製**, 系統螢幕擷取（Android 10+）
- **位置**, 支援精確度模式的 GPS
- **簡訊傳送**, 在支援電話功能的裝置上
- **聊天與歷史**, 在裝置上查看對話歷史

### 特性
- **前景服務**, 持久性通知保持連接活躍
- **共享工作階段**, 跨所有已連接節點的同一工作階段
- **現代 Android**, 需要 Android 12+（API 31）

## 無頭節點主機

無需任何 UI 即可執行節點, , 非常適合建置伺服器、遠端機器或無頭 Linux 機器。

### 功能
- **系統執行**, 在節點主機上執行命令
- **命令允許清單**, 設定節點可以執行哪些命令
- **持久性服務**, 安裝為 launchd/systemd 服務

### 使用案例
- CI/CD 建置代理程式, 讓您的 AI 代理程式在遠端伺服器上觸發建置
- 家庭實驗室自動化, 在 Raspberry Pi 或家用伺服器上執行命令
- 多機器協調, 跨多台機器協調任務

## 裝置配對

### 配對流程
1. 伴侶應用程式呈現其裝置身份（指紋 + 公鑰）
2. Gateway 發出配對核准請求
3. 您透過桌面應用程式或儀表板核准裝置
4. Gateway 為未來的連接發出裝置令牌

### 信任模型
- **本機裝置**（回送）為了方便起見自動核准
- **非本機裝置**需要明確核准
- 裝置令牌儲存在本機，在重新連接時重複使用

## 執行核准

對於可以執行系統命令的節點（macOS、無頭主機），執行核准控制允許的內容：

- **允許清單模式**, 只有預先核准的命令才能執行
- **詢問模式**, 未知命令會提示您核准
- **完整模式**, 無限制（謹慎使用）

設定每個節點的允許清單，以精確控制每個裝置可以執行的操作。