linkfox-1688-sourcing

name	linkfox-1688-sourcing
description	1688 货源一站式 AI 工具集，整合商品搜索、热销榜单、以图搜图与已授权采购履约，覆盖找货、选品、比价、图搜同款与下单全流程。

Linkfox 1688货源（1688 Sourcing）

1688 货源一站式 AI 工具集，整合 3 类底层工具、4 项子能力，覆盖货源搜索与热销榜单、以图搜图、已授权采购履约。各子能力完整参数、响应字段与错误码见 references/ 下对应文件，可执行脚本见 scripts/。

能力边界

✅ 能力范围

• 货源搜索与榜单（1688_sourcing）：商品搜索（linkfox-dld-product-search，按关键词/商品链接/商品 ID 检索 1688 批发商品，近 7 天/30 天销量周期，按价格/销量/销售额/上架时间排序，按公司类型/卖家会员/发货时间/代发权益/面单支持等筛选）、商品热销榜单（linkfox-dld-product-billboard，周榜/月榜，按销售笔数/销售额/销量排序，发现爆款与趋势货源）。返回批发价、代发价、销售笔数/件数、预估销售额、起批量、供应商资质、店铺与商品链接等。
• 以图搜图（1688_search_by_image）：1688 以图搜图（linkfox-1688-search-by-image，通过图片 URL/Base64/imageId 视觉检索外观相似或同款货源），返回标题、批发价、代发价、月销量、起批量、复购率、交易评分、商家身份（超级工厂/实力商家/诚信通）等；支持价格/筛选（1688 严选/认证工厂/发货时效/品质退款率等）/排序/分页；本地图片先用 upload_image.py 上传获取公网 URL（有效期 24h）。
• 采购履约（1688_procurement）：1688 采购全流程（linkfox-1688-procurement），覆盖 OAuth 授权检查与发起授权、SKU/规格与收货地址查询、下单预览、创建订单、获取支付链接、订单状态、物流概览与物流轨迹、取消订单、确认收货。除授权类操作外每个 endpoint 前自动校验当前用户 ACTIVE 且未过期的 1688 授权；高风险写操作（创建订单/支付链接/取消订单/确认收货）需用户单独中文确认后由 Agent 注入对应 boolean 安全字段。
• 数据平台均为中国大陆 1688 批发平台（阿里巴巴国内 B2B 市场），无多站点概念。

❌ 边界与限制

• API Key 必需：所有工具均需环境变量 LINKFOX_AGENT_API_KEY（或 LINKFOXAGENT_API_KEY）；各工具独立计费、独立限频。
• 计费约束：商品搜索/热销榜单固定计费（成功约 9 积分/18000 token），以图搜图固定计费（约 4.5 积分/9000 token），采购履约各操作消耗积分；同一会话同一参数组合默认只调用一次（搜索/榜单/图搜脚本带 24h 本地缓存）；失败、空结果、参数不全或授权不足不得自动换关键词、翻页或连续试探；需继续检索时先向用户说明会产生额外消耗（各工具计费规则见 skills-version.json 对应条目与 references 内 api.md）。
• 采购授权前置：采购类操作依赖当前用户已授权的 1688 OAuth；无 ACTIVE 授权时不调用目标 endpoint；高风险写操作失败不自动重试；不向用户索要 1688 token/refresh token/callback code/app secret。
• 不在范围内：Amazon/TikTok/沃尔玛等其他平台选品（用对应平台技能）；Alibaba.com 国际站数据；1688 店铺级分析（店铺流量/排名/评分）；商品评论分析；价格历史与趋势分析；图片生成或编辑；物流成本计算与货代；实时库存与订单系统对接；与供应商或平台的直接沟通。
• 数据时效：商品搜索/榜单为店雷达分析数据（7 天/30 天/周榜近 90 天/月榜近 12 个月）；以图搜图为实时搜索、不入库、无法二次 SQL 处理；采购履约为依赖 OAuth 的实时接口。

工具选择指南

按需求在下表定到子能力，再跳到【业务需求路由速查】查端点/脚本/references 取参执行。

