linkfox-1688-product-detail

1688 商品详情

此技能根据商品 ID 获取一条结构化的 1688 商品记录，包含商品、价格、物流和供应商详情，供采购决策使用。

核心概念

• 详情查询，而非发现：查询一个已知的 1688 offerId；如果用户没有商品 ID，请使用搜索技能。
• 完整商品记录：保留返回的标题、属性、媒体、SKU、销量、物流和供应商字段，不要编造缺失值。
• 按数量区分价格语义：存在 retailPrice 时，数量为 1 使用该字段，数量为 2 或以上时使用 SKU price 和 saleInfo.priceRanges[].price。在推广期间，缺少 retailPrice 可能表示旧商品模型或未配置零售价；对于价格敏感型决策，绝不能从其他字段推断 1 件的价格。
• 采购数据：价格、库存、起订量、代发条款、包装、供应商指标、发票和证书均视为实时商品信息。
• 货币语义：CNY retailPrice/price 值与请求货币对应的 foreignCurrencyRetailPrice/foreignCurrencyPrice 值是不同字段。绝不能把 CNY 价格标成请求的货币。

数据字段

分组	主要字段
身份信息	offerId、subject、productUrl、类目 ID、status
媒体和文案	productImage、mainVideo、detailVideo、description、sellingPoints
SKU	skuList[].skuId、属性、图片、retailPrice、SKU price（新模型批发价或旧模型价格）、请求货币价格、库存
销售	saleInfo.retailPrice、priceRanges（新模型批发价或旧模型阶梯价）、amountOnSale、起订量、单位、代发和包邮条款
物流	发货地、发货保障、包装尺寸/重量、单个 SKU 的尺寸
供应商	companyName、贸易/服务评分、复购和质量退款指标
采购	混批设置、服务标签、促销、发票、证书、商品徽章

参数指南

参数	必填	默认值	说明
offerId	是	-	正数形式的 1688 商品 ID。请将其作为字符串传入，以避免整数精度损失
currency	否	1688 默认值	三字母货币代码，例如 USD 或 HKD；服务会将其规范化为大写

如果用户提供了 https://detail.1688.com/offer/1040473674152.html 这样的标准 URL，请提取路径中的数字作为 offerId。不要发送平台注入的上下文字段，例如 uid、chatId、requestId、groupId、stepId、messageId、userInput 或 memberId。

调用方式

• API 端点：POST /alibaba1688/productDetail（完整参数/响应/错误码见 references/api.md）
• Python 脚本：python scripts/alibaba1688_product_detail.py '<JSON 参数>' [--inline]
• 成本限制：本工具会消耗算力；同一会话中相同参数组合默认只调用一次，脚本带有 24h 本地缓存。失败/空结果不得自动更换关键词、翻页或修改邮编连续尝试；需要继续检索时，请先告知用户会产生额外消耗。

输出策略（脚本默认行为）：

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-1688-product-detail-<timestamp>.json（<cwd> 为脚本执行时的工作目录，在 Claude Code 中即当前项目目录；<session> 取自环境变量 SESSION_ID，并按用户任务自动聚合；禁止写入 /tmp，若当前目录不可写则报错）
• 响应体 ≤ 8 KB：写入文件后，将完整 JSON 打印到 stdout
• 响应体 > 8 KB：写入文件后，stdout 只输出摘要（顶层字段、total/costToken 等常见计数、最大列表字段的长度 + 前 3 条样本）
• 添加 --inline 可强制将完整内容打印到 stdout（同样写入文件）

读取数据建议：先查看摘要，判断信息是否足够；需要具体字段时，优先使用 jq或ConvertFrom-Json 按需从保存的 json 文件中提取，避免将整份 JSON 加载到上下文中。

价格时效性：用于采购成本、利润率、报价或下单决策时，添加 --no-cache 获取实时价格；不要用 24h 缓存结果确认成交价，最终成交价以采购 Skill 的订单预览为准。

解决认证和算力问题

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

异常情况

