{"id":"d9ed5811-de83-4d76-a67a-10ead327c16e","entityType":"agent","slug":"clawhub-linkfox-ai-linkfox-amazon-store-listings","name":"亚马逊-店铺Listing管理","canonicalUrl":"https://www.xpersona.co/agent/clawhub-linkfox-ai-linkfox-amazon-store-listings","canonicalPath":"/agent/clawhub-linkfox-ai-linkfox-amazon-store-listings","generatedAt":"2026-10-10T10:44:40.821Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-10T07:41:13.853Z","emptyReason":null},"description":"亚马逊卖家 Listing 刊登与商品类型定义管理。用于按 SKU 查询或搜索 Listing，创建、全量更新、局部修改和删除刊登，检查 ASIN 刊登限制，并查询 product type 及其 JSON Schema 属性要求。用户提到亚马逊 Listing、刊登商品、修改商品信息、删除 Listing、卖家 SKU、ASIN 能否销售、刊登限制、product type、商品类型定义、JSON Schema、Listings Items、Listings Restrictions 时触发。即使未明确提及 API，只要希望管理卖家自己的商品刊登或确认上架所需字段与资格，也应触发此技能；查询亚马逊全站商品目录使用 linkfox-amazon-store-catalog，批量提交使用 linkfox-amazon-store-feeds。 Skill: 亚马逊-店铺Listing管理 Owner: linkfox-ai Summary: 亚马逊卖家 Listing 刊登与商品类型定义管理。用于按 SKU 查询或搜索 Listing，创建、全量更新、局部修改和删除刊登，检查 ASIN 刊登限制，并查询 product type 及其 JSON Schema 属性要求。用户提到亚马逊 Listing、刊登商品、修改商品信息、删除 Listing、卖家 SKU、ASIN 能否销售、刊登限制、product type、商品类型定义、JSON Schema、Listings Items、Listings Restrictions 时触发。即使未明确提及 API，只要希望管理卖家自己的商品刊登或确认上架所需字段与资格，也应触发此技能；查询亚马逊全站商品目录使用 linkfox-amazon-store-catalog，批量提交使用 linkfox-amazon-store-f","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.6K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s171g8b6m2khwdy9ye8bxj0wx183vd4z:linkfox-amazon-store-listings","sourceUrl":"https://clawhub.ai/linkfox-ai/linkfox-amazon-store-listings","homepage":"https://clawhub.ai/linkfox-ai/skills/linkfox-amazon-store-listings","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/linkfox-ai/linkfox-amazon-store-listings","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/linkfox-ai/skills/linkfox-amazon-store-listings","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":64,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"亚马逊卖家 Listing 刊登与商品类型定义管理。用于按 SKU 查询或搜索 Listing，创建、全量更新、局部修改和删除刊登，检查 ASIN 刊登限制，并查询 product type 及其 JSON Schema 属性要求。用户提到亚马逊 Listing、刊登商品、修改商品信息、删除 Listing、卖家 SK"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T07:41:13.853Z","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-10T07:41:13.853Z","emptyReason":null},"stars":null,"forks":null,"downloads":1584,"packageName":null,"latestVersion":"1.0.8","tractionLabel":"1.6K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T07:41:13.853Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T07:41:13.853Z","lastCrawledAt":"2026-10-10T07:41:13.853Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T07:41:13.853Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.8","createdAt":"2026-09-14T04:57:55.287Z","changelog":"Update from 1.0.7 to 1.0.8","fileCount":16,"zipByteSize":59856},{"version":"1.0.7","createdAt":"2026-08-14T14:45:42.653Z","changelog":"Update from 1.0.6 to 1.0.7","fileCount":16,"zipByteSize":58140},{"version":"1.0.6","createdAt":"2026-08-07T10:42:18.981Z","changelog":"Update from 1.0.5 to 1.0.6","fileCount":16,"zipByteSize":58088},{"version":"1.0.5","createdAt":"2026-07-13T12:05:04.393Z","changelog":"Update from 1.0.4 to 1.0.5","fileCount":14,"zipByteSize":49631},{"version":"1.0.4","createdAt":"2026-07-06T11:13:34.013Z","changelog":"Update from 1.0.3 to 1.0.4","fileCount":14,"zipByteSize":48266},{"version":"1.0.3","createdAt":"2026-07-03T08:11:58.215Z","changelog":"Update from 1.0.2 to 1.0.3","fileCount":13,"zipByteSize":46846},{"version":"1.0.2","createdAt":"2026-07-03T04:37:07.493Z","changelog":"Update from 1.0.1 to 1.0.2","fileCount":13,"zipByteSize":46754},{"version":"1.0.1","createdAt":"2026-06-29T09:45:08.327Z","changelog":"Update from 0.0.1 to 1.0.1","fileCount":14,"zipByteSize":51467}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s171g8b6m2khwdy9ye8bxj0wx183vd4z:linkfox-amazon-store-listings","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-amazon-store-listings/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-store-listings/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-store-listings/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-store-listings/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-store-listings/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-store-listings/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-10T10:44:40.817Z"}},"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-amazon-store-listings/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-store-listings/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-store-listings/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-amazon-store-listings/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-10T07:41:13.853Z","emptyReason":null},"readme":"Skill: 亚马逊-店铺Listing管理\n\nOwner: linkfox-ai\n\nSummary: 亚马逊卖家 Listing 刊登与商品类型定义管理。用于按 SKU 查询或搜索 Listing，创建、全量更新、局部修改和删除刊登，检查 ASIN 刊登限制，并查询 product type 及其 JSON Schema 属性要求。用户提到亚马逊 Listing、刊登商品、修改商品信息、删除 Listing、卖家 SKU、ASIN 能否销售、刊登限制、product type、商品类型定义、JSON Schema、Listings Items、Listings Restrictions 时触发。即使未明确提及 API，只要希望管理卖家自己的商品刊登或确认上架所需字段与资格，也应触发此技能；查询亚马逊全站商品目录使用 linkfox-amazon-store-catalog，批量提交使用 linkfox-amazon-store-feeds。\n\nTags: latest:1.0.8\n\nVersion history:\n\nv1.0.8 | 2026-09-14T04:57:55.287Z | user\n\nUpdate from 1.0.7 to 1.0.8\n\nv1.0.7 | 2026-08-14T14:45:42.653Z | user\n\nUpdate from 1.0.6 to 1.0.7\n\nv1.0.6 | 2026-08-07T10:42:18.981Z | user\n\nUpdate from 1.0.5 to 1.0.6\n\nv1.0.5 | 2026-07-13T12:05:04.393Z | user\n\nUpdate from 1.0.4 to 1.0.5\n\nv1.0.4 | 2026-07-06T11:13:34.013Z | user\n\nUpdate from 1.0.3 to 1.0.4\n\nv1.0.3 | 2026-07-03T08:11:58.215Z | user\n\nUpdate from 1.0.2 to 1.0.3\n\nv1.0.2 | 2026-07-03T04:37:07.493Z | user\n\nUpdate from 1.0.1 to 1.0.2\n\nv1.0.1 | 2026-06-29T09:45:08.327Z | user\n\nUpdate from 0.0.1 to 1.0.1\n\nv0.0.1 | 2026-05-20T08:04:40.356Z | user\n\nInitial release\n\nArchive index:\n\nArchive v1.0.8: 16 files, 59856 bytes\n\nFiles: references/api.md (31624b), references/onboarding.md (1999b), scripts/_spapi_listings_common.py (6542b), scripts/check_auth_dependency.py (10349b), scripts/delete_listings_item.py (7476b), scripts/get_definitions_product_type.py (8501b), scripts/get_listings_item.py (8456b), scripts/get_listings_restrictions.py (7520b), scripts/onboarding.py (24027b), scripts/patch_listings_item.py (9299b), scripts/put_listings_item.py (9206b), scripts/search_definitions_product_types.py (8450b), scripts/search_listings_items.py (12604b), skill-card.md (3497b), SKILL.md (15444b), _meta.json (148b)\n\nFile v1.0.8:SKILL.md\n\n---\nname: linkfox-amazon-store-listings\ndescription: 亚马逊卖家 Listing 刊登与商品类型定义管理。用于按 SKU 查询或搜索 Listing，创建、全量更新、局部修改和删除刊登，检查 ASIN 刊登限制，并查询 product type 及其 JSON Schema 属性要求。用户提到亚马逊 Listing、刊登商品、修改商品信息、删除 Listing、卖家 SKU、ASIN 能否销售、刊登限制、product type、商品类型定义、JSON Schema、Listings Items、Listings Restrictions 时触发。即使未明确提及 API，只要希望管理卖家自己的商品刊登或确认上架所需字段与资格，也应触发此技能；查询亚马逊全站商品目录使用 linkfox-amazon-store-catalog，批量提交使用 linkfox-amazon-store-feeds。\n---\n\n# Amazon 店铺 Listings 与相关 API\n\n本 skill 与 **`linkfox-amazon-store-auth`**、**`linkfox-amazon-store-report`** 同属 **Amazon Store** 系列：依赖 **`linkfox-amazon-store-auth`** 选店（`sellerId`+`region`）；直接 **`POST /spApi/developerProxy`** 传入 `sellerId`+`region`，由服务端解析 token（勿传 `amzAccessToken`，除非兼容旧调用）。转发上游 **GET**、**PATCH**、**PUT** 或 **DELETE**。\n\n| 操作 | 官方参考 |\n|------|----------|\n| 单条刊登 | [getListingsItem](https://developer-docs.amazon.com/sp-api/reference/getlistingsitem) |\n| 检索列表 | [searchListingsItems](https://developer-docs.amazon.com/sp-api/reference/searchlistingsitems) |\n| 部分更新刊登 | [patchListingsItem](https://developer-docs.amazon.com/sp-api/reference/patchlistingsitem) |\n| 创建 / 全量更新刊登 | [putListingsItem](https://developer-docs.amazon.com/sp-api/reference/putlistingsitem) |\n| 删除刊登 | [deleteListingsItem](https://developer-docs.amazon.com/sp-api/reference/deletelistingsitem) |\n| 刊登限制（ASIN） | [getListingsRestrictions](https://developer-docs.amazon.com/sp-api/reference/getlistingsrestrictions) |\n| 搜索 product type | [searchDefinitionsProductTypes](https://developer-docs.amazon.com/sp-api/reference/searchdefinitionsproducttypes) |\n| 获取 product type 定义 | [getDefinitionsProductType](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype) |\n\n---\n\n## 调用方式\n\n- **API 端点**：`POST /spApi/developerProxy`（不同操作通过请求体区分；完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/<脚本名>.py '<JSON 参数>' [--inline]`（可用脚本见上文脚本一览）\n- **成本约束**：本工具会消耗算力；失败/空结果不得自动换关键词、翻页或连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/<skill-name>-<timestamp>.json`（`<cwd>` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`<session>` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq`或`ConvertFrom-Json`或`ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 解决认证和算力问题\n发生以下异常情况时，采用 references/onboarding.md 引导解决问题：\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示算力或余额不足**：消息含\"算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n---\n\n## Prerequisites（必须先读）\n\n本 skill **依赖** **`linkfox-amazon-store-auth`**。流程与 `linkfox-amazon-store-report` 相同：\n\n1. 运行 `python scripts/check_auth_dependency.py`；若 exit code **42** 且 stderr 含 `DEPENDENCY_MISSING:`，请先安装 **`linkfox-amazon-store-auth`**。\n2. **不要**在本 skill 内绕过依赖实现授权或令牌逻辑。\n\n---\n\n## Current Capabilities\n\n| 能力 | Path 要点 | 脚本 |\n|------|-----------|------|\n| **获取单条 Listing** | `listings/2021-08-01/items/{sellerId}/{sku}` + Query | `scripts/get_listings_item.py` |\n| **搜索刊登列表** | `listings/2021-08-01/items/{sellerId}` + Query（**无**路径尾段 SKU） | `scripts/search_listings_items.py` |\n| **部分更新 Listing（PATCH）** | 同 **get** 路径 + Query + JSON body | `scripts/patch_listings_item.py` |\n| **创建 / 全量更新 Listing（PUT）** | 同 **get** 路径 + Query + body；**marketplaceIds 仅 1 个** | `scripts/put_listings_item.py` |\n| **删除 Listing（DELETE）** | 同 **get** 路径 + Query（**marketplaceIds 仅 1 个**） | `scripts/delete_listings_item.py` |\n| **刊登限制** | `listings/2021-08-01/restrictions` + Query（asin、sellerId、marketplaceIds 等） | `scripts/get_listings_restrictions.py` |\n| **搜索 Product Type** | `definitions/2020-09-01/productTypes` + Query | `scripts/search_definitions_product_types.py` |\n| **获取 Product Type 定义** | `definitions/2020-09-01/productTypes/{productType}` + Query；**marketplaceIds 仅 1 个** | `scripts/get_definitions_product_type.py` |\n\n**searchListingsItems** 下 `identifiers` / `variationParentSku` / `packageHierarchySku` **三者互斥**（仅该接口；见 **`references/api.md`**）。**searchDefinitionsProductTypes** 下 **`keywords`** 与 **`itemName`** **互斥**。\n\n---\n\n## Quick Parameters\n\n### getListingsItem（单条）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 已授权 Seller ID |\n| region | 是 | `NA` / `EU` / `FE` |\n| sku | 是 | **卖家 SKU**（非 ASIN） |\n| marketplaceIds | 是 | 建议仅 **一个** marketplace id |\n| includedData / issueLocale | 否 | 见 `references/api.md` |\n\n### searchListingsItems（列表）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 已授权 Seller ID |\n| region | 是 | `NA` / `EU` / `FE` |\n| marketplaceIds | 是 | 建议仅 **一个** marketplace id |\n| identifiers + identifiersType | 否 | 最多 **20** 个；与 `variationParentSku`、`packageHierarchySku` **不能同用** |\n| variationParentSku / packageHierarchySku | 否 | 与 identifiers **互斥** |\n| 时间窗 / 状态 / 排序 / 分页 | 否 | `createdAfter`、`lastUpdatedBefore`、`withStatus`、`sortBy`、`pageSize`（≤20）、`pageToken` 等，见 **`references/api.md`** |\n\n### patchListingsItem（部分更新）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 已授权 Seller ID |\n| region | 是 | `NA` / `EU` / `FE` |\n| sku | 是 | **卖家 SKU** |\n| marketplaceIds | 是 | 数组或逗号字符串；脚本拼入 Query |\n| productType | 是 | Amazon product type |\n| patches | 是 | **至少 1 条** JSON Patch（`op`、`path` 等） |\n| includedData / mode / issueLocale | 否 | 见 **`references/api.md`** |\n\n### putListingsItem（创建 / 全量更新）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 已授权 Seller ID |\n| region | 是 | `NA` / `EU` / `FE` |\n| sku | 是 | **卖家 SKU** |\n| marketplaceIds | 是 | **恰好一个** marketplace id |\n| productType | 是 | Amazon product type |\n| requirements | 是 | `LISTING` \\| `LISTING_PRODUCT_ONLY` \\| `LISTING_OFFER_ONLY` |\n| attributes | 是 | 须符合该 product type schema |\n| includedData / mode / issueLocale | 否 | 见 **`references/api.md`** |\n\n### deleteListingsItem（删除）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 已授权 Seller ID |\n| region | 是 | `NA` / `EU` / `FE` |\n| sku | 是 | **卖家 SKU** |\n| marketplaceIds | 是 | **恰好一个** marketplace id |\n| issueLocale | 否 | 见 **`references/api.md`** |\n\n### getListingsRestrictions\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 用于 `storeTokens` 与 Query |\n| region | 是 | `NA` / `EU` / `FE` |\n| asin | 是 | 目录 ASIN |\n| marketplaceIds | 是 | 数组或逗号字符串 |\n| conditionType / reasonLocale | 否 | 见 **`references/api.md`** |\n\n### searchDefinitionsProductTypes\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 用于 `storeTokens` |\n| region | 是 | `NA` / `EU` / `FE` |\n| marketplaceIds | 是 | 数组或逗号字符串 |\n| keywords **或** itemName | 否 | **二者不可同时传**（非空时互斥） |\n| locale / searchLocale | 否 | 见 **`references/api.md`** |\n\n### getDefinitionsProductType\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 用于 `storeTokens` |\n| region | 是 | `NA` / `EU` / `FE` |\n| productType | 是 | 如 `LUGGAGE`（写入 path） |\n| marketplaceIds | 是 | **恰好一个** id |\n| querySellerId | 否 | 若需上游 Query **`sellerId`**（卖家专属 schema），传入；常与 `sellerId` 相同 |\n| productTypeVersion / requirements / requirementsEnforced / locale | 否 | 见 **`references/api.md`** |\n\n---\n\n## Scripts\n\n- **`scripts/get_listings_item.py`** — 单条 listing。\n- **`scripts/search_listings_items.py`** — 搜索列表。\n- **`scripts/patch_listings_item.py`** — PATCH 部分更新。\n- **`scripts/put_listings_item.py`** — PUT 创建或全量更新。\n- **`scripts/delete_listings_item.py`** — DELETE 删除刊登。\n- **`scripts/get_listings_restrictions.py`** — GET 刊登限制。\n- **`scripts/search_definitions_product_types.py`** — GET 搜索 product type。\n- **`scripts/get_definitions_product_type.py`** — GET product type JSON Schema。\n- **`scripts/check_auth_dependency.py`** — 依赖检测。\n\n示例：\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<your-key>\"\n\npython scripts/get_listings_item.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"sku\":\"MY-SKU\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"]}'\n\npython scripts/search_listings_items.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"identifiers\":[\"B0XXXXXXXX\"],\"identifiersType\":\"ASIN\"}'\n\npython scripts/patch_listings_item.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"sku\":\"MY-SKU\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"productType\":\"LUGGAGE\",\"patches\":[{\"op\":\"replace\",\"path\":\"/attributes/item_name\",\"value\":[{\"value\":\"New Title\",\"marketplace_id\":\"ATVPDKIKX0DER\"}]}]}'\n\npython scripts/put_listings_item.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"sku\":\"MY-SKU\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"productType\":\"LUGGAGE\",\"requirements\":\"LISTING\",\"attributes\":{\"item_name\":[{\"value\":\"Title\",\"marketplace_id\":\"ATVPDKIKX0DER\"}]}}'\n\npython scripts/delete_listings_item.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"sku\":\"MY-SKU\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"]}'\n\npython scripts/get_listings_restrictions.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"asin\":\"B0XXXXXXXX\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"]}'\n\npython scripts/search_definitions_product_types.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"keywords\":[\"luggage\"]}'\n\npython scripts/get_definitions_product_type.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"productType\":\"LUGGAGE\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"querySellerId\":\"A1...\"}'\n```\n\n---\n\n## Display Rules\n\n1. **items** 类接口：路径含 **卖家 SKU** 时强调非 ASIN；**searchListingsItems** 路径仅到 `sellerId`。\n2. 展示网关结果时说明 **`errcode` / `httpStatus`**；成功后再解析 `body`（`listing` / `searchResult` / `patchResult` / `putResult` / `deleteResult` / **`restrictionsResult`** / **`productTypesSearchResult`** / **`productTypeDefinitionResult`**）。\n3. **searchListingsItems** 多页：从 `searchResult` 取下一页 token（字段名以 Amazon 响应为准），传入 `pageToken`。\n4. **restrictions** / **definitions** 路径与 **items** 不同；**1005** 时需为 **`listings/2021-08-01/restrictions`** 与 **`definitions/2020-09-01/productTypes`** 等前缀分别配置白名单（以运维为准）。\n5. **patch** / **put** / **delete** 为写操作；**delete** 须谨慎；**put** 为全量 **`attributes`**；**patch** 仅顶层属性可 patch（以官方为准）。\n\n---\n\n## Important Limitations\n\n- **marketplaceIds**：**get** / **searchListingsItems** 脚本对多 id 常仅取第一个；**put** / **delete** / **getDefinitionsProductType** 多于 1 个即报错；**patch**、**restrictions**、**searchDefinitionsProductTypes** 行为见 **`references/api.md`**。\n- **searchListingsItems**：`pageSize` **≤ 20**；`identifiers` **≤ 20**。\n- **patch**：`patches` 至少 1 条；JSON Patch 的 **`delete`** 与 **deleteListingsItem** 接口不同；Vendor 对部分 patch 可能 **400**。\n- **put**：**LISTING_OFFER_ONLY** 对 Vendor **400**。\n- **白名单**：`listings/.../items`、`listings/.../restrictions`、`definitions/2020-09-01/productTypes` 均须按需放行。\n\n## Amazon SP-API 接口保护与重试指引\n\n同一店铺连续收到 Amazon SP-API 的 400、403、404 或 429 时，网关会返回 450、453、454 或 459 并短暂冷却。这些自定义状态码不是 Amazon 原生状态，也不表示封号；目的是避免持续异常或高频调用扩大店铺风险。\n\n| 状态与 message | 范围 | 触发与冷却 | 处理 |\n|---|---|---|---|\n| `450`：`400，请求异常，请优化您的参数` | 店铺+接口 | 60 秒内超过 3 次：5 分钟；10 分钟内超过 4 次：20 分钟 | 停止原参数重试，检查必填字段、marketplace、ID、日期和请求体 |\n| `453`：`403，店铺未授权，请先授权` | 店铺全部接口 | 60 秒内超过 2 次：5 分钟；10 分钟内超过 4 次：30 分钟 | 停止该店铺调用，检查授权、权限、店铺归属和区域 |\n| `454`：`404，资源不存在，请优化您的参数` | 店铺+接口 | 60 秒内超过 3 次：5 分钟；10 分钟内超过 4 次：30 分钟 | 确认资源 ID、所属店铺/站点、资源状态和接口路径 |\n| `459`：`429限流中，请降低频率` | 店铺+接口 | 首次：15 秒；2 分钟内超过 2 次：30 秒；3 分钟内超过 4 次：2 分钟 | 降低并发、分页和轮询频率并逐级退避 |\n\n- 立即停止自动或并发重试，不得通过换脚本或重复创建任务绕过保护；优先遵循 `retryAfter`、`blockedUntil`，没有时按表中时长说明。\n- 450/453/454 必须先修正参数、授权或资源标识，冷却后最多谨慎重试一次；再次触发则停止调用。453 期间停止该店铺全部 SP-API。\n- 保留已有 `reportId`、`feedId` 等任务 ID；写操作结果不确定时先查询状态，不直接重放。\n- 向用户先说明店铺保护，再给原因、处理和等待时间。可回复：“为保护您的亚马逊店铺安全，检测到 Amazon SP-API 连续返回{原因}，当前已进入短暂保护。请先{处理动作}，预计{等待时间}后再试；这不代表封号，也不是套餐或算力限制。”不要只说“LinkFox 限流”或“服务器繁忙”。\n\n## 算力消耗规则\n\n不消耗算力。\n\n**Feedback：** 见 `references/api.md` 中 Feedback API，`skillName`：`linkfox-amazon-store-listings`。\n\n---\n*更多跨境 skill：[LinkFox Skills](https://skill.linkfox.com/)*\n\nFile v1.0.8:_meta.json\n\n{\n  \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n  \"slug\": \"linkfox-amazon-store-listings\",\n  \"version\": \"1.0.8\",\n  \"publishedAt\": 1789361875287\n}\n\nFile v1.0.8:references/api.md\n\n# Amazon 店铺 Listings API 参考（Listings Items / Restrictions / Product Type Definitions）\n\n本文档描述通过 **LinkFox 店铺网关** 调用 Selling Partner API 中与刊登相关的接口：**Listings Items v2021-08-01**（`getListingsItem`、`searchListingsItems`、`patchListingsItem`、`putListingsItem`、`deleteListingsItem`）、**Listings Restrictions v2021-08-01**（`getListingsRestrictions`）、**Product Type Definitions v2020-09-01**（`searchDefinitionsProductTypes`、`getDefinitionsProductType`）。流程与 `linkfox-amazon-store-report` **完全一致**——先取店铺令牌，再经 **`POST /spApi/developerProxy`** 转发上游 HTTP。\n\n> 官方参考：[getListingsItem](https://developer-docs.amazon.com/sp-api/reference/getlistingsitem) · [searchListingsItems](https://developer-docs.amazon.com/sp-api/reference/searchlistingsitems) · [patchListingsItem](https://developer-docs.amazon.com/sp-api/reference/patchlistingsitem) · [putListingsItem](https://developer-docs.amazon.com/sp-api/reference/putlistingsitem) · [deleteListingsItem](https://developer-docs.amazon.com/sp-api/reference/deletelistingsitem) · [getListingsRestrictions](https://developer-docs.amazon.com/sp-api/reference/getlistingsrestrictions) · [searchDefinitionsProductTypes](https://developer-docs.amazon.com/sp-api/reference/searchdefinitionsproducttypes) · [getDefinitionsProductType](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype)（路径、Query、Body、响应以 Amazon 文档为准）。\n\n> ⚠️ **依赖**：调用前需已安装并完成授权流程 **`linkfox-amazon-store-auth`**（`/spApi/storeTokens` 等），参见本 skill 的 `SKILL.md`。\n\n---\n\n## 调用规范（与 store-report 相同）\n\n| 项 | 说明 |\n|----|------|\n| **Base URL** | `${LINKFOX_TOOL_GATEWAY}`（默认 `https://tool-gateway.linkfox.com`；可用 `STORE_API_BASE_URL` 或 `SPAPI_BASE_URL` 覆盖） |\n| **网关认证** | Header `Authorization: <api_key>`，环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY`（如未配置 按 SKILL.md 的 **## 解决认证和算力问题** 处理） |\n| **店铺令牌** | `POST /spApi/storeTokens`，Body：`{\"sellerId\":\"...\",\"region\":\"NA\\|EU\\|FE\"}` → `accessToken` |\n| **SP-API 转发** | `POST /spApi/developerProxy`，Body 见下节 |\n\n---\n\n## 通用接口：`POST /spApi/developerProxy`\n\n与 `linkfox-amazon-store-report` 的 `references/api.md` 中 **Developer Proxy** 定义相同。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| region | string | 是 | `NA` / `EU` / `FE`，须与店铺授权区域一致 |\n| path | string | 是 | **不含** SP-API 主机名前缀，仅 **资源路径**（见下文 Listings **items** / **restrictions**、**definitions/.../productTypes** 等模板） |\n| method | string | 是 | **`GET`**（读操作）、**`PATCH`**、**`PUT`** 或 **`DELETE`**（写操作） |\n| amzAccessToken | string | 是 | `/spApi/storeTokens` 返回的 `accessToken` |\n| queryString | string | 视操作 | **无 `?` 前缀**。各操作必填/可选 Query 见各节（**put** / **delete** / **getDefinitionsProductType** 的 `marketplaceIds` 等见官方 **length ≤ 1** 说明） |\n| body | string | 视操作 | **PATCH / PUT** 时 JSON 字符串。**GET** / **DELETE** 通常不传 |\n| contentType | string | 视操作 | **PATCH / PUT** 建议 **`application/json`**。**GET** / **DELETE** 通常省略 |\n\n**网关响应**（与报告 skill 一致）：\n\n```json\n{\n  \"errcode\": 200,\n  \"errmsg\": \"ok\",\n  \"httpStatus\": 200,\n  \"contentType\": \"application/json\",\n  \"body\": \"{... Amazon 返回的 JSON 字符串 ...}\"\n}\n```\n\n解析步骤：**先看 `errcode`**，再 **`httpStatus`**，最后将 **`body`** 做 `JSON.parse`。\n\n### 白名单与错误码\n\n- `path` 必须在后端 **`sp-api.developer-proxy.allowed-path-prefixes`** 白名单内。若 **`errcode=1005`**，需联系后端放行（常见前缀，以运维为准）：\n  - **`listings/2021-08-01/items`**：`get` / `patch` / `put` / `delete` 为 `.../items/{sellerId}/{sku}`，`searchListingsItems` 为 `.../items/{sellerId}`；\n  - **`listings/2021-08-01/restrictions`**：`getListingsRestrictions`（**无** path 变量，固定 `.../restrictions`）；\n  - **`definitions/2020-09-01/productTypes`**：`searchDefinitionsProductTypes` 与 **`getDefinitionsProductType`**（后者 path 含 **`/{productType}`** 段）。\n- 网关须允许 **`PATCH`**、**`PUT`**、**`DELETE`**（及已有 **GET**）转发。\n- 其它 **`errcode`** / **`httpStatus`** 含义与处置与 `linkfox-amazon-store-report` 的 `references/api.md` 中 **Error Codes** / **Developer Proxy 上游状态码** 表格一致（400 参数、403 令牌/权限、404 无此 SKU 等）。\n- HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和算力问题** 处理。\n- HTTP 402：按 SKILL.md 的 **## 解决认证和算力问题** 处理。\n\n---\n\n## getListingsItem — 上游语义与网关映射\n\n### HTTP 与方法（Amazon）\n\n- **Method**：`GET`\n- **资源路径模板**（写入 `developerProxy.path`）：\n\n```text\nlistings/2021-08-01/items/{sellerId}/{sku}\n```\n\n其中 **`{sellerId}`**、**`{sku}`** 须做 **URL path 分段编码**（例如空格、`/` 等字符）；本仓库脚本使用百分号编码后拼入 `path`。\n\n> 说明：不同区域 SP-API **主机名**不同（na/eu/fe 等），由网关按 `region` + `amzAccessToken` 解析，调用方**只传相对 path** 即可。\n\n### Path 参数（写入 path 的占位段）\n\n| 名称 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| sellerId | string | 是 | 卖家标识，与已授权店铺一致（与 `/spApi/storeTokens` 所用 `sellerId` 相同） |\n| sku | string | 是 | **卖家自定义 SKU**（Seller SKU），不是 ASIN。须与 Listing 在目标站点下实际存在的 seller SKU 一致 |\n\n### Query 参数（写入 `developerProxy.queryString`，无 `?`）\n\n以下按 Amazon 文档整理；**键名大小写**须与官方一致。\n\n| 参数名 | 类型 | 必填 | 约束 / 说明 |\n|--------|------|------|----------------|\n| marketplaceIds | string | **是** | 目标 marketplace id。官方 schema 常见为 **单站点**（文档标注 length ≤ 1 时应只传 **一个** id）。多个 id 时本仓库脚本 **仅取第一个** 并打 stderr 警告。示例：`ATVPDKIKX0DER`（美国）。**Query 中写法**：`marketplaceIds=ATVPDKIKX0DER`（单值；若网关要求重复键名以官方为准，一般单站点即可） |\n| includedData | string | 否 | 逗号分隔数据集列表，控制响应中包含哪些块。**不传**时上游通常等价于默认 **`summaries`**（以实网为准）。可选值（与官方一致）：`summaries`、`attributes`、`issues`、`offers`、`fulfillmentAvailability`、`procurement`、`relationships`、`productTypes`。示例：`includedData=summaries,attributes` |\n| issueLocale | string | 否 | **issues** 等字段的本地化语言。示例：`en_US`、`fr_CA`。未传时通常使用第一个 marketplace 的默认语言；不可用回退行为以 Amazon 为准 |\n\n### 官方默认与速率（摘要）\n\n- **includedData** 默认集：文档为 **`summaries`**（若需结构化属性、报价、库存等，请在 `includedData` 中显式增加对应 token）。\n- **Usage plan（文档默认值）**：约 **5 req/s**，burst **10**（以响应头 `x-amzn-RateLimit-Limit` 及账号实际配额为准）。\n\n### 上游成功 / 常见错误（httpStatus）\n\n| httpStatus | 含义（摘要） |\n|------------|----------------|\n| 200 | 成功，`body` 为 Listing 详情 JSON |\n| 400 | Query / Path 非法或无法解析 |\n| 403 | 拒绝访问（令牌、签名、权限等） |\n| 404 | 指定 `sellerId`+`sku`+`marketplaceIds` 下无该 listing |\n| 413 | 请求过大 |\n| 415 | 不支持的媒体类型 |\n| 429 | 限流 |\n| 500 / 503 | 上游异常或维护 |\n\n---\n\n## 脚本参数映射（`scripts/get_listings_item.py`）\n\n| 脚本 JSON 字段 | 映射到 developerProxy |\n|----------------|-------------------------|\n| sellerId | 用于 `storeTokens`；并编码进 `path` 第一段 |\n| region | `region` |\n| sku | 编码进 `path` 第二段 |\n| marketplaceIds | `array[string]` 或单个 `string` → `queryString.marketplaceIds`（多元素时仅首元素） |\n| includedData | 可选，`array` 用逗号拼接 → `queryString.includedData` |\n| issueLocale | 可选 → `queryString.issueLocale` |\n\n脚本在 stdout 打印 JSON：含 `developerProxy` 原始包、`resolvedPath`、`queryString`；若 `errcode==200` 且 `httpStatus==200`，额外解析 `listing` 对象（`body` 的 JSON）。\n\n---\n\n## searchListingsItems — 上游语义与网关映射\n\n> 官方：[searchListingsItems](https://developer-docs.amazon.com/sp-api/reference/searchlistingsitems)\n\n### HTTP 与方法\n\n- **Method**：`GET`\n- **资源路径**（写入 `developerProxy.path`，仅含 `sellerId`，**无**路径尾段的 SKU）：\n\n```text\nlistings/2021-08-01/items/{sellerId}\n```\n\n`{sellerId}` 须 **URL 编码**（与 getListingsItem 相同约定）。\n\n### Path 参数\n\n| 名称 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| sellerId | string | 是 | 卖家标识，与已授权店铺及 `storeTokens` 一致 |\n\n### Query 参数（写入 `queryString`）\n\n| 参数名 | 类型 | 必填 | 约束 / 说明 |\n|--------|------|------|-------------|\n| marketplaceIds | string | **是** | 文档为 **length ≤ 1** 的 marketplace id 列表（逗号分隔语义）；本仓库脚本与 get 一致：**多传时仅取第一个** 并告警。示例：`ATVPDKIKX0DER` |\n| issueLocale | string | 否 | 本地化 issues 等，如 `en_US`、`fr_CA`；未传时行为以 Amazon 为准 |\n| includedData | string | 否 | 逗号分隔，默认文档为 **`summaries`**。可选：`summaries`、`attributes`、`issues`、`offers`、`fulfillmentAvailability`、`procurement`、`relationships`、`productTypes` |\n| identifiers | string | 条件 | **最多 20 个**商品标识，逗号分隔（脚本接受 JSON 数组，输出为逗号拼接）。**与 `identifiersType` 成对出现**：传了 identifiers 必须带 identifiersType，反之亦然 |\n| identifiersType | string | 条件 | 标识类型枚举：`SKU`、`ASIN`、`EAN`、`FNSKU`、`GTIN`、`ISBN`、`JAN`、`MINSAN`、`UPC`（以官方为准） |\n| variationParentSku | string | 条件 | 只返回该 **父 SKU** 下的变体子体。**禁止**与 `identifiers` / `packageHierarchySku` 同时使用 |\n| packageHierarchySku | string | 条件 | 返回包含或由该 SKU 构成的层级相关 listing。**禁止**与 `identifiers` / `variationParentSku` 同时使用 |\n| createdAfter | string | 否 | ISO 8601 **date-time**，筛选创建时间 ≥ 该时刻 |\n| createdBefore | string | 否 | ISO 8601，创建时间 ≤ 该时刻 |\n| lastUpdatedAfter | string | 否 | ISO 8601，最后更新时间 ≥ 该时刻 |\n| lastUpdatedBefore | string | 否 | ISO 8601，最后更新时间 ≤ 该时刻 |\n| withIssueSeverity | string | 否 | 逗号分隔；取值：`ERROR`、`WARNING`（仅包含有对应严重度 issue 的刊登） |\n| withStatus | string | 否 | 逗号分隔；取值：`BUYABLE`、`DISCOVERABLE`（文档注明 BUYABLE 不适用于 vendor listings） |\n| withoutStatus | string | 否 | 逗号分隔；同上枚举，表示 **排除** 含该状态的刊登 |\n| sortBy | string | 否 | 默认文档 **`lastUpdatedDate`**。允许：`sku`、`createdDate`、`lastUpdatedDate` |\n| sortOrder | string | 否 | 默认 **`DESC`**。允许：`ASC`、`DESC` |\n| pageSize | integer | 否 | 默认 **10**，**最大 20**（超出时脚本会截断为 20 并告警） |\n| pageToken | string | 否 | 下一页令牌（上一页响应中的分页字段，以 `body` JSON 为准） |\n\n### 互斥规则（官方 Note）\n\n以下 **不能混用**（本仓库 `search_listings_items.py` 会做校验）：\n\n1. 使用 **`identifiers` / `identifiersType`** 时，**不得**再传 `variationParentSku` 或 `packageHierarchySku`。\n2. 使用 **`variationParentSku`** 时，**不得**使用 `identifiers`（及 `identifiersType`）或 `packageHierarchySku`。\n3. 使用 **`packageHierarchySku`** 时，**不得**使用 `identifiers` 或 `variationParentSku`。\n4. **`variationParentSku`** 与 **`packageHierarchySku`** 亦不得同时使用。\n\n### 速率（文档摘要）\n\n- 默认约 **5 req/s**，burst **5**（以 `x-amzn-RateLimit-Limit` 与账号配额为准；与 getListingsItem 的 burst 可能不同）。\n\n### 成功响应\n\n- **`httpStatus=200`** 时，`body` 为 JSON 字符串，通常含 **列表 + 分页**（字段名以 Amazon 响应为准，常见含 `items`、`numberOfResults`、`pagination` 等）。\n\n---\n\n## 脚本参数映射（`scripts/search_listings_items.py`）\n\n| 脚本 JSON 字段 | 映射 |\n|----------------|------|\n| sellerId | `storeTokens` + path 编码 |\n| region | `region` |\n| marketplaceIds | 同 get；→ `marketplaceIds` |\n| issueLocale / includedData | → Query |\n| identifiers | `array` 或逗号字符串，≤20 个 → `identifiers` |\n| identifiersType | → `identifiersType` |\n| variationParentSku / packageHierarchySku | → 同名 Query |\n| createdAfter / createdBefore / lastUpdatedAfter / lastUpdatedBefore | → 同名 Query |\n| withIssueSeverity / withStatus / withoutStatus | `array` 或逗号字符串 → 逗号拼接 |\n| sortBy / sortOrder / pageSize / pageToken | → 同名 Query |\n\n成功且 `errcode==200`、`httpStatus==200` 时，脚本 stdout 中额外包含 **`searchResult`**（`body` 解析后的对象）。\n\n---\n\n## patchListingsItem — 上游语义与网关映射\n\n> 官方：[patchListingsItem](https://developer-docs.amazon.com/sp-api/reference/patchlistingsitem)\n\n仅支持对 **顶层** listing 属性做 JSON Patch；嵌套属性 patch 行为以 Amazon 文档为准。**Vendor** 场景下 **`delete`** 可能返回 **400**（官方说明）。\n\n### HTTP 与方法\n\n- **Method**：`PATCH`（经 `developerProxy.method` 传入 **`PATCH`**）\n- **Path**（与 getListingsItem 相同，含 **sellerId** 与 **卖家 SKU**）：\n\n```text\nlistings/2021-08-01/items/{sellerId}/{sku}\n```\n\n两段路径均需 **URL 编码**。\n\n### Query 参数（`queryString`）\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| marketplaceIds | string | **是** | 逗号分隔的 marketplace id 列表（脚本接受 JSON 数组并拼为逗号）。与 get 不同，patch 文档为 **列表**；多站点时一并传入 |\n| includedData | string | 否 | 逗号分隔；默认文档为 **`issues`**。可选：`identifiers`、`issues`。文档说明：**`identifiers`** 仅在 **`mode=VALIDATION_PREVIEW`** 时可请求 |\n| mode | string | 否 | 枚举：**`VALIDATION_PREVIEW`**（校验预览模式，与 `includedData=identifiers` 等组合以官方为准） |\n| issueLocale | string | 否 | 如 `en_US`、`fr_CA`；issues 本地化 |\n\n### Body（`developerProxy.body`，JSON 字符串）\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| productType | string | **是** | Amazon **product type**（如 `LUGGAGE`、`PRODUCT` 等，须与该 listing 在目录中的类型一致，以 [Product Type Definitions](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype) 为准） |\n| patches | array | **是** | **至少 1 条** [JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) 操作（Amazon 支持子集） |\n\n**单条 patch 对象**（`patches[]`）：\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| op | 是 | `add` \\| `replace` \\| `merge` \\| `delete` |\n| path | 是 | **JSON Pointer**，指向待修改属性（如 `/attributes/item_name`） |\n| value | 视 op | `add` / `replace` / `merge` 通常需要；`delete` 可无（Vendor 可能不支持 delete） |\n\n### 速率（文档摘要）\n\n- 默认约 **5 req/s**，burst **5**（以响应头与账号配额为准）。\n\n### 响应（httpStatus）\n\n- **200**：已理解 patch 请求；是否被接受须解析 **`body`** 内 issues / status（以 Amazon 响应 schema 为准）。\n- **400 / 403 / 413 / 415 / 429 / 500 / 503**：与通用 SP-API 语义一致。\n\n---\n\n## 脚本参数映射（`scripts/patch_listings_item.py`）\n\n| 脚本 JSON 字段 | 映射 |\n|----------------|------|\n| sellerId / region / sku | `storeTokens` + `path` 编码 |\n| marketplaceIds | 数组或逗号字符串 → `marketplaceIds`（Query，逗号拼接） |\n| productType / patches | → **PATCH body** |\n| includedData / mode / issueLocale | → Query |\n\n成功且 `errcode==200`、`httpStatus==200` 时，stdout 额外含 **`patchResult`**（解析后的 `body`）。\n\n---\n\n## putListingsItem — 上游语义与网关映射\n\n> 官方：[putListingsItem](https://developer-docs.amazon.com/sp-api/reference/putlistingsitem)\n\n**创建**新刊登或对现有刊登做**全量**更新（非部分 patch）；请求体为完整 **`attributes`** 对象，须符合该 **productType** 的 JSON Schema。\n\n### HTTP 与方法\n\n- **Method**：`PUT`（经 `developerProxy.method` 传入 **`PUT`**）\n- **Path**（与 getListingsItem / patchListingsItem 相同）：\n\n```text\nlistings/2021-08-01/items/{sellerId}/{sku}\n```\n\n两段路径均需 **URL 编码**。\n\n### Query 参数（`queryString`）\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| marketplaceIds | string | **是** | 官方约束：**length ≤ 1**（仅 **一个** marketplace id）。脚本在传入多个 id 时 **报错**（与 patch 允许多 id 不同） |\n| includedData | string | 否 | 逗号分隔；默认文档为 **`issues`**。可选：`identifiers`、`issues`。**`identifiers`** 仅在 **`mode=VALIDATION_PREVIEW`** 时可请求 |\n| mode | string | 否 | **`VALIDATION_PREVIEW`**（校验预览） |\n| issueLocale | string | 否 | issues 本地化，如 `en_US` |\n\n### Body（`developerProxy.body`，JSON 字符串）\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| productType | string | **是** | Amazon product type（与目录一致，参见 [Product Type Definitions](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype)） |\n| requirements | string | **是** | **`LISTING`**（商品事实 + 销售条款）\\| **`LISTING_PRODUCT_ONLY`**（仅商品事实）\\| **`LISTING_OFFER_ONLY`**（仅销售条款；**Vendor 不支持**，会 **400**） |\n| attributes | object | **是** | 以属性名为键的结构化刊登数据；须满足该 product type 的 schema |\n\n### 速率（文档摘要）\n\n- 默认约 **5 req/s**，burst **10**（以响应头与账号配额为准）。\n\n### 响应（httpStatus）\n\n- **200**：已理解创建/全量更新请求；是否被接受须解析 **`body`** 内 issues 等（以 Amazon 响应为准）。\n- **400 / 403 / 413 / 415 / 429 / 500 / 503**：与通用 SP-API 语义一致。\n\n---\n\n## 脚本参数映射（`scripts/put_listings_item.py`）\n\n| 脚本 JSON 字段 | 映射 |\n|----------------|------|\n| sellerId / region / sku | `storeTokens` + `path` 编码 |\n| marketplaceIds | 数组或逗号字符串 → **恰好 1 个** id 写入 Query（多于 1 个则脚本拒绝） |\n| productType / requirements / attributes | → **PUT body** |\n| includedData / mode / issueLocale | → Query |\n\n成功且 `errcode==200`、`httpStatus==200` 时，stdout 额外含 **`putResult`**（解析后的 `body`）。\n\n---\n\n## deleteListingsItem — 上游语义与网关映射\n\n> 官方：[deleteListingsItem](https://developer-docs.amazon.com/sp-api/reference/deletelistingsitem)\n\n删除指定 **marketplace** 下该 **sellerId + sku** 的刊登项；**无请求体**。\n\n### HTTP 与方法\n\n- **Method**：`DELETE`（经 `developerProxy.method` 传入 **`DELETE`**）\n- **Path**（与 get / patch / put 相同）：\n\n```text\nlistings/2021-08-01/items/{sellerId}/{sku}\n```\n\n两段路径均需 **URL 编码**。\n\n### Query 参数（`queryString`）\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| marketplaceIds | string | **是** | 官方约束：**length ≤ 1**（仅 **一个** marketplace id） |\n| issueLocale | string | 否 | 本地化，如 `en_US`、`fr_CA` |\n\n### 速率（文档摘要）\n\n- 默认约 **5 req/s**，burst **5**（以响应头与账号配额为准）。\n\n### 响应（httpStatus）\n\n- **200**：已理解删除请求；是否被接受须解析 **`body`**（以 Amazon 响应为准）。\n- **400 / 403 / 413 / 415 / 429 / 500 / 503**：与通用 SP-API 语义一致。\n\n---\n\n## 脚本参数映射（`scripts/delete_listings_item.py`）\n\n| 脚本 JSON 字段 | 映射 |\n|----------------|------|\n| sellerId / region / sku | `storeTokens` + `path` 编码 |\n| marketplaceIds | 数组或逗号字符串 → **恰好 1 个** id 写入 Query（多于 1 个则脚本拒绝） |\n| issueLocale | 否 → Query |\n\n成功且 `errcode==200`、`httpStatus==200` 时，stdout 额外含 **`deleteResult`**（解析后的 `body`）。\n\n---\n\n## getListingsRestrictions — 上游语义与网关映射\n\n> 官方：[getListingsRestrictions](https://developer-docs.amazon.com/sp-api/reference/getlistingsrestrictions)\n\n返回目录 **ASIN** 在指定 **sellerId** 与 **marketplaceIds** 下的刊登限制。\n\n### HTTP 与方法\n\n- **Method**：`GET`\n- **Path**（固定，无 path 参数）：\n\n```text\nlistings/2021-08-01/restrictions\n```\n\n### Query 参数（`queryString`）\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| asin | string | **是** | 目录 ASIN |\n| sellerId | string | **是** | 卖家标识（与 `storeTokens` 所用可一致） |\n| marketplaceIds | string | **是** | 逗号分隔 marketplace id 列表（脚本接受数组并拼接） |\n| conditionType | string | 否 | 商品状况枚举，用于过滤限制（如 `new`、`used_like_new` 等，以官方枚举为准） |\n| reasonLocale | string | 否 | 原因文案本地化，如 `en_US` |\n\n### 速率（文档摘要）\n\n- 默认约 **5 req/s**，burst **10**。\n\n### 响应\n\n- **200**：成功返回限制信息；**404** 等资源类错误以 Amazon 为准。\n\n---\n\n## 脚本参数映射（`scripts/get_listings_restrictions.py`）\n\n| 脚本 JSON 字段 | 映射 |\n|----------------|------|\n| sellerId / region | `storeTokens` |\n| asin / marketplaceIds / conditionType / reasonLocale | → Query |\n\n成功且 `errcode==200`、`httpStatus==200` 时，stdout 额外含 **`restrictionsResult`**。\n\n---\n\n## searchDefinitionsProductTypes — 上游语义与网关映射\n\n> 官方：[searchDefinitionsProductTypes](https://developer-docs.amazon.com/sp-api/reference/searchdefinitionsproducttypes)\n\n搜索可用的 **product type** 定义列表。\n\n### HTTP 与方法\n\n- **Method**：`GET`\n- **Path**：\n\n```text\ndefinitions/2020-09-01/productTypes\n```\n\n### Query 参数\n\n| 参数名 | 必填 | 说明 |\n|--------|------|------|\n| marketplaceIds | **是** | 逗号分隔（脚本接受数组） |\n| keywords | 否 | 逗号分隔关键词列表；**不可与** `itemName` **同用** |\n| itemName | 否 | ASIN 商品标题用于推荐 product type；**不可与** `keywords` **同用** |\n| locale / searchLocale | 否 | 展示语言、搜索所用 locale |\n\n### 速率（文档摘要）\n\n- 默认约 **5 req/s**，burst **10**。\n\n---\n\n## 脚本参数映射（`scripts/search_definitions_product_types.py`）\n\n| 脚本 JSON 字段 | 映射 |\n|----------------|------|\n| sellerId / region | `storeTokens` |\n| marketplaceIds | → Query |\n| keywords / itemName | → Query（**互斥**，脚本校验） |\n| locale / searchLocale | → Query |\n\n成功且 `errcode==200`、`httpStatus==200` 时，stdout 额外含 **`productTypesSearchResult`**。\n\n---\n\n## getDefinitionsProductType — 上游语义与网关映射\n\n> 官方：[getDefinitionsProductType](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype)\n\n按 **productType** 名称拉取 JSON Schema 定义。\n\n### HTTP 与方法\n\n- **Method**：`GET`\n- **Path**：\n\n```text\ndefinitions/2020-09-01/productTypes/{productType}\n```\n\n`{productType}` 须 **URL 编码**（脚本使用 `urllib.parse.quote`）。\n\n### Query 参数\n\n| 参数名 | 必填 | 说明 |\n|--------|------|------|\n| marketplaceIds | **是** | 官方说明当前 **limited to one** `marketplaceId`；脚本 **多于 1 个即报错** |\n| sellerId | 否 | 传入时填充卖家相关 schema；脚本字段 **`querySellerId`** → Query **`sellerId`**（避免与用于取令牌的 `sellerId` 混淆；通常可设为相同值） |\n| productTypeVersion | 否 | 默认 **`LATEST`**；预发布可用 **`RELEASE_CANDIDATE`**（以官方为准） |\n| requirements | 否 | `LISTING` \\| `LISTING_PRODUCT_ONLY` \\| `LISTING_OFFER_ONLY`（默认 **LISTING**） |\n| requirementsEnforced | 否 | `ENFORCED` \\| `NOT_ENFORCED` |\n| locale | 否 | 展示标签等所用 locale（官方枚举见文档） |\n\n### 速率（文档摘要）\n\n- 默认约 **5 req/s**，burst **10**。大 schema 响应体可能较大。\n\n---\n\n## 脚本参数映射（`scripts/get_definitions_product_type.py`）\n\n| 脚本 JSON 字段 | 映射 |\n|----------------|------|\n| sellerId / region | `storeTokens`（`sellerId` 为授权店铺） |\n| productType | → path 末段（编码） |\n| marketplaceIds | → Query，**恰好 1 个** id |\n| querySellerId | → Query `sellerId`（可选） |\n| productTypeVersion / requirements / requirementsEnforced / locale | → Query |\n\n成功且 `errcode==200`、`httpStatus==200` 时，stdout 额外含 **`productTypeDefinitionResult`**。\n\n---\n\n## curl 示例（两步：取令牌 + 代理 GET / PATCH / PUT / DELETE）\n\n**1）取 `accessToken`（与 store-report 相同）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/storeTokens\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"sellerId\":\"A1BCDEFGHIJK2\",\"region\":\"NA\"}'\n```\n\n**2）getListingsItem（path 与 query 按实际 sellerId / sku / marketplace 替换）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"listings/2021-08-01/items/A1BCDEFGHIJK2/My-Seller-SKU-001\",\n    \"method\": \"GET\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"marketplaceIds=ATVPDKIKX0DER&includedData=summaries,attributes\"\n  }'\n```\n\n> 若 `sku` 或 `sellerId` 含需编码字符，请使用与脚本一致的 **百分号编码** 后再放入 `path`。\n\n**3）searchListingsItems（path 仅到 `sellerId`，query 含 marketplaceIds 与分页等）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"listings/2021-08-01/items/A1BCDEFGHIJK2\",\n    \"method\": \"GET\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"marketplaceIds=ATVPDKIKX0DER&pageSize=10&sortBy=lastUpdatedDate&sortOrder=DESC&includedData=summaries\"\n  }'\n```\n\n按 ASIN 搜索时，在 `queryString` 中增加 `identifiers` 与 `identifiersType`（**勿与** `variationParentSku` / `packageHierarchySku` 同用），例如：`identifiers=B08N5WRWNW&identifiersType=ASIN`（示例 ASIN 请替换为真实值）。\n\n**4）patchListingsItem（`method` 为 `PATCH`，`body` 为 JSON 字符串；`productType` 与 `patches` 须按官方 schema 填写）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"listings/2021-08-01/items/A1BCDEFGHIJK2/My-Seller-SKU-001\",\n    \"method\": \"PATCH\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"marketplaceIds=ATVPDKIKX0DER&includedData=issues\",\n    \"contentType\": \"application/json\",\n    \"body\": \"{\\\"productType\\\":\\\"LUGGAGE\\\",\\\"patches\\\":[{\\\"op\\\":\\\"replace\\\",\\\"path\\\":\\\"/attributes/item_name\\\",\\\"value\\\":[{\\\"value\\\":\\\"Example\\\",\\\"marketplace_id\\\":\\\"ATVPDKIKX0DER\\\"}]}]}\"\n  }'\n```\n\n> 上例 **`body` 仅演示字段形态**；真实 `path` / `value` 必须与 **product type JSON Schema** 一致，否则会 **400**。\n\n**5）putListingsItem（`method` 为 `PUT`；`marketplaceIds` 在 Query 中仅 **一个** id；`body` 含 `productType`、`requirements`、`attributes`）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"listings/2021-08-01/items/A1BCDEFGHIJK2/My-Seller-SKU-001\",\n    \"method\": \"PUT\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"marketplaceIds=ATVPDKIKX0DER&includedData=issues\",\n    \"contentType\": \"application/json\",\n    \"body\": \"{\\\"productType\\\":\\\"LUGGAGE\\\",\\\"requirements\\\":\\\"LISTING\\\",\\\"attributes\\\":{\\\"item_name\\\":[{\\\"value\\\":\\\"Example Title\\\",\\\"marketplace_id\\\":\\\"ATVPDKIKX0DER\\\"}]}}\"\n  }'\n```\n\n> 上例 **`attributes` 仅演示键形态**；须与 **product type schema** 一致。**LISTING_OFFER_ONLY** 对 Vendor 会 **400**。\n\n**6）deleteListingsItem（`method` 为 `DELETE`；`queryString` 仅含 **一个** `marketplaceIds`；不传 `body`）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"listings/2021-08-01/items/A1BCDEFGHIJK2/My-Seller-SKU-001\",\n    \"method\": \"DELETE\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"marketplaceIds=ATVPDKIKX0DER\"\n  }'\n```\n\n**7）getListingsRestrictions（固定 path `listings/2021-08-01/restrictions`，Query 含 asin、sellerId、marketplaceIds）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"listings/2021-08-01/restrictions\",\n    \"method\": \"GET\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"asin=B08N5WRWNW&sellerId=A1BCDEFGHIJK2&marketplaceIds=ATVPDKIKX0DER\"\n  }'\n```\n\n**8）searchDefinitionsProductTypes（path `definitions/2020-09-01/productTypes`；`keywords` 与 `itemName` 勿同用）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"definitions/2020-09-01/productTypes\",\n    \"method\": \"GET\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"marketplaceIds=ATVPDKIKX0DER&keywords=luggage,suitcase\"\n  }'\n```\n\n**9）getDefinitionsProductType（path 末段为 product type 名称；`marketplaceIds` 仅一个）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"definitions/2020-09-01/productTypes/LUGGAGE\",\n    \"method\": \"GET\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"marketplaceIds=ATVPDKIKX0DER&requirements=LISTING&productTypeVersion=LATEST\"\n  }'\n```\n\n---\n\n## Feedback API\n\n- **POST** `https://skill-api.linkfox.com/api/v1/public/feedback`\n- **Content-Type:** `application/json`\n\n```json\n{\n  \"skillName\": \"linkfox-amazon-store-listings\",\n  \"sentiment\": \"POSITIVE\",\n  \"category\": \"OTHER\",\n  \"content\": \"getListingsItem / searchListingsItems / patchListingsItem / putListingsItem / deleteListingsItem / getListingsRestrictions / searchDefinitionsProductTypes / getDefinitionsProductType 结果符合预期。\"\n}\n```\n\nFile v1.0.8:references/onboarding.md\n\n# 解决认证和算力问题\n\n调用本 skill 时若网关返回 **auth** 或 **billing** 错误，走本 skill 自带的 `scripts/onboarding.py` 完成引导。\n\n**auth 场景**：`errcode=401` 或消息含 `authorized error`/`鉴权失败`/`未授权`/`unauthorized`；或 `LINKFOX_AGENT_API_KEY` 与 `LINKFOXAGENT_API_KEY` 均为空。\n1. 若已配置 key → 先让用户重启会话（最常见误判），仍失败让用户重新取 key 或换手机号重注册\n2. 未配置 → 询问：自助去 https://agent.linkfox.com/ 取 key，或提供手机号让脚本注册\n3. 手机号路径：\n   - `python scripts/onboarding.py send-code <phone>` → 展示 JSON 里的 phone/agreements\n   - 收到验证码后：`python scripts/onboarding.py login <phone> <code>`\n   - 拿到 `api_key` 后把下面三平台配置转发给用户，提示重启会话生效：\n     - Windows PowerShell（永久）：`setx LINKFOX_AGENT_API_KEY \"<key>\"`\n     - macOS zsh：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.zshrc && source ~/.zshrc`\n     - Linux bash：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.bashrc && source ~/.bashrc`\n     - 变量名 `LINKFOX_AGENT_API_KEY`（主推）或 `LINKFOXAGENT_API_KEY`（老规范）任一即可\n\n**billing 场景**：`errcode=402` 或消息含 `算力/余额/quota/insufficient/充值/套餐到期`。\n- `python scripts/onboarding.py list-plans` → 有 AskUserQuestion 就弹菜单，否则输出编号清单让用户选\n- 校验 `plan_id` ∈ 清单、支付方式 ∈ 该套餐 `available_methods`（通常 `wechat/alipay`）\n- `python scripts/onboarding.py order <plan_id> <method>` → 展示优先级 PNG > `pay_url` > `ascii_qr`（标注兜底）\n- 已付款可选调 `python scripts/onboarding.py query <order_id>`，不主动轮询\n\n排除 `errcode=403`（无权限，不归入这两类）。所有子命令输出 stdout JSON，`error` 字段已含阶段前缀，透传给用户即可。完整用法：`python scripts/onboarding.py --help`。\n\nFile v1.0.8:skill-card.md\n\n## Description:\n\n亚马逊卖家 Listing 刊登与商品类型定义管理，用于查询、搜索、创建、更新、局部修改和删除卖家 Listing，检查 ASIN 刊登限制，并查询 product type 及其 JSON Schema 属性要求。\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 Amazon sellers and their agents use this skill to manage seller-owned Listings through LinkFox and Amazon SP-API workflows. It supports Listing lookup, search, patch, put, delete, restrictions checks, and product type schema discovery.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can read and modify Amazon seller listings, including create, update, patch, and delete actions.\n\nMitigation: Require explicit human confirmation before patch, put, or delete operations, and verify sellerId, region, SKU, marketplaceIds, productType, and request body before execution.\n\nRisk: The skill can assist with LinkFox account login, API-key generation, billing, and payment/order flows.\n\nMitigation: Run only in a trusted environment, keep API keys out of shared logs, and require explicit user approval before login, API-key, payment, or order steps.\n\nRisk: Saved LinkFox response files may contain sensitive seller or listing data.\n\nMitigation: Review generated linkfox response files before sharing or committing them and apply local data handling controls for seller information.\n\nRisk: Custom LinkFox endpoint environment variables can redirect requests to a different destination.\n\nMitigation: Do not set custom LinkFox endpoint variables unless the destination is controlled and trusted.\n\n## Reference(s):\n\n- [Amazon 店铺 Listings API 参考](artifact/references/api.md)\n- [解决认证和算力问题](artifact/references/onboarding.md)\n- [getListingsItem](https://developer-docs.amazon.com/sp-api/reference/getlistingsitem)\n- [searchListingsItems](https://developer-docs.amazon.com/sp-api/reference/searchlistingsitems)\n- [patchListingsItem](https://developer-docs.amazon.com/sp-api/reference/patchlistingsitem)\n- [putListingsItem](https://developer-docs.amazon.com/sp-api/reference/putlistingsitem)\n- [deleteListingsItem](https://developer-docs.amazon.com/sp-api/reference/deletelistingsitem)\n- [getListingsRestrictions](https://developer-docs.amazon.com/sp-api/reference/getlistingsrestrictions)\n- [searchDefinitionsProductTypes](https://developer-docs.amazon.com/sp-api/reference/searchdefinitionsproducttypes)\n- [getDefinitionsProductType](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype)\n- [ClawHub skill page](https://clawhub.ai/linkfox-ai/skills/linkfox-amazon-store-listings)\n\n## Skill Output:\n\n**Output Type(s):** [Text, JSON, Shell commands, Configuration, Guidance, Files]\n\n**Output Format:** [Markdown guidance with shell commands and JSON API responses; scripts save full JSON response files.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Responses may include Amazon seller Listing data and LinkFox account or billing guidance.]\n\n## Skill Version(s):\n\n1.0.8 (source: server release metadata)\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.0.7: 16 files, 58140 bytes\n\nFiles: references/api.md (31624b), references/onboarding.md (2046b), scripts/_spapi_listings_common.py (6542b), scripts/check_auth_dependency.py (10349b), scripts/delete_listings_item.py (7242b), scripts/get_definitions_product_type.py (8267b), scripts/get_listings_item.py (8222b), scripts/get_listings_restrictions.py (7286b), scripts/onboarding.py (24089b), scripts/patch_listings_item.py (9065b), scripts/put_listings_item.py (8972b), scripts/search_definitions_product_types.py (8216b), scripts/search_listings_items.py (12370b), skill-card.md (3493b), SKILL.md (13250b), _meta.json (148b)\n\nFile v1.0.7:SKILL.md\n\n---\nname: linkfox-amazon-store-listings\ndescription: 亚马逊店铺 Listing 与刊登相关定义/限制（与 linkfox-amazon-store-auth / linkfox-amazon-store-report 同系列），经 LinkFox /spApi/developerProxy 调用 SP-API：Listings Items（get/search/patch/put/delete）、Listings Restrictions（getListingsRestrictions）、Product Type Definitions（searchDefinitionsProductTypes、getDefinitionsProductType）。当用户提到获取或删除 Listing、刊登限制、ASIN 能否卖、product type 定义、JSON Schema 刊登属性、searchDefinitionsProductTypes、getDefinitionsProductType、getListingsRestrictions、Listings Restrictions、亚马逊刊登列表 时触发。\n---\n\n# Amazon 店铺 Listings 与相关 API\n\n本 skill 与 **`linkfox-amazon-store-auth`**、**`linkfox-amazon-store-report`** 同属 **Amazon Store** 系列：依赖 **`linkfox-amazon-store-auth`** 选店（`sellerId`+`region`）；直接 **`POST /spApi/developerProxy`** 传入 `sellerId`+`region`，由服务端解析 token（勿传 `amzAccessToken`，除非兼容旧调用）。转发上游 **GET**、**PATCH**、**PUT** 或 **DELETE**。\n\n| 操作 | 官方参考 |\n|------|----------|\n| 单条刊登 | [getListingsItem](https://developer-docs.amazon.com/sp-api/reference/getlistingsitem) |\n| 检索列表 | [searchListingsItems](https://developer-docs.amazon.com/sp-api/reference/searchlistingsitems) |\n| 部分更新刊登 | [patchListingsItem](https://developer-docs.amazon.com/sp-api/reference/patchlistingsitem) |\n| 创建 / 全量更新刊登 | [putListingsItem](https://developer-docs.amazon.com/sp-api/reference/putlistingsitem) |\n| 删除刊登 | [deleteListingsItem](https://developer-docs.amazon.com/sp-api/reference/deletelistingsitem) |\n| 刊登限制（ASIN） | [getListingsRestrictions](https://developer-docs.amazon.com/sp-api/reference/getlistingsrestrictions) |\n| 搜索 product type | [searchDefinitionsProductTypes](https://developer-docs.amazon.com/sp-api/reference/searchdefinitionsproducttypes) |\n| 获取 product type 定义 | [getDefinitionsProductType](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype) |\n\n---\n\n## 调用方式\n\n- **API 端点**：`POST /spApi/developerProxy`（不同操作通过请求体区分；完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/<脚本名>.py '<JSON 参数>' [--inline]`（可用脚本见上文脚本一览）\n- **成本约束**：本工具会消耗积分；失败/空结果不得自动换关键词、翻页或连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/<skill-name>-<timestamp>.json`（`<cwd>` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`<session>` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq`或`ConvertFrom-Json`或`ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用 references/onboarding.md 引导解决问题：\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n---\n\n## Prerequisites（必须先读）\n\n本 skill **依赖** **`linkfox-amazon-store-auth`**。流程与 `linkfox-amazon-store-report` 相同：\n\n1. 运行 `python scripts/check_auth_dependency.py`；若 exit code **42** 且 stderr 含 `DEPENDENCY_MISSING:`，请先安装 **`linkfox-amazon-store-auth`**。\n2. **不要**在本 skill 内绕过依赖实现授权或令牌逻辑。\n\n---\n\n## Current Capabilities\n\n| 能力 | Path 要点 | 脚本 |\n|------|-----------|------|\n| **获取单条 Listing** | `listings/2021-08-01/items/{sellerId}/{sku}` + Query | `scripts/get_listings_item.py` |\n| **搜索刊登列表** | `listings/2021-08-01/items/{sellerId}` + Query（**无**路径尾段 SKU） | `scripts/search_listings_items.py` |\n| **部分更新 Listing（PATCH）** | 同 **get** 路径 + Query + JSON body | `scripts/patch_listings_item.py` |\n| **创建 / 全量更新 Listing（PUT）** | 同 **get** 路径 + Query + body；**marketplaceIds 仅 1 个** | `scripts/put_listings_item.py` |\n| **删除 Listing（DELETE）** | 同 **get** 路径 + Query（**marketplaceIds 仅 1 个**） | `scripts/delete_listings_item.py` |\n| **刊登限制** | `listings/2021-08-01/restrictions` + Query（asin、sellerId、marketplaceIds 等） | `scripts/get_listings_restrictions.py` |\n| **搜索 Product Type** | `definitions/2020-09-01/productTypes` + Query | `scripts/search_definitions_product_types.py` |\n| **获取 Product Type 定义** | `definitions/2020-09-01/productTypes/{productType}` + Query；**marketplaceIds 仅 1 个** | `scripts/get_definitions_product_type.py` |\n\n**searchListingsItems** 下 `identifiers` / `variationParentSku` / `packageHierarchySku` **三者互斥**（仅该接口；见 **`references/api.md`**）。**searchDefinitionsProductTypes** 下 **`keywords`** 与 **`itemName`** **互斥**。\n\n---\n\n## Quick Parameters\n\n### getListingsItem（单条）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 已授权 Seller ID |\n| region | 是 | `NA` / `EU` / `FE` |\n| sku | 是 | **卖家 SKU**（非 ASIN） |\n| marketplaceIds | 是 | 建议仅 **一个** marketplace id |\n| includedData / issueLocale | 否 | 见 `references/api.md` |\n\n### searchListingsItems（列表）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 已授权 Seller ID |\n| region | 是 | `NA` / `EU` / `FE` |\n| marketplaceIds | 是 | 建议仅 **一个** marketplace id |\n| identifiers + identifiersType | 否 | 最多 **20** 个；与 `variationParentSku`、`packageHierarchySku` **不能同用** |\n| variationParentSku / packageHierarchySku | 否 | 与 identifiers **互斥** |\n| 时间窗 / 状态 / 排序 / 分页 | 否 | `createdAfter`、`lastUpdatedBefore`、`withStatus`、`sortBy`、`pageSize`（≤20）、`pageToken` 等，见 **`references/api.md`** |\n\n### patchListingsItem（部分更新）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 已授权 Seller ID |\n| region | 是 | `NA` / `EU` / `FE` |\n| sku | 是 | **卖家 SKU** |\n| marketplaceIds | 是 | 数组或逗号字符串；脚本拼入 Query |\n| productType | 是 | Amazon product type |\n| patches | 是 | **至少 1 条** JSON Patch（`op`、`path` 等） |\n| includedData / mode / issueLocale | 否 | 见 **`references/api.md`** |\n\n### putListingsItem（创建 / 全量更新）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 已授权 Seller ID |\n| region | 是 | `NA` / `EU` / `FE` |\n| sku | 是 | **卖家 SKU** |\n| marketplaceIds | 是 | **恰好一个** marketplace id |\n| productType | 是 | Amazon product type |\n| requirements | 是 | `LISTING` \\| `LISTING_PRODUCT_ONLY` \\| `LISTING_OFFER_ONLY` |\n| attributes | 是 | 须符合该 product type schema |\n| includedData / mode / issueLocale | 否 | 见 **`references/api.md`** |\n\n### deleteListingsItem（删除）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 已授权 Seller ID |\n| region | 是 | `NA` / `EU` / `FE` |\n| sku | 是 | **卖家 SKU** |\n| marketplaceIds | 是 | **恰好一个** marketplace id |\n| issueLocale | 否 | 见 **`references/api.md`** |\n\n### getListingsRestrictions\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 用于 `storeTokens` 与 Query |\n| region | 是 | `NA` / `EU` / `FE` |\n| asin | 是 | 目录 ASIN |\n| marketplaceIds | 是 | 数组或逗号字符串 |\n| conditionType / reasonLocale | 否 | 见 **`references/api.md`** |\n\n### searchDefinitionsProductTypes\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 用于 `storeTokens` |\n| region | 是 | `NA` / `EU` / `FE` |\n| marketplaceIds | 是 | 数组或逗号字符串 |\n| keywords **或** itemName | 否 | **二者不可同时传**（非空时互斥） |\n| locale / searchLocale | 否 | 见 **`references/api.md`** |\n\n### getDefinitionsProductType\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 用于 `storeTokens` |\n| region | 是 | `NA` / `EU` / `FE` |\n| productType | 是 | 如 `LUGGAGE`（写入 path） |\n| marketplaceIds | 是 | **恰好一个** id |\n| querySellerId | 否 | 若需上游 Query **`sellerId`**（卖家专属 schema），传入；常与 `sellerId` 相同 |\n| productTypeVersion / requirements / requirementsEnforced / locale | 否 | 见 **`references/api.md`** |\n\n---\n\n## Scripts\n\n- **`scripts/get_listings_item.py`** — 单条 listing。\n- **`scripts/search_listings_items.py`** — 搜索列表。\n- **`scripts/patch_listings_item.py`** — PATCH 部分更新。\n- **`scripts/put_listings_item.py`** — PUT 创建或全量更新。\n- **`scripts/delete_listings_item.py`** — DELETE 删除刊登。\n- **`scripts/get_listings_restrictions.py`** — GET 刊登限制。\n- **`scripts/search_definitions_product_types.py`** — GET 搜索 product type。\n- **`scripts/get_definitions_product_type.py`** — GET product type JSON Schema。\n- **`scripts/check_auth_dependency.py`** — 依赖检测。\n\n示例：\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<your-key>\"\n\npython scripts/get_listings_item.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"sku\":\"MY-SKU\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"]}'\n\npython scripts/search_listings_items.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"identifiers\":[\"B0XXXXXXXX\"],\"identifiersType\":\"ASIN\"}'\n\npython scripts/patch_listings_item.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"sku\":\"MY-SKU\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"productType\":\"LUGGAGE\",\"patches\":[{\"op\":\"replace\",\"path\":\"/attributes/item_name\",\"value\":[{\"value\":\"New Title\",\"marketplace_id\":\"ATVPDKIKX0DER\"}]}]}'\n\npython scripts/put_listings_item.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"sku\":\"MY-SKU\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"productType\":\"LUGGAGE\",\"requirements\":\"LISTING\",\"attributes\":{\"item_name\":[{\"value\":\"Title\",\"marketplace_id\":\"ATVPDKIKX0DER\"}]}}'\n\npython scripts/delete_listings_item.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"sku\":\"MY-SKU\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"]}'\n\npython scripts/get_listings_restrictions.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"asin\":\"B0XXXXXXXX\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"]}'\n\npython scripts/search_definitions_product_types.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"keywords\":[\"luggage\"]}'\n\npython scripts/get_definitions_product_type.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"productType\":\"LUGGAGE\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"querySellerId\":\"A1...\"}'\n```\n\n---\n\n## Display Rules\n\n1. **items** 类接口：路径含 **卖家 SKU** 时强调非 ASIN；**searchListingsItems** 路径仅到 `sellerId`。\n2. 展示网关结果时说明 **`errcode` / `httpStatus`**；成功后再解析 `body`（`listing` / `searchResult` / `patchResult` / `putResult` / `deleteResult` / **`restrictionsResult`** / **`productTypesSearchResult`** / **`productTypeDefinitionResult`**）。\n3. **searchListingsItems** 多页：从 `searchResult` 取下一页 token（字段名以 Amazon 响应为准），传入 `pageToken`。\n4. **restrictions** / **definitions** 路径与 **items** 不同；**1005** 时需为 **`listings/2021-08-01/restrictions`** 与 **`definitions/2020-09-01/productTypes`** 等前缀分别配置白名单（以运维为准）。\n5. **patch** / **put** / **delete** 为写操作；**delete** 须谨慎；**put** 为全量 **`attributes`**；**patch** 仅顶层属性可 patch（以官方为准）。\n\n---\n\n## Important Limitations\n\n- **marketplaceIds**：**get** / **searchListingsItems** 脚本对多 id 常仅取第一个；**put** / **delete** / **getDefinitionsProductType** 多于 1 个即报错；**patch**、**restrictions**、**searchDefinitionsProductTypes** 行为见 **`references/api.md`**。\n- **searchListingsItems**：`pageSize` **≤ 20**；`identifiers` **≤ 20**。\n- **patch**：`patches` 至少 1 条；JSON Patch 的 **`delete`** 与 **deleteListingsItem** 接口不同；Vendor 对部分 patch 可能 **400**。\n- **put**：**LISTING_OFFER_ONLY** 对 Vendor **400**。\n- **白名单**：`listings/.../items`、`listings/.../restrictions`、`definitions/2020-09-01/productTypes` 均须按需放行。\n\n## 积分消耗规则\n\n不消耗积分。\n\n**Feedback：** 见 `references/api.md` 中 Feedback API，`skillName`：`linkfox-amazon-store-listings`。\n\n---\n*更多跨境 skill：[LinkFox Skills](https://skill.linkfox.com/)*\n\nFile v1.0.7:_meta.json\n\n{\n  \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n  \"slug\": \"linkfox-amazon-store-listings\",\n  \"version\": \"1.0.7\",\n  \"publishedAt\": 1786718742653\n}\n\nFile v1.0.7:references/api.md\n\n# Amazon 店铺 Listings API 参考（Listings Items / Restrictions / Product Type Definitions）\n\n本文档描述通过 **LinkFox 店铺网关** 调用 Selling Partner API 中与刊登相关的接口：**Listings Items v2021-08-01**（`getListingsItem`、`searchListingsItems`、`patchListingsItem`、`putListingsItem`、`deleteListingsItem`）、**Listings Restrictions v2021-08-01**（`getListingsRestrictions`）、**Product Type Definitions v2020-09-01**（`searchDefinitionsProductTypes`、`getDefinitionsProductType`）。流程与 `linkfox-amazon-store-report` **完全一致**——先取店铺令牌，再经 **`POST /spApi/developerProxy`** 转发上游 HTTP。\n\n> 官方参考：[getListingsItem](https://developer-docs.amazon.com/sp-api/reference/getlistingsitem) · [searchListingsItems](https://developer-docs.amazon.com/sp-api/reference/searchlistingsitems) · [patchListingsItem](https://developer-docs.amazon.com/sp-api/reference/patchlistingsitem) · [putListingsItem](https://developer-docs.amazon.com/sp-api/reference/putlistingsitem) · [deleteListingsItem](https://developer-docs.amazon.com/sp-api/reference/deletelistingsitem) · [getListingsRestrictions](https://developer-docs.amazon.com/sp-api/reference/getlistingsrestrictions) · [searchDefinitionsProductTypes](https://developer-docs.amazon.com/sp-api/reference/searchdefinitionsproducttypes) · [getDefinitionsProductType](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype)（路径、Query、Body、响应以 Amazon 文档为准）。\n\n> ⚠️ **依赖**：调用前需已安装并完成授权流程 **`linkfox-amazon-store-auth`**（`/spApi/storeTokens` 等），参见本 skill 的 `SKILL.md`。\n\n---\n\n## 调用规范（与 store-report 相同）\n\n| 项 | 说明 |\n|----|------|\n| **Base URL** | `${LINKFOX_TOOL_GATEWAY}`（默认 `https://tool-gateway.linkfox.com`；可用 `STORE_API_BASE_URL` 或 `SPAPI_BASE_URL` 覆盖） |\n| **网关认证** | Header `Authorization: <api_key>`，环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY`（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理） |\n| **店铺令牌** | `POST /spApi/storeTokens`，Body：`{\"sellerId\":\"...\",\"region\":\"NA\\|EU\\|FE\"}` → `accessToken` |\n| **SP-API 转发** | `POST /spApi/developerProxy`，Body 见下节 |\n\n---\n\n## 通用接口：`POST /spApi/developerProxy`\n\n与 `linkfox-amazon-store-report` 的 `references/api.md` 中 **Developer Proxy** 定义相同。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| region | string | 是 | `NA` / `EU` / `FE`，须与店铺授权区域一致 |\n| path | string | 是 | **不含** SP-API 主机名前缀，仅 **资源路径**（见下文 Listings **items** / **restrictions**、**definitions/.../productTypes** 等模板） |\n| method | string | 是 | **`GET`**（读操作）、**`PATCH`**、**`PUT`** 或 **`DELETE`**（写操作） |\n| amzAccessToken | string | 是 | `/spApi/storeTokens` 返回的 `accessToken` |\n| queryString | string | 视操作 | **无 `?` 前缀**。各操作必填/可选 Query 见各节（**put** / **delete** / **getDefinitionsProductType** 的 `marketplaceIds` 等见官方 **length ≤ 1** 说明） |\n| body | string | 视操作 | **PATCH / PUT** 时 JSON 字符串。**GET** / **DELETE** 通常不传 |\n| contentType | string | 视操作 | **PATCH / PUT** 建议 **`application/json`**。**GET** / **DELETE** 通常省略 |\n\n**网关响应**（与报告 skill 一致）：\n\n```json\n{\n  \"errcode\": 200,\n  \"errmsg\": \"ok\",\n  \"httpStatus\": 200,\n  \"contentType\": \"application/json\",\n  \"body\": \"{... Amazon 返回的 JSON 字符串 ...}\"\n}\n```\n\n解析步骤：**先看 `errcode`**，再 **`httpStatus`**，最后将 **`body`** 做 `JSON.parse`。\n\n### 白名单与错误码\n\n- `path` 必须在后端 **`sp-api.developer-proxy.allowed-path-prefixes`** 白名单内。若 **`errcode=1005`**，需联系后端放行（常见前缀，以运维为准）：\n  - **`listings/2021-08-01/items`**：`get` / `patch` / `put` / `delete` 为 `.../items/{sellerId}/{sku}`，`searchListingsItems` 为 `.../items/{sellerId}`；\n  - **`listings/2021-08-01/restrictions`**：`getListingsRestrictions`（**无** path 变量，固定 `.../restrictions`）；\n  - **`definitions/2020-09-01/productTypes`**：`searchDefinitionsProductTypes` 与 **`getDefinitionsProductType`**（后者 path 含 **`/{productType}`** 段）。\n- 网关须允许 **`PATCH`**、**`PUT`**、**`DELETE`**（及已有 **GET**）转发。\n- 其它 **`errcode`** / **`httpStatus`** 含义与处置与 `linkfox-amazon-store-report` 的 `references/api.md` 中 **Error Codes** / **Developer Proxy 上游状态码** 表格一致（400 参数、403 令牌/权限、404 无此 SKU 等）。\n- HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。\n- HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。\n\n---\n\n## getListingsItem — 上游语义与网关映射\n\n### HTTP 与方法（Amazon）\n\n- **Method**：`GET`\n- **资源路径模板**（写入 `developerProxy.path`）：\n\n```text\nlistings/2021-08-01/items/{sellerId}/{sku}\n```\n\n其中 **`{sellerId}`**、**`{sku}`** 须做 **URL path 分段编码**（例如空格、`/` 等字符）；本仓库脚本使用百分号编码后拼入 `path`。\n\n> 说明：不同区域 SP-API **主机名**不同（na/eu/fe 等），由网关按 `region` + `amzAccessToken` 解析，调用方**只传相对 path** 即可。\n\n### Path 参数（写入 path 的占位段）\n\n| 名称 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| sellerId | string | 是 | 卖家标识，与已授权店铺一致（与 `/spApi/storeTokens` 所用 `sellerId` 相同） |\n| sku | string | 是 | **卖家自定义 SKU**（Seller SKU），不是 ASIN。须与 Listing 在目标站点下实际存在的 seller SKU 一致 |\n\n### Query 参数（写入 `developerProxy.queryString`，无 `?`）\n\n以下按 Amazon 文档整理；**键名大小写**须与官方一致。\n\n| 参数名 | 类型 | 必填 | 约束 / 说明 |\n|--------|------|------|----------------|\n| marketplaceIds | string | **是** | 目标 marketplace id。官方 schema 常见为 **单站点**（文档标注 length ≤ 1 时应只传 **一个** id）。多个 id 时本仓库脚本 **仅取第一个** 并打 stderr 警告。示例：`ATVPDKIKX0DER`（美国）。**Query 中写法**：`marketplaceIds=ATVPDKIKX0DER`（单值；若网关要求重复键名以官方为准，一般单站点即可） |\n| includedData | string | 否 | 逗号分隔数据集列表，控制响应中包含哪些块。**不传**时上游通常等价于默认 **`summaries`**（以实网为准）。可选值（与官方一致）：`summaries`、`attributes`、`issues`、`offers`、`fulfillmentAvailability`、`procurement`、`relationships`、`productTypes`。示例：`includedData=summaries,attributes` |\n| issueLocale | string | 否 | **issues** 等字段的本地化语言。示例：`en_US`、`fr_CA`。未传时通常使用第一个 marketplace 的默认语言；不可用回退行为以 Amazon 为准 |\n\n### 官方默认与速率（摘要）\n\n- **includedData** 默认集：文档为 **`summaries`**（若需结构化属性、报价、库存等，请在 `includedData` 中显式增加对应 token）。\n- **Usage plan（文档默认值）**：约 **5 req/s**，burst **10**（以响应头 `x-amzn-RateLimit-Limit` 及账号实际配额为准）。\n\n### 上游成功 / 常见错误（httpStatus）\n\n| httpStatus | 含义（摘要） |\n|------------|----------------|\n| 200 | 成功，`body` 为 Listing 详情 JSON |\n| 400 | Query / Path 非法或无法解析 |\n| 403 | 拒绝访问（令牌、签名、权限等） |\n| 404 | 指定 `sellerId`+`sku`+`marketplaceIds` 下无该 listing |\n| 413 | 请求过大 |\n| 415 | 不支持的媒体类型 |\n| 429 | 限流 |\n| 500 / 503 | 上游异常或维护 |\n\n---\n\n## 脚本参数映射（`scripts/get_listings_item.py`）\n\n| 脚本 JSON 字段 | 映射到 developerProxy |\n|----------------|-------------------------|\n| sellerId | 用于 `storeTokens`；并编码进 `path` 第一段 |\n| region | `region` |\n| sku | 编码进 `path` 第二段 |\n| marketplaceIds | `array[string]` 或单个 `string` → `queryString.marketplaceIds`（多元素时仅首元素） |\n| includedData | 可选，`array` 用逗号拼接 → `queryString.includedData` |\n| issueLocale | 可选 → `queryString.issueLocale` |\n\n脚本在 stdout 打印 JSON：含 `developerProxy` 原始包、`resolvedPath`、`queryString`；若 `errcode==200` 且 `httpStatus==200`，额外解析 `listing` 对象（`body` 的 JSON）。\n\n---\n\n## searchListingsItems — 上游语义与网关映射\n\n> 官方：[searchListingsItems](https://developer-docs.amazon.com/sp-api/reference/searchlistingsitems)\n\n### HTTP 与方法\n\n- **Method**：`GET`\n- **资源路径**（写入 `developerProxy.path`，仅含 `sellerId`，**无**路径尾段的 SKU）：\n\n```text\nlistings/2021-08-01/items/{sellerId}\n```\n\n`{sellerId}` 须 **URL 编码**（与 getListingsItem 相同约定）。\n\n### Path 参数\n\n| 名称 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| sellerId | string | 是 | 卖家标识，与已授权店铺及 `storeTokens` 一致 |\n\n### Query 参数（写入 `queryString`）\n\n| 参数名 | 类型 | 必填 | 约束 / 说明 |\n|--------|------|------|-------------|\n| marketplaceIds | string | **是** | 文档为 **length ≤ 1** 的 marketplace id 列表（逗号分隔语义）；本仓库脚本与 get 一致：**多传时仅取第一个** 并告警。示例：`ATVPDKIKX0DER` |\n| issueLocale | string | 否 | 本地化 issues 等，如 `en_US`、`fr_CA`；未传时行为以 Amazon 为准 |\n| includedData | string | 否 | 逗号分隔，默认文档为 **`summaries`**。可选：`summaries`、`attributes`、`issues`、`offers`、`fulfillmentAvailability`、`procurement`、`relationships`、`productTypes` |\n| identifiers | string | 条件 | **最多 20 个**商品标识，逗号分隔（脚本接受 JSON 数组，输出为逗号拼接）。**与 `identifiersType` 成对出现**：传了 identifiers 必须带 identifiersType，反之亦然 |\n| identifiersType | string | 条件 | 标识类型枚举：`SKU`、`ASIN`、`EAN`、`FNSKU`、`GTIN`、`ISBN`、`JAN`、`MINSAN`、`UPC`（以官方为准） |\n| variationParentSku | string | 条件 | 只返回该 **父 SKU** 下的变体子体。**禁止**与 `identifiers` / `packageHierarchySku` 同时使用 |\n| packageHierarchySku | string | 条件 | 返回包含或由该 SKU 构成的层级相关 listing。**禁止**与 `identifiers` / `variationParentSku` 同时使用 |\n| createdAfter | string | 否 | ISO 8601 **date-time**，筛选创建时间 ≥ 该时刻 |\n| createdBefore | string | 否 | ISO 8601，创建时间 ≤ 该时刻 |\n| lastUpdatedAfter | string | 否 | ISO 8601，最后更新时间 ≥ 该时刻 |\n| lastUpdatedBefore | string | 否 | ISO 8601，最后更新时间 ≤ 该时刻 |\n| withIssueSeverity | string | 否 | 逗号分隔；取值：`ERROR`、`WARNING`（仅包含有对应严重度 issue 的刊登） |\n| withStatus | string | 否 | 逗号分隔；取值：`BUYABLE`、`DISCOVERABLE`（文档注明 BUYABLE 不适用于 vendor listings） |\n| withoutStatus | string | 否 | 逗号分隔；同上枚举，表示 **排除** 含该状态的刊登 |\n| sortBy | string | 否 | 默认文档 **`lastUpdatedDate`**。允许：`sku`、`createdDate`、`lastUpdatedDate` |\n| sortOrder | string | 否 | 默认 **`DESC`**。允许：`ASC`、`DESC` |\n| pageSize | integer | 否 | 默认 **10**，**最大 20**（超出时脚本会截断为 20 并告警） |\n| pageToken | string | 否 | 下一页令牌（上一页响应中的分页字段，以 `body` JSON 为准） |\n\n### 互斥规则（官方 Note）\n\n以下 **不能混用**（本仓库 `search_listings_items.py` 会做校验）：\n\n1. 使用 **`identifiers` / `identifiersType`** 时，**不得**再传 `variationParentSku` 或 `packageHierarchySku`。\n2. 使用 **`variationParentSku`** 时，**不得**使用 `identifiers`（及 `identifiersType`）或 `packageHierarchySku`。\n3. 使用 **`packageHierarchySku`** 时，**不得**使用 `identifiers` 或 `variationParentSku`。\n4. **`variationParentSku`** 与 **`packageHierarchySku`** 亦不得同时使用。\n\n### 速率（文档摘要）\n\n- 默认约 **5 req/s**，burst **5**（以 `x-amzn-RateLimit-Limit` 与账号配额为准；与 getListingsItem 的 burst 可能不同）。\n\n### 成功响应\n\n- **`httpStatus=200`** 时，`body` 为 JSON 字符串，通常含 **列表 + 分页**（字段名以 Amazon 响应为准，常见含 `items`、`numberOfResults`、`pagination` 等）。\n\n---\n\n## 脚本参数映射（`scripts/search_listings_items.py`）\n\n| 脚本 JSON 字段 | 映射 |\n|----------------|------|\n| sellerId | `storeTokens` + path 编码 |\n| region | `region` |\n| marketplaceIds | 同 get；→ `marketplaceIds` |\n| issueLocale / includedData | → Query |\n| identifiers | `array` 或逗号字符串，≤20 个 → `identifiers` |\n| identifiersType | → `identifiersType` |\n| variationParentSku / packageHierarchySku | → 同名 Query |\n| createdAfter / createdBefore / lastUpdatedAfter / lastUpdatedBefore | → 同名 Query |\n| withIssueSeverity / withStatus / withoutStatus | `array` 或逗号字符串 → 逗号拼接 |\n| sortBy / sortOrder / pageSize / pageToken | → 同名 Query |\n\n成功且 `errcode==200`、`httpStatus==200` 时，脚本 stdout 中额外包含 **`searchResult`**（`body` 解析后的对象）。\n\n---\n\n## patchListingsItem — 上游语义与网关映射\n\n> 官方：[patchListingsItem](https://developer-docs.amazon.com/sp-api/reference/patchlistingsitem)\n\n仅支持对 **顶层** listing 属性做 JSON Patch；嵌套属性 patch 行为以 Amazon 文档为准。**Vendor** 场景下 **`delete`** 可能返回 **400**（官方说明）。\n\n### HTTP 与方法\n\n- **Method**：`PATCH`（经 `developerProxy.method` 传入 **`PATCH`**）\n- **Path**（与 getListingsItem 相同，含 **sellerId** 与 **卖家 SKU**）：\n\n```text\nlistings/2021-08-01/items/{sellerId}/{sku}\n```\n\n两段路径均需 **URL 编码**。\n\n### Query 参数（`queryString`）\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| marketplaceIds | string | **是** | 逗号分隔的 marketplace id 列表（脚本接受 JSON 数组并拼为逗号）。与 get 不同，patch 文档为 **列表**；多站点时一并传入 |\n| includedData | string | 否 | 逗号分隔；默认文档为 **`issues`**。可选：`identifiers`、`issues`。文档说明：**`identifiers`** 仅在 **`mode=VALIDATION_PREVIEW`** 时可请求 |\n| mode | string | 否 | 枚举：**`VALIDATION_PREVIEW`**（校验预览模式，与 `includedData=identifiers` 等组合以官方为准） |\n| issueLocale | string | 否 | 如 `en_US`、`fr_CA`；issues 本地化 |\n\n### Body（`developerProxy.body`，JSON 字符串）\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| productType | string | **是** | Amazon **product type**（如 `LUGGAGE`、`PRODUCT` 等，须与该 listing 在目录中的类型一致，以 [Product Type Definitions](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype) 为准） |\n| patches | array | **是** | **至少 1 条** [JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) 操作（Amazon 支持子集） |\n\n**单条 patch 对象**（`patches[]`）：\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| op | 是 | `add` \\| `replace` \\| `merge` \\| `delete` |\n| path | 是 | **JSON Pointer**，指向待修改属性（如 `/attributes/item_name`） |\n| value | 视 op | `add` / `replace` / `merge` 通常需要；`delete` 可无（Vendor 可能不支持 delete） |\n\n### 速率（文档摘要）\n\n- 默认约 **5 req/s**，burst **5**（以响应头与账号配额为准）。\n\n### 响应（httpStatus）\n\n- **200**：已理解 patch 请求；是否被接受须解析 **`body`** 内 issues / status（以 Amazon 响应 schema 为准）。\n- **400 / 403 / 413 / 415 / 429 / 500 / 503**：与通用 SP-API 语义一致。\n\n---\n\n## 脚本参数映射（`scripts/patch_listings_item.py`）\n\n| 脚本 JSON 字段 | 映射 |\n|----------------|------|\n| sellerId / region / sku | `storeTokens` + `path` 编码 |\n| marketplaceIds | 数组或逗号字符串 → `marketplaceIds`（Query，逗号拼接） |\n| productType / patches | → **PATCH body** |\n| includedData / mode / issueLocale | → Query |\n\n成功且 `errcode==200`、`httpStatus==200` 时，stdout 额外含 **`patchResult`**（解析后的 `body`）。\n\n---\n\n## putListingsItem — 上游语义与网关映射\n\n> 官方：[putListingsItem](https://developer-docs.amazon.com/sp-api/reference/putlistingsitem)\n\n**创建**新刊登或对现有刊登做**全量**更新（非部分 patch）；请求体为完整 **`attributes`** 对象，须符合该 **productType** 的 JSON Schema。\n\n### HTTP 与方法\n\n- **Method**：`PUT`（经 `developerProxy.method` 传入 **`PUT`**）\n- **Path**（与 getListingsItem / patchListingsItem 相同）：\n\n```text\nlistings/2021-08-01/items/{sellerId}/{sku}\n```\n\n两段路径均需 **URL 编码**。\n\n### Query 参数（`queryString`）\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| marketplaceIds | string | **是** | 官方约束：**length ≤ 1**（仅 **一个** marketplace id）。脚本在传入多个 id 时 **报错**（与 patch 允许多 id 不同） |\n| includedData | string | 否 | 逗号分隔；默认文档为 **`issues`**。可选：`identifiers`、`issues`。**`identifiers`** 仅在 **`mode=VALIDATION_PREVIEW`** 时可请求 |\n| mode | string | 否 | **`VALIDATION_PREVIEW`**（校验预览） |\n| issueLocale | string | 否 | issues 本地化，如 `en_US` |\n\n### Body（`developerProxy.body`，JSON 字符串）\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| productType | string | **是** | Amazon product type（与目录一致，参见 [Product Type Definitions](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype)） |\n| requirements | string | **是** | **`LISTING`**（商品事实 + 销售条款）\\| **`LISTING_PRODUCT_ONLY`**（仅商品事实）\\| **`LISTING_OFFER_ONLY`**（仅销售条款；**Vendor 不支持**，会 **400**） |\n| attributes | object | **是** | 以属性名为键的结构化刊登数据；须满足该 product type 的 schema |\n\n### 速率（文档摘要）\n\n- 默认约 **5 req/s**，burst **10**（以响应头与账号配额为准）。\n\n### 响应（httpStatus）\n\n- **200**：已理解创建/全量更新请求；是否被接受须解析 **`body`** 内 issues 等（以 Amazon 响应为准）。\n- **400 / 403 / 413 / 415 / 429 / 500 / 503**：与通用 SP-API 语义一致。\n\n---\n\n## 脚本参数映射（`scripts/put_listings_item.py`）\n\n| 脚本 JSON 字段 | 映射 |\n|----------------|------|\n| sellerId / region / sku | `storeTokens` + `path` 编码 |\n| marketplaceIds | 数组或逗号字符串 → **恰好 1 个** id 写入 Query（多于 1 个则脚本拒绝） |\n| productType / requirements / attributes | → **PUT body** |\n| includedData / mode / issueLocale | → Query |\n\n成功且 `errcode==200`、`httpStatus==200` 时，stdout 额外含 **`putResult`**（解析后的 `body`）。\n\n---\n\n## deleteListingsItem — 上游语义与网关映射\n\n> 官方：[deleteListingsItem](https://developer-docs.amazon.com/sp-api/reference/deletelistingsitem)\n\n删除指定 **marketplace** 下该 **sellerId + sku** 的刊登项；**无请求体**。\n\n### HTTP 与方法\n\n- **Method**：`DELETE`（经 `developerProxy.method` 传入 **`DELETE`**）\n- **Path**（与 get / patch / put 相同）：\n\n```text\nlistings/2021-08-01/items/{sellerId}/{sku}\n```\n\n两段路径均需 **URL 编码**。\n\n### Query 参数（`queryString`）\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| marketplaceIds | string | **是** | 官方约束：**length ≤ 1**（仅 **一个** marketplace id） |\n| issueLocale | string | 否 | 本地化，如 `en_US`、`fr_CA` |\n\n### 速率（文档摘要）\n\n- 默认约 **5 req/s**，burst **5**（以响应头与账号配额为准）。\n\n### 响应（httpStatus）\n\n- **200**：已理解删除请求；是否被接受须解析 **`body`**（以 Amazon 响应为准）。\n- **400 / 403 / 413 / 415 / 429 / 500 / 503**：与通用 SP-API 语义一致。\n\n---\n\n## 脚本参数映射（`scripts/delete_listings_item.py`）\n\n| 脚本 JSON 字段 | 映射 |\n|----------------|------|\n| sellerId / region / sku | `storeTokens` + `path` 编码 |\n| marketplaceIds | 数组或逗号字符串 → **恰好 1 个** id 写入 Query（多于 1 个则脚本拒绝） |\n| issueLocale | 否 → Query |\n\n成功且 `errcode==200`、`httpStatus==200` 时，stdout 额外含 **`deleteResult`**（解析后的 `body`）。\n\n---\n\n## getListingsRestrictions — 上游语义与网关映射\n\n> 官方：[getListingsRestrictions](https://developer-docs.amazon.com/sp-api/reference/getlistingsrestrictions)\n\n返回目录 **ASIN** 在指定 **sellerId** 与 **marketplaceIds** 下的刊登限制。\n\n### HTTP 与方法\n\n- **Method**：`GET`\n- **Path**（固定，无 path 参数）：\n\n```text\nlistings/2021-08-01/restrictions\n```\n\n### Query 参数（`queryString`）\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| asin | string | **是** | 目录 ASIN |\n| sellerId | string | **是** | 卖家标识（与 `storeTokens` 所用可一致） |\n| marketplaceIds | string | **是** | 逗号分隔 marketplace id 列表（脚本接受数组并拼接） |\n| conditionType | string | 否 | 商品状况枚举，用于过滤限制（如 `new`、`used_like_new` 等，以官方枚举为准） |\n| reasonLocale | string | 否 | 原因文案本地化，如 `en_US` |\n\n### 速率（文档摘要）\n\n- 默认约 **5 req/s**，burst **10**。\n\n### 响应\n\n- **200**：成功返回限制信息；**404** 等资源类错误以 Amazon 为准。\n\n---\n\n## 脚本参数映射（`scripts/get_listings_restrictions.py`）\n\n| 脚本 JSON 字段 | 映射 |\n|----------------|------|\n| sellerId / region | `storeTokens` |\n| asin / marketplaceIds / conditionType / reasonLocale | → Query |\n\n成功且 `errcode==200`、`httpStatus==200` 时，stdout 额外含 **`restrictionsResult`**。\n\n---\n\n## searchDefinitionsProductTypes — 上游语义与网关映射\n\n> 官方：[searchDefinitionsProductTypes](https://developer-docs.amazon.com/sp-api/reference/searchdefinitionsproducttypes)\n\n搜索可用的 **product type** 定义列表。\n\n### HTTP 与方法\n\n- **Method**：`GET`\n- **Path**：\n\n```text\ndefinitions/2020-09-01/productTypes\n```\n\n### Query 参数\n\n| 参数名 | 必填 | 说明 |\n|--------|------|------|\n| marketplaceIds | **是** | 逗号分隔（脚本接受数组） |\n| keywords | 否 | 逗号分隔关键词列表；**不可与** `itemName` **同用** |\n| itemName | 否 | ASIN 商品标题用于推荐 product type；**不可与** `keywords` **同用** |\n| locale / searchLocale | 否 | 展示语言、搜索所用 locale |\n\n### 速率（文档摘要）\n\n- 默认约 **5 req/s**，burst **10**。\n\n---\n\n## 脚本参数映射（`scripts/search_definitions_product_types.py`）\n\n| 脚本 JSON 字段 | 映射 |\n|----------------|------|\n| sellerId / region | `storeTokens` |\n| marketplaceIds | → Query |\n| keywords / itemName | → Query（**互斥**，脚本校验） |\n| locale / searchLocale | → Query |\n\n成功且 `errcode==200`、`httpStatus==200` 时，stdout 额外含 **`productTypesSearchResult`**。\n\n---\n\n## getDefinitionsProductType — 上游语义与网关映射\n\n> 官方：[getDefinitionsProductType](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype)\n\n按 **productType** 名称拉取 JSON Schema 定义。\n\n### HTTP 与方法\n\n- **Method**：`GET`\n- **Path**：\n\n```text\ndefinitions/2020-09-01/productTypes/{productType}\n```\n\n`{productType}` 须 **URL 编码**（脚本使用 `urllib.parse.quote`）。\n\n### Query 参数\n\n| 参数名 | 必填 | 说明 |\n|--------|------|------|\n| marketplaceIds | **是** | 官方说明当前 **limited to one** `marketplaceId`；脚本 **多于 1 个即报错** |\n| sellerId | 否 | 传入时填充卖家相关 schema；脚本字段 **`querySellerId`** → Query **`sellerId`**（避免与用于取令牌的 `sellerId` 混淆；通常可设为相同值） |\n| productTypeVersion | 否 | 默认 **`LATEST`**；预发布可用 **`RELEASE_CANDIDATE`**（以官方为准） |\n| requirements | 否 | `LISTING` \\| `LISTING_PRODUCT_ONLY` \\| `LISTING_OFFER_ONLY`（默认 **LISTING**） |\n| requirementsEnforced | 否 | `ENFORCED` \\| `NOT_ENFORCED` |\n| locale | 否 | 展示标签等所用 locale（官方枚举见文档） |\n\n### 速率（文档摘要）\n\n- 默认约 **5 req/s**，burst **10**。大 schema 响应体可能较大。\n\n---\n\n## 脚本参数映射（`scripts/get_definitions_product_type.py`）\n\n| 脚本 JSON 字段 | 映射 |\n|----------------|------|\n| sellerId / region | `storeTokens`（`sellerId` 为授权店铺） |\n| productType | → path 末段（编码） |\n| marketplaceIds | → Query，**恰好 1 个** id |\n| querySellerId | → Query `sellerId`（可选） |\n| productTypeVersion / requirements / requirementsEnforced / locale | → Query |\n\n成功且 `errcode==200`、`httpStatus==200` 时，stdout 额外含 **`productTypeDefinitionResult`**。\n\n---\n\n## curl 示例（两步：取令牌 + 代理 GET / PATCH / PUT / DELETE）\n\n**1）取 `accessToken`（与 store-report 相同）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/storeTokens\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"sellerId\":\"A1BCDEFGHIJK2\",\"region\":\"NA\"}'\n```\n\n**2）getListingsItem（path 与 query 按实际 sellerId / sku / marketplace 替换）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"listings/2021-08-01/items/A1BCDEFGHIJK2/My-Seller-SKU-001\",\n    \"method\": \"GET\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"marketplaceIds=ATVPDKIKX0DER&includedData=summaries,attributes\"\n  }'\n```\n\n> 若 `sku` 或 `sellerId` 含需编码字符，请使用与脚本一致的 **百分号编码** 后再放入 `path`。\n\n**3）searchListingsItems（path 仅到 `sellerId`，query 含 marketplaceIds 与分页等）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"listings/2021-08-01/items/A1BCDEFGHIJK2\",\n    \"method\": \"GET\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"marketplaceIds=ATVPDKIKX0DER&pageSize=10&sortBy=lastUpdatedDate&sortOrder=DESC&includedData=summaries\"\n  }'\n```\n\n按 ASIN 搜索时，在 `queryString` 中增加 `identifiers` 与 `identifiersType`（**勿与** `variationParentSku` / `packageHierarchySku` 同用），例如：`identifiers=B08N5WRWNW&identifiersType=ASIN`（示例 ASIN 请替换为真实值）。\n\n**4）patchListingsItem（`method` 为 `PATCH`，`body` 为 JSON 字符串；`productType` 与 `patches` 须按官方 schema 填写）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"listings/2021-08-01/items/A1BCDEFGHIJK2/My-Seller-SKU-001\",\n    \"method\": \"PATCH\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"marketplaceIds=ATVPDKIKX0DER&includedData=issues\",\n    \"contentType\": \"application/json\",\n    \"body\": \"{\\\"productType\\\":\\\"LUGGAGE\\\",\\\"patches\\\":[{\\\"op\\\":\\\"replace\\\",\\\"path\\\":\\\"/attributes/item_name\\\",\\\"value\\\":[{\\\"value\\\":\\\"Example\\\",\\\"marketplace_id\\\":\\\"ATVPDKIKX0DER\\\"}]}]}\"\n  }'\n```\n\n> 上例 **`body` 仅演示字段形态**；真实 `path` / `value` 必须与 **product type JSON Schema** 一致，否则会 **400**。\n\n**5）putListingsItem（`method` 为 `PUT`；`marketplaceIds` 在 Query 中仅 **一个** id；`body` 含 `productType`、`requirements`、`attributes`）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"listings/2021-08-01/items/A1BCDEFGHIJK2/My-Seller-SKU-001\",\n    \"method\": \"PUT\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"marketplaceIds=ATVPDKIKX0DER&includedData=issues\",\n    \"contentType\": \"application/json\",\n    \"body\": \"{\\\"productType\\\":\\\"LUGGAGE\\\",\\\"requirements\\\":\\\"LISTING\\\",\\\"attributes\\\":{\\\"item_name\\\":[{\\\"value\\\":\\\"Example Title\\\",\\\"marketplace_id\\\":\\\"ATVPDKIKX0DER\\\"}]}}\"\n  }'\n```\n\n> 上例 **`attributes` 仅演示键形态**；须与 **product type schema** 一致。**LISTING_OFFER_ONLY** 对 Vendor 会 **400**。\n\n**6）deleteListingsItem（`method` 为 `DELETE`；`queryString` 仅含 **一个** `marketplaceIds`；不传 `body`）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"listings/2021-08-01/items/A1BCDEFGHIJK2/My-Seller-SKU-001\",\n    \"method\": \"DELETE\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"marketplaceIds=ATVPDKIKX0DER\"\n  }'\n```\n\n**7）getListingsRestrictions（固定 path `listings/2021-08-01/restrictions`，Query 含 asin、sellerId、marketplaceIds）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"listings/2021-08-01/restrictions\",\n    \"method\": \"GET\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"asin=B08N5WRWNW&sellerId=A1BCDEFGHIJK2&marketplaceIds=ATVPDKIKX0DER\"\n  }'\n```\n\n**8）searchDefinitionsProductTypes（path `definitions/2020-09-01/productTypes`；`keywords` 与 `itemName` 勿同用）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"definitions/2020-09-01/productTypes\",\n    \"method\": \"GET\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"marketplaceIds=ATVPDKIKX0DER&keywords=luggage,suitcase\"\n  }'\n```\n\n**9）getDefinitionsProductType（path 末段为 product type 名称；`marketplaceIds` 仅一个）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"definitions/2020-09-01/productTypes/LUGGAGE\",\n    \"method\": \"GET\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"marketplaceIds=ATVPDKIKX0DER&requirements=LISTING&productTypeVersion=LATEST\"\n  }'\n```\n\n---\n\n## Feedback API\n\n- **POST** `https://skill-api.linkfox.com/api/v1/public/feedback`\n- **Content-Type:** `application/json`\n\n```json\n{\n  \"skillName\": \"linkfox-amazon-store-listings\",\n  \"sentiment\": \"POSITIVE\",\n  \"category\": \"OTHER\",\n  \"content\": \"getListingsItem / searchListingsItems / patchListingsItem / putListingsItem / deleteListingsItem / getListingsRestrictions / searchDefinitionsProductTypes / getDefinitionsProductType 结果符合预期。\"\n}\n```\n\nFile v1.0.7:references/onboarding.md\n\n# 解决认证和积分问题\n\n调用本 skill 时若网关返回 **auth** 或 **billing** 错误，走本 skill 自带的 `scripts/onboarding.py` 完成引导。\n\n**auth 场景**：`errcode=401` 或消息含 `authorized error`/`鉴权失败`/`未授权`/`unauthorized`；或 `LINKFOX_AGENT_API_KEY` 与 `LINKFOXAGENT_API_KEY` 均为空。\n1. 若已配置 key → 先让用户重启会话（最常见误判），仍失败让用户重新取 key 或换手机号重注册\n2. 未配置 → 询问：自助去 https://agent.linkfox.com/ 取 key，或提供手机号让脚本注册\n3. 手机号路径：\n   - `python scripts/onboarding.py send-code <phone>` → 展示 JSON 里的 phone/agreements\n   - 收到验证码后：`python scripts/onboarding.py login <phone> <code>`（workbuddy 宿主加 `--channel workbuddy`）\n   - 拿到 `api_key` 后把下面三平台配置转发给用户，提示重启会话生效：\n     - Windows PowerShell（永久）：`setx LINKFOX_AGENT_API_KEY \"<key>\"`\n     - macOS zsh：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.zshrc && source ~/.zshrc`\n     - Linux bash：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.bashrc && source ~/.bashrc`\n     - 变量名 `LINKFOX_AGENT_API_KEY`（主推）或 `LINKFOXAGENT_API_KEY`（老规范）任一即可\n\n**billing 场景**：`errcode=402` 或消息含 `积分/余额/quota/insufficient/充值/套餐到期`。\n- `python scripts/onboarding.py list-plans` → 有 AskUserQuestion 就弹菜单，否则输出编号清单让用户选\n- 校验 `plan_id` ∈ 清单、支付方式 ∈ 该套餐 `available_methods`（通常 `wechat/alipay`）\n- `python scripts/onboarding.py order <plan_id> <method>` → 展示优先级 PNG > `pay_url` > `ascii_qr`（标注兜底）\n- 已付款可选调 `python scripts/onboarding.py query <order_id>`，不主动轮询\n\n排除 `errcode=403`（无权限，不归入这两类）。所有子命令输出 stdout JSON，`error` 字段已含阶段前缀，透传给用户即可。完整用法：`python scripts/onboarding.py --help`。\n\nFile v1.0.7:skill-card.md\n\n## Description:\n\nHelps agents manage Amazon store listings through LinkFox by retrieving, searching, updating, creating, deleting listings, checking listing restrictions, and fetching product type definitions.\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 Amazon sellers, operators, and developers use this skill to inspect and manage Amazon listing data, validate listing restrictions, and obtain product type definitions before creating or changing listings.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can perform high-impact listing changes through PATCH, PUT, and DELETE operations.\n\nMitigation: Require explicit review of sellerId, SKU, marketplace, and payload before any agent-initiated write or delete action.\n\nRisk: Generated LinkFox response files may contain sensitive Amazon seller listing or account data.\n\nMitigation: Treat saved files under ./linkfox/ as sensitive business data and clean them up according to the user's data handling policy.\n\nRisk: Credentials and gateway configuration affect access to Amazon seller data and LinkFox account onboarding.\n\nMitigation: Use a dedicated, minimally scoped API key and leave gateway URL override environment variables unset unless the endpoint is trusted.\n\nRisk: Account and payment onboarding may be triggered for authentication or billing failures.\n\nMitigation: Review onboarding prompts before providing phone, payment, or account information.\n\n## Reference(s):\n\n- [Amazon Store Listings API Reference](artifact/references/api.md)\n- [Authentication and Billing Onboarding](artifact/references/onboarding.md)\n- [ClawHub Skill Page](https://clawhub.ai/linkfox-ai/skills/linkfox-amazon-store-listings)\n- [Amazon SP-API getListingsItem](https://developer-docs.amazon.com/sp-api/reference/getlistingsitem)\n- [Amazon SP-API searchListingsItems](https://developer-docs.amazon.com/sp-api/reference/searchlistingsitems)\n- [Amazon SP-API patchListingsItem](https://developer-docs.amazon.com/sp-api/reference/patchlistingsitem)\n- [Amazon SP-API putListingsItem](https://developer-docs.amazon.com/sp-api/reference/putlistingsitem)\n- [Amazon SP-API deleteListingsItem](https://developer-docs.amazon.com/sp-api/reference/deletelistingsitem)\n- [Amazon SP-API getListingsRestrictions](https://developer-docs.amazon.com/sp-api/reference/getlistingsrestrictions)\n- [Amazon SP-API searchDefinitionsProductTypes](https://developer-docs.amazon.com/sp-api/reference/searchdefinitionsproducttypes)\n- [Amazon SP-API getDefinitionsProductType](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, JSON, files, guidance]\n\n**Output Format:** [Markdown guidance with shell commands, JSON stdout, and saved JSON response files]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Scripts save full responses under ./linkfox/<date>/<session>/data/ and summarize responses larger than 8 KB unless --inline is used.]\n\n## Skill Version(s):\n\n1.0.7 (source: server release evidence)\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.0.6: 16 files, 58088 bytes\n\nFiles: references/api.md (31624b), references/onboarding.md (2046b), scripts/_spapi_listings_common.py (6542b), scripts/check_auth_dependency.py (10349b), scripts/delete_listings_item.py (7241b), scripts/get_definitions_product_type.py (8267b), scripts/get_listings_item.py (8221b), scripts/get_listings_restrictions.py (7285b), scripts/onboarding.py (24089b), scripts/patch_listings_item.py (9064b), scripts/put_listings_item.py (8972b), scripts/search_definitions_product_types.py (8215b), scripts/search_listings_items.py (12369b), skill-card.md (3330b), SKILL.md (13250b), _meta.json (148b)\n\nFile v1.0.6:SKILL.md\n\n---\nname: linkfox-amazon-store-listings\ndescription: 亚马逊店铺 Listing 与刊登相关定义/限制（与 linkfox-amazon-store-auth / linkfox-amazon-store-report 同系列），经 LinkFox /spApi/developerProxy 调用 SP-API：Listings Items（get/search/patch/put/delete）、Listings Restrictions（getListingsRestrictions）、Product Type Definitions（searchDefinitionsProductTypes、getDefinitionsProductType）。当用户提到获取或删除 Listing、刊登限制、ASIN 能否卖、product type 定义、JSON Schema 刊登属性、searchDefinitionsProductTypes、getDefinitionsProductType、getListingsRestrictions、Listings Restrictions、亚马逊刊登列表 时触发。\n---\n\n# Amazon 店铺 Listings 与相关 API\n\n本 skill 与 **`linkfox-amazon-store-auth`**、**`linkfox-amazon-store-report`** 同属 **Amazon Store** 系列：依赖 **`linkfox-amazon-store-auth`** 选店（`sellerId`+`region`）；直接 **`POST /spApi/developerProxy`** 传入 `sellerId`+`region`，由服务端解析 token（勿传 `amzAccessToken`，除非兼容旧调用）。转发上游 **GET**、**PATCH**、**PUT** 或 **DELETE**。\n\n| 操作 | 官方参考 |\n|------|----------|\n| 单条刊登 | [getListingsItem](https://developer-docs.amazon.com/sp-api/reference/getlistingsitem) |\n| 检索列表 | [searchListingsItems](https://developer-docs.amazon.com/sp-api/reference/searchlistingsitems) |\n| 部分更新刊登 | [patchListingsItem](https://developer-docs.amazon.com/sp-api/reference/patchlistingsitem) |\n| 创建 / 全量更新刊登 | [putListingsItem](https://developer-docs.amazon.com/sp-api/reference/putlistingsitem) |\n| 删除刊登 | [deleteListingsItem](https://developer-docs.amazon.com/sp-api/reference/deletelistingsitem) |\n| 刊登限制（ASIN） | [getListingsRestrictions](https://developer-docs.amazon.com/sp-api/reference/getlistingsrestrictions) |\n| 搜索 product type | [searchDefinitionsProductTypes](https://developer-docs.amazon.com/sp-api/reference/searchdefinitionsproducttypes) |\n| 获取 product type 定义 | [getDefinitionsProductType](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype) |\n\n---\n\n## 调用方式\n\n- **API 端点**：`POST /spApi/developerProxy`（不同操作通过请求体区分；完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/<脚本名>.py '<JSON 参数>' [--inline]`（可用脚本见上文脚本一览）\n- **成本约束**：本工具会消耗积分；失败/空结果不得自动换关键词、翻页或连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/<skill-name>-<timestamp>.json`（`<cwd>` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`<session>` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq`或`ConvertFrom-Json`或`ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用 references/onboarding.md 引导解决问题：\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n---\n\n## Prerequisites（必须先读）\n\n本 skill **依赖** **`linkfox-amazon-store-auth`**。流程与 `linkfox-amazon-store-report` 相同：\n\n1. 运行 `python scripts/check_auth_dependency.py`；若 exit code **42** 且 stderr 含 `DEPENDENCY_MISSING:`，请先安装 **`linkfox-amazon-store-auth`**。\n2. **不要**在本 skill 内绕过依赖实现授权或令牌逻辑。\n\n---\n\n## Current Capabilities\n\n| 能力 | Path 要点 | 脚本 |\n|------|-----------|------|\n| **获取单条 Listing** | `listings/2021-08-01/items/{sellerId}/{sku}` + Query | `scripts/get_listings_item.py` |\n| **搜索刊登列表** | `listings/2021-08-01/items/{sellerId}` + Query（**无**路径尾段 SKU） | `scripts/search_listings_items.py` |\n| **部分更新 Listing（PATCH）** | 同 **get** 路径 + Query + JSON body | `scripts/patch_listings_item.py` |\n| **创建 / 全量更新 Listing（PUT）** | 同 **get** 路径 + Query + body；**marketplaceIds 仅 1 个** | `scripts/put_listings_item.py` |\n| **删除 Listing（DELETE）** | 同 **get** 路径 + Query（**marketplaceIds 仅 1 个**） | `scripts/delete_listings_item.py` |\n| **刊登限制** | `listings/2021-08-01/restrictions` + Query（asin、sellerId、marketplaceIds 等） | `scripts/get_listings_restrictions.py` |\n| **搜索 Product Type** | `definitions/2020-09-01/productTypes` + Query | `scripts/search_definitions_product_types.py` |\n| **获取 Product Type 定义** | `definitions/2020-09-01/productTypes/{productType}` + Query；**marketplaceIds 仅 1 个** | `scripts/get_definitions_product_type.py` |\n\n**searchListingsItems** 下 `identifiers` / `variationParentSku` / `packageHierarchySku` **三者互斥**（仅该接口；见 **`references/api.md`**）。**searchDefinitionsProductTypes** 下 **`keywords`** 与 **`itemName`** **互斥**。\n\n---\n\n## Quick Parameters\n\n### getListingsItem（单条）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 已授权 Seller ID |\n| region | 是 | `NA` / `EU` / `FE` |\n| sku | 是 | **卖家 SKU**（非 ASIN） |\n| marketplaceIds | 是 | 建议仅 **一个** marketplace id |\n| includedData / issueLocale | 否 | 见 `references/api.md` |\n\n### searchListingsItems（列表）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 已授权 Seller ID |\n| region | 是 | `NA` / `EU` / `FE` |\n| marketplaceIds | 是 | 建议仅 **一个** marketplace id |\n| identifiers + identifiersType | 否 | 最多 **20** 个；与 `variationParentSku`、`packageHierarchySku` **不能同用** |\n| variationParentSku / packageHierarchySku | 否 | 与 identifiers **互斥** |\n| 时间窗 / 状态 / 排序 / 分页 | 否 | `createdAfter`、`lastUpdatedBefore`、`withStatus`、`sortBy`、`pageSize`（≤20）、`pageToken` 等，见 **`references/api.md`** |\n\n### patchListingsItem（部分更新）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 已授权 Seller ID |\n| region | 是 | `NA` / `EU` / `FE` |\n| sku | 是 | **卖家 SKU** |\n| marketplaceIds | 是 | 数组或逗号字符串；脚本拼入 Query |\n| productType | 是 | Amazon product type |\n| patches | 是 | **至少 1 条** JSON Patch（`op`、`path` 等） |\n| includedData / mode / issueLocale | 否 | 见 **`references/api.md`** |\n\n### putListingsItem（创建 / 全量更新）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 已授权 Seller ID |\n| region | 是 | `NA` / `EU` / `FE` |\n| sku | 是 | **卖家 SKU** |\n| marketplaceIds | 是 | **恰好一个** marketplace id |\n| productType | 是 | Amazon product type |\n| requirements | 是 | `LISTING` \\| `LISTING_PRODUCT_ONLY` \\| `LISTING_OFFER_ONLY` |\n| attributes | 是 | 须符合该 product type schema |\n| includedData / mode / issueLocale | 否 | 见 **`references/api.md`** |\n\n### deleteListingsItem（删除）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 已授权 Seller ID |\n| region | 是 | `NA` / `EU` / `FE` |\n| sku | 是 | **卖家 SKU** |\n| marketplaceIds | 是 | **恰好一个** marketplace id |\n| issueLocale | 否 | 见 **`references/api.md`** |\n\n### getListingsRestrictions\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 用于 `storeTokens` 与 Query |\n| region | 是 | `NA` / `EU` / `FE` |\n| asin | 是 | 目录 ASIN |\n| marketplaceIds | 是 | 数组或逗号字符串 |\n| conditionType / reasonLocale | 否 | 见 **`references/api.md`** |\n\n### searchDefinitionsProductTypes\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 用于 `storeTokens` |\n| region | 是 | `NA` / `EU` / `FE` |\n| marketplaceIds | 是 | 数组或逗号字符串 |\n| keywords **或** itemName | 否 | **二者不可同时传**（非空时互斥） |\n| locale / searchLocale | 否 | 见 **`references/api.md`** |\n\n### getDefinitionsProductType\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 用于 `storeTokens` |\n| region | 是 | `NA` / `EU` / `FE` |\n| productType | 是 | 如 `LUGGAGE`（写入 path） |\n| marketplaceIds | 是 | **恰好一个** id |\n| querySellerId | 否 | 若需上游 Query **`sellerId`**（卖家专属 schema），传入；常与 `sellerId` 相同 |\n| productTypeVersion / requirements / requirementsEnforced / locale | 否 | 见 **`references/api.md`** |\n\n---\n\n## Scripts\n\n- **`scripts/get_listings_item.py`** — 单条 listing。\n- **`scripts/search_listings_items.py`** — 搜索列表。\n- **`scripts/patch_listings_item.py`** — PATCH 部分更新。\n- **`scripts/put_listings_item.py`** — PUT 创建或全量更新。\n- **`scripts/delete_listings_item.py`** — DELETE 删除刊登。\n- **`scripts/get_listings_restrictions.py`** — GET 刊登限制。\n- **`scripts/search_definitions_product_types.py`** — GET 搜索 product type。\n- **`scripts/get_definitions_product_type.py`** — GET product type JSON Schema。\n- **`scripts/check_auth_dependency.py`** — 依赖检测。\n\n示例：\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<your-key>\"\n\npython scripts/get_listings_item.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"sku\":\"MY-SKU\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"]}'\n\npython scripts/search_listings_items.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"identifiers\":[\"B0XXXXXXXX\"],\"identifiersType\":\"ASIN\"}'\n\npython scripts/patch_listings_item.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"sku\":\"MY-SKU\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"productType\":\"LUGGAGE\",\"patches\":[{\"op\":\"replace\",\"path\":\"/attributes/item_name\",\"value\":[{\"value\":\"New Title\",\"marketplace_id\":\"ATVPDKIKX0DER\"}]}]}'\n\npython scripts/put_listings_item.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"sku\":\"MY-SKU\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"productType\":\"LUGGAGE\",\"requirements\":\"LISTING\",\"attributes\":{\"item_name\":[{\"value\":\"Title\",\"marketplace_id\":\"ATVPDKIKX0DER\"}]}}'\n\npython scripts/delete_listings_item.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"sku\":\"MY-SKU\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"]}'\n\npython scripts/get_listings_restrictions.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"asin\":\"B0XXXXXXXX\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"]}'\n\npython scripts/search_definitions_product_types.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"keywords\":[\"luggage\"]}'\n\npython scripts/get_definitions_product_type.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"productType\":\"LUGGAGE\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"querySellerId\":\"A1...\"}'\n```\n\n---\n\n## Display Rules\n\n1. **items** 类接口：路径含 **卖家 SKU** 时强调非 ASIN；**searchListingsItems** 路径仅到 `sellerId`。\n2. 展示网关结果时说明 **`errcode` / `httpStatus`**；成功后再解析 `body`（`listing` / `searchResult` / `patchResult` / `putResult` / `deleteResult` / **`restrictionsResult`** / **`productTypesSearchResult`** / **`productTypeDefinitionResult`**）。\n3. **searchListingsItems** 多页：从 `searchResult` 取下一页 token（字段名以 Amazon 响应为准），传入 `pageToken`。\n4. **restrictions** / **definitions** 路径与 **items** 不同；**1005** 时需为 **`listings/2021-08-01/restrictions`** 与 **`definitions/2020-09-01/productTypes`** 等前缀分别配置白名单（以运维为准）。\n5. **patch** / **put** / **delete** 为写操作；**delete** 须谨慎；**put** 为全量 **`attributes`**；**patch** 仅顶层属性可 patch（以官方为准）。\n\n---\n\n## Important Limitations\n\n- **marketplaceIds**：**get** / **searchListingsItems** 脚本对多 id 常仅取第一个；**put** / **delete** / **getDefinitionsProductType** 多于 1 个即报错；**patch**、**restrictions**、**searchDefinitionsProductTypes** 行为见 **`references/api.md`**。\n- **searchListingsItems**：`pageSize` **≤ 20**；`identifiers` **≤ 20**。\n- **patch**：`patches` 至少 1 条；JSON Patch 的 **`delete`** 与 **deleteListingsItem** 接口不同；Vendor 对部分 patch 可能 **400**。\n- **put**：**LISTING_OFFER_ONLY** 对 Vendor **400**。\n- **白名单**：`listings/.../items`、`listings/.../restrictions`、`definitions/2020-09-01/productTypes` 均须按需放行。\n\n## 积分消耗规则\n\n不消耗积分。\n\n**Feedback：** 见 `references/api.md` 中 Feedback API，`skillName`：`linkfox-amazon-store-listings`。\n\n---\n*更多跨境 skill：[LinkFox Skills](https://skill.linkfox.com/)*\n\nFile v1.0.6:_meta.json\n\n{\n  \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n  \"slug\": \"linkfox-amazon-store-listings\",\n  \"version\": \"1.0.6\",\n  \"publishedAt\": 1786099338981\n}\n\nFile v1.0.6:references/api.md\n\n# Amazon 店铺 Listings API 参考（Listings Items / Restrictions / Product Type Definitions）\n\n本文档描述通过 **LinkFox 店铺网关** 调用 Selling Partner API 中与刊登相关的接口：**Listings Items v2021-08-01**（`getListingsItem`、`searchListingsItems`、`patchListingsItem`、`putListingsItem`、`deleteListingsItem`）、**Listings Restrictions v2021-08-01**（`getListingsRestrictions`）、**Product Type Definitions v2020-09-01**（`searchDefinitionsProductTypes`、`getDefinitionsProductType`）。流程与 `linkfox-amazon-store-report` **完全一致**——先取店铺令牌，再经 **`POST /spApi/developerProxy`** 转发上游 HTTP。\n\n> 官方参考：[getListingsItem](https://developer-docs.amazon.com/sp-api/reference/getlistingsitem) · [searchListingsItems](https://developer-docs.amazon.com/sp-api/reference/searchlistingsitems) · [patchListingsItem](https://developer-docs.amazon.com/sp-api/reference/patchlistingsitem) · [putListingsItem](https://developer-docs.amazon.com/sp-api/reference/putlistingsitem) · [deleteListingsItem](https://developer-docs.amazon.com/sp-api/reference/deletelistingsitem) · [getListingsRestrictions](https://developer-docs.amazon.com/sp-api/reference/getlistingsrestrictions) · [searchDefinitionsProductTypes](https://developer-docs.amazon.com/sp-api/reference/searchdefinitionsproducttypes) · [getDefinitionsProductType](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype)（路径、Query、Body、响应以 Amazon 文档为准）。\n\n> ⚠️ **依赖**：调用前需已安装并完成授权流程 **`linkfox-amazon-store-auth`**（`/spApi/storeTokens` 等），参见本 skill 的 `SKILL.md`。\n\n---\n\n## 调用规范（与 store-report 相同）\n\n| 项 | 说明 |\n|----|------|\n| **Base URL** | `${LINKFOX_TOOL_GATEWAY}`（默认 `https://tool-gateway.linkfox.com`；可用 `STORE_API_BASE_URL` 或 `SPAPI_BASE_URL` 覆盖） |\n| **网关认证** | Header `Authorization: <api_key>`，环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY`（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理） |\n| **店铺令牌** | `POST /spApi/storeTokens`，Body：`{\"sellerId\":\"...\",\"region\":\"NA\\|EU\\|FE\"}` → `accessToken` |\n| **SP-API 转发** | `POST /spApi/developerProxy`，Body 见下节 |\n\n---\n\n## 通用接口：`POST /spApi/developerProxy`\n\n与 `linkfox-amazon-store-report` 的 `references/api.md` 中 **Developer Proxy** 定义相同。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| region | string | 是 | `NA` / `EU` / `FE`，须与店铺授权区域一致 |\n| path | string | 是 | **不含** SP-API 主机名前缀，仅 **资源路径**（见下文 Listings **items** / **restrictions**、**definitions/.../productTypes** 等模板） |\n| method | string | 是 | **`GET`**（读操作）、**`PATCH`**、**`PUT`** 或 **`DELETE`**（写操作） |\n| amzAccessToken | string | 是 | `/spApi/storeTokens` 返回的 `accessToken` |\n| queryString | string | 视操作 | **无 `?` 前缀**。各操作必填/可选 Query 见各节（**put** / **delete** / **getDefinitionsProductType** 的 `marketplaceIds` 等见官方 **length ≤ 1** 说明） |\n| body | string | 视操作 | **PATCH / PUT** 时 JSON 字符串。**GET** / **DELETE** 通常不传 |\n| contentType | string | 视操作 | **PATCH / PUT** 建议 **`application/json`**。**GET** / **DELETE** 通常省略 |\n\n**网关响应**（与报告 skill 一致）：\n\n```json\n{\n  \"errcode\": 200,\n  \"errmsg\": \"ok\",\n  \"httpStatus\": 200,\n  \"contentType\": \"application/json\",\n  \"body\": \"{... Amazon 返回的 JSON 字符串 ...}\"\n}\n```\n\n解析步骤：**先看 `errcode`**，再 **`httpStatus`**，最后将 **`body`** 做 `JSON.parse`。\n\n### 白名单与错误码\n\n- `path` 必须在后端 **`sp-api.developer-proxy.allowed-path-prefixes`** 白名单内。若 **`errcode=1005`**，需联系后端放行（常见前缀，以运维为准）：\n  - **`listings/2021-08-01/items`**：`get` / `patch` / `put` / `delete` 为 `.../items/{sellerId}/{sku}`，`searchListingsItems` 为 `.../items/{sellerId}`；\n  - **`listings/2021-08-01/restrictions`**：`getListingsRestrictions`（**无** path 变量，固定 `.../restrictions`）；\n  - **`definitions/2020-09-01/productTypes`**：`searchDefinitionsProductTypes` 与 **`getDefinitionsProductType`**（后者 path 含 **`/{productType}`** 段）。\n- 网关须允许 **`PATCH`**、**`PUT`**、**`DELETE`**（及已有 **GET**）转发。\n- 其它 **`errcode`** / **`httpStatus`** 含义与处置与 `linkfox-amazon-store-report` 的 `references/api.md` 中 **Error Codes** / **Developer Proxy 上游状态码** 表格一致（400 参数、403 令牌/权限、404 无此 SKU 等）。\n- HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。\n- HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。\n\n---\n\n## getListingsItem — 上游语义与网关映射\n\n### HTTP 与方法（Amazon）\n\n- **Method**：`GET`\n- **资源路径模板**（写入 `developerProxy.path`）：\n\n```text\nlistings/2021-08-01/items/{sellerId}/{sku}\n```\n\n其中 **`{sellerId}`**、**`{sku}`** 须做 **URL path 分段编码**（例如空格、`/` 等字符）；本仓库脚本使用百分号编码后拼入 `path`。\n\n> 说明：不同区域 SP-API **主机名**不同（na/eu/fe 等），由网关按 `region` + `amzAccessToken` 解析，调用方**只传相对 path** 即可。\n\n### Path 参数（写入 path 的占位段）\n\n| 名称 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| sellerId | string | 是 | 卖家标识，与已授权店铺一致（与 `/spApi/storeTokens` 所用 `sellerId` 相同） |\n| sku | string | 是 | **卖家自定义 SKU**（Seller SKU），不是 ASIN。须与 Listing 在目标站点下实际存在的 seller SKU 一致 |\n\n### Query 参数（写入 `developerProxy.queryString`，无 `?`）\n\n以下按 Amazon 文档整理；**键名大小写**须与官方一致。\n\n| 参数名 | 类型 | 必填 | 约束 / 说明 |\n|--------|------|------|----------------|\n| marketplaceIds | string | **是** | 目标 marketplace id。官方 schema 常见为 **单站点**（文档标注 length ≤ 1 时应只传 **一个** id）。多个 id 时本仓库脚本 **仅取第一个** 并打 stderr 警告。示例：`ATVPDKIKX0DER`（美国）。**Query 中写法**：`marketplaceIds=ATVPDKIKX0DER`（单值；若网关要求重复键名以官方为准，一般单站点即可） |\n| includedData | string | 否 | 逗号分隔数据集列表，控制响应中包含哪些块。**不传**时上游通常等价于默认 **`summaries`**（以实网为准）。可选值（与官方一致）：`summaries`、`attributes`、`issues`、`offers`、`fulfillmentAvailability`、`procurement`、`relationships`、`productTypes`。示例：`includedData=summaries,attributes` |\n| issueLocale | string | 否 | **issues** 等字段的本地化语言。示例：`en_US`、`fr_CA`。未传时通常使用第一个 marketplace 的默认语言；不可用回退行为以 Amazon 为准 |\n\n### 官方默认与速率（摘要）\n\n- **includedData** 默认集：文档为 **`summaries`**（若需结构化属性、报价、库存等，请在 `includedData` 中显式增加对应 token）。\n- **Usage plan（文档默认值）**：约 **5 req/s**，burst **10**（以响应头 `x-amzn-RateLimit-Limit` 及账号实际配额为准）。\n\n### 上游成功 / 常见错误（httpStatus）\n\n| httpStatus | 含义（摘要） |\n|------------|----------------|\n| 200 | 成功，`body` 为 Listing 详情 JSON |\n| 400 | Query / Path 非法或无法解析 |\n| 403 | 拒绝访问（令牌、签名、权限等） |\n| 404 | 指定 `sellerId`+`sku`+`marketplaceIds` 下无该 listing |\n| 413 | 请求过大 |\n| 415 | 不支持的媒体类型 |\n| 429 | 限流 |\n| 500 / 503 | 上游异常或维护 |\n\n---\n\n## 脚本参数映射（`scripts/get_listings_item.py`）\n\n| 脚本 JSON 字段 | 映射到 developerProxy |\n|----------------|-------------------------|\n| sellerId | 用于 `storeTokens`；并编码进 `path` 第一段 |\n| region | `region` |\n| sku | 编码进 `path` 第二段 |\n| marketplaceIds | `array[string]` 或单个 `string` → `queryString.marketplaceIds`（多元素时仅首元素） |\n| includedData | 可选，`array` 用逗号拼接 → `queryString.includedData` |\n| issueLocale | 可选 → `queryString.issueLocale` |\n\n脚本在 stdout 打印 JSON：含 `developerProxy` 原始包、`resolvedPath`、`queryString`；若 `errcode==200` 且 `httpStatus==200`，额外解析 `listing` 对象（`body` 的 JSON）。\n\n---\n\n## searchListingsItems — 上游语义与网关映射\n\n> 官方：[searchListingsItems](https://developer-docs.amazon.com/sp-api/reference/searchlistingsitems)\n\n### HTTP 与方法\n\n- **Method**：`GET`\n- **资源路径**（写入 `developerProxy.path`，仅含 `sellerId`，**无**路径尾段的 SKU）：\n\n```text\nlistings/2021-08-01/items/{sellerId}\n```\n\n`{sellerId}` 须 **URL 编码**（与 getListingsItem 相同约定）。\n\n### Path 参数\n\n| 名称 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| sellerId | string | 是 | 卖家标识，与已授权店铺及 `storeTokens` 一致 |\n\n### Query 参数（写入 `queryString`）\n\n| 参数名 | 类型 | 必填 | 约束 / 说明 |\n|--------|------|------|-------------|\n| marketplaceIds | string | **是** | 文档为 **length ≤ 1** 的 marketplace id 列表（逗号分隔语义）；本仓库脚本与 get 一致：**多传时仅取第一个** 并告警。示例：`ATVPDKIKX0DER` |\n| issueLocale | string | 否 | 本地化 issues 等，如 `en_US`、`fr_CA`；未传时行为以 Amazon 为准 |\n| includedData | string | 否 | 逗号分隔，默认文档为 **`summaries`**。可选：`summaries`、`attributes`、`issues`、`offers`、`fulfillmentAvailability`、`procurement`、`relationships`、`productTypes` |\n| identifiers | string | 条件 | **最多 20 个**商品标识，逗号分隔（脚本接受 JSON 数组，输出为逗号拼接）。**与 `identifiersType` 成对出现**：传了 identifiers 必须带 identifiersType，反之亦然 |\n| identifiersType | string | 条件 | 标识类型枚举：`SKU`、`ASIN`、`EAN`、`FNSKU`、`GTIN`、`ISBN`、`JAN`、`MINSAN`、`UPC`（以官方为准） |\n| variationParentSku | string | 条件 | 只返回该 **父 SKU** 下的变体子体。**禁止**与 `identifiers` / `packageHierarchySku` 同时使用 |\n| packageHierarchySku | string | 条件 | 返回包含或由该 SKU 构成的层级相关 listing。**禁止**与 `identifiers` / `variationParentSku` 同时使用 |\n| createdAfter | string | 否 | ISO 8601 **date-time**，筛选创建时间 ≥ 该时刻 |\n| createdBefore | string | 否 | ISO 8601，创建时间 ≤ 该时刻 |\n| lastUpdatedAfter | string | 否 | ISO 8601，最后更新时间 ≥ 该时刻 |\n| lastUpdatedBefore | string | 否 | ISO 8601，最后更新时间 ≤ 该时刻 |\n| withIssueSeverity | string | 否 | 逗号分隔；取值：`ERROR`、`WARNING`（仅包含有对应严重度 issue 的刊登） |\n| withStatus | string | 否 | 逗号分隔；取值：`BUYABLE`、`DISCOVERABLE`（文档注明 BUYABLE 不适用于 vendor listings） |\n| withoutStatus | string | 否 | 逗号分隔；同上枚举，表示 **排除** 含该状态的刊登 |\n| sortBy | string | 否 | 默认文档 **`lastUpdatedDate`**。允许：`sku`、`createdDate`、`lastUpdatedDate` |\n| sortOrder | string | 否 | 默认 **`DESC`**。允许：`ASC`、`DESC` |\n| pageSize | integer | 否 | 默认 **10**，**最大 20**（超出时脚本会截断为 20 并告警） |\n| pageToken | string | 否 | 下一页令牌（上一页响应中的分页字段，以 `body` JSON 为准） |\n\n### 互斥规则（官方 Note）\n\n以下 **不能混用**（本仓库 `search_listings_items.py` 会做校验）：\n\n1. 使用 **`identifiers` / `identifiersType`** 时，**不得**再传 `variationParentSku` 或 `packageHierarchySku`。\n2. 使用 **`variationParentSku`** 时，**不得**使用 `identifiers`（及 `identifiersType`）或 `packageHierarchySku`。\n3. 使用 **`packageHierarchySku`** 时，**不得**使用 `identifiers` 或 `variationParentSku`。\n4. **`variationParentSku`** 与 **`packageHierarchySku`** 亦不得同时使用。\n\n### 速率（文档摘要）\n\n- 默认约 **5 req/s**，burst **5**（以 `x-amzn-RateLimit-Limit` 与账号配额为准；与 getListingsItem 的 burst 可能不同）。\n\n### 成功响应\n\n- **`httpStatus=200`** 时，`body` 为 JSON 字符串，通常含 **列表 + 分页**（字段名以 Amazon 响应为准，常见含 `items`、`numberOfResults`、`pagination` 等）。\n\n---\n\n## 脚本参数映射（`scripts/search_listings_items.py`）\n\n| 脚本 JSON 字段 | 映射 |\n|----------------|------|\n| sellerId | `storeTokens` + path 编码 |\n| region | `region` |\n| marketplaceIds | 同 get；→ `marketplaceIds` |\n| issueLocale / includedData | → Query |\n| identifiers | `array` 或逗号字符串，≤20 个 → `identifiers` |\n| identifiersType | → `identifiersType` |\n| variationParentSku / packageHierarchySku | → 同名 Query |\n| createdAfter / createdBefore / lastUpdatedAfter / lastUpdatedBefore | → 同名 Query |\n| withIssueSeverity / withStatus / withoutStatus | `array` 或逗号字符串 → 逗号拼接 |\n| sortBy / sortOrder / pageSize / pageToken | → 同名 Query |\n\n成功且 `errcode==200`、`httpStatus==200` 时，脚本 stdout 中额外包含 **`searchResult`**（`body` 解析后的对象）。\n\n---\n\n## patchListingsItem — 上游语义与网关映射\n\n> 官方：[patchListingsItem](https://developer-docs.amazon.com/sp-api/reference/patchlistingsitem)\n\n仅支持对 **顶层** listing 属性做 JSON Patch；嵌套属性 patch 行为以 Amazon 文档为准。**Vendor** 场景下 **`delete`** 可能返回 **400**（官方说明）。\n\n### HTTP 与方法\n\n- **Method**：`PATCH`（经 `developerProxy.method` 传入 **`PATCH`**）\n- **Path**（与 getListingsItem 相同，含 **sellerId** 与 **卖家 SKU**）：\n\n```text\nlistings/2021-08-01/items/{sellerId}/{sku}\n```\n\n两段路径均需 **URL 编码**。\n\n### Query 参数（`queryString`）\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| marketplaceIds | string | **是** | 逗号分隔的 marketplace id 列表（脚本接受 JSON 数组并拼为逗号）。与 get 不同，patch 文档为 **列表**；多站点时一并传入 |\n| includedData | string | 否 | 逗号分隔；默认文档为 **`issues`**。可选：`identifiers`、`issues`。文档说明：**`identifiers`** 仅在 **`mode=VALIDATION_PREVIEW`** 时可请求 |\n| mode | string | 否 | 枚举：**`VALIDATION_PREVIEW`**（校验预览模式，与 `includedData=identifiers` 等组合以官方为准） |\n| issueLocale | string | 否 | 如 `en_US`、`fr_CA`；issues 本地化 |\n\n### Body（`developerProxy.body`，JSON 字符串）\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| productType | string | **是** | Amazon **product type**（如 `LUGGAGE`、`PRODUCT` 等，须与该 listing 在目录中的类型一致，以 [Product Type Definitions](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype) 为准） |\n| patches | array | **是** | **至少 1 条** [JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) 操作（Amazon 支持子集） |\n\n**单条 patch 对象**（`patches[]`）：\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| op | 是 | `add` \\| `replace` \\| `merge` \\| `delete` |\n| path | 是 | **JSON Pointer**，指向待修改属性（如 `/attributes/item_name`） |\n| value | 视 op | `add` / `replace` / `merge` 通常需要；`delete` 可无（Vendor 可能不支持 delete） |\n\n### 速率（文档摘要）\n\n- 默认约 **5 req/s**，burst **5**（以响应头与账号配额为准）。\n\n### 响应（httpStatus）\n\n- **200**：已理解 patch 请求；是否被接受须解析 **`body`** 内 issues / status（以 Amazon 响应 schema 为准）。\n- **400 / 403 / 413 / 415 / 429 / 500 / 503**：与通用 SP-API 语义一致。\n\n---\n\n## 脚本参数映射（`scripts/patch_listings_item.py`）\n\n| 脚本 JSON 字段 | 映射 |\n|----------------|------|\n| sellerId / region / sku | `storeTokens` + `path` 编码 |\n| marketplaceIds | 数组或逗号字符串 → `marketplaceIds`（Query，逗号拼接） |\n| productType / patches | → **PATCH body** |\n| includedData / mode / issueLocale | → Query |\n\n成功且 `errcode==200`、`httpStatus==200` 时，stdout 额外含 **`patchResult`**（解析后的 `body`）。\n\n---\n\n## putListingsItem — 上游语义与网关映射\n\n> 官方：[putListingsItem](https://developer-docs.amazon.com/sp-api/reference/putlistingsitem)\n\n**创建**新刊登或对现有刊登做**全量**更新（非部分 patch）；请求体为完整 **`attributes`** 对象，须符合该 **productType** 的 JSON Schema。\n\n### HTTP 与方法\n\n- **Method**：`PUT`（经 `developerProxy.method` 传入 **`PUT`**）\n- **Path**（与 getListingsItem / patchListingsItem 相同）：\n\n```text\nlistings/2021-08-01/items/{sellerId}/{sku}\n```\n\n两段路径均需 **URL 编码**。\n\n### Query 参数（`queryString`）\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| marketplaceIds | string | **是** | 官方约束：**length ≤ 1**（仅 **一个** marketplace id）。脚本在传入多个 id 时 **报错**（与 patch 允许多 id 不同） |\n| includedData | string | 否 | 逗号分隔；默认文档为 **`issues`**。可选：`identifiers`、`issues`。**`identifiers`** 仅在 **`mode=VALIDATION_PREVIEW`** 时可请求 |\n| mode | string | 否 | **`VALIDATION_PREVIEW`**（校验预览） |\n| issueLocale | string | 否 | issues 本地化，如 `en_US` |\n\n### Body（`developerProxy.body`，JSON 字符串）\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| productType | string | **是** | Amazon product type（与目录一致，参见 [Product Type Definitions](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype)） |\n| requirements | string | **是** | **`LISTING`**（商品事实 + 销售条款）\\| **`LISTING_PRODUCT_ONLY`**（仅商品事实）\\| **`LISTING_OFFER_ONLY`**（仅销售条款；**Vendor 不支持**，会 **400**） |\n| attributes | object | **是** | 以属性名为键的结构化刊登数据；须满足该 product type 的 schema |\n\n### 速率（文档摘要）\n\n- 默认约 **5 req/s**，burst **10**（以响应头与账号配额为准）。\n\n### 响应（httpStatus）\n\n- **200**：已理解创建/全量更新请求；是否被接受须解析 **`body`** 内 issues 等（以 Amazon 响应为准）。\n- **400 / 403 / 413 / 415 / 429 / 500 / 503**：与通用 SP-API 语义一致。\n\n---\n\n## 脚本参数映射（`scripts/put_listings_item.py`）\n\n| 脚本 JSON 字段 | 映射 |\n|----------------|------|\n| sellerId / region / sku | `storeTokens` + `path` 编码 |\n| marketplaceIds | 数组或逗号字符串 → **恰好 1 个** id 写入 Query（多于 1 个则脚本拒绝） |\n| productType / requirements / attributes | → **PUT body** |\n| includedData / mode / issueLocale | → Query |\n\n成功且 `errcode==200`、`httpStatus==200` 时，stdout 额外含 **`putResult`**（解析后的 `body`）。\n\n---\n\n## deleteListingsItem — 上游语义与网关映射\n\n> 官方：[deleteListingsItem](https://developer-docs.amazon.com/sp-api/reference/deletelistingsitem)\n\n删除指定 **marketplace** 下该 **sellerId + sku** 的刊登项；**无请求体**。\n\n### HTTP 与方法\n\n- **Method**：`DELETE`（经 `developerProxy.method` 传入 **`DELETE`**）\n- **Path**（与 get / patch / put 相同）：\n\n```text\nlistings/2021-08-01/items/{sellerId}/{sku}\n```\n\n两段路径均需 **URL 编码**。\n\n### Query 参数（`queryString`）\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| marketplaceIds | string | **是** | 官方约束：**length ≤ 1**（仅 **一个** marketplace id） |\n| issueLocale | string | 否 | 本地化，如 `en_US`、`fr_CA` |\n\n### 速率（文档摘要）\n\n- 默认约 **5 req/s**，burst **5**（以响应头与账号配额为准）。\n\n### 响应（httpStatus）\n\n- **200**：已理解删除请求；是否被接受须解析 **`body`**（以 Amazon 响应为准）。\n- **400 / 403 / 413 / 415 / 429 / 500 / 503**：与通用 SP-API 语义一致。\n\n---\n\n## 脚本参数映射（`scripts/delete_listings_item.py`）\n\n| 脚本 JSON 字段 | 映射 |\n|----------------|------|\n| sellerId / region / sku | `storeTokens` + `path` 编码 |\n| marketplaceIds | 数组或逗号字符串 → **恰好 1 个** id 写入 Query（多于 1 个则脚本拒绝） |\n| issueLocale | 否 → Query |\n\n成功且 `errcode==200`、`httpStatus==200` 时，stdout 额外含 **`deleteResult`**（解析后的 `body`）。\n\n---\n\n## getListingsRestrictions — 上游语义与网关映射\n\n> 官方：[getListingsRestrictions](https://developer-docs.amazon.com/sp-api/reference/getlistingsrestrictions)\n\n返回目录 **ASIN** 在指定 **sellerId** 与 **marketplaceIds** 下的刊登限制。\n\n### HTTP 与方法\n\n- **Method**：`GET`\n- **Path**（固定，无 path 参数）：\n\n```text\nlistings/2021-08-01/restrictions\n```\n\n### Query 参数（`queryString`）\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| asin | string | **是** | 目录 ASIN |\n| sellerId | string | **是** | 卖家标识（与 `storeTokens` 所用可一致） |\n| marketplaceIds | string | **是** | 逗号分隔 marketplace id 列表（脚本接受数组并拼接） |\n| conditionType | string | 否 | 商品状况枚举，用于过滤限制（如 `new`、`used_like_new` 等，以官方枚举为准） |\n| reasonLocale | string | 否 | 原因文案本地化，如 `en_US` |\n\n### 速率（文档摘要）\n\n- 默认约 **5 req/s**，burst **10**。\n\n### 响应\n\n- **200**：成功返回限制信息；**404** 等资源类错误以 Amazon 为准。\n\n---\n\n## 脚本参数映射（`scripts/get_listings_restrictions.py`）\n\n| 脚本 JSON 字段 | 映射 |\n|----------------|------|\n| sellerId / region | `storeTokens` |\n| asin / marketplaceIds / conditionType / reasonLocale | → Query |\n\n成功且 `errcode==200`、`httpStatus==200` 时，stdout 额外含 **`restrictionsResult`**。\n\n---\n\n## searchDefinitionsProductTypes — 上游语义与网关映射\n\n> 官方：[searchDefinitionsProductTypes](https://developer-docs.amazon.com/sp-api/reference/searchdefinitionsproducttypes)\n\n搜索可用的 **product type** 定义列表。\n\n### HTTP 与方法\n\n- **Method**：`GET`\n- **Path**：\n\n```text\ndefinitions/2020-09-01/productTypes\n```\n\n### Query 参数\n\n| 参数名 | 必填 | 说明 |\n|--------|------|------|\n| marketplaceIds | **是** | 逗号分隔（脚本接受数组） |\n| keywords | 否 | 逗号分隔关键词列表；**不可与** `itemName` **同用** |\n| itemName | 否 | ASIN 商品标题用于推荐 product type；**不可与** `keywords` **同用** |\n| locale / searchLocale | 否 | 展示语言、搜索所用 locale |\n\n### 速率（文档摘要）\n\n- 默认约 **5 req/s**，burst **10**。\n\n---\n\n## 脚本参数映射（`scripts/search_definitions_product_types.py`）\n\n| 脚本 JSON 字段 | 映射 |\n|----------------|------|\n| sellerId / region | `storeTokens` |\n| marketplaceIds | → Query |\n| keywords / itemName | → Query（**互斥**，脚本校验） |\n| locale / searchLocale | → Query |\n\n成功且 `errcode==200`、`httpStatus==200` 时，stdout 额外含 **`productTypesSearchResult`**。\n\n---\n\n## getDefinitionsProductType — 上游语义与网关映射\n\n> 官方：[getDefinitionsProductType](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype)\n\n按 **productType** 名称拉取 JSON Schema 定义。\n\n### HTTP 与方法\n\n- **Method**：`GET`\n- **Path**：\n\n```text\ndefinitions/2020-09-01/productTypes/{productType}\n```\n\n`{productType}` 须 **URL 编码**（脚本使用 `urllib.parse.quote`）。\n\n### Query 参数\n\n| 参数名 | 必填 | 说明 |\n|--------|------|------|\n| marketplaceIds | **是** | 官方说明当前 **limited to one** `marketplaceId`；脚本 **多于 1 个即报错** |\n| sellerId | 否 | 传入时填充卖家相关 schema；脚本字段 **`querySellerId`** → Query **`sellerId`**（避免与用于取令牌的 `sellerId` 混淆；通常可设为相同值） |\n| productTypeVersion | 否 | 默认 **`LATEST`**；预发布可用 **`RELEASE_CANDIDATE`**（以官方为准） |\n| requirements | 否 | `LISTING` \\| `LISTING_PRODUCT_ONLY` \\| `LISTING_OFFER_ONLY`（默认 **LISTING**） |\n| requirementsEnforced | 否 | `ENFORCED` \\| `NOT_ENFORCED` |\n| locale | 否 | 展示标签等所用 locale（官方枚举见文档） |\n\n### 速率（文档摘要）\n\n- 默认约 **5 req/s**，burst **10**。大 schema 响应体可能较大。\n\n---\n\n## 脚本参数映射（`scripts/get_definitions_product_type.py`）\n\n| 脚本 JSON 字段 | 映射 |\n|----------------|------|\n| sellerId / region | `storeTokens`（`sellerId` 为授权店铺） |\n| productType | → path 末段（编码） |\n| marketplaceIds | → Query，**恰好 1 个** id |\n| querySellerId | → Query `sellerId`（可选） |\n| productTypeVersion / requirements / requirementsEnforced / locale | → Query |\n\n成功且 `errcode==200`、`httpStatus==200` 时，stdout 额外含 **`productTypeDefinitionResult`**。\n\n---\n\n## curl 示例（两步：取令牌 + 代理 GET / PATCH / PUT / DELETE）\n\n**1）取 `accessToken`（与 store-report 相同）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/storeTokens\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"sellerId\":\"A1BCDEFGHIJK2\",\"region\":\"NA\"}'\n```\n\n**2）getListingsItem（path 与 query 按实际 sellerId / sku / marketplace 替换）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"listings/2021-08-01/items/A1BCDEFGHIJK2/My-Seller-SKU-001\",\n    \"method\": \"GET\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"marketplaceIds=ATVPDKIKX0DER&includedData=summaries,attributes\"\n  }'\n```\n\n> 若 `sku` 或 `sellerId` 含需编码字符，请使用与脚本一致的 **百分号编码** 后再放入 `path`。\n\n**3）searchListingsItems（path 仅到 `sellerId`，query 含 marketplaceIds 与分页等）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"listings/2021-08-01/items/A1BCDEFGHIJK2\",\n    \"method\": \"GET\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"marketplaceIds=ATVPDKIKX0DER&pageSize=10&sortBy=lastUpdatedDate&sortOrder=DESC&includedData=summaries\"\n  }'\n```\n\n按 ASIN 搜索时，在 `queryString` 中增加 `identifiers` 与 `identifiersType`（**勿与** `variationParentSku` / `packageHierarchySku` 同用），例如：`identifiers=B08N5WRWNW&identifiersType=ASIN`（示例 ASIN 请替换为真实值）。\n\n**4）patchListingsItem（`method` 为 `PATCH`，`body` 为 JSON 字符串；`productType` 与 `patches` 须按官方 schema 填写）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"listings/2021-08-01/items/A1BCDEFGHIJK2/My-Seller-SKU-001\",\n    \"method\": \"PATCH\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"marketplaceIds=ATVPDKIKX0DER&includedData=issues\",\n    \"contentType\": \"application/json\",\n    \"body\": \"{\\\"productType\\\":\\\"LUGGAGE\\\",\\\"patches\\\":[{\\\"op\\\":\\\"replace\\\",\\\"path\\\":\\\"/attributes/item_name\\\",\\\"value\\\":[{\\\"value\\\":\\\"Example\\\",\\\"marketplace_id\\\":\\\"ATVPDKIKX0DER\\\"}]}]}\"\n  }'\n```\n\n> 上例 **`body` 仅演示字段形态**；真实 `path` / `value` 必须与 **product type JSON Schema** 一致，否则会 **400**。\n\n**5）putListingsItem（`method` 为 `PUT`；`marketplaceIds` 在 Query 中仅 **一个** id；`body` 含 `productType`、`requirements`、`attributes`）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"listings/2021-08-01/items/A1BCDEFGHIJK2/My-Seller-SKU-001\",\n    \"method\": \"PUT\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"marketplaceIds=ATVPDKIKX0DER&includedData=issues\",\n    \"contentType\": \"application/json\",\n    \"body\": \"{\\\"productType\\\":\\\"LUGGAGE\\\",\\\"requirements\\\":\\\"LISTING\\\",\\\"attributes\\\":{\\\"item_name\\\":[{\\\"value\\\":\\\"Example Title\\\",\\\"marketplace_id\\\":\\\"ATVPDKIKX0DER\\\"}]}}\"\n  }'\n```\n\n> 上例 **`attributes` 仅演示键形态**；须与 **product type schema** 一致。**LISTING_OFFER_ONLY** 对 Vendor 会 **400**。\n\n**6）deleteListingsItem（`method` 为 `DELETE`；`queryString` 仅含 **一个** `marketplaceIds`；不传 `body`）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"listings/2021-08-01/items/A1BCDEFGHIJK2/My-Seller-SKU-001\",\n    \"method\": \"DELETE\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"marketplaceIds=ATVPDKIKX0DER\"\n  }'\n```\n\n**7）getListingsRestrictions（固定 path `listings/2021-08-01/restrictions`，Query 含 asin、sellerId、marketplaceIds）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"listings/2021-08-01/restrictions\",\n    \"method\": \"GET\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"asin=B08N5WRWNW&sellerId=A1BCDEFGHIJK2&marketplaceIds=ATVPDKIKX0DER\"\n  }'\n```\n\n**8）searchDefinitionsProductTypes（path `definitions/2020-09-01/productTypes`；`keywords` 与 `itemName` 勿同用）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"definitions/2020-09-01/productTypes\",\n    \"method\": \"GET\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"marketplaceIds=ATVPDKIKX0DER&keywords=luggage,suitcase\"\n  }'\n```\n\n**9）getDefinitionsProductType（path 末段为 product type 名称；`marketplaceIds` 仅一个）**\n\n```bash\ncurl -sS -X POST \"https://tool-gateway.linkfox.com/spApi/developerProxy\" \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"region\": \"NA\",\n    \"path\": \"definitions/2020-09-01/productTypes/LUGGAGE\",\n    \"method\": \"GET\",\n    \"amzAccessToken\": \"Atza|IwEBI...\",\n    \"queryString\": \"marketplaceIds=ATVPDKIKX0DER&requirements=LISTING&productTypeVersion=LATEST\"\n  }'\n```\n\n---\n\n## Feedback API\n\n- **POST** `https://skill-api.linkfox.com/api/v1/public/feedback`\n- **Content-Type:** `application/json`\n\n```json\n{\n  \"skillName\": \"linkfox-amazon-store-listings\",\n  \"sentiment\": \"POSITIVE\",\n  \"category\": \"OTHER\",\n  \"content\": \"getListingsItem / searchListingsItems / patchListingsItem / putListingsItem / deleteListingsItem / getListingsRestrictions / searchDefinitionsProductTypes / getDefinitionsProductType 结果符合预期。\"\n}\n```\n\nFile v1.0.6:references/onboarding.md\n\n# 解决认证和积分问题\n\n调用本 skill 时若网关返回 **auth** 或 **billing** 错误，走本 skill 自带的 `scripts/onboarding.py` 完成引导。\n\n**auth 场景**：`errcode=401` 或消息含 `authorized error`/`鉴权失败`/`未授权`/`unauthorized`；或 `LINKFOX_AGENT_API_KEY` 与 `LINKFOXAGENT_API_KEY` 均为空。\n1. 若已配置 key → 先让用户重启会话（最常见误判），仍失败让用户重新取 key 或换手机号重注册\n2. 未配置 → 询问：自助去 https://agent.linkfox.com/ 取 key，或提供手机号让脚本注册\n3. 手机号路径：\n   - `python scripts/onboarding.py send-code <phone>` → 展示 JSON 里的 phone/agreements\n   - 收到验证码后：`python scripts/onboarding.py login <phone> <code>`（workbuddy 宿主加 `--channel workbuddy`）\n   - 拿到 `api_key` 后把下面三平台配置转发给用户，提示重启会话生效：\n     - Windows PowerShell（永久）：`setx LINKFOX_AGENT_API_KEY \"<key>\"`\n     - macOS zsh：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.zshrc && source ~/.zshrc`\n     - Linux bash：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.bashrc && source ~/.bashrc`\n     - 变量名 `LINKFOX_AGENT_API_KEY`（主推）或 `LINKFOXAGENT_API_KEY`（老规范）任一即可\n\n**billing 场景**：`errcode=402` 或消息含 `积分/余额/quota/insufficient/充值/套餐到期`。\n- `python scripts/onboarding.py list-plans` → 有 AskUserQuestion 就弹菜单，否则输出编号清单让用户选\n- 校验 `plan_id` ∈ 清单、支付方式 ∈ 该套餐 `available_methods`（通常 `wechat/alipay`）\n- `python scripts/onboarding.py order <plan_id> <method>` → 展示优先级 PNG > `pay_url` > `ascii_qr`（标注兜底）\n- 已付款可选调 `python scripts/onboarding.py query <order_id>`，不主动轮询\n\n排除 `errcode=403`（无权限，不归入这两类）。所有子命令输出 stdout JSON，`error` 字段已含阶段前缀，透传给用户即可。完整用法：`python scripts/onboarding.py --help`。\n\nFile v1.0.6:skill-card.md\n\n## Description:\n\nThis skill helps agents manage Amazon store listings through LinkFox SP-API workflows, including listing retrieval, search, updates, deletion, listing restrictions, and product type definitions.\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 operators and developers managing Amazon seller workflows use this skill to retrieve, search, create, update, or delete listings, check ASIN listing restrictions, and inspect product type definitions through LinkFox-authorized SP-API calls.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can change or delete live Amazon listings.\n\nMitigation: Verify the SKU, marketplace, operation type, and request body before running PATCH, PUT, or DELETE commands.\n\nRisk: The skill can run LinkFox login and payment-related onboarding flows.\n\nMitigation: Use a dedicated LinkFox API key and confirm authentication or billing prompts before continuing.\n\nRisk: Full API responses are stored locally and may contain business-sensitive seller data.\n\nMitigation: Review and protect the local linkfox output directory, and avoid sharing saved response files unless they have been checked for sensitive data.\n\nRisk: Gateway URL environment variables can redirect requests to a different endpoint.\n\nMitigation: Override gateway URL variables only when you control and trust the destination endpoint.\n\n## Reference(s):\n\n- [ClawHub release page](https://clawhub.ai/linkfox-ai/skills/linkfox-amazon-store-listings)\n- [Amazon Listings API reference](references/api.md)\n- [Authentication and billing onboarding](references/onboarding.md)\n- [Amazon getListingsItem](https://developer-docs.amazon.com/sp-api/reference/getlistingsitem)\n- [Amazon searchListingsItems](https://developer-docs.amazon.com/sp-api/reference/searchlistingsitems)\n- [Amazon patchListingsItem](https://developer-docs.amazon.com/sp-api/reference/patchlistingsitem)\n- [Amazon putListingsItem](https://developer-docs.amazon.com/sp-api/reference/putlistingsitem)\n- [Amazon deleteListingsItem](https://developer-docs.amazon.com/sp-api/reference/deletelistingsitem)\n- [Amazon getListingsRestrictions](https://developer-docs.amazon.com/sp-api/reference/getlistingsrestrictions)\n- [Amazon searchDefinitionsProductTypes](https://developer-docs.amazon.com/sp-api/reference/searchdefinitionsproducttypes)\n- [Amazon getDefinitionsProductType](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype)\n\n## Skill Output:\n\n**Output Type(s):** [Text, JSON, Shell commands, Configuration, Guidance]\n\n**Output Format:** [Markdown guidance with shell command examples and JSON API responses saved to local files.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Scripts save full LinkFox responses under ./linkfox/<date>/<session>/data and may print summaries for responses larger than 8 KB.]\n\n## Skill Version(s):\n\n1.0.6 (source: server release evidence)\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.0.5: 14 files, 49631 bytes\n\nFiles: references/api.md (31624b), scripts/_spapi_listings_common.py (6542b), scripts/check_auth_dependency.py (10349b), scripts/delete_listings_item.py (7494b), scripts/get_definitions_product_type.py (8487b), scripts/get_listings_item.py (8474b), scripts/get_listings_restrictions.py (7505b), scripts/patch_listings_item.py (9317b), scripts/put_listings_item.py (9225b), scripts/search_definitions_product_types.py (8435b), scripts/search_listings_items.py (12622b), skill-card.md (3211b), SKILL.md (13742b), _meta.json (148b)\n\nFile v1.0.5:SKILL.md\n\n---\nname: linkfox-amazon-store-listings\ndescription: 亚马逊店铺 Listing 与刊登相关定义/限制（与 linkfox-amazon-store-auth / linkfox-amazon-store-report 同系列），经 LinkFox /spApi/developerProxy 调用 SP-API：Listings Items（get/search/patch/put/delete）、Listings Restrictions（getListingsRestrictions）、Product Type Definitions（searchDefinitionsProductTypes、getDefinitionsProductType）。当用户提到获取或删除 Listing、刊登限制、ASIN 能否卖、product type 定义、JSON Schema 刊登属性、searchDefinitionsProductTypes、getDefinitionsProductType、getListingsRestrictions、Listings Restrictions、亚马逊刊登列表 时触发。\n---\n\n# Amazon 店铺 Listings 与相关 API\n\n本 skill 与 **`linkfox-amazon-store-auth`**、**`linkfox-amazon-store-report`** 同属 **Amazon Store** 系列：使用 **`POST /spApi/storeTokens`** 取 `accessToken`，再经 **`POST /spApi/developerProxy`** 转发上游 **GET**、**PATCH**、**PUT** 或 **DELETE**。\n\n| 操作 | 官方参考 |\n|------|----------|\n| 单条刊登 | [getListingsItem](https://developer-docs.amazon.com/sp-api/reference/getlistingsitem) |\n| 检索列表 | [searchListingsItems](https://developer-docs.amazon.com/sp-api/reference/searchlistingsitems) |\n| 部分更新刊登 | [patchListingsItem](https://developer-docs.amazon.com/sp-api/reference/patchlistingsitem) |\n| 创建 / 全量更新刊登 | [putListingsItem](https://developer-docs.amazon.com/sp-api/reference/putlistingsitem) |\n| 删除刊登 | [deleteListingsItem](https://developer-docs.amazon.com/sp-api/reference/deletelistingsitem) |\n| 刊登限制（ASIN） | [getListingsRestrictions](https://developer-docs.amazon.com/sp-api/reference/getlistingsrestrictions) |\n| 搜索 product type | [searchDefinitionsProductTypes](https://developer-docs.amazon.com/sp-api/reference/searchdefinitionsproducttypes) |\n| 获取 product type 定义 | [getDefinitionsProductType](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype) |\n\n---\n\n## 调用方式\n\n- **API 端点**：`POST /spApi/developerProxy`（不同操作通过请求体区分；完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/<脚本名>.py '<JSON 参数>' [--inline]`（可用脚本见上文脚本一览）\n- **成本约束**：本工具会消耗积分；失败/空结果不得自动换关键词、翻页或连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/<skill-name>-<timestamp>.json`（`<cwd>` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`<session>` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq`或`ConvertFrom-Json`或`ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用以下措施来处理：\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n### 措施\n- 优先采用skill内的 onboarding.md 引导解决问题。\n- 如找不到 onboarding.md 文件，则加载 /linkfox-onboarding 这个skill并根据它的引导来处理。如未安装请先安装：\n    - 下载 https://agent-files.linkfox.com/skills/linkfox-onboarding/release.zip，解压后安装这个skill。如需用户授权才可下载，要询问用户获得授权，你不能自己放弃下载。\n- 兜底措施：仅当前面两个措施经过所有努力都走不通时，才提示用户依据 https://skill.linkfox.com/linkfoxskills/guide.htm 指引获取API Key，或去 https://os.linkfox.com/ 补充积分。\n\n---\n\n## Prerequisites（必须先读）\n\n本 skill **依赖** **`linkfox-amazon-store-auth`**。流程与 `linkfox-amazon-store-report` 相同：\n\n1. 运行 `python scripts/check_auth_dependency.py`；若 exit code **42** 且 stderr 含 `DEPENDENCY_MISSING:`，请先安装 **`linkfox-amazon-store-auth`**。\n2. **不要**在本 skill 内绕过依赖实现授权或令牌逻辑。\n\n---\n\n## Current Capabilities\n\n| 能力 | Path 要点 | 脚本 |\n|------|-----------|------|\n| **获取单条 Listing** | `listings/2021-08-01/items/{sellerId}/{sku}` + Query | `scripts/get_listings_item.py` |\n| **搜索刊登列表** | `listings/2021-08-01/items/{sellerId}` + Query（**无**路径尾段 SKU） | `scripts/search_listings_items.py` |\n| **部分更新 Listing（PATCH）** | 同 **get** 路径 + Query + JSON body | `scripts/patch_listings_item.py` |\n| **创建 / 全量更新 Listing（PUT）** | 同 **get** 路径 + Query + body；**marketplaceIds 仅 1 个** | `scripts/put_listings_item.py` |\n| **删除 Listing（DELETE）** | 同 **get** 路径 + Query（**marketplaceIds 仅 1 个**） | `scripts/delete_listings_item.py` |\n| **刊登限制** | `listings/2021-08-01/restrictions` + Query（asin、sellerId、marketplaceIds 等） | `scripts/get_listings_restrictions.py` |\n| **搜索 Product Type** | `definitions/2020-09-01/productTypes` + Query | `scripts/search_definitions_product_types.py` |\n| **获取 Product Type 定义** | `definitions/2020-09-01/productTypes/{productType}` + Query；**marketplaceIds 仅 1 个** | `scripts/get_definitions_product_type.py` |\n\n**searchListingsItems** 下 `identifiers` / `variationParentSku` / `packageHierarchySku` **三者互斥**（仅该接口；见 **`references/api.md`**）。**searchDefinitionsProductTypes** 下 **`keywords`** 与 **`itemName`** **互斥**。\n\n---\n\n## Quick Parameters\n\n### getListingsItem（单条）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 已授权 Seller ID |\n| region | 是 | `NA` / `EU` / `FE` |\n| sku | 是 | **卖家 SKU**（非 ASIN） |\n| marketplaceIds | 是 | 建议仅 **一个** marketplace id |\n| includedData / issueLocale | 否 | 见 `references/api.md` |\n\n### searchListingsItems（列表）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 已授权 Seller ID |\n| region | 是 | `NA` / `EU` / `FE` |\n| marketplaceIds | 是 | 建议仅 **一个** marketplace id |\n| identifiers + identifiersType | 否 | 最多 **20** 个；与 `variationParentSku`、`packageHierarchySku` **不能同用** |\n| variationParentSku / packageHierarchySku | 否 | 与 identifiers **互斥** |\n| 时间窗 / 状态 / 排序 / 分页 | 否 | `createdAfter`、`lastUpdatedBefore`、`withStatus`、`sortBy`、`pageSize`（≤20）、`pageToken` 等，见 **`references/api.md`** |\n\n### patchListingsItem（部分更新）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 已授权 Seller ID |\n| region | 是 | `NA` / `EU` / `FE` |\n| sku | 是 | **卖家 SKU** |\n| marketplaceIds | 是 | 数组或逗号字符串；脚本拼入 Query |\n| productType | 是 | Amazon product type |\n| patches | 是 | **至少 1 条** JSON Patch（`op`、`path` 等） |\n| includedData / mode / issueLocale | 否 | 见 **`references/api.md`** |\n\n### putListingsItem（创建 / 全量更新）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 已授权 Seller ID |\n| region | 是 | `NA` / `EU` / `FE` |\n| sku | 是 | **卖家 SKU** |\n| marketplaceIds | 是 | **恰好一个** marketplace id |\n| productType | 是 | Amazon product type |\n| requirements | 是 | `LISTING` \\| `LISTING_PRODUCT_ONLY` \\| `LISTING_OFFER_ONLY` |\n| attributes | 是 | 须符合该 product type schema |\n| includedData / mode / issueLocale | 否 | 见 **`references/api.md`** |\n\n### deleteListingsItem（删除）\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 已授权 Seller ID |\n| region | 是 | `NA` / `EU` / `FE` |\n| sku | 是 | **卖家 SKU** |\n| marketplaceIds | 是 | **恰好一个** marketplace id |\n| issueLocale | 否 | 见 **`references/api.md`** |\n\n### getListingsRestrictions\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 用于 `storeTokens` 与 Query |\n| region | 是 | `NA` / `EU` / `FE` |\n| asin | 是 | 目录 ASIN |\n| marketplaceIds | 是 | 数组或逗号字符串 |\n| conditionType / reasonLocale | 否 | 见 **`references/api.md`** |\n\n### searchDefinitionsProductTypes\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 用于 `storeTokens` |\n| region | 是 | `NA` / `EU` / `FE` |\n| marketplaceIds | 是 | 数组或逗号字符串 |\n| keywords **或** itemName | 否 | **二者不可同时传**（非空时互斥） |\n| locale / searchLocale | 否 | 见 **`references/api.md`** |\n\n### getDefinitionsProductType\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| sellerId | 是 | 用于 `storeTokens` |\n| region | 是 | `NA` / `EU` / `FE` |\n| productType | 是 | 如 `LUGGAGE`（写入 path） |\n| marketplaceIds | 是 | **恰好一个** id |\n| querySellerId | 否 | 若需上游 Query **`sellerId`**（卖家专属 schema），传入；常与 `sellerId` 相同 |\n| productTypeVersion / requirements / requirementsEnforced / locale | 否 | 见 **`references/api.md`** |\n\n---\n\n## Scripts\n\n- **`scripts/get_listings_item.py`** — 单条 listing。\n- **`scripts/search_listings_items.py`** — 搜索列表。\n- **`scripts/patch_listings_item.py`** — PATCH 部分更新。\n- **`scripts/put_listings_item.py`** — PUT 创建或全量更新。\n- **`scripts/delete_listings_item.py`** — DELETE 删除刊登。\n- **`scripts/get_listings_restrictions.py`** — GET 刊登限制。\n- **`scripts/search_definitions_product_types.py`** — GET 搜索 product type。\n- **`scripts/get_definitions_product_type.py`** — GET product type JSON Schema。\n- **`scripts/check_auth_dependency.py`** — 依赖检测。\n\n示例：\n\n```bash\nexport LINKFOXAGENT_API_KEY=\"<your-key>\"\n\npython scripts/get_listings_item.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"sku\":\"MY-SKU\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"]}'\n\npython scripts/search_listings_items.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"identifiers\":[\"B0XXXXXXXX\"],\"identifiersType\":\"ASIN\"}'\n\npython scripts/patch_listings_item.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"sku\":\"MY-SKU\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"productType\":\"LUGGAGE\",\"patches\":[{\"op\":\"replace\",\"path\":\"/attributes/item_name\",\"value\":[{\"value\":\"New Title\",\"marketplace_id\":\"ATVPDKIKX0DER\"}]}]}'\n\npython scripts/put_listings_item.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"sku\":\"MY-SKU\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"productType\":\"LUGGAGE\",\"requirements\":\"LISTING\",\"attributes\":{\"item_name\":[{\"value\":\"Title\",\"marketplace_id\":\"ATVPDKIKX0DER\"}]}}'\n\npython scripts/delete_listings_item.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"sku\":\"MY-SKU\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"]}'\n\npython scripts/get_listings_restrictions.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"asin\":\"B0XXXXXXXX\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"]}'\n\npython scripts/search_definitions_product_types.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"keywords\":[\"luggage\"]}'\n\npython scripts/get_definitions_product_type.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"productType\":\"LUGGAGE\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"querySellerId\":\"A1...\"}'\n```\n\n---\n\n## Display Rules\n\n1. **items** 类接口：路径含 **卖家 SKU** 时强调非 ASIN；**searchListingsItems** 路径仅到 `sellerId`。\n2. 展示网关结果时说明 **`errcode` / `httpStatus`**；成功后再解析 `body`（`listing` / `searchResult` / `patchResult` / `putResult` / `deleteResult` / **`restrictionsResult`** / **`productTypesSearchResult`** / **`productTypeDefinitionResult`**）。\n3. **searchListingsItems** 多页：从 `searchResult` 取下一页 token（字段名以 Amazon 响应为准），传入 `pageToken`。\n4. **restrictions** / **definitions** 路径与 **items** 不同；**1005** 时需为 **`listings/2021-08-01/restrictions`** 与 **`definitions/2020-09-01/productTypes`** 等前缀分别配置白名单（以运维为准）。\n5. **patch** / **put** / **delete** 为写操作；**delete** 须谨慎；**put** 为全量 **`attributes`**；**patch** 仅顶层属性可 patch（以官方为准）。\n\n---\n\n## Important Limitations\n\n- **marketplaceIds**：**get** / **searchListingsItems** 脚本对多 id 常仅取第一个；**put** / **delete** / **getDefinitionsProductType** 多于 1 个即报错；**patch**、**restrictions**、**searchDefinitionsProductTypes** 行为见 **`references/api.md`**。\n- **searchListingsItems**：`pageSize` **≤ 20**；`identifiers` **≤ 20**。\n- **patch**：`patches` 至少 1 条；JSON Patch 的 **`delete`** 与 **deleteListingsItem** 接口不同；Vendor 对部分 patch 可能 **400**。\n- **put**：**LISTING_OFFER_ONLY** 对 Vendor **400**。\n- **白名单**：`listings/.../items`、`listings/.../restrictions`、`definitions/2020-09-01/productTypes` 均须按需放行。\n\n## 积分消耗规则\n\n不消耗积分。\n\n**Feedback：** 见 `references/api.md` 中 Feedback API，`skillName`：`linkfox-amazon-store-listings`。\n\n---\n*更多跨境 skill：[LinkFox Skills](https://skill.linkfox.com/)*\n\nFile v1.0.5:_meta.json\n\n{\n  \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n  \"slug\": \"linkfox-amazon-store-listings\",\n  \"version\": \"1.0.5\",\n  \"publishedAt\": 1783944304393\n}\n\nFile v1.0.5:references/api.md\n\n# Amazon 店铺 Listings API 参考（Listings Items / Restrictions / Product Type Definitions）\n\n本文档描述通过 **LinkFox 店铺网关** 调用 Selling Partner API 中与刊登相关的接口：**Listings Items v2021-08-01**（`getListingsItem`、`searchListingsItems`、`patchListingsItem`、`putListingsItem`、`deleteListingsItem`）、**Listings Restrictions v2021-08-01**（`getListingsRestrictions`）、**Product Type Definitions v2020-09-01**（`searchDefinitionsProductTypes`、`getDefinitionsProductType`）。流程与 `linkfox-amazon-store-report` **完全一致**——先取店铺令牌，再经 **`POST /spApi/developerProxy`** 转发上游 HTTP。\n\n> 官方参考：[getListingsItem](https://developer-docs.amazon.com/sp-api/reference/getlistingsitem) · [searchListingsItems](https://developer-docs.amazon.com/sp-api/reference/searchlistingsitems) · [patchListingsItem](https://developer-docs.amazon.com/sp-api/reference/patchlistingsitem) · [putListingsItem](https://developer-docs.amazon.com/sp-api/reference/putlistingsitem) · [deleteListingsItem](https://developer-docs.amazon.com/sp-api/reference/deletelistingsitem) · [getListingsRestrictions](https://developer-docs.amazon.com/sp-api/reference/getlistingsrestrictions) · [searchDefinitionsProductTypes](https://developer-docs.amazon.com/sp-api/reference/searchdefinitionsproducttypes) · [getDefinitionsProductType](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype)（路径、Query、Body、响应以 Amazon 文档为准）。\n\n> ⚠️ **依赖**：调用前需已安装并完成授权流程 **`linkfox-amazon-store-auth`**（`/spApi/storeTokens` 等），参见本 skill 的 `SKILL.md`。\n\n---\n\n## 调用规范（与 store-report 相同）\n\n| 项 | 说明 |\n|----|------|\n| **Base URL** | `${LINKFOX_TOOL_GATEWAY}`（默认 `https://tool-gateway.linkfox.com`；可用 `STORE_API_BASE_URL` 或 `SPAPI_BASE_URL` 覆盖） |\n| **网关认证** | Header `Authorization: <api_key>`，环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY`（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理） |\n| **店铺令牌** | `POST /spApi/storeTokens`，Body：`{\"sellerId\":\"...\",\"region\":\"NA\\|EU\\|FE\"}` → `accessToken` |\n| **SP-API 转发** | `POST /spApi/developerProxy`，Body 见下节 |\n\n---\n\n## 通用接口：`POST /spApi/developerProxy`\n\n与 `linkfox-amazon-store-report` 的 `references/api.md` 中 **Developer Proxy** 定义相同。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| region | string | 是 | `NA` / `EU` / `FE`，须与店铺授权区域一致 |\n| path | string | 是 | **不含** SP-API 主机名前缀，仅 **资源路径**（见下文 Listings **items** / **restrictions**、**definitions/.../productTypes** 等模板） |\n| method | string | 是 | **`GET`**（读操作）、**`PATCH`**、**`PUT`** 或 **`DELETE`**（写操作） |\n| amzAccessToken | string | 是 | `/spApi/storeTokens` 返回的 `accessToken` |\n| queryString | string | 视操作 | **无 `?` 前缀**。各操作必填/可选 Query 见各节（**put** / **delete** / **getDefinitionsProductType** 的 `marketplaceIds` 等见官方 **length ≤ 1** 说明） |\n| body | string | 视操作 | **PATCH / PUT** 时 JSON 字符串。**GET** / **DELETE** 通常不传 |\n| contentType | string | 视操作 | **PATCH / PUT** 建议 **`application/json`**。**GET** / **DELETE** 通常省略 |\n\n**网关响应**（与报告 skill 一致）：\n\n```json\n{\n  \"errcode\": 200,\n  \"errmsg\": \"ok\",\n  \"httpStatus\": 200,\n  \"contentType\": \"application/json\",\n  \"body\": \"{... Amazon 返回的 JSON 字符串 ...}\"\n}\n```\n\n解析步骤：**先看 `errcode`**，再 **`httpStatus`**，最后将 **`body`** 做 `JSON.parse`。\n\n### 白名单与错误码\n\n- `path` 必须在后端 **`sp-api.developer-proxy.allowed-path-prefixes`** 白名单内。若 **`errcode=1005`**，需联系后端放行（常见前缀，以运维为准）：\n  - **`listings/2021-08-01/items`**：`get` / `patch` / `put` / `delete` 为 `.../items/{sellerId}/{sku}`，`searchListingsItems` 为 `.../items/{sellerId}`；\n  - **`listings/2021-08-01/restrictions`**：`getListingsRestrictions`（**无** path 变量，固定 `.../restrictions`）；\n  - **`definitions/2020-09-01/productTypes`**：`searchDefinitionsProductTypes` 与 **`getDefinitionsProductType`**（后者 path 含 **`/{productType}`** 段）。\n- 网关须允许 **`PATCH`**、**`PUT`**、**`DELETE`**（及已有 **GET**）转发。\n- 其它 **`errcode`** / **`httpStatus`** 含义与处置与 `linkfox-amazon-store-report` 的 `references/api.md` 中 **Error Codes** / **Developer Proxy 上游状态码** 表格一致（400 参数、403 令牌/权限、404 无此 SKU 等）。\n- HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。\n- HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。\n\n---\n\n## getListingsItem — 上游语义与网关映射\n\n### HTTP 与方法（Amazon）\n\n- **Method**：`GET`\n- **资源路径模板**（写入 `developerProxy.path`）：\n\n```text\nlistings/2021-08-01/items/{sellerId}/{sku}\n```\n\n其中 **`{sellerId}`**、**`{sku}`** 须做 **URL path 分段编码**（例如空格、`/` 等字符）；本仓库脚本使用百分号编码后拼入 `path`。\n\n> 说明：不同区域 SP-API **主机名**不同（na/eu/fe 等），由网关按 `region` + `amzAccessToken` 解析，调用方**只传相对 path** 即可。\n\n### Path 参数（写入 path 的占位段）\n\n| 名称 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| sellerId | string | 是 | 卖家标识，与已授权店铺一致（与 `/spApi/storeTokens` 所用 `sellerId` 相同） |\n| sku | string | 是 | **卖家自定义 SKU**（Seller SKU），不是 ASIN。须与 Listing 在目标站点下实际存在的 seller SKU 一致 |\n\n### Query 参数（写入 `developerProxy.queryString`，无 `?`）\n\n以下按 Amazon 文档整理；**键名大小写**须与官方一致。\n\n| 参数名 | 类型 | 必填 | 约束 / 说明 |\n|--------|------|------|----------------|\n| marketplaceIds | string | **是** | 目标 marketplace id。官方 schema 常见为 **单站点**（文档标注 length ≤ 1 时应只传 **一个** id）。多个 id 时本仓库脚本 **仅取第一个** 并打 stderr 警告。示例：`ATVPDKIKX0DER`（美国）。**Query 中写法**：`marketplaceIds=ATVPDKIKX0DER`（单值；若网关要求重复键名以官方为准，一般单站点即可） |\n| includedData | string | 否 | 逗号分隔数据集列表，控制响应中包含哪些块。**不传**时上游通常等价于默认 **`summaries`**（以实网为准）。可选值（与官方一致）：`summaries`、`attributes`、`issues`、`offers`、`fulfillmentAvailability`、`procurement`、`relationships`、`productTypes`。示例：`includedData=summaries,attributes` |\n| issueLocale | string | 否 | **issues** 等字段的本地化语言。示例：`en_US`、`fr_CA`。未传时通常使用第一个 marketplace 的默认语言；不可用回退行为以 Amazon 为准 |\n\n### 官方默认与速率（摘要）\n\n- **includedData** 默认集：文档为 **`summaries`**（若需结构化属性、报价、库存等，请在 `includedData` 中显式增加对应 token）。\n- **Usage plan（文档默认值）**：约 **5 req/s**，burst **10**（以响应头 `x-amzn-RateLimit-Limit` 及账号实际配额为准）。\n\n### 上游成功 / 常见错误（httpStatus）\n\n| httpStatus | 含义（摘要） |\n|------------|----------------|\n| 200 | 成功，`body` 为 Listing 详情 JSON |\n| 400 | Query / Path 非法或无法解析 |\n| 403 | 拒绝访问（令牌、签名、权限等） |\n| 404 | 指定 `sellerId`+`sku`+`marketplaceIds` 下无该 listing |\n| 413 | 请求过大 |\n| 415 | 不支持的媒体类型 |\n| 429 | 限流 |\n| 500 / 503 | 上游异常或维护 |\n\n---\n\n## 脚本参数映射（`scripts/get_listings_item.py`）\n\n| 脚本 JSON 字段 | 映射到 developerProxy |\n|----------------|-------------------------|\n| sellerId | 用于 `storeTokens`；并编码进 `path` 第一段 |\n| region | `region` |\n| sku | 编码进 `path` 第二段 |\n| marketplaceIds | `array[string]` 或单个 `string` → `queryString.marketplaceIds`（多元素时仅首元素） |\n| includedData | 可选，`array` 用逗号拼接 → `queryString.includedData` |\n| issueLocale | 可选 → `queryString.issueLocale` |\n\n脚本在 stdout 打印 JSON：含 `developerProxy` 原始包、`resolvedPath`、`queryString`；若 `errcode==200` 且 `httpStatus==200`，额外解析 `listing` 对象（`body` 的 JSON）。\n\n---\n\n## searchListingsItems — 上游语义与网关映射\n\n> 官方：[searchListingsItems](https://developer-docs.amazon.com/sp-api/reference/searchlistingsitems)\n\n### HTTP 与方法\n\n- **Method**：`GET`\n- **资源路径**（写入 `developerProxy.path`，仅含 `sellerId`，**无**路径尾段的 SKU）：\n\n```text\nlistings/2021-08-01/items/{sellerId}\n```\n\n`{sellerId}` 须 **URL 编码**（与 getListingsItem 相同约定）。\n\n### Path 参数\n\n| 名称 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| sellerId | string | 是 | 卖家标识，与已授权店铺及 `storeTokens` 一致 |\n\n### Query 参数（写入 `queryString`）\n\n| 参数名 | 类型 | 必\n\nArchive v1.0.4: 14 files, 48266 bytes\n\nFiles: references/api.md (31376b), scripts/_spapi_listings_common.py (6542b), scripts/check_auth_dependency.py (10349b), scripts/delete_listings_item.py (7407b), scripts/get_definitions_product_type.py (8400b), scripts/get_listings_item.py (8387b), scripts/get_listings_restrictions.py (7418b), scripts/patch_listings_item.py (9230b), scripts/put_listings_item.py (9138b), scripts/search_definitions_product_types.py (8348b), scripts/search_listings_items.py (12535b), skill-card.md (3241b), SKILL.md (12608b), _meta.json (148b)\n\nArchive v1.0.3: 13 files, 46846 bytes\n\nFiles: references/api.md (31376b), scripts/_spapi_listings_common.py (6542b), scripts/check_auth_dependency.py (10349b), scripts/delete_listings_item.py (7407b), scripts/get_definitions_product_type.py (8400b), scripts/get_listings_item.py (8387b), scripts/get_listings_restrictions.py (7418b), scripts/patch_listings_item.py (9230b), scripts/put_listings_item.py (9138b), scripts/search_definitions_product_types.py (8348b), scripts/search_listings_items.py (12535b), SKILL.md (12608b), _meta.json (148b)\n\nArchive v1.0.2: 13 files, 46754 bytes\n\nFiles: references/api.md (31377b), scripts/_spapi_listings_common.py (6542b), scripts/check_auth_dependency.py (10349b), scripts/delete_listings_item.py (7408b), scripts/get_definitions_product_type.py (8401b), scripts/get_listings_item.py (8388b), scripts/get_listings_restrictions.py (7419b), scripts/patch_listings_item.py (9231b), scripts/put_listings_item.py (9139b), scripts/search_definitions_product_types.py (8349b), scripts/search_listings_items.py (12536b), SKILL.md (12608b), _meta.json (148b)\n\nArchive v1.0.1: 14 files, 51467 bytes\n\nFiles: references/api.md (31307b), scripts/check_auth_dependency.py (10349b), scripts/delete_listings_item.py (7040b), scripts/get_definitions_product_type.py (8018b), scripts/get_listings_item.py (7999b), scripts/get_listings_restrictions.py (7058b), scripts/patch_listings_item.py (8822b), scripts/put_listings_item.py (8728b), scripts/response_io.py (18387b), scripts/search_definitions_product_types.py (7956b), scripts/search_listings_items.py (12052b), skill-card.md (3507b), SKILL.md (13063b), _meta.json (148b)\n\nArchive v0.0.1: 13 files, 43907 bytes\n\nFiles: references/api.md (31307b), scripts/check_auth_dependency.py (10349b), scripts/delete_listings_item.py (7040b), scripts/get_definitions_product_type.py (8018b), scripts/get_listings_item.py (7999b), scripts/get_listings_restrictions.py (7058b), scripts/patch_listings_item.py (8822b), scripts/put_listings_item.py (8728b), scripts/search_definitions_product_types.py (7956b), scripts/search_listings_items.py (12052b), skill-card.md (2773b), SKILL.md (11314b), _meta.json (148b)","readmeExcerpt":"Skill: 亚马逊-店铺Listing管理 Owner: linkfox-ai Summary: 亚马逊卖家 Listing 刊登与商品类型定义管理。用于按 SKU 查询或搜索 Listing，创建、全量更新、局部修改和删除刊登，检查 ASIN 刊登限制，并查询 product type 及其 JSON Schema 属性要求。用户提到亚马逊 Listing、刊登商品、修改商品信息、删除 Listing、卖家 SKU、ASIN 能否销售、刊登限制、product type、商品类型定义、JSON Schema、Listings Items、Listings Restrictions 时触发。即使未明确提及 API，只要希望管理卖家自己的商品刊登或确认上架所需字段与资格，也应触发此技能；查询亚马逊全站商品目录使用 linkfox-amazon-store-catalog，批量提交使用 linkfox-amazon-store-f","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"export LINKFOXAGENT_API_KEY=\"<your-key>\"\n\npython scripts/get_listings_item.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"sku\":\"MY-SKU\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"]}'\n\npython scripts/search_listings_items.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"identifiers\":[\"B0XXXXXXXX\"],\"identifiersType\":\"ASIN\"}'\n\npython scripts/patch_listings_item.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"sku\":\"MY-SKU\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"productType\":\"LUGGAGE\",\"patches\":[{\"op\":\"replace\",\"path\":\"/attributes/item_name\",\"value\":[{\"value\":\"New Title\",\"marketplace_id\":\"ATVPDKIKX0DER\"}]}]}'\n\npython scripts/put_listings_item.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"sku\":\"MY-SKU\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"productType\":\"LUGGAGE\",\"requirements\":\"LISTING\",\"attributes\":{\"item_name\":[{\"value\":\"Title\",\"marketplace_id\":\"ATVPDKIKX0DER\"}]}}'\n\npython scripts/delete_listings_item.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"sku\":\"MY-SKU\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"]}'\n\npython scripts/get_listings_restrictions.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"asin\":\"B0XXXXXXXX\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"]}'\n\npython scripts/search_definitions_product_types.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"keywords\":[\"luggage\"]}'\n\npython scripts/get_definitions_product_type.py '{\"sellerId\":\"A1...\",\"region\":\"NA\",\"productType\":\"LUGGAGE\",\"marketplaceIds\":[\"ATVPDKIKX0DER\"],\"querySellerId\":\"A1...\"}'"},{"language":"json","snippet":"{\n  \"errcode\": 200,\n  \"errmsg\": \"ok\",\n  \"httpStatus\": 200,\n  \"contentType\": \"application/json\",\n  \"body\": \"{... Amazon 返回的 JSON 字符串 ...}\"\n}"},{"language":"text","snippet":"listings/2021-08-01/items/{sellerId}/{sku}"},{"language":"text","snippet":"listings/2021-08-01/items/{sellerId}"},{"language":"text","snippet":"listings/2021-08-01/items/{sellerId}/{sku}"},{"language":"text","snippet":"listings/2021-08-01/items/{sellerId}/{sku}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: linkfox-amazon-store-listings\ndescription: 亚马逊卖家 Listing 刊登与商品类型定义管理。用于按 SKU 查询或搜索 Listing，创建、全量更新、局部修改和删除刊登，检查 ASIN 刊登限制，并查询 product type 及其 JSON Schema 属性要求。用户提到亚马逊 Listing、刊登商品、修改商品信息、删除 Listing、卖家 SKU、ASIN 能否销售、刊登限制、product type、商品类型定义、JSON Schema、Listings Items、Listings Restrictions 时触发。即使未明确提及 API，只要希望管理卖家自己的商品刊登或确认上架所需字段与资格，也应触发此技能；查询亚马逊全站商品目录使用 linkfox-amazon-store-catalog，批量提交使用 linkfox-amazon-store-feeds。\n---\n\n# Amazon 店铺 Listings 与相关 API\n\n本 skill 与 **`linkfox-amazon-store-auth`**、**`linkfox-amazon-store-report`** 同属 **Amazon Store** 系列：依赖 **`linkfox-amazon-store-auth`** 选店（`sellerId`+`region`）；直接 **`POST /spApi/developerProxy`** 传入 `sellerId`+`region`，由服务端解析 token（勿传 `amzAccessToken`，除非兼容旧调用）。转发上游 **GET**、**PATCH**、**PUT** 或 **DELETE**。\n\n| 操作 | 官方参考 |\n|------|----------|\n| 单条刊登 | [getListingsItem](https://developer-docs.amazon.com/sp-api/reference/getlistingsitem) |\n| 检索列表 | [searchListingsItems](https://developer-docs.amazon.com/sp-api/reference/searchlistingsitems) |\n| 部分更新刊登 | [patchListingsItem](https://developer-docs.amazon.com/sp-api/reference/patchlistingsitem) |\n| 创建 / 全量更新刊登 | [putListingsItem](https://developer-docs.amazon.com/sp-api/reference/putlistingsitem) |\n| 删除刊登 | [deleteListingsItem](https://developer-docs.amazon.com/sp-api/reference/deletelistingsitem) |\n| 刊登限制（ASIN） | [getListingsRestrictions](https://developer-docs.amazon.com/sp-api/reference/getlistingsrestrictions) |\n| 搜索 product type | [searchDefinitionsProductTypes](https://developer-docs.amazon.com/sp-api/reference/searchdefinitionsproducttypes) |\n| 获取 product type 定义 | [getDefinitionsProductType](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype) |\n\n---\n\n## 调用方式\n\n- **API 端点**：`POST /spApi/developerProxy`（不同操作通过请求体区分；完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/<脚本名>.py '<JSON 参数>' [--inline]`（可用脚本见上文脚本一览）\n- **成本约束**：本工具会消耗算力；失败/空结果不得自动换关键词、翻页或连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/<skill-name>-<timestamp>.json`（`<cwd>` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`<session>` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq`或`ConvertFrom-Json`或`ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 解决认证和算力问题\n发生以下异常情况时，采用 references/onboarding.md 引导解决问题：\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示算力或余额不足**：消息含\"算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n---\n\n## Prerequisites（必须先读）\n\n本 skill **依赖** **`linkfox-amazon-store-auth`**。流程与 `linkfox-amazon-store-report` 相同：\n\n1. 运行 `python scripts/check_auth_dependency.py`；若 exit code **42** 且 stderr 含 `DEPENDENCY_MISSING:`，请先安装 **`linkfox-amazon-store-auth`**。\n2. **不要**在本 skill 内绕过依赖实现授权或令牌逻辑。\n\n---\n\n## Curren"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n  \"slug\": \"linkfox-amazon-store-listings\",\n  \"version\": \"1.0.8\",\n  \"publishedAt\": 1789361875287\n}"},{"path":"references/api.md","content":"# Amazon 店铺 Listings API 参考（Listings Items / Restrictions / Product Type Definitions）\n\n本文档描述通过 **LinkFox 店铺网关** 调用 Selling Partner API 中与刊登相关的接口：**Listings Items v2021-08-01**（`getListingsItem`、`searchListingsItems`、`patchListingsItem`、`putListingsItem`、`deleteListingsItem`）、**Listings Restrictions v2021-08-01**（`getListingsRestrictions`）、**Product Type Definitions v2020-09-01**（`searchDefinitionsProductTypes`、`getDefinitionsProductType`）。流程与 `linkfox-amazon-store-report` **完全一致**——先取店铺令牌，再经 **`POST /spApi/developerProxy`** 转发上游 HTTP。\n\n> 官方参考：[getListingsItem](https://developer-docs.amazon.com/sp-api/reference/getlistingsitem) · [searchListingsItems](https://developer-docs.amazon.com/sp-api/reference/searchlistingsitems) · [patchListingsItem](https://developer-docs.amazon.com/sp-api/reference/patchlistingsitem) · [putListingsItem](https://developer-docs.amazon.com/sp-api/reference/putlistingsitem) · [deleteListingsItem](https://developer-docs.amazon.com/sp-api/reference/deletelistingsitem) · [getListingsRestrictions](https://developer-docs.amazon.com/sp-api/reference/getlistingsrestrictions) · [searchDefinitionsProductTypes](https://developer-docs.amazon.com/sp-api/reference/searchdefinitionsproducttypes) · [getDefinitionsProductType](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype)（路径、Query、Body、响应以 Amazon 文档为准）。\n\n> ⚠️ **依赖**：调用前需已安装并完成授权流程 **`linkfox-amazon-store-auth`**（`/spApi/storeTokens` 等），参见本 skill 的 `SKILL.md`。\n\n---\n\n## 调用规范（与 store-report 相同）\n\n| 项 | 说明 |\n|----|------|\n| **Base URL** | `${LINKFOX_TOOL_GATEWAY}`（默认 `https://tool-gateway.linkfox.com`；可用 `STORE_API_BASE_URL` 或 `SPAPI_BASE_URL` 覆盖） |\n| **网关认证** | Header `Authorization: <api_key>`，环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY`（如未配置 按 SKILL.md 的 **## 解决认证和算力问题** 处理） |\n| **店铺令牌** | `POST /spApi/storeTokens`，Body：`{\"sellerId\":\"...\",\"region\":\"NA\\|EU\\|FE\"}` → `accessToken` |\n| **SP-API 转发** | `POST /spApi/developerProxy`，Body 见下节 |\n\n---\n\n## 通用接口：`POST /spApi/developerProxy`\n\n与 `linkfox-amazon-store-report` 的 `references/api.md` 中 **Developer Proxy** 定义相同。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| region | string | 是 | `NA` / `EU` / `FE`，须与店铺授权区域一致 |\n| path | string | 是 | **不含** SP-API 主机名前缀，仅 **资源路径**（见下文 Listings **items** / **restrictions**、**definitions/.../productTypes** 等模板） |\n| method | string | 是 | **`GET`**（读操作）、**`PATCH`**、**`PUT`** 或 **`DELETE`**（写操作） |\n| amzAccessToken | string | 是 | `/spApi/storeTokens` 返回的 `accessToken` |\n| queryString | string | 视操作 | **无 `?` 前缀**。各操作必填/可选 Query 见各节（**put** / **delete** / **getDefinitionsProductType** 的 `marketplaceIds` 等见官方 **length ≤ 1** 说明） |\n| body | string | 视操作 | **PATCH / PUT** 时 JSON 字符串。**GET** / **DELETE** 通常不传 |\n| contentType | string | 视操作 | **PATCH / PUT** 建议 **`application/json`**。**GET** / **DELETE** 通常省略 |\n\n**网关响应**（与报告 skill 一致）：\n\n```json\n{\n  \"errcode\": 200,\n  \"errmsg\": \"ok\",\n  \"httpStatus\": 200,\n  \"contentType\": \"application/json\",\n  \"body\": \"{... Amazon 返回的 JSON 字符串 "},{"path":"references/onboarding.md","content":"# 解决认证和算力问题\n\n调用本 skill 时若网关返回 **auth** 或 **billing** 错误，走本 skill 自带的 `scripts/onboarding.py` 完成引导。\n\n**auth 场景**：`errcode=401` 或消息含 `authorized error`/`鉴权失败`/`未授权`/`unauthorized`；或 `LINKFOX_AGENT_API_KEY` 与 `LINKFOXAGENT_API_KEY` 均为空。\n1. 若已配置 key → 先让用户重启会话（最常见误判），仍失败让用户重新取 key 或换手机号重注册\n2. 未配置 → 询问：自助去 https://agent.linkfox.com/ 取 key，或提供手机号让脚本注册\n3. 手机号路径：\n   - `python scripts/onboarding.py send-code <phone>` → 展示 JSON 里的 phone/agreements\n   - 收到验证码后：`python scripts/onboarding.py login <phone> <code>`\n   - 拿到 `api_key` 后把下面三平台配置转发给用户，提示重启会话生效：\n     - Windows PowerShell（永久）：`setx LINKFOX_AGENT_API_KEY \"<key>\"`\n     - macOS zsh：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.zshrc && source ~/.zshrc`\n     - Linux bash：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.bashrc && source ~/.bashrc`\n     - 变量名 `LINKFOX_AGENT_API_KEY`（主推）或 `LINKFOXAGENT_API_KEY`（老规范）任一即可\n\n**billing 场景**：`errcode=402` 或消息含 `算力/余额/quota/insufficient/充值/套餐到期`。\n- `python scripts/onboarding.py list-plans` → 有 AskUserQuestion 就弹菜单，否则输出编号清单让用户选\n- 校验 `plan_id` ∈ 清单、支付方式 ∈ 该套餐 `available_methods`（通常 `wechat/alipay`）\n- `python scripts/onboarding.py order <plan_id> <method>` → 展示优先级 PNG > `pay_url` > `ascii_qr`（标注兜底）\n- 已付款可选调 `python scripts/onboarding.py query <order_id>`，不主动轮询\n\n排除 `errcode=403`（无权限，不归入这两类）。所有子命令输出 stdout JSON，`error` 字段已含阶段前缀，透传给用户即可。完整用法：`python scripts/onboarding.py --help`。"},{"path":"skill-card.md","content":"## Description:\n\n亚马逊卖家 Listing 刊登与商品类型定义管理，用于查询、搜索、创建、更新、局部修改和删除卖家 Listing，检查 ASIN 刊登限制，并查询 product type 及其 JSON Schema 属性要求。\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 Amazon sellers and their agents use this skill to manage seller-owned Listings through LinkFox and Amazon SP-API workflows. It supports Listing lookup, search, patch, put, delete, restrictions checks, and product type schema discovery.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can read and modify Amazon seller listings, including create, update, patch, and delete actions.\n\nMitigation: Require explicit human confirmation before patch, put, or delete operations, and verify sellerId, region, SKU, marketplaceIds, productType, and request body before execution.\n\nRisk: The skill can assist with LinkFox account login, API-key generation, billing, and payment/order flows.\n\nMitigation: Run only in a trusted environment, keep API keys out of shared logs, and require explicit user approval before login, API-key, payment, or order steps.\n\nRisk: Saved LinkFox response files may contain sensitive seller or listing data.\n\nMitigation: Review generated linkfox response files before sharing or committing them and apply local data handling controls for seller information.\n\nRisk: Custom LinkFox endpoint environment variables can redirect requests to a different destination.\n\nMitigation: Do not set custom LinkFox endpoint variables unless the destination is controlled and trusted.\n\n## Reference(s):\n\n- [Amazon 店铺 Listings API 参考](artifact/references/api.md)\n- [解决认证和算力问题](artifact/references/onboarding.md)\n- [getListingsItem](https://developer-docs.amazon.com/sp-api/reference/getlistingsitem)\n- [searchListingsItems](https://developer-docs.amazon.com/sp-api/reference/searchlistingsitems)\n- [patchListingsItem](https://developer-docs.amazon.com/sp-api/reference/patchlistingsitem)\n- [putListingsItem](https://developer-docs.amazon.com/sp-api/reference/putlistingsitem)\n- [deleteListingsItem](https://developer-docs.amazon.com/sp-api/reference/deletelistingsitem)\n- [getListingsRestrictions](https://developer-docs.amazon.com/sp-api/reference/getlistingsrestrictions)\n- [searchDefinitionsProductTypes](https://developer-docs.amazon.com/sp-api/reference/searchdefinitionsproducttypes)\n- [getDefinitionsProductType](https://developer-docs.amazon.com/sp-api/reference/getdefinitionsproducttype)\n- [ClawHub skill page](https://clawhub.ai/linkfox-ai/skills/linkfox-amazon-store-listings)\n\n## Skill Output:\n\n**Output Type(s):** [Text, JSON, Shell commands, Configuration, Guidance, Files]\n\n**Output Format:** [Markdown guidance with shell commands and JSON API responses; scripts save full JSON response files.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Responses may include Amazon seller Listing data and LinkFox accou"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"亚马逊卖家 Listing 刊登与商品类型定义管理。用于按 SKU 查询或搜索 Listing，创建、全量更新、局部修改和删除刊登，检查 ASIN 刊登限制，并查询 product type 及其 JSON Schema 属性要求。用户提到亚马逊 Listing、刊登商品、修改商品信息、删除 Listing、卖家 SKU、ASIN 能否销售、刊登限制、product type、商品类型定义、JSON Schema、Listings Items、Listings Restrictions 时触发。即使未明确提及 API，只要希望管理卖家自己的商品刊登或确认上架所需字段与资格，也应触发此技能；查询亚马逊全站商品目录使用 linkfox-amazon-store-catalog，批量提交使用 linkfox-amazon-store-feeds。 Skill: 亚马逊-店铺Listing管理 Owner: linkfox-ai Summary: 亚马逊卖家 Listing 刊登与商品类型定义管理。用于按 SKU 查询或搜索 Listing，创建、全量更新、局部修改和删除刊登，检查 ASIN 刊登限制，并查询 product type 及其 JSON Schema 属性要求。用户提到亚马逊 Listing、刊登商品、修改商品信息、删除 Listing、卖家 SKU、ASIN 能否销售、刊登限制、product type、商品类型定义、JSON Schema、Listings Items、Listings Restrictions 时触发。即使未明确提及 API，只要希望管理卖家自己的商品刊登或确认上架所需字段与资格，也应触发此技能；查询亚马逊全站商品目录使用 linkfox-amazon-store-catalog，批量提交使用 linkfox-amazon-store-f","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1165,"uniquenessScore":45,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T07:41:13.853Z","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-10T07:41:13.853Z","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-10T10:44:40.821Z","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"}]}}}