需求 / 用户说	默认推荐（子能力）	何时换用其他
关键词找 1688 货源 / 找供应商（"1688 上找 XX 货源"）	linkfox-dld-product-search（关键词搜索，7/30 天销量）	要看周/月排行榜用 linkfox-dld-product-billboard；有图片找同款用 linkfox-1688-search-by-image
1688 什么好卖 / 趋势 / 热销榜（"1688 热销榜""什么火"）	linkfox-dld-product-billboard（周榜/月榜排名）	要按关键词实时搜 + 销量筛选用 linkfox-dld-product-search
用图片找 1688 同款 / 以图搜图（"用图找货源""找同款"）	linkfox-1688-search-by-image（唯一图搜，需图片 URL）	本地图片先 upload_image.py 上传换公网 URL；要按关键词文本搜索用 linkfox-dld-product-search
按商品 ID / 商品链接查 1688 商品	linkfox-dld-product-search（支持 goodsUrl/productIds）	仅按 ID 查榜单商品也可用 linkfox-dld-product-billboard
工厂直供 / 超级工厂 / OEM 供应商（"找工厂""顶级工厂"）	linkfox-dld-product-search（companyType=2/shiLiType=superFactory）	要榜单里的工厂货用 linkfox-dld-product-billboard
1688 一件代发货源（"一件代发""支持代发"）	linkfox-dld-product-search（proxyRights=4360897）	要榜单代发货用 linkfox-dld-product-billboard
跨境货源 / 出口商品（"跨境商品""1688 严选"）	linkfox-dld-product-search（offerType=4）	要图搜跨境同款用 linkfox-1688-search-by-image（filter=1688Selection）
1688 新品 / 最近上架（"新品""最近上的"）	linkfox-dld-product-search（sortField=offerCreateTime）	要榜单新品用 linkfox-dld-product-billboard（offerType=2）
对比供应商 / 跨供应商比价	linkfox-dld-product-search（多维排序）	—
查我的 1688 授权店铺（"我的 1688 授权"）	linkfox-1688-procurement（authorized_stores.py）	—
生成 1688 授权链接（"授权 1688"）	linkfox-1688-procurement（）

工具选择思路

• 重要：多个子能力满足需求时，要依据需求深入分析子能力的功能、用途、出入参、从中调研出最合适的子能力，并推荐用户，让用户自己决定。
• 满足程度同等的前提下，向用户推荐"默认推荐子能力"。注意：找货/选品用搜索或榜单（1688_sourcing）或图搜（1688_search_by_image），已授权采购履约用 1688_procurement——前者只查货不交易，后者才可下单。

业务需求路由速查

按【工具选择指南】定到子能力后，下表查端点、脚本与 references 文件取参执行：

子能力 ↔ references 文件 ↔ 端点 ↔ 脚本（4 项）

1688_sourcing

子能力	references 文件	端点	脚本
linkfox-dld-product-billboard	references/linkfox-dld-product-billboard.md	POST /dld/productBillboard	dld_product_billboard.py
linkfox-dld-product-search	references/linkfox-dld-product-search.md	POST /dld/productSearch	dld_product_search.py

1688_search_by_image

子能力	references 文件	端点	脚本
linkfox-1688-search-by-image	references/linkfox-1688-search-by-image.md	POST /alibaba1688/imageSearch	alibaba1688_image_search.py、upload_image.py（本地图片上传）

1688_procurement

子能力	references 文件	端点	脚本
linkfox-1688-procurement	references/linkfox-1688-procurement.md	POST /alibaba1688/{operation}	见下表（12 个操作脚本 + _alibaba1688_common.py 共享模块）

1688 采购操作明细（operation ↔ 脚本 ↔ 风险）

operation	端点	脚本	风险	高风险确认字段
authorizeUrl	POST /alibaba1688/authorizeUrl	authorize_url.py	低（不需 ACTIVE 前置）	—
authorizedStores	POST /alibaba1688/authorizedStores	authorized_stores.py	低（不需 ACTIVE 前置）	—
receiveAddressList	POST /alibaba1688/receiveAddressList	receive_address_list.py	低（需 ACTIVE）	—
sku	POST /alibaba1688/sku	sku.py	低（需 ACTIVE）	—
orderPreview	POST /alibaba1688/orderPreview	order_preview.py	中（需 ACTIVE）	—
createOrder	POST /alibaba1688/createOrder	create_order.py	高（需 ACTIVE）	confirmCreateOrder=true
paymentUrl	POST /alibaba1688/paymentUrl	payment_url.py	高（需 ACTIVE）	confirmGetPaymentUrl=true
orderStatus	POST /alibaba1688/orderStatus	order_status.py	低（需 ACTIVE）	—
logistics	POST /alibaba1688/logistics	logistics.py	低（需 ACTIVE）	—
logisticsTrace	POST /alibaba1688/logisticsTrace	logistics_trace.py	低（需 ACTIVE）	—
confirmReceive	POST /alibaba1688/confirmReceive	confirm_receive.py	高（需 ACTIVE）	confirmReceive=true
cancelOrder	POST /alibaba1688/cancelOrder	cancel_order.py	高（需 ACTIVE）	confirmCancel=true

