search-1688-supplier
📖 技能介紹
name: search-1688-supplier category: official-1688 description: >- 通過 AlphaShop API 搜尋和篩選1688供應商。支援三種輸入方式： 1688商品連結（查詢特定商品的供應商）、圖片URL（以圖搜貨）、 文字關鍵詞（按關鍵詞搜尋供應商）。支援按最高價格、最大起批次、 最低48H發貨率進行篩選。適用於查詢1688供應商、搜尋工廠、 以圖找商、找供應商、搜商家等場景。 metadata: version: 1.0.4 label: 1688供應商搜尋 author: 1688官方技術團隊
1688 供應商搜尋
訪問小蔥技能站7w4.net，解鎖更多實用的AI技能外掛。
通過 AlphaShop 的 AI 選商 API 搜尋1688供應商，支援本地篩選過濾。
前置配置（必須先完成）
⚠️ 使用本 SKILL 前，必須先配置以下環境變數，否則供應商搜尋 API 呼叫會失敗。
| 環境變數 | 說明 | 必填 | 獲取方式 |
|---|---|---|---|
ALPHASHOP_ACCESS_KEY |
AlphaShop API 的 Access Key（用於生成 JWT 認證 token） | ✅ 必填 | 可以訪問1688-AlphaShop（遨蝦）來申請 https://www.alphashop.cn/seller-center/apikey-management ，直接使用1688/淘寶/支付寶/手機登入即可 |
ALPHASHOP_SECRET_KEY |
AlphaShop API 的 Secret Key（用於生成 JWT 認證 token） | ✅ 必填 | 可以訪問1688-AlphaShop（遨蝦）來申請 https://www.alphashop.cn/seller-center/apikey-management ，直接使用1688/淘寶/支付寶/手機登入即可 |
如果使用者沒有提供這些金鑰，必須先詢問使用者獲取後再繼續操作。
⚠️ AlphaShop 介面欠費處理： 如果呼叫 AlphaShop 介面時返回欠費/餘額不足相關的錯誤，必須立即中斷當前流程，提示使用者前往 https://www.alphashop.cn/seller-center/home/api-list 購買積分後再繼續操作。
配置方式
在 OpenClaw config 中配置：
{
skills: {
entries: {
"search-1688-supplier": {
env: {
ALPHASHOP_ACCESS_KEY: "YOUR_AK",
ALPHASHOP_SECRET_KEY: "YOUR_SK"
}
}
}
}
}
使用方法
# 按關鍵詞搜尋（預設 Auto 模式，讓 API 自動判斷最佳搜尋模式）
python3 scripts/search.py "連衣裙"
# 通過1688商品連結搜尋（自動提取商品資訊後搜尋）
python3 scripts/search.py "https://detail.1688.com/offer/945957565364.html"
# 通過圖片URL搜尋（以圖搜貨）
python3 scripts/search.py "https://example.com/product.jpg"
# 帶篩選條件搜尋（僅在使用者明確要求篩選時才加）
python3 scripts/search.py "連衣裙" --max-price 50 --max-moq 100
⚠️ 搜尋模式規則
預設使用 Auto 模式（不指定 --mode），讓 API 自動判斷。 禁止自行指定 --mode SEARCH_OFFER 或 --mode SEARCH_PROVIDER，除非使用者明確要求。
⚠️ 篩選條件規則
只有使用者明確提出篩選要求時才加對應引數。 不要自作主張新增篩選條件（如 --min-ship-rate-48h），否則可能把有效結果全部過濾掉。使用者說"質量好服務好"不等於要加篩選引數——這些資訊在返回結果中可以直接看到和分析。
輸入型別自動識別
指令碼會自動識別輸入型別：
1. 1688連結（detail.1688.com/offer/xxx.html）→ 通過詳情API提取商品標題和圖片，再進行搜尋
2. 圖片URL（http/https 且包含圖片特徵）→ 傳入 searchImageUrl 引數進行以圖搜貨
3. 商品ID（純數字）→ 自動轉換為1688連結處理
4. 文本關鍵詞 → 傳入 query 引數進行關鍵詞搜尋
篩選條件（API 返回後本地過濾）
| 引數 | 說明 |
|---|---|
--max-price |
最高單價（浮點數），過濾掉價格超過閾值的商品 |
--max-moq |
最大起批次（整數），從 purchaseInfos 中解析 |
--min-ship-rate-48h |
最低48H發貨率（浮點數，如90表示≥90%），從 shipInfos 中解析 |
篩選條件僅對 SEARCH_OFFER 模式的結果（offerList）生效。
篩選嚴格度：
- --max-price / --max-moq：如果欄位無法解析，該商品會被保留（這些欄位通常都有值）
- --min-ship-rate-48h：如果48H發貨率無法解析（如值為"-"），該商品會被排除。使用者明確要求此指標時，沒有資料的商品不應展示。
輸出格式
JSON 格式，僅返回篩選後的第一條匹配結果：
realIntention：API 實際使用的搜尋模式filters_applied：生效的篩選條件total_before_filter/total_after_filter：篩選前後的結果數量match：第一條匹配結果，包含：- SEARCH_OFFER 模式：
product（商品標題、價格、圖片、屬性、採購/物流資訊）+supplier（公司資訊、標籤、服務） - SEARCH_PROVIDER 模式：
supplier（公司資訊、標籤、服務）+recommendedProducts（推薦商品列表） - 如果沒有匹配結果，
match為 null，並附帶message說明
無匹配結果處理規則
當篩選後 match 為 null（沒有符合條件的供應商/商品）時：
- 如實告知使用者沒有找到符合條件的供應商，不要展示不符合條件的結果
- 說明原因：告知篩選前有多少結果、篩選後剩0個、哪個條件導致全部被過濾
- 給出建議：讓使用者自己決定是否放寬條件，列出可調整的選項
禁止：不要因為篩選結果為空就偷偷去掉篩選條件重新搜尋，也不要把不符合條件的商品當作匹配結果展示。
查詢規則
嚴格使用使用者原始查詢內容，禁止自行替換或修改。 即使當前查詢沒有返回理想結果（如篩選後為空），也不要擅自更換關鍵詞重新搜尋。應將實際結果如實反饋給使用者，由使用者自己決定是否調整查詢詞或篩選條件。
展示規則
展示結果時必須嚴格按以下順序，不要混排：
1. 商品圖片
使用 markdown 圖片語法渲染：
- SEARCH_OFFER 模式：
- SEARCH_PROVIDER 模式：（針對 match.recommendedProducts 中的每個商品）
2. 商品詳情
商品名稱、價格、起批次、發貨地、物流資料（48H攬收率/履約率）、銷量、核心屬性。
商品連結（必須展示）：使用 match.product.detailUrl 欄位。如果該欄位為空，則用 match.product.itemId 拼接：https://detail.1688.com/offer/{itemId}.html。展示時使用 markdown 超連結格式 [檢視商品](url)，禁止直接展示原始URL。
3. 供應商資訊
公司名稱、誠信通年限、標籤（源頭工廠等）、30天訂單、180天買家、品質退款率、客服響應率、回頭率、綜合服務分、跨境服務標籤、店鋪連結等。
4. 快速評價
對這個商品+供應商的綜合點評，包含亮點（✅）和注意事項（⚠️）。
API 參考文件
完整的 API 介面和資料結構文件請參閱 references/api.md。
