用途
本技能通过1688开放平台官方API，为智能体提供完整的1688商品搜索与推荐能力，覆盖类目查询、关键词搜索、图片搜索、商品详情、店铺商品搜索、商品推荐、品池商品拉取、相关性推荐和图片上传共9个核心接口，适合电商选品、采购寻源、以图搜款等业务场景。
主要能力
- 类目查询：查询1688一级类目，支持中英文返回。
- 关键词搜索：支持多语言关键词搜索，可按发货时效、认证工厂、一件代发、7天上新、1688严选等条件筛选，支持按价格、复购率、月销量排序。
- 图片搜索：支持本地图片文件、图片URL、已有imageId三种方式，优先级为本地图片文件 > imageId > 图片URL。
- 商品详情：查询单个商品的详细信息，每次仅支持1个商品ID，不支持批量。
- 店铺商品搜索：根据商家ID（sellerOpenId）搜索该商家的商品。
- 商品推荐：基于关键词进行商品推荐。
- 品池商品拉取：从业务定制的品池中分页拉取商品列表，需提供品池ID（offerPoolId）和查询任务ID（taskId），分页查询时需固定同一个taskId。
- 相关性商品推荐：基于商品ID推荐相似或相关商品，部分商品可能返回空。
- 上传图片获取imageId：上传本地图片获取imageId，图片大于300KB时自动压缩。
鉴权与配置
每个技能内置独立鉴权模块（scripts/auth.py），不依赖外部技能。所有1688技能的Token缓存指向同一固定路径 skills/.1688_token_cache.json，任一技能首次鉴权后其他技能可直接复用缓存，Token过期前自动用refresh_token刷新。支持 ALI1688_REFRESH_TOKEN（自动刷新）和 ALI1688_ACCESS_TOKEN（直接使用）两种模式。
在OpenClaw config中通过环境变量配置：
{
skills: {
entries: {
"1688-product-search": {
env: {
ALI1688_APP_KEY: "your-app-key",
ALI1688_APP_SECRET: "your-app-secret",
ALI1688_REFRESH_TOKEN: "your-refresh-token"
}
}
}
}
}
获取AppKey/AppSecret/Token的流程：注册1688开放平台开发者并创建应用获取AppKey与AppSecret；订购对应解决方案获取API调用权限；通过OAuth授权获取access_token与refresh_token；最后配置到环境变量。access_token有效期约10小时，refresh_token有效期约半年。常见错误包括HTTP 400刷新失败、HTTP 401未授权、签名错误(code=25)、无权限调用等，需分别重新授权、启用自动刷新、检查AppSecret或订购解决方案。
使用方式
通过命令行脚本 scripts/product_search.py 调用，示例：
- 类目查询：
python3 scripts/product_search.py category 0 - 关键词搜索：
python3 scripts/product_search.py keyword-search "dress" --country en - 带筛选与排序：
python3 scripts/product_search.py keyword-search "dress" --country en --filter "shipIn48Hours,shipIn24Hours" --sort '{"price":"asc"}' - 图片搜索：
python3 scripts/product_search.py image-search --image-path "/path/to/image.jpg" --country en - 商品详情：
python3 scripts/product_search.py product-detail "offer_id" - 店铺搜索：
python3 scripts/product_search.py shop-search "seller_open_id" --country en - 商品推荐：
python3 scripts/product_search.py offer-recommend "keyword" --country en - 品池拉取：
python3 scripts/product_search.py pool-pull --pool-id 111 --task-id 1 --page-no 1 --page-size 10 - 相关推荐：
python3 scripts/product_search.py related-recommend "offer_id" --country en - 上传图片：
python3 scripts/product_search.py upload-image "/path/to/image.jpg"
通用参数中，--country/--language 默认en，可选en/ja/ko/ru/vi/es等，不支持zh；--beginPage 默认1；--pageSize 默认20，最大50。输出为JSON格式的1688 API原始响应，失败时返回错误信息JSON并退出码1，不返回mock数据。
适用场景
适用于智能体中的电商选品、以图搜款、同款查找、店铺商品查询、关键词找货、货盘拉取等采购与供应链相关任务。当接收到“图搜同款”“找同款”“以图搜款”等指令时，系统会自动调用图片搜索接口而非关键词搜索接口。
限制
- 语言参数不支持zh，无论中英文提问均默认传en，传zh可能导致接口报错或异常。
- 每个查询最多返回2000个商品。
- 商品详情接口每次仅支持查询1个商品ID，不支持批量。
- 图片搜索仅推荐使用1688图片地址（alicdn.com），其他域名成功率不稳定；图片上传接口的imageBase64方式仅支持1688平台自身图片，本地截图或外部图片可能返回无效imageId（“0”）。
- 品池拉取需具备品池访问权限，offerPoolId需从对接业务获取，随意传会报错。
- 排序功能仅对当前页有效。
- API返回的是原价，下单时会享受营销价格。
- 所有商品查询结果必须向用户展示offerId和商品链接，商品链接优先使用promotionURL，无则使用
https://detail.1688.com/offer/{offerId}.html。
接口地址
- 类目查询：
POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/category.translation.getById/${APPKEY} - 关键词搜索：
POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.keywordQuery/${APPKEY} - 图片搜索：
POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.imageQuery/${APPKEY} - 商品详情：
POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.queryProductDetail/${APPKEY} - 店铺搜索：
POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.querySellerOfferList/${APPKEY} - 商品推荐：
POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.search.offerRecommend/${APPKEY} - 品池商品拉取：
POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/pool.product.pull/${APPKEY} - 相关推荐：
POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.related.recommend/${APPKEY} - 图片上传：
POST https://gw.open.1688.com/openapi/param2/1/com.alibaba.fenxiao.crossborder/product.image.upload/${APPKEY}
完整API接口和数据结构文档请参阅references/api.md。