taobao-search-skill（淘宝搜索技巧）

Taobao-Search-Skill

AI Agent 执行指令

当 AI Agent（Claude Code、Cursor、Copilot 等）加载本 Skill 时，按以下步骤执行。

1. 参数提取

从用户自然语言输入中提取以下字段，缺失字段使用默认值：

2. 构造任务并执行

方式 A — 使用 CLI（推荐）：

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

可选参数：--task-file <task.json>（从 JSON 文件读取完整配置）、--price-min、--price-max、--min-sales、--require-free-shipping、--require-tmall yes/no、--sku-keywords "16G 512G"（指定SKU规格关键词）、--report-channel feishu（结果回传通道）、--no-screenshot、--no-manual-approval、--no-session-auto-save、--session-state-path、--headless。

方式 B — 编程调用：

from scripts.workflow import UiAutomationWorkflow
from scripts.browser_adapter import BrowserAdapter
from scripts.report_channel import FeishuClient

payload = {
    "search_keyword": "...",
    "rating_threshold": 0.95,
    "max_candidates": 5,
    "price_min": 50.0,
    "price_max": 500.0,
    "min_sales": 100,
    "require_free_shipping": True,
    "require_tmall": True,
    "need_screenshot": True,
    "manual_approval_required": True,
}
client = FeishuClient()
browser = BrowserAdapter()
workflow = UiAutomationWorkflow(client, browser)
result = workflow.run(payload)

3. 结果解读

执行完毕后，脚本输出一个 JSON，关键字段：

result.status          → "success" / "partial_success" / "failed"
result.login_status    → 登录态 ("success" / "waiting_manual" / "failed")
result.session_status  → 会话态 ("restored" / "captured" / "missing")
result.search_status   → 搜索状态
result.filter_status   → 筛选状态
result.cart_status     → 加购状态 ("success" / "empty" / "error")
result.matched_items   → 符合条件并加购成功的商品列表
  └─ title, item_id, price, price_value, sales_count, rating, free_shipping, is_tmall, url, cart_added
result.evidence        → 截图路径列表
result.steps           → 每步执行记录 [{name, status, message, details}]
result.error.code      → 错误码（失败时）

向用户汇报时，用自然语言总结 matched_items 列表（商品名、价格、好评率），以及整体状态。

4. 中断与人工接管

以下场景必须暂停并提示用户在浏览器中手动操作：

• 登录：提示"请在弹出的浏览器窗口中手动完成淘宝登录"，每 30 秒检测一次登录态，最长等待约 3.5 分钟；登录成功后自动保存会话
• 验证码/风控：自动尝试滑块求解（ddddocr + OpenCV 双引擎），失败后每 30 秒检测一次验证状态，最长等待约 3.5 分钟，期间不刷新页面以免打断用户操作
• 会话失效：提示用户重新登录

Skill 规格说明

目标

编排一个端到端的淘宝 UI 自动化流程：

1. 接收任务（飞书 / Slack / CLI / AI Agent 均可）。
2. 优先恢复已持久化的淘宝会话。
3. 在受控浏览器会话中打开淘宝。
4. 当会话不存在或失效时，走一次人工登录。
5. 登录成功后自动保存新的会话状态。
6. 搜索目标关键词。
7. 在搜索结果页按价格、销量、包邮、天猫等多维度筛选候选商品。
8. 逐商品访问详情页：提取好评率、匹配 SKU 规格关键词并校验实际价格。
9. 将符合条件的商品加入购物车。
10. 将结果回传到指定通道。

支持的输入

• task_id：任务唯一标识。
• feishu_message_id：消息通道的消息标识（飞书消息 ID 等）。
• report_channel：结果回传通道标识，默认 "feishu"。
• search_keyword：搜索关键词。
• rating_threshold：最低好评率阈值，0 表示不筛选，默认 0。
• max_candidates：最多检查的候选商品数量。
• need_screenshot：是否捕获证据截图。
• manual_approval_required：登录或校验时是否暂停等待人工接管。
• session_state_path：会话持久化文件路径，默认 .cache/taobao-search-skill/taobao-session.json。
• session_strategy：会话恢复策略，默认 storage_state。
• session_auto_save：人工登录成功后是否自动保存会话，默认 true。
• price_min：最低价格过滤（元），未设置则不限制。
• price_max：最高价格过滤（元），未设置则不限制。
• min_sales：最低付款人数过滤，未设置则不限制。
• require_free_shipping：是否只要包邮商品，默认 false。
• require_tmall：true 只要天猫、false 只要淘宝店、None 不限，默认 None。
• sku_keywords：规格关键词，空格分隔（如 "16G 512G"），用于匹配商品详情页的 SKU 选项。
• headless：是否以无头模式运行浏览器，默认 false。

期望输出

返回一个结构化结果对象，包含：

• task_id
• status (success / partial_success / failed)
• login_status
• session_status
• search_status
• filter_status
• cart_status
• matched_items — 商品列表，每项含 title、item_id、price、rating、url、cart_added
• evidence — 截图路径列表
• steps — 每步的执行记录（name、status、message）
• error — 错误码与详情

执行策略

• 优先使用确定性的浏览器操作，而非自由发挥式推理。
• 对短暂的导航或渲染失败使用重试。
• 所有 DOM 选择器集中管理在 scripts/taobao_selectors.py，淘宝改版时只需更新该文件，无需修改 browser_adapter.py。
• 优先恢复缓存会话，只有在会话不存在或失效时才进入人工登录。
• 每次进入淘宝后，必须先确认当前登录态；未登录时不得继续搜索、筛选或加购。
• 首次登录或会话失效时，提醒用户在浏览器中手动完成登录，然后立即提取存储状态并保存。
• 当登录、验证码或安全校验出现时，立即暂停并请求人工接管。
• 加购时如遇到 SKU 规格选择弹窗：若指定了 sku_keywords，按空格分隔的关键词逐一匹配选项文本，已选中的跳过以防止取消选中，任一关键词匹配失败则跳过该商品；若未指定关键词，则选择第一个可见选项作为默认规格。
• 不尝试绕过平台安全控制。

消息通道适配

• scripts/report_channel.py 是消息通道抽象层：ReportChannel 基类定义 send_report() / normalize_task_payload() 接口，FeishuClient 是飞书实现。接入新通道（Slack、钉钉、企业微信等）只需新增子类并注册到 CHANNEL_REGISTRY。

失败码

依赖与启动约定

• Python 3.11 或更高版本。
• 安装依赖：python -m pip install -r requirements.txt。
• 安装浏览器：python -m playwright install chromium。
• 默认以 Chromium 启动，使用 Playwright 的 storage_state 恢复淘宝会话。
• 默认会话文件路径：.cache/taobao-search-skill/taobao-session.json。
• 推荐的启动方式：python scripts/run_workflow.py --task-file <task.json>。

如果要重建会话，只需删除会话文件，或在人工登录后由脚本自动覆盖保存。

多平台部署

Claude Code

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

• 显式：/taobao-search 搜索苹果手机 好评率大于95%
• 语义匹配：描述淘宝搜索/加购意图时自动匹配

OpenClaw

将本文件作为 Skill 定义加载，由 OpenClaw 的消息路由机制匹配任务。保持 description 中的关键词覆盖触发场景即可。

其他 AI Agent 工具

任何支持 Markdown 前导 + 指令格式的 Agent 工具（Cursor Rules、Copilot Instructions 等），参考「AI Agent 执行指令」段即可直接使用。

直接 CLI

python scripts/run_workflow.py --search-keyword "苹果手机" --rating-threshold 0.95