giil

GIIL — 获取互联网链接中的图片

一款零设置的命令行工具，可从云端照片分享链接下载全分辨率图片。它是连接 iPhone 截图与远程 AI 编码会话的关键一环。

为什么要开发它

主要用途：远程 AI 辅助调试

你通过 SSH 连接到运行 Claude Code、Codex 或其他 AI 助手的远程服务。你需要调试 iPhone 上的 UI 问题，但怎样才能把截图传到远程终端？

没有 giil 时：

Download image locally → SCP to server → Tell AI the path
Email yourself → Download on server → Hope it works
Set up complex file sync between devices

使用 giil 后：

giil "https://share.icloud.com/photos/0a1Abc_xYz..." --json
# {"path": "/tmp/icloud_20240115_143022.jpg", "width": 1170, ...}

只需一条命令，AI 就能立即看到截图。无需传输文件，也无需切换上下文。

工作流

iPhone Screenshot → iCloud Sync → Photos.app Share Link → Paste to SSH → giil Downloads → AI Analyzes

云端分享链接为何难以处理

问题	难点	giil 的解决方式
JavaScript 密集型 SPA	标准 curl/wget 无法执行 JS	通过 Playwright 使用无头 Chromium
动态图片加载	图片从 CDN 异步加载	拦截网络请求，捕获 CDN 响应
没有直接下载链接	URL 与会话绑定且会过期	点击“下载”按钮或拦截实时请求
复制/粘贴会损失画质	手动截图会压缩图片	从源文件获取原始分辨率
Apple 上的 HEIC 格式	许多工具无法处理 HEIC/HEIF	根据平台进行转换（sips/heif-convert）

快速开始

# Install
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/giil/main/install.sh?v=3.0.0" | bash

# Download single image
giil "https://share.icloud.com/photos/02cD9okNHvVd-uuDnPCH3ZEEA"

# JSON output (best for AI workflows)
giil "https://share.icloud.com/photos/..." --json

# Download entire album
giil "https://share.icloud.com/photos/..." --all --output ~/album

**注意：**首次运行时会下载 Playwright Chromium（约 200MB，缓存在 ~/.cache/giil/ 中）。

支持的平台

