API 参考
配对
通过 app.capabilities 判断功能支持,通过 app.access 和宿主权限判断访问授权。示例使用合成数据,调用前请替换路径、ID、输入和筛选条件。
Device A
plainapp://pair?request=<URL-encoded JSON>Device B
QR
QR payload
签名算法: Ed25519 · PAIR_REQUEST
signature = Base64(Ed25519-Sign(Device A private key, signed))Ed25519-Verify(Device A public key, signed, Base64Decode(signature))点帧内的 JSON 段可查看这条合成示例的完整签名输入;接收方使用签名方公钥验签。两端本地计算,不作为字段传输;比较八位数字(包含前导零)。
verificationCode = 73939800digest = SHA256(request.signature encoded as UTF-8)digest (hex) = ff44f60497bc235899f050f272165ec094a2f2c685e776d153a0711424b85dc0number = first 8 digest bytes as an unsigned big-endian integerverificationCode = number mod 100000000, padded to 8 decimal digits二维码:A 展示,B 扫描。局域网 c-id 为发送方;蓝牙使用独立传输。PAIR_CANCEL 为可选步骤。
悬停或点按字段
固定时间的合成快照;签名与 requestId 相互匹配。192.0.2.0/24 为文档示例地址;8443 为默认 HTTPS 端口,实际使用发现结果中的 port。请求有时效,不能原样重放。
在 PlainApp 桌面版管理新设备或公钥已变更的设备时,先明确选择「信任」。这一步不显示核对码,公钥变更时会提示。随后,如果未使用密码,请先核对两台设备上显示的同一个验证码,再在被管理设备上批准。使用密码验证时,被管理设备也可能要求批准,但不显示验证码。
类型定义
graphql
type Subscription {
peersChanged: Boolean!
pairingRequested: PairingRequestNotice!
pairingCompleted: PairingCompletedNotice!
pairingStarted: PairingProgressNotice!
pairingFailed: PairingProgressNotice!
pairingCanceled: PairingProgressNotice!
}
type Mutation {
cancelPairing(peerId: ID!): Boolean!
deletePeer(peerId: ID!): Boolean!
pairPeer(peerId: ID!, input: PairPeerInput!): Boolean!
respondToPairing(peerId: ID!, accepted: Boolean!): Boolean!
unpairPeer(peerId: ID!): Boolean!
}
type Query {
peerFileUrl(peerId: ID!, fileId: String!): String!
peers: [Peer!]!
}
enum DeviceType {
COMPUTER
PHONE
TABLET
TV
NAS
OTHER
}
scalar Instant
input PairPeerInput {
mode: PairingMode!
password: String
}
type PairingCompletedNotice {
deviceId: ID!
deviceName: String!
ip: String!
port: Int
deviceType: DeviceType
requestId: String
}
enum PairingErrorCode {
TIMEOUT
REJECTED
PASSWORD_REQUIRED
INVALID_PASSWORD
PEER_IDENTITY_CHANGED
TOO_MANY_LOGIN_ATTEMPTS
INTERNAL_ERROR
}
enum PairingMode {
CHAT
MANAGE
}
type PairingProgressNotice {
verificationCode: String
deviceId: ID!
deviceName: String!
error: PairingErrorCode
}
type PairingRequestNotice {
fromIp: String!
fromId: ID!
fromName: String!
deviceType: DeviceType!
verificationCode: String!
identityChanged: Boolean!
}
type Peer {
id: ID!
name: String!
ip: String!
status: PeerStatus!
port: Int
deviceType: DeviceType!
createdAt: Instant!
updatedAt: Instant!
online: Boolean!
managed: Boolean!
key: String!
publicKey: String!
token: String!
}
enum PeerStatus {
PAIRED
UNPAIRED
CHANNEL
}操作
subscription
peersChanged
接收对端记录变更信号。
graphql
subscription peersChanged {
peersChanged
}subscription
pairingRequested
接收等待接受或拒绝的设备配对请求。
graphql
subscription pairingRequested {
pairingRequested { fromIp fromId fromName deviceType verificationCode identityChanged }
}subscription
pairingCompleted
接收设备配对完成通知。
graphql
subscription pairingCompleted {
pairingCompleted { deviceId deviceName ip port deviceType requestId }
}subscription
pairingStarted
接收配对尝试开始通知。
graphql
subscription pairingStarted {
pairingStarted { verificationCode deviceId deviceName error }
}subscription
pairingFailed
接收配对尝试失败通知。
graphql
subscription pairingFailed {
pairingFailed { verificationCode deviceId deviceName error }
}subscription
pairingCanceled
接收配对尝试取消通知。
graphql
subscription pairingCanceled {
pairingCanceled { verificationCode deviceId deviceName error }
}mutation
cancelPairing
取消指定设备当前正在进行的配对。
graphql
mutation cancelPairing($peerId: ID!) {
cancelPairing(peerId: $peerId)
}mutation
deletePeer
删除设备及其一对一聊天记录;频道仍引用该设备时保留频道设备记录。
graphql
mutation deletePeer($peerId: ID!) {
deletePeer(peerId: $peerId)
}mutation
pairPeer
发起聊天配对或管理登录;返回 true 表示已受理。
graphql
mutation pairPeer($peerId: ID!, $input: PairPeerInput!) {
pairPeer(peerId: $peerId, input: $input)
}mutation
respondToPairing
接受或拒绝该设备待处理的配对请求或信任确认。
graphql
mutation respondToPairing($peerId: ID!, $accepted: Boolean!) {
respondToPairing(peerId: $peerId, accepted: $accepted)
}mutation
unpairPeer
在本机取消配对并清除管理权限,保留聊天记录。
graphql
mutation unpairPeer($peerId: ID!) {
unpairPeer(peerId: $peerId)
}query
peerFileUrl
使用设备当前保存的地址生成文件下载链接。
graphql
query peerFileUrl($peerId: ID!, $fileId: String!) {
peerFileUrl(peerId: $peerId, fileId: $fileId)
}query
peers
列出所有已保存设备,包括已配对、未配对及仅供频道引用的记录。
graphql
query peers {
peers { id name ip status port deviceType createdAt updatedAt }
}