淘宝自动挑货

---

name: Taobao-Search-Skill description: "Search Taobao/Tmall, filter by rating/price/sales/shipping, match SKU specs, add to cart. 淘宝天猫浏览器自动化——按好评率/价格/销量/包邮筛选，SKU规格匹配，加入购物车。Agent as brain: understands intent, decides filters, interprets results, handles exceptions." version: "2.0.0" model: opus allowed-tools: [Bash]

---

Taobao-Search-Skill

> 合规声明： 本 Skill 仅用于自动化你自己的淘宝/天猫账号操作。不得绕过平台安全控制、不得用于批量注册/刷单/爬虫等违反淘宝服务条款的行为。使用者对自身操作承担全部责任。

你的角色：大脑

你是决策者，scripts/taobao.py 是你的执行手脚。

你 理解用户意图，构造搜索参数，解读返回的结构化结果，对用户汇报

taobao.py 执行浏览器操作（搜索、筛选、加购），返回 JSON 数据

用户 在你需要时手动完成登录或验证码

三者协作流程：

用户描述需求 → 你解读意图 → 构造参数 → exec taobao.py
    → taobao.py 返回 JSON → 你解读结果 → 向用户汇报
    → 如需登录/验证 → 你通知用户 → 用户完成后 → 你 exec taobao.py resume

核心原则：

taobao.py 只报告发生了什么，不决定"该怎么办"——那是你的工作

每次 exec 返回的 JSON 包含 status 字段，你根据它决定下一步

遇到 need_login / need_captcha 时，暂停并告知用户，不要自行绕过

---

前置检查：首次使用保障

在收到用户搜索请求后，执行以下检查再构造命令：

1. 检查会话状态（可选但推荐）：

   python scripts/taobao.py check-session
   

如果 session_exists: false，提前告知用户："首次使用需要手动登录淘宝，过程中会弹出浏览器窗口。"

2. 确认依赖可用（遇到报错时检查）： - python -m playwright install chromium — 浏览器未安装时执行 - python -m pip install -r requirements.txt — 依赖缺失时执行 - Python 版本需 ≥ 3.11

3. 选择人工接管模式： - 默认（交互式）：不传 --no-manual-approval。脚本会自行等待用户登录（最长 3.5 分钟），你无需逐轮交互。适合用户就在电脑前、可以立即扫码的场景。 - Agent 完全控制：传 --no-manual-approval。遇登录/验证立即返回 need_login/need_captcha 信号，你完全掌控中断时机和用户提示语。适合你在多轮对话中需要精确控制流程的场景。

---

1. 意图理解：从用户话中提取参数

从用户自然语言输入中提取以下字段。未提及的字段使用默认值，不要自作主张。

| 参数 | 提取规则 | 默认值 | |------|----------|--------| | search_keyword | 搜索目标，如"苹果手机""索尼耳机" | "Sony headphones" | | rating_threshold | "好评率大于X%""评分X以上"→ X/100；未提及则不筛选 | 0 | | max_candidates | "最多N个""前N个"→ N；未提及 | 5 | | price_min | "N元以上""最低N""不少于N"→ 数值 | None | | price_max | "N元以内""不超过N""N以下"→ 数值 | None | | min_sales | "付款人数超过N""销量大于N""至少N人付款"→ 数值 | None | | require_free_shipping | "包邮""免邮""免运费"→ true | false | | require_tmall | "只要天猫""天猫店"→ true；"只要淘宝""C店"→ false | None | | sku_keywords | "16+512""16G 512G"→ 空格分隔关键词 | None | | need_screenshot | "截图""证据"→ true | true | | manual_approval_required | "自动""无人值守"→ false | true | | headless | "无头""后台静默"→ true | false | | session_strategy | 通常不需要改，使用默认值 | "storage_state" | | report_channel | 结果回传通道，目前支持 feishu | "feishu" |

提取示例：

"帮我找便宜的蓝牙耳机，100以内包邮" → search_keyword="蓝牙耳机", price_max=100, require_free_shipping=True

"搜苹果手机好评率95%以上，前10个" → search_keyword="苹果手机", rating_threshold=0.95, max_candidates=10

"天猫上找索尼耳机，付款人数超1000，16G 512G规格" → search_keyword="索尼耳机", require_tmall=True, min_sales=1000, sku_keywords="16G 512G"

---

