Apple iCloud Suite

这个 Skill 提供对 Apple iCloud 主要服务的命令行访问能力。

✅ 实测验证结果 (2026-02-05)

🔐 认证方式说明

⚠️ 重要发现

pyicloud API 需要使用 主密码 + 双重认证码，不支持应用专用密码！

CalDAV (日历) 可以使用 应用专用密码。

认证流程

from pyicloud import PyiCloudService
import os

# 中国大陆用户设置环境变量
os.environ['icloud_china'] = '1'

# 使用主密码连接
api = PyiCloudService('your@email.com', '主密码', china_mainland=True)

# 处理双重认证
if api.requires_2fa:
    code = input("请输入 iPhone 上收到的验证码: ")
    api.validate_2fa_code(code)
    print("验证成功！")

📷 Part 1: 照片 (pyicloud) ✅ 已验证

列出相册

#!/usr/bin/env python3
import os
os.environ['icloud_china'] = '1'
from pyicloud import PyiCloudService

api = PyiCloudService('your@email.com', 'password', china_mainland=True)

# 处理双重认证...

# 列出所有相册
photos = api.photos
print(f'相册数量: {len(photos.albums)}')

for album_name in photos.albums:
    print(f'📁 {album_name}')

列出照片

# 获取照片库
library = photos.albums['Library']

# 列出最近的照片
for i, photo in enumerate(library.photos):
    if i >= 10: break
    print(f'📷 {photo.filename} | {photo.created}')

下载照片

# 获取第一张照片
photo = next(iter(library.photos))
print(f'正在下载: {photo.filename}')

# 下载
download = photo.download()
with open(photo.filename, 'wb') as f:
    f.write(download.raw.read())

print(f'✅ 已保存: {photo.filename}')

使用 icloudpd 批量下载

# 安装
pip install icloudpd

# 下载所有照片 (中国大陆)
icloudpd --directory ~/Pictures/iCloud \
         --username your@email.com \
         --domain cn

# 下载最近 100 张
icloudpd -d ~/Pictures/iCloud -u your@email.com --recent 100

# 持续同步 (每小时)
icloudpd -d ~/Pictures/iCloud -u your@email.com --watch-with-interval 3600

💾 Part 2: iCloud Drive ✅ 已验证

浏览文件

#!/usr/bin/env python3
import os
os.environ['icloud_china'] = '1'
from pyicloud import PyiCloudService

api = PyiCloudService('your@email.com', 'password', china_mainland=True)

# 处理双重认证...

# 列出根目录
drive = api.drive
for item in drive.dir():
    print(f'📂 {item}')

# 进入子目录
subfolder = drive['Downloads']
for item in subfolder.dir():
    print(f'  📄 {item}')

下载文件

# 下载文件
file = drive['文件名.pdf']
with file.open(stream=True) as response:
    with open('本地文件.pdf', 'wb') as f:
        f.write(response.raw.read())

📱 Part 3: 查找设备 ✅ 已验证

列出所有设备

#!/usr/bin/env python3
import os
os.environ['icloud_china'] = '1'
from pyicloud import PyiCloudService

api = PyiCloudService('your@email.com', 'password', china_mainland=True)

# 处理双重认证...

# 列出所有设备
print('📱 我的设备:')
for device in api.devices:
    print(f'  - {device}')

设备定位和操作

# 获取特定设备
iphone = api.devices['iPhone']

# 获取位置
location = iphone.location()
print(f'位置: {location}')

# 播放声音
iphone.play_sound()

# 丢失模式
iphone.lost_device(number='123456789', message='请联系我')

📅 Part 4: 日历 (CalDAV) ✅ 已验证

日历功能使用 CalDAV 协议直接访问 iCloud 日历，需要应用专用密码。

🎉 测试结果

📅 日历列表:
  1. 📁 大麦
  2. 📁 提醒 ⚠️
  3. 📁 哔哩哔哩
  4. 📁 携程
  5. 📁 个人
  6. 📁 工作

共 6 个日历

📅 今天的事件 (2026-02-05):
  📌 和sissi吃芈重山
     📆 2026-02-05 20:00-21:00

使用 icloud_calendar.py

# 设置环境变量
export ICLOUD_USERNAME="your@email.com"
export ICLOUD_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx"  # 应用专用密码！

# 列出日历
python icloud_calendar.py list

# 查看今天事件
python icloud_calendar.py today

# 查看未来 N 天
python icloud_calendar.py week 7

# 创建事件
python icloud_calendar.py new 2026-02-10 10:00 11:00 "开会"
python icloud_calendar.py new 2026-02-10 "全天事件"

# 搜索事件
python icloud_calendar.py search 会议

⚠️ 重要：日历需要应用专用密码

日历功能使用 CalDAV 协议，需要应用专用密码（不是主密码）：

1. 登录 https://appleid.apple.com
2. 进入「登录与安全」→「应用专用密码」
3. 点击「+」生成新密码
4. 复制密码（格式: xxxx-xxxx-xxxx-xxxx）

配置 vdirsyncer (可选)

创建 ~/.config/vdirsyncer/config：

[general]
status_path = "~/.local/share/vdirsyncer/status/"

