# 伴侣应用

## 什么是伴侣应用？

伴侣应用是 iOS、Android 和 macOS 的原生应用程序，作为**节点**连接到您的 Gateway。节点向您的代理暴露设备功能 -- 摄像头、画布、屏幕录制、位置、语音和系统执行。

可以这样理解：Gateway 是大脑，伴侣应用是您设备上的手和眼睛。

## 节点如何工作

1. **连接** -- 伴侣应用通过 WebSocket 连接到您的 Gateway
2. **配对** -- 新设备经过配对审批流程
3. **注册功能** -- 应用告诉 Gateway 它能做什么（摄像头、画布、位置等）
4. **代理调用** -- 在对话中，代理可以请求节点拍照、录屏、渲染画布等

节点**不是 Gateway** -- 它们不运行自己的 AI。它们是扩展代理能力的外围设备。

## macOS 伴侣应用

macOS 应用驻留在菜单栏中，既作为伴侣节点又作为 Gateway 管理器。

### 功能
- **画布** -- 在原生窗口中渲染交互式 Web 内容
- **摄像头** -- 拍摄照片和视频片段（前置/后置）
- **屏幕录制** -- 全屏或按应用录制
- **系统执行** -- 在 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 代理在远程服务器上触发构建
- 家庭实验室自动化 -- 在树莓派或家庭服务器上运行命令
- 多机器编排 -- 跨多台机器协调任务

## 设备配对

### 配对流程
1. 伴侣应用呈现其设备身份（指纹 + 公钥）
2. Gateway 发出配对审批请求
3. 您通过桌面应用或仪表盘批准设备
4. Gateway 为未来连接颁发设备 token

### 信任模型
- **本地设备**（回环）为方便起见自动批准
- **非本地设备**需要明确批准
- 设备 token 本地存储，重新连接时重用

## 执行审批

对于可以运行系统命令的节点（macOS、无头主机），执行审批控制允许的操作：

- **允许列表模式** -- 只有预先批准的命令可以执行
- **询问模式** -- 未知命令提示您批准
- **完全模式** -- 无限制（谨慎使用）

按节点配置允许列表，精确控制每个设备可以做什么。