| name | linkfox-amazon-store-operations |
| description | 亚马逊店铺 SP-API 运营一站式 AI 工具集，整合授权/订单/Listing/定价/Catalog/报告/Feeds/买家反馈/文件上传/A+ Content/External Fulfillment/FBA 等 12 项子能力，覆盖店铺日常运营全链路。 |
Linkfox 亚马逊店铺运营（Amazon Store Operations）
亚马逊店铺 SP-API 运营一站式 AI 工具集，整合 12 项子能力，覆盖授权与令牌、订单、Listing 刊登、定价、Catalog 目录、报告、Feeds 批量上传、买家反馈、文件上传、A+ Content、External Fulfillment 与 FBA。各子能力完整参数、响应字段与错误码见 references/ 下对应文件，可执行脚本见 scripts/。
能力边界
✅ 能力范围
以下能力均经 tool_key amazon_sp_api（亚马逊 SP-API 网关 POST /spApi/developerProxy 转发上游 SP-API，授权类直连 POST /spApi/*）实现，整合 12 项子能力：
- 授权与令牌管理（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）。
- External Fulfillment（linkfox-amazon-store-external-fulfillment）：location 级库存 batchInventory、履约单 get/process/packages/面单发票、EF 退货 list/get（SP-API External Fulfillment Inventory / Shipping / Returns v2024-09-11）。
- FBA（linkfox-amazon-store-fba）：入仓资格 getItemEligibilityPreview、FBA Inventory、Fulfillment Inbound（v2024-03-20 + v0）、Fulfillment Outbound/MCF 2020-07-01。
- 覆盖美国、英国、德国、日本、法国、意大利、西班牙等站点（
marketplaceIds/marketplaceId 指定，region 取 NA/EU/FE 且须与授权区域一致）。
❌ 边界与限制
- API Key 必需：所有工具均需环境变量
LINKFOX_AGENT_API_KEY（或 LINKFOXAGENT_API_KEY）；各子能力独立计费、独立限频。
- 授权前置：除
linkfox-amazon-store-auth 外，其余 11 项子能力均依赖店铺已授权——须先用 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 取参执行。
| 需求 / 用户说 | 默认推荐（子能力） | 何时换用其他 |
|---|
| 授权/绑定亚马逊店铺、查已授权店铺、令牌过期 | linkfox-amazon-store-auth | — |
| 查订单列表 / 单笔订单详情 / 买家信息 / 收货地址 / 订单行 | linkfox-amazon-store-orders | 要批量下载历史订单报告用 linkfox-amazon-store-report（reportType 订单类） |
| 确认发货 / 标记已发货 / 更新发货状态 | linkfox-amazon-store-orders（confirm_shipment / update_shipment_status） | — |
| 单条 Listing 改标题/价格/属性、新建/全量更新/删除刊登 | linkfox-amazon-store-listings（PATCH/PUT/DELETE） | 要批量上传/修改多条 Listing 文件用 linkfox-amazon-store-feeds（feedType=Listing 类） |
| 查 ASIN 能不能卖 / 刊登限制 | linkfox-amazon-store-listings（get_listings_restrictions） | — |
| Product Type 有哪些 / 某类型的字段 Schema | linkfox-amazon-store-listings（search/get_definitions_product_type） | — |
| 查商品定价 / 这个 ASIN 多少钱 / 比价 | linkfox-amazon-store-pricing（get_pricing / get_competitive_pricing） | 要批量（≤20 ASIN/SKU）报价用 post_item_offers_batch / post_listing_offers_batch；要购物车预期价用 post_featured_offer_expected_price_batch；要竞争摘要用 post_competitive_summary_batch |
| 批量查报价（多个 ASIN/SKU） | linkfox-amazon-store-pricing（post_item_offers_batch / post_listing_offers_batch） | 仅 1 个用单条 get_item_offers / get_listing_offers |
| 查商品目录 / 按 ASIN 查商品信息 / 关键词搜目录 / 类目节点 | linkfox-amazon-store-catalog | 要前台实时搜索结果（非店铺目录）用 amazon_search 系列（选品 skill） |
| 下载卖家后台报告（库存/订单/销售流量/财务/FBA/Brand Analytics） | linkfox-amazon-store-report（get_report ⭐端到端） | 要逐条查订单用 linkfox-amazon-store-orders |
| 批量上传库存 / 批量改 Listing（Feed 文件） | linkfox-amazon-store-feeds（create_feed_document→upload→create_feed→get_feed） | 单条 Listing 改用 linkfox-amazon-store-listings |
| 查 Feed 处理状态 / 取消 Feed / 下载 Feed 结果 | linkfox-amazon-store-feeds（get_feed / cancel_feed / get_feed_document） |
工具选择思路
- 重要：多个子能力满足需求时，要依据需求深入分析子能力的功能、用途、出入参，从中调研出最合适的子能力，并推荐用户，让用户自己决定。
- 满足程度同等的前提下，向用户推荐"默认推荐子能力"。
- 单条 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
| 子能力 | references 文件 | 端点 | 脚本 |
|---|
| linkfox-amazon-store-auth | references/linkfox-amazon-store-auth.md | POST /spApi/authorizeUrl、/spApi/authorizedStores、/spApi/refreshToken、/spApi/storeTokens | authorize_url.py、authorized_stores.py、refresh_token.py、store_tokens.py |
| linkfox-amazon-store-orders | references/linkfox-amazon-store-orders.md | POST /spApi/developerProxy（orders/2026-01-01/、orders/v0/） | search_orders.py、get_order.py、get_order_address.py、get_order_buyer_info.py、get_order_items.py、get_order_items_buyer_info.py、get_order_regulated_info.py、update_shipment_status.py、update_verification_status.py、confirm_shipment.py |
| linkfox-amazon-store-listings | references/linkfox-amazon-store-listings.md | POST /spApi/developerProxy（listings/2021-08-01/、definitions/2020-09-01/） | get_listings_item.py、search_listings_items.py、patch_listings_item.py、put_listings_item.py、delete_listings_item.py、get_listings_restrictions.py、search_definitions_product_types.py、get_definitions_product_type.py |
| linkfox-amazon-store-pricing | references/linkfox-amazon-store-pricing.md | POST /spApi/developerProxy（products/pricing/v0/、batches/products/pricing/） | get_pricing.py、get_competitive_pricing.py、get_listing_offers.py、get_item_offers.py、post_item_offers_batch.py、post_listing_offers_batch.py、post_featured_offer_expected_price_batch.py、post_competitive_summary_batch.py |
| linkfox-amazon-store-catalog | references/linkfox-amazon-store-catalog.md | POST /spApi/developerProxy（catalog/2022-04-01/、catalog/v0/） | get_catalog_item.py、list_catalog_categories.py、search_catalog_items.py |
| linkfox-amazon-store-report | references/linkfox-amazon-store-report.md | POST /spApi/developerProxy（reports/2021-06-30/reports、/reports/{reportId}、/documents/{reportDocumentId}） | get_report.py（⭐端到端）、merge_report_type_values_from_cache.py（辅助） |
| linkfox-amazon-store-feeds | references/linkfox-amazon-store-feeds.md | POST /spApi/developerProxy（feeds/2021-06-30/documents、/feeds、/feeds/{feedId}）+ PUT 预签名 URL | create_feed_document.py、upload_feed_document.py、create_feed.py、get_feed.py、get_feeds.py、get_feed_document.py、cancel_feed.py |
| linkfox-amazon-store-customer-feedback | references/linkfox-amazon-store-customer-feedback.md | POST /spApi/developerProxy（customerFeedback/2024-06-01/items/{asin}/、/browseNodes/{browseNodeId}/） |
各子能力脚本目录下另有共享模块（_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。
展示规则
- 客观呈现数据：以清晰表格展示查询/操作结果，不做主观商业建议（除非用户主动要求）；展示价格/金额时务必提示币种与站点（响应字段标明本地币种与 marketplace）。
- 来源标注：展示数据时说明来自哪个 SP-API 模块（Orders/Listings/Pricing/Catalog/Reports/Feeds/Customer Feedback/Uploads/A+ Content/Auth）。
- 不可用数据：值为
0/-1/null 的字段表示数据不可用，标注"N/A"或省略，不作实际值展示。
- 写操作确认：Listing/Feeds/A+/订单发货等写操作（PATCH/PUT/POST/DELETE）执行前向用户确认关键参数（sellerId、sku、ASIN、marketplaceIds、reportType、feedType 等），避免误改误删；写操作多为异步，展示
submissionId/feedId/reportId/processingStatus 并提示需轮询确认最终结果。
- 错误处理与协同：查询失败时根据响应
errcode/errmsg/httpStatus 说明原因并建议修正（ASIN/SKU 格式、region 与授权区不一致、path 白名单未放行 1005、参数越界、令牌过期需刷新等）；连续使用多模块时将各结果汇总为连贯分析，标注数据来源与时间窗。
解决认证和积分问题
发生以下异常情况时，采用 references/onboarding.md 引导解决问题：
注意：你是workbuddy，并且渠道是workbuddy，使用 onboarding 引导登录注册时 channel 必须为 workbuddy。这非常重要！
异常情况
- 未配置API Key：环境变量未配置
LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
- 响应401或402状态码
- 响应提示积分或余额不足：消息含"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。