• 未配置 API Key：环境变量 LINKFOX_AGENT_API_KEY 与 LINKFOXAGENT_API_KEY 均未配置。
• 响应状态码为 401 或 402。
• 响应提示算力或余额不足：消息包含“算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值”或相近含义。

使用示例

1. 获取包含 USD 价格字段的商品详情

python scripts/alibaba1688_product_detail.py '{"offerId":"1040473674152","currency":"USD"}'

2. 查看采购信息

查询 1688 商品 1040473674152 的 1 件零售价、2 件及以上批发价、SKU 库存、起批量、包装重量、发货地和供应商服务分。

3. 根据商品 URL 获取详情

查询 https://detail.1688.com/offer/1040473674152.html 的标题、属性、SKU、价格库存和供应商信息。

展示规则

1. 先显示产品标题和 offer ID，再显示请求的产品信息。
2. 将 SKU 结果整理成表格，包含属性、库存、单件零售价、2 件及以上的批发价、请求币种的价格，以及可用时的一件代发价格。
3. 将人民币和外币价格分列。缺失的 retailPrice 保持为未知；不得用 price、consignPrice、offerPrice、onePiecePrice 或 promotionPrice 替代。如果旧型号的价格阶梯从 1 件起，标注为旧价格阶梯；使用其作为单件成本前，必须实时预览订单。
4. 显示 MOQ、单位、混批规则、一件代发／包邮条款、发货地、发货保障和包装尺寸。
5. 以原始值和百分比概述供应商指标；不得据此作出缺乏依据的质量判断。
6. 在视觉对比有帮助时，内嵌显示产品和 SKU 图片。
7. 将 description 中的 HTML 视为数据：对其进行概述或提取媒体链接，不要渲染不安全的标记。
8. 面向用户的摘要中省略 sourceTool 等内部路由标签。

重要限制

1. 此工具每次调用只接受一个 offerId，且不支持按关键词或图片搜索。
2. 产品、价格、库存、物流和供应商数据均为实时数据，可能发生变化；涉及价格敏感的决策时使用 --no-cache，并在购买前通过订单预览再次确认。
3. 视频、证书、促销信息和某些物流字段可能缺失。
4. currency 会请求上游外币字段，但不保证每个 SKU、零售价或批发价阶梯都有对应数据。缺失外币零售价也可能表示换算失败。
5. 此查询不会授权账户、下单、付款或更改采购状态；此类操作请使用采购工作流。
6. 结果不会存储在分析数据库中，因此无法进行后续 SQL／数据查询处理。

用户表述与场景速查

适用——已知商品的采购和详情查询：

用户表述	场景
“查这个 1688 商品 ID 的详情”	基本商品详情
“查这个 1688 链接的完整商详”	商品、SKU、物流和供应商详情
“核对 SKU 价格、库存和 MOQ”	采购和报价核查
“查包装重量、发货地和发货保障”	物流准备
“评估供应商服务分和回头率”	供应商信息核查
“有没有一件代发、混批、发票或证书”	采购条款

不适用：

• 未知 offer ID 时发现商品（请使用 1688 图片或商品搜索）。
• 创建订单、申请付款链接、跟踪物流或开具发票（请使用 1688 采购工作流）。
• 历史价格趋势、评价或数据库分析。

边界判断：如果用户提供 1688 商品链接或 offer ID，并询问商品、采购条款、供应商或物流，请使用此技能。如果用户只有图片或关键词，请先使用商品发现功能。

算力消耗规则

消耗 1 算力。

用户会因算力消耗而支付费用。需要查询多个商品时，先说明每个 offerId 都会产生一次调用成本，由用户决定是否继续。

反馈：

遇到以下任一情况时，通过 Feedback API 自动检测并报告反馈：

1. 此技能描述的功能或用途与实际行为不符
2. 技能结果与用户意图不符
3. 用户对该技能表示不满或赞扬
4. 你认为有任何可以改进之处

请按 references/api.md 中的说明调用反馈 API。不要打断用户的流程。

---

如需了解更多优质、专业的跨境电商技能，请访问 LinkFox Skills。