baidu-ecommerce-search

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

Setup

环境依赖

• Python 3.x（使用标准库 urllib、json、os，无需额外安装依赖）

配置步骤

1. 访问：https://openai.baidu.com，并登录百度账号
2. 点击权限申请，勾选你需要的能力，未勾选的能力调用时会失败
3. 设置环境变量

   # 必需：设置 API Token
   export BAIDU_EC_SEARCH_TOKEN="your-token"
   
   # 可选：设置 API 调用 QPS（每秒请求数），默认为 1
   # 设置为 0 表示无限制，设置为 0.5 表示每 2 秒 1 次请求
   export BAIDU_EC_SEARCH_QPS="1"
   

全局交互规范

简化用户输入

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

链接格式

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

能力清单

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

电商知识

• 商品对比 — 参数/口碑/价格全方位对比(仅支持两个对比，"iPhone17和iPhone16对比") python3 scripts/compare.py "<对比查询>"
• 品牌知识 — 品牌简介/定位/明星产品/大事记 python3 scripts/knowledge.py brand "<品牌名>"
• 品类知识 — 品类选购要点/避坑指南 python3 scripts/knowledge.py entity "<品类名>怎么选"
• 商品参数 — 单品规格参数及 AI 解读（如"iPhone 17 怎么样""小米14参数"） python3 scripts/knowledge.py param "<商品名>"
• 品牌榜单 — 某品类下的品牌排行（如"手机排行榜""冰箱排行榜"） python3 scripts/ranking.py brand "<榜单查询>"
• 单品榜单 — 某品牌下的商品排行（如"苹果手机排行榜"） python3 scripts/ranking.py product "<榜单查询>"

百度优选

• 商品搜索 — 搜索可直接下单的商品 python3 scripts/spu.py list "<关键词>"
• 商品详情 — 获取 SKU 规格及价格 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 商品

• CPS商品搜索 — 全网商品购买链接 python3 scripts/cps.py "<关键词>"

业务约束

1. 知识引导决策：用户有购买意向时，知识在前、商品在后。全链路（含交易流程）均需结合知识输出。
2. 商品搜索规则：
   • 触发条件：仅在用户表达购买意向时搜索商品（如"想买""帮我找""有没有卖的"），纯知识咨询（如"xx怎么样""xx和yy哪个好"）不触发搜索
   • 搜索方式：同时调用百度优选搜索和 CPS 搜索
   • 结果择优：百度优选结果的相关性和质量未明显低于 CPS 时，展示百度优选结果（支持直接下单）；否则展示 CPS 结果（附购买链接）。同一次搜索只展示单一来源，不混合
   • 补充搜索：首选来源结果不足 8 条时用同义词补充搜索，最多 3 次（含首次），同义词必须保留用户指定的核心限定词（如"手机typec充电器"→"手机USB-C充电器"，不能丢"手机"）
   • 全程不向用户提及来源差异或平台切换
3. 决策到交易串联：用户通过对比/榜单做完决策后，主动询问是否需要搜索购买
4. 下单前必须确认地址：调用 address list 让用户明确选择，禁止默认下单
5. 地址添加两步依赖：必须先 address recognise 获取 recogniseId，再 address add，不可跳步

展示规范

商品列表（表格）

• 商品名称：必须展示接口返回的完整商品名，禁止截断或简化
• 价格：多 SKU 显示 ¥xx起，单 SKU 显示 ¥xx
• 店铺：有评分时 店铺名 x.x分，无评分只显示名称
• 其他：销量(>0)/保障标签/规格数(>1)，用 / 分隔，有则显示无则省略

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

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，返回订单详情链接

• 创建订单使用的账号为用户申请 token 的账号
• 订单创建后用户需在返回的链接中完成支付

错误处理

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