TransferKit

TransferKit 是 AgentOS 里的跨设备文件传输服务。
它让第三方 App 能够在局域网内的 AgentOS 设备之间安全地传输文件。

它解决什么问题

TransferKit 帮你处理：

• 向目标设备发送文件
• 实时跟踪传输进度
• 接收来自其他设备的文件
• 管理接收策略（自动接收 / 手动确认）
• 传输历史记录管理

最适合什么场景

• 你要实现跨设备文件分享
• 你要让用户在多台设备间传文件
• 你要构建多设备协作工作流
• 你的 App 需要在设备间同步文件数据

核心能力

发送文件

• SDK（TypeScript）：sdk.transferkit.send(bearerToken, { targetDeviceId, files, targetBundleId })
• SDK（Python）：await sdk.transferkit.send(bearer_token, {"targetDeviceId": "...", "files": [...]})
• HTTP：POST /transferkit/send

请求体：

字段	类型	说明
targetDeviceId	string	目标设备 ID（从 DiscoveryKit 获取）
targetBundleId	string?	目标设备上的 App bundleId
files	array	文件列表
files[].fileName	string	文件名
files[].filePath	string	文件路径
files[].size	int	文件大小（字节）
files[].mimeType	string?	MIME 类型

返回 TransferSession，包含 transferId 和初始 state。

跟踪传输进度

实时 SSE 流：

• SDK：sdk.transferkit.streamProgress(bearerToken, transferId)
• HTTP：GET /transferkit/transfers/<transferId>/stream

也可轮询状态：

• SDK：sdk.transferkit.getStatus(bearerToken, transferId)
• HTTP：GET /transferkit/transfers/<transferId>/status

传输状态（state）：

状态	说明
preparing	正在准备
transferring	传输中
completed	已完成
failed	失败
cancelled	已取消

取消传输

• SDK：sdk.transferkit.cancel(bearerToken, transferId)
• HTTP：POST /transferkit/transfers/<transferId>/cancel

接收文件

通过 SSE 监听传入文件事件：

• SDK：sdk.transferkit.receiveStream(bearerToken)
• HTTP：GET /transferkit/receive/stream

当接收策略为 requireConfirm 时，需要手动响应：

• SDK：sdk.transferkit.respond(bearerToken, transferId, { accept: true })
• HTTP：POST /transferkit/transfers/<transferId>/respond

接收策略管理

设置接收策略：

• SDK：sdk.transferkit.setPolicy(bearerToken, { policy: 'autoAccept' })
• HTTP：PUT /transferkit/receive/policy

获取当前策略：

• SDK：sdk.transferkit.getPolicy(bearerToken)
• HTTP：GET /transferkit/receive/policy

策略	说明
autoAccept	自动接收所有文件
requireConfirm	每次接收前需要手动确认

传输历史

• 查询记录：GET /transferkit/history?deviceId=...&userId=...
• 删除单条：DELETE /transferkit/history/<recordId>
• 清空历史：DELETE /transferkit/history

安全机制

• 文件路径验证：确保文件在 App 沙盒内，防止路径穿越
• 权限隔离：每个 App 只能查看和管理自己的传输
• Bearer token 鉴权：所有操作需要有效的 AppKit token

与 DiscoveryKit 的关系

TransferKit 依赖 DiscoveryKit 提供目标设备信息：

• targetDeviceId 来自 DiscoveryKit 的 getPeers 结果
• 发送前需要确保目标设备在线且已注册

与 AuthKit 的关系

TransferKit 使用 AuthKit 的 userId 标识发送者身份：

• 传输记录按 deviceId:userId 分作用域
• 接收方可以看到发送者的身份信息

什么时候不一定需要 TransferKit

• 你不需要设备间传文件
• 你的文件通过云端服务器中转
• 你不在局域网环境中运行

下一步看什么

• 发送前需要先发现设备：看 DiscoveryKit
• 需要先获取用户身份：看 AuthKit
• 需要注册 App：看 AppKit