Linkfox 亚马逊店铺运营（Amazon Store Operations）

亚马逊店铺 SP-API 运营一站式 AI 工具集，整合 10 项子能力，覆盖授权与令牌、订单、Listing 刊登、定价、Catalog 目录、报告、Feeds 批量上传、买家反馈、文件上传与 A+ Content。各子能力完整参数、响应字段与错误码见 references/ 下对应文件，可执行脚本见 scripts/。

能力边界

✅ 能力范围

以下能力均经 tool_key amazon_sp_api（亚马逊 SP-API 网关 POST /spApi/developerProxy 转发上游 SP-API，授权类直连 POST /spApi/*）实现，整合 10 项子能力：

• 授权与令牌管理（linkfox-amazon-store-auth）：生成亚马逊店铺 OAuth 授权链接、查询已授权店铺列表、刷新令牌、查询指定店铺访问令牌；是所有下游 SP-API 操作的前置依赖（取 accessToken）。
• 订单管理（linkfox-amazon-store-orders）：订单列表检索、单笔订单详情、买家信息、收货地址、订单行项目、管制订单核验信息查询，以及发货状态更新、确认发货、管制订单核验状态更新（SP-API Orders）。
• Listing 刊登管理（linkfox-amazon-store-listings）：单条/列表检索刊登、PATCH 部分更新、PUT 创建/全量更新、DELETE 删除刊登，查询 ASIN 刊登限制（是否可售）、Product Type 列表搜索与 JSON Schema 定义查询（SP-API Listings & Definitions）。
• 商品定价与比价（linkfox-amazon-store-pricing）：单条/批量获取 ASIN/SKU 定价、竞争性报价、Listing/Item 报价、购物车预期价（FOEP）与竞争摘要（SP-API Product Pricing，含 batch 接口）。
• Catalog 目录检索（linkfox-amazon-store-catalog）：按 ASIN 获取商品目录详情、按关键词/标识符检索商品目录、查询商品所属类目节点，返回摘要/图片/销售排名等（SP-API Catalog Items）。
• 报告自动化（linkfox-amazon-store-report）：95+ 种卖家后台报告（库存/订单/销售流量/财务结算/FBA/Brand Analytics 等）的端到端获取——请求→轮询→下载→解压，并生成限时本机 HTTP 下载链接（SP-API Reports）。
• Feeds 批量数据上传（linkfox-amazon-store-feeds）：库存或 Listing 批量文件的 Feed 文档创建、文件上传、Feed 任务创建、状态轮询、列表查询、取消与结果文档下载（SP-API Feeds）。
• 买家反馈洞察（linkfox-amazon-store-customer-feedback）：按 ASIN 或类目节点分析评论主题、评价趋势、退货原因与星级影响（MENTIONS / STAR_RATING_IMPACT）（SP-API Customer Feedback）。
• 文件预签名上传（linkfox-amazon-store-uploads）：创建上传目的地生成预签名 URL，再向该 URL 上传文件，供 A+ Content、Messaging 等下游 API 使用（SP-API Uploads）。
• A+ Content 管理（linkfox-amazon-store-aplus-content）：A+ 文档检索、创建、获取、更新、ASIN 关联校验/全量替换、发布记录查询、审核提交与暂停展示（SP-API A+ Content Management）。
• 覆盖美国、英国、德国、日本、法国、意大利、西班牙等站点（marketplaceIds/marketplaceId 指定，region 取 NA/EU/FE 且须与授权区域一致）。

❌ 边界与限制

• API Key 必需：所有工具均需环境变量 LINKFOX_AGENT_API_KEY（或 LINKFOXAGENT_API_KEY）；各子能力独立计费、独立限频。
• 授权前置：除 linkfox-amazon-store-auth 外，其余 9 项子能力均依赖店铺已授权——须先用 linkfox-amazon-store-auth（store_tokens.py / POST /spApi/storeTokens）取得 accessToken，并通过 check_auth_dependency.py 本地探测依赖是否就绪（未就绪以 exit 42 + DEPENDENCY_MISSING: 信号提示安装 linkfox-amazon-store-auth）。
• 计费约束：同一会话同一参数组合默认只调用一次（脚本带本地缓存）；失败或空结果不得自动改参数、翻页或连续试探；需继续检索时先向用户说明会产生额外消耗（各工具计费规则见 skills-version.json 对应条目与 references 内 api.md 的 costToken 字段）。
• 不在范围内：选品/关键词/竞品/评论挖掘等选品调研（用 linkfox-amazon-product-selection 系列）；广告投放与管理（用 Amazon Ads 系列）；前台实时搜索/商品详情/前台评论（用 amazon_search / amazon_product_detail / amazon_reviews 系列）；物流与供应链规划、1688 找货源、其他平台运营、与平台或卖家的直接沟通、实时库存与订单的自动决策。
• 数据时效：SP-API 返回为亚马逊后台当前状态；报告类为按 dataStartTime/dataEndTime 拉取的历史快照；accessToken 约 1 小时过期，过期需 refresh_token.py 刷新或重新 store_tokens.py 获取。

工具选择指南

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

工具选择思路

• 重要：多个子能力满足需求时，要依据需求深入分析子能力的功能、用途、出入参，从中调研出最合适的子能力，并推荐用户，让用户自己决定。
• 满足程度同等的前提下，向用户推荐"默认推荐子能力"。
• 单条 vs 批量：单条写操作优先 linkfox-amazon-store-listings；批量文件操作优先 linkfox-amazon-store-feeds。
• 店铺目录 vs 前台搜索：查自己店铺后台可售商品/类目用 linkfox-amazon-store-catalog；查前台实时 SERP/竞品用选品 skill 的 amazon_search 系列。

业务需求路由速查

按【工具选择指南】定到子能力后，下表查端点、脚本与 references 文件取参执行。所有 SP-API 业务调用统一经 POST ${LINKFOX_TOOL_GATEWAY}/spApi/developerProxy，请求体含 region + path（SP-API 相对路径，无前导 /）+ method + amzAccessToken（来自 linkfox-amazon-store-auth 的 store_tokens.py）+ 可选 queryString/body/contentType；授权类直连 POST /spApi/*。

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

amazon_sp_api

各子能力脚本目录下另有共享模块（_spapi_<域>_common.py / _lf_output.py）与依赖检查脚本 check_auth_dependency.py，由业务脚本内部调用，不作为独立 CLI 使用。

调用方式

• 网关：${LINKFOX_TOOL_GATEWAY}/<端点>（默认 https://tool-gateway.linkfox.com，可用 LINKFOX_TOOL_GATEWAY 覆盖，兼容旧名 STORE_API_BASE_URL/SPAPI_BASE_URL），请求方式 POST、Content-Type application/json，认证 Header Authorization: <api_key>（api_key 从环境变量 LINKFOX_AGENT_API_KEY 或 LINKFOXAGENT_API_KEY 读取；未配置按下方【解决认证和积分问题】处理）。各端点路径见上方【业务需求路由速查】与对应 references 文件。
• SP-API 请求体：业务接口统一 POST /spApi/developerProxy，JSON 体含 region（NA/EU/FE）、path（SP-API 相对路径，无前导 /）、method（GET/POST/PATCH/PUT/DELETE）、amzAccessToken（访问令牌）、可选 queryString/body/contentType；授权类直连 POST /spApi/authorizeUrl 等专用端点。
• 授权前置：首次或令牌过期时，先跑 linkfox-amazon-store-auth 的 store_tokens.py '{"region":"NA","sellerId":"A1..."}' 取 amzAccessToken，再传给下游业务脚本；业务脚本启动时会本地探测 check_auth_dependency.py，依赖缺失时以 exit 42 + DEPENDENCY_MISSING: 提示先安装 linkfox-amazon-store-auth。
• Python 脚本：每项子能力对应 scripts/<脚本名>.py '<JSON 参数>' [--inline]（脚本名与端点见路由速查表）。脚本内部完成网关调用、鉴权与落盘。
• 输出策略（脚本默认行为）：始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/<skill>-<timestamp>.json（<cwd> 为脚本执行时工作目录；<session> 取自环境变量 SESSION_ID；禁止写入 /tmp，当前目录不可写则报错）；响应体 ≤ 8 KB 落盘后完整打印到 stdout，> 8 KB 仅打印摘要（顶层字段、常见计数、最大列表长度 + 前 3 条样本）；加 --inline 强制全量打印（同样落盘）。
• 读数据建议：先看摘要判断是否足够；需要具体字段时优先用 jq 或 PowerShell ConvertFrom-Json 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。
• 完整参数：每个子能力的请求参数、响应字段、错误码、curl 示例见 references/<源skill>.md（文件内含该子能力 SKILL.md 正文与 api.md 全文）。

使用示例

以下按运营模块给出代表性子能力的出入参示例；其余子能力参数见对应 references 文件。region 取 NA/EU/FE（须与授权区域一致），marketplaceIds/marketplaceId 为站点 ID（美国 ATVPDKIKX0DER），sellerId 为卖家标识，amzAccessToken 由 linkfox-amazon-store-auth 的 store_tokens.py 取得。

授权层

1. 生成授权链接 / 取访问令牌（amazon_sp_api → authorize_url.py / store_tokens.py）

{"region": "NA", "sellerName": "My Store"}

出参：authorizeUrl（Amazon 授权链接）；store_tokens.py 出参 accessToken（约 1 小时过期）、refreshToken、tokenType、expiresIn、authRecordId。sellerName 必填，用于在已授权列表中识别账号。

订单层

2. 订单列表检索（amazon_sp_api → search_orders.py）

{"sellerId": "A1EC6SZ7XAMURH", "region": "NA", "marketplaceIds": ["ATVPDKIKX0DER"], "lastUpdatedAfter": "2026-05-01T00:00:00Z"}

出参：searchOrders（订单列表，含 AmazonOrderId/PurchaseDate/OrderStatus/OrderTotal/FulfillmentChannel 等）、paginationToken、developerProxy 的 errcode/httpStatus/body。lastUpdatedAfter/createdAfter 二选一，marketplaceIds ≤50。

Listing 刊登层

3. 创建/全量更新刊登（amazon_sp_api → put_listings_item.py）

{"sellerId": "A1BCDEFGHIJK2", "region": "NA", "sku": "My-Seller-SKU-001", "marketplaceIds": ["ATVPDKIKX0DER"], "productType": "LUGGAGE", "requirements": "LISTING", "attributes": {"item_name": [{"value": "Example Title", "marketplace_id": "ATVPDKIKX0DER"}]}}

出参：putResult（Amazon 返回的提交结果，含 sku/status/submissionId/issues）、httpStatus、errcode。marketplaceIds 官方约束 ≤1，requirements 必填（LISTING/LISTING_PRODUCT_ONLY/LISTING_OFFER_ONLY）。

定价层

4. 单条定价/比价（amazon_sp_api → get_pricing.py）

{"sellerId": "A1...", "region": "NA", "asin": "B08N5WRWNW", "marketplaceId": "ATVPDKIKX0DER", "itemType": "Asin", "asins": ["B08N5WRWNW"], "itemCondition": "New"}

出参：pricing（含 Identifier/Summary/Product，价格、竞品数、Buy Box 价等）、errcode/httpStatus/body。批量 ≤20 用 post_item_offers_batch.py；购物车预期价用 post_featured_offer_expected_price_batch.py（≤40）。

Catalog 目录层

5. 按 ASIN 查商品目录（amazon_sp_api → get_catalog_item.py）

{"sellerId": "A1...", "region": "NA", "asin": "B08N5WRWNW", "marketplaceIds": ["ATVPDKIKX0DER"], "includedData": ["summaries", "images"]}

出参：catalogItem（含 asin/summaries/images/attributes/salesRanks 等）、errcode/httpStatus/body。includedData 可选 summaries/images/attributes/salesRanks 等。

报告层

6. 端到端获取报告（amazon_sp_api → get_report.py ⭐）

{"sellerId": "A1EC6SZ7XAMURH", "region": "NA", "reportType": "GET_MERCHANT_LISTINGS_ALL_DATA", "marketplaceIds": ["ATVPDKIKX0DER"]}

出参：reportId、processingStatus（IN_QUEUE/IN_PROGRESS/DONE/FATAL/CANCELLED）、reportDocumentId、downloadPath（解压后本地绝对路径）、extractedFileHttpUrl（限时本机 HTTP 直链，默认 300s）。支持 95+ 报告类型，详见 references/report-types.md 与 references/report-requests/。

Feeds 批量上传层

7. 创建 Feed 任务（amazon_sp_api → create_feed.py，需先 create_feed_document.py+upload_feed_document.py 上传文件）

{"sellerId": "A1EC6SZ7XAMURH", "region": "NA", "feedType": "POST_FLAT_FILE_INVLOADER_DATA", "marketplaceIds": ["ATVPDKIKX0DER"], "inputFeedDocumentId": "amzn1.tdoc.1.1.xxx"}

出参：feedId、processingStatus（IN_QUEUE/IN_PROGRESS/DONE/FATAL/CANCELLED）、resultFeedDocumentId、errcode/httpStatus。流程：create_feed_document 取 url → upload_feed_document PUT 上传 → create_feed 建任务 → get_feed 轮询 → get_feed_document 取结果。

买家反馈层

8. ASIN 评论主题（amazon_sp_api → get_item_review_topics.py）

{"sellerId": "A1...", "region": "NA", "asin": "B0...", "marketplaceId": "ATVPDKIKX0DER", "sortBy": "MENTIONS"}

出参：itemReviewTopics（评论主题及频次/星级影响）、errcode/httpStatus/body。sortBy 必填 MENTIONS（提及量）或 STAR_RATING_IMPACT（星级影响）；要趋势用 get_item_review_trends.py，类目级用 get_browse_node_review_topics.py（需先 get_item_browse_node.py 反查 browseNodeId）。

文件上传层

9. 创建上传目的地（amazon_sp_api → create_upload_destination_for_resource.py → upload_to_destination.py）

{"sellerId": "A1...", "region": "NA", "resource": "aplus/2020-11-01/contentDocuments", "marketplaceId": "ATVPDKIKX0DER", "filePath": "/path/to/banner.jpg", "contentType": "image/jpeg"}

出参：uploadDestination（含 uploadDestinationId/url/headers）、errcode/httpStatus。contentMD5 可由 filePath/content/contentBase64 自动计算；步骤 2 upload_to_destination.py 向返回的预签名 url PUT 文件（带 headers）。

A+ Content 层

10. 获取 A+ 文档详情（amazon_sp_api → get_content_document.py）

{"sellerId": "A1...", "region": "NA", "marketplaceId": "ATVPDKIKX0DER", "contentReferenceKey": "YOUR_KEY", "includedDataSet": ["CONTENTS", "METADATA"]}

出参：contentDocument（文档内容与元数据）、contentReferenceKey、warnings、errcode/httpStatus/body。includedDataSet 必填 ≥1（CONTENTS/METADATA）；创建/更新用 create_content_document.py/update_content_document.py，提交审核用 post_content_document_approval_submission.py。

展示规则

1. 客观呈现数据：以清晰表格展示查询/操作结果，不做主观商业建议（除非用户主动要求）；展示价格/金额时务必提示币种与站点（响应字段标明本地币种与 marketplace）。
2. 来源标注：展示数据时说明来自哪个 SP-API 模块（Orders/Listings/Pricing/Catalog/Reports/Feeds/Customer Feedback/Uploads/A+ Content/Auth）。
3. 不可用数据：值为 0/-1/null 的字段表示数据不可用，标注"N/A"或省略，不作实际值展示。
4. 写操作确认：Listing/Feeds/A+/订单发货等写操作（PATCH/PUT/POST/DELETE）执行前向用户确认关键参数（sellerId、sku、ASIN、marketplaceIds、reportType、feedType 等），避免误改误删；写操作多为异步，展示 submissionId/feedId/reportId/processingStatus 并提示需轮询确认最终结果。
5. 错误处理与协同：查询失败时根据响应 errcode/errmsg/httpStatus 说明原因并建议修正（ASIN/SKU 格式、region 与授权区不一致、path 白名单未放行 1005、参数越界、令牌过期需刷新等）；连续使用多模块时将各结果汇总为连贯分析，标注数据来源与时间窗。

解决认证和积分问题

异常情况：未配置 LINKFOX_AGENT_API_KEY/LINKFOXAGENT_API_KEY；响应 401 或 402；消息含"积分余额不足/quota exceeded/insufficient balance/套餐到期/需充值"等；业务脚本 exit 42 且 stderr 含 DEPENDENCY_MISSING:（提示未安装 linkfox-amazon-store-auth）。

措施：优先用 skill 内 onboarding.md 引导；找不到则加载 /linkfox-onboarding skill（未安装先下载 https://agent-files.linkfox.com/skills/linkfox-onboarding/release.zip 解压安装）。DEPENDENCY_MISSING: 时先安装并完成 linkfox-amazon-store-auth 店铺授权，再用 store_tokens.py 取得 amzAccessToken 后重试下游操作。

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