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