淘宝搜同款 TOP5 批量图片搜索

用途概述

在淘宝首页通过"搜同款"上传用户提供的图片，搜索相同商品，按"顶行从左到右、逐行下移"的顺序取 TOP5 商品主图，下载保存到以原图片名命名的子目录中，文件名格式 原图名-01.jpg ~ 原图名-05.jpg。支持一次批量处理多张图片。

使用场景

• 用户提供图片文件夹路径，要求批量搜索同款商品
• 电商选品、找同款货源、比价场景
• 触发词："淘宝搜同款"、"找同款"、"搜同款"、"TOP5 主图"、"批量图片搜索"

浏览器操作统一约定（强制，最高优先级）

本技能的所有浏览器操作必须且只能通过 agent-browser 执行。这是本技能唯一允许的浏览器操作方式。

• 禁止使用 Playwright、Selenium、puppeteer 等其他任何浏览器自动化方式打开或操作浏览器
• 即使当前电脑/会话中已安装、已连接 Playwright 等其他浏览器技能或工具，本技能执行期间也一律禁用、不得调用
• 执行本技能时，不要加载/触发 Playwright 相关技能；若环境中存在自动选择浏览器工具的逻辑，必须显式排除其他工具，只用 agent-browser

原因：多个任务并发运行时，若不同任务用不同方式（Playwright / agent-browser / 其他）操作浏览器，会互相抢占 CDP 端口、抢页面控制权，产生干扰，导致各种奇怪问题。统一到 agent-browser 一个工具，行为可预期、互不干扰。

统一操作方式（连接已启动的系统 Chrome；实际调用方式与故障规避见 references/selectors.md 的"agent-browser 实际调用方式"节）：

agent-browser connect <debug_port>          # 连接外部 Chrome（CDP）；沙箱下静默失败时改用下方 --cdp 前缀
agent-browser --cdp <debug_port> eval "<JS>"           # 执行 JS（读 DOM、取数据、移除弹窗）
agent-browser --cdp <debug_port> click "<selector>"    # 真实鼠标点击（JS click() 可能不触发跳转）
agent-browser --cdp <debug_port> upload "<selector>" "<file>"  # 上传文件
agent-browser --cdp <debug_port> eval "location.href"  # 获取当前页面 URL

• 页面导航、数据提取、点击、上传、关页签等一切浏览器交互，一律用上述 agent-browser 命令
• 绝不使用 playwright / python-playwright / selenium / 其他库的浏览器接口
• 页签关闭只允许两种方式：CDP HTTP /json/close/<targetId>（推荐）或 agent-browser eval "window.close()"（备选，偶发失效），均只关闭当前搜索结果页签（见第六步第 9 点），禁止使用任何"关闭所有页签"类命令

环境适配（跨电脑零配置）

本技能不依赖任何预置路径，在任何电脑上均可运行。开始执行前，先运行环境探测脚本获取本机参数：

python "<技能目录>/scripts/env_setup.py"

脚本输出 JSON：chrome_path（系统 Chrome 路径）、profile_dir（配置目录，基于当前用户主目录自动生成）、debug_port（空闲调试端口）。若探测不到 Chrome，询问用户手动指定 Chrome 路径。

执行流程

第一步：询问图片路径

告知用户：请提供需要搜索同款的图片文件夹路径。

第二步：创建子目录

遍历用户指定目录下的所有图片文件（jpg/png/jpeg/webp/bmp），为每张图片创建同名子目录（去掉扩展名）。

第三步：启动系统 Chrome（可见模式）

使用 env_setup.py 返回的 chrome_path，以可见模式启动（登录需人工操作，绝不可无头）：

<chrome_path> --start-maximized --remote-debugging-port=<debug_port> --user-data-dir="<profile_dir>" https://www.taobao.com

• 固定使用 --user-data-dir="<profile_dir>"：cookie 持久保存在此，后续运行自动复用登录态
• 启动方式必须脱离 shell 会话（2026-08-19 实测）：若把 Chrome 作为后台 Bash 任务的子进程启动，任务被回收时 Chrome 会一起退出（表现为调试端口突然失联）。Windows 上用 PowerShell Start-Process 启动：
  powershell Start-Process -FilePath "<chrome_path>" -ArgumentList '--start-maximized',"--remote-debugging-port=<debug_port>","--user-data-dir=<profile_dir>",'https://www.taobao.com'
• --start-maximized 让窗口最大化打开（便于人工观察，也保证结果页布局与正常桌面一致）
• 通过 CDP 连接：curl http://127.0.0.1:<debug_port>/json/version 获取 webSocketDebuggerUrl，必须用 127.0.0.1 而非 localhost（Windows 上 localhost 可能解析到 IPv6 导致连接失败）
• 连接后所有操作统一走 agent-browser（见上方"浏览器操作统一约定"；调用方式见 references/selectors.md 的"agent-browser 调用方式"节，优先用原生二进制 + --cdp <port> 前缀）

