夸克旅行足迹报告
把夸克网盘手机相册照片整理成一份自包含的「去过的地方」旅行地图 HTML 报告：自动统计到访城市/国家、按地理分区汇总、提炼旅行行为洞察，并配代表照片缩略图。
适用场景
- 「把我网盘里的照片整理成一份去过的地方报告」
- 「基于相册生成旅行地图 / 旅行足迹」
- 「统计我去过哪些城市、哪些国家，各多少张照片」
- 「把相册照片按拍摄地点聚类成目的地」
前置依赖
- 夸克网盘官方 skill（
quarkclouddrive）已安装且账号已授权绑定。脚本会自动定位该 skill 并复用其 CLI（scripts/quark-drive.cjs）。 - Python 3 + Pillow（第 4 步内嵌缩略图用，
pip install Pillow）。 - Node.js >= 16（夸克 CLI 运行时）。
首次调用夸克 CLI 前，先确保夸克 skill 就绪：
bash ~/.workbuddy/skills/quarkclouddrive*/scripts/install.sh
会话参数（贯穿全流程）
调用夸克 CLI 必须携带两个公共参数，同一对话内所有步骤复用同一个 session_id：
session_id：格式{unix秒时间戳}-{6位随机字母数字}，如1788752429-4DQM0P，禁止语义化命名。session_input：用户原始提问，逐字复制、禁止改写。
SESSION_ID=$(date +%s)-$(openssl rand -hex 3)
工作流（五步流水线）
所有脚本写入一个统一的工作目录 --base，中间产物依次衔接：
| 步骤 | 脚本 | 输入 | 输出 |
|---|---|---|---|
| 1 遍历收集 | scripts/traverse.py |
夸克网盘目录 | all_photos.jsonl |
| 2 聚类目的地 | scripts/cluster.py |
all_photos.jsonl |
destinations_full.json |
| 3 校验缩略图 | scripts/verify_thumbs.py |
destinations_full.json |
report_data.json |
| 4 内嵌图片 | scripts/embed_thumbs.py |
report_data.json |
thumbs_b64.json |
| 5 生成报告 | scripts/gen_report.py |
report_data.json + thumbs_b64.json |
报告.html |
第 1 步：递归遍历收集照片拍摄地点
python scripts/traverse.py \
--base <工作目录> \
--session-id "$SESSION_ID" \
--session-input "<用户原始提问>" \
--start-fid 0
--start-fid默认0（网盘根目录），递归进入所有子目录，收集图片文件的shoot_address、l_shot_at、filename、category、fid、source。- 若只想整理某个手机备份目录，可传该目录的 FID 作为
--start-fid缩小范围（FID 用夸克 skill 的search --search-type dir或browse获取）。
第 2 步：聚类到目的地
python scripts/cluster.py --base <工作目录>
内置判定规则（顺序重要）：港澳台特别行政区 → 国内省级前缀（省·市）→ 海外国家关键词（国家·城市）→ 兜底「国内·其他」。海外已内置日本逐城市细分、东南亚（印尼/泰国/马来西亚）、韩国等，详见 references/pitfalls.md。
第 3 步：搜索并校验代表缩略图
python scripts/verify_thumbs.py \
--base <工作目录> \
--session-id "$SESSION_ID" \
--session-input "<用户原始提问>"
对每个目的地用 search --search-type album 检索照片，用「省 + 市」双重验证国内目的地、国家关键词验证海外目的地，排除「运城→大运城」这类跨地域误配。
第 4 步：下载并内嵌缩略图（解决防盗链 + 时效）
python scripts/embed_thumbs.py --base <工作目录>
用夸克自身 Referer 下载全部缩略图，PIL 转 400px 宽 JPEG，base64 内嵌，产出 thumbs_b64.json，让 HTML 单文件自包含、不依赖任何会过期/防盗链的夸克 URL。
第 5 步：生成报告
python scripts/gen_report.py --base <工作目录> --out <输出 HTML 路径>
产出结构：分地区足迹统计（地区卡片 + 城市明细 + 量级占比）→ 旅行洞察 → 国外足迹（海外 + 港澳台）→ 国内足迹（按七大地理分区）。
关键注意事项
--session-input逐字传用户原话，禁止改写；--session-id同对话复用。- 缩略图 URL 3 小时失效 + 防盗链：报告分享到外部域名（如 OA Pages）会挂图，必须跑第 4 步内嵌 base64。详见
references/pitfalls.md。 - 聚类易错点：国内省份要覆盖全 34 个省级行政区；「江西/安徽/天津/西藏/台湾」等常被遗漏，会导致目的地落到「其他」。
- 照片量级判定：报告内的「常驻地/高频往返/路过打卡」等定性基于「照片数量 × 年份跨度」，阈值见
scripts/gen_report.py的trip_class()。
资源说明
scripts/：五步流水线的可执行脚本 +common.py（自动定位夸克 skill 与 Node）。references/pitfalls.md：夸克缩略图防盗链/时效、聚类易错点、时间戳等已知坑的详细说明。