调用方式

• 网关：${LINKFOX_TOOL_GATEWAY}/<端点>，请求方式 POST、Content-Type application/json，认证 Header Authorization: <api_key>（api_key 从环境变量 LINKFOX_AGENT_API_KEY 或 LINKFOXAGENT_API_KEY 读取；未配置按下方【解决认证和积分问题】处理）。各端点路径见上方【业务需求路由速查】与对应 references 文件（注意：商品搜索/榜单走 /dld/ 前缀，图搜与采购走 /alibaba1688/ 前缀）。
• Python 脚本：每项子能力对应 scripts/<脚本名>.py '<JSON 参数>' [--inline]（脚本名与端点见路由速查表）。采购类脚本另支持 --payload-env PAYLOAD / --payload-file payload.json / --save / --no-save（Windows 推荐用 $env:PAYLOAD 传参，见 references/linkfox-1688-procurement.md）；upload_image.py 用法为 python scripts/upload_image.py /path/to/local/image.png，返回公网图片 URL（{"url": "..."}，有效期 24h）。
• 输出策略：商品搜索/榜单/图搜脚本始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/<skill>-<timestamp>.json（<cwd> 为脚本执行时工作目录；<session> 取自 SESSION_ID；禁止写入 /tmp，当前目录不可写则报错）；响应体 ≤ 8 KB 落盘后完整打印到 stdout，> 8 KB 仅打印摘要（顶层字段、常见计数、最大列表长度 + 前 3 条样本）；加 --inline 强制全量打印（同样落盘）。采购类脚本略有不同：响应体 ≤ 8 KB 默认不落盘、直接把完整脱敏 JSON 打印到 stdout，> 8 KB 默认写入 <writable-root>/linkfox/.../data/linkfox-1688-procurement-<operation>-<timestamp>.json 并仅输出摘要；加 --save/LINKFOX_SKILL_SAVE_RESPONSE=1 强制保存，--no-save/LINKFOX_SKILL_NO_SAVE=1 禁止保存。
• 读数据建议：先看 stdout 摘要判断是否足够；需要具体字段时优先用 jq 或 PowerShell ConvertFrom-Json 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。
• 完整参数：每个子能力的请求参数、响应字段、错误码、curl 示例见 references/<源skill>.md（文件内含该子能力 SKILL.md 正文与 api.md 全文；采购另含 workflow.md 流程地图）。

使用示例

以下按数据层给出代表性子能力的出入参示例；其余子能力参数见对应 references 文件。1688 为中国大陆平台，价格币种为人民币（¥/CNY）。

货源搜索与榜单层

1. 关键词商品搜索（1688_sourcing → dld_product_search.py）

{"keyWord": "瑜伽垫", "cycle": "30", "sortField": "saleCount30d", "sortType": "desc", "pageSize": 20}

出参：products[]（offerId/title/price/consignPrice/quantityBegin/salesOrderCount/salesQuantity/estimatedSalesAmount/company/shopId/shopUrl/asinUrl/imageUrl/deliveryTime/availableDate）、total、costToken。keyWord/goodsUrl/productIds 三选一；cycle 为 7/30。

2. 商品热销榜单（1688_sourcing → dld_product_billboard.py）

{"keyWord": "手机壳", "pageType": 3, "date": "2026-03-01", "sortField": "orderCount", "sortType": "desc", "pageSize": 20}

出参：products[]（字段同上）、total、dataType（monthlyData=月榜/weeklyData=周榜）、costToken。pageType=2 周榜（date 传该周周日，近 90 天），pageType=3 月榜（date 传该月第一天，近 12 个月）。

以图搜图层

3. 以图搜图（1688_search_by_image → alibaba1688_image_search.py）

