Imported from newbietan/Taobao-Search-Skill (
SKILL.md). Install upstream withnpx skills add newbietan/Taobao-Search-Skill. Copyright stays with the author.
Taobao-Search-Skill v4
合规声明： 本 Skill 仅用于自动化你自己的淘宝/天猫账号操作。不得绕过平台安全控制、不得用于批量注册/刷单/爬虫等违反淘宝服务条款的行为。使用者对自身操作承担全部责任。
核心架构：Session 模式
浏览器只启动一次，通过 stdin/stdout JSON 协议接收命令。命令间共享同一浏览器实例，无需反复启动。
用户需求 → 你(理解意图)
↓
Bash: 启动 session 进程（浏览器打开一次）
↓
Bash: stdin 发 {"cmd":"search","keyword":"MacBook Air M4"}
← stdout 收 {"data":{"items":[...8个商品...]}}
↓
你看 JSON 数据 → 决定"打开第3个"
↓
Bash: stdin 发 {"cmd":"open","index":2}
← stdout 收 {"data":{"sku_groups":[{"label":"芯片","values":[...]},...]}}
↓
你看 JSON 数据 → 决定"选M4+16G+512G"
↓
Bash: stdin 发 {"cmd":"select-sku","selections":[{"label":"芯片","value":"M4"},{"label":"内存","value":"16G"},{"label":"硬盘","value":"512G"}]}
← stdout 收 {"data":{"final_price":5999,"all_selected":true}}
↓
5999 < 6000 → 加购
↓
Bash: stdin 发 {"cmd":"cart-add"}
← stdout 收 {"data":{"cart_added":true,"confirmed":true}}
↓
汇报用户
你（AI Agent）是决策者： 解析用户意图、分析搜索结果、选择商品和 SKU、确认价格、判断风险。 session 进程是执行者： 操控浏览器、提取数据、返回结构化 JSON。不做决策。
一、启动会话
python scripts/taobao.py session --task-id <自定义ID>首次启动会自动打开浏览器并检查登录状态。如果未登录，会等待用户手动完成登录（弹出浏览器窗口）。
启动后，进程进入等待状态，从 stdin 逐行读取 JSON 命令，每条命令处理完后将 JSON 结果写到 stdout。
退出方式： 发送 {"cmd": "quit"} 或关闭 stdin（进程自动退出，浏览器关闭）。
二、命令参考
2.1 search — 搜索商品
{"cmd": "search", "keyword": "MacBook Air M4 16G 512G", "price_max": 6000, "require_tmall": true}| 参数 | 类型 | 说明 |
|---|---|---|
| keyword | string | 必填，搜索关键词 |
| price_min | float | 最低价格 |
| price_max | float | 最高价格 |
| min_sales | int | 最低销量 |
| require_free_shipping | bool | 仅包邮 |
| require_tmall | bool | true=仅天猫，false=仅淘宝 |
| max_candidates | int | 最多返回商品数，默认 20 |
返回 data：
{
"keyword": "MacBook Air M4 16G 512G",
"items": [
{
"index": 0,
"title": "Apple MacBook Air M4 16G+512G 13寸...",
"url": "https://item.taobao.com/...",
"price": "¥5499.00",
"price_value": 5499.0,
"sales_count": 2300,
"rating": 0.98,
"is_tmall": true,
"free_shipping": true
}
],
"items_count": 8
}2.2 open — 打开商品详情
{"cmd": "open", "index": 2}| 参数 | 类型 | 说明 |
|---|---|---|
| index | int | 必填，商品在搜索结果中的索引（从 0 开始） |
返回 data：
{
"item": {"title": "...", "price": 5499.0, "sales_count": 2300, "rating": 0.98, ...},
"sku_groups": [
{
"label": "芯片",
"values": [
{"text": "M4", "disabled": false, "selected": false},
{"text": "M3", "disabled": false, "selected": false}
]
},
{
"label": "内存",
"values": [
{"text": "16G", "disabled": false, "selected": false},
{"text": "24G", "disabled": false, "selected": false}
]
}
],
"detail_price": 5499.0
}2.3 select-sku — 选择 SKU 规格
{"cmd": "select-sku", "selections": [
{"label": "芯片", "value": "M4"},
{"label": "内存", "value": "16G"},
{"label": "硬盘", "value": "512G"}
]}也支持单选：
{"cmd": "select-sku", "selections": {"label": "芯片", "value": "M4"}}| 参数 | 类型 | 说明 |
|---|---|---|
| selections | object 或 array | 必填，每个选择包含 label（SKU 组名）和 value（选项值） |
返回 data：
{
"all_selected": true,
"selections": [
{"label": "芯片", "value": "M4", "ok": true},
{"label": "内存", "value": "16G", "ok": true},
{"label": "硬盘", "value": "512G", "ok": true}
],
"final_price": 5999.0,
"sku_groups": [...更新后的SKU结构...]
}all_selected: false 表示部分选择失败，检查 selections 中 ok: false 的项。
2.4 cart-add — 加入购物车
{"cmd": "cart-add"}返回 data：
{
"cart_added": true,
"confirmed": true,
"item_index": 2
}confirmed 表示是否看到了"已加入购物车"的确认弹窗。
2.5 cart-view — 查看购物车
{"cmd": "cart-view"}返回 data：
{
"cart_item_count": 3,
"items": [...本次会话中处理过的商品列表...]
}2.6 dom — 提取页面 DOM 结构
{"cmd": "dom", "url": "https://..."}url 可选，不提供则使用当前页面。返回可见区域的按钮、链接、输入框、SKU 选项等元素，包含坐标和语义角色。
2.7 screenshot — 截取当前页面
{"cmd": "screenshot"}返回当前视口截图路径和页面文本摘要。
2.8 quit — 退出会话
{"cmd": "quit"}关闭浏览器，退出进程。
三、响应格式
所有命令返回统一 JSON 结构：
{
"status": "success", // "success" 或 "error"
"task_id": "taobao-abc123",
"screenshot": ".cache/.../xxx.png", // 截图文件路径（可用 Read 工具查看）
"page_text_summary": "...", // 页面文本前 500 字符
"data": { ... } // 命令特定的返回数据
}错误时：
{
"status": "error",
"task_id": "taobao-abc123",
"error": {"message": "No search results. Run 'search' first."}
}四、决策框架
4.1 数据驱动优先
结构化 JSON 数据是你决策的主要依据，大多数情况下不需要看截图：
| 决策 | 数据来源 | 需要截图？ |
|---|---|---|
| 选择哪个商品 | items[].title/price/rating/is_tmall |
❌ |
| SKU 是否可选 | sku_groups[].values[].disabled |
❌ |
| 价格是否在预算 | final_price |
❌ |
| 加购是否成功 | cart_added / confirmed |
❌ |
| 标题是否含风险词 | item.title（正则匹配） |
❌ |
4.2 需要看截图的场景
| 场景 | 原因 |
|---|---|
| 弹窗/活动遮挡 | JSON 无法反映页面视觉遮挡 |
| 验证码/滑块 | 需要视觉确认验证码类型 |
| 加购后确认 | 确认弹窗可能被遗漏 |
| 异常页面 | 页面空白/加载失败/布局异常 |
| 调试失败原因 | 元素找不到时排查页面状态 |
看截图时使用 Read 工具查看 screenshot 字段返回的 PNG 路径。
4.3 风险识别
在汇报用户前，用正则检查以下风险信号（基于 JSON 数据，不需要截图）：
标题含 "官换""翻新""后封""99新""二手""展示机" → 警告用户
价格显著低于市场价（>30%） → 警告用户
is_tmall=false 且用户要求正品 → 提示风险
好评率 < 90% → 提示风险
五、SKU 选择策略
淘宝 SKU 通常是多级依赖的：选颜色→选项更新→选芯片→选项更新→选内存→价格变化。
策略 A：批量选择（推荐）
一次性发送所有选择，脚本内部依次执行：
{"cmd": "select-sku", "selections": [
{"label": "芯片", "value": "M4"},
{"label": "内存", "value": "16G"},
{"label": "硬盘", "value": "512G"}
]}适用于：你对 SKU 结构已经清楚（从 open 返回的 sku_groups 中获取）。
策略 B：逐个选择 + 确认
先选最关键的规格，看价格变化后再决定下一步：
1. select-sku {"label":"芯片","value":"M4"} → 看 final_price
2. 如果价格合理 → select-sku {"label":"内存","value":"16G"} → 看 final_price
3. 继续...
适用于：价格随 SKU 变化大、需要逐步确认预算。
选择技巧
label用 SKU 组的标题关键词（"颜色""存储""版本""芯片""内存""硬盘""尺寸"）value用选项文字的关键部分（"512G" "黑色" "M4" "16G"）- 如果
ok: false，尝试用更短的关键词重试 sku_groups中disabled: true的选项不可选（缺货）
六、完整工作流示例
示例：搜索 MacBook Air M4
用户："帮我找6000以下MacBook Air M4 16+512"
你的操作序列：
1. 启动会话
python scripts/taobao.py session --task-id macbook-task
2. 搜索
→ {"cmd":"search","keyword":"MacBook Air M4 16G 512G","price_max":6000}
← items: 8个候选商品
判断：第0个(¥5499,天猫,好评98%)和第2个(¥5899,天猫,好评96%)看起来靠谱
3. 打开第0个
→ {"cmd":"open","index":0}
← sku_groups: 芯片(M4/M3), 内存(16G/24G), 硬盘(256G/512G/1T)
判断：有M4+16G+512G可选
4. 选择规格
→ {"cmd":"select-sku","selections":[{"label":"芯片","value":"M4"},{"label":"内存","value":"16G"},{"label":"硬盘","value":"512G"}]}
← final_price: 5999, all_selected: true
判断：5999 < 6000，符合预算
5. 加购
→ {"cmd":"cart-add"}
← cart_added: true, confirmed: true
6. 查看购物车
→ {"cmd":"cart-view"}
← cart_item_count: 1
7. 退出
→ {"cmd":"quit"}
汇报用户：
搜索「MacBook Air M4 16G 512G」完成：
✅ 已加购：MacBook Air M4 16G+512G 13寸 — ¥5,999.00 — 好评率 98% — 天猫 — 包邮
请前往购物车确认。
示例：处理异常
→ {"cmd":"open","index":3}
← status: error, "Item has no URL"
判断：跳过这个商品，试下一个
→ {"cmd":"open","index":4}
← sku_groups: [{label:"颜色", values:[{text:"黑色",disabled:true}]}]
判断：想要的颜色缺货，跳过
→ {"cmd":"select-sku","selections":{"label":"颜色","value":"白色"}}
← all_selected: false, selections: [{ok: false}]
判断：选择失败，可能是关键词不匹配。截图排查：
→ {"cmd":"screenshot"}
← screenshot: ".cache/.../xxx.png"
Read 截图 → 看到选项文字是"象牙白"不是"白色"
→ {"cmd":"select-sku","selections":{"label":"颜色","value":"象牙白"}}
← all_selected: true, final_price: 3299
七、异常处理
登录失效
搜索或其他命令返回页面内容异常（空结果、被重定向到登录页）时：
# 检查会话状态
python scripts/taobao.py check-session
# 如果 session 进程还在运行，发送 quit 重启
# 重新启动 session，首次启动会自动检测登录
python scripts/taobao.py session --task-id <ID>验证码
命令返回的 screenshot 中出现滑块/验证码时：
- 告知用户："淘宝触发了安全验证，请在浏览器中完成验证，完成后告诉我。"
- 等待用户确认
- 重新发送刚才的命令
元素找不到
cart-add 返回 error: "Add-to-cart button not found" 时：
- 发送
{"cmd":"screenshot"}查看页面状态 - 可能需要滚动页面找到按钮——但当前 session 模式暂不支持滚动操作
- 尝试重新
open该商品再cart-add
八、依赖与环境
pip install -r requirements.txt
python -m playwright install chromium- Python 3.11+
- 默认会话路径：
.cache/taobao-search-skill/taobao-session.json - 截图目录：
.cache/taobao-search-skill/artifacts/