名称： icloud-findmy
描述： 通过 iCloud 查询家人设备的“查找”位置与电池状态。
主页： https://github.com/picklepete/pyicloud
元数据： {"clawdbot":{"emoji":"📍","requires":{"bins":["icloud"]},"install":[{"id":"pipx","kind":"shell","command":"brew install pipx && pipx install pyicloud","bins":["icloud"],"label":"安装 PyiCloud (pipx)"}]}}

iCloud 查找

通过 iCloud CLI (pyicloud) 获取“查找”中设备的位置与电池状态。

设置

1. 安装 pyicloud:

brew install pipx
pipx install pyicloud

2. 认证（一次性操作）:

向用户询问其 Apple ID，然后运行：

icloud --username their.email@example.com --with-family --list

用户需要输入密码并完成双重认证。会话将被保存，有效期 1-2 个月。

3. 存储 Apple ID:

将 Apple ID 添加到你的 TOOLS.md 或工作区配置中，以便后续查询时使用：

## iCloud 查找
Apple ID: their.email@example.com

使用

列出所有设备

icloud --username APPLE_ID --with-family --list

输出格式:

------------------------------
名称           - Liam's iPhone
显示名称       - iPhone 15 Pro
位置           - {'latitude': 52.248, 'longitude': 0.761, 'timeStamp': 1767810759054, ...}
电池电量       - 0.72
电池状态       - NotCharging
设备类型       - iPhone
------------------------------

解析提示:
- 设备之间用 ------------------------------ 分隔
- 位置信息是一个 Python 字典（可使用 eval() 或正则表达式解析）
- 电池电量范围是 0.0-1.0（乘以 100 得到百分比）
- 电池状态："Charging" 或 "NotCharging"
- 位置字段：latitude（纬度）、longitude（经度）、timeStamp（时间戳，毫秒）、horizontalAccuracy（水平精度）

获取特定设备

通过 grep 过滤输出以查找特定设备：

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 会在每次请求时自动验证会话

常用模式

外出前检查电池电量:

# 获取特定设备的电池电量
icloud --username ID --with-family --list | \
  grep -B 2 -A 5 "iPhone" | \
  grep "Battery Level"

获取当前位置:

# 提取位置字典并解析坐标
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 分钟更新一次
• 电池读数可能被缓存（请检查时间戳）