用途：用 Planet SDK v2 大规模拉取 PlanetScope 影像（数百到 10 万+ AOI）。SDK 本身很薄，没有重试、批处理、冷存储解冻感知和场景分组，这些都需要自行构建。
主要能力与架构：把任务拆成 search → activate → extract 三阶段，各自维护 JSONL 缓存、并发参数和断点续跑逻辑。search 是廉价元数据调用，客户端限速；activate 受 Planet 冷存储解冻队列限制，约 10 个冷场景/分钟/账户；extract 通过 GDAL 做 HTTP range 读取，约 0.5 秒/1.5km patch。
关键做法：按 item_id 对 patch 分组，同一场景只激活一次再读取多个窗口，可减少 10-20 倍激活量。search 与 extract 按 patch 索引分片，每片 1-5k 条；extract 按 hash(item_id) 分片以保持 GDAL /vsicurl/ 缓存热度。PSScene ortho_analytic_4b_sr 自 2022 年起为 COG，激活后用签名 URL 做 range 读取，比 Orders API 快约 100 倍；仅在全条带下载或需服务端重投影时用 Orders API。
GDAL 配置：通过 rasterio.Env(**opts) 传入，数值须为 Python int 而非字符串。不要设置 CPL_VSIL_CURL_ALLOWED_EXTENSIONS，因为 Planet 签名 URL 以 ?token= 结尾而非 .tif。
重试：SDK 无内置重试，需包裹每个 Data API 调用，处理 TooManyRequests(429)、含 503/502/504/Server Error 的 APIError，以及 httpx 超时/连接类异常，指数退避。
并发参考：search 64-128，activate 32-96，extract 32-64。SR 与 UDM2 用 asyncio.gather 并行激活。
可靠性注意：约 24% 的 activate 返回 active 但 URL 损坏，需二次激活；部分返回 location=null；2018 年前存档及印度、芬兰等区域存在永久失效资产，预算 3-5% 不可恢复；冷存储解冻 p99 可达 45 分钟以上。
限制：账户级激活上限未公开；UDM2 比 SR 慢约 3 倍；patch 级云量不等于场景级云量，需用 UDM2 在实际 AOI 上后验。避免用 Orders API 做窗口化大规模访问、在 per-patch 循环内激活 UDM2、无上限轮询 wait_asset、重提取前清空输出等反模式。