第四步：检查登录状态

打开淘宝首页后，检查页面右上角是否显示用户名/头像：
- 已登录 → 直接继续
- 未登录 → 暂停并提醒用户人工登录（扫码/账号密码），等待用户确认"已登录"后再继续。登录态自动存入 <profile_dir>，下次运行自动复用

cookie 存储位置（新版 Chrome）：登录态文件在 <profile_dir>\Default\Network\Cookies（旧版 Chrome 是 Default\Cookies）。判断是否已有登录态，检查 Default\Network\Cookies 文件是否存在即可。

登录态迁移（可选）：如果本机存在旧版技能/旧流程遗留的淘宝配置目录（里面已有登录态），可在启动 Chrome 前将旧目录的 Local State 和 Default\Network\Cookies（含 Cookies-journal）复制到新 <profile_dir>，避免重新登录。复制前先确认没有 Chrome 进程正在使用旧目录（否则文件被锁定）。

第五步：移除弹窗广告

每次打开/返回淘宝首页后，先检查并移除弹窗遮罩（如 #J_TBTC_POP_home / #J_TBPC_POP_home），否则"找同款"按钮被遮挡无法点击。详细选择器见 references/selectors.md。

第六步：循环处理每张图片

对每张图片依次执行（所有浏览器操作均用 agent-browser 命令）：

1. 打开搜同款面板：agent-browser click ".image-search-icon-wrapper"（选择器见 references/selectors.md）
2. 上传图片：agent-browser upload "#image-search-custom-file-input" "<图片路径>"；图片大于 1MB 时先用 PIL 压缩（长边 1000px、JPEG quality 88）再上传，避免上传超时
3. 点击搜索：agent-browser click "#image-search-upload-button"（真实鼠标事件，JS 直接 click() 可能不触发跳转；必要时点击 1~2 次）
4. 等待结果加载：agent-browser eval 轮询等待结果卡片出现后再取数据
5. 切换"销量"排序（默认综合，必须先切换）：结果页默认是"综合"排序，必须先切到"销量"再取图，否则 TOP5 不是按销量排。用 agent-browser eval 在结果页找到文本为"销量"的排序 tab 并真实点击（JS 见 references/selectors.md 的"销量排序"节），点击后等待 1~2 秒让页面重排（重新请求/重排后图片会回到未加载状态）。点击后建议验证当前激活的排序 tab 是否变为"销量"：若返回 NO_SALES_TAB（页面没有销量排序入口）或验证未切换成功，在汇总报告中注明该图仍是"综合"顺序，继续下载不中断
6. 按顺序取 TOP5：先滚动页面触发懒加载（scrollTo 300→800→1500→回顶部；切换排序后图片会重新加载，必须重新滚动，且滚动要够深、等待够久，参考 references/selectors.md），再用 agent-browser eval 按 DOM 顺序（= 销量从高到低、顶行从左到右、逐行下移）取前 5 个商品卡片链接（过滤 href 含 item.htm），用 img[class*=mainPic] 提取主图 URL（过滤占位图 tps- 和装饰图标 atmosphere；不要用 [class*=mainPic]，会匹配到外层 div）
7. MD5 去重：若前 5 张存在重复主图，向后多取候选（如 TOP8）再筛选出 5 张唯一图
8. 下载保存：用 curl 带 UA + Referer 下载，保存为 原图名-01.jpg ~ 原图名-05.jpg 到对应子目录
9. 关闭搜索结果页签：保存成功后只关闭当前搜索结果页签，然后回到最初打开的淘宝主页页签处理下一张。注意：不关闭淘宝主页页签，也不关闭其他任何页签，绝不用 close --all 等"关闭所有页签"命令。原因：防止批量搜索时搜索结果页签堆积导致浏览器崩溃；淘宝主页页签始终保留，下一张图直接从该主页继续"搜同款"操作
   - 推荐方式（2026-08-19 实测，最可靠）：CDP HTTP 关闭。window.close() 在淘宝结果页上偶发被页面脚本拦截失效，CDP 方式必然生效：
   bash # 1) 列出所有 page target：curl http://127.0.0.1:<port>/json/list # 2) 找出 url 不含 www.taobao.com 的 page target（即搜索结果页签） # 3) 关闭之：curl http://127.0.0.1:<port>/json/close/<targetId> # 4) 每次调用 /json/list 前先重新拉取最新列表，不要用缓存文件
   - 备选：agent-browser eval "window.close()"（若返回 null 且后续 title 仍为空说明没关掉，改用 CDP 方式）

第七步：汇总报告

全部完成后，输出每个目录的保存情况（文件数、文件名、大小），并注明任何不足 5 张的异常。

故障处理

Resources

• scripts/env_setup.py：跨平台环境探测（Chrome 路径 / 配置目录 / 空闲端口），零依赖标准库
• references/selectors.md：淘宝搜同款完整 DOM 选择器与关键技术细节