shopping-browser-automation

购物浏览器自动化技能

此技能基于 Playwright MCP 工具，为电子商务网站提供自动化功能。

核心概念

在购物网站自动化中，我们区分两种操作类型：

1. 技能：多个工具调用的有意义组合，封装为独立的 Python 脚本
2. 基础工具：utils.py 中的单个函数调用，用于执行原子操作。

---

I. 技能

1. 简单搜索 - 输入并提交

文件：simple_search.py

使用场景：

• 需要使用主搜索栏搜索商品
• 希望输入搜索词并自动按 Enter 键提交

前置条件：

• 首先使用 navigate() 导航到网站首页
• 获取搜索输入框的 ref 值

用法：

# Usage:
#   python simple_search.py <search_term> <search_input_ref>
# Example:
python simple_search.py "gingerbread" e35

---

2. 高级搜索 - 按商品名称和价格范围搜索

文件：advanced_search_by_name.py

使用场景：

• 已位于高级搜索页面
• 需要填写商品名称和价格范围进行搜索

前置条件：

• 首先使用 navigate() 导航到网站首页
• 然后使用 click() 点击“Advanced Search”链接
• 获取表单字段的 ref 值

典型任务示例：

• 搜索名称包含“Ginger”、价格在 $50.00 到 $100.00 之间的商品
• 搜索名称包含“cookie”、价格在 $20.00 到 $40.00 之间的商品

用法：

# Usage:
#   python advanced_search_by_name.py <product_name> <price_from> <price_to> <name_ref> <price_from_ref> <price_to_ref> <search_btn_ref>
# Example:
python advanced_search_by_name.py "Ginger" 50.00 100.00 e91 e110 e114 e118

---

3. 高级搜索 - 按描述和价格范围搜索

文件：advanced_search_by_description.py

使用场景：

• 已位于高级搜索页面
• 需要搜索商品描述中的关键词（而不是商品名称）
• 需要按价格范围筛选

前置条件：

• 首先使用 navigate() 导航到网站首页
• 然后使用 click() 点击“Advanced Search”链接
• 获取表单字段的 ref 值

典型任务示例：

• 搜索描述包含“vitamin”、价格在 $0.00 到 $99.99 之间的商品

用法：

# Usage:
#   python advanced_search_by_description.py <description> <price_from> <price_to> <desc_ref> <price_from_ref> <price_to_ref> <search_btn_ref>
# Example:
python advanced_search_by_description.py "vitamin" 0.00 99.99 e99 e110 e114 e118

---

4. 结账 - 填写配送信息

文件：fill_shipping_info.py

使用场景：

• 已位于结账页面（点击“Proceed to Checkout”之后）
• 需要填写完整的配送地址信息

典型任务示例：

• 填写客户姓名、地址、城市、州、邮政编码、电话等信息

前置条件：

• 首先使用 click() 点击“Proceed to Checkout”按钮
• 使用 snapshot() 获取所有表单字段的 ref 值

用法：

# Usage:
#   python fill_shipping_info.py <email> <first_name> <last_name> <street> <country> <state> <city> <zipcode> <phone> <email_ref> <fname_ref> <lname_ref> <street_ref> <country_ref> <state_ref> <city_ref> <zip_ref> <phone_ref>
# Example:
python fill_shipping_info.py [email protected] Alice Johnson "456 Oak Avenue" "United States" California "San Francisco" 94102 415-555-0123 e33 e46 e51 e65 e75 e80 e85 e90 e95

---

II. 基础工具（何时使用单个函数）

以下是 utils.py 中提供的基础工具函数及其使用场景。这些是用于灵活组合的原子操作。

注意：基础工具需要在异步上下文中使用。可以使用 run_browser_ops.py 简化操作。代码应写在一行中，不要换行。

如何运行

# Standard format (browser persists across calls)
python run_browser_ops.py -c "await browser.navigate('http://localhost:7770')"

导航工具

navigate(url: str)

使用场景：

• 打开网站首页
• 直接访问特定商品页面的 URL
• 跳转到特定 URL

示例：

python run_browser_ops.py -c "await browser.navigate('http://localhost:7770')"

---

navigate_back()

使用场景：

• 返回上一页
• 浏览商品后返回搜索结果页面

示例：

python run_browser_ops.py -c "await browser.navigate_back()"