平台	URL 模式	方法	是否需要浏览器
iCloud	share.icloud.com/photos/*、icloud.com/photos/#*	四层捕获策略	是
Dropbox	dropbox.com/s/*、dropbox.com/scl/fi/*	直接使用 curl（raw=1）	否
Google Photos	photos.app.goo.gl/*、photos.google.com/share/*	提取 URL + =s0 修饰符	是
Google Drive	drive.google.com/file/d/*、drive.google.com/open?id=*	多层策略并检测身份验证	是

**Dropbox 快速通道：**直接使用 curl 下载，无需启动浏览器，通常只需 1–2 秒。

**Google Photos 全分辨率：**自动在 CDN URL 后附加 =s0，以获取最高分辨率。

四层捕获策略

giil 采用回退策略，以尽可能提高可靠性：

1. 下载按钮（最高画质）

• 使用 9 种选择器模式定位可见的“下载”按钮
• 点击按钮并等待浏览器下载事件
• 获取原始文件（无重新编码损失）
• 支持 HEIC/HEIF 原图

2. 网络拦截（全分辨率）

• 监控所有 HTTP 响应，匹配 CDN 模式（cvws.icloud-content.com 等）
• 按 content-type 过滤（仅保留图片格式）
• 捕获最大图片缓冲区（阈值 >10KB，以跳过缩略图）
• 即使 UI 元素被遮挡也能正常工作

3. 元素截图

• 使用 10 种选择器模式查询图片元素
• 确认元素可见且尺寸至少为 100×100 像素
• 对该元素截取 PNG 格式的截图

4. 视口截图（最后手段）

• 捕获可见视口（1920×1080）
• 只要页面加载成功，就始终能成功
• 可用于调试页面状态

命令参考

基本用法

giil <url> [options]

选项

标志	默认值	描述
--output DIR	.	输出目录
--preserve	off	保留原始字节（跳过 MozJPEG 压缩）
--convert FMT	—	转换为：jpeg、png、webp
--quality N	85	JPEG 质量，范围为 1-100
--base64	off	将 base64 输出到标准输出（不保存文件）
--json	off	输出 JSON 元数据
--all	off	下载相册中的所有照片
--timeout N	60	页面加载超时时间，单位为秒
--debug	off	失败时保存调试产物
--verbose	off	显示详细进度
--trace	off	启用 Playwright 跟踪以进行深度调试
--print-url	off	输出解析后的 CDN URL（不下载）
--debug-dir DIR	.	调试产物目录
--update	off	强制重新安装依赖项

输出模式

默认：文件路径

giil "https://share.icloud.com/photos/XXX"
# stdout: /current/dir/icloud_20240115_143245.jpg

脚本：

IMAGE_PATH=$(giil "..." --output ~/Downloads 2>/dev/null)

JSON 模式

giil "https://share.icloud.com/photos/XXX" --json

成功：

{
  "ok": true,
  "schema_version": "1",
  "platform": "icloud",
  "path": "/absolute/path/to/icloud_20240115_143245.jpg",
  "datetime": "2024-01-15T14:32:45.000Z",
  "sourceUrl": "https://cvws.icloud-content.com/...",
  "method": "network",
  "size": 245678,
  "width": 4032,
  "height": 3024
}

错误：

{
  "ok": false,
  "schema_version": "1",
  "platform": "icloud",
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Login required - link is not publicly shared",
    "remediation": "The file is not publicly shared. The owner must enable public access."
  }
}

字段	描述
method	捕获策略：download、network、element-screenshot、viewport-screenshot、direct
error.code	错误代码（参见退出代码）
error.remediation	建议的修复方法

Base64 模式

# Decode to file
giil "..." --base64 | base64 -d > image.jpg

# Create data URI
echo "data:image/jpeg;base64,$(giil '...' --base64)" > uri.txt

# Pipe to API
giil "..." --base64 | curl -X POST -d @- https://api.example.com/upload

仅 URL 模式

giil "https://share.icloud.com/photos/XXX" --print-url
# stdout: https://cvws.icloud-content.com/B/...

适用于外部下载器、缓存或调试。

相册模式

使用 --all 下载整个共享相册：

giil "https://share.icloud.com/photos/XXX" --all --output ~/album

工作原理

1. 加载相册页面
2. 检测缩略图网格（11 种选择器策略）
3. 对每张缩略图：点击 → 捕获 → 关闭 → 继续下一张
4. 每张照片输出一个路径或 JSON

相册功能

• 容错性强： 一张照片失败时会继续处理下一张
• 带索引的文件名： 使用 _001、_002 等编号排序
• 速率限制： 照片之间延迟 1 秒（礼貌地下载）
• 指数退避： 收到速率限制信号时自动重试

相册输出

# Default
/path/to/album/icloud_20240115_143245_001.jpg
/path/to/album/icloud_20240115_143246_002.jpg

# With --json
{"path": "...001.jpg", "method": "download", "width": 4032, ...}
{"path": "...002.jpg", "method": "network", "width": 3024, ...}

图像处理管线

EXIF 日期时间提取

生成文件名时的优先顺序：

1. DateTimeOriginal（拍摄照片的时间）
2. CreateDate
3. DateTimeDigitized
4. ModifyDate
5. 当前时间（回退值）

HEIC/HEIF 转换

平台	工具	备注
macOS	sips	内置，始终可用
Linux	heif-convert	需要 libheif-examples 软件包

# Install HEIC support on Linux
sudo apt-get install libheif-examples  # Debian/Ubuntu
sudo dnf install libheif-tools         # Fedora

MozJPEG 压缩（默认）

默认情况下，giil 使用 MozJPEG 压缩，以获得最佳体积和质量：

• 比标准 JPEG 小 40-50%，且质量相当
• 质量为 85（可通过 --quality 配置）
• 使用 --preserve 保留原始字节

文件名格式

icloud_YYYYMMDD_HHMMSS[_NNN][_counter].jpg
        │              │      │
        │              │      └── Collision counter (if file exists)
        │              └── Album index (--all mode only)
        └── Date/time from EXIF or capture time

下载验证

giil 分三个阶段验证下载内容：

1. Content-Type 验证

验证 HTTP Content-Type 是否与预期的图像类型匹配。

2. 魔数检测

无论服务器如何声明，都会验证二进制签名：

格式	魔数
JPEG	FF D8 FF
PNG	89 50 4E 47
GIF	47 49 46 38
WebP	包含 WEBP 的 RIFF 容器
HEIC/HEIF	ISO 基础媒体文件（ftyp 框）

3. HTML 错误页面检测

拒绝包含 HTML 内容的响应，因为这表示返回的是错误页面而非图像。

退出代码

代码	名称	描述
0	成功	已捕获并保存/输出图像
1	捕获失败	所有捕获策略均失败
2	用法错误	参数无效或缺少 URL
3	依赖项错误	Node.js、Playwright 或 Chromium 问题
10	网络错误	超时、DNS 解析失败或主机无法访问
11	需要身份验证	重定向到登录页面、需要密码或未公开共享
12	未找到	链接已过期、文件已删除或返回 404
13	不支持的类型	视频、Google 文档或非图像内容
20	内部错误	giil 中的错误（请报告！）

脚本：

giil "https://share.icloud.com/photos/XXX" 2>/dev/null
case $? in
    0) echo "Success!" ;;
    10) echo "Network issue - retry later" ;;
    11) echo "Link not public - ask owner to share" ;;
    12) echo "Link expired" ;;
    *) echo "Failed with code $?" ;;
esac

环境变量

运行时变量

变量	描述	默认值
XDG_CACHE_HOME	缓存目录根路径	~/.cache
GIIL_HOME	giil 运行时目录	$XDG_CACHE_HOME/giil
PLAYWRIGHT_BROWSERS_PATH	自定义 Chromium 缓存	$GIIL_HOME/ms-playwright
GIIL_NO_GUM	禁用 gum 样式	未设置
GIIL_CHECK_UPDATES	启用更新检查	未设置

安装程序变量

变量	描述	默认值
DEST	自定义安装目录	~/.local/bin
GIIL_SYSTEM	安装到 /usr/local/bin	未设置
GIIL_VERIFY	验证 SHA256 校验和	未设置
GIIL_VERSION	安装指定版本	最新版本

文件位置

路径	用途
~/.local/bin/giil	主脚本
~/.cache/giil/	运行时目录
~/.cache/giil/node_modules/	Playwright、Sharp、exifr
~/.cache/giil/extractor.mjs	生成的 Node.js 脚本
~/.cache/giil/ms-playwright/	Chromium 浏览器缓存

调试产物（使用 --debug 后失败时生成）

文件	内容
giil_debug_<timestamp>.png	全页截图
giil_debug_<timestamp>.html	页面 DOM 内容

性能

阶段	首次运行	后续运行
Chromium 下载	30-60s	跳过（已缓存）
浏览器启动	2-3s	2-3s
页面加载	3-10s	3-10s
图像捕获	1-5s	1-5s
总计	40-80s	5-15s

Dropbox： 1-2 秒（直接使用 curl，无需浏览器）。

故障排除

“需要身份验证”错误

链接未公开共享。所有者必须在云服务设置中启用公开访问。

超时错误

增加超时时间：giil "..." --timeout 120

捕获到错误或尺寸过小的图像

使用 --debug 运行以查看页面状态。提交问题时附上调试产物。

Linux 上 HEIC 转换失败

sudo apt-get install libheif-examples  # Debian/Ubuntu
sudo dnf install libheif-tools         # Fedora

Chromium 启动失败

giil "..." --update
# Or manually:
cd ~/.cache/giil && npx playwright install --with-deps chromium

调试

# Verbose output
giil "..." --verbose

# Debug artifacts on failure
giil "..." --debug

# Playwright trace (generates trace.zip)
giil "..." --trace
npx playwright show-trace ~/.cache/giil/trace.zip

安装

# One-liner (recommended)
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/giil/main/install.sh?v=3.0.0" | bash

# Verified installation
GIIL_VERIFY=1 curl -fsSL .../install.sh | bash

# System-wide
GIIL_SYSTEM=1 curl -fsSL .../install.sh | bash

# Manual
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/giil/main/giil -o ~/.local/bin/giil
chmod +x ~/.local/bin/giil

卸载

rm ~/.local/bin/giil
rm -rf ~/.cache/giil
rm -rf ~/.cache/ms-playwright  # If no other Playwright tools

安全与隐私

• 本地运行： 所有处理都在你的计算机上进行
• 无遥测： 除云服务外，不会向任何地方发送数据
• 不存储身份验证信息： 使用公开共享机制
• 不保存 Cookie： 浏览器上下文为临时状态
• 清理临时文件： 处理完成后清理下载的文件

与 Flywheel 集成

工具	集成方式
Claude Code	通过 SSH 下载截图，用于视觉调试
NTM	在多 Agent 会话之间共享图像
Agent Mail	将下载的图像附加到 Agent 消息中
CASS	搜索使用过 giil 的会话，以获取图像上下文