Taobao Image Search

name: taobao-image-search
description: 使用淘宝进行以图搜同款、候选比对和加购物车操作。用户提供商品图片并要求“搜同款/找类似款/比价/加入购物车”时使用。优先执行本地脚本（run-taobao-task.js）完成全流程；当脚本失败或页面结构变化时回退 browser 工具手动执行。
install:
  - npm install playwright
  - npx playwright install chromium
---

# 淘宝图片搜索技能

## 执行策略

- 优先执行脚本：`run-taobao-task.js`。
- 脚本失败、登录超时或页面结构变化时，回退 `browser` 工具。
- 默认不下单、不支付；仅搜索与加购。

## 输入要求

- 必需：本地图片路径或会话中的图片。
- 可选：预算、偏好（品牌/颜色/尺码）、仅搜索或加购。

若缺少关键输入，先补充最少问题（例如“是否直接加购？”、“预算上限是多少？”）。

## 主流程（脚本优先）

### 1. 执行完整链路（含自动登录）

```bash
node run-taobao-task.js --image /absolute/path/to/image.png --headed
```

该脚本覆盖：

1. **自动登录校验**：若未登录，弹出窗口引导用户登录，成功后自动续行。
2. **图搜上传**：打开淘宝首页并上传图片。
3. **按钮定位**：点击弹窗内搜索按钮。
4. **选品采样**：采样候选商品并进入详情页。
5. **自动加购**：点击加入购物车并检测成功提示。

脚本参数约定：

- `--image, -i`：图片路径（默认 `test.png`）。
- `--headless` / `--headed`：本地调试运行模式（默认 `--headed`）。
- `--delay-ms`：为关键步骤追加等待时长（默认 `5000`，慢网可增大到 `8000-12000`）。
- `browser` 工具在 OpenClaw 运行时由技能流程调用，不由该本地脚本直接调用。

### 2. 读取验证结果

脚本运行后读取：

- `verification-artifacts/result.json`
- `verification-artifacts/run-log.txt`
- `verification-artifacts/*.png`（流程截图）

关键判定字段：

- `success`：流程是否成功执行。
- `loginCheck.isLoggedIn`：是否登录。
- `addToCart.success`：是否加购成功。

## 回退流程（browser 工具）

仅在脚本执行失败、页面结构变化、或需要人工交互排障时使用。

### 1. 打开淘宝并校验登录

- 打开 `https://www.taobao.com`。
- 校验昵称元素是否可见。
- 若未登录，提示用户先登录，再继续。

### 2. 上传图片并搜索

- 点击相机/搜同款入口打开上传弹窗。
- 上传图片。
- 点击弹窗内搜索按钮（优先 `#image-search-upload-button.upload-button.upload-button-active`）。

### 3. 选品与加购

- 分析候选商品并优先选择最相似商品。
- 进入详情页点击“加入购物车”。
- 若强制规格选择，先选默认规格再加购。

## 失败回退建议

- **登录超时**：重新运行 `node run-taobao-task.js --headed`。
- **上传失败**：重新打开图搜弹窗再上传。
- **搜索按钮定位失败**：优先使用弹窗按钮精确选择器，或在 browser 工具中手动点击。
- **加购失败**：检查规格选择、风控拦截或登录失效。

## 安全边界与隐私

- **会话持久化**：为实现自动化登录，本技能会将浏览器会话（Cookies 和 Storage State）保存至本地。
  - 路径：`verification-artifacts/taobao-storage-state.json` 与 `.pw-user-data-taobao/`。
  - **重要提示**：这些文件包含您的淘宝登录令牌，请务必将其视为**敏感凭据**，严禁上传或分享。
  - 若需清除登录态，请手动删除上述目录及文件。
- **操作受限**：仅操作用户明确指示的商品。
- **支付保护**：不执行“立即购买”“提交订单”“支付”动作。
- **环境建议**：建议在受信的个人机器或沙箱环境中运行。