---

交互工具

click(ref: str, element: Optional[str] = None)

使用场景（非常广泛）：

• 点击导航菜单（类别、子类别）
• 点击商品链接
• 点击“Add to Compare”按钮
• 点击“Add to Cart”按钮
• 点击分页链接（Page 2、Page 3 等）
• 点击价格筛选项
• 点击排序方向切换按钮

示例：

python run_browser_ops.py -c "await browser.click(ref='e56', element='Health & Household menu item')"

---

type_text(ref: str, text: str, element: Optional[str] = None)

使用场景：

• 在搜索框中输入关键词
• 填写单个表单字段
• 修改数量输入框

示例：

# Enter in search box
python run_browser_ops.py -c "await browser.type_text(ref='e32', text='gingerbread', element='Search input')"
# Press Enter to submit
python run_browser_ops.py -c "await browser.press_key('Enter')"

---

fill_form(fields: List[Dict[str, str]])

使用场景：

• 填写多个表单字段（例如高级搜索表单）
• 批量更新表单数据
• 更新购物车中的数量

示例：

# Fill advanced search form
python run_browser_ops.py -c "await browser.fill_form(fields=[{'name': 'Product Name', 'ref': 'e111', 'value': 'cookie'}, {'name': 'Price From', 'ref': 'e134', 'value': '20.00'}, {'name': 'Price To', 'ref': 'e138', 'value': '40.00'}])"

# Update cart quantity
python run_browser_ops.py -c "await browser.fill_form(fields=[{'name': 'Qty', 'ref': 'e141', 'value': '3'}])"

---

select_option(ref: str, element_desc: str, value: str)

使用场景：

• 选择排序方式（排序依据：价格、相关性等）
• 选择国家／州／省下拉选项
• 选择产品选项（例如口味、尺寸等）

示例：

# Sort by price
python run_browser_ops.py -c "await browser.select_option(ref='e114', element_desc='Sort By dropdown', value='Price')"

# Select product flavor
python run_browser_ops.py -c "await browser.select_option(ref='e128', element_desc='Flavor', value='Peanut Butter')"

---

press_key(key: str)

使用场景：

• 提交搜索（按 Enter 键）
• 关闭对话框（按 Escape 键）

示例：

# Press Enter after typing in search box
python run_browser_ops.py -c "await browser.press_key('Enter')"

---

页面状态工具

snapshot()

使用场景（非常重要）：

• 不确定当前页面状态时
• 需要查看完整页面内容以决定下一步操作时
• 验证操作是否成功时
• 查找特定元素的 ref 引用时

示例：

python run_browser_ops.py -c "await browser.snapshot()"

最佳实践：

• 在关键操作前后使用 snapshot 确认状态
• 在搜索结果页面使用 snapshot 查看所有产品
• 页面跳转后使用 snapshot 确认页面已完全加载

---

get_console_messages()

使用场景：

• 调试 JavaScript 错误
• 查看页面加载期间的日志信息

---

get_network_requests()

使用场景：

• 调试网络请求问题
• 查看 API 调用状态

---

等待工具

wait_for_time(seconds: int)

使用场景：

• 等待页面完全加载
• 等待动画效果结束
• 等待异步数据加载

示例：

python run_browser_ops.py -c "await browser.wait_for_time(3)"

---

标签页管理

list_tabs()

使用场景：

• 查看所有当前打开的标签页
• 获取标签页 ID

---

tab_new(url: Optional[str] = None)

使用场景：

• 在新标签页中打开产品详情页（保留搜索结果页面）
• 同时比较多个产品

示例：

python run_browser_ops.py -c "await browser.tab_new(url='http://localhost:7770/product-page.html')"

三、最佳实践建议

1. 善用 snapshot()

在以下情况下使用 snapshot()：

• 刚进入新页面，不确定页面结构时
• 执行操作后，需要验证结果时
• 需要查找元素的 ref 引用时
• 不确定当前排序顺序（降序或升序）／筛选状态时

---

使用原则

1. 固定工作流优先使用组合技能：例如高级搜索、将商品数量添加到购物车、填写表单
2. 场景多变时灵活使用基础工具：例如点击、输入、选择等原子操作
3. 善用 snapshot() 了解页面状态：在关键步骤前后确认状态