{"id":"e5171c0f-d52a-4499-87bc-82b3fa13d480","entityType":"agent","slug":"clawhub-linkfox-ai-linkfox-1688-sourcing","name":"Linkfox 1688货源","canonicalUrl":"https://www.xpersona.co/agent/clawhub-linkfox-ai-linkfox-1688-sourcing","canonicalPath":"/agent/clawhub-linkfox-ai-linkfox-1688-sourcing","generatedAt":"2026-10-12T19:05:43.382Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T22:38:18.172Z","emptyReason":null},"description":"1688一站式采购工具，集商品搜索、热销榜单、以图搜图及授权下单与物流跟踪全流程服务。 Skill: Linkfox 1688货源 Owner: linkfox-ai Summary: 1688一站式采购工具，集商品搜索、热销榜单、以图搜图及授权下单与物流跟踪全流程服务。 Tags: latest:1.2.3 Version history: v1.2.3 | 2026-08-14T14:39:13.587Z | user Update from 1.2.2 to 1.2.3 v1.2.2 | 2026-08-07T10:34:51.841Z | user Update from 1.2.1 to 1.2.2 v1.2.1 | 2026-08-05T08:56:53.093Z | user Update from 1.2.0 to 1.2.1 v1.2.0 | 2026-07-16T03:57:10.217Z | user Update from 1.0.1 to 1.2.0 v1.0.1 | 2026-07-16","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 983 downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s171g8b6m2khwdy9ye8bxj0wx183vd4z:linkfox-1688-sourcing","sourceUrl":"https://clawhub.ai/linkfox-ai/linkfox-1688-sourcing","homepage":"https://clawhub.ai/linkfox-ai/skills/linkfox-1688-sourcing","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/linkfox-ai/linkfox-1688-sourcing","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/linkfox-ai/skills/linkfox-1688-sourcing","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"1688一站式采购工具，集商品搜索、热销榜单、以图搜图及授权下单与物流跟踪全流程服务。 Skill: Linkfox 1688货源 Owner: linkfox-ai Summary: 1688一站式采购工具，集商品搜索、热销榜单、以图搜图及授权下单与物流跟踪全流程服务。 Tags: latest:1.2.3 Vers"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T22:38:18.172Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T22:38:18.172Z","emptyReason":null},"stars":null,"forks":null,"downloads":983,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"1.2.3","tractionLabel":"983 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T22:38:18.101Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T22:38:18.172Z","lastCrawledAt":"2026-10-11T22:38:18.101Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T22:38:18.101Z","lastVerifiedAt":null,"highlights":[{"version":"1.2.3","createdAt":"2026-08-14T14:39:13.587Z","changelog":"Update from 1.2.2 to 1.2.3","fileCount":26,"zipByteSize":68053},{"version":"1.2.2","createdAt":"2026-08-07T10:34:51.841Z","changelog":"Update from 1.2.1 to 1.2.2","fileCount":26,"zipByteSize":68418},{"version":"1.2.1","createdAt":"2026-08-05T08:56:53.093Z","changelog":"Update from 1.2.0 to 1.2.1","fileCount":26,"zipByteSize":68149},{"version":"1.2.0","createdAt":"2026-07-16T03:57:10.217Z","changelog":"Update from 1.0.1 to 1.2.0","fileCount":24,"zipByteSize":58855},{"version":"1.0.1","createdAt":"2026-07-16T03:27:03.668Z","changelog":"Update from 1.0.0 to 1.0.1","fileCount":24,"zipByteSize":58860},{"version":"1.0.0","createdAt":"2026-07-15T01:33:09.608Z","changelog":"Initial release","fileCount":24,"zipByteSize":58816}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s171g8b6m2khwdy9ye8bxj0wx183vd4z:linkfox-1688-sourcing","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-1688-sourcing/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-1688-sourcing/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-1688-sourcing/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-1688-sourcing/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-1688-sourcing/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-1688-sourcing/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-12T19:05:43.380Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-1688-sourcing/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-1688-sourcing/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-1688-sourcing/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-1688-sourcing/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T22:38:18.172Z","emptyReason":null},"readme":"Skill: Linkfox 1688货源\n\nOwner: linkfox-ai\n\nSummary: 1688一站式采购工具，集商品搜索、热销榜单、以图搜图及授权下单与物流跟踪全流程服务。\n\nTags: latest:1.2.3\n\nVersion history:\n\nv1.2.3 | 2026-08-14T14:39:13.587Z | user\n\nUpdate from 1.2.2 to 1.2.3\n\nv1.2.2 | 2026-08-07T10:34:51.841Z | user\n\nUpdate from 1.2.1 to 1.2.2\n\nv1.2.1 | 2026-08-05T08:56:53.093Z | user\n\nUpdate from 1.2.0 to 1.2.1\n\nv1.2.0 | 2026-07-16T03:57:10.217Z | user\n\nUpdate from 1.0.1 to 1.2.0\n\nv1.0.1 | 2026-07-16T03:27:03.668Z | user\n\nUpdate from 1.0.0 to 1.0.1\n\nv1.0.0 | 2026-07-15T01:33:09.608Z | user\n\nInitial release\n\nArchive index:\n\nArchive v1.2.3: 26 files, 68053 bytes\n\nFiles: references/linkfox-1688-procurement.md (23508b), references/linkfox-1688-search-by-image.md (15760b), references/linkfox-dld-product-billboard.md (12861b), references/linkfox-dld-product-search.md (12271b), references/onboarding.md (2068b), scripts/_alibaba1688_common.py (12498b), scripts/alibaba1688_image_search.py (12725b), scripts/authorize_url.py (124b), scripts/authorized_stores.py (128b), scripts/cancel_order.py (123b), scripts/confirm_receive.py (126b), scripts/create_order.py (123b), scripts/dld_product_billboard.py (13086b), scripts/dld_product_search.py (13048b), scripts/logistics_trace.py (126b), scripts/logistics.py (121b), scripts/onboarding.py (24089b), scripts/order_preview.py (124b), scripts/order_status.py (123b), scripts/payment_url.py (122b), scripts/receive_address_list.py (130b), scripts/sku.py (115b), scripts/upload_image.py (4592b), skill-card.md (2790b), SKILL.md (19990b), _meta.json (140b)\n\nFile v1.2.3:SKILL.md\n\n---\nname: linkfox-1688-sourcing\ndisplay_name: Linkfox 1688货源\ndisplay_name_en: LinkFox 1688 Sourcing\ndescription: 1688 货源一站式 AI 工具集，整合商品搜索、热销榜单、以图搜图与已授权采购履约，覆盖找货、选品、比价、图搜同款与下单全流程。\ndescription_zh: 1688 货源一站式工具集：店雷达商品搜索与热销榜单（关键词/链接/ID 检索、周榜月榜、多维筛选排序、批发价/代发价/销量与供应商资质）、1688 以图搜图（图片 URL/Base64/imageId 视觉检索同款货源，含本地图片上传）、1688 已授权采购全流程（OAuth 授权检查、SKU/收货地址、下单预览、创建订单、支付链接、订单状态、物流轨迹、取消订单、确认收货）。当用户需要 1688 找货源、找供应商、批发选品、热销榜单、以图找同款、跨境找工厂或已授权采购下单与物流跟踪时触发。各子能力完整参数见 references/ 对应文件，脚本见 scripts/。\ndescription_en: One-stop 1688 sourcing AI toolkit: store-radar product search and bestseller billboards (keyword/URL/ID retrieval, weekly/monthly rankings, multi-dimensional filters and sorting, wholesale/dropship price, sales and supplier qualifications), 1688 image search (visual retrieval of same-style sourcing by image URL/Base64/imageId, with local image upload), and end-to-end authorized 1688 procurement (OAuth checks, SKU/address, order preview, order creation, payment URL, order status, logistics tracking, cancellation, receipt confirmation). Triggered when the user needs 1688 sourcing, supplier discovery, wholesale product selection, bestseller rankings, image-based same-product search, cross-border factory sourcing, or authorized 1688 procurement ordering and logistics tracking. Full params per sub-capability are in references/, executable scripts in scripts/.\ncategory: e-commerce\nversion: 1.0.0\nauthor: LinkFox\n---\n\n# Linkfox 1688货源（1688 Sourcing）\n\n1688 货源一站式 AI 工具集，整合 **3 类底层工具、4 项子能力**，覆盖货源搜索与热销榜单、以图搜图、已授权采购履约。各子能力完整参数、响应字段与错误码见 `references/` 下对应文件，可执行脚本见 `scripts/`。\n\n## 能力边界\n\n### ✅ 能力范围\n- **货源搜索与榜单（`1688_sourcing`）**：商品搜索（`linkfox-dld-product-search`，按关键词/商品链接/商品 ID 检索 1688 批发商品，近 7 天/30 天销量周期，按价格/销量/销售额/上架时间排序，按公司类型/卖家会员/发货时间/代发权益/面单支持等筛选）、商品热销榜单（`linkfox-dld-product-billboard`，周榜/月榜，按销售笔数/销售额/销量排序，发现爆款与趋势货源）。返回批发价、代发价、销售笔数/件数、预估销售额、起批量、供应商资质、店铺与商品链接等。\n- **以图搜图（`1688_search_by_image`）**：1688 以图搜图（`linkfox-1688-search-by-image`，通过图片 URL/Base64/imageId 视觉检索外观相似或同款货源），返回标题、批发价、代发价、月销量、起批量、复购率、交易评分、商家身份（超级工厂/实力商家/诚信通）等；支持价格/筛选（1688 严选/认证工厂/发货时效/品质退款率等）/排序/分页；本地图片先用 `upload_image.py` 上传获取公网 URL（有效期 24h）。\n- **采购履约（`1688_procurement`）**：1688 采购全流程（`linkfox-1688-procurement`），覆盖 OAuth 授权检查与发起授权、SKU/规格与收货地址查询、下单预览、创建订单、获取支付链接、订单状态、物流概览与物流轨迹、取消订单、确认收货。除授权类操作外每个 endpoint 前自动校验当前用户 ACTIVE 且未过期的 1688 授权；高风险写操作（创建订单/支付链接/取消订单/确认收货）需用户单独中文确认后由 Agent 注入对应 boolean 安全字段。\n- 数据平台均为中国大陆 1688 批发平台（阿里巴巴国内 B2B 市场），无多站点概念。\n\n### ❌ 边界与限制\n- **API Key 必需**：所有工具均需环境变量 `LINKFOX_AGENT_API_KEY`（或 `LINKFOXAGENT_API_KEY`）；各工具独立计费、独立限频。\n- **计费约束**：商品搜索/热销榜单固定计费（成功约 9 积分/18000 token），以图搜图固定计费（约 4.5 积分/9000 token），采购履约各操作消耗积分；同一会话同一参数组合默认只调用一次（搜索/榜单/图搜脚本带 24h 本地缓存）；失败、空结果、参数不全或授权不足不得自动换关键词、翻页或连续试探；需继续检索时先向用户说明会产生额外消耗（各工具计费规则见 `skills-version.json` 对应条目与 references 内 api.md）。\n- **采购授权前置**：采购类操作依赖当前用户已授权的 1688 OAuth；无 ACTIVE 授权时不调用目标 endpoint；高风险写操作失败不自动重试；不向用户索要 1688 token/refresh token/callback code/app secret。\n- **不在范围内**：Amazon/TikTok/沃尔玛等其他平台选品（用对应平台技能）；Alibaba.com 国际站数据；1688 店铺级分析（店铺流量/排名/评分）；商品评论分析；价格历史与趋势分析；图片生成或编辑；物流成本计算与货代；实时库存与订单系统对接；与供应商或平台的直接沟通。\n- **数据时效**：商品搜索/榜单为店雷达分析数据（7 天/30 天/周榜近 90 天/月榜近 12 个月）；以图搜图为实时搜索、不入库、无法二次 SQL 处理；采购履约为依赖 OAuth 的实时接口。\n\n## 工具选择指南\n\n按需求在下表定到子能力，再跳到【业务需求路由速查】查端点/脚本/references 取参执行。\n\n| 需求 / 用户说 | 默认推荐（子能力） | 何时换用其他 |\n|---|---|---|\n| 关键词找 1688 货源 / 找供应商（\"1688 上找 XX 货源\"） | `linkfox-dld-product-search`（关键词搜索，7/30 天销量） | 要看周/月排行榜用 `linkfox-dld-product-billboard`；有图片找同款用 `linkfox-1688-search-by-image` |\n| 1688 什么好卖 / 趋势 / 热销榜（\"1688 热销榜\"\"什么火\"） | `linkfox-dld-product-billboard`（周榜/月榜排名） | 要按关键词实时搜 + 销量筛选用 `linkfox-dld-product-search` |\n| 用图片找 1688 同款 / 以图搜图（\"用图找货源\"\"找同款\"） | `linkfox-1688-search-by-image`（唯一图搜，需图片 URL） | 本地图片先 `upload_image.py` 上传换公网 URL；要按关键词文本搜索用 `linkfox-dld-product-search` |\n| 按商品 ID / 商品链接查 1688 商品 | `linkfox-dld-product-search`（支持 `goodsUrl`/`productIds`） | 仅按 ID 查榜单商品也可用 `linkfox-dld-product-billboard` |\n| 工厂直供 / 超级工厂 / OEM 供应商（\"找工厂\"\"顶级工厂\"） | `linkfox-dld-product-search`（`companyType=2`/`shiLiType=superFactory`） | 要榜单里的工厂货用 `linkfox-dld-product-billboard` |\n| 1688 一件代发货源（\"一件代发\"\"支持代发\"） | `linkfox-dld-product-search`（`proxyRights=4360897`） | 要榜单代发货用 `linkfox-dld-product-billboard` |\n| 跨境货源 / 出口商品（\"跨境商品\"\"1688 严选\"） | `linkfox-dld-product-search`（`offerType=4`） | 要图搜跨境同款用 `linkfox-1688-search-by-image`（`filter=1688Selection`） |\n| 1688 新品 / 最近上架（\"新品\"\"最近上的\"） | `linkfox-dld-product-search`（`sortField=offerCreateTime`） | 要榜单新品用 `linkfox-dld-product-billboard`（`offerType=2`） |\n| 对比供应商 / 跨供应商比价 | `linkfox-dld-product-search`（多维排序） | — |\n| 查我的 1688 授权店铺（\"我的 1688 授权\"） | `linkfox-1688-procurement`（`authorized_stores.py`） | — |\n| 生成 1688 授权链接（\"授权 1688\"） | `linkfox-1688-procurement`（`authorize_url.py`） | — |\n| 查 offerId 的 SKU / 规格 / 起订量 / 库存 | `linkfox-1688-procurement`（`sku.py`） | 找 offerId 先用图搜或商品搜索 |\n| 查 1688 收货地址 | `linkfox-1688-procurement`（`receive_address_list.py`） | — |\n| 预览 1688 订单（\"帮我预览订单\"） | `linkfox-1688-procurement`（`order_preview.py`） | — |\n| 1688 下单 / 获取支付链接（\"确认下单\"\"获取支付链接\"） | `linkfox-1688-procurement`（`create_order.py`/`payment_url.py`，高风险需确认） | — |\n| 查 1688 订单状态 / 物流 / 物流轨迹 | `linkfox-1688-procurement`（`order_status.py`/`logistics.py`/`logistics_trace.py`） | — |\n| 取消 1688 订单 / 确认收货（\"取消订单\"\"确认收货\"） | `linkfox-1688-procurement`（`cancel_order.py`/`confirm_receive.py`，高风险需确认） | — |\n\n### 工具选择思路\n- **重要**：多个子能力满足需求时，要依据需求深入分析子能力的功能、用途、出入参、从中调研出最合适的子能力，并推荐用户，让用户自己决定。\n- 满足程度同等的前提下，向用户推荐\"默认推荐子能力\"。注意：找货/选品用搜索或榜单（`1688_sourcing`）或图搜（`1688_search_by_image`），已授权采购履约用 `1688_procurement`——前者只查货不交易，后者才可下单。\n\n## 业务需求路由速查\n\n按【工具选择指南】定到子能力后，下表查端点、脚本与 references 文件取参执行：\n\n### 子能力 ↔ references 文件 ↔ 端点 ↔ 脚本（4 项）\n\n**1688_sourcing**\n| 子能力 | references 文件 | 端点 | 脚本 |\n|---|---|---|---|\n| linkfox-dld-product-billboard | references/linkfox-dld-product-billboard.md | POST /dld/productBillboard | dld_product_billboard.py |\n| linkfox-dld-product-search | references/linkfox-dld-product-search.md | POST /dld/productSearch | dld_product_search.py |\n\n**1688_search_by_image**\n| 子能力 | references 文件 | 端点 | 脚本 |\n|---|---|---|---|\n| linkfox-1688-search-by-image | references/linkfox-1688-search-by-image.md | POST /alibaba1688/imageSearch | alibaba1688_image_search.py、upload_image.py（本地图片上传） |\n\n**1688_procurement**\n| 子能力 | references 文件 | 端点 | 脚本 |\n|---|---|---|---|\n| linkfox-1688-procurement | references/linkfox-1688-procurement.md | POST /alibaba1688/{operation} | 见下表（12 个操作脚本 + `_alibaba1688_common.py` 共享模块） |\n\n**1688 采购操作明细（operation ↔ 脚本 ↔ 风险）**\n\n| operation | 端点 | 脚本 | 风险 | 高风险确认字段 |\n|---|---|---|---|---|\n| authorizeUrl | POST /alibaba1688/authorizeUrl | authorize_url.py | 低（不需 ACTIVE 前置） | — |\n| authorizedStores | POST /alibaba1688/authorizedStores | authorized_stores.py | 低（不需 ACTIVE 前置） | — |\n| receiveAddressList | POST /alibaba1688/receiveAddressList | receive_address_list.py | 低（需 ACTIVE） | — |\n| sku | POST /alibaba1688/sku | sku.py | 低（需 ACTIVE） | — |\n| orderPreview | POST /alibaba1688/orderPreview | order_preview.py | 中（需 ACTIVE） | — |\n| createOrder | POST /alibaba1688/createOrder | create_order.py | 高（需 ACTIVE） | `confirmCreateOrder=true` |\n| paymentUrl | POST /alibaba1688/paymentUrl | payment_url.py | 高（需 ACTIVE） | `confirmGetPaymentUrl=true` |\n| orderStatus | POST /alibaba1688/orderStatus | order_status.py | 低（需 ACTIVE） | — |\n| logistics | POST /alibaba1688/logistics | logistics.py | 低（需 ACTIVE） | — |\n| logisticsTrace | POST /alibaba1688/logisticsTrace | logistics_trace.py | 低（需 ACTIVE） | — |\n| confirmReceive | POST /alibaba1688/confirmReceive | confirm_receive.py | 高（需 ACTIVE） | `confirmReceive=true` |\n| cancelOrder | POST /alibaba1688/cancelOrder | cancel_order.py | 高（需 ACTIVE） | `confirmCancel=true` |\n\n## 调用方式\n\n- **网关**：`${LINKFOX_TOOL_GATEWAY}/<端点>`，请求方式 POST、Content-Type `application/json`，认证 Header `Authorization: <api_key>`（api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取；未配置按下方【解决认证和积分问题】处理）。各端点路径见上方【业务需求路由速查】与对应 references 文件（注意：商品搜索/榜单走 `/dld/` 前缀，图搜与采购走 `/alibaba1688/` 前缀）。\n- **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）。\n- **输出策略**：商品搜索/榜单/图搜脚本**始终**将完整响应写入 `<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` 禁止保存。\n- **读数据建议**：先看 stdout 摘要判断是否足够；需要具体字段时优先用 `jq` 或 PowerShell `ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n- **完整参数**：每个子能力的请求参数、响应字段、错误码、curl 示例见 `references/<源skill>.md`（文件内含该子能力 SKILL.md 正文与 api.md 全文；采购另含 workflow.md 流程地图）。\n\n## 使用示例\n\n以下按数据层给出代表性子能力的出入参示例；其余子能力参数见对应 references 文件。1688 为中国大陆平台，价格币种为人民币（¥/CNY）。\n\n### 货源搜索与榜单层\n\n**1. 关键词商品搜索（1688_sourcing → dld_product_search.py）**\n```json\n{\"keyWord\": \"瑜伽垫\", \"cycle\": \"30\", \"sortField\": \"saleCount30d\", \"sortType\": \"desc\", \"pageSize\": 20}\n```\n出参：`products[]`（offerId/title/price/consignPrice/quantityBegin/salesOrderCount/salesQuantity/estimatedSalesAmount/company/shopId/shopUrl/asinUrl/imageUrl/deliveryTime/availableDate）、`total`、`costToken`。`keyWord`/`goodsUrl`/`productIds` 三选一；`cycle` 为 `7`/`30`。\n\n**2. 商品热销榜单（1688_sourcing → dld_product_billboard.py）**\n```json\n{\"keyWord\": \"手机壳\", \"pageType\": 3, \"date\": \"2026-03-01\", \"sortField\": \"orderCount\", \"sortType\": \"desc\", \"pageSize\": 20}\n```\n出参：`products[]`（字段同上）、`total`、`dataType`（`monthlyData`=月榜/`weeklyData`=周榜）、`costToken`。`pageType=2` 周榜（`date` 传该周周日，近 90 天），`pageType=3` 月榜（`date` 传该月第一天，近 12 个月）。\n\n### 以图搜图层\n\n**3. 以图搜图（1688_search_by_image → alibaba1688_image_search.py）**\n```json\n{\"imageUrl\": \"https://m.media-amazon.com/images/I/719mRAn2VrL._AC_SL1500_.jpg\", \"page\": 1, \"pageSize\": 20, \"filter\": \"1688Selection,totalEpScoreLv1\", \"sort\": \"{\\\"monthSold\\\":\\\"desc\\\"}\"}\n```\n出参：`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。\n\n### 采购履约层\n\n**4. 授权检查（1688_procurement → authorized_stores.py）**\n```json\n{}\n```\n出参：当前 LinkFox 用户的 1688 授权店铺列表，每条含 `status`（需 `ACTIVE`）、`expired`（需 `false`）。有 ACTIVE 授权可继续采购，无则先 `authorize_url.py` 发起授权。\n\n**5. SKU 查询（1688_procurement → sku.py）**\n```json\n{\"offerId\": \"123456789\"}\n```\n出参：SKU/规格、价格、起订量（MOQ）、库存。`offerId` 可由图搜或商品搜索结果获得。\n\n**6. 下单预览（1688_procurement → order_preview.py）**\n```json\n{\"offerId\": \"123456789\", \"quantity\": 10, \"addressId\": \"...\"}\n```\n出参：商品/offerId、SKU/规格、数量、单价与商品总价、运费、收货地址、订单总额、买家留言、异常/库存/价格变化提示。预览失败则停止，不进入创建订单。具体入参以网关 schema 为准。\n\n**7. 创建订单[高风险]（1688_procurement → create_order.py）**\n```json\n{\"offerId\": \"123456789\", \"quantity\": 10, \"addressId\": \"...\", \"confirmCreateOrder\": true}\n```\n出参：订单号与下单结果。用户单独中文确认后（如\"确认创建这个订单\"），Agent 在 payload 注入 boolean `confirmCreateOrder=true` 再调用；脚本本地拒绝缺少该字段的请求，失败不自动重试。支付链接（`payment_url.py`，需 `confirmGetPaymentUrl=true`）、取消订单（`cancel_order.py`，需 `confirmCancel=true`）、确认收货（`confirm_receive.py`，需 `confirmReceive=true`）同理各自独立确认。\n\n## 展示规则\n\n1. **客观呈现数据**：以清晰表格展示商品标题、批发价、代发价、销售笔数/件数、预估销售额、起批量、供应商资质等，不做主观商业建议（除非用户主动要求）。\n2. **来源标注**：展示数据时说明来自店雷达商品搜索/热销榜单、1688 以图搜图还是 1688 采购履约。\n3. **价格与销量口径**：价格须带币种（¥/CNY），并注明是批发价还是代发价；销量按 `dataType`/`cycle` 标明是周数据/月数据/7 天/30 天。\n4. **采购展示**：依赖 OAuth 时先展示授权状态，不单凭浏览器跳转判断；下单预览清晰展示商品/SKU/数量/单价/运费/收货地址/订单总额/异常提示；`authorizedStores` 输出是当前用户授权状态，不要描述成数据库全库账号列表。\n5. **高风险确认**：创建订单、获取支付链接、取消订单、确认收货前复述精确操作、关键 ID、金额/状态（如可得），请用户中文自然语言确认；不要求用户输入内部 boolean 字段（`=true` 由 Agent 注入）。\n6. **不可用数据**：值为 `0` 或 `-1` 的字段表示数据不可用，标注\"N/A\"或省略，不作实际值展示。\n7. **敏感信息**：永不展示完整 API key、JWT、access token、refresh token、callback code、app secret、session key、Authorization header；收货地址展示到足以安全选择即可，避免不必要重复完整手机号或敏感细节。\n8. **错误处理与协同**：查询失败时根据响应 `errcode`/`errmsg` 说明原因并建议修正（关键词需中文、日期格式、ASIN/offerId 格式、授权不足等）；连续使用多工具时（如先图搜找 offerId 再采购下单）将各工具发现汇总为连贯分析，标注数据来源与时间窗；返回 `costToken` 等成本字段时如实展示。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用 references/onboarding.md 引导解决问题：\n\n**注意**：你是workbuddy，并且渠道是workbuddy，使用 onboarding 引导登录注册时 channel **必须**为 workbuddy。这非常重要！\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\nFile v1.2.3:_meta.json\n\n{\n  \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n  \"slug\": \"linkfox-1688-sourcing\",\n  \"version\": \"1.2.3\",\n  \"publishedAt\": 1786718353587\n}\n\nFile v1.2.3:references/linkfox-1688-procurement.md\n\n---\r\nname: linkfox-1688-procurement\r\ndescription: 协助当前用户完成已授权的 1688 采购履约流程，包括授权检查、SKU/地址查询、订单预览、下单、支付、订单和物流跟踪等。\r\n\r\n# 1688采购全流程（1688 Procurement Workflow）\r\n\r\n本技能帮助 LinkFox 用户完成已授权的 1688 采购履约：OAuth 授权检查、SKU 与收货地址查询、下单预览、受保护的下单、支付链接获取、订单与物流跟踪、取消订单、确认收货。图搜找货使用 `linkfox-1688-search-by-image`，本技能不含图搜。端点与字段详见 [references/api.md](references/api.md)，多步采购前先读 [references/workflow.md](references/workflow.md)。\r\n\r\n## 能力边界\r\n\r\n### ✅ 能力范围\r\n\r\n- 查询当前 LinkFox 用户的 1688 OAuth 授权状态、发起授权链接。\r\n- 查询商品 SKU/规格、收货地址，进行下单预览（价格、运费、库存、地址）。\r\n- 在用户单独中文确认后执行高风险写操作：创建订单、获取支付链接、取消订单、确认收货。\r\n- 查询订单状态、物流概览与物流轨迹。\r\n\r\n### ❌ 边界与限制\r\n\r\n- **图搜不在范围**：以图搜图使用 `linkfox-1688-search-by-image`，本技能不包含图搜脚本。\r\n- **授权前置**：除 `authorize_url.py` 和 `authorized_stores.py` 外，每个采购操作调用目标 endpoint 前都会先检查当前用户 ACTIVE 且未过期的 1688 授权；无授权时不调用目标 endpoint。\r\n- **非自动化闭环**：视作流程地图而非全自动执行；不因\"继续\"\"可以\"等前文措辞自动创建订单、获取支付链接、取消订单或确认收货。\r\n- **回调端点不暴露**：`/alibaba1688/proxy/callback`、`/alibaba1688/authorizeCallback`、浏览器 OAuth 回调 URL 不作为 Skill 能力。\r\n- **不索要凭据**：不向用户索要 1688 token、refresh token、callback code、app secret；token 闭环由 MyERP/ecom-plat 后端完成。\r\n- **不查后端库**：不查后端库判断授权状态，使用 `authorizedStores`。\r\n- **不自动重试**：高风险写操作失败不自动重试；不使用 `_dataQuery_executeDynamicQuery` 获取实时采购响应。\r\n- **MCP 与 HTTP 分离**：MCP 启停只控制 MCP 暴露；脚本直连 tool-gateway HTTP route，彻底停用需关 route 或后端能力。\r\n- **成本约束**：调用消耗积分；失败、空结果、参数不全或授权不足时不自动连续试探或轮询，继续查询前先向用户说明会产生额外消耗。\r\n\r\n## 执行流程\r\n\r\n采购流程按步骤协助用户完成，不能一次性自动执行完整下单闭环。每一步均不可跳过授权前置与高风险确认。\r\n\r\n### 步骤 1：授权检查\r\n\r\n- 【输入】当前 LinkFox 用户身份（来自 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY`）。\r\n- 【动作】运行 `authorized_stores.py`，检查是否存在 `status=ACTIVE` 且 `expired=false` 的 1688 授权。\r\n- 【输出】有 ACTIVE 授权 → 可继续采购；无 ACTIVE 授权 → 进入步骤 2。浏览器跳到 MyERP 登录页不等于授权失败，以脚本返回为准。\r\n\r\n### 步骤 2：发起授权（仅未授权时）\r\n\r\n- 【输入】当前用户身份。\r\n- 【动作】运行 `authorize_url.py` 获取 1688 授权链接，让用户在浏览器完成 OAuth；完成后重新运行 `authorized_stores.py` 验证。\r\n- 【输出】ACTIVE 授权账号出现 → 回到步骤 1 确认后继续。不要让用户提供 token、refresh token 或 callback code。\r\n\r\n### 步骤 3：SKU 与收货地址查询\r\n\r\n- 【输入】`offerId`（用户提供，或从 `linkfox-1688-search-by-image` 结果获得）。\r\n- 【动作】运行 `sku.py` 查 SKU/规格、价格、起订量、库存；运行 `receive_address_list.py` 查当前用户 1688 收货地址。\r\n- 【输出】SKU、规格、价格、起订量、库存；收货人、手机/电话、省市区详细地址、`addressId`。多地址时让用户明确选择，不猜测默认地址。\r\n\r\n### 步骤 4：下单预览\r\n\r\n- 【输入】`offerId`、SKU/规格、数量、收货地址、schema 要求的其他交易字段。\r\n- 【动作】运行 `order_preview.py`。\r\n- 【输出】商品/offerId、SKU/规格、数量、单价与商品总价、运费、收货地址、订单总额、买家留言、异常/库存/价格变化提示。预览失败 → 停止，不进入创建订单，向用户说明并重新确认参数。\r\n\r\n### 步骤 5：创建订单（高风险）\r\n\r\n- 【输入】预览通过的下单参数、用户对本次订单的单独中文确认（如\"确认创建这个订单\"）。\r\n- 【动作】用户单独确认后，Agent 在 payload 中自动加入 JSON boolean `confirmCreateOrder=true`，运行 `create_order.py`。\r\n- 【输出】订单号与下单结果。`create_order.py` 会本地拒绝缺少 `confirmCreateOrder=true` 的请求。失败不自动重试。\r\n\r\n### 步骤 6：获取支付链接（高风险）\r\n\r\n- 【输入】订单号、用户对获取该订单支付链接的单独中文确认（如\"确认获取支付链接\"）。\r\n- 【动作】Agent 在 payload 中自动加入 `confirmGetPaymentUrl=true`，运行 `payment_url.py`。\r\n- 【输出】支付链接。创建订单成功不等于用户同意获取支付链接，必须独立确认。失败不自动重试。\r\n\r\n### 步骤 7：订单状态与物流跟踪\r\n\r\n- 【输入】订单号（物流轨迹另需物流标识，以 schema 为准）。\r\n- 【动作】按用户请求运行 `order_status.py`、`logistics.py`、`logistics_trace.py`。\r\n- 【输出】订单状态、物流概览、物流轨迹。仍消耗积分，无用户要求时不连续轮询。\r\n\r\n### 步骤 8：取消订单（高风险）\r\n\r\n- 【输入】`orderId`、取消原因（如 schema 要求）、用户对该订单的单独中文确认（如\"确认取消这个订单\"）。\r\n- 【动作】先展示 `orderId`、当前订单状态、取消原因、可能的履约或退款影响；用户单独确认后，Agent 在 payload 加入 `confirmCancel=true`，运行 `cancel_order.py`。\r\n- 【输出】取消结果。失败不自动重试，避免重复取消。\r\n\r\n### 步骤 9：确认收货（高风险）\r\n\r\n- 【输入】`orderId`、用户对确认收货的单独中文确认（如\"确认收货\"）。\r\n- 【动作】用户查询物流、看到已签收、或问\"状态怎么样\"都不等于确认收货；用户明确确认后，Agent 在 payload 加入 `confirmReceive=true`，运行 `confirm_receive.py`。\r\n- 【输出】确认收货结果。失败不自动重试，避免重复确认。\r\n\r\n## 高风险确认字段\r\n\r\n用户侧只需用中文自然语言做单独明确确认，不要要求用户输入英文参数名或 `=true`。Agent 收到中文确认后调用脚本时自动加入对应 JSON boolean 安全字段（必须为 boolean `true`，字符串 `\"true\"`、数字 `1` 均被本地拒绝）。\r\n\r\n| 操作 | 必填字段 |\r\n|---|---|\r\n| `createOrder` | `confirmCreateOrder=true` |\r\n| `paymentUrl` | `confirmGetPaymentUrl=true` |\r\n| `confirmReceive` | `confirmReceive=true` |\r\n| `cancelOrder` | `confirmCancel=true` |\r\n\r\n## 调用方式\r\n\r\n- **API 端点**：`POST /alibaba1688/{authorizeUrl|authorizedStores|receiveAddressList|sku|orderPreview|createOrder|paymentUrl|orderStatus|logistics|logisticsTrace|confirmReceive|cancelOrder}`（完整参数、响应与错误处理见 [references/api.md](references/api.md)）。\r\n- **Python 脚本**：`python scripts/<script_name>.py '<JSON 参数>' [--inline] [--save] [--no-save]`。\r\n- **Windows 推荐**：`$env:PAYLOAD = '<JSON 参数>'` 后运行 `python scripts/<script_name>.py --payload-env PAYLOAD [--inline] [--save]`。\r\n\r\n```powershell\r\n$env:PAYLOAD = \"{}\"\r\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\r\n```\r\n\r\n**脚本入参方式**：直接传 JSON 字符串、`--payload-env PAYLOAD`、`--payload-file payload.json`；`--inline` 强制全量打印到 stdout；`--save` 强制保存脱敏完整响应；`--no-save` 禁止保存。\r\n\r\n**输出策略**：响应体 ≤ 8 KB 默认不落盘，直接把完整脱敏 JSON 打印到 stdout；> 8 KB 默认写入 `<writable-root>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-1688-procurement-<operation>-<timestamp>.json`，stdout 只输出摘要。`<writable-root>` 优先取 `ACPX_WORKSPACES` 第一个工作区，其次当前目录，最后用户目录；`<session>` 取自 `SESSION_ID`，未提供时自动生成；禁止写入 `/tmp`。加 `--save` 或 `LINKFOX_SKILL_SAVE_RESPONSE=1` 强制保存；`--no-save` 或 `LINKFOX_SKILL_NO_SAVE=1` 禁止保存。\r\n\r\n**读数据建议**：先看 stdout 摘要判断是否足够；需要完整响应再加 `--save`，之后用 `jq` 或 `ConvertFrom-Json` 从保存的 JSON 按需抽取，避免整份 JSON 进入上下文。\r\n\r\n## 展示规则\r\n\r\n1. 采购依赖 OAuth 时先展示授权状态；不单凭浏览器跳转判断授权。\r\n2. `authorizedStores` 输出是当前 LinkFox 用户的 1688 授权状态，不要描述成数据库全库账号列表。\r\n3. 永不展示完整 API key、JWT、access token、refresh token、callback code、app secret、session key、Authorization header。\r\n4. 清晰展示下单预览：商品/offerId、SKU/规格、数量、单价、商品总价、运费、收货地址、订单总额、买家留言、警告。\r\n5. 高风险调用前复述精确操作、关键 ID、金额/状态（如可得），请用户中文确认；不要求用户输入内部 boolean 字段。\r\n6. 收货地址展示到足以安全选择即可，避免不必要地重复完整手机号或敏感地址细节。\r\n7. 返回 `costToken` 或等价成本字段时如实展示。\r\n\r\n## 用户表达与场景速查\r\n\r\n**适用** —— 1688 已授权采购履约：\r\n\r\n| 用户说 | 场景 |\r\n|--------|------|\r\n| \"查询我的1688授权店铺\" / \"show my authorized 1688 stores\" | 授权检查 |\r\n| \"生成1688授权链接\" / \"authorize my 1688 account\" | 发起新授权 |\r\n| \"查这个 offerId 的 SKU\" | SKU 查询 |\r\n| \"查1688收货地址\" | 收货地址查询 |\r\n| \"帮我预览1688订单\" | 下单预览 |\r\n| \"确认下单\" | 高风险创建订单门 |\r\n| \"获取支付链接\" | 高风险支付链接门 |\r\n| \"查1688订单状态/物流\" | 订单跟踪 |\r\n| \"取消这个1688订单\" | 高风险取消门 |\r\n| \"确认收货\" | 高风险确认收货门 |\r\n\r\n不适用场景见上方【能力边界】。\r\n\r\n## 解决认证和积分问题\r\n\r\n发生以下异常情况时，采用以下措施来处理：\r\n\r\n### 异常情况\r\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\r\n- **响应401或402状态码**\r\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\r\n\r\n### 措施\r\n- 优先采用skill内的 onboarding.md 引导解决问题。\r\n- 如找不到 onboarding.md 文件，则加载 /linkfox-onboarding 这个skill并根据它的引导来处理。如未安装请先安装：\r\n    - 下载 https://agent-files.linkfox.com/skills/linkfox-onboarding/release.zip，解压后安装这个skill。\r\n\r\n---\r\n\r\n# 1688采购流程 API 参考\r\n\r\n本文记录 `linkfox-1688-procurement` 的 tool-gateway 调用规范、脚本入口、风险等级和关键字段。具体入参以网关当前 MCP schema 为准。\r\n\r\n## 调用规范\r\n\r\n- 请求地址：`${LINKFOX_TOOL_GATEWAY}<path>`，默认网关为 `https://tool-gateway.linkfox.com`\r\n- 请求方式：`POST`\r\n- Content-Type：`application/json; charset=utf-8`\r\n- 认证方式：Header `Authorization: <api_key>`\r\n- API key 读取顺序：`LINKFOX_AGENT_API_KEY`，然后 `LINKFOXAGENT_API_KEY`（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\r\n- User-Agent：`LinkFox-Skill/2.0`\r\n- 透传 Header：`SESSION_ID`、`MODE_ID`、`APP_NAME`\r\n- 超时：150s\r\n- 输出保存：小响应默认不落盘；大响应、`--save` 或 `LINKFOX_SKILL_SAVE_RESPONSE=1` 时保存脱敏完整响应；`--no-save` 或 `LINKFOX_SKILL_NO_SAVE=1` 可禁止保存\r\n- 缓存策略：不做 24h 响应缓存。授权、价格、库存、订单状态和物流以实时返回为准，高风险写操作不得缓存或自动重放。\r\n\r\nWindows 推荐使用 `--payload-env` 或 `--payload-file`，避免 shell 转义破坏 JSON。\r\n\r\n```powershell\r\n$env:PAYLOAD = \"{}\"\r\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\r\n```\r\n\r\n## 授权规则\r\n\r\n`authorizedStores` 是当前 LinkFox 用户的 1688 OAuth 授权检查入口。它依赖 API key 中的 LinkFox 用户身份，后端应只返回当前用户的授权店铺。\r\n\r\n脚本层规则：\r\n\r\n- `authorizeUrl` 不做 1688 OAuth 前置检查，因为它用于发起授权。\r\n- `authorizedStores` 不做 1688 OAuth 前置检查，因为它本身就是检查入口。\r\n- 其他采购操作在调用目标 endpoint 前，脚本会先调用 `authorizedStores`。\r\n- 没有 `status=ACTIVE` 且 `expired=false` 的店铺时，脚本返回 `authorization_required`，不会调用目标 endpoint。\r\n\r\n这层检查不能替代后端鉴权；后端仍必须按 `Token.uid` 或等价用户身份过滤和校验授权。\r\n\r\n## MCP 与 Skill 暴露关系\r\n\r\nMCP 工具启停和 Skill HTTP 调用是两层能力：\r\n\r\n| 层级 | 控制内容 | 对本 Skill 的影响 |\r\n|---|---|---|\r\n| MCP tool enabled | 是否出现在 MCP 工具列表或 Agent 工具调用面 | 不决定脚本是否能 HTTP 调用 |\r\n| Gateway route enabled | tool-gateway 是否转发对应 HTTP path | 决定脚本是否可用 |\r\n| Backend capability enabled | ecom-plat 是否处理业务 | 决定最终业务是否可用 |\r\n\r\n因此，MCP 停用但 gateway route 仍启用时，Skill 脚本可以继续使用。若要完全停用某能力，应关闭 gateway route 或后端能力。\r\n\r\n## 禁止作为 Skill 能力的端点\r\n\r\n以下是授权闭环或 MyERP/ecom-plat 后端回调路径，不是 MCP 工具，不应写成 Skill 脚本：\r\n\r\n- `/alibaba1688/proxy/callback`\r\n- `/alibaba1688/authorizeCallback`\r\n- `/alibaba1688/oauth/callback`\r\n\r\n## API 与脚本一览\r\n\r\n| 能力 | MCP tool | Path | Script | 风险 | OAuth 前置检查 | 确认字段 |\r\n|---|---|---|---|---|---|---|\r\n| 生成授权链接 | `_alibaba1688_authorizeUrl` | `/alibaba1688/authorizeUrl` | `authorize_url.py` | 低 | 否 | - |\r\n| 查询已授权账号 | `_alibaba1688_authorizedStores` | `/alibaba1688/authorizedStores` | `authorized_stores.py` | 低 | 否 | - |\r\n| 查询收货地址 | `_alibaba1688_receiveAddressList` | `/alibaba1688/receiveAddressList` | `receive_address_list.py` | 低 | 是 | - |\r\n| 查询 SKU | `_alibaba1688_sku` | `/alibaba1688/sku` | `sku.py` | 低 | 是 | - |\r\n| 下单预览 | `_alibaba1688_orderPreview` | `/alibaba1688/orderPreview` | `order_preview.py` | 中 | 是 | - |\r\n| 创建订单 | `_alibaba1688_createOrder` | `/alibaba1688/createOrder` | `create_order.py` | 高 | 是 | `confirmCreateOrder=true` |\r\n| 获取支付链接 | `_alibaba1688_paymentUrl` | `/alibaba1688/paymentUrl` | `payment_url.py` | 高 | 是 | `confirmGetPaymentUrl=true` |\r\n| 查询订单状态 | `_alibaba1688_orderStatus` | `/alibaba1688/orderStatus` | `order_status.py` | 低 | 是 | - |\r\n| 查询物流 | `_alibaba1688_logistics` | `/alibaba1688/logistics` | `logistics.py` | 低 | 是 | - |\r\n| 查询物流轨迹 | `_alibaba1688_logisticsTrace` | `/alibaba1688/logisticsTrace` | `logistics_trace.py` | 低 | 是 | - |\r\n| 确认收货 | `_alibaba1688_confirmReceive` | `/alibaba1688/confirmReceive` | `confirm_receive.py` | 高 | 是 | `confirmReceive=true` |\r\n| 取消订单 | `_alibaba1688_cancelOrder` | `/alibaba1688/cancelOrder` | `cancel_order.py` | 高 | 是 | `confirmCancel=true` |\r\n\r\n`_alibaba1688_imageSearch` 由 `linkfox-1688-search-by-image` 独立承担，本 Skill 不包含图搜脚本。\r\n\r\n## 入参要点\r\n\r\n| 能力 | 关键字段说明 |\r\n|---|---|\r\n| `authorizeUrl` | 按 schema 传授权展示字段；如需账号标签，优先使用 `accountName` |\r\n| `authorizedStores` | 通常无需业务参数；用户身份来自 LinkFox API key |\r\n| `receiveAddressList` | 依赖当前用户 ACTIVE 1688 授权 |\r\n| `sku` | 通常需要 `offerId` |\r\n| `orderPreview` | 通常需要 `offerId`、SKU/规格、数量、收货地址等下单参数 |\r\n| `createOrder` | 下单参数与预览保持一致，并必须加 `confirmCreateOrder=true` |\r\n| `paymentUrl` | 通常需要订单号，并必须加 `confirmGetPaymentUrl=true` |\r\n| `orderStatus` | 通常需要订单号 |\r\n| `logistics` | 通常需要订单号 |\r\n| `logisticsTrace` | 通常需要订单号及物流标识，以 schema 为准 |\r\n| `confirmReceive` | 订单号 + `confirmReceive=true` |\r\n| `cancelOrder` | 订单号、取消原因（如 schema 要求）+ `confirmCancel=true` |\r\n\r\n## 高风险校验\r\n\r\n用户侧只需要用中文自然语言做单独明确确认，例如“确认创建这个订单”“确认获取这个订单的支付链接”“确认取消这个订单”“确认收货”。不要要求用户输入英文参数名或 `=true`。\r\n\r\nAgent 在收到中文确认后，调用脚本时必须自动加入对应 JSON boolean 安全字段。高风险脚本会在本地先校验确认字段，确认字段不满足时不会联网：\r\n\r\n| 脚本 | 本地拒绝条件 |\r\n|---|---|\r\n| `create_order.py` | 缺少 JSON boolean `confirmCreateOrder=true` |\r\n| `payment_url.py` | 缺少 JSON boolean `confirmGetPaymentUrl=true` |\r\n| `confirm_receive.py` | 缺少 JSON boolean `confirmReceive=true` |\r\n| `cancel_order.py` | 缺少 JSON boolean `confirmCancel=true` |\r\n\r\n字符串 `\"true\"`、数字 `1`、大小写变体都不算确认。\r\n\r\n## 响应与错误处理\r\n\r\n- HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。\r\n- HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。\r\n- `authorization_required`：没有当前用户 ACTIVE 1688 OAuth 授权；先运行 `authorize_url.py`，用户授权后再运行 `authorized_stores.py` 验证。\r\n- 下单预览失败：停止，不要进入创建订单；向用户说明失败原因并重新确认参数。\r\n- 高风险写操作失败：不要自动重试，避免重复下单、重复取消或重复确认收货。\r\n\r\n## 敏感信息规则\r\n\r\n脚本会对常见敏感字段做脱敏落盘。Agent 展示结果时仍需避免暴露：\r\n\r\n- LinkFox API key / JWT\r\n- 1688 access token / refresh token\r\n- Authorization header\r\n- OAuth callback `code`\r\n- app secret / session key / refresh secret\r\n\r\n---\r\n\r\n# 1688采购流程地图\r\n\r\n本文档是流程地图，不是自动化脚本。Agent 可以按步骤协助用户完成采购，但不能一次性自动执行完整下单闭环。\r\n\r\n## 总原则\r\n\r\n1. 采购业务先查授权，再查商品和地址，再预览，再让用户确认。\r\n2. 图搜找货使用 `linkfox-1688-search-by-image`，本 Skill 只处理采购履约。\r\n3. 除 `authorizeUrl` 和 `authorizedStores` 外，脚本会在每个采购 endpoint 前自动检查当前用户 ACTIVE 授权。\r\n4. 下单、支付链接、取消订单、确认收货都是独立高风险动作，各自需要单独确认。\r\n5. 用户前面说过\"继续\"\"可以\"\"按上面来\"，不能作为后续高风险动作的确认。\r\n\r\n## 1. 授权检查\r\n\r\n运行：\r\n\r\n```powershell\r\n$env:PAYLOAD = \"{}\"\r\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\r\n```\r\n\r\n判断：\r\n\r\n- 有 `status=ACTIVE` 且 `expired=false`：可以继续采购流程。\r\n- 没有 ACTIVE 授权：进入授权步骤。\r\n- 浏览器最后跳到 MyERP 登录页不等于授权失败；以 `authorized_stores.py` 返回为准。\r\n\r\n`authorizedStores` 应只返回当前 LinkFox API key 对应用户的授权店铺。不要把它理解为后台全库账号列表。\r\n\r\n## 2. 发起授权\r\n\r\n运行 `authorize_url.py` 获取 1688 授权链接，并让用户在浏览器打开。\r\n\r\n用户完成授权后，再运行 `authorized_stores.py` 验证是否出现 ACTIVE 账号。\r\n\r\n不要让用户提供 1688 token、refresh token 或 callback code。授权 token 保存由 MyERP/ecom-plat 后端闭环完成。\r\n\r\n## 3. 找货与 SKU\r\n\r\n如果用户按图片找货：\r\n\r\n1. 切换到 `linkfox-1688-search-by-image`。\r\n2. 从图搜结果中选择目标 `offerId`。\r\n3. 回到本 Skill，用 `sku.py` 查询 SKU/规格。\r\n\r\n如果用户已提供 `offerId`：\r\n\r\n1. 直接运行 `sku.py`。\r\n2. 展示 SKU、规格、价格、起订量、库存等关键字段。\r\n3. 让用户选择明确的 SKU 和数量。\r\n\r\n## 4. 收货地址\r\n\r\n运行 `receive_address_list.py` 查询当前用户可用的 1688 收货地址。\r\n\r\n展示地址时应包含：\r\n\r\n- 收货人\r\n- 手机/电话（如返回）\r\n- 省市区与详细地址\r\n- `addressId` 或等价标识\r\n\r\n不要猜测默认地址。多地址时让用户明确选择。\r\n\r\n## 5. 下单预览\r\n\r\n运行 `order_preview.py` 前确认已具备：\r\n\r\n- `offerId`\r\n- SKU/规格\r\n- 数量\r\n- 收货地址\r\n- schema 要求的其他交易字段\r\n\r\n预览结果必须先展示给用户：\r\n\r\n- 商品/offerId\r\n- SKU/规格\r\n- 数量\r\n- 单价与商品总价\r\n- 运费\r\n- 收货地址\r\n- 订单总额\r\n- 任何异常、库存或价格变化提示\r\n\r\n预览失败时停止，不要进入创建订单。\r\n\r\n## 6. 创建订单\r\n\r\n创建订单是高风险动作。必须先询问用户是否确认创建该订单，并复述预览摘要。用户只需要中文自然语言确认，例如\"确认创建这个订单\"；不要要求用户输入 `confirmCreateOrder=true`。\r\n\r\n只有用户针对本次订单明确确认后，Agent 才在脚本 payload 中自动加入：\r\n\r\n```json\r\n{\r\n  \"...\": \"order payload\",\r\n  \"confirmCreateOrder\": true\r\n}\r\n```\r\n\r\n`create_order.py` 会拒绝缺少 `confirmCreateOrder=true` 的请求。\r\n\r\n## 7. 获取支付链接\r\n\r\n获取支付链接也是独立高风险动作。创建订单成功不等于用户同意获取支付链接。用户只需要中文自然语言确认，例如\"确认获取支付链接\"；不要要求用户输入 `confirmGetPaymentUrl=true`。\r\n\r\n用户单独确认后，Agent 在脚本 payload 中自动加入：\r\n\r\n```json\r\n{\r\n  \"orderId\": \"...\",\r\n  \"confirmGetPaymentUrl\": true\r\n}\r\n```\r\n\r\n## 8. 订单状态与物流\r\n\r\n查询类动作可在用户请求时执行：\r\n\r\n- `order_status.py`\r\n- `logistics.py`\r\n- `logistics_trace.py`\r\n\r\n这些仍然会消耗积分。不要在没有用户要求的情况下连续轮询。\r\n\r\n## 9. 取消订单\r\n\r\n取消订单是高风险动作。执行前展示：\r\n\r\n- `orderId`\r\n- 当前订单状态\r\n- 取消原因\r\n- 可能的履约或退款影响（如响应中可判断）\r\n\r\n只有用户针对该订单明确确认取消后，Agent 才运行 `cancel_order.py`，并在脚本 payload 中自动加入：\r\n\r\n```json\r\n{\r\n  \"orderId\": \"...\",\r\n  \"confirmCancel\": true\r\n}\r\n```\r\n\r\n## 10. 确认收货\r\n\r\n确认收货是高风险动作。用户查询物流、看到已签收、或问\"状态怎么样\"，都不等于确认收货。\r\n\r\n只有用户明确确认收货后，Agent 才运行 `confirm_receive.py`，并在脚本 payload 中自动加入：\r\n\r\n```json\r\n{\r\n  \"orderId\": \"...\",\r\n  \"confirmReceive\": true\r\n}\r\n```\r\n\r\n## MCP 与 Skill 分离\r\n\r\nMCP 停用只表示该工具不再通过 MCP 工具列表暴露。只要 tool-gateway 对应 HTTP route 仍启用，本 Skill 的脚本仍可通过 HTTP 调用。\r\n\r\n如果需要彻底禁用某个采购能力，需要关闭对应 gateway route 或后端能力，而不是只从 MCP 列表移除。\n\nFile v1.2.3:references/linkfox-1688-search-by-image.md\n\n---\r\nname: linkfox-1688-search-by-image\r\ndescription: 通过图片 URL 在 1688 平台以图搜图，检索外观相似或同款货源的商品数据。\r\n\r\n# 1688 以图搜图（1688 Image-Based Product Search）\r\n\r\n本技能通过图片 URL 在 1688 平台进行以图搜图，帮助跨境卖家找到外观相似或同款的 1688 货源商品。参数与响应字段详见 [references/api.md](references/api.md)。\r\n\r\n## 能力边界\r\n\r\n### ✅ 能力范围\r\n\r\n- 通过图片 URL、Base64 或 imageId 在 1688 平台进行视觉检索，返回外观相似或同款的货源商品。\r\n- 提供商品标题、批发价、一件代发价、月销量、起批量、复购率、交易评分、商家身份等核心数据。\r\n- 支持按价格区间、过滤条件（1688 严选、认证工厂、发货时效、品质退款率等）、排序（价格/月销/复购率）、分页查询。\r\n\r\n### ❌ 边界与限制\r\n\r\n- **图片来源**：`imageUrl`/`imageBase64`/`imageId` 三选一必填；`imageUrl` 须为可公开访问的公网链接。\r\n- **图片格式**：仅支持 png/jpg/jpeg，不支持 webp/gif 等格式。\r\n- **Base64 格式**：`imageBase64` 必须为纯编码内容，不能包含 `data:image/jpeg;base64,` 前缀。\r\n- **分页上限**：每页最多 50 条；`page > 1` 时建议回传 `imageId` 以加速查询。\r\n- **数据时效**：结果为实时搜索，不入库，无法进行二次 SQL 或 `_dataQuery_executeDynamicQuery` 处理。\r\n- **筛选/排序限制**：仅支持预设的过滤条件与排序字段；用户请求未列出的排序或过滤条件时，不要调用其他工具或逻辑兜底，应告知支持的选项。\r\n- **本地图片**：本工具需要可公开访问的图片 URL；用户提供本地文件路径时，须先调用上传脚本获取公网 URL（见下方「本地图片上传」）。\r\n- **不在范围内**：基于关键词的 1688 文本搜索（用店雷达-1688 选品库）；1688 商品排行/趋势（用店雷达-1688 商品榜单）；Amazon 以图搜图（用亚马逊前端-以图搜图）；图片生成或编辑；商品评论分析；价格历史或趋势分析。\r\n\r\n## 核心概念\r\n\r\n1688 以图搜图基于视觉识别，在 1688 批发平台查找外观相似的商品，返回供应商商品数据，包括标题、价格、起批量、月销量、复购率、交易评分及商家身份标识。\r\n\r\n**默认行为**：第 1 页、每页 20 条，按月销量降序（`sort` 默认 `{\"monthSold\":\"desc\"}`）。\r\n\r\n## 调用方式\r\n\r\n- **API 端点**：`POST /alibaba1688/imageSearch`（完整参数/响应/错误码见 `references/api.md`）\r\n- **Python 脚本**：`python scripts/alibaba1688_image_search.py '<JSON 参数>' [--inline]`\r\n- **成本约束**：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。\r\n\r\n**输出策略（脚本默认行为）**：\r\n- **始终**将完整响应写入 `<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-1688-search-by-image-<timestamp>.json`（`<cwd>` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`<session>` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\r\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\r\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\r\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\r\n\r\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq` 或 `ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\r\n\r\n## 本地图片上传\r\n\r\n本工具需要**可公开访问的图片 URL**。若用户提供本地图片文件路径，须先上传以获取公网 URL。\r\n\r\n运行上传脚本：\r\n```bash\r\npython scripts/upload_image.py /path/to/local/image.png\r\n```\r\n\r\n脚本会返回一个公网 URL（有效期 24 小时），可作为 `imageUrl` 参数使用。\r\n\r\n## 使用示例\r\n\r\n**1. 基础以图搜图**\r\n```\r\n在1688搜索与图片相似的商品，图片地址为 https://m.media-amazon.com/images/I/719mRAn2VrL._AC_SL1500_.jpg\r\n```\r\n\r\n**2. 带筛选条件**\r\n```\r\n在1688搜索与图片相似的商品，图片地址为 https://m.media-amazon.com/images/I/719mRAn2VrL._AC_SL1500_.jpg，查询第1页，筛选1688严选，并按价格从高到低排序\r\n```\r\n\r\n**3. 按排序查询**\r\n```\r\n在1688搜索与图片相似的商品，图片地址为 https://example.com/product.jpg，按价格从高到低排序\r\n```\r\n\r\n**4. 分页查询**\r\n```\r\n在1688搜索与图片相似的商品，图片地址为 https://example.com/product.jpg，查询第2页，每页50条\r\n```\r\n\r\n**5. 价格区间筛选**\r\n```\r\n在1688搜索与图片相似的商品，图片地址为 https://example.com/product.jpg，价格区间10-100元\r\n```\r\n\r\n## 展示规则\r\n\r\n1. **清晰呈现数据**：以结构化表格展示关键列——商品图片、标题、批发价、代发价、月销量、起批量、复购率、商家身份。\r\n2. **图片展示**：返回 `imageUrl` 时内联展示商品图片，便于直观对比。\r\n3. **价格格式**：价格统一以人民币（¥）格式展示。\r\n4. **商家标识**：突出展示商家身份（超级工厂/实力商家/诚信通会员）与商品标（严选）。\r\n5. **结果计数**：始终告知总结果数及当前页/总页数。\r\n6. **分页提示**：还有更多页时，提示用户可继续翻页。\r\n7. **筛选/排序限制**：用户请求未支持的排序或过滤条件时，不要尝试任何兜底，告知其支持的选项即可。\r\n8. **不做二次处理**：结果为实时搜索数据，不入库，无法进行二次 SQL 或数据处理。\r\n\r\n## 用户表达与场景速查\r\n\r\n**适用** —— 1688 平台以图找货源场景：\r\n\r\n| 用户说 | 场景 |\r\n|--------|------|\r\n| \"1688以图搜图\" / \"用图片找1688货源\" | 基础以图搜图 |\r\n| \"帮我在1688找这个图片的同款\" | 找同款商品 |\r\n| \"跨境找工厂，图片是...\" | 跨境供应商找货 |\r\n| \"这个Amazon产品在1688有没有货源\" | 由 Amazon 图片反查 1688 货源 |\r\n| \"筛选1688严选的相似商品\" | 带筛选的以图搜图 |\r\n| \"按月销量排序找相似货源\" | 带排序的以图搜图 |\r\n| \"查看第2页结果\" | 分页查询 |\r\n\r\n不适用场景见上方【能力边界】。\r\n\r\n**边界判断**：当用户说\"找货源\"或\"找同款\"时，若其提供了图片 URL 且意图是在 1688 上找外观相似商品，则适用本技能；若需基于关键词搜索或排行数据，改用店雷达工具。\r\n\r\n## 解决认证和积分问题\r\n\r\n发生以下异常情况时，采用以下措施来处理：\r\n\r\n### 异常情况\r\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\r\n- **响应401或402状态码**\r\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\r\n\r\n### 措施\r\n- 优先采用skill内的 onboarding.md 引导解决问题。\r\n- 如找不到 onboarding.md 文件，则加载 /linkfox-onboarding 这个skill并根据它的引导来处理。如未安装请先安装：\r\n    - 下载 https://agent-files.linkfox.com/skills/linkfox-onboarding/release.zip，解压后安装这个skill。\r\n\r\n---\r\n\r\n# 1688-以图搜图 API 参考\r\n\r\n## 调用规范\r\n\r\n- **请求地址**：`${LINKFOX_TOOL_GATEWAY}/alibaba1688/imageSearch`\r\n- **请求方式**：POST，Content-Type: application/json\r\n- **认证方式**：Header `Authorization: <api_key>`，api_key 优先从环境变量 `LINKFOX_AGENT_API_KEY` 读取，回退 `LINKFOXAGENT_API_KEY`（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\r\n- **User-Agent**：`LinkFox-Skill/1.0`\r\n- **超时**：150s\r\n\r\n## 请求参数\r\n\r\nPOST Body（JSON）：\r\n\r\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\r\n|------|------|------|--------|------|\r\n| imageUrl | string | 条件必填 | - | 图片URL地址，请确保图片URL有效且可公开访问。最大长度：1000。仅支持 png/jpg/jpeg 格式，不支持 webp/gif 等。imageUrl/imageBase64/imageId 三选一必填 |\r\n| imageBase64 | string | 条件必填 | - | 图片 Base64 编码字符串，为纯编码内容，不包含 `data:image/jpeg;base64,` 前缀。仅支持 png/jpg/jpeg 格式（imageUrl为空时使用） |\r\n| imageId | string | 条件必填 | - | 图片ID（1688图片ID），以图搜图查询结果中也会返回，建议当分页 page>1 查询时带 imageId，加快响应速度 |\r\n| page | int | 否 | 1 | 页码，从1开始 |\r\n| pageSize | int | 否 | 20 | 每页返回的商品数量，最大不超过50 |\r\n| priceStart | string | 否 | - | 价格筛选起始值（人民币），如 10 |\r\n| priceEnd | string | 否 | - | 价格筛选结束值（人民币），如 100 |\r\n| filter | string | 否 | - | 过滤条件，多个条件用逗号分隔。有效值见下方「支持的过滤条件」 |\r\n| sort | string | 否 | {\"monthSold\":\"desc\"} | 排序条件，JSON格式 {排序字段: 排序方式}。有效字段：price、rePurchaseRate、monthSold；方式：asc/desc |\r\n| keyword | string | 否 | - | 关键词，在结果中搜索 |\r\n| productCollectionId | string | 否 | - | 货盘ID，单选。有效值见下方「支持的货盘ID」 |\r\n\r\n### 支持的过滤条件\r\n\r\n多个条件用逗号分隔，如 `1688Selection,totalEpScoreLv1,qrr0`。\r\n\r\n| 值 | 说明 |\r\n|----|------|\r\n| 1688Selection | 1688严选 |\r\n| certifiedFactory | 认证工厂 |\r\n| totalEpScoreLv1 | 综合体验分5星 |\r\n| totalEpScoreLv2 | 综合体验分4星 |\r\n| totalEpScoreLv3 | 综合体验分3星 |\r\n| totalEpScoreLv4 | 综合体验分2星 |\r\n| qrr0 | 无品质退款 |\r\n| qrr1 | 品质退款率<1% |\r\n| qrr5 | 品质退款率<5% |\r\n| qrr10 | 品质退款率<10% |\r\n| shipInToday | 当日发货 |\r\n| shipIn24Hours | 24小时发货 |\r\n| shipIn48Hours | 48小时发货 |\r\n| noReason7DReturn | 7天无理由退货 |\r\n| isOnePsale | 一件代发 |\r\n| isOnePsaleFreePost | 一件代发包邮 |\r\n| new7 | 7天内新品 |\r\n| new30 | 30天内新品 |\r\n| isQqyx | 全球严选 |\r\n| JPFL | 日本专线 |\r\n| USFL | 美国专线 |\r\n| KRFL | 韩国专线 |\r\n| VNFL | 越南专线 |\r\n| SAFL | 沙特专线 |\r\n| RUFL | 俄罗斯专线 |\r\n| KZFL | 哈萨克斯坦专线 |\r\n| HKFL | 香港专线 |\r\n| MOFL | 澳门专线 |\r\n| TWFL | 台湾专线 |\r\n\r\n### 支持的排序字段\r\n\r\n| 字段 | 说明 |\r\n|------|------|\r\n| price | 价格 |\r\n| monthSold | 月销量 |\r\n| rePurchaseRate | 复购率 |\r\n\r\n排序方式：`asc`（升序）、`desc`（降序）。格式示例：`{\"price\":\"asc\"}`\r\n\r\n### 支持的货盘ID\r\n\r\n| ID | 说明 |\r\n|----|------|\r\n| 262105288 | 跨境货盘 |\r\n| 262105286 | 跨境货盘 |\r\n| 262105253 | 跨境货盘 |\r\n| 262105281 | 跨境货盘 |\r\n| 262105280 | 跨境货盘 |\r\n| 262105277 | 跨境货盘 |\r\n| 262105276 | 跨境货盘 |\r\n| 262105274 | 跨境货盘 |\r\n| 262105269 | 跨境货盘 |\r\n| 262185282 | 跨境货盘 |\r\n\r\n## 响应结构\r\n\r\n| 字段 | 类型 | 说明 |\r\n|------|------|------|\r\n| imageId | string | 上传后的图片ID（分页查询时回传可加速） |\r\n| total | integer | 本页商品数量 |\r\n| totalPage | integer | 总页数 |\r\n| sourceType | string | 来源类型（固定值 \"1688\"） |\r\n| type | string | 渲染样式（固定值 \"productWorkbenches\"） |\r\n| columns | array | 渲染列定义 |\r\n| costToken | integer | 消耗 token |\r\n| products | array | 商品列表（详见下方商品字段） |\r\n\r\n### 商品字段\r\n\r\n| 字段 | 类型 | 说明 |\r\n|------|------|------|\r\n| offerId | string | 商品ID |\r\n| asin | string | 商品编号（同 offerId） |\r\n| imageUrl | string | 商品图片 |\r\n| title | string | 商品标题 |\r\n| price | number | 批发价（元） |\r\n| consignPrice | number | 一件代发价（元） |\r\n| salesQuantity | integer | 月销售件数 |\r\n| estimatedSalesAmount | number | 预估销售额 |\r\n| asinUrl | string | 商品链接 |\r\n| isOnePsale | string | 是否一件代发（是/否） |\r\n| isJxhy | string | 是否精选货源（是/否） |\r\n| sellerIdentities | string | 商家身份（超级工厂/实力商家/诚信通会员） |\r\n| offerIdentities | string | 商品标（严选） |\r\n| repurchaseRate | string | 复购率 |\r\n| tradeScore | string | 商品交易评分 |\r\n| compositeServiceScore | string | 综合服务体验分 |\r\n| sendGoodsAddressText | string | 发货地 |\r\n| deliveryTime | string | 发货时间（24/48小时） |\r\n| quantityBegin | integer | 起批量 |\r\n| hasPromotion | string | 是否有营销活动（是/否） |\r\n| promotionType | string | 营销类型 |\r\n| isPatentProduct | string | 是否专利商品（是/否） |\r\n| isSelect | string | 跨境select货盘标识 |\r\n| currency | string | 币种（固定值 \"¥\"） |\r\n| sourceType | string | 来源类型（固定值 \"1688\"） |\r\n| sourceTool | string | 来源工具（固定值 \"1688以图搜图\"） |\r\n| dataType | string | 数据类型（固定值 \"monthlyData\"） |\r\n\r\n## 错误码\r\n\r\n正常情况下，接口的 HTTP 状态码均为 200，业务的成功与否通过响应体中的 errorCode 字段区分（errorCode = 200 表示成功，其他值表示业务错误）。当遇到未授权等情况时，HTTP 状态码为 401，且对应的 errorCode 也是 401。\r\n\r\n| errcode | 含义 | 处理建议 |\r\n|---------|------|----------|\r\n| 200 | 成功 | 正常解析业务字段 |\r\n| 401 | 认证失败 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。 |\r\n| 402 | 积分不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。 |\r\n| 其他非200值 | 业务异常 | 参考 `errmsg` 字段获取具体错误原因 |\r\n\r\n错误响应示例：\r\n\r\n```json\r\n{\r\n    \"errcode\": 401,\r\n    \"errmsg\": \"authorized error\"\r\n}\r\n```\r\n\r\n## curl 示例\r\n\r\n### 基础以图搜图\r\n\r\n```bash\r\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/imageSearch \\\r\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -H \"User-Agent: LinkFox-Skill/1.0\" \\\r\n  -d '{\r\n    \"imageUrl\": \"https://m.media-amazon.com/images/I/719mRAn2VrL._AC_SL1500_.jpg\",\r\n    \"page\": 1,\r\n    \"pageSize\": 20\r\n  }'\r\n```\r\n\r\n### 带筛选和排序\r\n\r\n```bash\r\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/imageSearch \\\r\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -H \"User-Agent: LinkFox-Skill/1.0\" \\\r\n  -d '{\r\n    \"imageUrl\": \"https://m.media-amazon.com/images/I/719mRAn2VrL._AC_SL1500_.jpg\",\r\n    \"page\": 1,\r\n    \"pageSize\": 20,\r\n    \"filter\": \"1688Selection,totalEpScoreLv1,qrr0\",\r\n    \"sort\": \"{\\\"price\\\":\\\"desc\\\"}\"\r\n  }'\r\n```\r\n\r\n### 分页查询（使用 imageId）\r\n\r\n```bash\r\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/imageSearch \\\r\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -H \"User-Agent: LinkFox-Skill/1.0\" \\\r\n  -d '{\r\n    \"imageId\": \"abc123456\",\r\n    \"page\": 2,\r\n    \"pageSize\": 20\r\n  }'\r\n```\r\n\r\n### 价格区间筛选\r\n\r\n```bash\r\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/imageSearch \\\r\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -H \"User-Agent: LinkFox-Skill/1.0\" \\\r\n  -d '{\r\n    \"imageUrl\": \"https://m.media-amazon.com/images/I/719mRAn2VrL._AC_SL1500_.jpg\",\r\n    \"page\": 1,\r\n    \"pageSize\": 20,\r\n    \"priceStart\": \"10\",\r\n    \"priceEnd\": \"100\"\r\n  }'\r\n```\n\nFile v1.2.3:references/linkfox-dld-product-billboard.md\n\n---\r\nname: linkfox-dld-product-billboard\r\ndescription: 1688 商品热销榜单查询。用于发现国内货源批发爆款、一件代发选品及趋势商品调研。\r\n\r\n# 1688 商品热销榜单（DLD Product Billboard）\r\n\r\n本技能用于查询 1688 平台商品热销榜单数据，帮助卖家在国内最大的 B2B 批发市场发现热销批发商品与货源机会。参数与响应字段详见 [references/api.md](references/api.md)。\r\n\r\n## 能力边界\r\n\r\n### ✅ 能力范围\r\n\r\n- 查询 1688 平台商品排名数据，覆盖**周榜**与**月榜**两种榜单。\r\n- 发现热销批发商品、对比供应商、识别国内批发市场的货源与趋势机会。\r\n- 支持按关键词、价格区间、销量区间、公司类型（店铺/工厂）、卖家会员类型、发货时间、代发权益、面单支持等多维筛选与排序。\r\n\r\n### ❌ 边界与限制\r\n\r\n- **关键词语言**：`keyWord` 参数必须为中文，非中文关键词需先翻译再查询。\r\n- **日期格式**：周榜日期须为该周周日；月榜日期须为该月第一天。\r\n- **数据时效**：周榜仅近 90 天，月榜仅近 12 个月。\r\n- **分页上限**：单次请求最多 100 条；按商品 ID 查询时最多 20 个。\r\n- **不在范围内**：Amazon 选品与关键词分析（用 ABA 工具）；1688 店铺级分析（店铺排名、店铺评分）；Alibaba.com 国际站数据；价格议价与下单；商品质量评价与认证；物流成本计算与货代。\r\n\r\n## 核心概念\r\n\r\n1688 商品热销榜单提供 1688 平台商品排名数据，覆盖**周榜**与**月榜**，帮助发现趋势批发商品、对比供应商、识别货源机会。\r\n\r\n**榜单类型**：\r\n- **周榜**（`pageType=2`）：日期传该周周日，如 `2025-06-15`；数据为近 90 天。\r\n- **月榜**（`pageType=3`）：日期传该月第一天，如 `2025-06-01`；数据为近 12 个月。\r\n\r\n**默认行为**：月榜，按销售笔数降序，每页 20 条。\r\n\r\n## 使用示例\r\n\r\n**1. 某关键词的月度热销榜**\r\n> \"查一下 1688 本月手机壳的热销榜\"\r\n```json\r\n{\"keyWord\": \"手机壳\", \"pageType\": 3, \"date\": \"2026-03-01\", \"sortField\": \"orderCount\", \"sortType\": \"desc\"}\r\n```\r\n\r\n**2. 周榜按销售额排序**\r\n> \"上周瑜伽垫品类里销售额最高的是哪些？\"\r\n```json\r\n{\"keyWord\": \"瑜伽垫\", \"pageType\": 2, \"date\": \"2026-03-22\", \"sortField\": \"saleVolume\", \"sortType\": \"desc\"}\r\n```\r\n\r\n**3. 工厂直供并限价**\r\n> \"在 1688 找 5-30 元的耳机工厂直供商品\"\r\n```json\r\n{\"keyWord\": \"耳机\", \"companyType\": 2, \"beginPrice\": 5, \"endPrice\": 30, \"sortField\": \"saleCount\", \"sortType\": \"desc\"}\r\n```\r\n\r\n**4. 跨境标签且 24 小时发货**\r\n> \"看下 24 小时内发货的跨境标签 LED 灯商品\"\r\n```json\r\n{\"keyWord\": \"LED灯\", \"offerType\": 4, \"sendTime\": \"24\", \"sortField\": \"orderCount\", \"sortType\": \"desc\"}\r\n```\r\n\r\n**5. 超级工厂新品**\r\n> \"找宠物用品类目下超级工厂的新上架商品\"\r\n```json\r\n{\"keyWord\": \"宠物用品\", \"offerType\": 2, \"shiLiType\": \"superFactory\", \"sortField\": \"offerCreateTime\", \"sortType\": \"desc\"}\r\n```\r\n\r\n**6. 支持代发且有买家保障的商品**\r\n> \"看下支持一件代发、包邮且支持 7 天退货的包包商品\"\r\n```json\r\n{\"keyWord\": \"包包\", \"proxyRights\": \"4360897\", \"buyerProtections\": \"商品包邮,7天包退货\", \"sortField\": \"orderCount\", \"sortType\": \"desc\"}\r\n```\r\n\r\n**7. 价格区间内的高销量商品**\r\n> \"找玩具类目下批发价 50 元以内、销售笔数超 1000 的商品\"\r\n```json\r\n{\"keyWord\": \"玩具\", \"beginOrderCount\": 1000, \"endPrice\": 50, \"sortField\": \"orderCount\", \"sortType\": \"desc\"}\r\n```\r\n\r\n**8. 按商品 ID 查询**\r\n> \"查这几个 1688 商品 ID：123456、789012\"\r\n```json\r\n{\"productIds\": \"123456、789012\"}\r\n```\r\n\r\n## 展示规则\r\n\r\n1. **清晰呈现数据**：以结构化表格展示商品标题、批发价、代发价、销售笔数、销售件数、预估销售额、供应商名称、上架时间等。\r\n2. **图片展示**：返回 `imageUrl` 时展示商品图片，便于直观识别。\r\n3. **提供链接**：附商品链接（`asinUrl`）与店铺链接（`shopUrl`），方便直达 1688 商品页。\r\n4. **价格格式**：价格须带币种（CNY/RMB），并注明是批发价还是代发价。\r\n5. **销量口径**：展示销量数据时，按 `dataType` 字段标明是周数据还是月数据。\r\n6. **分页提示**：总条数超出当前页时，告知总数并询问是否继续翻页。\r\n7. **关键词翻译**：用户提供非中文关键词时，先翻译为中文再查询，并告知译文。\r\n8. **错误处理**：查询失败时说明原因，并建议调整参数（如放宽筛选、检查日期格式）。\r\n\r\n## 用户表达与场景速查\r\n\r\n**适用** —— 1688 批发商品发现与货源调研：\r\n\r\n| 用户说 | 场景 |\r\n|--------|------|\r\n| \"1688 上什么火\"、\"1688 趋势商品\" | 热销商品发现 |\r\n| \"给 XX 找便宜货源\"、\"XX 批发货源\" | 按关键词找货源 |\r\n| \"工厂直供商品\"、\"OEM 供应商\" | 工厂筛选 |\r\n| \"跨境货源\"、\"出口商品\" | 跨境标签筛选 |\r\n| \"1688 一件代发商品\" | 支持代发的商品搜索 |\r\n| \"1688 新品\"、\"最近上架的\" | 新品发现 |\r\n| \"对比 XX 的供应商\" | 多结果对比 |\r\n| \"1688 商品排行\"、\"热销榜\" | 榜单浏览 |\r\n\r\n不适用场景见上方【能力边界】。\r\n\r\n## 解决认证和积分问题\r\n\r\n发生以下异常情况时，采用以下措施来处理：\r\n\r\n### 异常情况\r\n- **未配置 API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\r\n- **响应 401 或 402 状态码**\r\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\r\n\r\n### 措施\r\n- 优先采用 skill 内的 onboarding.md 引导解决问题。\r\n- 如找不到 onboarding.md 文件，则加载 /linkfox-onboarding 这个 skill 并根据它的引导来处理。如未安装请先安装：\r\n    - 下载 https://agent-files.linkfox.com/skills/linkfox-onboarding/release.zip，解压后安装这个 skill。\r\n\r\n---\r\n\r\n# 店雷达-1688商品榜单 API 参考\r\n\r\n## 调用规范\r\n\r\n- **请求地址**：`${LINKFOX_TOOL_GATEWAY}/dld/productBillboard`\r\n- **请求方式**：POST，Content-Type: application/json\r\n- **认证方式**：Header `Authorization: <api_key>`，api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\r\n\r\n## 请求参数\r\n\r\nPOST Body（JSON）：\r\n\r\n| 参数 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| keyWord | string | 否 | 商品搜索关键字（搜索关键词必须是中文，如果不是请先翻译），最大长度50 |\r\n| date | string | 否 | 查询时间。周榜：传入该周的周天日期，如 `2025-06-15`（最长近90天）；月榜：传入该月第一天，如 `2025-06-01`（最长近一年） |\r\n| pageType | integer | 否 | 榜单类型：`2` = 周榜，`3` = 月榜。默认 `3` |\r\n| pageIndex | integer | 否 | 页码（从1开始），默认 `1` |\r\n| pageSize | integer | 否 | 每页返回数量（10-100），默认 `20` |\r\n| sortField | string | 否 | 排序字段，默认 `orderCount`。可选值：`orderCount`（销售笔数）、`saleCount`（销售件数）、`saleVolume`（预估销售额）、`offerCreateTime`（上架时间）、`price`（批发价）、`consignPrice`（代发价） |\r\n| sortType | string | 否 | 排序类型：`desc`（降序）、`asc`（升序），默认 `desc` |\r\n| searchType | integer | 否 | 商品关键词搜索类型：`1` = 模糊匹配，`3` = 精准匹配。默认 `1` |\r\n| offerType | integer | 否 | 商品标识：`0` = 不限制，`2` = 新品，`3` = 1688严选，`4` = 跨境，`5` = 支持定制，`6` = 镇店之宝。默认 `0` |\r\n| companyType | integer | 否 | 公司类型：`0` = 不限，`1` = 店铺，`2` = 工厂 |\r\n| shiLiType | string | 否 | 卖家会员类型（多选），多个使用\",\"号隔开。可选值：`superFactory`（超级工厂）、`Power`（实力商家）、`TrustPass`（仅诚信通会员） |\r\n| beginTpYear | integer | 否 | 开始诚信通年限 |\r\n| endTpYear | integer | 否 | 结束诚信通年限 |\r\n| beginPrice | number | 否 | 批发价（起始） |\r\n| endPrice | number | 否 | 批发价（结束） |\r\n| beginConsignPrice | number | 否 | 代发价（起始） |\r\n| endConsignPrice | number | 否 | 代发价（结束） |\r\n| beginOrderCount | integer | 否 | 销售笔数（起始） |\r\n| endOrderCount | integer | 否 | 销售笔数（结束） |\r\n| beginSaleCount | integer | 否 | 销售件数（起始） |\r\n| endSaleCount | integer | 否 | 销售件数（结束） |\r\n| beginSaleVolume | number | 否 | 销售额（起始） |\r\n| endSaleVolume | number | 否 | 销售额（结束） |\r\n| beginStartQuantity | integer | 否 | 起始起批量 |\r\n| endStartQuantity | integer | 否 | 结束起批量 |\r\n| beginOfferCreateTime | string | 否 | 上架时间（起始），格式：`YYYY-MM-DD` |\r\n| endOfferCreateTime | string | 否 | 上架时间（结束），格式：`YYYY-MM-DD` |\r\n| sendTime | string | 否 | 发货时间（多选），多个使用\",\"号隔开。可选值：`24`（24小时）、`48`（48小时）、`72`（72小时） |\r\n| proxyRights | string | 否 | 代发权益（多选），多个使用\",\"号隔开。可选值：`4360897`（一件代发包邮）、`449154`（先采后付） |\r\n| shopService | string | 否 | 卖家服务（多选），多个使用\",\"号隔开。可选值：`4057409`（安心购）、`888777`（深度认证报告） |\r\n| buyerProtections | string | 否 | 权益保障（多选），多个用\",\"隔开。可选值：`商品包邮`、`7天包退货`、`支持运费险` |\r\n| faceToFaceSupport | string | 否 | 面单支持（多选），多个使用\",\"号隔开。可选值：`441218`（淘宝）、`386434`（抖音）、`422914`（拼多多）、`422978`（小红书）、`386370`（快手） |\r\n| productIds | string | 否 | 商品ID，顿号隔开搜索多个，最多20个 |\r\n| goodsUrl | string | 否 | 商品链接地址 |\r\n\r\n\r\n## 响应结构\r\n\r\n| 字段 | 类型 | 说明 |\r\n|------|------|------|\r\n| total | integer | 记录数 |\r\n| type | string | 渲染的样式 |\r\n| columns | array | 渲染的列 |\r\n| products | array | 商品列表（见下方商品对象） |\r\n\r\n### 商品对象\r\n\r\n| 字段 | 类型 | 说明 |\r\n|------|------|------|\r\n| offerId | string | 商品id |\r\n| asin | string | 商品编号 |\r\n| title | string | 商品标题 |\r\n| price | number | 批发价 |\r\n| consignPrice | number | 代发价 |\r\n| currency | string | 币种 |\r\n| unit | string | 单位 |\r\n| quantityBegin | integer | 起批量 |\r\n| quantityPrices | string | 价格区间 |\r\n| salesOrderCount | integer | 销售笔数（按统计周期返回对应的值） |\r\n| salesQuantity | integer | 销售件数（按统计周期返回对应的值） |\r\n| estimatedSalesAmount | integer | 预估销售额（按统计周期返回对应的值） |\r\n| dataType | string | 数据类型：`weeklyData` = 周数据，`monthlyData` = 月数据 |\r\n| availableDate | string | 商品上架时间，格式为 `yyyy-MM-dd HH:mm:ss` |\r\n| deliveryTime | string | 发货时间 |\r\n| levelName | string | 类目层级名称 |\r\n| company | string | 店铺名称 |\r\n| shopId | string | 店铺id |\r\n| shopUrl | string | 店铺链接地址 |\r\n| asinUrl | string | 商品链接地址 |\r\n| imageUrl | string | 图片地址 |\r\n| sourceType | string | 来源平台（1688） |\r\n| sourceTool | string | 来源工具 |\r\n\r\n## 错误码\r\n\r\n正常情况下，接口的 HTTP 状态码均为 200，业务的成功与否通过响应体中的 errorCode 字段区分（errorCode = 200 表示成功，其他值表示业务错误）。当遇到未授权等情况时，HTTP 状态码为 401，且对应的 errorCode 也是 401。\r\n\r\n| errcode | 含义 | 处理建议 |\r\n|---------|------|----------|\r\n| 200 | 成功 | 正常解析业务字段 |\r\n| 401 | 认证失败 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\r\n| 402 | 积分不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\r\n| 其他非200值 | 业务异常 | 参考 `errmsg` 字段获取具体错误原因 |\r\n\r\n错误响应示例：\r\n\r\n```json\r\n{\r\n    \"errcode\": 401,\r\n    \"errmsg\": \"authorized error\"\r\n}\r\n```\r\n\r\n## curl 示例\r\n\r\n```bash\r\ncurl -X POST https://tool-gateway.linkfox.com/dld/productBillboard \\\r\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -d '{\r\n    \"keyWord\": \"手机壳\",\r\n    \"pageType\": 3,\r\n    \"date\": \"2026-03-01\",\r\n    \"sortField\": \"orderCount\",\r\n    \"sortType\": \"desc\",\r\n    \"pageSize\": 20,\r\n    \"pageIndex\": 1\r\n  }'\r\n```\n\nFile v1.2.3:references/linkfox-dld-product-search.md\n\n---\r\nname: linkfox-dld-product-search\r\ndescription: 1688 批发平台商品搜索。用于寻找国内工厂货源、供应商发现、批发价格对比及选品调研。\r\n\r\n# 1688 商品搜索（DLD Product Search）\r\n\r\n本技能用于在 1688 批发平台（阿里巴巴国内 B2B 市场）上搜索和分析商品，帮助电商卖家与采购人员寻找优质供应商与有利润空间的商品。参数与响应字段详见 [references/api.md](references/api.md)。\r\n\r\n## 能力边界\r\n\r\n### ✅ 能力范围\r\n\r\n- 基于 1688 平台进行关键词商品搜索，聚合商品列表及其销量、价格分层、供应商资质与履约信息。\r\n- 数据来源于店雷达（store radar）分析，覆盖实时商品列表与近 7 天 / 30 天销量指标。\r\n- 支持按关键词、商品链接、商品 ID 检索，并按价格、销量、销售额、上架时间等多维排序。\r\n- 支持按公司类型（店铺/工厂）、卖家会员类型、发货时间、代发权益、面单支持等筛选。\r\n\r\n### ❌ 边界与限制\r\n\r\n- **关键词语言**：`keyWord` 必须为中文，非中文关键词需先翻译再查询。\r\n- **搜索方式互斥**：`keyWord`、`goodsUrl`、`productIds` 三者择一使用。\r\n- **统计周期**：仅支持近 7 天（`cycle=\"7\"`）或近 30 天（`cycle=\"30\"`）。\r\n- **分页上限**：单次最多 100 条；按商品 ID 查询最多 20 个。\r\n- **不在范围内**：Amazon 等非 1688 平台的商品研究；1688 店铺级分析（店铺流量、店铺排名）；1688 广告与推广策略；商品评论或评分分析；物流成本计算与运费估算；下单与交易处理；用户已有本地商品数据文件需分析。\r\n\r\n**边界判断**：当用户说\"找货源\"\"找供应商\"\"批发商品\"时，若涉及在 1688 平台按价格、销量、供应商类型等条件搜索具体商品，适用本技能；若需要店铺级分析、广告优化或超出商品搜索范围的运营操作，则不适用。\r\n\r\n## 核心概念\r\n\r\n本工具提供 1688（中国最大的 B2B 批发市场）的关键词商品搜索，聚合商品列表及其销量数据、价格分层、供应商资质与履约选项。数据来源于店雷达分析，覆盖实时商品列表与 7 天、30 天销量指标。\r\n\r\n**关键术语**：\r\n- **批发价**（`price`）：按起批量下单时的单件价格。\r\n- **代发价**（`consignPrice`）：单件一件代发的单件价格（通常高于批发价）。\r\n- **诚信通年限**（`tpYear`）：供应商持有阿里巴巴诚信通会员的年数，反映经营年限。\r\n- **销售件数**（`salesQuantity`）：所选统计周期内的总销售件数。\r\n- **销售笔数**（`salesOrderCount`）：所选统计周期内的总订单笔数。\r\n- **预估销售额**（`estimatedSalesAmount`）：所选统计周期内的预估销售额。\r\n\r\n## 使用示例\r\n\r\n**1. 基础关键词搜索——\"瑜伽垫\"热销品**\r\n```json\r\n{\"keyWord\": \"瑜伽垫\", \"cycle\": \"30\", \"sortField\": \"saleCount30d\", \"sortType\": \"desc\", \"pageSize\": 20}\r\n```\r\n\r\n**2. 仅工厂且有价格区间**\r\n```json\r\n{\"keyWord\": \"蓝牙耳机\", \"companyType\": 2, \"beginPrice\": 10, \"endPrice\": 50, \"cycle\": \"30\", \"sortField\": \"orderCount30d\"}\r\n```\r\n\r\n**3. 跨境商品并支持代发**\r\n```json\r\n{\"keyWord\": \"手机壳\", \"offerType\": 4, \"proxyRights\": \"4360897\", \"cycle\": \"7\", \"sortField\": \"saleVolume7d\"}\r\n```\r\n\r\n**4. 最近上架的新品，按上架时间排序**\r\n```json\r\n{\"keyWord\": \"夏季连衣裙\", \"offerType\": 2, \"sortField\": \"offerCreateTime\", \"sortType\": \"desc\", \"pageSize\": 50}\r\n```\r\n\r\n**5. 超级工厂的高销量商品**\r\n```json\r\n{\"keyWord\": \"数据线\", \"shiLiType\": \"superFactory\", \"beginSaleCount\": 1000, \"cycle\": \"30\", \"sortField\": \"saleCount30d\"}\r\n```\r\n\r\n**6. 按商品链接搜索**\r\n```json\r\n{\"goodsUrl\": \"https://detail.1688.com/offer/805578065498.html\", \"cycle\": \"30\"}\r\n```\r\n\r\n## 展示规则\r\n\r\n1. **清晰呈现数据**：以结构化表格展示商品标题、价格、销量指标与供应商信息，并附商品链接方便直达。\r\n2. **价格口径**：有批发价与代发价时同时展示，便于用户对比利润空间。\r\n3. **销量口径**：根据所用的 `cycle` 参数，明确标注是 7 天还是 30 天数据。\r\n4. **图片展示**：返回 `imageUrl` 时展示商品图片，便于直观识别。\r\n5. **分页提示**：总条数超出当前页时，告知总数并询问是否继续翻页。\r\n6. **错误处理**：查询失败时说明原因，并建议调整参数（如放宽筛选、检查关键词拼写）。\r\n7. **关键词翻译**：用户提供英文商品词时，先翻译为中文再调用，并在回复中注明译文。\r\n\r\n## 用户表达与场景速查\r\n\r\n**适用** —— 1688 批发商品搜索与货源调研：\r\n\r\n| 用户说 | 场景 |\r\n|--------|------|\r\n| \"在 1688 上找 XX 的供应商\" | 关键词商品搜索 |\r\n| \"1688 上什么好卖\" | 热销商品发现 |\r\n| \"找工厂的便宜 XX\" | 工厂货源 + 价格筛选 |\r\n| \"1688 一件代发 XX 的供应商\" | 支持代发的商品搜索 |\r\n| \"对比 XX 在 1688 上的价格\" | 跨供应商比价 |\r\n| \"1688 上 XX 的新品\" | 新品发现 |\r\n| \"找 1688 跨境商品\" | 跨境商品采购 |\r\n| \"哪些 1688 供应商 24 小时发货\" | 履约速度筛选 |\r\n| \"XX 的顶级工厂\" | 超级工厂 / 实力商家搜索 |\r\n| \"查这个 1688 商品\"（带链接或 ID） | 直接查询指定商品 |\r\n\r\n不适用场景见上方【能力边界】。\r\n\r\n## 解决认证和积分问题\r\n\r\n发生以下异常情况时，采用以下措施来处理：\r\n\r\n### 异常情况\r\n- **未配置 API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\r\n- **响应 401 或 402 状态码**\r\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\r\n\r\n### 措施\r\n- 优先采用 skill 内的 onboarding.md 引导解决问题。\r\n- 如找不到 onboarding.md 文件，则加载 /linkfox-onboarding 这个 skill 并根据它的引导来处理。如未安装请先安装：\r\n    - 下载 https://agent-files.linkfox.com/skills/linkfox-onboarding/release.zip，解压后安装这个 skill。\r\n\r\n---\r\n\r\n# 店雷达 1688 选品库 API 参考\r\n\r\n## 调用规范\r\n\r\n- **请求地址**：`${LINKFOX_TOOL_GATEWAY}/dld/productSearch`\r\n- **请求方式**：POST，Content-Type: application/json\r\n- **认证方式**：Header `Authorization: <api_key>`，api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\r\n\r\n## 请求参数\r\n\r\nPOST Body（JSON）：\r\n\r\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\r\n|------|------|------|--------|------|\r\n| keyWord | string | 否 | - | 搜索关键词（必须为中文，最多50字符） |\r\n| goodsUrl | string | 否 | - | 商品链接地址（与keyWord二选一） |\r\n| productIds | string | 否 | - | 商品ID，多个逗号隔开，最多20个 |\r\n| cycle | string | 否 | - | 统计周期：`7`（近7天）或 `30`（近30天） |\r\n| searchType | integer | 否 | 1 | 搜索类型：1-模糊匹配，3-精准匹配 |\r\n| sortField | string | 否 | orderCount30d | 排序字段：orderCount7d, saleCount7d, saleVolume7d, orderCount30d, saleCount30d, saleVolume30d, offerCreateTime, price, consignPrice |\r\n| sortType | string | 否 | desc | 排序类型：desc（降序）、asc（升序） |\r\n| pageIndex | integer | 否 | 1 | 页码（从1开始） |\r\n| pageSize | integer | 否 | 20 | 每页数量（10-100） |\r\n| beginPrice | number | 否 | - | 批发价（起始） |\r\n| endPrice | number | 否 | - | 批发价（结束） |\r\n| beginConsignPrice | number | 否 | - | 代发价（起始） |\r\n| endConsignPrice | number | 否 | - | 代发价（结束） |\r\n| beginOrderCount | integer | 否 | - | 销售笔数（起始） |\r\n| endOrderCount | integer | 否 | - | 销售笔数（结束） |\r\n| beginSaleCount | integer | 否 | - | 销售件数（起始） |\r\n| endSaleCount | integer | 否 | - | 销售件数（结束） |\r\n| beginSaleVolume | number | 否 | - | 销售额（起始） |\r\n| endSaleVolume | number | 否 | - | 销售额（结束） |\r\n| beginStartQuantity | integer | 否 | - | 起购数量（起始） |\r\n| endStartQuantity | integer | 否 | - | 起购数量（结束） |\r\n| beginTpYear | integer | 否 | - | 诚信通年限（起始） |\r\n| endTpYear | integer | 否 | - | 诚信通年限（结束） |\r\n| beginOfferCreateTime | string | 否 | - | 上架时间起始（格式：YYYY-MM-DD） |\r\n| endOfferCreateTime | string | 否 | - | 上架时间结束（格式：YYYY-MM-DD） |\r\n| companyType | integer | 否 | 0 | 公司类型：0-不限，1-店铺，2-工厂 |\r\n| offerType | integer | 否 | 0 | 商品标识：0-不限，2-新品，3-1688严选，4-跨境，5-支持定制，6-镇店之宝 |\r\n| shiLiType | string | 否 | - | 卖家类型（多选逗号隔开）：superFactory（超级工厂）、Power（实力商家）、TrustPass（诚信通） |\r\n| sendTime | string | 否 | - | 发货时间（多选逗号隔开）：24、48、72 |\r\n| faceToFaceSupport | string | 否 | - | 面单支持（多选逗号隔开）：441218（淘宝）、386434（抖音）、422914（拼多多）、422978（小红书）、386370（快手） |\r\n| proxyRights | string | 否 | - | 代发权益（多选逗号隔开）：4360897（一件代发包邮）、449154（先采后付） |\r\n| shopService | string | 否 | - | 卖家服务（多选逗号隔开）：4057409（安心购）、888777（深度认证报告） |\r\n| buyerProtections | string | 否 | - | 权益保障（多选逗号隔开）：商品包邮、7天包退货、支持运费险 |\r\n\r\n## 响应结构\r\n\r\n| 字段 | 类型 | 说明 |\r\n|------|------|------|\r\n| total | integer | 总记录数 |\r\n| type | string | 渲染样式 |\r\n| columns | array | 渲染列定义 |\r\n| products | array | 商品列表（详见下方字段） |\r\n\r\n### products 数组元素字段\r\n\r\n| 字段 | 类型 | 说明 |\r\n|------|------|------|\r\n| offerId | string | 商品ID |\r\n| asin | string | 商品编号 |\r\n| title | string | 商品标题 |\r\n| asinUrl | string | 商品链接地址 |\r\n| imageUrl | string | 商品图片地址 |\r\n| price | number | 批发价 |\r\n| consignPrice | number | 代发价 |\r\n| quantityPrices | string | 价格区间 |\r\n| quantityBegin | integer | 起批量 |\r\n| unit | string | 单位 |\r\n| currency | string | 币种 |\r\n| salesOrderCount | integer | 销售笔数（按统计周期） |\r\n| salesQuantity | integer | 销售件数（按统计周期） |\r\n| estimatedSalesAmount | integer | 预估销售额（按统计周期） |\r\n| deliveryTime | string | 发货时间 |\r\n| availableDate | string | 商品上架时间 |\r\n| levelName | string | 类目层级名称 |\r\n| company | string | 店铺名称 |\r\n| shopId | string | 店铺ID |\r\n| shopUrl | string | 店铺链接地址 |\r\n| dataType | string | 数据类型：weeklyData（周数据）、monthlyData（月数据） |\r\n| sourceType | string | 来源平台（1688） |\r\n| sourceTool | string | 来源工具 |\r\n\r\n## 错误码\r\n\r\n正常情况下，接口的 HTTP 状态码均为 200，业务的成功与否通过响应体中的 errorCode 字段区分（errorCode = 200 表示成功，其他值表示业务错误）。当遇到未授权等情况时，HTTP 状态码为 401，且对应的 errorCode 也是 401。\r\n\r\n| errcode | 含义 | 处理建议 |\r\n|---------|------|----------|\r\n| 200 | 成功 | 正常解析业务字段 |\r\n| 401 | 认证失败 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\r\n| 402 | 积分不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\r\n| 其他非200值 | 业务异常 | 参考 `errmsg` 字段获取具体错误原因 |\r\n\r\n错误响应示例：\r\n\r\n```json\r\n{\r\n    \"errcode\": 401,\r\n    \"errmsg\": \"authorized error\"\r\n}\r\n```\r\n\r\n## curl 示例\r\n\r\n```bash\r\ncurl -X POST https://tool-gateway.linkfox.com/dld/productSearch \\\r\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -d '{\"keyWord\": \"瑜伽垫\", \"cycle\": \"30\", \"sortField\": \"saleCount30d\", \"sortType\": \"desc\", \"pageSize\": 20}'\r\n```\n\nFile v1.2.3:references/onboarding.md\n\n# 解决认证和积分问题\r\n\r\n调用本 skill 时若网关返回 **auth** 或 **billing** 错误，走本 skill 自带的 `scripts/onboarding.py` 完成引导。\r\n\r\n**auth 场景**：`errcode=401` 或消息含 `authorized error`/`鉴权失败`/`未授权`/`unauthorized`；或 `LINKFOX_AGENT_API_KEY` 与 `LINKFOXAGENT_API_KEY` 均为空。\r\n1. 若已配置 key → 先让用户重启会话（最常见误判），仍失败让用户重新取 key 或换手机号重注册\r\n2. 未配置 → 询问：自助去 https://agent.linkfox.com/ 取 key，或提供手机号让脚本注册\r\n3. 手机号路径：\r\n   - `python scripts/onboarding.py send-code <phone>` → 展示 JSON 里的 phone/agreements\r\n   - 收到验证码后：`python scripts/onboarding.py login <phone> <code>`（workbuddy 宿主加 `--channel workbuddy`）\r\n   - 拿到 `api_key` 后把下面三平台配置转发给用户，提示重启会话生效：\r\n     - Windows PowerShell（永久）：`setx LINKFOX_AGENT_API_KEY \"<key>\"`\r\n     - macOS zsh：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.zshrc && source ~/.zshrc`\r\n     - Linux bash：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.bashrc && source ~/.bashrc`\r\n     - 变量名 `LINKFOX_AGENT_API_KEY`（主推）或 `LINKFOXAGENT_API_KEY`（老规范）任一即可\r\n\r\n**billing 场景**：`errcode=402` 或消息含 `积分/余额/quota/insufficient/充值/套餐到期`。\r\n- `python scripts/onboarding.py list-plans` → 有 AskUserQuestion 就弹菜单，否则输出编号清单让用户选\r\n- 校验 `plan_id` ∈ 清单、支付方式 ∈ 该套餐 `available_methods`（通常 `wechat/alipay`）\r\n- `python scripts/onboarding.py order <plan_id> <method>` → 展示优先级 PNG > `pay_url` > `ascii_qr`（标注兜底）\r\n- 已付款可选调 `python scripts/onboarding.py query <order_id>`，不主动轮询\r\n\r\n排除 `errcode=403`（无权限，不归入这两类）。所有子命令输出 stdout JSON，`error` 字段已含阶段前缀，透传给用户即可。完整用法：`python scripts/onboarding.py --help`。\n\nFile v1.2.3:skill-card.md\n\n## Description:\n\nLinkfox 1688货源 is a one-stop 1688 sourcing toolkit for product search, bestseller discovery, image-based sourcing, and authorized procurement workflows.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[linkfox-ai](https://clawhub.ai/user/linkfox-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and agents use this skill to find and compare 1688 suppliers and products, run image-based same-product sourcing, and complete authorized procurement tasks such as order preview, order creation, payment link retrieval, status checks, logistics tracking, cancellation, and receipt confirmation.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill uses account-scoped LinkFox API access for 1688 sourcing and procurement.\n\nMitigation: Install only when the publisher is trusted, keep API keys sensitive, and avoid exposing generated keys or shell profile exports.\n\nRisk: Procurement actions such as creating orders, obtaining payment links, cancelling orders, or confirming receipt can affect real transactions.\n\nMitigation: Require explicit user confirmation and review key details such as item, order ID, amount, and status before each action.\n\nRisk: Custom LINKFOX_* endpoint variables could redirect requests away from the intended service.\n\nMitigation: Use default endpoints unless a custom endpoint has been deliberately reviewed and trusted.\n\nRisk: Local images uploaded for image search may become accessible through generated URLs.\n\nMitigation: Upload only images that are safe to share through a temporary URL.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/linkfox-ai/skills/linkfox-1688-sourcing)\n- [1688 procurement reference](references/linkfox-1688-procurement.md)\n- [1688 image search reference](references/linkfox-1688-search-by-image.md)\n- [DLD product billboard reference](references/linkfox-dld-product-billboard.md)\n- [DLD product search reference](references/linkfox-dld-product-search.md)\n- [Onboarding reference](references/onboarding.md)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Markdown, Shell commands, Configuration, JSON]\n\n**Output Format:** [Markdown guidance with inline shell commands and JSON snippets]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Tool runs can return JSON summaries and may save detailed response files for later inspection.]\n\n## Skill Version(s):\n\n1.2.3 (source: server release metadata; artifact frontmatter reports 1.0.0)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.2.2: 26 files, 68418 bytes\n\nFiles: references/linkfox-1688-procurement.md (23508b), references/linkfox-1688-search-by-image.md (15759b), references/linkfox-dld-product-billboard.md (12861b), references/linkfox-dld-product-search.md (12271b), references/onboarding.md (2068b), scripts/_alibaba1688_common.py (12498b), scripts/alibaba1688_image_search.py (12725b), scripts/authorize_url.py (124b), scripts/authorized_stores.py (128b), scripts/cancel_order.py (123b), scripts/confirm_receive.py (126b), scripts/create_order.py (123b), scripts/dld_product_billboard.py (13086b), scripts/dld_product_search.py (13048b), scripts/logistics_trace.py (126b), scripts/logistics.py (121b), scripts/onboarding.py (24089b), scripts/order_preview.py (124b), scripts/order_status.py (123b), scripts/payment_url.py (122b), scripts/receive_address_list.py (130b), scripts/sku.py (115b), scripts/upload_image.py (4591b), skill-card.md (3396b), SKILL.md (19990b), _meta.json (140b)\n\nFile v1.2.2:SKILL.md\n\n---\nname: linkfox-1688-sourcing\ndisplay_name: Linkfox 1688货源\ndisplay_name_en: LinkFox 1688 Sourcing\ndescription: 1688 货源一站式 AI 工具集，整合商品搜索、热销榜单、以图搜图与已授权采购履约，覆盖找货、选品、比价、图搜同款与下单全流程。\ndescription_zh: 1688 货源一站式工具集：店雷达商品搜索与热销榜单（关键词/链接/ID 检索、周榜月榜、多维筛选排序、批发价/代发价/销量与供应商资质）、1688 以图搜图（图片 URL/Base64/imageId 视觉检索同款货源，含本地图片上传）、1688 已授权采购全流程（OAuth 授权检查、SKU/收货地址、下单预览、创建订单、支付链接、订单状态、物流轨迹、取消订单、确认收货）。当用户需要 1688 找货源、找供应商、批发选品、热销榜单、以图找同款、跨境找工厂或已授权采购下单与物流跟踪时触发。各子能力完整参数见 references/ 对应文件，脚本见 scripts/。\ndescription_en: One-stop 1688 sourcing AI toolkit: store-radar product search and bestseller billboards (keyword/URL/ID retrieval, weekly/monthly rankings, multi-dimensional filters and sorting, wholesale/dropship price, sales and supplier qualifications), 1688 image search (visual retrieval of same-style sourcing by image URL/Base64/imageId, with local image upload), and end-to-end authorized 1688 procurement (OAuth checks, SKU/address, order preview, order creation, payment URL, order status, logistics tracking, cancellation, receipt confirmation). Triggered when the user needs 1688 sourcing, supplier discovery, wholesale product selection, bestseller rankings, image-based same-product search, cross-border factory sourcing, or authorized 1688 procurement ordering and logistics tracking. Full params per sub-capability are in references/, executable scripts in scripts/.\ncategory: e-commerce\nversion: 1.0.0\nauthor: LinkFox\n---\n\n# Linkfox 1688货源（1688 Sourcing）\n\n1688 货源一站式 AI 工具集，整合 **3 类底层工具、4 项子能力**，覆盖货源搜索与热销榜单、以图搜图、已授权采购履约。各子能力完整参数、响应字段与错误码见 `references/` 下对应文件，可执行脚本见 `scripts/`。\n\n## 能力边界\n\n### ✅ 能力范围\n- **货源搜索与榜单（`1688_sourcing`）**：商品搜索（`linkfox-dld-product-search`，按关键词/商品链接/商品 ID 检索 1688 批发商品，近 7 天/30 天销量周期，按价格/销量/销售额/上架时间排序，按公司类型/卖家会员/发货时间/代发权益/面单支持等筛选）、商品热销榜单（`linkfox-dld-product-billboard`，周榜/月榜，按销售笔数/销售额/销量排序，发现爆款与趋势货源）。返回批发价、代发价、销售笔数/件数、预估销售额、起批量、供应商资质、店铺与商品链接等。\n- **以图搜图（`1688_search_by_image`）**：1688 以图搜图（`linkfox-1688-search-by-image`，通过图片 URL/Base64/imageId 视觉检索外观相似或同款货源），返回标题、批发价、代发价、月销量、起批量、复购率、交易评分、商家身份（超级工厂/实力商家/诚信通）等；支持价格/筛选（1688 严选/认证工厂/发货时效/品质退款率等）/排序/分页；本地图片先用 `upload_image.py` 上传获取公网 URL（有效期 24h）。\n- **采购履约（`1688_procurement`）**：1688 采购全流程（`linkfox-1688-procurement`），覆盖 OAuth 授权检查与发起授权、SKU/规格与收货地址查询、下单预览、创建订单、获取支付链接、订单状态、物流概览与物流轨迹、取消订单、确认收货。除授权类操作外每个 endpoint 前自动校验当前用户 ACTIVE 且未过期的 1688 授权；高风险写操作（创建订单/支付链接/取消订单/确认收货）需用户单独中文确认后由 Agent 注入对应 boolean 安全字段。\n- 数据平台均为中国大陆 1688 批发平台（阿里巴巴国内 B2B 市场），无多站点概念。\n\n### ❌ 边界与限制\n- **API Key 必需**：所有工具均需环境变量 `LINKFOX_AGENT_API_KEY`（或 `LINKFOXAGENT_API_KEY`）；各工具独立计费、独立限频。\n- **计费约束**：商品搜索/热销榜单固定计费（成功约 9 积分/18000 token），以图搜图固定计费（约 4.5 积分/9000 token），采购履约各操作消耗积分；同一会话同一参数组合默认只调用一次（搜索/榜单/图搜脚本带 24h 本地缓存）；失败、空结果、参数不全或授权不足不得自动换关键词、翻页或连续试探；需继续检索时先向用户说明会产生额外消耗（各工具计费规则见 `skills-version.json` 对应条目与 references 内 api.md）。\n- **采购授权前置**：采购类操作依赖当前用户已授权的 1688 OAuth；无 ACTIVE 授权时不调用目标 endpoint；高风险写操作失败不自动重试；不向用户索要 1688 token/refresh token/callback code/app secret。\n- **不在范围内**：Amazon/TikTok/沃尔玛等其他平台选品（用对应平台技能）；Alibaba.com 国际站数据；1688 店铺级分析（店铺流量/排名/评分）；商品评论分析；价格历史与趋势分析；图片生成或编辑；物流成本计算与货代；实时库存与订单系统对接；与供应商或平台的直接沟通。\n- **数据时效**：商品搜索/榜单为店雷达分析数据（7 天/30 天/周榜近 90 天/月榜近 12 个月）；以图搜图为实时搜索、不入库、无法二次 SQL 处理；采购履约为依赖 OAuth 的实时接口。\n\n## 工具选择指南\n\n按需求在下表定到子能力，再跳到【业务需求路由速查】查端点/脚本/references 取参执行。\n\n| 需求 / 用户说 | 默认推荐（子能力） | 何时换用其他 |\n|---|---|---|\n| 关键词找 1688 货源 / 找供应商（\"1688 上找 XX 货源\"） | `linkfox-dld-product-search`（关键词搜索，7/30 天销量） | 要看周/月排行榜用 `linkfox-dld-product-billboard`；有图片找同款用 `linkfox-1688-search-by-image` |\n| 1688 什么好卖 / 趋势 / 热销榜（\"1688 热销榜\"\"什么火\"） | `linkfox-dld-product-billboard`（周榜/月榜排名） | 要按关键词实时搜 + 销量筛选用 `linkfox-dld-product-search` |\n| 用图片找 1688 同款 / 以图搜图（\"用图找货源\"\"找同款\"） | `linkfox-1688-search-by-image`（唯一图搜，需图片 URL） | 本地图片先 `upload_image.py` 上传换公网 URL；要按关键词文本搜索用 `linkfox-dld-product-search` |\n| 按商品 ID / 商品链接查 1688 商品 | `linkfox-dld-product-search`（支持 `goodsUrl`/`productIds`） | 仅按 ID 查榜单商品也可用 `linkfox-dld-product-billboard` |\n| 工厂直供 / 超级工厂 / OEM 供应商（\"找工厂\"\"顶级工厂\"） | `linkfox-dld-product-search`（`companyType=2`/`shiLiType=superFactory`） | 要榜单里的工厂货用 `linkfox-dld-product-billboard` |\n| 1688 一件代发货源（\"一件代发\"\"支持代发\"） | `linkfox-dld-product-search`（`proxyRights=4360897`） | 要榜单代发货用 `linkfox-dld-product-billboard` |\n| 跨境货源 / 出口商品（\"跨境商品\"\"1688 严选\"） | `linkfox-dld-product-search`（`offerType=4`） | 要图搜跨境同款用 `linkfox-1688-search-by-image`（`filter=1688Selection`） |\n| 1688 新品 / 最近上架（\"新品\"\"最近上的\"） | `linkfox-dld-product-search`（`sortField=offerCreateTime`） | 要榜单新品用 `linkfox-dld-product-billboard`（`offerType=2`） |\n| 对比供应商 / 跨供应商比价 | `linkfox-dld-product-search`（多维排序） | — |\n| 查我的 1688 授权店铺（\"我的 1688 授权\"） | `linkfox-1688-procurement`（`authorized_stores.py`） | — |\n| 生成 1688 授权链接（\"授权 1688\"） | `linkfox-1688-procurement`（`authorize_url.py`） | — |\n| 查 offerId 的 SKU / 规格 / 起订量 / 库存 | `linkfox-1688-procurement`（`sku.py`） | 找 offerId 先用图搜或商品搜索 |\n| 查 1688 收货地址 | `linkfox-1688-procurement`（`receive_address_list.py`） | — |\n| 预览 1688 订单（\"帮我预览订单\"） | `linkfox-1688-procurement`（`order_preview.py`） | — |\n| 1688 下单 / 获取支付链接（\"确认下单\"\"获取支付链接\"） | `linkfox-1688-procurement`（`create_order.py`/`payment_url.py`，高风险需确认） | — |\n| 查 1688 订单状态 / 物流 / 物流轨迹 | `linkfox-1688-procurement`（`order_status.py`/`logistics.py`/`logistics_trace.py`） | — |\n| 取消 1688 订单 / 确认收货（\"取消订单\"\"确认收货\"） | `linkfox-1688-procurement`（`cancel_order.py`/`confirm_receive.py`，高风险需确认） | — |\n\n### 工具选择思路\n- **重要**：多个子能力满足需求时，要依据需求深入分析子能力的功能、用途、出入参、从中调研出最合适的子能力，并推荐用户，让用户自己决定。\n- 满足程度同等的前提下，向用户推荐\"默认推荐子能力\"。注意：找货/选品用搜索或榜单（`1688_sourcing`）或图搜（`1688_search_by_image`），已授权采购履约用 `1688_procurement`——前者只查货不交易，后者才可下单。\n\n## 业务需求路由速查\n\n按【工具选择指南】定到子能力后，下表查端点、脚本与 references 文件取参执行：\n\n### 子能力 ↔ references 文件 ↔ 端点 ↔ 脚本（4 项）\n\n**1688_sourcing**\n| 子能力 | references 文件 | 端点 | 脚本 |\n|---|---|---|---|\n| linkfox-dld-product-billboard | references/linkfox-dld-product-billboard.md | POST /dld/productBillboard | dld_product_billboard.py |\n| linkfox-dld-product-search | references/linkfox-dld-product-search.md | POST /dld/productSearch | dld_product_search.py |\n\n**1688_search_by_image**\n| 子能力 | references 文件 | 端点 | 脚本 |\n|---|---|---|---|\n| linkfox-1688-search-by-image | references/linkfox-1688-search-by-image.md | POST /alibaba1688/imageSearch | alibaba1688_image_search.py、upload_image.py（本地图片上传） |\n\n**1688_procurement**\n| 子能力 | references 文件 | 端点 | 脚本 |\n|---|---|---|---|\n| linkfox-1688-procurement | references/linkfox-1688-procurement.md | POST /alibaba1688/{operation} | 见下表（12 个操作脚本 + `_alibaba1688_common.py` 共享模块） |\n\n**1688 采购操作明细（operation ↔ 脚本 ↔ 风险）**\n\n| operation | 端点 | 脚本 | 风险 | 高风险确认字段 |\n|---|---|---|---|---|\n| authorizeUrl | POST /alibaba1688/authorizeUrl | authorize_url.py | 低（不需 ACTIVE 前置） | — |\n| authorizedStores | POST /alibaba1688/authorizedStores | authorized_stores.py | 低（不需 ACTIVE 前置） | — |\n| receiveAddressList | POST /alibaba1688/receiveAddressList | receive_address_list.py | 低（需 ACTIVE） | — |\n| sku | POST /alibaba1688/sku | sku.py | 低（需 ACTIVE） | — |\n| orderPreview | POST /alibaba1688/orderPreview | order_preview.py | 中（需 ACTIVE） | — |\n| createOrder | POST /alibaba1688/createOrder | create_order.py | 高（需 ACTIVE） | `confirmCreateOrder=true` |\n| paymentUrl | POST /alibaba1688/paymentUrl | payment_url.py | 高（需 ACTIVE） | `confirmGetPaymentUrl=true` |\n| orderStatus | POST /alibaba1688/orderStatus | order_status.py | 低（需 ACTIVE） | — |\n| logistics | POST /alibaba1688/logistics | logistics.py | 低（需 ACTIVE） | — |\n| logisticsTrace | POST /alibaba1688/logisticsTrace | logistics_trace.py | 低（需 ACTIVE） | — |\n| confirmReceive | POST /alibaba1688/confirmReceive | confirm_receive.py | 高（需 ACTIVE） | `confirmReceive=true` |\n| cancelOrder | POST /alibaba1688/cancelOrder | cancel_order.py | 高（需 ACTIVE） | `confirmCancel=true` |\n\n## 调用方式\n\n- **网关**：`${LINKFOX_TOOL_GATEWAY}/<端点>`，请求方式 POST、Content-Type `application/json`，认证 Header `Authorization: <api_key>`（api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取；未配置按下方【解决认证和积分问题】处理）。各端点路径见上方【业务需求路由速查】与对应 references 文件（注意：商品搜索/榜单走 `/dld/` 前缀，图搜与采购走 `/alibaba1688/` 前缀）。\n- **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）。\n- **输出策略**：商品搜索/榜单/图搜脚本**始终**将完整响应写入 `<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` 禁止保存。\n- **读数据建议**：先看 stdout 摘要判断是否足够；需要具体字段时优先用 `jq` 或 PowerShell `ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n- **完整参数**：每个子能力的请求参数、响应字段、错误码、curl 示例见 `references/<源skill>.md`（文件内含该子能力 SKILL.md 正文与 api.md 全文；采购另含 workflow.md 流程地图）。\n\n## 使用示例\n\n以下按数据层给出代表性子能力的出入参示例；其余子能力参数见对应 references 文件。1688 为中国大陆平台，价格币种为人民币（¥/CNY）。\n\n### 货源搜索与榜单层\n\n**1. 关键词商品搜索（1688_sourcing → dld_product_search.py）**\n```json\n{\"keyWord\": \"瑜伽垫\", \"cycle\": \"30\", \"sortField\": \"saleCount30d\", \"sortType\": \"desc\", \"pageSize\": 20}\n```\n出参：`products[]`（offerId/title/price/consignPrice/quantityBegin/salesOrderCount/salesQuantity/estimatedSalesAmount/company/shopId/shopUrl/asinUrl/imageUrl/deliveryTime/availableDate）、`total`、`costToken`。`keyWord`/`goodsUrl`/`productIds` 三选一；`cycle` 为 `7`/`30`。\n\n**2. 商品热销榜单（1688_sourcing → dld_product_billboard.py）**\n```json\n{\"keyWord\": \"手机壳\", \"pageType\": 3, \"date\": \"2026-03-01\", \"sortField\": \"orderCount\", \"sortType\": \"desc\", \"pageSize\": 20}\n```\n出参：`products[]`（字段同上）、`total`、`dataType`（`monthlyData`=月榜/`weeklyData`=周榜）、`costToken`。`pageType=2` 周榜（`date` 传该周周日，近 90 天），`pageType=3` 月榜（`date` 传该月第一天，近 12 个月）。\n\n### 以图搜图层\n\n**3. 以图搜图（1688_search_by_image → alibaba1688_image_search.py）**\n```json\n{\"imageUrl\": \"https://m.media-amazon.com/images/I/719mRAn2VrL._AC_SL1500_.jpg\", \"page\": 1, \"pageSize\": 20, \"filter\": \"1688Selection,totalEpScoreLv1\", \"sort\": \"{\\\"monthSold\\\":\\\"desc\\\"}\"}\n```\n出参：`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。\n\n### 采购履约层\n\n**4. 授权检查（1688_procurement → authorized_stores.py）**\n```json\n{}\n```\n出参：当前 LinkFox 用户的 1688 授权店铺列表，每条含 `status`（需 `ACTIVE`）、`expired`（需 `false`）。有 ACTIVE 授权可继续采购，无则先 `authorize_url.py` 发起授权。\n\n**5. SKU 查询（1688_procurement → sku.py）**\n```json\n{\"offerId\": \"123456789\"}\n```\n出参：SKU/规格、价格、起订量（MOQ）、库存。`offerId` 可由图搜或商品搜索结果获得。\n\n**6. 下单预览（1688_procurement → order_preview.py）**\n```json\n{\"offerId\": \"123456789\", \"quantity\": 10, \"addressId\": \"...\"}\n```\n出参：商品/offerId、SKU/规格、数量、单价与商品总价、运费、收货地址、订单总额、买家留言、异常/库存/价格变化提示。预览失败则停止，不进入创建订单。具体入参以网关 schema 为准。\n\n**7. 创建订单[高风险]（1688_procurement → create_order.py）**\n```json\n{\"offerId\": \"123456789\", \"quantity\": 10, \"addressId\": \"...\", \"confirmCreateOrder\": true}\n```\n出参：订单号与下单结果。用户单独中文确认后（如\"确认创建这个订单\"），Agent 在 payload 注入 boolean `confirmCreateOrder=true` 再调用；脚本本地拒绝缺少该字段的请求，失败不自动重试。支付链接（`payment_url.py`，需 `confirmGetPaymentUrl=true`）、取消订单（`cancel_order.py`，需 `confirmCancel=true`）、确认收货（`confirm_receive.py`，需 `confirmReceive=true`）同理各自独立确认。\n\n## 展示规则\n\n1. **客观呈现数据**：以清晰表格展示商品标题、批发价、代发价、销售笔数/件数、预估销售额、起批量、供应商资质等，不做主观商业建议（除非用户主动要求）。\n2. **来源标注**：展示数据时说明来自店雷达商品搜索/热销榜单、1688 以图搜图还是 1688 采购履约。\n3. **价格与销量口径**：价格须带币种（¥/CNY），并注明是批发价还是代发价；销量按 `dataType`/`cycle` 标明是周数据/月数据/7 天/30 天。\n4. **采购展示**：依赖 OAuth 时先展示授权状态，不单凭浏览器跳转判断；下单预览清晰展示商品/SKU/数量/单价/运费/收货地址/订单总额/异常提示；`authorizedStores` 输出是当前用户授权状态，不要描述成数据库全库账号列表。\n5. **高风险确认**：创建订单、获取支付链接、取消订单、确认收货前复述精确操作、关键 ID、金额/状态（如可得），请用户中文自然语言确认；不要求用户输入内部 boolean 字段（`=true` 由 Agent 注入）。\n6. **不可用数据**：值为 `0` 或 `-1` 的字段表示数据不可用，标注\"N/A\"或省略，不作实际值展示。\n7. **敏感信息**：永不展示完整 API key、JWT、access token、refresh token、callback code、app secret、session key、Authorization header；收货地址展示到足以安全选择即可，避免不必要重复完整手机号或敏感细节。\n8. **错误处理与协同**：查询失败时根据响应 `errcode`/`errmsg` 说明原因并建议修正（关键词需中文、日期格式、ASIN/offerId 格式、授权不足等）；连续使用多工具时（如先图搜找 offerId 再采购下单）将各工具发现汇总为连贯分析，标注数据来源与时间窗；返回 `costToken` 等成本字段时如实展示。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用 references/onboarding.md 引导解决问题：\n\n**注意**：你是workbuddy，并且渠道是workbuddy，使用 onboarding 引导登录注册时 channel **必须**为 workbuddy。这非常重要！\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\nFile v1.2.2:_meta.json\n\n{\n  \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n  \"slug\": \"linkfox-1688-sourcing\",\n  \"version\": \"1.2.2\",\n  \"publishedAt\": 1786098891841\n}\n\nFile v1.2.2:references/linkfox-1688-procurement.md\n\n---\r\nname: linkfox-1688-procurement\r\ndescription: 协助当前用户完成已授权的 1688 采购履约流程，包括授权检查、SKU/地址查询、订单预览、下单、支付、订单和物流跟踪等。\r\n\r\n# 1688采购全流程（1688 Procurement Workflow）\r\n\r\n本技能帮助 LinkFox 用户完成已授权的 1688 采购履约：OAuth 授权检查、SKU 与收货地址查询、下单预览、受保护的下单、支付链接获取、订单与物流跟踪、取消订单、确认收货。图搜找货使用 `linkfox-1688-search-by-image`，本技能不含图搜。端点与字段详见 [references/api.md](references/api.md)，多步采购前先读 [references/workflow.md](references/workflow.md)。\r\n\r\n## 能力边界\r\n\r\n### ✅ 能力范围\r\n\r\n- 查询当前 LinkFox 用户的 1688 OAuth 授权状态、发起授权链接。\r\n- 查询商品 SKU/规格、收货地址，进行下单预览（价格、运费、库存、地址）。\r\n- 在用户单独中文确认后执行高风险写操作：创建订单、获取支付链接、取消订单、确认收货。\r\n- 查询订单状态、物流概览与物流轨迹。\r\n\r\n### ❌ 边界与限制\r\n\r\n- **图搜不在范围**：以图搜图使用 `linkfox-1688-search-by-image`，本技能不包含图搜脚本。\r\n- **授权前置**：除 `authorize_url.py` 和 `authorized_stores.py` 外，每个采购操作调用目标 endpoint 前都会先检查当前用户 ACTIVE 且未过期的 1688 授权；无授权时不调用目标 endpoint。\r\n- **非自动化闭环**：视作流程地图而非全自动执行；不因\"继续\"\"可以\"等前文措辞自动创建订单、获取支付链接、取消订单或确认收货。\r\n- **回调端点不暴露**：`/alibaba1688/proxy/callback`、`/alibaba1688/authorizeCallback`、浏览器 OAuth 回调 URL 不作为 Skill 能力。\r\n- **不索要凭据**：不向用户索要 1688 token、refresh token、callback code、app secret；token 闭环由 MyERP/ecom-plat 后端完成。\r\n- **不查后端库**：不查后端库判断授权状态，使用 `authorizedStores`。\r\n- **不自动重试**：高风险写操作失败不自动重试；不使用 `_dataQuery_executeDynamicQuery` 获取实时采购响应。\r\n- **MCP 与 HTTP 分离**：MCP 启停只控制 MCP 暴露；脚本直连 tool-gateway HTTP route，彻底停用需关 route 或后端能力。\r\n- **成本约束**：调用消耗积分；失败、空结果、参数不全或授权不足时不自动连续试探或轮询，继续查询前先向用户说明会产生额外消耗。\r\n\r\n## 执行流程\r\n\r\n采购流程按步骤协助用户完成，不能一次性自动执行完整下单闭环。每一步均不可跳过授权前置与高风险确认。\r\n\r\n### 步骤 1：授权检查\r\n\r\n- 【输入】当前 LinkFox 用户身份（来自 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY`）。\r\n- 【动作】运行 `authorized_stores.py`，检查是否存在 `status=ACTIVE` 且 `expired=false` 的 1688 授权。\r\n- 【输出】有 ACTIVE 授权 → 可继续采购；无 ACTIVE 授权 → 进入步骤 2。浏览器跳到 MyERP 登录页不等于授权失败，以脚本返回为准。\r\n\r\n### 步骤 2：发起授权（仅未授权时）\r\n\r\n- 【输入】当前用户身份。\r\n- 【动作】运行 `authorize_url.py` 获取 1688 授权链接，让用户在浏览器完成 OAuth；完成后重新运行 `authorized_stores.py` 验证。\r\n- 【输出】ACTIVE 授权账号出现 → 回到步骤 1 确认后继续。不要让用户提供 token、refresh token 或 callback code。\r\n\r\n### 步骤 3：SKU 与收货地址查询\r\n\r\n- 【输入】`offerId`（用户提供，或从 `linkfox-1688-search-by-image` 结果获得）。\r\n- 【动作】运行 `sku.py` 查 SKU/规格、价格、起订量、库存；运行 `receive_address_list.py` 查当前用户 1688 收货地址。\r\n- 【输出】SKU、规格、价格、起订量、库存；收货人、手机/电话、省市区详细地址、`addressId`。多地址时让用户明确选择，不猜测默认地址。\r\n\r\n### 步骤 4：下单预览\r\n\r\n- 【输入】`offerId`、SKU/规格、数量、收货地址、schema 要求的其他交易字段。\r\n- 【动作】运行 `order_preview.py`。\r\n- 【输出】商品/offerId、SKU/规格、数量、单价与商品总价、运费、收货地址、订单总额、买家留言、异常/库存/价格变化提示。预览失败 → 停止，不进入创建订单，向用户说明并重新确认参数。\r\n\r\n### 步骤 5：创建订单（高风险）\r\n\r\n- 【输入】预览通过的下单参数、用户对本次订单的单独中文确认（如\"确认创建这个订单\"）。\r\n- 【动作】用户单独确认后，Agent 在 payload 中自动加入 JSON boolean `confirmCreateOrder=true`，运行 `create_order.py`。\r\n- 【输出】订单号与下单结果。`create_order.py` 会本地拒绝缺少 `confirmCreateOrder=true` 的请求。失败不自动重试。\r\n\r\n### 步骤 6：获取支付链接（高风险）\r\n\r\n- 【输入】订单号、用户对获取该订单支付链接的单独中文确认（如\"确认获取支付链接\"）。\r\n- 【动作】Agent 在 payload 中自动加入 `confirmGetPaymentUrl=true`，运行 `payment_url.py`。\r\n- 【输出】支付链接。创建订单成功不等于用户同意获取支付链接，必须独立确认。失败不自动重试。\r\n\r\n### 步骤 7：订单状态与物流跟踪\r\n\r\n- 【输入】订单号（物流轨迹另需物流标识，以 schema 为准）。\r\n- 【动作】按用户请求运行 `order_status.py`、`logistics.py`、`logistics_trace.py`。\r\n- 【输出】订单状态、物流概览、物流轨迹。仍消耗积分，无用户要求时不连续轮询。\r\n\r\n### 步骤 8：取消订单（高风险）\r\n\r\n- 【输入】`orderId`、取消原因（如 schema 要求）、用户对该订单的单独中文确认（如\"确认取消这个订单\"）。\r\n- 【动作】先展示 `orderId`、当前订单状态、取消原因、可能的履约或退款影响；用户单独确认后，Agent 在 payload 加入 `confirmCancel=true`，运行 `cancel_order.py`。\r\n- 【输出】取消结果。失败不自动重试，避免重复取消。\r\n\r\n### 步骤 9：确认收货（高风险）\r\n\r\n- 【输入】`orderId`、用户对确认收货的单独中文确认（如\"确认收货\"）。\r\n- 【动作】用户查询物流、看到已签收、或问\"状态怎么样\"都不等于确认收货；用户明确确认后，Agent 在 payload 加入 `confirmReceive=true`，运行 `confirm_receive.py`。\r\n- 【输出】确认收货结果。失败不自动重试，避免重复确认。\r\n\r\n## 高风险确认字段\r\n\r\n用户侧只需用中文自然语言做单独明确确认，不要要求用户输入英文参数名或 `=true`。Agent 收到中文确认后调用脚本时自动加入对应 JSON boolean 安全字段（必须为 boolean `true`，字符串 `\"true\"`、数字 `1` 均被本地拒绝）。\r\n\r\n| 操作 | 必填字段 |\r\n|---|---|\r\n| `createOrder` | `confirmCreateOrder=true` |\r\n| `paymentUrl` | `confirmGetPaymentUrl=true` |\r\n| `confirmReceive` | `confirmReceive=true` |\r\n| `cancelOrder` | `confirmCancel=true` |\r\n\r\n## 调用方式\r\n\r\n- **API 端点**：`POST /alibaba1688/{authorizeUrl|authorizedStores|receiveAddressList|sku|orderPreview|createOrder|paymentUrl|orderStatus|logistics|logisticsTrace|confirmReceive|cancelOrder}`（完整参数、响应与错误处理见 [references/api.md](references/api.md)）。\r\n- **Python 脚本**：`python scripts/<script_name>.py '<JSON 参数>' [--inline] [--save] [--no-save]`。\r\n- **Windows 推荐**：`$env:PAYLOAD = '<JSON 参数>'` 后运行 `python scripts/<script_name>.py --payload-env PAYLOAD [--inline] [--save]`。\r\n\r\n```powershell\r\n$env:PAYLOAD = \"{}\"\r\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\r\n```\r\n\r\n**脚本入参方式**：直接传 JSON 字符串、`--payload-env PAYLOAD`、`--payload-file payload.json`；`--inline` 强制全量打印到 stdout；`--save` 强制保存脱敏完整响应；`--no-save` 禁止保存。\r\n\r\n**输出策略**：响应体 ≤ 8 KB 默认不落盘，直接把完整脱敏 JSON 打印到 stdout；> 8 KB 默认写入 `<writable-root>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-1688-procurement-<operation>-<timestamp>.json`，stdout 只输出摘要。`<writable-root>` 优先取 `ACPX_WORKSPACES` 第一个工作区，其次当前目录，最后用户目录；`<session>` 取自 `SESSION_ID`，未提供时自动生成；禁止写入 `/tmp`。加 `--save` 或 `LINKFOX_SKILL_SAVE_RESPONSE=1` 强制保存；`--no-save` 或 `LINKFOX_SKILL_NO_SAVE=1` 禁止保存。\r\n\r\n**读数据建议**：先看 stdout 摘要判断是否足够；需要完整响应再加 `--save`，之后用 `jq` 或 `ConvertFrom-Json` 从保存的 JSON 按需抽取，避免整份 JSON 进入上下文。\r\n\r\n## 展示规则\r\n\r\n1. 采购依赖 OAuth 时先展示授权状态；不单凭浏览器跳转判断授权。\r\n2. `authorizedStores` 输出是当前 LinkFox 用户的 1688 授权状态，不要描述成数据库全库账号列表。\r\n3. 永不展示完整 API key、JWT、access token、refresh token、callback code、app secret、session key、Authorization header。\r\n4. 清晰展示下单预览：商品/offerId、SKU/规格、数量、单价、商品总价、运费、收货地址、订单总额、买家留言、警告。\r\n5. 高风险调用前复述精确操作、关键 ID、金额/状态（如可得），请用户中文确认；不要求用户输入内部 boolean 字段。\r\n6. 收货地址展示到足以安全选择即可，避免不必要地重复完整手机号或敏感地址细节。\r\n7. 返回 `costToken` 或等价成本字段时如实展示。\r\n\r\n## 用户表达与场景速查\r\n\r\n**适用** —— 1688 已授权采购履约：\r\n\r\n| 用户说 | 场景 |\r\n|--------|------|\r\n| \"查询我的1688授权店铺\" / \"show my authorized 1688 stores\" | 授权检查 |\r\n| \"生成1688授权链接\" / \"authorize my 1688 account\" | 发起新授权 |\r\n| \"查这个 offerId 的 SKU\" | SKU 查询 |\r\n| \"查1688收货地址\" | 收货地址查询 |\r\n| \"帮我预览1688订单\" | 下单预览 |\r\n| \"确认下单\" | 高风险创建订单门 |\r\n| \"获取支付链接\" | 高风险支付链接门 |\r\n| \"查1688订单状态/物流\" | 订单跟踪 |\r\n| \"取消这个1688订单\" | 高风险取消门 |\r\n| \"确认收货\" | 高风险确认收货门 |\r\n\r\n不适用场景见上方【能力边界】。\r\n\r\n## 解决认证和积分问题\r\n\r\n发生以下异常情况时，采用以下措施来处理：\r\n\r\n### 异常情况\r\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\r\n- **响应401或402状态码**\r\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\r\n\r\n### 措施\r\n- 优先采用skill内的 onboarding.md 引导解决问题。\r\n- 如找不到 onboarding.md 文件，则加载 /linkfox-onboarding 这个skill并根据它的引导来处理。如未安装请先安装：\r\n    - 下载 https://agent-files.linkfox.com/skills/linkfox-onboarding/release.zip，解压后安装这个skill。\r\n\r\n---\r\n\r\n# 1688采购流程 API 参考\r\n\r\n本文记录 `linkfox-1688-procurement` 的 tool-gateway 调用规范、脚本入口、风险等级和关键字段。具体入参以网关当前 MCP schema 为准。\r\n\r\n## 调用规范\r\n\r\n- 请求地址：`${LINKFOX_TOOL_GATEWAY}<path>`，默认网关为 `https://tool-gateway.linkfox.com`\r\n- 请求方式：`POST`\r\n- Content-Type：`application/json; charset=utf-8`\r\n- 认证方式：Header `Authorization: <api_key>`\r\n- API key 读取顺序：`LINKFOX_AGENT_API_KEY`，然后 `LINKFOXAGENT_API_KEY`（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\r\n- User-Agent：`LinkFox-Skill/2.0`\r\n- 透传 Header：`SESSION_ID`、`MODE_ID`、`APP_NAME`\r\n- 超时：120s\r\n- 输出保存：小响应默认不落盘；大响应、`--save` 或 `LINKFOX_SKILL_SAVE_RESPONSE=1` 时保存脱敏完整响应；`--no-save` 或 `LINKFOX_SKILL_NO_SAVE=1` 可禁止保存\r\n- 缓存策略：不做 24h 响应缓存。授权、价格、库存、订单状态和物流以实时返回为准，高风险写操作不得缓存或自动重放。\r\n\r\nWindows 推荐使用 `--payload-env` 或 `--payload-file`，避免 shell 转义破坏 JSON。\r\n\r\n```powershell\r\n$env:PAYLOAD = \"{}\"\r\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\r\n```\r\n\r\n## 授权规则\r\n\r\n`authorizedStores` 是当前 LinkFox 用户的 1688 OAuth 授权检查入口。它依赖 API key 中的 LinkFox 用户身份，后端应只返回当前用户的授权店铺。\r\n\r\n脚本层规则：\r\n\r\n- `authorizeUrl` 不做 1688 OAuth 前置检查，因为它用于发起授权。\r\n- `authorizedStores` 不做 1688 OAuth 前置检查，因为它本身就是检查入口。\r\n- 其他采购操作在调用目标 endpoint 前，脚本会先调用 `authorizedStores`。\r\n- 没有 `status=ACTIVE` 且 `expired=false` 的店铺时，脚本返回 `authorization_required`，不会调用目标 endpoint。\r\n\r\n这层检查不能替代后端鉴权；后端仍必须按 `Token.uid` 或等价用户身份过滤和校验授权。\r\n\r\n## MCP 与 Skill 暴露关系\r\n\r\nMCP 工具启停和 Skill HTTP 调用是两层能力：\r\n\r\n| 层级 | 控制内容 | 对本 Skill 的影响 |\r\n|---|---|---|\r\n| MCP tool enabled | 是否出现在 MCP 工具列表或 Agent 工具调用面 | 不决定脚本是否能 HTTP 调用 |\r\n| Gateway route enabled | tool-gateway 是否转发对应 HTTP path | 决定脚本是否可用 |\r\n| Backend capability enabled | ecom-plat 是否处理业务 | 决定最终业务是否可用 |\r\n\r\n因此，MCP 停用但 gateway route 仍启用时，Skill 脚本可以继续使用。若要完全停用某能力，应关闭 gateway route 或后端能力。\r\n\r\n## 禁止作为 Skill 能力的端点\r\n\r\n以下是授权闭环或 MyERP/ecom-plat 后端回调路径，不是 MCP 工具，不应写成 Skill 脚本：\r\n\r\n- `/alibaba1688/proxy/callback`\r\n- `/alibaba1688/authorizeCallback`\r\n- `/alibaba1688/oauth/callback`\r\n\r\n## API 与脚本一览\r\n\r\n| 能力 | MCP tool | Path | Script | 风险 | OAuth 前置检查 | 确认字段 |\r\n|---|---|---|---|---|---|---|\r\n| 生成授权链接 | `_alibaba1688_authorizeUrl` | `/alibaba1688/authorizeUrl` | `authorize_url.py` | 低 | 否 | - |\r\n| 查询已授权账号 | `_alibaba1688_authorizedStores` | `/alibaba1688/authorizedStores` | `authorized_stores.py` | 低 | 否 | - |\r\n| 查询收货地址 | `_alibaba1688_receiveAddressList` | `/alibaba1688/receiveAddressList` | `receive_address_list.py` | 低 | 是 | - |\r\n| 查询 SKU | `_alibaba1688_sku` | `/alibaba1688/sku` | `sku.py` | 低 | 是 | - |\r\n| 下单预览 | `_alibaba1688_orderPreview` | `/alibaba1688/orderPreview` | `order_preview.py` | 中 | 是 | - |\r\n| 创建订单 | `_alibaba1688_createOrder` | `/alibaba1688/createOrder` | `create_order.py` | 高 | 是 | `confirmCreateOrder=true` |\r\n| 获取支付链接 | `_alibaba1688_paymentUrl` | `/alibaba1688/paymentUrl` | `payment_url.py` | 高 | 是 | `confirmGetPaymentUrl=true` |\r\n| 查询订单状态 | `_alibaba1688_orderStatus` | `/alibaba1688/orderStatus` | `order_status.py` | 低 | 是 | - |\r\n| 查询物流 | `_alibaba1688_logistics` | `/alibaba1688/logistics` | `logistics.py` | 低 | 是 | - |\r\n| 查询物流轨迹 | `_alibaba1688_logisticsTrace` | `/alibaba1688/logisticsTrace` | `logistics_trace.py` | 低 | 是 | - |\r\n| 确认收货 | `_alibaba1688_confirmReceive` | `/alibaba1688/confirmReceive` | `confirm_receive.py` | 高 | 是 | `confirmReceive=true` |\r\n| 取消订单 | `_alibaba1688_cancelOrder` | `/alibaba1688/cancelOrder` | `cancel_order.py` | 高 | 是 | `confirmCancel=true` |\r\n\r\n`_alibaba1688_imageSearch` 由 `linkfox-1688-search-by-image` 独立承担，本 Skill 不包含图搜脚本。\r\n\r\n## 入参要点\r\n\r\n| 能力 | 关键字段说明 |\r\n|---|---|\r\n| `authorizeUrl` | 按 schema 传授权展示字段；如需账号标签，优先使用 `accountName` |\r\n| `authorizedStores` | 通常无需业务参数；用户身份来自 LinkFox API key |\r\n| `receiveAddressList` | 依赖当前用户 ACTIVE 1688 授权 |\r\n| `sku` | 通常需要 `offerId` |\r\n| `orderPreview` | 通常需要 `offerId`、SKU/规格、数量、收货地址等下单参数 |\r\n| `createOrder` | 下单参数与预览保持一致，并必须加 `confirmCreateOrder=true` |\r\n| `paymentUrl` | 通常需要订单号，并必须加 `confirmGetPaymentUrl=true` |\r\n| `orderStatus` | 通常需要订单号 |\r\n| `logistics` | 通常需要订单号 |\r\n| `logisticsTrace` | 通常需要订单号及物流标识，以 schema 为准 |\r\n| `confirmReceive` | 订单号 + `confirmReceive=true` |\r\n| `cancelOrder` | 订单号、取消原因（如 schema 要求）+ `confirmCancel=true` |\r\n\r\n## 高风险校验\r\n\r\n用户侧只需要用中文自然语言做单独明确确认，例如“确认创建这个订单”“确认获取这个订单的支付链接”“确认取消这个订单”“确认收货”。不要要求用户输入英文参数名或 `=true`。\r\n\r\nAgent 在收到中文确认后，调用脚本时必须自动加入对应 JSON boolean 安全字段。高风险脚本会在本地先校验确认字段，确认字段不满足时不会联网：\r\n\r\n| 脚本 | 本地拒绝条件 |\r\n|---|---|\r\n| `create_order.py` | 缺少 JSON boolean `confirmCreateOrder=true` |\r\n| `payment_url.py` | 缺少 JSON boolean `confirmGetPaymentUrl=true` |\r\n| `confirm_receive.py` | 缺少 JSON boolean `confirmReceive=true` |\r\n| `cancel_order.py` | 缺少 JSON boolean `confirmCancel=true` |\r\n\r\n字符串 `\"true\"`、数字 `1`、大小写变体都不算确认。\r\n\r\n## 响应与错误处理\r\n\r\n- HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。\r\n- HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。\r\n- `authorization_required`：没有当前用户 ACTIVE 1688 OAuth 授权；先运行 `authorize_url.py`，用户授权后再运行 `authorized_stores.py` 验证。\r\n- 下单预览失败：停止，不要进入创建订单；向用户说明失败原因并重新确认参数。\r\n- 高风险写操作失败：不要自动重试，避免重复下单、重复取消或重复确认收货。\r\n\r\n## 敏感信息规则\r\n\r\n脚本会对常见敏感字段做脱敏落盘。Agent 展示结果时仍需避免暴露：\r\n\r\n- LinkFox API key / JWT\r\n- 1688 access token / refresh token\r\n- Authorization header\r\n- OAuth callback `code`\r\n- app secret / session key / refresh secret\r\n\r\n---\r\n\r\n# 1688采购流程地图\r\n\r\n本文档是流程地图，不是自动化脚本。Agent 可以按步骤协助用户完成采购，但不能一次性自动执行完整下单闭环。\r\n\r\n## 总原则\r\n\r\n1. 采购业务先查授权，再查商品和地址，再预览，再让用户确认。\r\n2. 图搜找货使用 `linkfox-1688-search-by-image`，本 Skill 只处理采购履约。\r\n3. 除 `authorizeUrl` 和 `authorizedStores` 外，脚本会在每个采购 endpoint 前自动检查当前用户 ACTIVE 授权。\r\n4. 下单、支付链接、取消订单、确认收货都是独立高风险动作，各自需要单独确认。\r\n5. 用户前面说过\"继续\"\"可以\"\"按上面来\"，不能作为后续高风险动作的确认。\r\n\r\n## 1. 授权检查\r\n\r\n运行：\r\n\r\n```powershell\r\n$env:PAYLOAD = \"{}\"\r\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\r\n```\r\n\r\n判断：\r\n\r\n- 有 `status=ACTIVE` 且 `expired=false`：可以继续采购流程。\r\n- 没有 ACTIVE 授权：进入授权步骤。\r\n- 浏览器最后跳到 MyERP 登录页不等于授权失败；以 `authorized_stores.py` 返回为准。\r\n\r\n`authorizedStores` 应只返回当前 LinkFox API key 对应用户的授权店铺。不要把它理解为后台全库账号列表。\r\n\r\n## 2. 发起授权\r\n\r\n运行 `authorize_url.py` 获取 1688 授权链接，并让用户在浏览器打开。\r\n\r\n用户完成授权后，再运行 `authorized_stores.py` 验证是否出现 ACTIVE 账号。\r\n\r\n不要让用户提供 1688 token、refresh token 或 callback code。授权 token 保存由 MyERP/ecom-plat 后端闭环完成。\r\n\r\n## 3. 找货与 SKU\r\n\r\n如果用户按图片找货：\r\n\r\n1. 切换到 `linkfox-1688-search-by-image`。\r\n2. 从图搜结果中选择目标 `offerId`。\r\n3. 回到本 Skill，用 `sku.py` 查询 SKU/规格。\r\n\r\n如果用户已提供 `offerId`：\r\n\r\n1. 直接运行 `sku.py`。\r\n2. 展示 SKU、规格、价格、起订量、库存等关键字段。\r\n3. 让用户选择明确的 SKU 和数量。\r\n\r\n## 4. 收货地址\r\n\r\n运行 `receive_address_list.py` 查询当前用户可用的 1688 收货地址。\r\n\r\n展示地址时应包含：\r\n\r\n- 收货人\r\n- 手机/电话（如返回）\r\n- 省市区与详细地址\r\n- `addressId` 或等价标识\r\n\r\n不要猜测默认地址。多地址时让用户明确选择。\r\n\r\n## 5. 下单预览\r\n\r\n运行 `order_preview.py` 前确认已具备：\r\n\r\n- `offerId`\r\n- SKU/规格\r\n- 数量\r\n- 收货地址\r\n- schema 要求的其他交易字段\r\n\r\n预览结果必须先展示给用户：\r\n\r\n- 商品/offerId\r\n- SKU/规格\r\n- 数量\r\n- 单价与商品总价\r\n- 运费\r\n- 收货地址\r\n- 订单总额\r\n- 任何异常、库存或价格变化提示\r\n\r\n预览失败时停止，不要进入创建订单。\r\n\r\n## 6. 创建订单\r\n\r\n创建订单是高风险动作。必须先询问用户是否确认创建该订单，并复述预览摘要。用户只需要中文自然语言确认，例如\"确认创建这个订单\"；不要要求用户输入 `confirmCreateOrder=true`。\r\n\r\n只有用户针对本次订单明确确认后，Agent 才在脚本 payload 中自动加入：\r\n\r\n```json\r\n{\r\n  \"...\": \"order payload\",\r\n  \"confirmCreateOrder\": true\r\n}\r\n```\r\n\r\n`create_order.py` 会拒绝缺少 `confirmCreateOrder=true` 的请求。\r\n\r\n## 7. 获取支付链接\r\n\r\n获取支付链接也是独立高风险动作。创建订单成功不等于用户同意获取支付链接。用户只需要中文自然语言确认，例如\"确认获取支付链接\"；不要要求用户输入 `confirmGetPaymentUrl=true`。\r\n\r\n用户单独确认后，Agent 在脚本 payload 中自动加入：\r\n\r\n```json\r\n{\r\n  \"orderId\": \"...\",\r\n  \"confirmGetPaymentUrl\": true\r\n}\r\n```\r\n\r\n## 8. 订单状态与物流\r\n\r\n查询类动作可在用户请求时执行：\r\n\r\n- `order_status.py`\r\n- `logistics.py`\r\n- `logistics_trace.py`\r\n\r\n这些仍然会消耗积分。不要在没有用户要求的情况下连续轮询。\r\n\r\n## 9. 取消订单\r\n\r\n取消订单是高风险动作。执行前展示：\r\n\r\n- `orderId`\r\n- 当前订单状态\r\n- 取消原因\r\n- 可能的履约或退款影响（如响应中可判断）\r\n\r\n只有用户针对该订单明确确认取消后，Agent 才运行 `cancel_order.py`，并在脚本 payload 中自动加入：\r\n\r\n```json\r\n{\r\n  \"orderId\": \"...\",\r\n  \"confirmCancel\": true\r\n}\r\n```\r\n\r\n## 10. 确认收货\r\n\r\n确认收货是高风险动作。用户查询物流、看到已签收、或问\"状态怎么样\"，都不等于确认收货。\r\n\r\n只有用户明确确认收货后，Agent 才运行 `confirm_receive.py`，并在脚本 payload 中自动加入：\r\n\r\n```json\r\n{\r\n  \"orderId\": \"...\",\r\n  \"confirmReceive\": true\r\n}\r\n```\r\n\r\n## MCP 与 Skill 分离\r\n\r\nMCP 停用只表示该工具不再通过 MCP 工具列表暴露。只要 tool-gateway 对应 HTTP route 仍启用，本 Skill 的脚本仍可通过 HTTP 调用。\r\n\r\n如果需要彻底禁用某个采购能力，需要关闭对应 gateway route 或后端能力，而不是只从 MCP 列表移除。\n\nFile v1.2.2:references/linkfox-1688-search-by-image.md\n\n---\r\nname: linkfox-1688-search-by-image\r\ndescription: 通过图片 URL 在 1688 平台以图搜图，检索外观相似或同款货源的商品数据。\r\n\r\n# 1688 以图搜图（1688 Image-Based Product Search）\r\n\r\n本技能通过图片 URL 在 1688 平台进行以图搜图，帮助跨境卖家找到外观相似或同款的 1688 货源商品。参数与响应字段详见 [references/api.md](references/api.md)。\r\n\r\n## 能力边界\r\n\r\n### ✅ 能力范围\r\n\r\n- 通过图片 URL、Base64 或 imageId 在 1688 平台进行视觉检索，返回外观相似或同款的货源商品。\r\n- 提供商品标题、批发价、一件代发价、月销量、起批量、复购率、交易评分、商家身份等核心数据。\r\n- 支持按价格区间、过滤条件（1688 严选、认证工厂、发货时效、品质退款率等）、排序（价格/月销/复购率）、分页查询。\r\n\r\n### ❌ 边界与限制\r\n\r\n- **图片来源**：`imageUrl`/`imageBase64`/`imageId` 三选一必填；`imageUrl` 须为可公开访问的公网链接。\r\n- **图片格式**：仅支持 png/jpg/jpeg，不支持 webp/gif 等格式。\r\n- **Base64 格式**：`imageBase64` 必须为纯编码内容，不能包含 `data:image/jpeg;base64,` 前缀。\r\n- **分页上限**：每页最多 50 条；`page > 1` 时建议回传 `imageId` 以加速查询。\r\n- **数据时效**：结果为实时搜索，不入库，无法进行二次 SQL 或 `_dataQuery_executeDynamicQuery` 处理。\r\n- **筛选/排序限制**：仅支持预设的过滤条件与排序字段；用户请求未列出的排序或过滤条件时，不要调用其他工具或逻辑兜底，应告知支持的选项。\r\n- **本地图片**：本工具需要可公开访问的图片 URL；用户提供本地文件路径时，须先调用上传脚本获取公网 URL（见下方「本地图片上传」）。\r\n- **不在范围内**：基于关键词的 1688 文本搜索（用店雷达-1688 选品库）；1688 商品排行/趋势（用店雷达-1688 商品榜单）；Amazon 以图搜图（用亚马逊前端-以图搜图）；图片生成或编辑；商品评论分析；价格历史或趋势分析。\r\n\r\n## 核心概念\r\n\r\n1688 以图搜图基于视觉识别，在 1688 批发平台查找外观相似的商品，返回供应商商品数据，包括标题、价格、起批量、月销量、复购率、交易评分及商家身份标识。\r\n\r\n**默认行为**：第 1 页、每页 20 条，按月销量降序（`sort` 默认 `{\"monthSold\":\"desc\"}`）。\r\n\r\n## 调用方式\r\n\r\n- **API 端点**：`POST /alibaba1688/imageSearch`（完整参数/响应/错误码见 `references/api.md`）\r\n- **Python 脚本**：`python scripts/alibaba1688_image_search.py '<JSON 参数>' [--inline]`\r\n- **成本约束**：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。\r\n\r\n**输出策略（脚本默认行为）**：\r\n- **始终**将完整响应写入 `<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-1688-search-by-image-<timestamp>.json`（`<cwd>` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`<session>` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\r\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\r\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\r\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\r\n\r\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq` 或 `ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\r\n\r\n## 本地图片上传\r\n\r\n本工具需要**可公开访问的图片 URL**。若用户提供本地图片文件路径，须先上传以获取公网 URL。\r\n\r\n运行上传脚本：\r\n```bash\r\npython scripts/upload_image.py /path/to/local/image.png\r\n```\r\n\r\n脚本会返回一个公网 URL（有效期 24 小时），可作为 `imageUrl` 参数使用。\r\n\r\n## 使用示例\r\n\r\n**1. 基础以图搜图**\r\n```\r\n在1688搜索与图片相似的商品，图片地址为 https://m.media-amazon.com/images/I/719mRAn2VrL._AC_SL1500_.jpg\r\n```\r\n\r\n**2. 带筛选条件**\r\n```\r\n在1688搜索与图片相似的商品，图片地址为 https://m.media-amazon.com/images/I/719mRAn2VrL._AC_SL1500_.jpg，查询第1页，筛选1688严选，并按价格从高到低排序\r\n```\r\n\r\n**3. 按排序查询**\r\n```\r\n在1688搜索与图片相似的商品，图片地址为 https://example.com/product.jpg，按价格从高到低排序\r\n```\r\n\r\n**4. 分页查询**\r\n```\r\n在1688搜索与图片相似的商品，图片地址为 https://example.com/product.jpg，查询第2页，每页50条\r\n```\r\n\r\n**5. 价格区间筛选**\r\n```\r\n在1688搜索与图片相似的商品，图片地址为 https://example.com/product.jpg，价格区间10-100元\r\n```\r\n\r\n## 展示规则\r\n\r\n1. **清晰呈现数据**：以结构化表格展示关键列——商品图片、标题、批发价、代发价、月销量、起批量、复购率、商家身份。\r\n2. **图片展示**：返回 `imageUrl` 时内联展示商品图片，便于直观对比。\r\n3. **价格格式**：价格统一以人民币（¥）格式展示。\r\n4. **商家标识**：突出展示商家身份（超级工厂/实力商家/诚信通会员）与商品标（严选）。\r\n5. **结果计数**：始终告知总结果数及当前页/总页数。\r\n6. **分页提示**：还有更多页时，提示用户可继续翻页。\r\n7. **筛选/排序限制**：用户请求未支持的排序或过滤条件时，不要尝试任何兜底，告知其支持的选项即可。\r\n8. **不做二次处理**：结果为实时搜索数据，不入库，无法进行二次 SQL 或数据处理。\r\n\r\n## 用户表达与场景速查\r\n\r\n**适用** —— 1688 平台以图找货源场景：\r\n\r\n| 用户说 | 场景 |\r\n|--------|------|\r\n| \"1688以图搜图\" / \"用图片找1688货源\" | 基础以图搜图 |\r\n| \"帮我在1688找这个图片的同款\" | 找同款商品 |\r\n| \"跨境找工厂，图片是...\" | 跨境供应商找货 |\r\n| \"这个Amazon产品在1688有没有货源\" | 由 Amazon 图片反查 1688 货源 |\r\n| \"筛选1688严选的相似商品\" | 带筛选的以图搜图 |\r\n| \"按月销量排序找相似货源\" | 带排序的以图搜图 |\r\n| \"查看第2页结果\" | 分页查询 |\r\n\r\n不适用场景见上方【能力边界】。\r\n\r\n**边界判断**：当用户说\"找货源\"或\"找同款\"时，若其提供了图片 URL 且意图是在 1688 上找外观相似商品，则适用本技能；若需基于关键词搜索或排行数据，改用店雷达工具。\r\n\r\n## 解决认证和积分问题\r\n\r\n发生以下异常情况时，采用以下措施来处理：\r\n\r\n### 异常情况\r\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\r\n- **响应401或402状态码**\r\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\r\n\r\n### 措施\r\n- 优先采用skill内的 onboarding.md 引导解决问题。\r\n- 如找不到 onboarding.md 文件，则加载 /linkfox-onboarding 这个skill并根据它的引导来处理。如未安装请先安装：\r\n    - 下载 https://agent-files.linkfox.com/skills/linkfox-onboarding/release.zip，解压后安装这个skill。\r\n\r\n---\r\n\r\n# 1688-以图搜图 API 参考\r\n\r\n## 调用规范\r\n\r\n- **请求地址**：`${LINKFOX_TOOL_GATEWAY}/alibaba1688/imageSearch`\r\n- **请求方式**：POST，Content-Type: application/json\r\n- **认证方式**：Header `Authorization: <api_key>`，api_key 优先从环境变量 `LINKFOX_AGENT_API_KEY` 读取，回退 `LINKFOXAGENT_API_KEY`（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\r\n- **User-Agent**：`LinkFox-Skill/1.0`\r\n- **超时**：60s\r\n\r\n## 请求参数\r\n\r\nPOST Body（JSON）：\r\n\r\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\r\n|------|------|------|--------|------|\r\n| imageUrl | string | 条件必填 | - | 图片URL地址，请确保图片URL有效且可公开访问。最大长度：1000。仅支持 png/jpg/jpeg 格式，不支持 webp/gif 等。imageUrl/imageBase64/imageId 三选一必填 |\r\n| imageBase64 | string | 条件必填 | - | 图片 Base64 编码字符串，为纯编码内容，不包含 `data:image/jpeg;base64,` 前缀。仅支持 png/jpg/jpeg 格式（imageUrl为空时使用） |\r\n| imageId | string | 条件必填 | - | 图片ID（1688图片ID），以图搜图查询结果中也会返回，建议当分页 page>1 查询时带 imageId，加快响应速度 |\r\n| page | int | 否 | 1 | 页码，从1开始 |\r\n| pageSize | int | 否 | 20 | 每页返回的商品数量，最大不超过50 |\r\n| priceStart | string | 否 | - | 价格筛选起始值（人民币），如 10 |\r\n| priceEnd | string | 否 | - | 价格筛选结束值（人民币），如 100 |\r\n| filter | string | 否 | - | 过滤条件，多个条件用逗号分隔。有效值见下方「支持的过滤条件」 |\r\n| sort | string | 否 | {\"monthSold\":\"desc\"} | 排序条件，JSON格式 {排序字段: 排序方式}。有效字段：price、rePurchaseRate、monthSold；方式：asc/desc |\r\n| keyword | string | 否 | - | 关键词，在结果中搜索 |\r\n| productCollectionId | string | 否 | - | 货盘ID，单选。有效值见下方「支持的货盘ID」 |\r\n\r\n### 支持的过滤条件\r\n\r\n多个条件用逗号分隔，如 `1688Selection,totalEpScoreLv1,qrr0`。\r\n\r\n| 值 | 说明 |\r\n|----|------|\r\n| 1688Selection | 1688严选 |\r\n| certifiedFactory | 认证工厂 |\r\n| totalEpScoreLv1 | 综合体验分5星 |\r\n| totalEpScoreLv2 | 综合体验分4星 |\r\n| totalEpScoreLv3 | 综合体验分3星 |\r\n| totalEpScoreLv4 | 综合体验分2星 |\r\n| qrr0 | 无品质退款 |\r\n| qrr1 | 品质退款率<1% |\r\n| qrr5 | 品质退款率<5% |\r\n| qrr10 | 品质退款率<10% |\r\n| shipInToday | 当日发货 |\r\n| shipIn24Hours | 24小时发货 |\r\n| shipIn48Hours | 48小时发货 |\r\n| noReason7DReturn | 7天无理由退货 |\r\n| isOnePsale | 一件代发 |\r\n| isOnePsaleFreePost | 一件代发包邮 |\r\n| new7 | 7天内新品 |\r\n| new30 | 30天内新品 |\r\n| isQqyx | 全球严选 |\r\n| JPFL | 日本专线 |\r\n| USFL | 美国专线 |\r\n| KRFL | 韩国专线 |\r\n| VNFL | 越南专线 |\r\n| SAFL | 沙特专线 |\r\n| RUFL | 俄罗斯专线 |\r\n| KZFL | 哈萨克斯坦专线 |\r\n| HKFL | 香港专线 |\r\n| MOFL | 澳门专线 |\r\n| TWFL | 台湾专线 |\r\n\r\n### 支持的排序字段\r\n\r\n| 字段 | 说明 |\r\n|------|------|\r\n| price | 价格 |\r\n| monthSold | 月销量 |\r\n| rePurchaseRate | 复购率 |\r\n\r\n排序方式：`asc`（升序）、`desc`（降序）。格式示例：`{\"price\":\"asc\"}`\r\n\r\n### 支持的货盘ID\r\n\r\n| ID | 说明 |\r\n|----|------|\r\n| 262105288 | 跨境货盘 |\r\n| 262105286 | 跨境货盘 |\r\n| 262105253 | 跨境货盘 |\r\n| 262105281 | 跨境货盘 |\r\n| 262105280 | 跨境货盘 |\r\n| 262105277 | 跨境货盘 |\r\n| 262105276 | 跨境货盘 |\r\n| 262105274 | 跨境货盘 |\r\n| 262105269 | 跨境货盘 |\r\n| 262185282 | 跨境货盘 |\r\n\r\n## 响应结构\r\n\r\n| 字段 | 类型 | 说明 |\r\n|------|------|------|\r\n| imageId | string | 上传后的图片ID（分页查询时回传可加速） |\r\n| total | integer | 本页商品数量 |\r\n| totalPage | integer | 总页数 |\r\n| sourceType | string | 来源类型（固定值 \"1688\"） |\r\n| type | string | 渲染样式（固定值 \"productWorkbenches\"） |\r\n| columns | array | 渲染列定义 |\r\n| costToken | integer | 消耗 token |\r\n| products | array | 商品列表（详见下方商品字段） |\r\n\r\n### 商品字段\r\n\r\n| 字段 | 类型 | 说明 |\r\n|------|------|------|\r\n| offerId | string | 商品ID |\r\n| asin | string | 商品编号（同 offerId） |\r\n| imageUrl | string | 商品图片 |\r\n| title | string | 商品标题 |\r\n| price | number | 批发价（元） |\r\n| consignPrice | number | 一件代发价（元） |\r\n| salesQuantity | integer | 月销售件数 |\r\n| estimatedSalesAmount | number | 预估销售额 |\r\n| asinUrl | string | 商品链接 |\r\n| isOnePsale | string | 是否一件代发（是/否） |\r\n| isJxhy | string | 是否精选货源（是/否） |\r\n| sellerIdentities | string | 商家身份（超级工厂/实力商家/诚信通会员） |\r\n| offerIdentities | string | 商品标（严选） |\r\n| repurchaseRate | string | 复购率 |\r\n| tradeScore | string | 商品交易评分 |\r\n| compositeServiceScore | string | 综合服务体验分 |\r\n| sendGoodsAddressText | string | 发货地 |\r\n| deliveryTime | string | 发货时间（24/48小时） |\r\n| quantityBegin | integer | 起批量 |\r\n| hasPromotion | string | 是否有营销活动（是/否） |\r\n| promotionType | string | 营销类型 |\r\n| isPatentProduct | string | 是否专利商品（是/否） |\r\n| isSelect | string | 跨境select货盘标识 |\r\n| currency | string | 币种（固定值 \"¥\"） |\r\n| sourceType | string | 来源类型（固定值 \"1688\"） |\r\n| sourceTool | string | 来源工具（固定值 \"1688以图搜图\"） |\r\n| dataType | string | 数据类型（固定值 \"monthlyData\"） |\r\n\r\n## 错误码\r\n\r\n正常情况下，接口的 HTTP 状态码均为 200，业务的成功与否通过响应体中的 errorCode 字段区分（errorCode = 200 表示成功，其他值表示业务错误）。当遇到未授权等情况时，HTTP 状态码为 401，且对应的 errorCode 也是 401。\r\n\r\n| errcode | 含义 | 处理建议 |\r\n|---------|------|----------|\r\n| 200 | 成功 | 正常解析业务字段 |\r\n| 401 | 认证失败 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。 |\r\n| 402 | 积分不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。 |\r\n| 其他非200值 | 业务异常 | 参考 `errmsg` 字段获取具体错误原因 |\r\n\r\n错误响应示例：\r\n\r\n```json\r\n{\r\n    \"errcode\": 401,\r\n    \"errmsg\": \"authorized error\"\r\n}\r\n```\r\n\r\n## curl 示例\r\n\r\n### 基础以图搜图\r\n\r\n```bash\r\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/imageSearch \\\r\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -H \"User-Agent: LinkFox-Skill/1.0\" \\\r\n  -d '{\r\n    \"imageUrl\": \"https://m.media-amazon.com/images/I/719mRAn2VrL._AC_SL1500_.jpg\",\r\n    \"page\": 1,\r\n    \"pageSize\": 20\r\n  }'\r\n```\r\n\r\n### 带筛选和排序\r\n\r\n```bash\r\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/imageSearch \\\r\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -H \"User-Agent: LinkFox-Skill/1.0\" \\\r\n  -d '{\r\n    \"imageUrl\": \"https://m.media-amazon.com/images/I/719mRAn2VrL._AC_SL1500_.jpg\",\r\n    \"page\": 1,\r\n    \"pageSize\": 20,\r\n    \"filter\": \"1688Selection,totalEpScoreLv1,qrr0\",\r\n    \"sort\": \"{\\\"price\\\":\\\"desc\\\"}\"\r\n  }'\r\n```\r\n\r\n### 分页查询（使用 imageId）\r\n\r\n```bash\r\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/imageSearch \\\r\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -H \"User-Agent: LinkFox-Skill/1.0\" \\\r\n  -d '{\r\n    \"imageId\": \"abc123456\",\r\n    \"page\": 2,\r\n    \"pageSize\": 20\r\n  }'\r\n```\r\n\r\n### 价格区间筛选\r\n\r\n```bash\r\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/imageSearch \\\r\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -H \"User-Agent: LinkFox-Skill/1.0\" \\\r\n  -d '{\r\n    \"imageUrl\": \"https://m.media-amazon.com/images/I/719mRAn2VrL._AC_SL1500_.jpg\",\r\n    \"page\": 1,\r\n    \"pageSize\": 20,\r\n    \"priceStart\": \"10\",\r\n    \"priceEnd\": \"100\"\r\n  }'\r\n```\n\nFile v1.2.2:references/linkfox-dld-product-billboard.md\n\n---\r\nname: linkfox-dld-product-billboard\r\ndescription: 1688 商品热销榜单查询。用于发现国内货源批发爆款、一件代发选品及趋势商品调研。\r\n\r\n# 1688 商品热销榜单（DLD Product Billboard）\r\n\r\n本技能用于查询 1688 平台商品热销榜单数据，帮助卖家在国内最大的 B2B 批发市场发现热销批发商品与货源机会。参数与响应字段详见 [references/api.md](references/api.md)。\r\n\r\n## 能力边界\r\n\r\n### ✅ 能力范围\r\n\r\n- 查询 1688 平台商品排名数据，覆盖**周榜**与**月榜**两种榜单。\r\n- 发现热销批发商品、对比供应商、识别国内批发市场的货源与趋势机会。\r\n- 支持按关键词、价格区间、销量区间、公司类型（店铺/工厂）、卖家会员类型、发货时间、代发权益、面单支持等多维筛选与排序。\r\n\r\n### ❌ 边界与限制\r\n\r\n- **关键词语言**：`keyWord` 参数必须为中文，非中文关键词需先翻译再查询。\r\n- **日期格式**：周榜日期须为该周周日；月榜日期须为该月第一天。\r\n- **数据时效**：周榜仅近 90 天，月榜仅近 12 个月。\r\n- **分页上限**：单次请求最多 100 条；按商品 ID 查询时最多 20 个。\r\n- **不在范围内**：Amazon 选品与关键词分析（用 ABA 工具）；1688 店铺级分析（店铺排名、店铺评分）；Alibaba.com 国际站数据；价格议价与下单；商品质量评价与认证；物流成本计算与货代。\r\n\r\n## 核心概念\r\n\r\n1688 商品热销榜单提供 1688 平台商品排名数据，覆盖**周榜**与**月榜**，帮助发现趋势批发商品、对比供应商、识别货源机会。\r\n\r\n**榜单类型**：\r\n- **周榜**（`pageType=2`）：日期传该周周日，如 `2025-06-15`；数据为近 90 天。\r\n- **月榜**（`pageType=3`）：日期传该月第一天，如 `2025-06-01`；数据为近 12 个月。\r\n\r\n**默认行为**：月榜，按销售笔数降序，每页 20 条。\r\n\r\n## 使用示例\r\n\r\n**1. 某关键词的月度热销榜**\r\n> \"查一下 1688 本月手机壳的热销榜\"\r\n```json\r\n{\"keyWord\": \"手机壳\", \"pageType\": 3, \"date\": \"2026-03-01\", \"sortField\": \"orderCount\", \"sortType\": \"desc\"}\r\n```\r\n\r\n**2. 周榜按销售额排序**\r\n> \"上周瑜伽垫品类里销售额最高的是哪些？\"\r\n```json\r\n{\"keyWord\": \"瑜伽垫\", \"pageType\": 2, \"date\": \"2026-03-22\", \"sortField\": \"saleVolume\", \"sortType\": \"desc\"}\r\n```\r\n\r\n**3. 工厂直供并限价**\r\n> \"在 1688 找 5-30 元的耳机工厂直供商品\"\r\n```json\r\n{\"keyWord\": \"耳机\", \"companyType\": 2, \"beginPrice\": 5, \"endPrice\": 30, \"sortField\": \"saleCount\", \"sortType\": \"desc\"}\r\n```\r\n\r\n**4. 跨境标签且 24 小时发货**\r\n> \"看下 24 小时内发货的跨境标签 LED 灯商品\"\r\n```json\r\n{\"keyWord\": \"LED灯\", \"offerType\": 4, \"sendTime\": \"24\", \"sortField\": \"orderCount\", \"sortType\": \"desc\"}\r\n```\r\n\r\n**5. 超级工厂新品**\r\n> \"找宠物用品类目下超级工厂的新上架商品\"\r\n```json\r\n{\"keyWord\": \"宠物用品\", \"offerType\": 2, \"shiLiType\": \"superFactory\", \"sortField\": \"offerCreateTime\", \"sortType\": \"desc\"}\r\n```\r\n\r\n**6. 支持代发且有买家保障的商品**\r\n> \"看下支持一件代发、包邮且支持 7 天退货的包包商品\"\r\n```json\r\n{\"keyWord\": \"包包\", \"proxyRights\": \"4360897\", \"buyerProtections\": \"商品包邮,7天包退货\", \"sortField\": \"orderCount\", \"sortType\": \"desc\"}\r\n```\r\n\r\n**7. 价格区间内的高销量商品**\r\n> \"找玩具类目下批发价 50 元以内、销售笔数超 1000 的商品\"\r\n```json\r\n{\"keyWord\": \"玩具\", \"beginOrderCount\": 1000, \"endPrice\": 50, \"sortField\": \"orderCount\", \"sortType\": \"desc\"}\r\n```\r\n\r\n**8. 按商品 ID 查询**\r\n> \"查这几个 1688 商品 ID：123456、789012\"\r\n```json\r\n{\"productIds\": \"123456、789012\"}\r\n```\r\n\r\n## 展示规则\r\n\r\n1. **清晰呈现数据**：以结构化表格展示商品标题、批发价、代发价、销售笔数、销售件数、预估销售额、供应商名称、上架时间等。\r\n2. **图片展示**：返回 `imageUrl` 时展示商品图片，便于直观识别。\r\n3. **提供链接**：附商品链接（`asinUrl`）与店铺链接（`shopUrl`），方便直达 1688 商品页。\r\n4. **价格格式**：价格须带币种（CNY/RMB），并注明是批发价还是代发价。\r\n5. **销量口径**：展示销量数据时，按 `dataType` 字段标明是周数据还是月数据。\r\n6. **分页提示**：总条数超出当前页时，告知总数并询问是否继续翻页。\r\n7. **关键词翻译**：用户提供非中文关键词时，先翻译为中文再查询，并告知译文。\r\n8. **错误处理**：查询失败时说明原因，并建议调整参数（如放宽筛选、检查日期格式）。\r\n\r\n## 用户表达与场景速查\r\n\r\n**适用** —— 1688 批发商品发现与货源调研：\r\n\r\n| 用户说 | 场景 |\r\n|--------|------|\r\n| \"1688 上什么火\"、\"1688 趋势商品\" | 热销商品发现 |\r\n| \"给 XX 找便宜货源\"、\"XX 批发货源\" | 按关键词找货源 |\r\n| \"工厂直供商品\"、\"OEM 供应商\" | 工厂筛选 |\r\n| \"跨境货源\"、\"出口商品\" | 跨境标签筛选 |\r\n| \"1688 一件代发商品\" | 支持代发的商品搜索 |\r\n| \"1688 新品\"、\"最近上架的\" | 新品发现 |\r\n| \"对比 XX 的供应商\" | 多结果对比 |\r\n| \"1688 商品排行\"、\"热销榜\" | 榜单浏览 |\r\n\r\n不适用场景见上方【能力边界】。\r\n\r\n## 解决认证和积分问题\r\n\r\n发生以下异常情况时，采用以下措施来处理：\r\n\r\n### 异常情况\r\n- **未配置 API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\r\n- **响应 401 或 402 状态码**\r\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\r\n\r\n### 措施\r\n- 优先采用 skill 内的 onboarding.md 引导解决问题。\r\n- 如找不到 onboarding.md 文件，则加载 /linkfox-onboarding 这个 skill 并根据它的引导来处理。如未安装请先安装：\r\n    - 下载 https://agent-files.linkfox.com/skills/linkfox-onboarding/release.zip，解压后安装这个 skill。\r\n\r\n---\r\n\r\n# 店雷达-1688商品榜单 API 参考\r\n\r\n## 调用规范\r\n\r\n- **请求地址**：`${LINKFOX_TOOL_GATEWAY}/dld/productBillboard`\r\n- **请求方式**：POST，Content-Type: application/json\r\n- **认证方式**：Header `Authorization: <api_key>`，api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\r\n\r\n## 请求参数\r\n\r\nPOST Body（JSON）：\r\n\r\n| 参数 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| keyWord | string | 否 | 商品搜索关键字（搜索关键词必须是中文，如果不是请先翻译），最大长度50 |\r\n| date | string | 否 | 查询时间。周榜：传入该周的周天日期，如 `2025-06-15`（最长近90天）；月榜：传入该月第一天，如 `2025-06-01`（最长近一年） |\r\n| pageType | integer | 否 | 榜单类型：`2` = 周榜，`3` = 月榜。默认 `3` |\r\n| pageIndex | integer | 否 | 页码（从1开始），默认 `1` |\r\n| pageSize | integer | 否 | 每页返回数量（10-100），默认 `20` |\r\n| sortField | string | 否 | 排序字段，默认 `orderCount`。可选值：`orderCount`（销售笔数）、`saleCount`（销售件数）、`saleVolume`（预估销售额）、`offerCreateTime`（上架时间）、`price`（批发价）、`consignPrice`（代发价） |\r\n| sortType | string | 否 | 排序类型：`desc`（降序）、`asc`（升序），默认 `desc` |\r\n| searchType | integer | 否 | 商品关键词搜索类型：`1` = 模糊匹配，`3` = 精准匹配。默认 `1` |\r\n| offerType | integer | 否 | 商品标识：`0` = 不限制，`2` = 新品，`3` = 1688严选，`4` = 跨境，`5` = 支持定制，`6` = 镇店之宝。默认 `0` |\r\n| companyType | integer | 否 | 公司类型：`0` = 不限，`1` = 店铺，`2` = 工厂 |\r\n| shiLiType | string | 否 | 卖家会员类型（多选），多个使用\",\"号隔开。可选值：`superFactory`（超级工厂）、`Power`（实力商家）、`TrustPass`（仅诚信通会员） |\r\n| beginTpYear | integer | 否 | 开始诚信通年限 |\r\n| endTpYear | integer | 否 | 结束诚信通年限 |\r\n| beginPrice | number | 否 | 批发价（起始） |\r\n| endPrice | number | 否 | 批发价（结束） |\r\n| beginConsignPrice | number | 否 | 代发价（起始） |\r\n| endConsignPrice | number | 否 | 代发价（结束） |\r\n| beginOrderCount | integer | 否 | 销售笔数（起始） |\r\n| endOrderCount | integer | 否 | 销售笔数（结束） |\r\n| beginSaleCount | integer | 否 | 销售件数（起始） |\r\n| endSaleCount | integer | 否 | 销售件数（结束） |\r\n| beginSaleVolume | number | 否 | 销售额（起始） |\r\n| endSaleVolume | number | 否 | 销售额（结束） |\r\n| beginStartQuantity | integer | 否 | 起始起批量 |\r\n| endStartQuantity | integer | 否 | 结束起批量 |\r\n| beginOfferCreateTime | string | 否 | 上架时间（起始），格式：`YYYY-MM-DD` |\r\n| endOfferCreateTime | string | 否 | 上架时间（结束），格式：`YYYY-MM-DD` |\r\n| sendTime | string | 否 | 发货时间（多选），多个使用\",\"号隔开。可选值：`24`（24小时）、`48`（48小时）、`72`（72小时） |\r\n| proxyRights | string | 否 | 代发权益（多选），多个使用\",\"号隔开。可选值：`4360897`（一件代发包邮）、`449154`（先采后付） |\r\n| shopService | string | 否 | 卖家服务（多选），多个使用\",\"号隔开。可选值：`4057409`（安心购）、`888777`（深度认证报告） |\r\n| buyerProtections | string | 否 | 权益保障（多选），多个用\",\"隔开。可选值：`商品包邮`、`7天包退货`、`支持运费险` |\r\n| faceToFaceSupport | string | 否 | 面单支持（多选），多个使用\",\"号隔开。可选值：`441218`（淘宝）、`386434`（抖音）、`422914`（拼多多）、`422978`（小红书）、`386370`（快手） |\r\n| productIds | string | 否 | 商品ID，顿号隔开搜索多个，最多20个 |\r\n| goodsUrl | string | 否 | 商品链接地址 |\r\n\r\n\r\n## 响应结构\r\n\r\n| 字段 | 类型 | 说明 |\r\n|------|------|------|\r\n| total | integer | 记录数 |\r\n| type | string | 渲染的样式 |\r\n| columns | array | 渲染的列 |\r\n| products | array | 商品列表（见下方商品对象） |\r\n\r\n### 商品对象\r\n\r\n| 字段 | 类型 | 说明 |\r\n|------|------|------|\r\n| offerId | string | 商品id |\r\n| asin | string | 商品编号 |\r\n| title | string | 商品标题 |\r\n| price | number | 批发价 |\r\n| consignPrice | number | 代发价 |\r\n| currency | string | 币种 |\r\n| unit | string | 单位 |\r\n| quantityBegin | integer | 起批量 |\r\n| quantityPrices | string | 价格区间 |\r\n| salesOrderCount | integer | 销售笔数（按统计周期返回对应的值） |\r\n| salesQuantity | integer | 销售件数（按统计周期返回对应的值） |\r\n| estimatedSalesAmount | integer | 预估销售额（按统计周期返回对应的值） |\r\n| dataType | string | 数据类型：`weeklyData` = 周数据，`monthlyData` = 月数据 |\r\n| availableDate | string | 商品上架时间，格式为 `yyyy-MM-dd HH:mm:ss` |\r\n| deliveryTime | string | 发货时间 |\r\n| levelName | string | 类目层级名称 |\r\n| company | string | 店铺名称 |\r\n| shopId | string | 店铺id |\r\n| shopUrl | string | 店铺链接地址 |\r\n| asinUrl | string | 商品链接地址 |\r\n| imageUrl | string | 图片地址 |\r\n| sourceType | string | 来源平台（1688） |\r\n| sourceTool | string | 来源工具 |\r\n\r\n## 错误码\r\n\r\n正常情况下，接口的 HTTP 状态码均为 200，业务的成功与否通过响应体中的 errorCode 字段区分（errorCode = 200 表示成功，其他值表示业务错误）。当遇到未授权等情况时，HTTP 状态码为 401，且对应的 errorCode 也是 401。\r\n\r\n| errcode | 含义 | 处理建议 |\r\n|---------|------|----------|\r\n| 200 | 成功 | 正常解析业务字段 |\r\n| 401 | 认证失败 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\r\n| 402 | 积分不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\r\n| 其他非200值 | 业务异常 | 参考 `errmsg` 字段获取具体错误原因 |\r\n\r\n错误响应示例：\r\n\r\n```json\r\n{\r\n    \"errcode\": 401,\r\n    \"errmsg\": \"authorized error\"\r\n}\r\n```\r\n\r\n## curl 示例\r\n\r\n```bash\r\ncurl -X POST https://tool-gateway.linkfox.com/dld/productBillboard \\\r\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -d '{\r\n    \"keyWord\": \"手机壳\",\r\n    \"pageType\": 3,\r\n    \"date\": \"2026-03-01\",\r\n    \"sortField\": \"orderCount\",\r\n    \"sortType\": \"desc\",\r\n    \"pageSize\": 20,\r\n    \"pageIndex\": 1\r\n  }'\r\n```\n\nFile v1.2.2:references/linkfox-dld-product-search.md\n\n---\r\nname: linkfox-dld-product-search\r\ndescription: 1688 批发平台商品搜索。用于寻找国内工厂货源、供应商发现、批发价格对比及选品调研。\r\n\r\n# 1688 商品搜索（DLD Product Search）\r\n\r\n本技能用于在 1688 批发平台（阿里巴巴国内 B2B 市场）上搜索和分析商品，帮助电商卖家与采购人员寻找优质供应商与有利润空间的商品。参数与响应字段详见 [references/api.md](references/api.md)。\r\n\r\n## 能力边界\r\n\r\n### ✅ 能力范围\r\n\r\n- 基于 1688 平台进行关键词商品搜索，聚合商品列表及其销量、价格分层、供应商资质与履约信息。\r\n- 数据来源于店雷达（store radar）分析，覆盖实时商品列表与近 7 天 / 30 天销量指标。\r\n- 支持按关键词、商品链接、商品 ID 检索，并按价格、销量、销售额、上架时间等多维排序。\r\n- 支持按公司类型（店铺/工厂）、卖家会员类型、发货时间、代发权益、面单支持等筛选。\r\n\r\n### ❌ 边界与限制\r\n\r\n- **关键词语言**：`keyWord` 必须为中文，非中文关键词需先翻译再查询。\r\n- **搜索方式互斥**：`keyWord`、`goodsUrl`、`productIds` 三者择一使用。\r\n- **统计周期**：仅支持近 7 天（`cycle=\"7\"`）或近 30 天（`cycle=\"30\"`）。\r\n- **分页上限**：单次最多 100 条；按商品 ID 查询最多 20 个。\r\n- **不在范围内**：Amazon 等非 1688 平台的商品研究；1688 店铺级分析（店铺流量、店铺排名）；1688 广告与推广策略；商品评论或评分分析；物流成本计算与运费估算；下单与交易处理；用户已有本地商品数据文件需分析。\r\n\r\n**边界判断**：当用户说\"找货源\"\"找供应商\"\"批发商品\"时，若涉及在 1688 平台按价格、销量、供应商类型等条件搜索具体商品，适用本技能；若需要店铺级分析、广告优化或超出商品搜索范围的运营操作，则不适用。\r\n\r\n## 核心概念\r\n\r\n本工具提供 1688（中国最大的 B2B 批发市场）的关键词商品搜索，聚合商品列表及其销量数据、价格分层、供应商资质与履约选项。数据来源于店雷达分析，覆盖实时商品列表与 7 天、30 天销量指标。\r\n\r\n**关键术语**：\r\n- **批发价**（`price`）：按起批量下单时的单件价格。\r\n- **代发价**（`consignPrice`）：单件一件代发的单件价格（通常高于批发价）。\r\n- **诚信通年限**（`tpYear`）：供应商持有阿里巴巴诚信通会员的年数，反映经营年限。\r\n- **销售件数**（`salesQuantity`）：所选统计周期内的总销售件数。\r\n- **销售笔数**（`salesOrderCount`）：所选统计周期内的总订单笔数。\r\n- **预估销售额**（`estimatedSalesAmount`）：所选统计周期内的预估销售额。\r\n\r\n## 使用示例\r\n\r\n**1. 基础关键词搜索——\"瑜伽垫\"热销品**\r\n```json\r\n{\"keyWord\": \"瑜伽垫\", \"cycle\": \"30\", \"sortField\": \"saleCount30d\", \"sortType\": \"desc\", \"pageSize\": 20}\r\n```\r\n\r\n**2. 仅工厂且有价格区间**\r\n```json\r\n{\"keyWord\": \"蓝牙耳机\", \"companyType\": 2, \"beginPrice\": 10, \"endPrice\": 50, \"cycle\": \"30\", \"sortField\": \"orderCount30d\"}\r\n```\r\n\r\n**3. 跨境商品并支持代发**\r\n```json\r\n{\"keyWord\": \"手机壳\", \"offerType\": 4, \"proxyRights\": \"4360897\", \"cycle\": \"7\", \"sortField\": \"saleVolume7d\"}\r\n```\r\n\r\n**4. 最近上架的新品，按上架时间排序**\r\n```json\r\n{\"keyWord\": \"夏季连衣裙\", \"offerType\": 2, \"sortField\": \"offerCreateTime\", \"sortType\": \"desc\", \"pageSize\": 50}\r\n```\r\n\r\n**5. 超级工厂的高销量商品**\r\n```json\r\n{\"keyWord\": \"数据线\", \"shiLiType\": \"superFactory\", \"beginSaleCount\": 1000, \"cycle\": \"30\", \"sortField\": \"saleCount30d\"}\r\n```\r\n\r\n**6. 按商品链接搜索**\r\n```json\r\n{\"goodsUrl\": \"https://detail.1688.com/offer/805578065498.html\", \"cycle\": \"30\"}\r\n```\r\n\r\n## 展示规则\r\n\r\n1. **清晰呈现数据**：以结构化表格展示商品标题、价格、销量指标与供应商信息，并附商品链接方便直达。\r\n2. **价格口径**：有批发价与代发价时同时展示，便于用户对比利润空间。\r\n3. **销量口径**：根据所用的 `cycle` 参数，明确标注是 7 天还是 30 天数据。\r\n4. **图片展示**：返回 `imageUrl` 时展示商品图片，便于直观识别。\r\n5. **分页提示**：总条数超出当前页时，告知总数并询问是否继续翻页。\r\n6. **错误处理**：查询失败时说明原因，并建议调整参数（如放宽筛选、检查关键词拼写）。\r\n7. **关键词翻译**：用户提供英文商品词时，先翻译为中文再调用，并在回复中注明译文。\r\n\r\n## 用户表达与场景速查\r\n\r\n**适用** —— 1688 批发商品搜索与货源调研：\r\n\r\n| 用户说 | 场景 |\r\n|--------|------|\r\n| \"在 1688 上找 XX 的供应商\" | 关键词商品搜索 |\r\n| \"1688 上什么好卖\" | 热销商品发现 |\r\n| \"找工厂的便宜 XX\" | 工厂货源 + 价格筛选 |\r\n| \"1688 一件代发 XX 的供应商\" | 支持代发的商品搜索 |\r\n| \"对比 XX 在 1688 上的价格\" | 跨供应商比价 |\r\n| \"1688 上 XX 的新品\" | 新品发现 |\r\n| \"找 1688 跨境商品\" | 跨境商品采购 |\r\n| \"哪些 1688 供应商 24 小时发货\" | 履约速度筛选 |\r\n| \"XX 的顶级工厂\" | 超级工厂 / 实力商家搜索 |\r\n| \"查这个 1688 商品\"（带链接或 ID） | 直接查询指定商品 |\r\n\r\n不适用场景见上方【能力边界】。\r\n\r\n## 解决认证和积分问题\r\n\r\n发生以下异常情况时，采用以下措施来处理：\r\n\r\n### 异常情况\r\n- **未配置 API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\r\n- **响应 401 或 402 状态码**\r\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\r\n\r\n### 措施\r\n- 优先采用 skill 内的 onboarding.md 引导解决问题。\r\n- 如找不到 onboarding.md 文件，则加载 /linkfox-onboarding 这个 skill 并根据它的引导来处理。如未安装请先安装：\r\n    - 下载 https://agent-files.linkfox.com/skills/linkfox-onboarding/release.zip，解压后安装这个 skill。\r\n\r\n---\r\n\r\n# 店雷达 1688 选品库 API 参考\r\n\r\n## 调用规范\r\n\r\n- **请求地址**：`${LINKFOX_TOOL_GATEWAY}/dld/productSearch`\r\n- **请求方式**：POST，Content-Type: application/json\r\n- **认证方式**：Header `Authorization: <api_key>`，api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\r\n\r\n## 请求参数\r\n\r\nPOST Body（JSON）：\r\n\r\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\r\n|------|------|------|--------|------|\r\n| keyWord | string | 否 | - | 搜索关键词（必须为中文，最多50字符） |\r\n| goodsUrl | string | 否 | - | 商品链接地址（与keyWord二选一） |\r\n| productIds | string | 否 | - | 商品ID，多个逗号隔开，最多20个 |\r\n| cycle | string | 否 | - | 统计周期：`7`（近7天）或 `30`（近30天） |\r\n| searchType | integer | 否 | 1 | 搜索类型：1-模糊匹配，3-精准匹配 |\r\n| sortField | string | 否 | orderCount30d | 排序字段：orderCount7d, saleCount7d, saleVolume7d, orderCount30d, saleCount30d, saleVolume30d, offerCreateTime, price, consignPrice |\r\n| sortType | string | 否 | desc | 排序类型：desc（降序）、asc（升序） |\r\n| pageIndex | integer | 否 | 1 | 页码（从1开始） |\r\n| pageSize | integer | 否 | 20 | 每页数量（10-100） |\r\n| beginPrice | number | 否 | - | 批发价（起始） |\r\n| endPrice | number | 否 | - | 批发价（结束） |\r\n| beginConsignPrice | number | 否 | - | 代发价（起始） |\r\n| endConsignPrice | number | 否 | - | 代发价（结束） |\r\n| beginOrderCount | integer | 否 | - | 销售笔数（起始） |\r\n| endOrderCount | integer | 否 | - | 销售笔数（结束） |\r\n| beginSaleCount | integer | 否 | - | 销售件数（起始） |\r\n| endSaleCount | integer | 否 | - | 销售件数（结束） |\r\n| beginSaleVolume | number | 否 | - | 销售额（起始） |\r\n| endSaleVolume | number | 否 | - | 销售额（结束） |\r\n| beginStartQuantity | integer | 否 | - | 起购数量（起始） |\r\n| endStartQuantity | integer | 否 | - | 起购数量（结束） |\r\n| beginTpYear | integer | 否 | - | 诚信通年限（起始） |\r\n| endTpYear | integer | 否 | - | 诚信通年限（结束） |\r\n| beginOfferCreateTime | string | 否 | - | 上架时间起始（格式：YYYY-MM-DD） |\r\n| endOfferCreateTime | string | 否 | - | 上架时间结束（格式：YYYY-MM-DD） |\r\n| companyType | integer | 否 | 0 | 公司类型：0-不限，1-店铺，2-工厂 |\r\n| offerType | integer | 否 | 0 | 商品标识：0-不限，2-新品，3-1688严选，4-跨境，5-支持定制，6-镇店之宝 |\r\n| shiLiType | string | 否 | - | 卖家类型（多选逗号隔开）：superFactory（超级工厂）、Power（实力商家）、TrustPass（诚信通） |\r\n| sendTime | string | 否 | - | 发货时间（多选逗号隔开）：24、48、72 |\r\n| faceToFaceSupport | string | 否 | - | 面单支持（多选逗号隔开）：441218（淘宝）、386434（抖音）、422914（拼多多）、422978（小红书）、386370（快手） |\r\n| proxyRights | string | 否 | - | 代发权益（多选逗号隔开）：4360897（一件代发包邮）、449154（先采后付） |\r\n| shopService | string | 否 | - | 卖家服务（多选逗号隔开）：4057409（安心购）、888777（深度认证报告） |\r\n| buyerProtections | string | 否 | - | 权益保障（多选逗号隔开）：商品包邮、7天包退货、支持运费险 |\r\n\r\n## 响应结构\r\n\r\n| 字段 | 类型 | 说明 |\r\n|------|------|------|\r\n| total | integer | 总记录数 |\r\n| type | string | 渲染样式 |\r\n| columns | array | 渲染列定义 |\r\n| products | array | 商品列表（详见下方字段） |\r\n\r\n### products 数组元素字段\r\n\r\n| 字段 | 类型 | 说明 |\r\n|------|------|------|\r\n| offerId | string | 商品ID |\r\n| asin | string | 商品编号 |\r\n| title | string | 商品标题 |\r\n| asinUrl | string | 商品链接地址 |\r\n| imageUrl | string | 商品图片地址 |\r\n| price | number | 批发价 |\r\n| consignPrice | number | 代发价 |\r\n| quantityPrices | string | 价格区间 |\r\n| quantityBegin | integer | 起批量 |\r\n| unit | string | 单位 |\r\n| currency | string | 币种 |\r\n| salesOrderCount | integer | 销售笔数（按统计周期） |\r\n| salesQuantity | integer | 销售件数（按统计周期） |\r\n| estimatedSalesAmount | integer | 预估销售额（按统计周期） |\r\n| deliveryTime | string | 发货时间 |\r\n| availableDate | string | 商品上架时间 |\r\n| levelName | string | 类目层级名称 |\r\n| company | string | 店铺名称 |\r\n| shopId | string | 店铺ID |\r\n| shopUrl | string | 店铺链接地址 |\r\n| dataType | string | 数据类型：weeklyData（周数据）、monthlyData（月数据） |\r\n| sourceType | string | 来源平台（1688） |\r\n| sourceTool | string | 来源工具 |\r\n\r\n## 错误码\r\n\r\n正常情况下，接口的 HTTP 状态码均为 200，业务的成功与否通过响应体中的 errorCode 字段区分（errorCode = 200 表示成功，其他值表示业务错误）。当遇到未授权等情况时，HTTP 状态码为 401，且对应的 errorCode 也是 401。\r\n\r\n| errcode | 含义 | 处理建议 |\r\n|---------|------|----------|\r\n| 200 | 成功 | 正常解析业务字段 |\r\n| 401 | 认证失败 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\r\n| 402 | 积分不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\r\n| 其他非200值 | 业务异常 | 参考 `errmsg` 字段获取具体错误原因 |\r\n\r\n错误响应示例：\r\n\r\n```json\r\n{\r\n    \"errcode\": 401,\r\n    \"errmsg\": \"authorized error\"\r\n}\r\n```\r\n\r\n## curl 示例\r\n\r\n```bash\r\ncurl -X POST https://tool-gateway.linkfox.com/dld/productSearch \\\r\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -d '{\"keyWord\": \"瑜伽垫\", \"cycle\": \"30\", \"sortField\": \"saleCount30d\", \"sortType\": \"desc\", \"pageSize\": 20}'\r\n```\n\nFile v1.2.2:references/onboarding.md\n\n# 解决认证和积分问题\r\n\r\n调用本 skill 时若网关返回 **auth** 或 **billing** 错误，走本 skill 自带的 `scripts/onboarding.py` 完成引导。\r\n\r\n**auth 场景**：`errcode=401` 或消息含 `authorized error`/`鉴权失败`/`未授权`/`unauthorized`；或 `LINKFOX_AGENT_API_KEY` 与 `LINKFOXAGENT_API_KEY` 均为空。\r\n1. 若已配置 key → 先让用户重启会话（最常见误判），仍失败让用户重新取 key 或换手机号重注册\r\n2. 未配置 → 询问：自助去 https://agent.linkfox.com/ 取 key，或提供手机号让脚本注册\r\n3. 手机号路径：\r\n   - `python scripts/onboarding.py send-code <phone>` → 展示 JSON 里的 phone/agreements\r\n   - 收到验证码后：`python scripts/onboarding.py login <phone> <code>`（workbuddy 宿主加 `--channel workbuddy`）\r\n   - 拿到 `api_key` 后把下面三平台配置转发给用户，提示重启会话生效：\r\n     - Windows PowerShell（永久）：`setx LINKFOX_AGENT_API_KEY \"<key>\"`\r\n     - macOS zsh：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.zshrc && source ~/.zshrc`\r\n     - Linux bash：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.bashrc && source ~/.bashrc`\r\n     - 变量名 `LINKFOX_AGENT_API_KEY`（主推）或 `LINKFOXAGENT_API_KEY`（老规范）任一即可\r\n\r\n**billing 场景**：`errcode=402` 或消息含 `积分/余额/quota/insufficient/充值/套餐到期`。\r\n- `python scripts/onboarding.py list-plans` → 有 AskUserQuestion 就弹菜单，否则输出编号清单让用户选\r\n- 校验 `plan_id` ∈ 清单、支付方式 ∈ 该套餐 `available_methods`（通常 `wechat/alipay`）\r\n- `python scripts/onboarding.py order <plan_id> <method>` → 展示优先级 PNG > `pay_url` > `ascii_qr`（标注兜底）\r\n- 已付款可选调 `python scripts/onboarding.py query <order_id>`，不主动轮询\r\n\r\n排除 `errcode=403`（无权限，不归入这两类）。所有子命令输出 stdout JSON，`error` 字段已含阶段前缀，透传给用户即可。完整用法：`python scripts/onboarding.py --help`。\n\nFile v1.2.2:skill-card.md\n\n## Description:\n\n1688 货源一站式 AI 工具集，整合商品搜索、热销榜单、以图搜图与已授权采购履约，覆盖找货、选品、比价、图搜同款与下单全流程。\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[linkfox-ai](https://clawhub.ai/user/linkfox-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users, operators, and sourcing teams use this skill to search 1688 products and suppliers, compare prices and sales signals, find visually similar products from images, and manage authorized 1688 procurement steps including order preview, creation, payment link retrieval, order status, logistics, cancellation, and receipt confirmation.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can perform order-changing 1688 procurement actions, including creating orders, retrieving payment links, cancelling orders, and confirming receipt.\n\nMitigation: Require a separate explicit user confirmation for each high-risk action and review the account, item, quantity, amount, order ID, and status before execution.\n\nRisk: The skill sends credential-bearing requests to LinkFox and 1688 services.\n\nMitigation: Store the LinkFox API key only in supported environment variables, review configured gateway variables, and never paste 1688 tokens, refresh tokens, app secrets, or Authorization headers into prompts.\n\nRisk: Image search may transmit product images and search data to LinkFox or 1688 services, and local image uploads create public URLs.\n\nMitigation: Avoid uploading confidential, personal, or proprietary images; use only images that are acceptable to share with the service.\n\nRisk: Search, image-search, procurement, and cache outputs may persist locally with product, order, address, or logistics details.\n\nMitigation: Periodically clean the local linkfox output and cache directories, especially on shared machines, and avoid forcing full inline output unless needed.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/linkfox-ai/skills/linkfox-1688-sourcing)\n- [1688采购全流程（1688 Procurement Workflow）](artifact/references/linkfox-1688-procurement.md)\n- [1688 以图搜图（1688 Image-Based Product Search）](artifact/references/linkfox-1688-search-by-image.md)\n- [1688 商品热销榜单（DLD Product Billboard）](artifact/references/linkfox-dld-product-billboard.md)\n- [1688 商品搜索（DLD Product Search）](artifact/references/linkfox-dld-product-search.md)\n- [解决认证和积分问题](artifact/references/onboarding.md)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, JSON, Shell commands, Configuration, Guidance]\n\n**Output Format:** [Markdown guidance with command examples and JSON API responses or saved response files]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May call LinkFox gateway APIs, upload local images to public URLs for image search, and save full responses or cache files under local linkfox output directories.]\n\n## Skill Version(s):\n\n1.2.2 (source: server release metadata; artifact frontmatter reports 1.0.0)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.2.1: 26 files, 68149 bytes\n\nFiles: references/linkfox-1688-procurement.md (23508b), references/linkfox-1688-search-by-image.md (15759b), references/linkfox-dld-product-billboard.md (12861b), references/linkfox-dld-product-search.md (12271b), references/onboarding.md (2068b), scripts/_alibaba1688_common.py (12498b), scripts/alibaba1688_image_search.py (12725b), scripts/authorize_url.py (124b), scripts/authorized_stores.py (128b), scripts/cancel_order.py (123b), scripts/confirm_receive.py (126b), scripts/create_order.py (123b), scripts/dld_product_billboard.py (13086b), scripts/dld_product_search.py (13048b), scripts/logistics_trace.py (126b), scripts/logistics.py (121b), scripts/onboarding.py (24089b), scripts/order_preview.py (124b), scripts/order_status.py (123b), scripts/payment_url.py (122b), scripts/receive_address_list.py (130b), scripts/sku.py (115b), scripts/upload_image.py (4591b), skill-card.md (2935b), SKILL.md (19990b), _meta.json (140b)\n\nFile v1.2.1:SKILL.md\n\n---\nname: linkfox-1688-sourcing\ndisplay_name: Linkfox 1688货源\ndisplay_name_en: LinkFox 1688 Sourcing\ndescription: 1688 货源一站式 AI 工具集，整合商品搜索、热销榜单、以图搜图与已授权采购履约，覆盖找货、选品、比价、图搜同款与下单全流程。\ndescription_zh: 1688 货源一站式工具集：店雷达商品搜索与热销榜单（关键词/链接/ID 检索、周榜月榜、多维筛选排序、批发价/代发价/销量与供应商资质）、1688 以图搜图（图片 URL/Base64/imageId 视觉检索同款货源，含本地图片上传）、1688 已授权采购全流程（OAuth 授权检查、SKU/收货地址、下单预览、创建订单、支付链接、订单状态、物流轨迹、取消订单、确认收货）。当用户需要 1688 找货源、找供应商、批发选品、热销榜单、以图找同款、跨境找工厂或已授权采购下单与物流跟踪时触发。各子能力完整参数见 references/ 对应文件，脚本见 scripts/。\ndescription_en: One-stop 1688 sourcing AI toolkit: store-radar product search and bestseller billboards (keyword/URL/ID retrieval, weekly/monthly rankings, multi-dimensional filters and sorting, wholesale/dropship price, sales and supplier qualifications), 1688 image search (visual retrieval of same-style sourcing by image URL/Base64/imageId, with local image upload), and end-to-end authorized 1688 procurement (OAuth checks, SKU/address, order preview, order creation, payment URL, order status, logistics tracking, cancellation, receipt confirmation). Triggered when the user needs 1688 sourcing, supplier discovery, wholesale product selection, bestseller rankings, image-based same-product search, cross-border factory sourcing, or authorized 1688 procurement ordering and logistics tracking. Full params per sub-capability are in references/, executable scripts in scripts/.\ncategory: e-commerce\nversion: 1.0.0\nauthor: LinkFox\n---\n\n# Linkfox 1688货源（1688 Sourcing）\n\n1688 货源一站式 AI 工具集，整合 **3 类底层工具、4 项子能力**，覆盖货源搜索与热销榜单、以图搜图、已授权采购履约。各子能力完整参数、响应字段与错误码见 `references/` 下对应文件，可执行脚本见 `scripts/`。\n\n## 能力边界\n\n### ✅ 能力范围\n- **货源搜索与榜单（`1688_sourcing`）**：商品搜索（`linkfox-dld-product-search`，按关键词/商品链接/商品 ID 检索 1688 批发商品，近 7 天/30 天销量周期，按价格/销量/销售额/上架时间排序，按公司类型/卖家会员/发货时间/代发权益/面单支持等筛选）、商品热销榜单（`linkfox-dld-product-billboard`，周榜/月榜，按销售笔数/销售额/销量排序，发现爆款与趋势货源）。返回批发价、代发价、销售笔数/件数、预估销售额、起批量、供应商资质、店铺与商品链接等。\n- **以图搜图（`1688_search_by_image`）**：1688 以图搜图（`linkfox-1688-search-by-image`，通过图片 URL/Base64/imageId 视觉检索外观相似或同款货源），返回标题、批发价、代发价、月销量、起批量、复购率、交易评分、商家身份（超级工厂/实力商家/诚信通）等；支持价格/筛选（1688 严选/认证工厂/发货时效/品质退款率等）/排序/分页；本地图片先用 `upload_image.py` 上传获取公网 URL（有效期 24h）。\n- **采购履约（`1688_procurement`）**：1688 采购全流程（`linkfox-1688-procurement`），覆盖 OAuth 授权检查与发起授权、SKU/规格与收货地址查询、下单预览、创建订单、获取支付链接、订单状态、物流概览与物流轨迹、取消订单、确认收货。除授权类操作外每个 endpoint 前自动校验当前用户 ACTIVE 且未过期的 1688 授权；高风险写操作（创建订单/支付链接/取消订单/确认收货）需用户单独中文确认后由 Agent 注入对应 boolean 安全字段。\n- 数据平台均为中国大陆 1688 批发平台（阿里巴巴国内 B2B 市场），无多站点概念。\n\n### ❌ 边界与限制\n- **API Key 必需**：所有工具均需环境变量 `LINKFOX_AGENT_API_KEY`（或 `LINKFOXAGENT_API_KEY`）；各工具独立计费、独立限频。\n- **计费约束**：商品搜索/热销榜单固定计费（成功约 9 积分/18000 token），以图搜图固定计费（约 4.5 积分/9000 token），采购履约各操作消耗积分；同一会话同一参数组合默认只调用一次（搜索/榜单/图搜脚本带 24h 本地缓存）；失败、空结果、参数不全或授权不足不得自动换关键词、翻页或连续试探；需继续检索时先向用户说明会产生额外消耗（各工具计费规则见 `skills-version.json` 对应条目与 references 内 api.md）。\n- **采购授权前置**：采购类操作依赖当前用户已授权的 1688 OAuth；无 ACTIVE 授权时不调用目标 endpoint；高风险写操作失败不自动重试；不向用户索要 1688 token/refresh token/callback code/app secret。\n- **不在范围内**：Amazon/TikTok/沃尔玛等其他平台选品（用对应平台技能）；Alibaba.com 国际站数据；1688 店铺级分析（店铺流量/排名/评分）；商品评论分析；价格历史与趋势分析；图片生成或编辑；物流成本计算与货代；实时库存与订单系统对接；与供应商或平台的直接沟通。\n- **数据时效**：商品搜索/榜单为店雷达分析数据（7 天/30 天/周榜近 90 天/月榜近 12 个月）；以图搜图为实时搜索、不入库、无法二次 SQL 处理；采购履约为依赖 OAuth 的实时接口。\n\n## 工具选择指南\n\n按需求在下表定到子能力，再跳到【业务需求路由速查】查端点/脚本/references 取参执行。\n\n| 需求 / 用户说 | 默认推荐（子能力） | 何时换用其他 |\n|---|---|---|\n| 关键词找 1688 货源 / 找供应商（\"1688 上找 XX 货源\"） | `linkfox-dld-product-search`（关键词搜索，7/30 天销量） | 要看周/月排行榜用 `linkfox-dld-product-billboard`；有图片找同款用 `linkfox-1688-search-by-image` |\n| 1688 什么好卖 / 趋势 / 热销榜（\"1688 热销榜\"\"什么火\"） | `linkfox-dld-product-billboard`（周榜/月榜排名） | 要按关键词实时搜 + 销量筛选用 `linkfox-dld-product-search` |\n| 用图片找 1688 同款 / 以图搜图（\"用图找货源\"\"找同款\"） | `linkfox-1688-search-by-image`（唯一图搜，需图片 URL） | 本地图片先 `upload_image.py` 上传换公网 URL；要按关键词文本搜索用 `linkfox-dld-product-search` |\n| 按商品 ID / 商品链接查 1688 商品 | `linkfox-dld-product-search`（支持 `goodsUrl`/`productIds`） | 仅按 ID 查榜单商品也可用 `linkfox-dld-product-billboard` |\n| 工厂直供 / 超级工厂 / OEM 供应商（\"找工厂\"\"顶级工厂\"） | `linkfox-dld-product-search`（`companyType=2`/`shiLiType=superFactory`） | 要榜单里的工厂货用 `linkfox-dld-product-billboard` |\n| 1688 一件代发货源（\"一件代发\"\"支持代发\"） | `linkfox-dld-product-search`（`proxyRights=4360897`） | 要榜单代发货用 `linkfox-dld-product-billboard` |\n| 跨境货源 / 出口商品（\"跨境商品\"\"1688 严选\"） | `linkfox-dld-product-search`（`offerType=4`） | 要图搜跨境同款用 `linkfox-1688-search-by-image`（`filter=1688Selection`） |\n| 1688 新品 / 最近上架（\"新品\"\"最近上的\"） | `linkfox-dld-product-search`（`sortField=offerCreateTime`） | 要榜单新品用 `linkfox-dld-product-billboard`（`offerType=2`） |\n| 对比供应商 / 跨供应商比价 | `linkfox-dld-product-search`（多维排序） | — |\n| 查我的 1688 授权店铺（\"我的 1688 授权\"） | `linkfox-1688-procurement`（`authorized_stores.py`） | — |\n| 生成 1688 授权链接（\"授权 1688\"） | `linkfox-1688-procurement`（`authorize_url.py`） | — |\n| 查 offerId 的 SKU / 规格 / 起订量 / 库存 | `linkfox-1688-procurement`（`sku.py`） | 找 offerId 先用图搜或商品搜索 |\n| 查 1688 收货地址 | `linkfox-1688-procurement`（`receive_address_list.py`） | — |\n| 预览 1688 订单（\"帮我预览订单\"） | `linkfox-1688-procurement`（`order_preview.py`） | — |\n| 1688 下单 / 获取支付链接（\"确认下单\"\"获取支付链接\"） | `linkfox-1688-procurement`（`create_order.py`/`payment_url.py`，高风险需确认） | — |\n| 查 1688 订单状态 / 物流 / 物流轨迹 | `linkfox-1688-procurement`（`order_status.py`/`logistics.py`/`logistics_trace.py`） | — |\n| 取消 1688 订单 / 确认收货（\"取消订单\"\"确认收货\"） | `linkfox-1688-procurement`（`cancel_order.py`/`confirm_receive.py`，高风险需确认） | — |\n\n### 工具选择思路\n- **重要**：多个子能力满足需求时，要依据需求深入分析子能力的功能、用途、出入参、从中调研出最合适的子能力，并推荐用户，让用户自己决定。\n- 满足程度同等的前提下，向用户推荐\"默认推荐子能力\"。注意：找货/选品用搜索或榜单（`1688_sourcing`）或图搜（`1688_search_by_image`），已授权采购履约用 `1688_procurement`——前者只查货不交易，后者才可下单。\n\n## 业务需求路由速查\n\n按【工具选择指南】定到子能力后，下表查端点、脚本与 references 文件取参执行：\n\n### 子能力 ↔ references 文件 ↔ 端点 ↔ 脚本（4 项）\n\n**1688_sourcing**\n| 子能力 | references 文件 | 端点 | 脚本 |\n|---|---|---|---|\n| linkfox-dld-product-billboard | references/linkfox-dld-product-billboard.md | POST /dld/productBillboard | dld_product_billboard.py |\n| linkfox-dld-product-search | references/linkfox-dld-product-search.md | POST /dld/productSearch | dld_product_search.py |\n\n**1688_search_by_image**\n| 子能力 | references 文件 | 端点 | 脚本 |\n|---|---|---|---|\n| linkfox-1688-search-by-image | references/linkfox-1688-search-by-image.md | POST /alibaba1688/imageSearch | alibaba1688_image_search.py、upload_image.py（本地图片上传） |\n\n**1688_procurement**\n| 子能力 | references 文件 | 端点 | 脚本 |\n|---|---|---|---|\n| linkfox-1688-procurement | references/linkfox-1688-procurement.md | POST /alibaba1688/{operation} | 见下表（12 个操作脚本 + `_alibaba1688_common.py` 共享模块） |\n\n**1688 采购操作明细（operation ↔ 脚本 ↔ 风险）**\n\n| operation | 端点 | 脚本 | 风险 | 高风险确认字段 |\n|---|---|---|---|---|\n| authorizeUrl | POST /alibaba1688/authorizeUrl | authorize_url.py | 低（不需 ACTIVE 前置） | — |\n| authorizedStores | POST /alibaba1688/authorizedStores | authorized_stores.py | 低（不需 ACTIVE 前置） | — |\n| receiveAddressList | POST /alibaba1688/receiveAddressList | receive_address_list.py | 低（需 ACTIVE） | — |\n| sku | POST /alibaba1688/sku | sku.py | 低（需 ACTIVE） | — |\n| orderPreview | POST /alibaba1688/orderPreview | order_preview.py | 中（需 ACTIVE） | — |\n| createOrder | POST /alibaba1688/createOrder | create_order.py | 高（需 ACTIVE） | `confirmCreateOrder=true` |\n| paymentUrl | POST /alibaba1688/paymentUrl | payment_url.py | 高（需 ACTIVE） | `confirmGetPaymentUrl=true` |\n| orderStatus | POST /alibaba1688/orderStatus | order_status.py | 低（需 ACTIVE） | — |\n| logistics | POST /alibaba1688/logistics | logistics.py | 低（需 ACTIVE） | — |\n| logisticsTrace | POST /alibaba1688/logisticsTrace | logistics_trace.py | 低（需 ACTIVE） | — |\n| confirmReceive | POST /alibaba1688/confirmReceive | confirm_receive.py | 高（需 ACTIVE） | `confirmReceive=true` |\n| cancelOrder | POST /alibaba1688/cancelOrder | cancel_order.py | 高（需 ACTIVE） | `confirmCancel=true` |\n\n## 调用方式\n\n- **网关**：`${LINKFOX_TOOL_GATEWAY}/<端点>`，请求方式 POST、Content-Type `application/json`，认证 Header `Authorization: <api_key>`（api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取；未配置按下方【解决认证和积分问题】处理）。各端点路径见上方【业务需求路由速查】与对应 references 文件（注意：商品搜索/榜单走 `/dld/` 前缀，图搜与采购走 `/alibaba1688/` 前缀）。\n- **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）。\n- **输出策略**：商品搜索/榜单/图搜脚本**始终**将完整响应写入 `<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` 禁止保存。\n- **读数据建议**：先看 stdout 摘要判断是否足够；需要具体字段时优先用 `jq` 或 PowerShell `ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n- **完整参数**：每个子能力的请求参数、响应字段、错误码、curl 示例见 `references/<源skill>.md`（文件内含该子能力 SKILL.md 正文与 api.md 全文；采购另含 workflow.md 流程地图）。\n\n## 使用示例\n\n以下按数据层给出代表性子能力的出入参示例；其余子能力参数见对应 references 文件。1688 为中国大陆平台，价格币种为人民币（¥/CNY）。\n\n### 货源搜索与榜单层\n\n**1. 关键词商品搜索（1688_sourcing → dld_product_search.py）**\n```json\n{\"keyWord\": \"瑜伽垫\", \"cycle\": \"30\", \"sortField\": \"saleCount30d\", \"sortType\": \"desc\", \"pageSize\": 20}\n```\n出参：`products[]`（offerId/title/price/consignPrice/quantityBegin/salesOrderCount/salesQuantity/estimatedSalesAmount/company/shopId/shopUrl/asinUrl/imageUrl/deliveryTime/availableDate）、`total`、`costToken`。`keyWord`/`goodsUrl`/`productIds` 三选一；`cycle` 为 `7`/`30`。\n\n**2. 商品热销榜单（1688_sourcing → dld_product_billboard.py）**\n```json\n{\"keyWord\": \"手机壳\", \"pageType\": 3, \"date\": \"2026-03-01\", \"sortField\": \"orderCount\", \"sortType\": \"desc\", \"pageSize\": 20}\n```\n出参：`products[]`（字段同上）、`total`、`dataType`（`monthlyData`=月榜/`weeklyData`=周榜）、`costToken`。`pageType=2` 周榜（`date` 传该周周日，近 90 天），`pageType=3` 月榜（`date` 传该月第一天，近 12 个月）。\n\n### 以图搜图层\n\n**3. 以图搜图（1688_search_by_image → alibaba1688_image_search.py）**\n```json\n{\"imageUrl\": \"https://m.media-amazon.com/images/I/719mRAn2VrL._AC_SL1500_.jpg\", \"page\": 1, \"pageSize\": 20, \"filter\": \"1688Selection,totalEpScoreLv1\", \"sort\": \"{\\\"monthSold\\\":\\\"desc\\\"}\"}\n```\n出参：`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。\n\n### 采购履约层\n\n**4. 授权检查（1688_procurement → authorized_stores.py）**\n```json\n{}\n```\n出参：当前 LinkFox 用户的 1688 授权店铺列表，每条含 `status`（需 `ACTIVE`）、`expired`（需 `false`）。有 ACTIVE 授权可继续采购，无则先 `authorize_url.py` 发起授权。\n\n**5. SKU 查询（1688_procurement → sku.py）**\n```json\n{\"offerId\": \"123456789\"}\n```\n出参：SKU/规格、价格、起订量（MOQ）、库存。`offerId` 可由图搜或商品搜索结果获得。\n\n**6. 下单预览（1688_procurement → order_preview.py）**\n```json\n{\"offerId\": \"123456789\", \"quantity\": 10, \"addressId\": \"...\"}\n```\n出参：商品/offerId、SKU/规格、数量、单价与商品总价、运费、收货地址、订单总额、买家留言、异常/库存/价格变化提示。预览失败则停止，不进入创建订单。具体入参以网关 schema 为准。\n\n**7. 创建订单[高风险]（1688_procurement → create_order.py）**\n```json\n{\"offerId\": \"123456789\", \"quantity\": 10, \"addressId\": \"...\", \"confirmCreateOrder\": true}\n```\n出参：订单号与下单结果。用户单独中文确认后（如\"确认创建这个订单\"），Agent 在 payload 注入 boolean `confirmCreateOrder=true` 再调用；脚本本地拒绝缺少该字段的请求，失败不自动重试。支付链接（`payment_url.py`，需 `confirmGetPaymentUrl=true`）、取消订单（`cancel_order.py`，需 `confirmCancel=true`）、确认收货（`confirm_receive.py`，需 `confirmReceive=true`）同理各自独立确认。\n\n## 展示规则\n\n1. **客观呈现数据**：以清晰表格展示商品标题、批发价、代发价、销售笔数/件数、预估销售额、起批量、供应商资质等，不做主观商业建议（除非用户主动要求）。\n2. **来源标注**：展示数据时说明来自店雷达商品搜索/热销榜单、1688 以图搜图还是 1688 采购履约。\n3. **价格与销量口径**：价格须带币种（¥/CNY），并注明是批发价还是代发价；销量按 `dataType`/`cycle` 标明是周数据/月数据/7 天/30 天。\n4. **采购展示**：依赖 OAuth 时先展示授权状态，不单凭浏览器跳转判断；下单预览清晰展示商品/SKU/数量/单价/运费/收货地址/订单总额/异常提示；`authorizedStores` 输出是当前用户授权状态，不要描述成数据库全库账号列表。\n5. **高风险确认**：创建订单、获取支付链接、取消订单、确认收货前复述精确操作、关键 ID、金额/状态（如可得），请用户中文自然语言确认；不要求用户输入内部 boolean 字段（`=true` 由 Agent 注入）。\n6. **不可用数据**：值为 `0` 或 `-1` 的字段表示数据不可用，标注\"N/A\"或省略，不作实际值展示。\n7. **敏感信息**：永不展示完整 API key、JWT、access token、refresh token、callback code、app secret、session key、Authorization header；收货地址展示到足以安全选择即可，避免不必要重复完整手机号或敏感细节。\n8. **错误处理与协同**：查询失败时根据响应 `errcode`/`errmsg` 说明原因并建议修正（关键词需中文、日期格式、ASIN/offerId 格式、授权不足等）；连续使用多工具时（如先图搜找 offerId 再采购下单）将各工具发现汇总为连贯分析，标注数据来源与时间窗；返回 `costToken` 等成本字段时如实展示。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用 references/onboarding.md 引导解决问题：\n\n**注意**：你是workbuddy，并且渠道是workbuddy，使用 onboarding 引导登录注册时 channel **必须**为 workbuddy。这非常重要！\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\nFile v1.2.1:_meta.json\n\n{\n  \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n  \"slug\": \"linkfox-1688-sourcing\",\n  \"version\": \"1.2.1\",\n  \"publishedAt\": 1785920213093\n}\n\nFile v1.2.1:references/linkfox-1688-procurement.md\n\n---\r\nname: linkfox-1688-procurement\r\ndescription: 协助当前用户完成已授权的 1688 采购履约流程，包括授权检查、SKU/地址查询、订单预览、下单、支付、订单和物流跟踪等。\r\n\r\n# 1688采购全流程（1688 Procurement Workflow）\r\n\r\n本技能帮助 LinkFox 用户完成已授权的 1688 采购履约：OAuth 授权检查、SKU 与收货地址查询、下单预览、受保护的下单、支付链接获取、订单与物流跟踪、取消订单、确认收货。图搜找货使用 `linkfox-1688-search-by-image`，本技能不含图搜。端点与字段详见 [references/api.md](references/api.md)，多步采购前先读 [references/workflow.md](references/workflow.md)。\r\n\r\n## 能力边界\r\n\r\n### ✅ 能力范围\r\n\r\n- 查询当前 LinkFox 用户的 1688 OAuth 授权状态、发起授权链接。\r\n- 查询商品 SKU/规格、收货地址，进行下单预览（价格、运费、库存、地址）。\r\n- 在用户单独中文确认后执行高风险写操作：创建订单、获取支付链接、取消订单、确认收货。\r\n- 查询订单状态、物流概览与物流轨迹。\r\n\r\n### ❌ 边界与限制\r\n\r\n- **图搜不在范围**：以图搜图使用 `linkfox-1688-search-by-image`，本技能不包含图搜脚本。\r\n- **授权前置**：除 `authorize_url.py` 和 `authorized_stores.py` 外，每个采购操作调用目标 endpoint 前都会先检查当前用户 ACTIVE 且未过期的 1688 授权；无授权时不调用目标 endpoint。\r\n- **非自动化闭环**：视作流程地图而非全自动执行；不因\"继续\"\"可以\"等前文措辞自动创建订单、获取支付链接、取消订单或确认收货。\r\n- **回调端点不暴露**：`/alibaba1688/proxy/callback`、`/alibaba1688/authorizeCallback`、浏览器 OAuth 回调 URL 不作为 Skill 能力。\r\n- **不索要凭据**：不向用户索要 1688 token、refresh token、callback code、app secret；token 闭环由 MyERP/ecom-plat 后端完成。\r\n- **不查后端库**：不查后端库判断授权状态，使用 `authorizedStores`。\r\n- **不自动重试**：高风险写操作失败不自动重试；不使用 `_dataQuery_executeDynamicQuery` 获取实时采购响应。\r\n- **MCP 与 HTTP 分离**：MCP 启停只控制 MCP 暴露；脚本直连 tool-gateway HTTP route，彻底停用需关 route 或后端能力。\r\n- **成本约束**：调用消耗积分；失败、空结果、参数不全或授权不足时不自动连续试探或轮询，继续查询前先向用户说明会产生额外消耗。\r\n\r\n## 执行流程\r\n\r\n采购流程按步骤协助用户完成，不能一次性自动执行完整下单闭环。每一步均不可跳过授权前置与高风险确认。\r\n\r\n### 步骤 1：授权检查\r\n\r\n- 【输入】当前 LinkFox 用户身份（来自 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY`）。\r\n- 【动作】运行 `authorized_stores.py`，检查是否存在 `status=ACTIVE` 且 `expired=false` 的 1688 授权。\r\n- 【输出】有 ACTIVE 授权 → 可继续采购；无 ACTIVE 授权 → 进入步骤 2。浏览器跳到 MyERP 登录页不等于授权失败，以脚本返回为准。\r\n\r\n### 步骤 2：发起授权（仅未授权时）\r\n\r\n- 【输入】当前用户身份。\r\n- 【动作】运行 `authorize_url.py` 获取 1688 授权链接，让用户在浏览器完成 OAuth；完成后重新运行 `authorized_stores.py` 验证。\r\n- 【输出】ACTIVE 授权账号出现 → 回到步骤 1 确认后继续。不要让用户提供 token、refresh token 或 callback code。\r\n\r\n### 步骤 3：SKU 与收货地址查询\r\n\r\n- 【输入】`offerId`（用户提供，或从 `linkfox-1688-search-by-image` 结果获得）。\r\n- 【动作】运行 `sku.py` 查 SKU/规格、价格、起订量、库存；运行 `receive_address_list.py` 查当前用户 1688 收货地址。\r\n- 【输出】SKU、规格、价格、起订量、库存；收货人、手机/电话、省市区详细地址、`addressId`。多地址时让用户明确选择，不猜测默认地址。\r\n\r\n### 步骤 4：下单预览\r\n\r\n- 【输入】`offerId`、SKU/规格、数量、收货地址、schema 要求的其他交易字段。\r\n- 【动作】运行 `order_preview.py`。\r\n- 【输出】商品/offerId、SKU/规格、数量、单价与商品总价、运费、收货地址、订单总额、买家留言、异常/库存/价格变化提示。预览失败 → 停止，不进入创建订单，向用户说明并重新确认参数。\r\n\r\n### 步骤 5：创建订单（高风险）\r\n\r\n- 【输入】预览通过的下单参数、用户对本次订单的单独中文确认（如\"确认创建这个订单\"）。\r\n- 【动作】用户单独确认后，Agent 在 payload 中自动加入 JSON boolean `confirmCreateOrder=true`，运行 `create_order.py`。\r\n- 【输出】订单号与下单结果。`create_order.py` 会本地拒绝缺少 `confirmCreateOrder=true` 的请求。失败不自动重试。\r\n\r\n### 步骤 6：获取支付链接（高风险）\r\n\r\n- 【输入】订单号、用户对获取该订单支付链接的单独中文确认（如\"确认获取支付链接\"）。\r\n- 【动作】Agent 在 payload 中自动加入 `confirmGetPaymentUrl=true`，运行 `payment_url.py`。\r\n- 【输出】支付链接。创建订单成功不等于用户同意获取支付链接，必须独立确认。失败不自动重试。\r\n\r\n### 步骤 7：订单状态与物流跟踪\r\n\r\n- 【输入】订单号（物流轨迹另需物流标识，以 schema 为准）。\r\n- 【动作】按用户请求运行 `order_status.py`、`logistics.py`、`logistics_trace.py`。\r\n- 【输出】订单状态、物流概览、物流轨迹。仍消耗积分，无用户要求时不连续轮询。\r\n\r\n### 步骤 8：取消订单（高风险）\r\n\r\n- 【输入】`orderId`、取消原因（如 schema 要求）、用户对该订单的单独中文确认（如\"确认取消这个订单\"）。\r\n- 【动作】先展示 `orderId`、当前订单状态、取消原因、可能的履约或退款影响；用户单独确认后，Agent 在 payload 加入 `confirmCancel=true`，运行 `cancel_order.py`。\r\n- 【输出】取消结果。失败不自动重试，避免重复取消。\r\n\r\n### 步骤 9：确认收货（高风险）\r\n\r\n- 【输入】`orderId`、用户对确认收货的单独中文确认（如\"确认收货\"）。\r\n- 【动作】用户查询物流、看到已签收、或问\"状态怎么样\"都不等于确认收货；用户明确确认后，Agent 在 payload 加入 `confirmReceive=true`，运行 `confirm_receive.py`。\r\n- 【输出】确认收货结果。失败不自动重试，避免重复确认。\r\n\r\n## 高风险确认字段\r\n\r\n用户侧只需用中文自然语言做单独明确确认，不要要求用户输入英文参数名或 `=true`。Agent 收到中文确认后调用脚本时自动加入对应 JSON boolean 安全字段（必须为 boolean `true`，字符串 `\"true\"`、数字 `1` 均被本地拒绝）。\r\n\r\n| 操作 | 必填字段 |\r\n|---|---|\r\n| `createOrder` | `confirmCreateOrder=true` |\r\n| `paymentUrl` | `confirmGetPaymentUrl=true` |\r\n| `confirmReceive` | `confirmReceive=true` |\r\n| `cancelOrder` | `confirmCancel=true` |\r\n\r\n## 调用方式\r\n\r\n- **API 端点**：`POST /alibaba1688/{authorizeUrl|authorizedStores|receiveAddressList|sku|orderPreview|createOrder|paymentUrl|orderStatus|logistics|logisticsTrace|confirmReceive|cancelOrder}`（完整参数、响应与错误处理见 [references/api.md](references/api.md)）。\r\n- **Python 脚本**：`python scripts/<script_name>.py '<JSON 参数>' [--inline] [--save] [--no-save]`。\r\n- **Windows 推荐**：`$env:PAYLOAD = '<JSON 参数>'` 后运行 `python scripts/<script_name>.py --payload-env PAYLOAD [--inline] [--save]`。\r\n\r\n```powershell\r\n$env:PAYLOAD = \"{}\"\r\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\r\n```\r\n\r\n**脚本入参方式**：直接传 JSON 字符串、`--payload-env PAYLOAD`、`--payload-file payload.json`；`--inline` 强制全量打印到 stdout；`--save` 强制保存脱敏完整响应；`--no-save` 禁止保存。\r\n\r\n**输出策略**：响应体 ≤ 8 KB 默认不落盘，直接把完整脱敏 JSON 打印到 stdout；> 8 KB 默认写入 `<writable-root>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-1688-procurement-<operation>-<timestamp>.json`，stdout 只输出摘要。`<writable-root>` 优先取 `ACPX_WORKSPACES` 第一个工作区，其次当前目录，最后用户目录；`<session>` 取自 `SESSION_ID`，未提供时自动生成；禁止写入 `/tmp`。加 `--save` 或 `LINKFOX_SKILL_SAVE_RESPONSE=1` 强制保存；`--no-save` 或 `LINKFOX_SKILL_NO_SAVE=1` 禁止保存。\r\n\r\n**读数据建议**：先看 stdout 摘要判断是否足够；需要完整响应再加 `--save`，之后用 `jq` 或 `ConvertFrom-Json` 从保存的 JSON 按需抽取，避免整份 JSON 进入上下文。\r\n\r\n## 展示规则\r\n\r\n1. 采购依赖 OAuth 时先展示授权状态；不单凭浏览器跳转判断授权。\r\n2. `authorizedStores` 输出是当前 LinkFox 用户的 1688 授权状态，不要描述成数据库全库账号列表。\r\n3. 永不展示完整 API key、JWT、access token、refresh token、callback code、app secret、session key、Authorization header。\r\n4. 清晰展示下单预览：商品/offerId、SKU/规格、数量、单价、商品总价、运费、收货地址、订单总额、买家留言、警告。\r\n5. 高风险调用前复述精确操作、关键 ID、金额/状态（如可得），请用户中文确认；不要求用户输入内部 boolean 字段。\r\n6. 收货地址展示到足以安全选择即可，避免不必要地重复完整手机号或敏感地址细节。\r\n7. 返回 `costToken` 或等价成本字段时如实展示。\r\n\r\n## 用户表达与场景速查\r\n\r\n**适用** —— 1688 已授权采购履约：\r\n\r\n| 用户说 | 场景 |\r\n|--------|------|\r\n| \"查询我的1688授权店铺\" / \"show my authorized 1688 stores\" | 授权检查 |\r\n| \"生成1688授权链接\" / \"authorize my 1688 account\" | 发起新授权 |\r\n| \"查这个 offerId 的 SKU\" | SKU 查询 |\r\n| \"查1688收货地址\" | 收货地址查询 |\r\n| \"帮我预览1688订单\" | 下单预览 |\r\n| \"确认下单\" | 高风险创建订单门 |\r\n| \"获取支付链接\" | 高风险支付链接门 |\r\n| \"查1688订单状态/物流\" | 订单跟踪 |\r\n| \"取消这个1688订单\" | 高风险取消门 |\r\n| \"确认收货\" | 高风险确认收货门 |\r\n\r\n不适用场景见上方【能力边界】。\r\n\r\n## 解决认证和积分问题\r\n\r\n发生以下异常情况时，采用以下措施来处理：\r\n\r\n### 异常情况\r\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\r\n- **响应401或402状态码**\r\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\r\n\r\n### 措施\r\n- 优先采用skill内的 onboarding.md 引导解决问题。\r\n- 如找不到 onboarding.md 文件，则加载 /linkfox-onboarding 这个skill并根据它的引导来处理。如未安装请先安装：\r\n    - 下载 https://agent-files.linkfox.com/skills/linkfox-onboarding/release.zip，解压后安装这个skill。\r\n\r\n---\r\n\r\n# 1688采购流程 API 参考\r\n\r\n本文记录 `linkfox-1688-procurement` 的 tool-gateway 调用规范、脚本入口、风险等级和关键字段。具体入参以网关当前 MCP schema 为准。\r\n\r\n## 调用规范\r\n\r\n- 请求地址：`${LINKFOX_TOOL_GATEWAY}<path>`，默认网关为 `https://tool-gateway.linkfox.com`\r\n- 请求方式：`POST`\r\n- Content-Type：`application/json; charset=utf-8`\r\n- 认证方式：Header `Authorization: <api_key>`\r\n- API key 读取顺序：`LINKFOX_AGENT_API_KEY`，然后 `LINKFOXAGENT_API_KEY`（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\r\n- User-Agent：`LinkFox-Skill/2.0`\r\n- 透传 Header：`SESSION_ID`、`MODE_ID`、`APP_NAME`\r\n- 超时：120s\r\n- 输出保存：小响应默认不落盘；大响应、`--save` 或 `LINKFOX_SKILL_SAVE_RESPONSE=1` 时保存脱敏完整响应；`--no-save` 或 `LINKFOX_SKILL_NO_SAVE=1` 可禁止保存\r\n- 缓存策略：不做 24h 响应缓存。授权、价格、库存、订单状态和物流以实时返回为准，高风险写操作不得缓存或自动重放。\r\n\r\nWindows 推荐使用 `--payload-env` 或 `--payload-file`，避免 shell 转义破坏 JSON。\r\n\r\n```powershell\r\n$env:PAYLOAD = \"{}\"\r\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\r\n```\r\n\r\n## 授权规则\r\n\r\n`authorizedStores` 是当前 LinkFox 用户的 1688 OAuth 授权检查入口。它依赖 API key 中的 LinkFox 用户身份，后端应只返回当前用户的授权店铺。\r\n\r\n脚本层规则：\r\n\r\n- `authorizeUrl` 不做 1688 OAuth 前置检查，因为它用于发起授权。\r\n- `authorizedStores` 不做 1688 OAuth 前置检查，因为它本身就是检查入口。\r\n- 其他采购操作在调用目标 endpoint 前，脚本会先调用 `authorizedStores`。\r\n- 没有 `status=ACTIVE` 且 `expired=false` 的店铺时，脚本返回 `authorization_required`，不会调用目标 endpoint。\r\n\r\n这层检查不能替代后端鉴权；后端仍必须按 `Token.uid` 或等价用户身份过滤和校验授权。\r\n\r\n## MCP 与 Skill 暴露关系\r\n\r\nMCP 工具启停和 Skill HTTP 调用是两层能力：\r\n\r\n| 层级 | 控制内容 | 对本 Skill 的影响 |\r\n|---|---|---|\r\n| MCP tool enabled | 是否出现在 MCP 工具列表或 Agent 工具调用面 | 不决定脚本是否能 HTTP 调用 |\r\n| Gateway route enabled | tool-gateway 是否转发对应 HTTP path | 决定脚本是否可用 |\r\n| Backend capability enabled | ecom-plat 是否处理业务 | 决定最终业务是否可用 |\r\n\r\n因此，MCP 停用但 gateway route 仍启用时，Skill 脚本可以继续使用。若要完全停用某能力，应关闭 gateway route 或后端能力。\r\n\r\n## 禁止作为 Skill 能力的端点\r\n\r\n以下是授权闭环或 MyERP/ecom-plat 后端回调路径，不是 MCP 工具，不应写成 Skill 脚本：\r\n\r\n- `/alibaba1688/proxy/callback`\r\n- `/alibaba1688/authorizeCallback`\r\n- `/alibaba1688/oauth/callback`\r\n\r\n## API 与脚本一览\r\n\r\n| 能力 | MCP tool | Path | Script | 风险 | OAuth 前置检查 | 确认字段 |\r\n|---|---|---|---|---|---|---|\r\n| 生成授权链接 | `_alibaba1688_authorizeUrl` | `/alibaba1688/authorizeUrl` | `authorize_url.py` | 低 | 否 | - |\r\n| 查询已授权账号 | `_alibaba1688_authorizedStores` | `/alibaba1688/authorizedStores` | `authorized_stores.py` | 低 | 否 | - |\r\n| 查询收货地址 | `_alibaba1688_receiveAddressList` | `/alibaba1688/receiveAddressList` | `receive_address_list.py` | 低 | 是 | - |\r\n| 查询 SKU | `_alibaba1688_sku` | `/alibaba1688/sku` | `sku.py` | 低 | 是 | - |\r\n| 下单预览 | `_alibaba1688_orderPreview` | `/alibaba1688/orderPreview` | `order_preview.py` | 中 | 是 | - |\r\n| 创建订单 | `_alibaba1688_createOrder` | `/alibaba1688/createOrder` | `create_order.py` | 高 | 是 | `confirmCreateOrder=true` |\r\n| 获取支付链接 | `_alibaba1688_paymentUrl` | `/alibaba1688/paymentUrl` | `payment_url.py` | 高 | 是 | `confirmGetPaymentUrl=true` |\r\n| 查询订单状态 | `_alibaba1688_orderStatus` | `/alibaba1688/orderStatus` | `order_status.py` | 低 | 是 | - |\r\n| 查询物流 | `_alibaba1688_logistics` | `/alibaba1688/logistics` | `logistics.py` | 低 | 是 | - |\r\n| 查询物流轨迹 | `_alibaba1688_logisticsTrace` | `/alibaba1688/logisticsTrace` | `logistics_trace.py` | 低 | 是 | - |\r\n| 确认收货 | `_alibaba1688_confirmReceive` | `/alibaba1688/confirmReceive` | `confirm_receive.py` | 高 | 是 | `confirmReceive=true` |\r\n| 取消订单 | `_alibaba1688_cancelOrder` | `/alibaba1688/cancelOrder` | `cancel_order.py` | 高 | 是 | `confirmCancel=true` |\r\n\r\n`_alibaba1688_imageSearch` 由 `linkfox-1688-search-by-image` 独立承担，本 Skill 不包含图搜脚本。\r\n\r\n## 入参要点\r\n\r\n| 能力 | 关键字段说明 |\r\n|---|---|\r\n| `authorizeUrl` | 按 schema 传授权展示字段；如需账号标签，优先使用 `accountName` |\r\n| `authorizedStores` | 通常无需业务参数；用户身份来自 LinkFox API key |\r\n| `receiveAddressList` | 依赖当前用户 ACTIVE 1688 授权 |\r\n| `sku` | 通常需要 `offerId` |\r\n| `orderPreview` | 通常需要 `offerId`、SKU/规格、数量、收货地址等下单参数 |\r\n| `createOrder` | 下单参数与预览保持一致，并必须加 `confirmCreateOrder=true` |\r\n| `paymentUrl` | 通常需要订单号，并必须加 `confirmGetPaymentUrl=true` |\r\n| `orderStatus` | 通常需要订单号 |\r\n| `logistics` | 通常需要订单号 |\r\n| `logisticsTrace` | 通常需要订单号及物流标识，以 schema 为准 |\r\n| `confirmReceive` | 订单号 + `confirmReceive=true` |\r\n| `cancelOrder` | 订单号、取消原因（如 schema 要求）+ `confirmCancel=true` |\r\n\r\n## 高风险校验\r\n\r\n用户侧只需要用中文自然语言做单独明确确认，例如“确认创建这个订单”“确认获取这个订单的支付链接”“确认取消这个订单”“确认收货”。不要要求用户输入英文参数名或 `=true`。\r\n\r\nAgent 在收到中文确认后，调用脚本时必须自动加入对应 JSON boolean 安全字段。高风险脚本会在本地先校验确认字段，确认字段不满足时不会联网：\r\n\r\n| 脚本 | 本地拒绝条件 |\r\n|---|---|\r\n| `create_order.py` | 缺少 JSON boolean `confirmCreateOrder=true` |\r\n| `payment_url.py` | 缺少 JSON boolean `confirmGetPaymentUrl=true` |\r\n| `confirm_receive.py` | 缺少 JSON boolean `confirmReceive=true` |\r\n| `cancel_order.py` | 缺少 JSON boolean `confirmCancel=true` |\r\n\r\n字符串 `\"true\"`、数字 `1`、大小写变体都不算确认。\r\n\r\n## 响应与错误处理\r\n\r\n- HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。\r\n- HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。\r\n- `authorization_required`：没有当前用户 ACTIVE 1688 OAuth 授权；先运行 `authorize_url.py`，用户授权后再运行 `authorized_stores.py` 验证。\r\n- 下单预览失败：停止，不要进入创建订单；向用户说明失败原因并重新确认参数。\r\n- 高风险写操作失败：不要自动重试，避免重复下单、重复取消或重复确认收货。\r\n\r\n## 敏感信息规则\r\n\r\n脚本会对常见敏感字段做脱敏落盘。Agent 展示结果时仍需避免暴露：\r\n\r\n- LinkFox API key / JWT\r\n- 1688 access token / refresh token\r\n- Authorization header\r\n- OAuth callback `code`\r\n- app secret / session key / refresh secret\r\n\r\n---\r\n\r\n# 1688采购流程地图\r\n\r\n本文档是流程地图，不是自动化脚本。Agent 可以按步骤协助用户完成采购，但不能一次性自动执行完整下单闭环。\r\n\r\n## 总原则\r\n\r\n1. 采购业务先查授权，再查商品和地址，再预览，再让用户确认。\r\n2. 图搜找货使用 `linkfox-1688-search-by-image`，本 Skill 只处理采购履约。\r\n3. 除 `authorizeUrl` 和 `authorizedStores` 外，脚本会在每个采购 endpoint 前自动检查当前用户 ACTIVE 授权。\r\n4. 下单、支付链接、取消订单、确认收货都是独立高风险动作，各自需要单独确认。\r\n5. 用户前面说过\"继续\"\"可以\"\"按上面来\"，不能作为后续高风险动作的确认。\r\n\r\n## 1. 授权检查\r\n\r\n运行：\r\n\r\n```powershell\r\n$env:PAYLOAD = \"{}\"\r\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\r\n```\r\n\r\n判断：\r\n\r\n- 有 `status=ACTIVE` 且 `expired=false`：可以继续采购流程。\r\n- 没有 ACTIVE 授权：进入授权步骤。\r\n- 浏览器最后跳到 MyERP 登录页不等于授权失败；以 `authorized_stores.py` 返回为准。\r\n\r\n`authorizedStores` 应只返回当前 LinkFox API key 对应用户的授权店铺。不要把它理解为后台全库账号列表。\r\n\r\n## 2. 发起授权\r\n\r\n运行 `authorize_url.py` 获取 1688 授权链接，并让用户在浏览器打开。\r\n\r\n用户完成授权后，再运行 `authorized_stores.py` 验证是否出现 ACTIVE 账号。\r\n\r\n不要让用户提供 1688 token、refresh token 或 callback code。授权 token 保存由 MyERP/ecom-plat 后端闭环完成。\r\n\r\n## 3. 找货与 SKU\r\n\r\n如果用户按图片找货：\r\n\r\n1. 切换到 `linkfox-1688-search-by-image`。\r\n2. 从图搜结果中选择目标 `offerId`。\r\n3. 回到本 Skill，用 `sku.py` 查询 SKU/规格。\r\n\r\n如果用户已提供 `offerId`：\r\n\r\n1. 直接运行 `sku.py`。\r\n2. 展示 SKU、规格、价格、起订量、库存等关键字段。\r\n3. 让用户选择明确的 SKU 和数量。\r\n\r\n## 4. 收货地址\r\n\r\n运行 `receive_address_list.py` 查询当前用户可用的 1688 收货地址。\r\n\r\n展示地址时应包含：\r\n\r\n- 收货人\r\n- 手机/电话（如返回）\r\n- 省市区与详细地\n\nArchive v1.2.0: 24 files, 58855 bytes\n\nFiles: references/linkfox-1688-procurement.md (23508b), references/linkfox-1688-search-by-image.md (15759b), references/linkfox-dld-product-billboard.md (12861b), references/linkfox-dld-product-search.md (12271b), scripts/_alibaba1688_common.py (12498b), scripts/alibaba1688_image_search.py (12725b), scripts/authorize_url.py (124b), scripts/authorized_stores.py (128b), scripts/cancel_order.py (123b), scripts/confirm_receive.py (126b), scripts/create_order.py (123b), scripts/dld_product_billboard.py (13086b), scripts/dld_product_search.py (13048b), scripts/logistics_trace.py (126b), scripts/logistics.py (121b), scripts/order_preview.py (124b), scripts/order_status.py (123b), scripts/payment_url.py (122b), scripts/receive_address_list.py (130b), scripts/sku.py (115b), scripts/upload_image.py (4591b), skill-card.md (3059b), SKILL.md (19960b), _meta.json (140b)\n\nArchive v1.0.1: 24 files, 58860 bytes\n\nFiles: references/linkfox-1688-procurement.md (23508b), references/linkfox-1688-search-by-image.md (15759b), references/linkfox-dld-product-billboard.md (12861b), references/linkfox-dld-product-search.md (12271b), scripts/_alibaba1688_common.py (12498b), scripts/alibaba1688_image_search.py (12725b), scripts/authorize_url.py (124b), scripts/authorized_stores.py (128b), scripts/cancel_order.py (123b), scripts/confirm_receive.py (126b), scripts/create_order.py (123b), scripts/dld_product_billboard.py (13086b), scripts/dld_product_search.py (13048b), scripts/logistics_trace.py (126b), scripts/logistics.py (121b), scripts/order_preview.py (124b), scripts/order_status.py (123b), scripts/payment_url.py (122b), scripts/receive_address_list.py (130b), scripts/sku.py (115b), scripts/upload_image.py (4591b), skill-card.md (2992b), SKILL.md (19959b), _meta.json (140b)\n\nArchive v1.0.0: 24 files, 58816 bytes\n\nFiles: references/linkfox-1688-procurement.md (23508b), references/linkfox-1688-search-by-image.md (15759b), references/linkfox-dld-product-billboard.md (12861b), references/linkfox-dld-product-search.md (12271b), scripts/_alibaba1688_common.py (12498b), scripts/alibaba1688_image_search.py (12725b), scripts/authorize_url.py (124b), scripts/authorized_stores.py (128b), scripts/cancel_order.py (123b), scripts/confirm_receive.py (126b), scripts/create_order.py (123b), scripts/dld_product_billboard.py (13086b), scripts/dld_product_search.py (13048b), scripts/logistics_trace.py (126b), scripts/logistics.py (121b), scripts/order_preview.py (124b), scripts/order_status.py (123b), scripts/payment_url.py (122b), scripts/receive_address_list.py (130b), scripts/sku.py (115b), scripts/upload_image.py (4591b), skill-card.md (2757b), SKILL.md (19860b), _meta.json (140b)","readmeExcerpt":"Skill: Linkfox 1688货源 Owner: linkfox-ai Summary: 1688一站式采购工具，集商品搜索、热销榜单、以图搜图及授权下单与物流跟踪全流程服务。 Tags: latest:1.2.3 Version history: v1.2.3 | 2026-08-14T14:39:13.587Z | user Update from 1.2.2 to 1.2.3 v1.2.2 | 2026-08-07T10:34:51.841Z | user Update from 1.2.1 to 1.2.2 v1.2.1 | 2026-08-05T08:56:53.093Z | user Update from 1.2.0 to 1.2.1 v1.2.0 | 2026-07-16T03:57:10.217Z | user Update from 1.0.1 to 1.2.0 v1.0.1 | 2026-07-16","codeSnippets":[],"executableExamples":[{"language":"json","snippet":"{\"keyWord\": \"瑜伽垫\", \"cycle\": \"30\", \"sortField\": \"saleCount30d\", \"sortType\": \"desc\", \"pageSize\": 20}"},{"language":"json","snippet":"{\"keyWord\": \"手机壳\", \"pageType\": 3, \"date\": \"2026-03-01\", \"sortField\": \"orderCount\", \"sortType\": \"desc\", \"pageSize\": 20}"},{"language":"json","snippet":"{\"imageUrl\": \"https://m.media-amazon.com/images/I/719mRAn2VrL._AC_SL1500_.jpg\", \"page\": 1, \"pageSize\": 20, \"filter\": \"1688Selection,totalEpScoreLv1\", \"sort\": \"{\\\"monthSold\\\":\\\"desc\\\"}\"}"},{"language":"json","snippet":"{}"},{"language":"json","snippet":"{\"offerId\": \"123456789\"}"},{"language":"json","snippet":"{\"offerId\": \"123456789\", \"quantity\": 10, \"addressId\": \"...\"}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: linkfox-1688-sourcing\ndisplay_name: Linkfox 1688货源\ndisplay_name_en: LinkFox 1688 Sourcing\ndescription: 1688 货源一站式 AI 工具集，整合商品搜索、热销榜单、以图搜图与已授权采购履约，覆盖找货、选品、比价、图搜同款与下单全流程。\ndescription_zh: 1688 货源一站式工具集：店雷达商品搜索与热销榜单（关键词/链接/ID 检索、周榜月榜、多维筛选排序、批发价/代发价/销量与供应商资质）、1688 以图搜图（图片 URL/Base64/imageId 视觉检索同款货源，含本地图片上传）、1688 已授权采购全流程（OAuth 授权检查、SKU/收货地址、下单预览、创建订单、支付链接、订单状态、物流轨迹、取消订单、确认收货）。当用户需要 1688 找货源、找供应商、批发选品、热销榜单、以图找同款、跨境找工厂或已授权采购下单与物流跟踪时触发。各子能力完整参数见 references/ 对应文件，脚本见 scripts/。\ndescription_en: One-stop 1688 sourcing AI toolkit: store-radar product search and bestseller billboards (keyword/URL/ID retrieval, weekly/monthly rankings, multi-dimensional filters and sorting, wholesale/dropship price, sales and supplier qualifications), 1688 image search (visual retrieval of same-style sourcing by image URL/Base64/imageId, with local image upload), and end-to-end authorized 1688 procurement (OAuth checks, SKU/address, order preview, order creation, payment URL, order status, logistics tracking, cancellation, receipt confirmation). Triggered when the user needs 1688 sourcing, supplier discovery, wholesale product selection, bestseller rankings, image-based same-product search, cross-border factory sourcing, or authorized 1688 procurement ordering and logistics tracking. Full params per sub-capability are in references/, executable scripts in scripts/.\ncategory: e-commerce\nversion: 1.0.0\nauthor: LinkFox\n---\n\n# Linkfox 1688货源（1688 Sourcing）\n\n1688 货源一站式 AI 工具集，整合 **3 类底层工具、4 项子能力**，覆盖货源搜索与热销榜单、以图搜图、已授权采购履约。各子能力完整参数、响应字段与错误码见 `references/` 下对应文件，可执行脚本见 `scripts/`。\n\n## 能力边界\n\n### ✅ 能力范围\n- **货源搜索与榜单（`1688_sourcing`）**：商品搜索（`linkfox-dld-product-search`，按关键词/商品链接/商品 ID 检索 1688 批发商品，近 7 天/30 天销量周期，按价格/销量/销售额/上架时间排序，按公司类型/卖家会员/发货时间/代发权益/面单支持等筛选）、商品热销榜单（`linkfox-dld-product-billboard`，周榜/月榜，按销售笔数/销售额/销量排序，发现爆款与趋势货源）。返回批发价、代发价、销售笔数/件数、预估销售额、起批量、供应商资质、店铺与商品链接等。\n- **以图搜图（`1688_search_by_image`）**：1688 以图搜图（`linkfox-1688-search-by-image`，通过图片 URL/Base64/imageId 视觉检索外观相似或同款货源），返回标题、批发价、代发价、月销量、起批量、复购率、交易评分、商家身份（超级工厂/实力商家/诚信通）等；支持价格/筛选（1688 严选/认证工厂/发货时效/品质退款率等）/排序/分页；本地图片先用 `upload_image.py` 上传获取公网 URL（有效期 24h）。\n- **采购履约（`1688_procurement`）**：1688 采购全流程（`linkfox-1688-procurement`），覆盖 OAuth 授权检查与发起授权、SKU/规格与收货地址查询、下单预览、创建订单、获取支付链接、订单状态、物流概览与物流轨迹、取消订单、确认收货。除授权类操作外每个 endpoint 前自动校验当前用户 ACTIVE 且未过期的 1688 授权；高风险写操作（创建订单/支付链接/取消订单/确认收货）需用户单独中文确认后由 Agent 注入对应 boolean 安全字段。\n- 数据平台均为中国大陆 1688 批发平台（阿里巴巴国内 B2B 市场），无多站点概念。\n\n### ❌ 边界与限制\n- **API Key 必需**：所有工具均需环境变量 `LINKFOX_AGENT_API_KEY`（或 `LINKFOXAGENT_API_KEY`）；各工具独立计费、独立限频。\n- **计费约束**：商品搜索/热销榜单固定计费（成功约 9 积分/18000 token），以图搜图固定计费（约 4.5 积分/9000 token），采购履约各操作消耗积分；同一会话同一参数组合默认只调用一次（搜索/榜单/图搜脚本带 24h 本地缓存）；失败、空结果、参数不全或授权不足不得自动换关键词、翻页或连续试探；需继续检索时先向用户说明会产生额外消耗（各工具计费规则见 `skills-version.json` 对应条目与 references 内 api.md）。\n- **采购授权前置**：采购类操作依赖当前用户已授权的 1688 OAuth；无 ACTIVE 授权时不调用目标 endpoint；高风险写操作失败不自动重试；不向用户索要 1688 token/refresh token/callback code/app secret。\n- **不在范围内**：Amazon/TikTok/沃尔玛等其他平台选品（用对应平台技能）；Alibaba.com 国际站数据；1688 店铺级分析（店铺流量/排名/评分"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n  \"slug\": \"linkfox-1688-sourcing\",\n  \"version\": \"1.2.3\",\n  \"publishedAt\": 1786718353587\n}"},{"path":"references/linkfox-1688-procurement.md","content":"---\r\nname: linkfox-1688-procurement\r\ndescription: 协助当前用户完成已授权的 1688 采购履约流程，包括授权检查、SKU/地址查询、订单预览、下单、支付、订单和物流跟踪等。\r\n\r\n# 1688采购全流程（1688 Procurement Workflow）\r\n\r\n本技能帮助 LinkFox 用户完成已授权的 1688 采购履约：OAuth 授权检查、SKU 与收货地址查询、下单预览、受保护的下单、支付链接获取、订单与物流跟踪、取消订单、确认收货。图搜找货使用 `linkfox-1688-search-by-image`，本技能不含图搜。端点与字段详见 [references/api.md](references/api.md)，多步采购前先读 [references/workflow.md](references/workflow.md)。\r\n\r\n## 能力边界\r\n\r\n### ✅ 能力范围\r\n\r\n- 查询当前 LinkFox 用户的 1688 OAuth 授权状态、发起授权链接。\r\n- 查询商品 SKU/规格、收货地址，进行下单预览（价格、运费、库存、地址）。\r\n- 在用户单独中文确认后执行高风险写操作：创建订单、获取支付链接、取消订单、确认收货。\r\n- 查询订单状态、物流概览与物流轨迹。\r\n\r\n### ❌ 边界与限制\r\n\r\n- **图搜不在范围**：以图搜图使用 `linkfox-1688-search-by-image`，本技能不包含图搜脚本。\r\n- **授权前置**：除 `authorize_url.py` 和 `authorized_stores.py` 外，每个采购操作调用目标 endpoint 前都会先检查当前用户 ACTIVE 且未过期的 1688 授权；无授权时不调用目标 endpoint。\r\n- **非自动化闭环**：视作流程地图而非全自动执行；不因\"继续\"\"可以\"等前文措辞自动创建订单、获取支付链接、取消订单或确认收货。\r\n- **回调端点不暴露**：`/alibaba1688/proxy/callback`、`/alibaba1688/authorizeCallback`、浏览器 OAuth 回调 URL 不作为 Skill 能力。\r\n- **不索要凭据**：不向用户索要 1688 token、refresh token、callback code、app secret；token 闭环由 MyERP/ecom-plat 后端完成。\r\n- **不查后端库**：不查后端库判断授权状态，使用 `authorizedStores`。\r\n- **不自动重试**：高风险写操作失败不自动重试；不使用 `_dataQuery_executeDynamicQuery` 获取实时采购响应。\r\n- **MCP 与 HTTP 分离**：MCP 启停只控制 MCP 暴露；脚本直连 tool-gateway HTTP route，彻底停用需关 route 或后端能力。\r\n- **成本约束**：调用消耗积分；失败、空结果、参数不全或授权不足时不自动连续试探或轮询，继续查询前先向用户说明会产生额外消耗。\r\n\r\n## 执行流程\r\n\r\n采购流程按步骤协助用户完成，不能一次性自动执行完整下单闭环。每一步均不可跳过授权前置与高风险确认。\r\n\r\n### 步骤 1：授权检查\r\n\r\n- 【输入】当前 LinkFox 用户身份（来自 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY`）。\r\n- 【动作】运行 `authorized_stores.py`，检查是否存在 `status=ACTIVE` 且 `expired=false` 的 1688 授权。\r\n- 【输出】有 ACTIVE 授权 → 可继续采购；无 ACTIVE 授权 → 进入步骤 2。浏览器跳到 MyERP 登录页不等于授权失败，以脚本返回为准。\r\n\r\n### 步骤 2：发起授权（仅未授权时）\r\n\r\n- 【输入】当前用户身份。\r\n- 【动作】运行 `authorize_url.py` 获取 1688 授权链接，让用户在浏览器完成 OAuth；完成后重新运行 `authorized_stores.py` 验证。\r\n- 【输出】ACTIVE 授权账号出现 → 回到步骤 1 确认后继续。不要让用户提供 token、refresh token 或 callback code。\r\n\r\n### 步骤 3：SKU 与收货地址查询\r\n\r\n- 【输入】`offerId`（用户提供，或从 `linkfox-1688-search-by-image` 结果获得）。\r\n- 【动作】运行 `sku.py` 查 SKU/规格、价格、起订量、库存；运行 `receive_address_list.py` 查当前用户 1688 收货地址。\r\n- 【输出】SKU、规格、价格、起订量、库存；收货人、手机/电话、省市区详细地址、`addressId`。多地址时让用户明确选择，不猜测默认地址。\r\n\r\n### 步骤 4：下单预览\r\n\r\n- 【输入】`offerId`、SKU/规格、数量、收货地址、schema 要求的其他交易字段。\r\n- 【动作】运行 `order_preview.py`。\r\n- 【输出】商品/offerId、SKU/规格、数量、单价与商品总价、运费、收货地址、订单总额、买家留言、异常/库存/价格变化提示。预览失败 → 停止，不进入创建订单，向用户说明并重新确认参数。\r\n\r\n### 步骤 5：创建订单（高风险）\r\n\r\n- 【输入】预览通过的下单参数、用户对本次订单的单独中文确认（如\"确认创建这个订单\"）。\r\n- 【动作】用户单独确认后，Agent 在 payload 中自动加入 JSON boolean `confirmCreateOrder=true`，运行 `create_order.py`。\r\n- 【输出】订单号与下单结果。`create_order.py` 会本地拒绝缺少 `confirmCreateOrder=true` 的请求。失败不自动重试。\r\n\r\n### 步骤 6：获取支付链接（高风险）\r\n\r\n- 【输入】订单号、用户对获取该订单支付链接的单独中文确认（如\"确认获取支付链接\"）。\r\n- 【动作】Agent 在 payload 中自动加入 `confirmGetPaymentUrl=true`，运行 `payment_url.py`。\r\n- 【输出】支付链接。创建订单成功不等于用户同意获取支付链接，必须独立确认。失败不自动重试。\r\n\r\n### 步骤 7：订单状态与物流跟踪\r\n\r\n- 【输入】订单号（物流轨迹另需物流标识，以 schema 为准）。\r\n- 【动作】按用户请求运行 `order_status.py`、`logistics.py`、`logistics_trace.py`。\r\n- 【输出】订单状态、物流概览、物流轨迹。仍消耗积分，无用户要求时不连续轮询。\r\n\r\n### 步骤 8：取消订单（高风险）\r\n\r\n- 【输入】`orderId`、取消原因（如 sc"},{"path":"references/linkfox-1688-search-by-image.md","content":"---\r\nname: linkfox-1688-search-by-image\r\ndescription: 通过图片 URL 在 1688 平台以图搜图，检索外观相似或同款货源的商品数据。\r\n\r\n# 1688 以图搜图（1688 Image-Based Product Search）\r\n\r\n本技能通过图片 URL 在 1688 平台进行以图搜图，帮助跨境卖家找到外观相似或同款的 1688 货源商品。参数与响应字段详见 [references/api.md](references/api.md)。\r\n\r\n## 能力边界\r\n\r\n### ✅ 能力范围\r\n\r\n- 通过图片 URL、Base64 或 imageId 在 1688 平台进行视觉检索，返回外观相似或同款的货源商品。\r\n- 提供商品标题、批发价、一件代发价、月销量、起批量、复购率、交易评分、商家身份等核心数据。\r\n- 支持按价格区间、过滤条件（1688 严选、认证工厂、发货时效、品质退款率等）、排序（价格/月销/复购率）、分页查询。\r\n\r\n### ❌ 边界与限制\r\n\r\n- **图片来源**：`imageUrl`/`imageBase64`/`imageId` 三选一必填；`imageUrl` 须为可公开访问的公网链接。\r\n- **图片格式**：仅支持 png/jpg/jpeg，不支持 webp/gif 等格式。\r\n- **Base64 格式**：`imageBase64` 必须为纯编码内容，不能包含 `data:image/jpeg;base64,` 前缀。\r\n- **分页上限**：每页最多 50 条；`page > 1` 时建议回传 `imageId` 以加速查询。\r\n- **数据时效**：结果为实时搜索，不入库，无法进行二次 SQL 或 `_dataQuery_executeDynamicQuery` 处理。\r\n- **筛选/排序限制**：仅支持预设的过滤条件与排序字段；用户请求未列出的排序或过滤条件时，不要调用其他工具或逻辑兜底，应告知支持的选项。\r\n- **本地图片**：本工具需要可公开访问的图片 URL；用户提供本地文件路径时，须先调用上传脚本获取公网 URL（见下方「本地图片上传」）。\r\n- **不在范围内**：基于关键词的 1688 文本搜索（用店雷达-1688 选品库）；1688 商品排行/趋势（用店雷达-1688 商品榜单）；Amazon 以图搜图（用亚马逊前端-以图搜图）；图片生成或编辑；商品评论分析；价格历史或趋势分析。\r\n\r\n## 核心概念\r\n\r\n1688 以图搜图基于视觉识别，在 1688 批发平台查找外观相似的商品，返回供应商商品数据，包括标题、价格、起批量、月销量、复购率、交易评分及商家身份标识。\r\n\r\n**默认行为**：第 1 页、每页 20 条，按月销量降序（`sort` 默认 `{\"monthSold\":\"desc\"}`）。\r\n\r\n## 调用方式\r\n\r\n- **API 端点**：`POST /alibaba1688/imageSearch`（完整参数/响应/错误码见 `references/api.md`）\r\n- **Python 脚本**：`python scripts/alibaba1688_image_search.py '<JSON 参数>' [--inline]`\r\n- **成本约束**：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。\r\n\r\n**输出策略（脚本默认行为）**：\r\n- **始终**将完整响应写入 `<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-1688-search-by-image-<timestamp>.json`（`<cwd>` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`<session>` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\r\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\r\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\r\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\r\n\r\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq` 或 `ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\r\n\r\n## 本地图片上传\r\n\r\n本工具需要**可公开访问的图片 URL**。若用户提供本地图片文件路径，须先上传以获取公网 URL。\r\n\r\n运行上传脚本：\r\n```bash\r\npython scripts/upload_image.py /path/to/local/image.png\r\n```\r\n\r\n脚本会返回一个公网 URL（有效期 24 小时），可作为 `imageUrl` 参数使用。\r\n\r\n## 使用示例\r\n\r\n**1. 基础以图搜图**\r\n```\r\n在1688搜索与图片相似的商品，图片地址为 https://m.media-amazon.com/images/I/719mRAn2VrL._AC_SL1500_.jpg\r\n```\r\n\r\n**2. 带筛选条件**\r\n```\r\n在1688搜索与图片相似的商品，图片地址为 https://m.media-amazon.com/images/I/719mRAn2VrL._AC_SL1500_.jpg，查询第1页，筛选1688严选，并按价格从高到低排序\r\n```\r\n\r\n**3. 按排序查询**\r\n```\r\n在1688搜索与图片相似的商品，图片地址为 https://example.com/product.jpg，按价格从高到低排序\r\n```\r\n\r\n**4. 分页查询**\r\n```\r\n在1688搜索与图片相似的商品，图片地址为 https://example.com/product.jpg，查询第2页，每页50条\r\n```\r\n\r\n**5. 价格区间筛选**\r\n```\r\n在1688搜索与图片相似的商品，图片地址为 https://example.com/product.jpg，价格区间10-100元\r\n```\r\n\r\n## 展示规则\r\n\r\n1. **清晰呈现数据**：以结构化表格展示关键列——商品图片、标题、批发价、代发价、月销量、起批量、复购率、商家身份。\r\n2. **图片展示**：返回 `imageUrl` 时内联展示商品图片，便于直观对比。\r\n3. **价格格式**：价格统一以人民币（¥）格式展示。\r\n4. **商家标识**：突出展示商家身份（超级工厂/实力商家/诚信通会员）与商品标（严选）。\r\n5. **结果计数**：始终告知总结果数及当前页/总页数。\r\n6. **分页提示**：还有更多页时，提示用户可继续翻页。\r\n7. "},{"path":"references/linkfox-dld-product-billboard.md","content":"---\r\nname: linkfox-dld-product-billboard\r\ndescription: 1688 商品热销榜单查询。用于发现国内货源批发爆款、一件代发选品及趋势商品调研。\r\n\r\n# 1688 商品热销榜单（DLD Product Billboard）\r\n\r\n本技能用于查询 1688 平台商品热销榜单数据，帮助卖家在国内最大的 B2B 批发市场发现热销批发商品与货源机会。参数与响应字段详见 [references/api.md](references/api.md)。\r\n\r\n## 能力边界\r\n\r\n### ✅ 能力范围\r\n\r\n- 查询 1688 平台商品排名数据，覆盖**周榜**与**月榜**两种榜单。\r\n- 发现热销批发商品、对比供应商、识别国内批发市场的货源与趋势机会。\r\n- 支持按关键词、价格区间、销量区间、公司类型（店铺/工厂）、卖家会员类型、发货时间、代发权益、面单支持等多维筛选与排序。\r\n\r\n### ❌ 边界与限制\r\n\r\n- **关键词语言**：`keyWord` 参数必须为中文，非中文关键词需先翻译再查询。\r\n- **日期格式**：周榜日期须为该周周日；月榜日期须为该月第一天。\r\n- **数据时效**：周榜仅近 90 天，月榜仅近 12 个月。\r\n- **分页上限**：单次请求最多 100 条；按商品 ID 查询时最多 20 个。\r\n- **不在范围内**：Amazon 选品与关键词分析（用 ABA 工具）；1688 店铺级分析（店铺排名、店铺评分）；Alibaba.com 国际站数据；价格议价与下单；商品质量评价与认证；物流成本计算与货代。\r\n\r\n## 核心概念\r\n\r\n1688 商品热销榜单提供 1688 平台商品排名数据，覆盖**周榜**与**月榜**，帮助发现趋势批发商品、对比供应商、识别货源机会。\r\n\r\n**榜单类型**：\r\n- **周榜**（`pageType=2`）：日期传该周周日，如 `2025-06-15`；数据为近 90 天。\r\n- **月榜**（`pageType=3`）：日期传该月第一天，如 `2025-06-01`；数据为近 12 个月。\r\n\r\n**默认行为**：月榜，按销售笔数降序，每页 20 条。\r\n\r\n## 使用示例\r\n\r\n**1. 某关键词的月度热销榜**\r\n> \"查一下 1688 本月手机壳的热销榜\"\r\n```json\r\n{\"keyWord\": \"手机壳\", \"pageType\": 3, \"date\": \"2026-03-01\", \"sortField\": \"orderCount\", \"sortType\": \"desc\"}\r\n```\r\n\r\n**2. 周榜按销售额排序**\r\n> \"上周瑜伽垫品类里销售额最高的是哪些？\"\r\n```json\r\n{\"keyWord\": \"瑜伽垫\", \"pageType\": 2, \"date\": \"2026-03-22\", \"sortField\": \"saleVolume\", \"sortType\": \"desc\"}\r\n```\r\n\r\n**3. 工厂直供并限价**\r\n> \"在 1688 找 5-30 元的耳机工厂直供商品\"\r\n```json\r\n{\"keyWord\": \"耳机\", \"companyType\": 2, \"beginPrice\": 5, \"endPrice\": 30, \"sortField\": \"saleCount\", \"sortType\": \"desc\"}\r\n```\r\n\r\n**4. 跨境标签且 24 小时发货**\r\n> \"看下 24 小时内发货的跨境标签 LED 灯商品\"\r\n```json\r\n{\"keyWord\": \"LED灯\", \"offerType\": 4, \"sendTime\": \"24\", \"sortField\": \"orderCount\", \"sortType\": \"desc\"}\r\n```\r\n\r\n**5. 超级工厂新品**\r\n> \"找宠物用品类目下超级工厂的新上架商品\"\r\n```json\r\n{\"keyWord\": \"宠物用品\", \"offerType\": 2, \"shiLiType\": \"superFactory\", \"sortField\": \"offerCreateTime\", \"sortType\": \"desc\"}\r\n```\r\n\r\n**6. 支持代发且有买家保障的商品**\r\n> \"看下支持一件代发、包邮且支持 7 天退货的包包商品\"\r\n```json\r\n{\"keyWord\": \"包包\", \"proxyRights\": \"4360897\", \"buyerProtections\": \"商品包邮,7天包退货\", \"sortField\": \"orderCount\", \"sortType\": \"desc\"}\r\n```\r\n\r\n**7. 价格区间内的高销量商品**\r\n> \"找玩具类目下批发价 50 元以内、销售笔数超 1000 的商品\"\r\n```json\r\n{\"keyWord\": \"玩具\", \"beginOrderCount\": 1000, \"endPrice\": 50, \"sortField\": \"orderCount\", \"sortType\": \"desc\"}\r\n```\r\n\r\n**8. 按商品 ID 查询**\r\n> \"查这几个 1688 商品 ID：123456、789012\"\r\n```json\r\n{\"productIds\": \"123456、789012\"}\r\n```\r\n\r\n## 展示规则\r\n\r\n1. **清晰呈现数据**：以结构化表格展示商品标题、批发价、代发价、销售笔数、销售件数、预估销售额、供应商名称、上架时间等。\r\n2. **图片展示**：返回 `imageUrl` 时展示商品图片，便于直观识别。\r\n3. **提供链接**：附商品链接（`asinUrl`）与店铺链接（`shopUrl`），方便直达 1688 商品页。\r\n4. **价格格式**：价格须带币种（CNY/RMB），并注明是批发价还是代发价。\r\n5. **销量口径**：展示销量数据时，按 `dataType` 字段标明是周数据还是月数据。\r\n6. **分页提示**：总条数超出当前页时，告知总数并询问是否继续翻页。\r\n7. **关键词翻译**：用户提供非中文关键词时，先翻译为中文再查询，并告知译文。\r\n8. **错误处理**：查询失败时说明原因，并建议调整参数（如放宽筛选、检查日期格式）。\r\n\r\n## 用户表达与场景速查\r\n\r\n**适用** —— 1688 批发商品发现与货源调研：\r\n\r\n| 用户说 | 场景 |\r\n|--------|------|\r\n| \"1688 上什么火\"、\"1688 趋势商品\" | 热销商品发现 |\r\n| \"给 XX 找便宜货源\"、\"XX 批发货源\" | 按关键词找货源 |\r\n| \"工厂直供商品\"、\"OEM 供应商\" | 工厂筛选 |\r\n| \"跨境货源\"、\"出口商品\" | 跨境标签筛选 |\r\n| \"1688 一件代发商品\" | 支持代发的商品搜索 |\r\n| \"1688 新品\"、\"最近上架的\" | 新品发现 |\r\n| \"对比 XX 的供应商\" | 多结果对比 |\r\n| \"1688 商品排行\"、\"热"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"1688一站式采购工具，集商品搜索、热销榜单、以图搜图及授权下单与物流跟踪全流程服务。 Skill: Linkfox 1688货源 Owner: linkfox-ai Summary: 1688一站式采购工具，集商品搜索、热销榜单、以图搜图及授权下单与物流跟踪全流程服务。 Tags: latest:1.2.3 Version history: v1.2.3 | 2026-08-14T14:39:13.587Z | user Update from 1.2.2 to 1.2.3 v1.2.2 | 2026-08-07T10:34:51.841Z | user Update from 1.2.1 to 1.2.2 v1.2.1 | 2026-08-05T08:56:53.093Z | user Update from 1.2.0 to 1.2.1 v1.2.0 | 2026-07-16T03:57:10.217Z | user Update from 1.0.1 to 1.2.0 v1.0.1 | 2026-07-16","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1002,"uniquenessScore":47,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T22:38:18.172Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T22:38:18.172Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-12T19:05:43.382Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}