[pair icloud_calendar]
a = "icloud_calendar_remote"
b = "icloud_calendar_local"
collections = ["from a", "from b"]
conflict_resolution = "a wins"

[storage icloud_calendar_remote]
type = "caldav"
url = "https://caldav.icloud.com/"
username = "your@email.com"
# 使用应用专用密码
password.fetch = ["command", "cat", "~/.config/vdirsyncer/icloud_password"]

[storage icloud_calendar_local]
type = "filesystem"
path = "~/.local/share/vdirsyncer/calendars/"
fileext = ".ics"

配置 khal

创建 ~/.config/khal/config：

[calendars]
[[icloud]]
path = ~/.local/share/vdirsyncer/calendars/*
type = discover

[default]
default_calendar = Home
highlight_event_days = True

[locale]
timeformat = %H:%M
dateformat = %Y-%m-%d

日历命令

# 首次设置
vdirsyncer discover
vdirsyncer sync

# 查看事件
khal list                       # 今天
khal list today 7d              # 未来7天

# 创建事件
khal new 2026-01-15 10:00 11:00 "会议"

# 同步
vdirsyncer sync

🔧 完整 Python 脚本

icloud_tool.py

#!/usr/bin/env python3
"""
Apple iCloud 命令行工具
用法: python icloud_tool.py [photos|drive|devices] [子命令]
"""

import sys
import os

os.environ['icloud_china'] = '1'

from pyicloud import PyiCloudService

def get_api():
    """连接 iCloud"""
    username = os.environ.get('ICLOUD_USERNAME') or input("Apple ID: ")
    password = os.environ.get('ICLOUD_PASSWORD') or input("密码: ")
    
    api = PyiCloudService(username, password, china_mainland=True)
    
    if api.requires_2fa:
        print("\n🔐 需要双重认证")
        print("请查看 iPhone 上的验证码")
        code = input("验证码: ")
        if not api.validate_2fa_code(code):
            print("❌ 验证失败")
            sys.exit(1)
        print("✅ 验证成功!\n")
    
    return api

def cmd_photos(api, args):
    """照片命令"""
    photos = api.photos
    
    if not args or args[0] == 'albums':
        print('📷 相册列表:')
        for name in photos.albums:
            print(f'  📁 {name}')
    
    elif args[0] == 'list':
        limit = int(args[1]) if len(args) > 1 else 10
        library = photos.albums['Library']
        print(f'📷 最近 {limit} 张照片:')
        for i, p in enumerate(library.photos):
            if i >= limit: break
            print(f'  {i+1}. {p.filename} | {p.created}')
    
    elif args[0] == 'download':
        index = int(args[1]) - 1 if len(args) > 1 else 0
        library = photos.albums['Library']
        for i, p in enumerate(library.photos):
            if i == index:
                print(f'正在下载: {p.filename}')
                dl = p.download()
                with open(p.filename, 'wb') as f:
                    f.write(dl.raw.read())
                print(f'✅ 已保存: {p.filename}')
                break

def cmd_drive(api, args):
    """iCloud Drive 命令"""
    drive = api.drive
    
    if not args or args[0] == 'list':
        print('💾 iCloud Drive:')
        for item in drive.dir():
            print(f'  📂 {item}')
    
    elif args[0] == 'cd' and len(args) > 1:
        folder = drive[args[1]]
        print(f'📂 {args[1]}:')
        for item in folder.dir():
            print(f'  📄 {item}')

def cmd_devices(api, args):
    """设备命令"""
    print('📱 我的设备:')
    for d in api.devices:
        print(f'  - {d}')

def main():
    if len(sys.argv) < 2:
        print("""
🍎 Apple iCloud 命令行工具

用法: python icloud_tool.py <命令> [参数]

命令:
  photos albums          列出相册
  photos list [N]        列出最近 N 张照片
  photos download N      下载第 N 张照片
  
  drive list             列出 iCloud Drive
  drive cd <文件夹>      进入文件夹
  
  devices                列出设备

环境变量:
  ICLOUD_USERNAME        Apple ID
  ICLOUD_PASSWORD        密码
        """)
        sys.exit(0)
    
    api = get_api()
    cmd = sys.argv[1]
    args = sys.argv[2:]
    
    if cmd == 'photos':
        cmd_photos(api, args)
    elif cmd == 'drive':
        cmd_drive(api, args)
    elif cmd == 'devices':
        cmd_devices(api, args)
    else:
        print(f'未知命令: {cmd}')

if __name__ == '__main__':
    main()

📋 快速参考

pyicloud (需要主密码 + 2FA)

CalDAV (使用应用专用密码)

⚠️ 注意事项

1. pyicloud 使用主密码：不支持应用专用密码，需要双重认证
2. CalDAV 使用应用专用密码：在 appleid.apple.com 生成
3. 中国大陆用户：
   • pyicloud: china_mainland=True 或 os.environ['icloud_china'] = '1'
   • icloudpd: --domain cn
4. 会话缓存：首次认证后会话会保存在 ~/.pyicloud/
5. 备忘录限制：Apple Notes 没有公开 API，建议使用 iCloud.com 网页版

🔗 相关资源

• pyicloud GitHub
• icloudpd GitHub
• vdirsyncer 文档
• khal 文档
• todoman 文档