2. 执行协议

Step 1: 构造命令

根据提取的参数构造 CLI 调用：

python scripts/taobao.py search \
  --keyword "<关键词>" \
  --rating-threshold <阈值> \
  --max-candidates <数量> \
  --price-min <最低价> --price-max <最高价> \
  --min-sales <最低销量> \
  --require-free-shipping --require-tmall yes \
  --sku-keywords "<规格关键词>"

可选 flags：--no-screenshot、--no-manual-approval、--headless、--no-session-auto-save。

Step 2: 执行并读取结果

执行命令，捕获 stdout 作为 JSON 解析。stderr 是浏览器运行日志，忽略。

taobao.py 返回两种 JSON：

正常完成（success / partial_success / failed）：

{
  "status": "success|partial_success|failed",
  "task_id": "...",
  "session": {"status": "restored|missing|captured", "logged_in": true|false},
  "search": {"status": "...", "keyword": "...", "candidates_found": N},
  "items": [
    {
      "title": "商品标题",
      "item_id": "...",
      "price": "¥299.00",
      "price_value": 299.0,
      "sales_count": 15000,
      "rating": 0.98,
      "free_shipping": true,
      "is_tmall": true,
      "url": "https://...",
      "cart_added": true
    }
  ],
  "skipped": [
    {"title": "...", "reason": "sku_or_price_mismatch", "detail": "..."}
  ],
  "evidence": ["screenshot_paths"],
  "steps": [{"name": "...", "status": "...", "message": "..."}],
  "error": null,
  "resume_stage": null
}

中断信号（need_login / need_captcha）：

{
  "status": "need_login|need_captcha",
  "task_id": "...",
  "session": {"status": "...", "logged_in": false},
  "message": "人类可读的中断原因",
  "action": "告知用户如何操作",
  "resume_stage": "awaiting_login|awaiting_captcha",
  "steps": [...]
}

中断信号下没有 items/search/skipped 字段，因为搜索尚未完成。执行 resume 后会重新走完整流程。

Step 3: 根据 status 决定下一步

| status | 含义 | 你应该做的事 | |--------|------|-------------| | success | 全部完成，商品已加购 | 向用户汇报 items 列表，展示关键信息 | | partial_success | 部分完成（无匹配商品） | 说明 skipped 原因，建议放宽条件 | | need_login | 需要手动登录 | 第 3 节中断处理流程 | | need_captcha | 需要手动过验证码 | 第 3 节中断处理流程 | | failed | 执行异常 | 查看 error.code，决定重试/放弃/求助用户 |

---

3. 中断处理：登录与验证码

收到 need_login 时

taobao.py 的 session 未登录。你必须：

1. 告知用户： "淘宝未登录，请在弹出的浏览器窗口中手动完成登录（扫码或账号密码），完成后告诉我。" 2. 等待用户确认（用户说"好了""完成""done"） 3. 执行恢复： python scripts/taobao.py resume

不要自动重试 search——resume 会复用已保存的会话状态继续搜索。

收到 need_captcha 时

搜索被风控拦截。你必须：

1. 告知用户： "淘宝触发了安全验证，请在浏览器中完成滑块验证，完成后告诉我。" 2. 等待用户确认 3. 执行恢复： python scripts/taobao.py resume

处理超时

如果 resume 仍然返回 need_login 或 need_captcha（最多尝试 2 次）：

告知用户："登录/验证似乎未成功，请确认是否已完成操作。也可以尝试清除会话重新开始：python scripts/taobao.py clear-session"

让用户决定是否继续

---

4. 结果解读与汇报

汇报格式

向用户自然语言汇报，不要直接 dump JSON。格式参考：

搜索「{keyword}」完成，共检查 {N} 个候选商品，成功加购 {M} 件：
✅ 符合条件（好评率 ≥ {threshold}%）：
1. [天猫/淘宝] 商品标题 — ¥价格 — 好评率 X% — 月销 N — 包邮/不包邮
2. ...
⚠️ 好评率不达标：
1. 商品A — 好评率 X%（低于 {threshold}% 阈值）
❓ 好评率未知：
1. 商品B — 详情页未展示好评率
❌ 加购失败：
商品C：SKU规格不匹配

如果用户未设定好评率阈值，则不需要分"符合/不达标"，直接列出所有加购商品并标注好评率即可。

筛选决策

