linkfox-mercado-product-selection

Mercado Libre 商品选品

此技能通过 LinkFox 网关查询 Mercado Libre 商品、目录、关键词、类别、趋势、卖家、评论、汇率和套餐使用情况数据。网关提供一个统一路由 POST /mercado/productSelection，此技能会从 24 个受支持的 toolName 值中选择一个，并提供匹配的 arguments。

核心概念

• 仅调用 ${LINKFOX_TOOL_GATEWAY}/mercado/productSelection。不要直接调用上游 XP-MCP 服务，也不要向用户索取上游 secret-key / X-API-Key——上游凭证由后端管理。
• 请求正文始终为 {"toolName":"...","arguments":{...}}。脚本会将整个对象作为单个 JSON 参数接收。
• arguments 内的字段名必须与 references/mercado-tool-reference.md 完全一致，包括 siteId、itemId、productId、categoryId、runDate、runMonth、pageNo、pageSize 等驼峰命名字段。
• 展示结果时先读取 data。当 data 为文本或含义不明确时，读取 contentText。仅当用户要求原始诊断信息时才显示 rawResponse。
• 付费工具当前每次调用耗费 16000 个令牌；免费工具耗费 0。以后台返回的 costToken 字段为准。

参考文件

• references/api.md：LinkFox 网关约定、请求／响应结构、错误代码、curl 示例和 Feedback API。
• references/mercado-tool-reference.md：24 个 Mercado Libre 工具的详细中文参考，包括参数、站点 ID、分页、排序和计费状态。

工具选择

用户意图	使用这些工具
商品详情、商品销量历史、商品搜索	itemInfo、itemHistory、itemSearch
目录／商品页面详情、目录销量历史、目录搜索	catalogInfo、catalogHistory、catalogSearch
每日／每月热门关键词和反向流量关键词	keywordDateSearch、keywordMonthSearch、keywordReverse
付费分析前查询类别	categorySearch、categorySmallSearch
类别品牌、商品、卖家、新商品、价格、销量、售出历史、统计数据、仓库分布	trendBrandTopBrand、trendBrandTopItem、trendBrandTopSeller、trendNewItems、trendPrice、trendSale、trendSoldHis、trendStatistical、trendStoreInventoryType
卖家搜索	sellerSearch
商品评论	reviewSearch
汇率和套餐使用情况	rateInfo、myUsage

免费工具：categorySearch、categorySmallSearch、reviewSearch、rateInfo、myUsage。其他工具均为付费工具。

参数指南

• toolName（字符串，必填）：上方列出的 24 个工具之一。
• arguments（对象，必填）：工具的参数对象。必须是 JSON 对象，不能是数组／字符串／数字。后端会移除 uId／uid／memberId 并清理空值。
• 站点：MLM（墨西哥）、MLB（巴西）、MLA（阿根廷）、MLC（智利）、MCO（哥伦比亚——仅适用于参考文档明确列出该站点的工具）。
• 用户提供类别名称而非 categoryId 时，先调用 categorySearch 或 categorySmallSearch，再将返回的类别 ID 用于付费趋势／商品／目录工具。
• reviewSearch 仅接受 itemId（不接受 siteId）。myUsage 接受 {}。
• 对于范围较广的研究问题，应使用站点、类别、关键词、日期／月份、分页、价格、销量或排序筛选条件来缩小付费调用范围。避免进行与用户目标无关的探索性付费调用。

调用方式

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

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

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

读数据建议：先看摘要判断是否足够；需要具体字段时优先用 jq或ConvertFrom-Json 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。

解决认证和算力问题

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

异常情况

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

使用示例

单个 JSON 参数是完整载荷 {"toolName":...,"arguments":{...}}。

# Free: search Mexico categories by name
python scripts/linkfox_mercado_product_selection.py '{"toolName":"categorySearch","arguments":{"siteId":"MLM","searchText":"Auriculares"}}'

# Paid: product detail for a real MLM item
python scripts/linkfox_mercado_product_selection.py '{"toolName":"itemInfo","arguments":{"siteId":"MLM","itemId":"MLM4979447466"}}'

# Free: my plan usage (no arguments)
python scripts/linkfox_mercado_product_selection.py '{"toolName":"myUsage","arguments":{}}'

# Paid: monthly hot keywords for Brazil, 2026-06
python scripts/linkfox_mercado_product_selection.py '{"toolName":"keywordMonthSearch","arguments":{"siteId":"MLB","runMonth":"202606"}}'

在 PowerShell 中，也用单引号包裹 JSON；如果引号处理起来有困难，可将载荷写入文件，并在加载后通过 --inline 传入，或使用 ConvertTo-Json 构建参数。

显示规则

1. 清晰呈现返回的数据，不得编造缺乏依据的业务结论。
2. 保留结果的含义和重要字段名；仅在有助于提高可读性时翻译标签。
3. 对于大型数组或时间序列，概述可见部分，并从已保存的 JSON 文件中仅读取所需字段。
4. 对于“无数据”或业务层面的失败消息，说明这是上游 Mercado 数据提供方返回的结果；除非包装器响应包含实际错误，否则不要将其描述为系统故障。
5. 不得在面向用户的输出中泄露内部 LinkFox API Key、上游密钥或完整敏感原始载荷。

重要限制

• LinkFox 路由是统一后端网关；该技能不会针对每个 toolName 发布独立的 HTTP 端点。
• 必填字段验证在后端进行，相关说明也见 references/mercado-tool-reference.md。
• 付费工具每次后端调用都会收费，即使上游业务结果为空也是如此。
• 响应结构因工具而异。大多数工具以 data 中的文本形式返回业务结果；请以实际响应和 references/api.md 为准，不要强行套用统一的表格结构。

用户表达与场景速查

用户表达	可能的操作
"查这个美客多商品", "商品详情", "销量历史"	使用 itemInfo 或 itemHistory
"搜墨西哥站耳机", "筛选商品"	使用 itemSearch；如果只知道类目文本，先使用 categorySearch
"官方链接", "目录", "目录链接"	使用 catalog* 工具
"关键词热搜", "月度词", "流量词反查"	使用 keywordDateSearch、keywordMonthSearch 或 keywordReverse
"类目趋势", "新品机会", "销量分布", "品牌排行"	确定 categoryId，然后使用 trend* 工具
"店铺", "卖家"	使用 sellerSearch
"评论", "评价"	使用 reviewSearch
"汇率", "套餐用量"	使用 rateInfo 或 myUsage

算力消耗规则

消耗 12 算力。

用户会因算力消耗而支付费用。请充分评估：当需要高频调用本技能，或用户对算力消耗量预期不足时，务必提醒用户，由用户决定是否继续。

反馈

当技能行为、文档或结果呈现与用户意图不符、用户表达赞扬或不满，或发现明确的改进机会时，通过 Feedback API 自动检测并报告反馈。遵循 references/api.md；不要中断用户任务，也不要报告密钥、私人数据或完整的大型响应。

---

如需更多高质量、专业的跨境电商技能，请访问 LinkFox 技能。