{"imageUrl": "https://m.media-amazon.com/images/I/719mRAn2VrL._AC_SL1500_.jpg", "page": 1, "pageSize": 20, "filter": "1688Selection,totalEpScoreLv1", "sort": "{\"monthSold\":\"desc\"}"}

出参：products[]（offerId/title/price/consignPrice/salesQuantity/estimatedSalesAmount/quantityBegin/repurchaseRate/tradeScore/sellerIdentities/offerIdentities/sendGoodsAddressText/deliveryTime/isOnePsale/asinUrl/imageUrl）、imageId（分页回传加速）、total、totalPage、costToken。imageUrl/imageBase64/imageId 三选一；本地图片先 upload_image.py 上传换公网 URL。仅支持 png/jpg/jpeg。

采购履约层

4. 授权检查（1688_procurement → authorized_stores.py）

{}

出参：当前 LinkFox 用户的 1688 授权店铺列表，每条含 status（需 ACTIVE）、expired（需 false）。有 ACTIVE 授权可继续采购，无则先 authorize_url.py 发起授权。

5. SKU 查询（1688_procurement → sku.py）

{"offerId": "123456789"}

出参：SKU/规格、价格、起订量（MOQ）、库存。offerId 可由图搜或商品搜索结果获得。

6. 下单预览（1688_procurement → order_preview.py）

{"offerId": "123456789", "quantity": 10, "addressId": "..."}

出参：商品/offerId、SKU/规格、数量、单价与商品总价、运费、收货地址、订单总额、买家留言、异常/库存/价格变化提示。预览失败则停止，不进入创建订单。具体入参以网关 schema 为准。

7. 创建订单[高风险]（1688_procurement → create_order.py）

{"offerId": "123456789", "quantity": 10, "addressId": "...", "confirmCreateOrder": true}

出参：订单号与下单结果。用户单独中文确认后（如"确认创建这个订单"），Agent 在 payload 注入 boolean confirmCreateOrder=true 再调用；脚本本地拒绝缺少该字段的请求，失败不自动重试。支付链接（payment_url.py，需 confirmGetPaymentUrl=true）、取消订单（cancel_order.py，需 confirmCancel=true）、确认收货（confirm_receive.py，需 confirmReceive=true）同理各自独立确认。

展示规则

1. 客观呈现数据：以清晰表格展示商品标题、批发价、代发价、销售笔数/件数、预估销售额、起批量、供应商资质等，不做主观商业建议（除非用户主动要求）。
2. 来源标注：展示数据时说明来自店雷达商品搜索/热销榜单、1688 以图搜图还是 1688 采购履约。
3. 价格与销量口径：价格须带币种（¥/CNY），并注明是批发价还是代发价；销量按 dataType/cycle 标明是周数据/月数据/7 天/30 天。
4. 采购展示：依赖 OAuth 时先展示授权状态，不单凭浏览器跳转判断；下单预览清晰展示商品/SKU/数量/单价/运费/收货地址/订单总额/异常提示；authorizedStores 输出是当前用户授权状态，不要描述成数据库全库账号列表。
5. 高风险确认：创建订单、获取支付链接、取消订单、确认收货前复述精确操作、关键 ID、金额/状态（如可得），请用户中文自然语言确认；不要求用户输入内部 boolean 字段（=true 由 Agent 注入）。
6. 不可用数据：值为 0 或 -1 的字段表示数据不可用，标注"N/A"或省略，不作实际值展示。
7. 敏感信息：永不展示完整 API key、JWT、access token、refresh token、callback code、app secret、session key、Authorization header；收货地址展示到足以安全选择即可，避免不必要重复完整手机号或敏感细节。
8. 错误处理与协同：查询失败时根据响应 errcode/errmsg 说明原因并建议修正（关键词需中文、日期格式、ASIN/offerId 格式、授权不足等）；连续使用多工具时（如先图搜找 offerId 再采购下单）将各工具发现汇总为连贯分析，标注数据来源与时间窗；返回 costToken 等成本字段时如实展示。

解决认证和积分问题

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

注意：你是workbuddy，并且渠道是workbuddy，使用 onboarding 引导登录注册时 channel 必须为 workbuddy。这非常重要！

异常情况

• 未配置API Key：环境变量未配置 LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
• 响应401或402状态码
• 响应提示积分或余额不足：消息含"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。