iCloud Find My 是一个用于通过 iCloud CLI(pyicloud)访问“查找”设备位置和电池状态的技能。它面向需要查询家庭设备位置与电量信息的场景,例如出门前检查设备电量、获取用户当前位置、判断用户在家或外出、以及在电量低于 30% 且未充电时发出提醒。
主要能力
该技能可以列出家庭共享中所有设备,并输出设备名称、显示名称、位置、电池电量、电池状态和设备类别。位置信息以 Python 字典形式给出,包含 latitude、longitude、timeStamp(毫秒)和 horizontalAccuracy 等字段。电池电量为 0.0 到 1.0 之间的数值,乘以 100 可得到百分比;电池状态为 "Charging" 或 "NotCharging"。
使用方式
首先安装 pyicloud:
brew install pipx pipx install pyicloud
然后进行一次性认证。向用户询问 Apple ID,并运行:
icloud --username their.email@example.com --with-family --list
用户需要输入密码并完成双重验证。会话会被保存,持续 1-2 个月。建议将 Apple ID 记录到 TOOLS.md 或工作区配置中,例如:
iCloud Find My
Apple ID: their.email@example.com
列出所有设备:
icloud --username APPLE_ID --with-family --list
输出格式示例:
Name - Liam's iPhone Display Name - iPhone 15 Pro Location - {'latitude': 52.248, 'longitude': 0.761, 'timeStamp': 1767810759054, ...} Battery Level - 0.72 Battery Status - NotCharging Device Class - iPhone
解析提示:设备之间以 ------------------------------ 分隔;Location 是 Python 字典,可使用 eval() 或正则解析;Battery Level 为 0.0-1.0;Battery Status 为 "Charging" 或 "NotCharging";Location 字段包括 latitude、longitude、timeStamp(毫秒)、horizontalAccuracy。
获取特定设备:
icloud --username APPLE_ID --with-family --list | grep -A 10 "iPhone"
解析位置:
icloud --username APPLE_ID --with-family --list |
grep -A 10 "Device Name" |
grep "Location" |
sed "s/Location.*- //"
然后使用 Python 解析该 Python 字典字符串,或用正则提取坐标。
解析电池:
icloud --username APPLE_ID --with-family --list |
grep -A 10 "Device Name" |
grep "Battery Level"
设备名称来自 iCloud,可能包含花式 Unicode 撇号(U+2019 ')而非 ASCII 撇号,也可能完全没有撇号(例如 "Lindas iPhone")。必要时使用不区分大小写的匹配并规范化撇号。
会话管理
会话持续 1-2 个月,存储在用户主目录中。过期后需重新运行认证步骤。PyiCloud 会在每次请求时自动验证。
常见模式
出门前检查电池:
Get battery for specific device
icloud --username ID --with-family --list |
grep -B 2 -A 5 "iPhone" |
grep "Battery Level"
获取当前位置:
Extract location dict and parse coordinates
icloud --username ID --with-family --list |
grep -A 10 "iPhone" |
grep "Location" |
sed "s/.*- //" |
python3 -c "import sys; loc = eval(sys.stdin.read()); print(f"{loc['latitude']}, {loc['longitude']}")"
检查设备是否在充电:
icloud --username ID --with-family --list |
grep -A 10 "iPhone" |
grep "Battery Status"
主动使用场景
电池警告:在日历事件(外出)前检查电池电量。位置上下文:通过检查用户当前位置来回答“附近”查询。在家/外出检测:根据坐标判断用户是否在家。低电量提醒:如果电量低于 30% 且未充电则发出警告。
故障排除
认证错误:会话过期需重新认证;Apple ID 错误需检查存储的 ID;需要双重验证时完成双重验证流程。无位置可用:设备离线、关闭“查找”或定位服务关闭。找不到设备:使用 --list 检查确切设备名称;名称区分大小写;可能包含 Unicode 撇号。
限制
需要 macOS(iCloud API 特性)。必须启用家庭共享才能看到家庭设备。设备活跃时位置每约 1-5 分钟更新一次。电池读数可能被缓存(检查时间戳)。