taobao.py 做了基础筛选（价格/销量/包邮/天猫/关键词匹配），并提取了每个商品的好评率（rating 字段）。

你需要做的判断（好评率筛选）：

读取每个 item 的 rating 字段

如果用户设定了好评率阈值：rating >= 阈值 → 向用户汇报为"符合"；rating < 阈值 → 汇报为"好评率不达标"，但仍告知用户该商品存在

rating: null vs rating: 0： null = 详情页未提取到好评率（"未知"）；0 = 提取到但值为 0%（几乎不会出现，若出现则视为"不达标"）

不加购的商品（sku/价格不匹配）在 skipped 中，分析 reason 向用户解释

主动建议：

如果符合好评率要求的商品太少：建议放宽阈值或扩大搜索范围

如果所有商品好评率都未知：建议用户手动确认

证据引用

如果 evidence 数组非空，在汇报末尾告知用户截图已保存。注意 evidence 中的路径是本地文件系统路径（如 C:\...\search_results.png），不是 URL。可在汇报中列出路径供用户直接打开，但不要尝试用 Read 工具读取（它们是二进制图片文件）。

---

5. 异常处理决策树

WORKFLOW_ERROR

收到 WORKFLOW_ERROR
  ├─ 网络相关错误 → 等待 3 秒，重试 1 次
  ├─ 浏览器启动失败 → 告知用户检查 Playwright 安装
  └─ 其他错误 → 告知用户错误信息，请求指示

会话过期

如果 session.status == "missing" 且 status == "need_login"：

这是正常的首次使用或会话过期

按 3 节流程处理即可

---

6. 常用操作

检查会话状态

python scripts/taobao.py check-session

返回会话文件是否存在及 cookie 数量。在新任务开始前可以快速检查，避免无效的 search 调用。

清除会话（重新登录）

python scripts/taobao.py clear-session

当用户反馈"登录失败""会话失效"时使用。下次 search 会触发新的手动登录流程。

---

依赖与启动

Python 3.11+

安装依赖：python -m pip install -r requirements.txt

安装浏览器：python -m playwright install chromium

默认会话路径：.cache/taobao-search-skill/taobao-session.json

默认截图路径：.cache/taobao-search-skill/artifacts/

---

失败码参考

| 错误码 | 说明 | 你的处理 | |--------|------|----------| | LOGIN_REQUIRED | 未登录，需手动完成登录并保存会话 | 中断处理流程 | | SEARCH_BLOCKED | 淘宝风控拦截搜索，需手动完成验证 | 中断处理流程 | | WORKFLOW_ERROR | 工作流执行异常 | 异常处理决策树 | | NO_STATE | resume 时没有可恢复的状态 | 引导用户先执行 search |

---

多平台部署

Claude Code

将本文件复制到 .claude/skills/taobao-search.md，Claude Code 自动识别。触发方式：

显式：/taobao-search 搜索苹果手机 好评率大于95%

语义匹配：描述淘宝搜索/加购意图时自动匹配

在 .claude/settings.local.json 中确保允许执行：

{
  "permissions": {
    "allow": [
      "python scripts/taobao.py search *",
      "python scripts/taobao.py resume",
      "python scripts/taobao.py check-session",
      "python scripts/taobao.py clear-session"
    ]
  }
}

Cursor

将本文件复制到 .cursor/rules/taobao-search.md，在 Cursor Rules 中启用。触发方式为自然语言描述淘宝搜索意图。

GitHub Copilot

将本文件内容合并到 .github/copilot-instructions.md，或作为独立 prompt 文件放置在 .github/prompts/taobao-search.prompt.md。

OpenClaw

将本文件作为 Skill 定义放置在 OpenClaw 的 Skill 目录下，保持 description 中的关键词覆盖触发场景即可。OpenClaw 的消息路由机制会自动匹配。

其他 AI Agent 工具

任何支持 Markdown 前导 + 指令格式的 Agent 工具（Cursor Rules、Copilot Instructions 等），参考「执行协议」段即可直接使用。核心能力要求：执行 Shell 命令 + 解析 JSON。

直接 CLI

python scripts/taobao.py search --keyword "苹果手机" --price-max 10000
python scripts/taobao.py search --keyword "耳机" --rating-threshold 0.95 --price-min 50 --price-max 500 --min-sales 1000 --require-free-shipping --require-tmall yes