淘宝自动挑货

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

• 参数提取

从用户自然语言输入中提取以下字段，缺失字段使用默认值： 参数 | 提取规则 | 默认值 ---|---|--- search_keyword | 搜索目标，如“苹果手机”“索尼耳机” | “索尼耳机” rating_threshold | 用户明确要求时 → X/100；未提及则不筛选 | 0 max_candidates | 用户指定的“最多 N 个”，未提及则默认 | 5 price_min | “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”→ 空格分隔关键词匹配SKU选项 | None need_screenshot | 提到“截图”“证据”则为 true | true manual_approval_required | 提到“自动”“无人值守”则为 false | true headless | 提到“无头”“后台静默”则为 true | false

• 构造任务并执行

方式 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 、--price-min、--price-max、--min-sales、--require-free-shipping、--require-tmall yes/no、--sku-keywords "16G 512G"、--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)

• 结果解读

执行完毕后，脚本输出一个 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 列表（商品名、价格、好评率），以及整体状态。

• 中断与人工接管

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

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

Skill 规格说明 目标 编排一个端到端的淘宝 UI 自动化流程：

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

支持的输入

• 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。

失败码

• LOGIN_REQUIRED：未登录，需手动完成首次登录并保存会话
• SEARCH_BLOCKED：淘宝风控拦截搜索，需手动完成验证
• WORKFLOW_ERROR：工作流执行异常

依赖与启动约定

• 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 。
• 如果要重建会话，只需删除会话文件，或在人工登录后由脚本自动覆盖保存。

多平台部署 Claude Code 将本文件复制到 .claude/skills/taobao-search.md