baidu-ecommerce-search

---

name: baidu-ecommerce-search

description: Baidu ecommerce one-stop service, including product knowledge (product comparison / brand knowledge / category knowledge / product specifications / brand rankings / product rankings) and transaction execution (search / order placement / after-sales)

homepage: https://openai.baidu.com

metadata: {"openclaw":{"emoji":"🛒","slug":"baidu-ecommerce-search","requires":{"bins":["python3"],"env":["BAIDU_EC_SEARCH_TOKEN"]},"primaryEnv":"BAIDU_EC_SEARCH_TOKEN"}}

---

# baidu-ecommerce-search

百度电商一站式服务，覆盖商品知识查询和购物交易全流程。支持商品对比、品牌知识、品类选购指南、商品参数解读、品牌榜单及单品榜单等知识查询能力；同时提供商品搜索、规格查看、地址管理、下单购买、订单查询及售后服务等完整交易链路，帮助用户从决策到购买一步到位。

Setup

1. 访问 https://openai.baidu.com 登录百度账号，点击权限申请勾选所需能力

2. 设置环境变量：

```bash

export BAIDU_EC_SEARCH_TOKEN="your-token"

export BAIDU_EC_SEARCH_QPS="1" # 可选，默认1，设为0无限制

```

全局交互规范

简化用户输入

展示列表时必须带序号供用户输入序号选择，确认环节告知用户可输入"1"或"确认"。

链接格式

所有可跳转内容用 `[文本](URL)` 格式，URL 中的 `|` 必须转义为 `\|`，优先使用接口返回的购买链接。

能力清单

以下能力是可组合的工具箱。响应用户时，先分析哪些能力与用户问题相关，再调用所有相关能力.

电商知识

`python3 scripts/compare.py "<对比查询>"`

`python3 scripts/knowledge.py brand "<品牌名>"`

`python3 scripts/knowledge.py entity "<品类名>怎么选"`

`python3 scripts/knowledge.py param "<商品名>"`

`python3 scripts/ranking.py brand "<榜单查询>"`

`python3 scripts/ranking.py product "<榜单查询>"`

百度优选

`python3 scripts/spu.py list "<关键词>"`

`python3 scripts/spu.py detail <spuId>`

`python3 scripts/order.py create --sku-id <skuId> --spu-id <spuId> --addr-id <addrId>`

`python3 scripts/order.py history`

`python3 scripts/order.py detail <orderId>`

`python3 scripts/after_service.py <orderId>`

`python3 scripts/address.py list`

`python3 scripts/address.py recognise "<姓名 地址 手机号>"`

`python3 scripts/address.py add <recogniseId>`

CPS 商品

`python3 scripts/cps.py "<关键词>"`

业务约束

1. **知识引导决策**：用户有购买意向时，知识在前、商品在后。全链路（含交易流程）均需结合知识输出。

2. **商品搜索规则**：

- **触发条件**：仅在用户表达购买意向时搜索商品（如"想买""帮我找""有没有卖的"），纯知识咨询（如"xx怎么样""xx和yy哪个好"）不触发搜索

- **搜索方式**：同时调用百度优选搜索和 CPS 搜索

- **准入规则**：百度优选和 CPS 结果均按相关性筛选，仅纳入与用户查询相关的商品

- **排序规则**：表格内必须先展示百度优选的商品，再展示cps的商品

- **补充搜索**：首选来源结果不足 10 条时用同义词补充搜索，最多 3 次（含首次），同义词必须保留用户指定的核心限定词（如"手机typec充电器"→"手机USB-C充电器"，不能丢"手机"）

- **全程不向用户提及来源差异或平台切换**

3. **决策到交易串联**：用户通过对比/榜单做完决策后，主动询问是否需要搜索购买

4. **下单前必须确认地址**：调用 address list 让用户明确选择，禁止默认下单

5. **地址添加两步依赖**：必须先 address recognise 获取 recogniseId，再 address add，不可跳步

展示规范

商品列表（表格）

| 序号 | 商品名称 | 价格 | 商城 | 店铺 | 其他 |

|:---:|:---|:---:|:---:|:---|:---|

| 1 | [商品名称](spuUrl) | ¥xx起 | 京东 | 店铺名 4.9分 | 销量170 / 7天无理由 / 3种规格 |

品牌榜单列表

下单流程（严格按顺序执行）

CPS商品

不支持 spu detail 和 order create。用户选择 CPS 商品时：解析 `extra_attributes` 展示规格参数表格 → 提供购买链接引导跳转。

百度优选商品

1. **商品选择**：调用 spu list 搜索 → 展示结果 → 用户选择 → 获取 spuId

2. **规格选择**：从搜索结果或 spu detail 获取 SKU 列表

- 仅 1 个 SKU：自动使用，跳过确认

- 多个 SKU：展示规格让用户选择 → 获取 skuId

- 无匹配 SKU（SKU 规格与用户需求不符）：禁止使用不匹配的 SKU 下单，告知用户当前商品无匹配规格，引导重新搜索或选择其他商品

3. **地址确认**：调用 address list 获取地址列表

- 有地址：展示列表让用户选择，同时提示可新增地址 → 获取 addrId

- 无地址：引导用户提供地址信息（格式：收货人 + 详细地址 + 手机号）→ 调用 address recognise → 调用 address add → 获取 addrId

4. **订单确认**：汇总展示商品名称 + 规格 + 收货地址 + 金额 → 用户确认

5. **创建订单**：调用 order create，返回订单详情链接

错误处理

| errmsg | 处理 |

|---|---|

| `token is limit` | 必须静默等待 1 秒后重试同一请求，不可跳过或用其他结果替代 |

| `token权限不足` | 告知用户访问 https://openai.baidu.com 申请 |

| `token is nil` / `token is invalid` | 提示用户检查 BAIDU_EC_SEARCH_TOKEN 配置 |

| `path错误` / `请求地址错误` / `非法path` | 检查脚本路径和参数 |

| `商品已下架` / `商品已售罄` | 引导选择其他商品或规格 |

| `不支持用户地址发货` | 引导修改收货地址 |

不向用户展示原始 errmsg，转译为用户友好的提示。