{"id":"0df0fbc7-eb36-4477-9ab7-e241c8b783c4","entityType":"agent","slug":"clawhub-linkfox-ai-linkfox-tiktok-selection-and-shoppable-video","name":"Linkfox Tiktok选品与带货视频","canonicalUrl":"https://www.xpersona.co/agent/clawhub-linkfox-ai-linkfox-tiktok-selection-and-shoppable-video","canonicalPath":"/agent/clawhub-linkfox-ai-linkfox-tiktok-selection-and-shoppable-video","generatedAt":"2026-10-12T04:35:29.877Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-12T01:13:45.938Z","emptyReason":null},"description":"TikTok 选品与带货视频一站式 AI 工具集，整合 EchoTik/FastMoss 选品数据与 TikTok 官方带货视频 API，覆盖 TikTok Shop 选品、爆品趋势、带货视频分析与可购物视频发布。 Skill: Linkfox Tiktok选品与带货视频 Owner: linkfox-ai Summary: TikTok 选品与带货视频一站式 AI 工具集，整合 EchoTik/FastMoss 选品数据与 TikTok 官方带货视频 API，覆盖 TikTok Shop 选品、爆品趋势、带货视频分析与可购物视频发布。 Tags: latest:1.2.3 Version history: v1.2.3 | 2026-08-14T15:20:41.705Z | user Update from 1.2.2 to 1.2.3 v1.2.2 | 2026-08-07T11:25:23.696Z | user Update from 1.2.1 to 1.2.2 v1.2.1 | 2026-08-05T09:00:32.063Z | user Update from 1.2.0 to 1.2.1 v1.2.0 | 2026-07","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 962 downloads reported by the source. Last updated 10/12/2026.","installCommand":"clawhub skill install s171g8b6m2khwdy9ye8bxj0wx183vd4z:linkfox-tiktok-selection-and-shoppable-video","sourceUrl":"https://clawhub.ai/linkfox-ai/linkfox-tiktok-selection-and-shoppable-video","homepage":"https://clawhub.ai/linkfox-ai/skills/linkfox-tiktok-selection-and-shoppable-video","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/linkfox-ai/linkfox-tiktok-selection-and-shoppable-video","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/linkfox-ai/skills/linkfox-tiktok-selection-and-shoppable-video","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"TikTok 选品与带货视频一站式 AI 工具集，整合 EchoTik/FastMoss 选品数据与 TikTok 官方带货视频 API，覆盖 TikTok Shop 选品、爆品趋势、带货视频分析与可购物视频发布。 Skill: Linkfox Tiktok选品与带货视频 Owner: linkfox-ai Summa"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-12T01:13:45.938Z","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-12T01:13:45.938Z","emptyReason":null},"stars":null,"forks":null,"downloads":962,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"1.2.3","tractionLabel":"962 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-12T01:13:45.896Z","emptyReason":null},"lastUpdatedAt":"2026-10-12T01:13:45.938Z","lastCrawledAt":"2026-10-12T01:13:45.896Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-13T01:13:45.896Z","lastVerifiedAt":null,"highlights":[{"version":"1.2.3","createdAt":"2026-08-14T15:20:41.705Z","changelog":"Update from 1.2.2 to 1.2.3","fileCount":49,"zipByteSize":153696},{"version":"1.2.2","createdAt":"2026-08-07T11:25:23.696Z","changelog":"Update from 1.2.1 to 1.2.2","fileCount":49,"zipByteSize":153761},{"version":"1.2.1","createdAt":"2026-08-05T09:00:32.063Z","changelog":"Update from 1.2.0 to 1.2.1","fileCount":49,"zipByteSize":153659},{"version":"1.2.0","createdAt":"2026-07-16T04:01:42.613Z","changelog":"Update from 1.0.1 to 1.2.0","fileCount":47,"zipByteSize":144526},{"version":"1.0.1","createdAt":"2026-07-16T03:37:39.244Z","changelog":"Update from 1.0.0 to 1.0.1","fileCount":47,"zipByteSize":144626},{"version":"1.0.0","createdAt":"2026-07-15T01:38:15.943Z","changelog":"Initial release","fileCount":47,"zipByteSize":144361}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s171g8b6m2khwdy9ye8bxj0wx183vd4z:linkfox-tiktok-selection-and-shoppable-video","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-tiktok-selection-and-shoppable-video/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-tiktok-selection-and-shoppable-video/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-tiktok-selection-and-shoppable-video/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-tiktok-selection-and-shoppable-video/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-tiktok-selection-and-shoppable-video/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-tiktok-selection-and-shoppable-video/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-12T04:35:29.873Z"}},"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-tiktok-selection-and-shoppable-video/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-tiktok-selection-and-shoppable-video/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-tiktok-selection-and-shoppable-video/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-tiktok-selection-and-shoppable-video/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-12T01:13:45.938Z","emptyReason":null},"readme":"Skill: Linkfox Tiktok选品与带货视频\n\nOwner: linkfox-ai\n\nSummary: TikTok 选品与带货视频一站式 AI 工具集，整合 EchoTik/FastMoss 选品数据与 TikTok 官方带货视频 API，覆盖 TikTok Shop 选品、爆品趋势、带货视频分析与可购物视频发布。\n\nTags: latest:1.2.3\n\nVersion history:\n\nv1.2.3 | 2026-08-14T15:20:41.705Z | user\n\nUpdate from 1.2.2 to 1.2.3\n\nv1.2.2 | 2026-08-07T11:25:23.696Z | user\n\nUpdate from 1.2.1 to 1.2.2\n\nv1.2.1 | 2026-08-05T09:00:32.063Z | user\n\nUpdate from 1.2.0 to 1.2.1\n\nv1.2.0 | 2026-07-16T04:01:42.613Z | user\n\nUpdate from 1.0.1 to 1.2.0\n\nv1.0.1 | 2026-07-16T03:37:39.244Z | user\n\nUpdate from 1.0.0 to 1.0.1\n\nv1.0.0 | 2026-07-15T01:38:15.943Z | user\n\nInitial release\n\nArchive index:\n\nArchive v1.2.3: 49 files, 153696 bytes\n\nFiles: references/large-file-upload.md (6593b), references/linkfox-echotik-batch-product-detail.md (14105b), references/linkfox-echotik-get-video-download-url.md (11627b), references/linkfox-echotik-list-new-product-rank.md (9384b), references/linkfox-echotik-list-product.md (14292b), references/linkfox-echotik-product-video.md (10568b), references/linkfox-fastmoss-product-rank-top-selling.md (11254b), references/linkfox-fastmoss-product-search.md (12740b), references/linkfox-tiktok-video-auth.md (16268b), references/linkfox-tiktok-video-products.md (13589b), references/linkfox-tiktok-video.md (40510b), references/onboarding.md (2068b), scripts/_products_api_runner.py (5541b), scripts/_products_endpoints.py (1768b), scripts/_tiktok_video_common.py (5234b), scripts/_tiktok_video_products_common.py (5246b), scripts/_video_api_runner.py (6057b), scripts/_video_endpoints.py (6373b), scripts/account_tokens.py (2987b), scripts/authorize_url.py (2475b), scripts/authorized_accounts.py (2146b), scripts/check_auth_dependency.py (3958b), scripts/echotik_batch_product_detail.py (13120b), scripts/echotik_get_video_download_url.py (13126b), scripts/echotik_list_new_product_rank.py (13126b), scripts/echotik_list_product_video.py (13091b), scripts/echotik_list_product.py (13060b), scripts/fastmoss_product_rank_top_selling.py (13144b), scripts/fastmoss_product_search.py (13072b), scripts/get_creator_profile.py (892b), scripts/get_shop_products.py (1169b), scripts/get_shoppable_video_precheck_result.py (1279b), scripts/get_shoppable_video_status.py (1212b), scripts/get_showcase_products.py (1287b), scripts/large_file_upload_bind.py (1054b), scripts/large_file_upload_init.py (1070b), scripts/large_file_upload.py (1688b), scripts/onboarding.py (24089b), scripts/post_shoppable_video.py (1766b), scripts/precheck_shoppable_video.py (1734b), scripts/products_api.py (955b), scripts/refresh_token.py (2966b), scripts/response_io.py (18387b), scripts/upload_shoppable_video_file.py (1767b), scripts/video_api.py (1074b), scripts/video_proxy.py (3878b), skill-card.md (3589b), SKILL.md (22605b), _meta.json (163b)\n\nFile v1.2.3:SKILL.md\n\n---\nname: linkfox-tiktok-selection-and-shoppable-video\ndisplay_name: Linkfox Tiktok选品与带货视频\ndisplay_name_en: LinkFox TikTok Product Selection and Shoppable Video\ndescription: TikTok 选品与带货视频一站式 AI 工具集，整合 EchoTik/FastMoss 选品数据与 TikTok 官方带货视频 API，覆盖 TikTok Shop 选品、爆品趋势、带货视频分析与可购物视频发布。\ndescription_zh: TikTok 选品与带货视频一站式 AI 工具集，整合 3 类工具、10 项子能力：EchoTik（16 区域市场新品排行、商品搜索、商品详情、带货视频、视频下载）、FastMoss（全球热销榜与商品搜索，日周月多维筛选）、TikTok 官方 API（视频号 OAuth 授权与令牌、可购物视频预检/发布/状态/达人档案/大文件上传/可带货商品查询）。覆盖选品、爆品趋势、销量/GMV/达人带货与带货视频分析及可购物视频发布链路。当用户需 TikTok 选品、爆品/新品排行、商品或带货视频分析、视频号授权与可购物视频发布时触发。参数见 references/，脚本见 scripts/。\ndescription_en: One-stop TikTok product-selection and shoppable-video AI toolkit integrating 10 sub-capabilities across 3 tool families — EchoTik (new-product ranking, product search, product detail, promotional-video query, video download URL across 16 regional markets), FastMoss (global top-selling rankings and product search with day/week/month and category/sales/commission/creator multi-dimensional filters), and the TikTok official shoppable-video API (creator OAuth authorization & token management, shoppable video pre-check/publish/status/creator profile/large-file chunked upload, creator sellable-product query). Covers TikTok Shop product research, bestseller/new-product trends, product sales/GMV/live/influencer analysis, promotional-video performance & download, and the full official shoppable-video publishing chain (authorize → get product_id → pre-check → publish → check status). Triggered when the user needs TikTok product selection, bestseller/new-product rankings, product or promotional-video data analysis, or TikTok video-account authorization and shoppable-video publishing. Full params per sub-capability are in references/, executable scripts in scripts/.\ncategory: e-commerce\nversion: 1.0.0\nauthor: LinkFox\n---\n\n# Linkfox Tiktok选品与带货视频（TikTok Product Selection and Shoppable Video）\n\nTikTok 选品与带货视频一站式 AI 工具集，整合 **3 类底层工具、10 项子能力**，覆盖选品数据（EchoTik 16 区域市场 / FastMoss 全球电商）与官方带货视频发布链路（TikTok 视频号授权 → 可带货商品 → 可购物视频预检/发布）。各子能力完整参数、响应字段与错误码见 `references/` 下对应文件，可执行脚本见 `scripts/`。\n\n## 能力边界\n\n### ✅ 能力范围\n- **TikTok 选品数据（`echotik_tiktok`，EchoTik，覆盖 16 个区域市场）**：新品排行发现热销爆品与新兴趋势（`echotik_tiktok` list-new-product-rank）；商品搜索按销量/达人/佣金/评分/评论多维筛选（`echotik_tiktok` list-product）；商品关联带货视频查询播放/互动/视频销量/GMV（`echotik_tiktok` product-video）；批量商品详情含多周期销量与 GMV、直播销量、带货达人数、价格评分与佣金（`echotik_tiktok` batch-product-detail）；解析 TikTok 视频链接返回无水印/含水印下载、播放与封面地址（`echotik_tiktok` get-video-download-url）。\n- **TikTok 全球电商热销与选品（`fastmoss_tiktok`，FastMoss）**：按日/周/月维度与类目分析热销商品排行榜与 GMV 排名（`fastmoss_tiktok` product-rank-top-selling）；按类目/销量/佣金率/达人数/店铺类型多维搜索筛选商品（`fastmoss_tiktok` product-search）。\n- **TikTok 官方带货视频 API（`tiktok_official_video_api`）**：视频号达人 OAuth 授权、已授权账号列表、令牌查询与 access_token 刷新（`tiktok_official_video_api` linkfox-tiktok-video-auth）；可购物视频内容预检、查预检结果、发布、查发布状态、达人档案查询及大文件分片上传（`tiktok_official_video_api` linkfox-tiktok-video）；达人可带货商品查询（店铺商品与橱窗/直播袋商品），取得 product_id 供可购物视频挂车（`tiktok_official_video_api` linkfox-tiktok-video-products）。\n- 覆盖 region/marketplace：EchoTik 16 个 TikTok Shop 区域市场；FastMoss 全球电商（按 region 筛选）；TikTok 官方视频号 region 支持 `global`（默认）/ `us`（美国站）。具体取值见各 references。\n\n### ❌ 边界与限制\n- **API Key 必需**：所有工具均需环境变量 `LINKFOX_AGENT_API_KEY`（或 `LINKFOXAGENT_API_KEY`）；各工具独立计费、独立限频，数据时效与区域覆盖随数据源而异。\n- **计费约束**：同一会话同一参数组合默认只调用一次（脚本带本地缓存）；失败或空结果不得自动换关键词、翻页或改区域连续试探；需继续检索时先向用户说明会产生额外消耗（计费规则见 `skills-version.json` 与 references 内 api.md 的 `costToken` 字段：EchoTik 5 项 fixed≈4.5/9000 token，FastMoss 2 项 fixed≈10.5/21000 token，TikTok 官方 3 项免费）。\n- **TikTok 官方模块隔离**：`linkfox-tiktok-video` / `linkfox-tiktok-video-products` 仅走 `/tiktokVideo/developerProxy`，path 须以 `affiliate_creator` / `video` / `creator` 开头（否则 errcode 1005）；不可用于 `/tiktokShop/*`（TikTok Shop 卖家模块用 `linkfox-tiktok-shop-auth`）。令牌 `ttsAccessToken` 由 `linkfox-tiktok-video-auth` 授权后经 `/tiktokVideo/accountTokens` 取得，固定 creator 达人端。\n- **TikTok 官方依赖链**：可购物视频发布需先 `linkfox-tiktok-video-auth` 授权取令牌，再 `linkfox-tiktok-video-products` 取 `product_id`，最后 `linkfox-tiktok-video` 预检/发布；`check_auth_dependency.py` 探测 `linkfox-tiktok-video-auth` 是否安装（exit 42=未安装/未授权，需先完成授权）。\n- **大文件上传限制**：≤10MB 走 `upload_shoppable_video_file`（multipart，网关暂不支持）；>10MB 走大文件分片三步（Initialize → PUT 分片 → Bind，详见 `references/large-file-upload.md`，Step 1/3 可经 proxy，Step 2 分片 PUT 不经网关）。\n- **不在范围内**：TikTok Shop 小店 ERP（商品/订单/财务，用 `linkfox-tiktok-shop-auth` + 业务 skill）、TikTok Shop 可购物视频（`/tiktokShop/developerProxy`，用 `linkfox-tiktok-creator`）、TikTok 广告投放、物流与供应链、非电商任务、与平台或卖家的直接沟通。\n\n## 工具选择指南\n\n按需求在下表定到子能力，再跳到【业务需求路由速查】查端点/脚本/references 取参执行。\n\n| 需求 / 用户说 | 默认推荐（子能力） | 何时换用其他 |\n|---|---|---|\n| TikTok 选品 / 搜商品（\"TikTok 上什么好卖\"） | `linkfox-echotik-list-product`（16 区域市场，销量/达人/佣金/评分多维） | 要全球电商+日/周/月维度+范围筛选（达人数/佣金率 range）用 `linkfox-fastmoss-product-search` |\n| TikTok 新品 / 新兴趋势（\"最近有什么新品爆\"） | `linkfox-echotik-list-new-product-rank`（新品排行） | 要热销榜（非新品）用 `linkfox-fastmoss-product-rank-top-selling` |\n| TikTok 热销榜 / 爆品排行 / GMV 排名 | `linkfox-fastmoss-product-rank-top-selling`（日/周/月+类目） | 要\"新品\"趋势用 `linkfox-echotik-list-new-product-rank` |\n| 商品详情 / 多周期销量 GMV（\"这个 productId 卖得怎么样\"） | `linkfox-echotik-batch-product-detail`（1d/7d/15d/30d/60d/90d/累计+直播+达人） | — |\n| 商品带货视频（\"这个商品有哪些带货视频 / 视频销量\"） | `linkfox-echotik-product-video`（播放/互动/视频销量/GMV） | — |\n| 视频下载 / 去水印（\"下载这个 TikTok 视频\"） | `linkfox-echotik-get-video-download-url`（无水印/含水印/播放/封面） | — |\n| 视频号授权 / 绑定视频号 / 刷新令牌 | `linkfox-tiktok-video-auth`（OAuth+令牌） | TikTok Shop 卖家授权用 `linkfox-tiktok-shop-auth`（不互通） |\n| 达人能带什么货 / 橱窗商品 / 取 product_id | `linkfox-tiktok-video-products`（店铺商品+橱窗/直播袋） | — |\n| 发布可购物视频 / 视频挂车（\"发一个带商品的 TikTok 视频\"） | `linkfox-tiktok-video`（预检→发布→查状态） | 需先 `linkfox-tiktok-video-auth` 授权 + `linkfox-tiktok-video-products` 取 product_id |\n| 达人主页 / 档案 | `linkfox-tiktok-video`（get_creator_profile，独立功能） | — |\n| 大文件分片上传视频（>10MB） | `linkfox-tiktok-video`（large_file_upload_init/bind + 分片 PUT） | ≤10MB 走 `upload_shoppable_video_file`（网关暂不支持 multipart） |\n\n### 工具选择思路\n- **重要**：多个子能力满足需求时，要依据需求深入分析子能力的功能、用途、出入参、从中调研出最合适的子能力，并推荐用户，让用户自己决定。\n- 满足程度同等的前提下，向用户推荐\"默认推荐子能力\"。\n\n## 业务需求路由速查\n\n按【工具选择指南】定到子能力 后，下表查端点、脚本与 references 文件取参执行：\n\n### 子能力 ↔ references 文件 ↔ 端点 ↔ 脚本（10 项）\n\n**echotik_tiktok**\n| 子能力 | references 文件 | 端点 | 脚本 |\n|---|---|---|---|\n| linkfox-echotik-list-new-product-rank | references/linkfox-echotik-list-new-product-rank.md | POST /echotik/listNewProductRank | echotik_list_new_product_rank.py |\n| linkfox-echotik-list-product | references/linkfox-echotik-list-product.md | POST /echotik/listProduct | echotik_list_product.py |\n| linkfox-echotik-product-video | references/linkfox-echotik-product-video.md | POST /echotik/listProductVideo | echotik_list_product_video.py |\n| linkfox-echotik-batch-product-detail | references/linkfox-echotik-batch-product-detail.md | POST /echotik/batchProductDetail | echotik_batch_product_detail.py |\n| linkfox-echotik-get-video-download-url | references/linkfox-echotik-get-video-download-url.md | POST /echotik/getVideoDownloadUrl | echotik_get_video_download_url.py |\n\n**fastmoss_tiktok**\n| 子能力 | references 文件 | 端点 | 脚本 |\n|---|---|---|---|\n| linkfox-fastmoss-product-rank-top-selling | references/linkfox-fastmoss-product-rank-top-selling.md | POST /fastmoss/productRankTopSelling | fastmoss_product_rank_top_selling.py |\n| linkfox-fastmoss-product-search | references/linkfox-fastmoss-product-search.md | POST /fastmoss/productSearch | fastmoss_product_search.py |\n\n**tiktok_official_video_api**\n| 子能力 | references 文件 | 端点 | 脚本 |\n|---|---|---|---|\n| linkfox-tiktok-video-auth | references/linkfox-tiktok-video-auth.md | POST /tiktokVideo/authorizeUrl、/authorizedAccounts、/accountTokens、/refreshToken | authorize_url.py、authorized_accounts.py、account_tokens.py、refresh_token.py |\n| linkfox-tiktok-video | references/linkfox-tiktok-video.md | POST /tiktokVideo/developerProxy | video_api.py、video_proxy.py、get_creator_profile.py、precheck_shoppable_video.py、get_shoppable_video_precheck_result.py、post_shoppable_video.py、get_shoppable_video_status.py、upload_shoppable_video_file.py、large_file_upload_init.py、large_file_upload_bind.py |\n| linkfox-tiktok-video-products | references/linkfox-tiktok-video-products.md | POST /tiktokVideo/developerProxy | get_shop_products.py、get_showcase_products.py、products_api.py |\n\n> TikTok 官方三子能力共享 helper：`response_io.py`（落盘/摘要）、`check_auth_dependency.py`（探测 `linkfox-tiktok-video-auth`）；`linkfox-tiktok-video` 另有 `_video_api_runner.py` / `_video_endpoints.py` / `_tiktok_video_common.py`，`linkfox-tiktok-video-products` 另有 `_products_api_runner.py` / `_products_endpoints.py` / `_tiktok_video_products_common.py`，均与本入口脚本同目录、随调随用。\n\n## 调用方式\n\n- **网关**：`${LINKFOX_TOOL_GATEWAY}/<端点>`（默认 `https://tool-gateway.linkfox.com`），请求方式 POST、Content-Type `application/json`，认证 Header `Authorization: `（api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取；未配置按下方【解决认证和积分问题】处理）。各端点路径见上方【业务需求路由速查】与对应 references 文件。\n- **TikTok 官方带货视频链路**：`linkfox-tiktok-video` / `linkfox-tiktok-video-products` 经 `POST /tiktokVideo/developerProxy` 转发至紫鸟 `tiktok-proxy/creator/{region}/{path}`；调用方传 `path` / `method` / `ttsAccessToken`（= creator `access_token`，上游请求头 `x-tts-access-token`）/ `region`（`global` 默认 / `us`）；`app_key` / `timestamp` / `sign` 由紫鸟代理自动注入。具名脚本（`video_api.py` / `products_api.py` / 各 `get_*.py` / `post_*.py`）只需传 `{\"api\": \"...\", \"openId\": \"...\"}`，脚本内部自动调 `/tiktokVideo/accountTokens` 取 `ttsAccessToken` 再调 developerProxy。\n- **Python 脚本**：每项子能力对应 `scripts/<脚本名>.py '' [--inline]`（脚本名与端点见路由速查表）。脚本内部完成网关调用、鉴权与落盘。\n- **输出策略（脚本默认行为）**：始终将完整响应写入 `/linkfox///data/-.json`（`` 为脚本执行时工作目录；`` 取自环境变量 `SESSION_ID`；禁止写入 /tmp，当前目录不可写则报错）；响应体 ≤ 8 KB 落盘后完整打印到 stdout，> 8 KB 仅打印摘要（顶层字段、常见计数、最大列表长度 + 前 3 条样本）；加 `--inline` 强制全量打印（同样落盘）。\n- **读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq` 或 PowerShell `ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n- **完整参数**：每个子能力的请求参数、响应字段、错误码、curl 示例见 `references/<子能力>.md`（文件内含该子能力 SKILL.md 正文与 api.md 全文）；`linkfox-tiktok-video` 另含 `references/large-file-upload.md`（大文件分片上传详解）。\n\n## 使用示例\n\n以下按数据层给出代表性子能力的出入参示例；其余子能力参数见对应 references 文件。\n\n### 选品与数据层（EchoTik / FastMoss）\n\n**1. TikTok 新品排行（echotik_tiktok → echotik_list_new_product_rank.py）**\n```json\n{\"date\": \"2025-06-15\", \"region\": \"US\", \"pageNum\": 1, \"pageSize\": 50}\n```\n出参：`products[]`（title/asin/price/minPrice/maxPrice/currency/totalSaleCnt/totalSaleGmvAmt/salesTrendFlagText/totalVideoCnt/totalLiveCnt/totalIflCnt 达人数/productCommissionRate/productRating/reviewCount/categoryId/imageUrl）、`total`、`columns`、`costToken`。\n\n**2. TikTok 商品搜索（echotik_tiktok → echotik_list_product.py）**\n```json\n{\"keyword\": \"phone case\", \"region\": \"US\", \"minTotalSale30dCnt\": 1000, \"productSortField\": 5, \"sortType\": 1, \"pageSize\": 20}\n```\n出参：`products[]`（productId/productName/title/price/spuAvgPrice/productRating/reviewCount/ratings/productCommissionRate/totalSaleCnt/monthlySalesUnits/totalSaleGmvAmt/totalIflCnt 达人数/categoryName/firstCrawlDt/salesTrendFlagText）、`total`、`columns`、`costToken`。\n\n**3. TikTok 热销榜（fastmoss_tiktok → fastmoss_product_rank_top_selling.py）**\n```json\n{\"region\": \"US\", \"dateInfo\": {\"type\": \"day\", \"value\": \"2026-04-15\"}, \"page\": 1, \"pageSize\": 10}\n```\n出参：`products[]`（title/productId/price/minPrice/maxPrice/currency/totalSaleCnt/totalSaleGmvAmt/growthRate/shopName/shopTotalUnitsSold/categoryName/productCommissionRate/imageUrl/offShelvesText）、`total`、`columns`、`costToken`。`dateInfo.type` 支持 `day` / `week` / `month`。\n\n**4. TikTok 商品搜索（fastmoss_tiktok → fastmoss_product_search.py）**\n```json\n{\"keyword\": \"phone case\", \"region\": \"US\", \"orderField\": \"day7_units_sold\", \"pageSize\": 10}\n```\n带范围筛选：`{\"keyword\": \"beauty\", \"region\": \"US\", \"commissionRateRange\": {\"min\": 0.10}, \"creatorCountRange\": {\"min\": 50}, \"orderField\": \"commission_rate\", \"pageSize\": 10}`\n出参：`products[]`（title/productId/price/totalSaleCnt/totalSaleGmvAmt/totalVideoCnt/totalLiveCnt/totalIflCnt 达人数/productCommissionRate/productRating/reviewCount/skuCount/shopName/isCrossBorder/tiktokUrl/fastmossUrl/imageUrl）、`total`、`columns`、`costToken`。\n\n**5. 批量商品详情（echotik_tiktok → echotik_batch_product_detail.py）**\n```json\n{\"productIds\": [\"1729382310407603945\", \"1729382310407603946\"]}\n```\n出参：`products[]`（productId/productName/region/sellerId/minPrice/maxPrice/spuAvgPrice/productRating/reviewCount/productCommissionRate/totalSaleCnt/totalSaleGmvAmt/totalLiveCnt/totalVideoCnt/totalIflCnt 达人数/totalViewsCnt/discount/freeShipping/salesTrendFlag/firstCrawlDt）、`total`、`columns`、`costToken`。也可用 `productUrls` 传 TikTok Shop 商品 URL。\n\n**6. 商品带货视频（echotik_tiktok → echotik_list_product_video.py）**\n```json\n{\"productId\": \"1729382310407603945\", \"productVideoSortField\": 1, \"sortType\": 1, \"pageSize\": 20}\n```\n出参：`data[]`（videoId/productId/userId/videoDesc/officialUrl/covet 封面/totalFavoritesCnt 点赞/totalVideoSaleCnt/totalVideoSaleGmvAmt/hashTag/createDate/region）、`total`、`columns`、`costToken`。\n\n**7. 视频下载地址（echotik_tiktok → echotik_get_video_download_url.py）**\n```json\n{\"url\": \"https://www.tiktok.com/@user/video/1234567890\"}\n```\n出参：`downloadUrl`（无水印）、`playUrl`、`coverUrl`、`dynamicCoverUrl`、`videoId`、`costToken`、`errmsg`。\n\n### 带货视频发布层（TikTok 官方）\n\n> 完整链路：`linkfox-tiktok-video-auth` 授权取 `ttsAccessToken` → `linkfox-tiktok-video-products` 取 `product_id` → `linkfox-tiktok-video` 上传 `file_id` →（可选）预检 → 发布 → 查状态。\n\n**8. 视频号授权与令牌（tiktok_official_video_api → authorize_url.py / authorized_accounts.py / account_tokens.py / refresh_token.py）**\n```json\n// POST /tiktokVideo/authorizeUrl\n{\"displayName\": \"My Channel\", \"region\": \"global\"}\n// → {\"authorizeUrl\": \"https://services.tiktokshop.com/open/authorize?service_id=xxx&state=abc123\"}（约 1 小时失效）\n// POST /tiktokVideo/authorizedAccounts {} → accounts[](openId/displayName/region/userType)、total\n// POST /tiktokVideo/accountTokens {\"openId\": \"\"}\n// → accessToken/refreshToken/accessTokenExpireIn/refreshTokenExpireIn（accessToken 即下游 ttsAccessToken）\n// POST /tiktokVideo/refreshToken {\"openId\": \"\"} → 续签并回写\n```\n\n**9. 视频号可带货商品（tiktok_official_video_api → get_shop_products.py / get_showcase_products.py）**\n```json\n// 店铺商品（get_shop_products，GET affiliate_creator/202509/shop_products）\n{\"openId\": \"...\", \"title_keyword\": \"apple\", \"sort_field\": \"PRICE\", \"sort_order\": \"DESC\", \"page_size\": 20}\n// 橱窗/直播袋商品（get_showcase_products，GET affiliate_creator/202405/showcases/products）\n{\"openId\": \"...\", \"page_size\": 20, \"origin\": \"SHOWCASE\"} // origin: SHOWCASE（默认）/ LIVE\n```\n出参：商品列表含 **`product_id`**（供 `linkfox-tiktok-video` 预检/发布挂车）、`data.next_page_token`（翻页）。`page_size` 必填 1~20。\n\n**10. 发布可购物视频（tiktok_official_video_api → precheck_shoppable_video.py / get_shoppable_video_precheck_result.py / post_shoppable_video.py / get_shoppable_video_status.py）**\n```json\n// 内容预检（precheck_shoppable_video，POST affiliate_creator/202511/videos/precheck_task）\n{\"openId\": \"...\", \"video_info\": {\"file_id\": \"...\"}, \"product_link_info\": {\"product_id\": \"...\", \"title\": \"Product anchor\"}}\n// → data.precheck.task_id\n// 查预检结果（GET affiliate_creator/202511/videos/precheck_tasks/{task_id}）\n{\"openId\": \"...\", \"task_id\": \"1123123123\"}\n// → result（SUCCESS/FAIL/PROCESSING）；FAIL 时看 issues[] 整改\n// 发布可购物视频（post_shoppable_video，POST affiliate_creator/202603/videos）\n{\"openId\": \"...\", \"video_info\": {\"file_id\": \"...\", \"title\": \"My shoppable video\"}, \"product_link_info\": {\"product_id\": \"...\", \"title\": \"Product anchor\"}}\n// → data.video.id\n// 查发布状态（get_shoppable_video_status，GET affiliate_creator/202509/videos/{video_id}/status）\n{\"openId\": \"...\", \"video_id\": \"7548431509997292816\"}\n// → post_status（SUCCESS/FAIL/PROCESSING）、post_time\n```\n> 上传视频文件取 `file_id`：≤10MB 走 `upload_shoppable_video_file`（multipart，网关暂不支持）；>10MB 走大文件分片（`large_file_upload_init` → PUT 分片 → `large_file_upload_bind`，详见 `references/large-file-upload.md`）。\n\n## 展示规则\n\n1. **客观呈现数据**：以清晰表格展示查询结果，不做主观商业建议（除非用户主动要求）；不同区域币种不同，展示价格/收入时务必提示币种（响应 `currency` 字段标明本地币种）。\n2. **来源标注**：展示数据时说明来自哪个工具/数据源（EchoTik / FastMoss / TikTok 官方）。\n3. **令牌安全**：不向用户明文输出完整 `ttsAccessToken` / `accessToken` / `refreshToken`，仅展示前 10 字符等掩码形式。\n4. **不可用数据**：值为 `0` 或 `-1` 的字段表示数据不可用，标注\"N/A\"或省略，不作实际值展示；`salesTrendFlagText`/`salesTrendFlag` 为 0=平稳 1=上升 2=下降。\n5. **错误处理与协同**：查询失败时根据响应 `errcode`/`errmsg` 或 TikTok `body.code`/`message` 说明原因并建议修正（TikTok 官方 path 未在白名单返回 errcode 1005、缺参 1002、上游异常 1003；HTTP 401/402 按下方认证积分处理）；连续使用多工具时将各工具发现汇总为连贯分析，标注数据来源与时间窗。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用 references/onboarding.md 引导解决问题：\n\n**注意**：你是workbuddy，并且渠道是workbuddy，使用 onboarding 引导登录注册时 channel **必须**为 workbuddy。这非常重要！\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\nFile v1.2.3:_meta.json\n\n{\n \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n \"slug\": \"linkfox-tiktok-selection-and-shoppable-video\",\n \"version\": \"1.2.3\",\n \"publishedAt\": 1786720841705\n}\n\nFile v1.2.3:references/large-file-upload.md\n\n# 可购物视频大文件分片上传方案（Shoppable Video Large File Upload）\n\n- **来源文档**：[Shoppable Video Large File Upload Solution（Lark）](https://bytedance.sg.larkoffice.com/docx/WTMvdfbTBo30Fex0r9YlYstGg0d)\n- **Partner Center**：[shoppable-video-large-file-upload](https://partner.tiktokshop.com/docv2/page/shoppable-video-large-file-upload)（需登录）\n- **适用场景**：可购物视频文件 **> 10MB**（≤ 10MB 仍可用 §4 直传 `video_files`）\n- **替代关系**：取代旧版「请求头特殊参数」大文件方案；旧方案已于 **2026-01-31** 停止支持\n\n## 方案概述\n\n通过 **文件网关分片上传（chunked upload via file gateway）**：\n\n1. 客户端将 **> 10MB** 的文件按 chunk 切分；\n2. 携带 `upload_token` **顺序**上传各分片至 `upload_url`；\n3. 服务端合并分片还原原文件；\n4. **Bind Business Resource** 将文件绑定到可购物视频业务资源，得到与直传等价的 `file_id`。\n\n≤ 10MB 的文件继续使用 **Upload Shoppable Video File**（`POST .../videos/video_files`）。\n\n## 三步流程\n\n```\nStep 1 Initialize Upload → upload_url + upload_token\nStep 2 Upload Chunks & Merge → PUT 分片至 upload_url（不经 LinkFox 网关）\nStep 3 Bind Business Resource → file_id（供后续发布；可选预检）\n```\n\n| 步骤 | 调用方 | 经 LinkFox `/tiktokVideo/developerProxy` |\n|------|--------|------------------------------------------|\n| 1 Initialize | JSON POST | **可能**（path 须白名单放行，见下） |\n| 2 Upload Chunks | 二进制 PUT | **否** — 直连 Step 1 返回的 `upload_url` |\n| 3 Bind | JSON POST | **可能**（同 Step 1 路径前缀约束） |\n\n---\n\n## Step 1：初始化上传（Initialize Upload）\n\n获取分片上传所需的 `upload_url` 与 `upload_token`。\n\n| 项 | 说明 |\n|----|------|\n| Method | `POST` |\n| 上游 Path | `/open/{version}/file/init`（`:version` 如 `202505`，**以 Lark / Partner 文档为准**） |\n| 经 proxy 的 path 示例 | `open/202505/file/init` |\n\n### Query 参数（紫鸟自动注入）\n\n| 参数 | 说明 |\n|------|------|\n| access_token | 即 creator `access_token` / `ttsAccessToken` |\n| app_key | 紫鸟注入 |\n| timestamp | 紫鸟注入 |\n| sign | 紫鸟注入 |\n\n### 请求体（JSON）\n\n> Lark 文档中 Request Body 字段需以官方最新版为准。常见初始化字段如下（**调用前请对照 Lark 核对**）：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| file_size | int64 | 文件总字节数 |\n| chunk_size | int64 | 分片大小（字节） |\n| file_name | string | 文件名（如 `video.mp4`） |\n| content_type | string | MIME，如 `video/mp4` |\n\n### 成功响应\n\n```json\n{\n \"upload_url\": \"{uploader_url}\",\n \"upload_token\": \"{your_unique_upload_token}\"\n}\n```\n\n| 字段 | 说明 |\n|------|------|\n| upload_url | 分片上传目标 URL（Step 2 使用，**完整 URL 含 query**） |\n| upload_token | 本次上传会话 token（Step 2/3 使用） |\n\n---\n\n## Step 2：上传分片并合并（Upload Chunks & Merge）\n\n将视频二进制 **顺序** PUT 到 Step 1 返回的 **`upload_url`**（文件网关域名，**不经过** LinkFox 网关）。\n\n### 请求要点\n\n| Header | 说明 |\n|--------|------|\n| Content-Type | 视频 MIME，如 `video/mp4` |\n| Content-Length | **当前分片**字节长度 |\n| Content-Range | `bytes {first}-{last}/{total}` |\n\n### 分片规则（参考 TikTok 媒体传输惯例，与 Lark 一致方向）\n\n| 规则 | 说明 |\n|------|------|\n| 顺序 | 分片须 **按序** 上传 |\n| 分片大小 | 单分片建议 **5MB ~ 64MB**；最后一片可含剩余字节（可略大于 chunk_size） |\n| 小文件 | 总大小 < 5MB 时通常整文件一片上传 |\n| 分片数量 | 最少 1 片，最多约 **1000** 片 |\n| chunk 计算 | `total_chunk_count = floor(file_size / chunk_size)`，末片包含余数 |\n\n### PUT 示例（单片 / 末片）\n\n```bash\ncurl --location --request PUT '{upload_url}' \\\n --header 'Content-Type: video/mp4' \\\n --header 'Content-Range: bytes 0-9999999/50000000' \\\n --header 'Content-Length: 10000000' \\\n --data-binary '@/path/to/chunk.bin'\n```\n\n> 使用 Step 1 返回的 **完整** `upload_url`（含 query 参数）。上传完成后由文件网关 **自动合并** 分片。\n\n---\n\n## Step 3：绑定业务资源（Bind Business Resource）\n\n将已合并的文件绑定到 **可购物视频（Shoppable Video）** 业务资源，取得与直传 `video_files` 等价的 **`file_id`**（`data.video_file.id`）。\n\n| 项 | 说明 |\n|----|------|\n| Method | `POST` |\n| 上游 Path | `/open/{version}/file/bind`（**path 名称以 Lark Step 3 为准**，也可能是 `complete` / `commit` 等） |\n| 经 proxy 的 path 示例 | `open/202505/file/bind` |\n\n### 请求体（JSON，字段以 Lark 为准）\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| upload_token | string | Step 1 返回的 `upload_token` |\n| resource_type / biz_type | string | 业务资源类型（可购物视频场景，见官方枚举） |\n\n### 成功响应（结构以官方为准）\n\n预期返回可购物视频文件 id，供后续 **Post Shoppable Video / Pre-check** 使用：\n\n```json\n{\n \"code\": 0,\n \"data\": {\n \"video_file\": {\n \"id\": \"123123123123\",\n \"md5\": \"...\"\n }\n },\n \"message\": \"success\"\n}\n```\n\n---\n\n## LinkFox 集成现状\n\n### 路径白名单\n\n当前 `tiktok-video.developer-proxy.allowed-path-prefixes` 仅含：\n\n- `affiliate_creator`\n- `video`\n- `creator`\n\nStep 1 / Step 3 文档路径为 **`open/{version}/file/...`**，**不在现网白名单内**，经 `/tiktokVideo/developerProxy` 调用会返回 **errcode 1005**。需后端扩展白名单或确认紫鸟映射后的 `affiliate_creator/...` 等价 path 后再启用脚本。\n\n### 脚本支持\n\n| 脚本 | 状态 |\n|------|------|\n| `large_file_upload.py --help` | 流程说明 |\n| `large_file_upload_init.py` | 文档入口（暂不可实际调用） |\n| `large_file_upload_bind.py` | 文档入口（暂不可实际调用） |\n| Step 2 分片 PUT | 须客户端直连 `upload_url`，暂无 skill 封装 |\n\n---\n\n## 与直传方案的选择\n\n| 文件大小 | 推荐方案 |\n|----------|----------|\n| ≤ 10MB | §4 `upload_shoppable_video_file`（multipart 直传，网关 multipart 待支持） |\n| > 10MB | 本节大文件分片三步流程 |\n\n## 在发布链路中的位置\n\n```\n选品 → [大文件分片上传 或 直传] → file_id → （可选）预检 → 发布 → 查状态\n```\n\n> 选品请使用 **`linkfox-tiktok-video-products`**。预检为可选步骤；上传获得 `file_id` 后可直接发布。\n\nFile v1.2.3:references/linkfox-echotik-batch-product-detail.md\n\n---\nname: linkfox-echotik-batch-product-detail\ndescription: 批量查询 TikTok 商品的多周期销量、GMV、直播数据、带货达人、价格评分等详情。\n---\n\n# EchoTik TikTok 商品批量详情（Batch Product Detail）\n\n本技能用于批量获取 TikTok 商品的详细表现指标，帮助卖家与运营人员并排对比候选商品的销售、GMV、直播、视频与达人数据。参数与响应字段详见 [references/api.md](references/api.md)。\n\n## 能力边界\n\n### ✅ 能力范围\n\n- 通过商品 ID 或 TikTok Shop 商品 URL 批量查询最多 1000 个商品的详情指标。\n- 返回多周期（1d/7d/15d/30d/60d/90d/累计）销量、GMV、直播销量、直播 GMV、视频、达人、观看次数等数据。\n- 返回价格（USD）、评分、评论数、佣金比例、上下架/全托管状态等。\n\n### ❌ 边界与限制\n\n- **批量上限**：单次请求最多 1000 个商品。\n- **价格币种**：所有价格字段均为 USD。\n- **数据口径**：销量、GMV、归因数据为分析估算值，非平台精确数据。\n- **仅查询已知商品**：本工具不按关键词或类目搜索，只解析用户已有的 ID/URL。\n- **不在范围内**：按关键词发现商品（用 `linkfox-echotik-product-search`）；新品/趋势商品排行（用 `linkfox-echotik-new-product-rank`）；商品关联带货视频（用 `linkfox-echotik-product-video`）；TikTok 视频下载链接解析（用 `linkfox-echotik-get-video-download-url`）；达人主页分析；非 TikTok 平台数据。\n\n## 调用方式\n\n- **API 端点**：`POST /echotik/batchProductDetail`（完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/echotik_batch_product_detail.py '' [--inline]`\n- **成本约束**：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `/linkfox///data/linkfox-echotik-batch-product-detail-.json`（`` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq`或`ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 使用示例\n\n**1. 按商品 ID 批量查询**\n```json\n{\n \"productIds\": [\"1729382310407603945\", \"1729382310407603946\"]\n}\n```\n\n**2. 按商品 URL 批量查询**\n```json\n{\n \"productUrls\": [\n \"https://shop.tiktok.com/us/pdp/phone-case/1729382310407603945\",\n \"https://shop.tiktok.com/us/pdp/case-for-phone/1729382310407603946\"\n ]\n}\n```\n\n**3. ID 与 URL 混合（服务端合并）**\n```json\n{\n \"productIds\": [\"1729382310407603945\"],\n \"productUrls\": [\"https://shop.tiktok.com/us/pdp/phone-case/1729382310407603946\"]\n}\n```\n\n## 展示规则\n\n1. **呈现对比表**：每商品一行，关键列含名称、价格（USD）、总销量、30 天销量、总 GMV、评分、评论数、佣金比例、带货达人数。\n2. **多周期语境**：对比动量时，在累计值旁展示相关窗口（如 7d/30d），而非只看总量。\n3. **币种**：价格为 USD，需标注 USD。\n4. **佣金格式**：`productCommissionRate` 以百分比展示（如 `0.05` → \"5%\"）。\n5. **趋势标识**：`salesTrendFlag` 渲染为稳定/上升/下降，便于快速扫描。\n6. **状态徽标**：在相关位置标注 `isSShop`（全托管）、`offMark`（下架）、`freeShipping`，避免用户误把下架商品纳入对比。\n7. **图片引用**：返回 `imageUrl` / `productImageUrls` 时说明图片可用。\n8. **长描述**：`descDetail` 可能为较长 HTML/文本，做摘要或说明其可用性，而非整段倾倒。\n9. **缺失商品处理**：若请求的商品无记录，列出无数据的 ID/URL 供用户核对。\n10. **错误处理**：查询失败时根据 `errmsg`/`error` 字段说明原因，建议检查 ID/URL。\n\n## 用户表达与场景速查\n\n**适用** —— TikTok 商品批量详情查询：\n\n| 用户说 | 场景 |\n|--------|------|\n| \"查这些 TikTok 商品的详情\" | 按商品 ID 批量详情 |\n| \"拉一下这些 TikTok 链接的销量\" | 按商品 URL 批量详情 |\n| \"对比这些 TikTok 商品的 GMV\" | 批量查询，展示 GMV 列 |\n| \"这些 TikTok 商品哪些在涨\" | 批量查询，读 `salesTrendFlag` |\n| \"这些 TikTok 商品有下架/全托管吗\" | 批量查询，读 `offMark` / `isSShop` |\n| \"查这些 TikTok 商品的直播销量\" | 批量查询，展示直播销量/GMV |\n\n不适用场景见上方【能力边界】。\n\n### 边界判断\n\n当用户说\"分析这些 TikTok 商品\"时，判断用户是否已有具体商品 ID 或 TikTok Shop URL（本技能），还是想按关键词/类目**发现**商品（搜索技能）。若用户粘贴了 ID/URL 列表并希望查看销量/GMV/直播详情，适用本技能；若用户问\"该卖什么\"或\"找趋势商品\"，则不适用。\n\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\n---\n\n# EchoTik-TikTok商品批量详情 API 参考\n\n## 调用规范\n\n- **请求地址**：`${LINKFOX_TOOL_GATEWAY}/echotik/batchProductDetail`\n- **请求方式**：POST，Content-Type: application/json\n- **认证方式**：Header `Authorization: `，api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\n\n## 请求参数\n\nPOST Body（JSON）：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| productIds | array<string> | 否* | 商品ID列表（最多 1000 个）。示例：`[\"1729382310407603945\", \"1729382310407603946\"]` |\n| productUrls | array<string> | 否* | 商品URL列表（最多 1000 个），形如 `https://shop.tiktok.com/us/pdp//?...`；后端会从每个URL中提取末尾的 `productId` 并合并到 `productIds`，与 `productIds` 不互斥 |\n\n\\* `productIds` 与 `productUrls` 至少传其一，可同时传入；二者合并后最多 1000 个商品。\n\n## 响应结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| total | integer | 记录数 |\n| products | array | 商品详情列表（详见下方商品对象） |\n| columns | array | 渲染的列 |\n| type | string | 渲染的样式 |\n| costToken | integer | 消耗token |\n\n### 商品对象字段\n\n> 销量、GMV、直播、视频、达人、观看等指标均按 `1d / 7d / 15d / 30d / 60d / 90d` 多周期及累计（total）返回。价格字段单位均为 USD。\n\n**基础信息**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| productId | string | 商品ID |\n| productName | string | 商品名称 |\n| imageUrl | string | 商品图片 |\n| productImageUrls | array | 商品图片列表 |\n| region | string | 区域代码 |\n| sellerId | string | 卖家ID |\n| categoryId | string | 一级分类ID |\n| categoryL2Id | string | 二级分类ID |\n| categoryL3Id | string | 三级分类ID |\n\n**价格 / 评分 / 佣金**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| minPrice | number | 最低SKU价格(USD) |\n| maxPrice | number | 最高SKU价格(USD) |\n| spuAvgPrice | number | SPU平均价格(USD) |\n| productRating | number | 商品评分 |\n| reviewCount | integer | 评论数量 |\n| productCommissionRate | number | 商品佣金比例 |\n\n**销量（多周期）**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| totalSaleCnt | integer | 总销量 |\n| totalSale1dCnt | integer | 近1天销量 |\n| totalSale7dCnt | integer | 近7天销量 |\n| totalSale15dCnt | integer | 近15天销量 |\n| totalSale30dCnt | integer | 近30天销量 |\n| totalSale60dCnt | integer | 近60天销量 |\n| totalSale90dCnt | integer | 近90天销量 |\n\n**销售额 GMV（多周期）**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| totalSaleGmvAmt | number | 总销售额 |\n| totalSaleGmv1dAmt | number | 近1天销售额 |\n| totalSaleGmv7dAmt | number | 近7天销售额 |\n| totalSaleGmv15dAmt | number | 近15天销售额 |\n| totalSaleGmv30dAmt | number | 近30天销售额 |\n| totalSaleGmv60dAmt | number | 近60天销售额 |\n| totalSaleGmv90dAmt | number | 近90天销售额 |\n\n**直播（多周期）**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| totalLiveCnt | integer | 总直播数量 |\n| totalLive1dCnt | integer | 近1天直播数量 |\n| totalLive7dCnt | integer | 近7天直播数量 |\n| totalLive15dCnt | integer | 近15天直播数量 |\n| totalLive30dCnt | integer | 近30天直播数量 |\n| totalLive60dCnt | integer | 近60天直播数量 |\n| totalLive90dCnt | integer | 近90天直播数量 |\n\n**直播销量 / 直播销售额（多周期）**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| totalLiveSale1dCnt | integer | 近1天直播销量 |\n| totalLiveSale7dCnt | integer | 近7天直播销量 |\n| totalLiveSale15dCnt | integer | 近15天直播销量 |\n| totalLiveSale30dCnt | integer | 近30天直播销量 |\n| totalLiveSale60dCnt | integer | 近60天直播销量 |\n| totalLiveSale90dCnt | integer | 近90天直播销量 |\n| totalLiveSaleGmv1dAmt | integer | 近1天直播销售额 |\n| totalLiveSaleGmv7dAmt | integer | 近7天直播销售额 |\n| totalLiveSaleGmv15dAmt | integer | 近15天直播销售额 |\n| totalLiveSaleGmv30dAmt | integer | 近30天直播销售额 |\n| totalLiveSaleGmv60dAmt | integer | 近60天直播销售额 |\n| totalLiveSaleGmv90dAmt | integer | 近90天直播销售额 |\n\n**视频（多周期）**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| totalVideoCnt | integer | 总视频数量 |\n| totalVideo1dCnt | integer | 近1天视频数量 |\n| totalVideo7dCnt | integer | 近7天视频数量 |\n| totalVideo15dCnt | integer | 近15天视频数量 |\n| totalVideo30dCnt | integer | 近30天视频数量 |\n| totalVideo60dCnt | integer | 近60天视频数量 |\n| totalVideo90dCnt | integer | 近90天视频数量 |\n\n**达人（多周期）**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| totalIflCnt | integer | 总达人数量 |\n| totalIflVideo1dCnt | integer | 近1天达人视频数量 |\n| totalIflVideo7dCnt | integer | 近7天达人视频数量 |\n| totalIflVideo15dCnt | integer | 近15天达人视频数量 |\n| totalIflVideo30dCnt | integer | 近30天达人视频数量 |\n| totalIflVideo60dCnt | integer | 近60天达人视频数量 |\n| totalIflVideo90dCnt | integer | 近90天达人视频数量 |\n| totalIflLive1dCnt | integer | 近1天达人直播数量 |\n| totalIflLive7dCnt | integer | 近7天达人直播数量 |\n| totalIflLive15dCnt | integer | 近15天达人直播数量 |\n| totalIflLive30dCnt | integer | 近30天达人直播数量 |\n| totalIflLive60dCnt | integer | 近60天达人直播数量 |\n| totalIflLive90dCnt | integer | 近90天达人直播数量 |\n\n**观看次数（多周期）**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| totalViewsCnt | integer | 总观看次数 |\n| totalViews1dCnt | integer | 近1天观看次数 |\n| totalViews7dCnt | integer | 近7天观看次数 |\n| totalViews15dCnt | integer | 近15天观看次数 |\n| totalViews30dCnt | integer | 近30天观看次数 |\n| totalViews60dCnt | integer | 近60天观看次数 |\n| totalViews90dCnt | integer | 近90天观看次数 |\n\n**状态标识与其它**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| discount | string | 折扣信息 |\n| freeShipping | integer | 是否免运费 |\n| salesFlag | integer | 主要配送方式 |\n| salesTrendFlag | integer | 销售趋势标识：0=稳定、1=上升、2=下降 |\n| isSShop | integer | 是否全托管店铺 |\n| offMark | integer | 商品下架标识 |\n| firstCrawlDt | string | 首次爬取日期 |\n| descDetail | string | 商品详情描述 |\n\n## 错误码\n\n正常情况下，接口的 HTTP 状态码均为 200，业务的成功与否通过响应体中的 errorCode 字段区分（errorCode = 200 表示成功，其他值表示业务错误）。当遇到未授权等情况时，HTTP 状态码为 401，且对应的 errorCode 也是 401。\n\n| errcode | 含义 | 处理建议 |\n|---------|------|----------|\n| 200 | 成功 | 正常解析业务字段 |\n| 401 | 认证失败 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 402 | 积分不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 其他非200值 | 业务异常 | 参考 `errmsg` 字段获取具体错误原因（如商品ID不正确、商品不存在等） |\n\n错误响应示例：\n\n```json\n{\n \"errcode\": 401,\n \"errmsg\": \"authorized error\"\n}\n```\n\n## curl 示例\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/echotik/batchProductDetail \\\n -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"productIds\": [\"1729382310407603945\", \"1729382310407603946\"]\n }'\n```\n\nFile v1.2.3:references/linkfox-echotik-get-video-download-url.md\n\n---\nname: linkfox-echotik-get-video-download-url\ndescription: 解析 TikTok 视频链接，返回无水印/含水印下载地址、播放地址与封面地址。\n---\n\n# EchoTik TikTok 视频下载地址查询\n\n本技能用于把一个 TikTok 视频链接解析为可直接下载/播放的视频地址，帮助卖家保存带货视频素材或离线分析复用。参数与响应字段详见 [references/api.md](references/api.md)。\n\n## 能力边界\n\n### ✅ 能力范围\n\n- 把单个 TikTok 视频链接解析为：无水印下载地址（`noWatermarkDownloadUrl`）、含水印下载地址（`downloadUrl`）、播放地址（`playUrl`）与封面（静态 `coverUrl` / 动态 `dynamicCoverUrl`）。\n- 支持两种链接格式：短链 `https://vt.tiktok.com/xxxxxx` 与完整链接 `https://www.tiktok.com/@user/video/1234567890`。\n- 适用于归档高表现带货视频、复用创作者素材等场景。\n\n### ❌ 边界与限制\n\n- **必填参数**：必须提供 `url`，最大长度 1000。\n- **下载地址不一定返回**：受区域、隐私或源站限制，部分视频不返回 `noWatermarkDownloadUrl` / `downloadUrl`，仅返回 `playUrl` 与封面；此时应改用 `playUrl` 播放预览，不要伪造下载链接。\n- **链接时效**：返回的下载/播放地址会过期，应在解析后尽快使用；链接失效时需重新解析。\n- **不在范围内**：按商品查询关联带货视频（用 `linkfox-echotik-product-video`，需 `productId`）；TikTok 商品搜索（用 `linkfox-echotik-product-search`）；TikTok 新品榜单（用 `linkfox-echotik-new-product-rank`）；TikTok 直播数据；视频剪辑或内容创作建议；非 TikTok 平台的视频下载。\n\n## 核心概念\n\n本工具接收单个 TikTok 视频链接，解析为直接媒体地址：无水印下载地址（推荐用于干净素材）、含水印下载地址、播放地址与封面（静态/动态）。当卖家想归档通过 EchoTik 商品视频工具发现的高表现带货视频，或复用创作者片段而无需重新录制时，本工具很有用。\n\n**必填输入**：`url` 必填，支持两种格式：\n- 短链：`https://vt.tiktok.com/xxxxxx`\n- 完整链接：`https://www.tiktok.com/@user/video/1234567890`\n\n**下载地址为条件返回**：并非所有视频都返回可下载地址。`noWatermarkDownloadUrl` 与 `downloadUrl` 仅在源视频允许时返回；部分视频（受区域/隐私/可用性限制）两者都缺省，仅返回 `playUrl` 与封面。呈现下载链接前务必检查字段是否存在，下载字段缺失时用 `playUrl` 播放兜底。\n\n**地址时效**：返回的下载/播放地址会随时间失效，应在解析后尽快使用；链接失效时重新解析。\n\n## 调用方式\n\n- **API 端点**：`POST /echotik/getVideoDownloadUrl`（完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/echotik_get_video_download_url.py '' [--inline]`\n- **成本约束**：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `/linkfox///data/linkfox-echotik-get-video-download-url-.json`（`` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq` 或 `ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 使用示例\n\n**1. 解析完整 TikTok 视频链接**\n```json\n{\n \"url\": \"https://www.tiktok.com/@user/video/1234567890\"\n}\n```\n\n**2. 解析 TikTok 短链**\n```json\n{\n \"url\": \"https://vt.tiktok.com/Z123abc/\"\n}\n```\n\n## 展示规则\n\n1. **优先呈现无水印链接**：`noWatermarkDownloadUrl` 存在时，作为首选下载选项呈现，因为干净素材通常是卖家想要的。\n2. **同时提供含水印版本**：`downloadUrl`（含水印）存在时也列出，以备用户需要原版品牌。\n3. **处理下载地址缺失**：`noWatermarkDownloadUrl` 与 `downloadUrl` 都缺失时（部分视频常见），不要伪造下载链接——告知用户该视频无直接下载地址，改用 `playUrl` 播放/预览。\n4. **提供播放与封面**：说明 `playUrl` 可快速预览，`coverUrl` / `dynamicCoverUrl` 作为缩略图。\n5. **时效提醒**：提醒用户解析的地址会过期，应尽快下载。\n6. **只呈现数据**：清晰展示解析出的地址，不对视频如何使用做主观建议。\n7. **错误处理**：解析失败时根据 `errcode`/`errmsg` 说明原因——`400` 表示 `url` 缺失或无效，`10000` 表示链接非有效/可访问的 TikTok 视频；建议检查 URL 格式。\n\n## 用户表达与场景速查\n\n**适用** —— TikTok 视频下载与素材保存：\n\n| 用户说 | 场景 |\n|--------|------|\n| \"下载这个 TikTok 视频\"、\"保存这个 TikTok 片段\" | 把视频链接解析为下载地址 |\n| \"给我这个 TikTok 视频的无水印版本\" | 优先返回 `noWatermarkDownloadUrl` |\n| \"我想保存这个达人的带货视频\" | 解析并归档创作者视频 |\n| \"给我这个 TikTok 视频的可播放链接\" | 返回 `playUrl` |\n| \"给我这个 TikTok 视频的封面/缩略图\" | 返回 `coverUrl` / `dynamicCoverUrl` |\n\n不适用场景见上方【能力边界】。\n\n**边界判断**：当用户提到「TikTok 视频」时，判断其是否已有想下载的**具体视频链接**（本技能），还是想**发现某商品关联的视频**（商品视频技能）。若用户提供 `tiktok.com` 或 `vt.tiktok.com` 链接并要求保存/下载/提取，适用本技能；若其提供商品 ID 并问「这个商品有哪些带货视频」，则用 `linkfox-echotik-product-video`。\n\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\n---\n\n# EchoTik TikTok 视频下载 API 参考\n\n## 调用规范\n\n- **请求地址**：`${LINKFOX_TOOL_GATEWAY}/echotik/getVideoDownloadUrl`\n- **请求方式**：POST，Content-Type: application/json\n- **认证方式**：Header `Authorization: `，api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\n\n## 请求参数\n\nPOST Body（JSON）：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| url | string | 是 | TikTok 视频地址，支持两种格式：`https://vt.tiktok.com/xxx` 短链或 `https://www.tiktok.com/@user/video/xxx` 完整链接。最大长度 1000 |\n\n## 响应结构\n\n成功时 HTTP 状态码为 200，响应体顶层同时包含业务码 `errcode=200`、`errmsg=\"ok\"` 与下列数据字段。\n\n| 字段 | 类型 | 是否必返 | 说明 |\n|------|------|----------|------|\n| noWatermarkDownloadUrl | string | 条件返回 | 视频下载地址（无水印）。**并非所有视频都返回**：部分视频该字段缺省，此时无法提供无水印下载 |\n| downloadUrl | string | 条件返回 | 视频下载地址（含水印）。**并非所有视频都返回**：与无水印地址一同缺省或出现 |\n| playUrl | string | 始终返回 | 视频播放地址。当下载地址缺省时，可作为播放/预览的兜底 |\n| coverUrl | string | 始终返回 | 视频封面地址（静态） |\n| dynamicCoverUrl | string | 始终返回 | 视频动态封面地址 |\n| videoId | string | 始终返回 | 视频 ID |\n| columns | array | 始终返回 | 渲染列定义（字段元数据：field/title/cellType/filterable/sortable，供前端表格渲染用） |\n| type | string | 始终返回 | 渲染样式（如 `tableListWorkbenches`） |\n| costToken | integer | 始终返回 | 消耗 token |\n| errcode | integer | 始终返回 | 业务码，200 表示成功 |\n| errmsg | string | 始终返回 | 业务信息，成功时为 `ok` |\n\n> **下载地址缺省说明**：实测部分视频（受区域、隐私或源站限制）不会返回 `noWatermarkDownloadUrl` / `downloadUrl`，仅返回 `playUrl` 与封面。此时应向用户说明该视频暂无可直接下载地址，可改用 `playUrl` 播放预览。\n\n成功响应示例（真实调用，已截断长 URL）：\n\n```json\n{\n \"errcode\": 200,\n \"errmsg\": \"ok\",\n \"videoId\": \"7096674515245206810\",\n \"noWatermarkDownloadUrl\": \"https://v45.tiktokcdn-eu.com/51678f6e0de3...\",\n \"downloadUrl\": \"https://v45.tiktokcdn-eu.com/626c5d3d5a7d...\",\n \"playUrl\": \"https://v45.tiktokcdn-eu.com/51678f6e0de3...\",\n \"coverUrl\": \"https://agent-files.linkfox.com/tiktok/20260629/7096674515245206810.jpg\",\n \"dynamicCoverUrl\": \"https://p16-common-sign.tiktokcdn-eu.com/tos-useast2a-p-0037...\",\n \"type\": \"tableListWorkbenches\",\n \"costToken\": 12000,\n \"columns\": [/* 渲染列定义 */]\n}\n```\n\n## 错误码\n\n正常情况下，接口的 HTTP 状态码均为 200，业务的成功与否通过响应体中的 `errcode` 字段区分（`errcode = 200` 表示成功，其他值表示业务错误）。当遇到未授权等情况时，HTTP 状态码为 401，且对应的 `errcode` 也是 401。\n\n| errcode | 含义 | 处理建议 |\n|---------|------|----------|\n| 200 | 成功 | 正常解析业务字段 |\n| 400 | 参数错误 | `errmsg` 会指明缺失项，如 `url 为必填参数`；检查 `url` 是否传入且非空 |\n| 401 | 认证失败 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 402 | 积分不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 10000 | 未获取到视频下载地址 | URL 非 TikTok 视频链接、视频不可访问或已被删除；提示用户检查链接是否为有效的 TikTok 视频地址 |\n| 其他非200值 | 业务异常 | 参考 `errmsg` 字段获取具体错误原因 |\n\n错误响应示例：\n\n```json\n// 参数缺失\n{\n \"errcode\": 400,\n \"errmsg\": \"url 为必填参数\",\n \"url\": \"\"\n}\n\n// 非有效 TikTok 视频链接\n{\n \"errcode\": 10000,\n \"errmsg\": \"未获取到视频下载地址\"\n}\n\n// 未授权\n{\n \"errcode\": 401,\n \"errmsg\": \"authorized error\"\n}\n```\n\n## curl 示例\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/echotik/getVideoDownloadUrl \\\n -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"url\": \"https://www.tiktok.com/@user/video/1234567890\"\n }'\n```\n\nFile v1.2.3:references/linkfox-echotik-list-new-product-rank.md\n\n---\nname: linkfox-echotik-list-new-product-rank\ndescription: TikTok Shop 新品排行查询。基于 EchoTik 数据发现多区域市场的短视频电商热销爆品与新兴商品趋势。\n---\n\n# EchoTik - TikTok 新品排行（New Product Ranking）\n\n本技能用于通过 EchoTik 数据源查询和分析 TikTok Shop 新品排行数据，帮助跨境电商卖家在 TikTok 区域市场识别热门新品。参数与响应字段详见 [references/api.md](references/api.md)。\n\n## 能力边界\n\n### ✅ 能力范围\n\n- 查询 TikTok Shop 16 个区域市场的新品排行数据，获取每日新品快照。\n- 展示新品的价格、销量、销售额、带货达人数、关联视频/直播数、佣金率、评分等指标。\n- 支持按 `region` 切换市场、按 `pageNum` / `pageSize` 翻页浏览大结果集。\n\n### ❌ 边界与限制\n\n- **日期必填**：`date` 参数必填，格式 `YYYY-MM-DD`，无默认日期。\n- **日粒度数据**：为每日快照，不提供周榜/月榜或跨多月的长期趋势。\n- **分页**：单次请求不会返回全部商品，需用 `pageNum`、`pageSize` 翻页。\n- **不在范围内**：Amazon 选品与关键词分析（用 ABA 工具）；TikTok 广告投放与广告管理；TikTok 内容创作或视频剪辑；商品评价与 Listing 文案撰写；利润率计算与定价策略。\n\n## 核心概念\n\nTikTok 新品排行追踪在 TikTok Shop 近期上架且表现上升的新品，揭示哪些新品卖得好、其定价、销量、达人覆盖与直播活跃度，是短视频电商选品、趋势分析与竞品情报的必备工具。\n\n**数据范围**：覆盖 16 个 TikTok Shop 市场，提供每日新品快照及其表现指标（销量、销售额、达人数、视频数、直播数、佣金率、评分等）。\n\n**分页**：结果分页返回，用 `pageNum`（页码，从 1 开始）与 `pageSize`（每页条数，默认 50）浏览。\n\n## 调用方式\n\n- **API 端点**：`POST /echotik/listNewProductRank`（完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/echotik_list_new_product_rank.py '' [--inline]`\n- **成本约束**：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换 region、翻页或改 date 连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `/linkfox///data/linkfox-echotik-list-new-product-rank-.json`（`` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq` 或 `ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 使用示例\n\n**1. 当日美国市场热门新品**\n查询美国市场当前日期，查看哪些新品正在上升。\n```\ndate: \"2025-06-15\", region: \"US\"\n```\n\n**2. 发掘东南亚热门新品**\n查看印尼或泰国市场的新品机会。\n```\ndate: \"2025-06-15\", region: \"ID\"\n```\n\n**3. 浏览英国市场新品排行**\n考察英国 TikTok Shop 的新晋热门商品。\n```\ndate: \"2025-06-15\", region: \"GB\"\n```\n\n**4. 翻页浏览大结果集**\n获取美国市场每页 20 条的第 2 页。\n```\ndate: \"2025-06-15\", region: \"US\", pageNum: 2, pageSize: 20\n```\n\n## 展示规则\n\n1. **只呈现数据**：以清晰表格展示查询结果，不做主观商业建议。\n2. **销量趋势说明**：展示销量趋势时，将数值标识翻译为可读标签：0 = 平稳，1 = 上升，2 = 下降。\n3. **币种标注**：价格须带币种代码，不同市场币种不同。\n4. **大结果提示**：结果较多时展示头部商品摘要，并提醒用户可翻页获取更多。\n5. **图片处理**：返回 `imageUrl` 时提及但不内联渲染，除非环境支持。\n6. **错误处理**：查询失败时说明原因，并建议调整 `date` 或 `region` 参数。\n\n## 用户表达与场景速查\n\n**适用** —— TikTok Shop 新品发现与趋势分析：\n\n| 用户说 | 场景 |\n|--------|------|\n| \"TikTok 上什么新品火\" | 新品排行查询 |\n| \"TikTok 今日热销\"、\"TikTok Shop 爆品\" | 每日排行查询 |\n| \"东南亚 TikTok 新品机会\" | 区域市场考察 |\n| \"TikTok 英国卖得好的新品\" | 区域排行 |\n| \"TikTok 选品\"、\"短视频电商趋势\" | 通用商品发现 |\n| \"TikTok 上升的新品\" | 趋势筛选排行 |\n| \"TikTok 达人推的货\"、\"TikTok 创作者在卖什么\" | 达人驱动商品发现 |\n\n不适用场景见上方【能力边界】。\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\n---\n\n# EchoTik-TikTok新品榜 API 参考\n\n## 调用规范\n\n- **请求地址**：`${LINKFOX_TOOL_GATEWAY}/echotik/listNewProductRank`\n- **请求方式**：POST，Content-Type: application/json\n- **认证方式**：Header `Authorization: `，api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\n\n## 请求参数\n\nPOST Body（JSON）：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| date | string | 是 | 日期，格式为 `YYYY-MM-DD` |\n| region | string | 否 | 区域，默认 `US`。可选值：US（美国）、ID（印度尼西亚）、TH（泰国）、PH（菲律宾）、MY（马来西亚）、VN（越南）、GB（英国）、MX（墨西哥）、SG（新加坡）、SA（沙特阿拉伯）、BR（巴西）、ES（西班牙）、JP（日本）、DE（德国）、IT（意大利）、FR（法国） |\n| pageNum | integer | 否 | 分页页码，默认 `1` |\n| pageSize | integer | 否 | 每页条数，默认 `50` |\n\n\n## 响应结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| total | integer | 记录数 |\n| products | array | 最新商品列表（见下方商品对象） |\n| columns | array | 渲染的列 |\n| type | string | 渲染的样式 |\n| costToken | integer | 消耗token |\n\n### 商品对象\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| title | string | 商品名称 |\n| asin | string | 商品ID |\n| region | string | 区域代码 |\n| price | number | SPU平均价格 |\n| minPrice | number | 最低价格 |\n| maxPrice | number | 最高价格 |\n| currency | string | 货币 |\n| totalSaleCnt | integer | 总销量 |\n| totalSale30dCnt | integer | 近30天销量 |\n| totalSaleGmvAmt | number | 总销售额 |\n| totalSaleGmv30dAmt | number | 近30天销售额 |\n| salesTrendFlagText | string | 销售趋势标识，0=平稳 1=上升 2=下降 |\n| totalVideoCnt | integer | 视频总数 |\n| totalLiveCnt | integer | 直播总数 |\n| totalIflCnt | integer | 总达人数 |\n| productCommissionRate | number | 商品佣金比例 |\n| productRating | number | 商品评分 |\n| reviewCount | integer | 评论数量 |\n| availableDate | string (date) | 首次爬取日期 |\n| categoryId | string | 商品分类ID |\n| imageUrl | string | 商品图片 |\n| productImageUrls | array | 商品图片URL列表 |\n| sourceTool | string | 来源工具 |\n| sourceType | string | 商品来源 |\n\n## 错误码\n\n正常情况下，接口的 HTTP 状态码均为 200，业务的成功与否通过响应体中的 errorCode 字段区分（errorCode = 200 表示成功，其他值表示业务错误）。当遇到未授权等情况时，HTTP 状态码为 401，且对应的 errorCode 也是 401。\n\n| errcode | 含义 | 处理建议 |\n|---------|------|----------|\n| 200 | 成功 | 正常解析业务字段 |\n| 401 | 认证失败 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 402 | 积分不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 其他非200值 | 业务异常 | 参考 `errmsg` 字段获取具体错误原因 |\n\n错误响应示例：\n\n```json\n{\n \"errcode\": 401,\n \"errmsg\": \"authorized error\"\n}\n```\n\n## curl 示例\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/echotik/listNewProductRank \\\n -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"date\": \"2025-06-15\", \"region\": \"US\", \"pageNum\": 1, \"pageSize\": 50}'\n```\n\nFile v1.2.3:references/linkfox-echotik-list-product.md\n\n---\nname: linkfox-echotik-list-product\ndescription: 搜索和分析TikTok 16个站点的商品销量、达人带货、定价及佣金等数据，用于TikTok Shop选品和商品表现分析。\n---\n\n# EchoTik TikTok 商品搜索\n\n本技能用于搜索和分析 TikTok Shop 商品数据，帮助卖家和营销人员发现商品机会、评估销售表现、识别达人带货商品。参数与响应字段详见 [references/api.md](references/api.md)。\n\n## 能力边界\n\n### ✅ 能力范围\n\n- 按**关键词**搜索 TikTok Shop 商品，支持销量、GMV、价格、评分、评论数、佣金率、达人/视频/播放量等多维筛选与排序。\n- 返回多周期销售数据（1d/7d/15d/30d/60d/90d/total）及对应 GMV、定价、评分、评论、佣金率、达人带货统计等明细。\n- 覆盖 16 个 TikTok Shop 站点（US、ID、TH、PH、MY、VN、GB、MX、SG、SA、BR、ES、JP、DE、IT、FR）。\n\n### ❌ 边界与限制\n\n- **关键词语言**：`keyword` 须翻译为目标站点的当地语言；`categoryKeywordCN` 必须为中文。\n- **佣金率**：以小数存储（0.05 表示 5%），用户给百分比时需先换算。\n- **上架日期**：`firstCrawlDt` 为紧凑整数格式 `YYYYMMDD`（如 `20240101`）。\n- **默认站点**：用户未指定站点时默认 `US`。\n- **不在范围内**：TikTok 达人/创作者分析（粉丝数、互动率）；TikTok 视频表现分析（单条视频的播放、点赞、分享）；TikTok 广告/广告系列管理；Amazon、Shopee 等非 TikTok 平台数据；TikTok Shop 店铺级分析；Listing 创建或优化建议；物流、履约或发货分析。\n\n## 核心概念\n\nEchoTik 是一个 TikTok Shop 数据分析平台，跟踪多个 TikTok 站点的商品表现。本工具提供基于关键词的商品搜索与丰富的筛选能力，返回商品销量（1d/7d/15d/30d/60d/90d/total）、GMV、定价、评分、评论数、佣金率及达人带货统计等明细。\n\n**销售指标**：商品包含多周期销售数据——1 天、7 天、15 天、30 天、60 天、90 天及总销量；GMV 同样按此粒度返回。\n\n**佣金率**：以小数存储（0.05 表示 5%）。当用户指定百分比时，传入 API 前需先换算为小数。\n\n**上架日期**：`firstCrawlDt` 字段使用紧凑整数格式 `YYYYMMDD`（如 `20240101` 表示 2024 年 1 月 1 日）。\n\n## 调用方式\n\n- **API 端点**：`POST /echotik/listProduct`（完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/echotik_list_product.py '' [--inline]`\n- **成本约束**：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `/linkfox///data/linkfox-echotik-list-product-.json`（`` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq`或`ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 使用示例\n\n**1. 基础关键词搜索 —— 查某关键词的热销商品**\n```json\n{\n \"keyword\": \"phone case\",\n \"region\": \"US\",\n \"productSortField\": 1,\n \"sortType\": 1,\n \"pageSize\": 20\n}\n```\n\n**2. 高佣金商品发现 —— 佣金率 >= 10% 的商品**\n```json\n{\n \"keyword\": \"beauty\",\n \"region\": \"US\",\n \"minProductCommissionRate\": 0.10,\n \"productSortField\": 5,\n \"sortType\": 1\n}\n```\n\n**3. 新品趋势 —— 近期上架且 30 天销量强劲**\n```json\n{\n \"keyword\": \"gadget\",\n \"region\": \"US\",\n \"minFirstCrawlDt\": 20250101,\n \"minTotalSale30dCnt\": 1000,\n \"productSortField\": 5,\n \"sortType\": 1\n}\n```\n\n**4. 达人热推商品 —— 多达人推广的商品**\n```json\n{\n \"keyword\": \"skincare\",\n \"region\": \"US\",\n \"minTotalIflCnt\": 50,\n \"minTotalViewsCnt\": 1000000,\n \"productSortField\": 1,\n \"sortType\": 1\n}\n```\n\n**5. 平价高销量 —— 低价 + 高销量**\n```json\n{\n \"keyword\": \"accessories\",\n \"region\": \"US\",\n \"maxSpuAvgPrice\": 10,\n \"minTotalSaleCnt\": 5000,\n \"productSortField\": 2,\n \"sortType\": 1\n}\n```\n\n**6. 东南亚市场探索**\n```json\n{\n \"keyword\": \"fashion\",\n \"region\": \"TH\",\n \"minTotalSale30dCnt\": 500,\n \"productSortField\": 7,\n \"sortType\": 1\n}\n```\n\n## 展示规则\n\n1. **清晰呈现数据**：以结构化表格展示关键列——商品名称、价格、总销量、30 天销量、GMV、评分、佣金率、推广达人数。\n2. **币种感知**：展示价格和 GMV 时附上响应中的货币字段。\n3. **佣金格式**：佣金率以百分比展示便于阅读（如 0.05 显示为「5%」）。\n4. **数据量提示**：当结果 `total` 较大时，展示当前页数据并告知可用总数；建议调整筛选或翻页以继续浏览。\n5. **图片引用**：若返回 `imageUrl` 或 `coverUrl`，提示用户商品图片可用。\n6. **错误处理**：查询失败时依据响应说明原因，并建议调整参数。\n7. **关键词翻译提醒**：当用户面向非英语站点时，提醒关键词应使用该站点的当地语言以获得更好结果。\n\n## 用户表达与场景速查\n\n**适用** —— TikTok 商品搜索与表现分析：\n\n| 用户说 | 场景 |\n|--------|------|\n| \"TikTok 上什么火\"、\"TikTok 热销品\" | 按销量排序的关键词搜索 |\n| \"TikTok 高佣金商品\" | 按佣金率筛选 |\n| \"TikTok Shop 美国站什么卖得好\" | 按区域搜索销量商品 |\n| \"TikTok 新爆品\" | 按上架日期 + 销量筛选 |\n| \"哪些商品很多达人在推\" | 按达人数筛选 |\n| \"TikTok 便宜又高销量的商品\" | 按价格 + 销量筛选 |\n| \"东南亚 TikTok 选品\" | 搜索指定东南亚区域 |\n| \"TikTok 上好评多的商品\" | 按评分 + 评论数筛选 |\n\n不适用场景见上方【能力边界】。\n\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\n---\n\n# EchoTik-TikTok商品搜索 API 参考\n\n## 调用规范\n\n- **请求地址**：`${LINKFOX_TOOL_GATEWAY}/echotik/listProduct`\n- **请求方式**：POST，Content-Type: application/json\n- **认证方式**：Header `Authorization: `，api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\n\n## 请求参数\n\nPOST Body（JSON）：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| keyword | string | 否 | 商品关键词（请翻译为当地语言）。最大长度 1000 |\n| region | string | 否 | 区域，默认 `US`。可选值：US（美国）、ID（印度尼西亚）、TH（泰国）、PH（菲律宾）、MY（马来西亚）、VN（越南）、GB（英国）、MX（墨西哥）、SG（新加坡）、SA（沙特阿拉伯）、BR（巴西）、ES（西班牙）、JP（日本）、DE（德国）、IT（意大利）、FR（法国） |\n| categoryKeywordCN | string | 否 | 商品分类（请输入中文）。最大长度 1000 |\n| minTotalSaleCnt | integer | 否 | 总销量（最小值） |\n| maxTotalSaleCnt | integer | 否 | 总销量（最大值） |\n| minTotalSale30dCnt | integer | 否 | 30天销量（最小值） |\n| maxTotalSale30dCnt | integer | 否 | 30天销量（最大值） |\n| minTotalSaleGmvAmt | string | 否 | 商品交易总额（最小值）。最大长度 1000 |\n| maxTotalSaleGmvAmt | string | 否 | 商品交易总额（最大值）。最大长度 1000 |\n| minTotalSaleGmv30dAmt | string | 否 | 商品交易总额（30天）（最小值）。最大长度 1000 |\n| maxTotalSaleGmv30dAmt | string | 否 | 商品交易总额（30天）（最大值）。最大长度 1000 |\n| minSpuAvgPrice | number | 否 | SPU平均价格（最小值） |\n| maxSpuAvgPrice | number | 否 | SPU平均价格（最大值） |\n| minProductRating | number | 否 | 商品评分（最小值） |\n| maxProductRating | number | 否 | 商品评分（最大值） |\n| minReviewCount | integer | 否 | 商品评价数（最小值） |\n| maxReviewCount | integer | 否 | 商品评价数（最大值） |\n| minProductCommissionRate | number | 否 | 商品佣金比例（最小值），输入值为百分比时自动转成小数，例如：5%->0.05 |\n| maxProductCommissionRate | number | 否 | 商品佣金比例（最大值），输入值为百分比时自动转成小数，例如：5%->0.05 |\n| minTotalIflCnt | integer | 否 | 带货达人数（最小值） |\n| maxTotalIflCnt | integer | 否 | 带货达人数（最大值） |\n| minTotalVideoCnt | integer | 否 | 带货视频数（最小值） |\n| maxTotalVideoCnt | integer | 否 | 带货视频数（最大值） |\n| minTotalViewsCnt | integer | 否 | 带货播放数（最小值） |\n| maxTotalViewsCnt | integer | 否 | 带货播放数（最大值） |\n| minFirstCrawlDt | integer | 否 | 商品上架时间（最小值），格式 YYYYMMDD（例如：20200101 代表 2020-01-01） |\n| maxFirstCrawlDt | integer | 否 | 商品上架时间（最大值），格式 YYYYMMDD |\n| saleDays | integer | 否 | 商品上架销售天数，单位是天 |\n| productSortField | integer | 否 | 排序字段：1=总销量、2=商品交易总额、3=SPU平均价格、4=7天销量、5=30天销量、6=7天商品交易额、7=30天商品交易额。默认 `1` |\n| sortType | integer | 否 | 排序方式：0=升序（asc）、1=降序（desc）。默认 `1` |\n| pageNum | integer | 否 | 分页页码。默认 `1` |\n| pageSize | integer | 否 | 每页条数。默认 `50` |\n\n\n## 响应结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| total | integer | 记录数 |\n| products | array | 产品信息列表（详见下方） |\n| columns | array | 渲染的列 |\n| type | string | 渲染的样式 |\n| costToken | integer | 消耗token |\n\n### 产品对象字段\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| productId | string | 商品唯一标识ID |\n| productName | string | 商品名称 |\n| title | string | 商品名称 |\n| imageUrl | string | 商品图片URL |\n| coverUrl | string | 封面图URL列表 |\n| productImageUrls | array | 商品图片URL列表 |\n| categoryName | string | 商品类目名称 |\n| categoryIds | array | 商品类目ID列表 |\n| region | string | 区域代码 |\n| currency | string | 货币 |\n| price | number | 商品价格 |\n| minPrice | number | 最低价格 |\n| maxPrice | number | 最高价格 |\n| spuAvgPrice | number | SPU平均价格 |\n| productRating | number | 商品评分 |\n| reviewCount | integer | 评论数量 |\n| ratings | integer | 评论数 |\n| productCommissionRate | number | 商品佣金比例 |\n| totalSaleCnt | integer | 总销量 |\n| totalSale1dCnt | integer | 1天内总销量 |\n| totalSale7dCnt | integer | 7天内总销量 |\n| totalSale15dCnt | integer | 15天内总销量 |\n| totalSale30dCnt | integer | 30天内总销量 |\n| totalSale60dCnt | integer | 60天内总销量 |\n| totalSale90dCnt | integer | 90天内总销量 |\n| monthlySalesUnits | integer | 月销量 |\n| totalSaleGmvAmt | number | 总销售额 |\n| totalSaleGmv1dAmt | number | 1天内总销售额 |\n| totalSaleGmv7dAmt | number | 7天内总销售额 |\n| totalSaleGmv15dAmt | number | 15天内总销售额 |\n| totalSaleGmv30dAmt | number | 30天内总销售额 |\n| totalSaleGmv60dAmt | number | 60天内总销售额 |\n| totalSaleGmv90dAmt | number | 90天内总销售额 |\n| firstCrawlDt | integer | 上架日期 |\n| availableDate | string | 上架时间(时间戳) |\n| discount | string | 折扣信息 |\n| freeShippingText | string | 是否包邮 |\n| offMarkText | string | 是否有优惠标记 |\n| salesFlagText | string | 带货方式 |\n| salesTrendFlagText | string | 销售趋势标记 |\n| isSShopText | string | 是否S店 |\n| salePropsInfo | array | 销售属性信息（商品规格） |\n| sourceTool | string | 来源工具 |\n| sourceType | string | 商品来源 |\n| asin | string | 产品ID |\n\n## 错误码\n\n正常情况下，接口的 HTTP 状态码均为 200，业务的成功与否通过响应体中的 errorCode 字段区分（errorCode = 200 表示成功，其他值表示业务错误）。当遇到未授权等情况时，HTTP 状态码为 401，且对应的 errorCode 也是 401。\n\n| errcode | 含义 | 处理建议 |\n|---------|------|----------|\n| 200 | 成功 | 正常解析业务字段 |\n| 401 | 认证失败 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 402 | 积分不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 其他非200值 | 业务异常 | 参考 `errmsg` 字段获取具体错误原因 |\n\n错误响应示例：\n\n```json\n{\n \"errcode\": 401,\n \"errmsg\": \"authorized error\"\n}\n```\n\n## curl 示例\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/echotik/listProduct \\\n -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"keyword\": \"phone case\",\n \"region\": \"US\",\n \"minTotalSale30dCnt\": 1000,\n \"productSortField\": 5,\n \"sortType\": 1,\n \"pageSize\": 20\n }'\n```\n\nFile v1.2.3:references/linkfox-echotik-product-video.md\n\n---\nname: linkfox-echotik-product-video\ndescription: 查询TikTok商品的带货视频数据，包括播放、互动、视频销量及GMV，用于分析视频营销与达人带货效果。\n---\n\n# EchoTik - TikTok 商品视频\n\n本技能用于查询 TikTok Shop 商品关联的带货视频数据，帮助卖家分析视频营销表现，识别有效的达人内容策略。参数与响应字段详见 [references/api.md](references/api.md)。\n\n## 能力边界\n\n### ✅ 能力范围\n\n- 查询指定 TikTok 商品的关联带货视频列表。\n- 展示视频互动指标（播放、点赞、评论、分享、收藏）、估算销量与 GMV、视频元数据（时长、分辨率、发布日期）以及创作者（达人）ID。\n- 支持按播放量、点赞数、分享数、视频销量、视频 GMV、发布时间排序。\n- 支持按达人 ID、发布时间区间筛选。\n\n### ❌ 边界与限制\n\n- **必填输入**：必须提供 `productId`。商品 ID 可从 `linkfox-echotik-product-search` 或 `linkfox-echotik-new-product-rank` 获取。\n- **分页上限**：`pageSize` 须为 10 的倍数，最大 100；后端按每页 10 条分批拉取后合并。\n- **估算数据**：视频销量与 GMV 为估算值，非精确统计。\n- **播放地址时效**：`playAddr` 字段可能快速过期，分享优先使用 `officialUrl`。\n- **不在范围内**：商品搜索（用 `linkfox-echotik-product-search`）；TikTok 新品排名（用 `linkfox-echotik-new-product-rank`）；达人档案分析（粉丝数、简介、整体表现）；TikTok 直播数据；视频内容创作或剪辑建议；TikTok 广告/广告活动管理；非 TikTok 平台视频数据。\n\n## 核心概念\n\n本工具检索与特定 TikTok 商品关联的带货视频列表。每条视频记录包含互动指标（播放、点赞、评论、分享、收藏）、估算销量归因（视频销量与 GMV）、视频元数据（时长、分辨率、发布日期）及创作者（达人）ID，帮助卖家理解哪些视频为商品带来了最多销量、哪些内容模式最有效。\n\n- **排序字段**：可按播放量（1）、点赞数（2）、分享数（3）、视频销量（4）、视频 GMV（5）、发布时间（6）排序。\n- **分页**：`pageSize` 须为 10 的倍数，最大 100；后端按每页 10 条分批拉取后合并。\n\n## 调用方式\n\n- **API 端点**：`POST /echotik/listProductVideo`（完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/echotik_list_product_video.py '' [--inline]`\n- **成本约束**：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `/linkfox///data/linkfox-echotik-product-video-.json`（`` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq`或`ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 使用示例\n\n**1. 查询某商品播放量最高的视频**\n```json\n{\n \"productId\": \"1729382310407603945\",\n \"productVideoSortField\": 1,\n \"sortType\": 1,\n \"pageSize\": 20\n}\n```\n\n**2. 查找转化最高的视频（按视频销量）**\n```json\n{\n \"productId\": \"1729382310407603945\",\n \"productVideoSortField\": 4,\n \"sortType\": 1,\n \"pageSize\": 20\n}\n```\n\n**3. 查询某商品下指定达人的视频**\n```json\n{\n \"productId\": \"1729382310407603945\",\n \"userId\": \"7234567890123456789\",\n \"productVideoSortField\": 1,\n \"sortType\": 1\n}\n```\n\n**4. 查询时间区间内的视频（按 GMV 排序）**\n```json\n{\n \"productId\": \"1729382310407603945\",\n \"minCreateTime\": 1717200000,\n \"maxCreateTime\": 1719792000,\n \"productVideoSortField\": 5,\n \"sortType\": 1\n}\n```\n\n**5. 按发布时间排序（最新优先）**\n```json\n{\n \"productId\": \"1729382310407603945\",\n \"productVideoSortField\": 6,\n \"sortType\": 1,\n \"pageSize\": 50\n}\n```\n\n## 展示规则\n\n1. **以表格呈现数据**：展示视频描述（过长截断）、播放量、点赞、评论、分享、视频销量、视频 GMV、发布日期、达人 ID。\n2. **附原始链接**：`officialUrl` 可用时提供，便于用户在 TikTok 观看视频。\n3. **估算值提示**：视频销量与 GMV 为估算值，提醒用户这些是近似数据。\n4. **封面图**：存在 `coverUrl` 时提及，告知用户视频缩略图可用。\n5. **时长格式化**：将 `duration`（秒）转为可读格式（如 90 秒显示为 \"1:30\"）。\n6. **话题标签**：存在 `hashTag` 时展示，帮助用户理解内容主题。\n7. **播放地址时效**：`playAddr` 字段可能快速过期；分享优先使用 `officialUrl`。\n\n## 用户表达与场景速查\n\n**适用** —— TikTok 商品带货视频查询：\n\n| 用户说 | 场景 |\n|--------|------|\n| \"看看这个 TikTok 商品的带货视频\" | 按 productId 查询视频 |\n| \"哪些视频给这个商品带来最多销量\" | 按视频销量排序（字段 4） |\n| \"有哪些达人在推这个商品\" | 通用视频列表查询 |\n| \"看某位达人推这个商品的视频\" | 按 userId 筛选 |\n| \"这个商品最近的带货视频\" | 按时间区间筛选或按发布时间排序 |\n| \"这个 TikTok 商品 GMV 最高的视频是哪些\" | 按视频 GMV 排序（字段 5） |\n| \"分析这个商品的视频营销表现\" | 综合视频列表查询 |\n\n不适用场景见上方【能力边界】。\n\n当用户提到\"TikTok 视频\"时，需判断其想要的是某具体商品关联的视频（本技能适用）还是通用的 TikTok 视频分析（不适用）。若用户提到商品 ID 或询问\"有哪些视频在推商品 X\"，则适用本技能；若仅泛泛询问热门视频而无商品上下文，则不适用。\n\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\n---\n\n# EchoTik-TikTok商品视频 API 参考\n\n## 调用规范\n\n- **请求地址**：`${LINKFOX_TOOL_GATEWAY}/echotik/listProductVideo`\n- **请求方式**：POST，Content-Type: application/json\n- **认证方式**：Header `Authorization: `，api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\n\n## 请求参数\n\nPOST Body（JSON）：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| productId | string | 是 | 商品ID。最大长度 1000 |\n| userId | string | 否 | 达人ID，用于筛选特定达人的带货视频。最大长度 1000 |\n| productVideoSortField | integer | 否 | 排序字段：1=播放量、2=点赞数、3=分享数、4=视频销量、5=视频销售GMV、6=发布时间。默认 `1` |\n| sortType | integer | 否 | 排序方式：0=升序、1=降序。默认 `1` |\n| minCreateTime | integer | 否 | 视频发布时间区间-开始（秒级时间戳） |\n| maxCreateTime | integer | 否 | 视频发布时间区间-结束（秒级时间戳） |\n| pageNum | integer | 否 | 分页页码。默认 `1` |\n| pageSize | integer | 否 | 分页条数（须为10的倍数，最大100；官方接口单页上限10，内部按10每页多次拉取后合并）。默认 `50` |\n\n## 响应结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| total | integer | 记录数 |\n| data | array | 视频列表（见下方视频对象） |\n| columns | array | 渲染的列 |\n| type | string | 渲染的样式 |\n| costToken | integer | 消耗token |\n\n### 视频对象\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| videoId | string | 视频ID |\n| productId | string | 商品ID |\n| userId | string | 达人ID |\n| videoDesc | string | 视频描述 |\n| officialUrl | string | TikTok官方视频地址 |\n| covet | integer | 分享数 |\n| totalFavoritesCnt | integer | 收藏数 |\n| totalVideoSaleCnt | integer | 视频销量（估算） |\n| totalVideoSaleGmvAmt | integer | 视频销售GMV（估算） |\n| hashTag | string | 话题标签 |\n| createDate | string (date) | 视频发布日期 |\n| region | string | 区域代码 |\n| sourceTool | string | 来源工具 |\n| sourceType | string | 商品来源 |\n\n## 错误码\n\n正常情况下，接口的 HTTP 状态码均为 200，业务的成功与否通过响应体中的 errorCode 字段区分（errorCode = 200 表示成功，其他值表示业务错误）。当遇到未授权等情况时，HTTP 状态码为 401，且对应的 errorCode 也是 401。\n\n| errcode | 含义 | 处理建议 |\n|---------|------|----------|\n| 200 | 成功 | 正常解析业务字段 |\n| 401 | 认证失败 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 402 | 积分不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 其他非200值 | 业务异常 | 参考 `errmsg` 字段获取具体错误原因 |\n\n错误响应示例：\n\n```json\n{\n \"errcode\": 401,\n \"errmsg\": \"authorized error\"\n}\n```\n\n## curl 示例\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/echotik/listProductVideo \\\n -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"productId\": \"1729382310407603945\",\n \"productVideoSortField\": 1,\n \"sortType\": 1,\n \"pageSize\": 20\n }'\n```\n\nFile v1.2.3:references/linkfox-fastmoss-product-rank-top-selling.md\n\n---\nname: linkfox-fastmoss-product-rank-top-selling\ndescription: 基于FastMoss数据，按日/周/月维度和品类分析TikTok全球电商市场的热销商品排行榜与GMV排名，用于爆品分析与选品调研。\n---\n\n# FastMoss TikTok 热销榜单（FastMoss Product Rank Top Selling）\n\n本技能用于查询 TikTok Shop 全球电商市场的热销商品排行榜，帮助跨境卖家按日/周/月维度及类目维度发现爆品、分析销量与 GMV 排名。参数与响应字段详见 [references/api.md](references/api.md)。\n\n## 能力边界\n\n### ✅ 能力范围\n\n- 查询 TikTok Shop 9 个全球市场（US、GB、MX、ES、ID、VN、MY、TH、PH）的热销商品排行榜。\n- 支持日、周、月三种时间粒度，可按销量、GMV、增长率等字段排序。\n- 支持按类目筛选，查看特定类目下的热销商品。\n- 返回商品价格、销量、GMV、增长率、佣金率、店铺信息等多维数据。\n\n### ❌ 边界与限制\n\n- **dateInfo 必填**：`type` 与 `value` 必须同时提供且格式严格匹配（day=`YYYY-MM-DD`，week=`YYYY-周数`如 `2025-18`，month=`YYYY-MM`）。\n- **不支持关键词搜索**：本工具不支持按关键词搜索商品（请使用 linkfox-fastmoss-product-search）。\n- **分页上限**：`pageSize` 最大 10，默认 10。\n- **数据时效**：数据存在 T+1 统计延迟。\n- **类目语言**：`category` 参数须为英文，非英文输入需先翻译。\n- **不在范围内**：Amazon 选品与 ABA 关键词；TikTok 广告投放与广告管理；TikTok 内容创作与视频剪辑；商品评论与 Listing 文案；TikTok 关键词商品搜索（用 linkfox-fastmoss-product-search）；利润率计算与定价策略。\n\n## 核心概念\n\nTikTok 热销榜单追踪 TikTok Shop 在 9 个全球市场表现最佳的商品，反映其在销量、GMV、增长率上的领先情况，是 TikTok 选品、趋势分析与竞争情报的核心工具。\n\n**数据范围**：覆盖 9 个 TikTok Shop 市场，支持日/周/月三种时间粒度（通过 `dateInfo` 参数控制）。每个商品包含销量、GMV、增长率、佣金率、店铺、类目等信息。\n\n**dateInfo 格式（关键）**：\n- type: `\"day\"` -> value: `\"2025-02-01\"`（YYYY-MM-DD）\n- type: `\"week\"` -> value: `\"2025-18\"`（年-周数）\n- type: `\"month\"` -> value: `\"2025-02\"`（年-月）\n\n**分页**：使用 `page`（页码，从 1 开始）与 `pageSize`（每页条数，最大 10，默认 10）翻页。\n\n## 支持市场\n\n| 代码 | 市场 |\n|------|------|\n| US | 美国 |\n| GB | 英国 |\n| MX | 墨西哥 |\n| ES | 西班牙 |\n| ID | 印度尼西亚 |\n| VN | 越南 |\n| MY | 马来西亚 |\n| TH | 泰国 |\n| PH | 菲律宾 |\n\n用户未指定市场时默认使用 **US**。\n\n## 调用方式\n\n- **API 端点**：`POST /fastmoss/productRankTopSelling`（完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/fastmoss_product_rank_top_selling.py '' [--inline]`\n- **成本约束**：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `/linkfox///data/linkfox-fastmoss-product-rank-top-selling-.json`（`` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq`或`ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 使用示例\n\n**1. 美国当日热销商品（日榜）**\n查询美国市场某一天的热销商品。\n```\nregion: \"US\", dateInfo: {\"type\": \"day\", \"value\": \"2026-04-15\"}\n```\n\n**2. 英国周榜热销**\n查看英国市场的周度热销商品。\n```\nregion: \"GB\", dateInfo: {\"type\": \"week\", \"value\": \"2026-15\"}\n```\n\n**3. 东南亚月度 GMV 领先商品**\n查看印尼市场月度热销商品并按 GMV 排序。\n```\nregion: \"ID\", dateInfo: {\"type\": \"month\", \"value\": \"2026-03\"}, orderby: {\"field\": \"gmv\", \"order\": \"desc\"}\n```\n\n**4. 指定类目排行**\n查找特定类目下的热销商品。\n```\nregion: \"US\", dateInfo: {\"type\": \"day\", \"value\": \"2026-04-15\"}, category: \"Beauty\"\n```\n\n## 展示规则\n\n1. **只呈现数据**：以清晰表格展示查询结果，不做主观商业建议。\n2. **增长率**：增长率为百分比，展示时带 % 符号。\n3. **佣金率**：佣金率为基点（1000 = 10%），展示时换算为百分比。\n4. **币种**：不同市场币种不同，价格须始终附带币种展示。\n5. **dateInfo 格式**：校验并提醒用户所选时间粒度的正确格式。\n6. **下架状态**：`offShelvesText` 值 \"是\" 表示已下架，\"否\" 表示在售，需向用户说明。\n\n## 用户表达与场景速查\n\n**适用** —— TikTok 热销商品排行与趋势分析：\n\n| 用户说 | 场景 |\n|--------|------|\n| \"TikTok 上什么最火\"、\"TikTok 热销榜\" | 热销排行查询 |\n| \"TikTok 本周爆款\"、\"TikTok Shop 热门商品\" | 周/日榜查询 |\n| \"TikTok GMV 排名\"、\"TikTok 收入最高的商品\" | 按 GMV 排序的排行 |\n| \"TikTok 类目热销\"、\"TikTok 美妆热销榜\" | 指定类目排行 |\n| \"TikTok 选品周报\"、\"月度热销榜\" | 时间维度分析 |\n| \"FastMoss 热销\"、\"FastMoss 排行数据\" | 直接数据源引用 |\n| \"TikTok 上增长最快的商品\" | 按增长率排序的排行 |\n\n不适用场景见上方【能力边界】。\n\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\n---\n\n# FastMoss-TikTok热销榜单 API 参考\n\n## 调用规范\n\n- **请求地址**：`${LINKFOX_TOOL_GATEWAY}/fastmoss/productRankTopSelling`\n- **请求方式**：POST，Content-Type: application/json\n- **认证方式**：Header `Authorization: `，api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\n\n## 请求参数\n\nPOST Body（JSON）：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| region | string | 是 | 市场区域代码。可选值：US（美国）、GB（英国）、MX（墨西哥）、ES（西班牙）、ID（印度尼西亚）、VN（越南）、MY（马来西亚）、TH（泰国）、PH（菲律宾） |\n| dateInfo | object | 是 | 日期规格对象，包含 `type` 和 `value` 两个字段 |\n| dateInfo.type | string | 是 | 时间粒度：`day`（日）、`week`（周）、`month`（月） |\n| dateInfo.value | string | 是 | 日期值：day 格式 `YYYY-MM-DD`，week 格式 `YYYY-周数`（如 `2025-18`），month 格式 `YYYY-MM` |\n| category | string | 否 | 商品类目名称（英文），会匹配到 TikTok 类目 ID。非英文输入需先翻译为英文 |\n| orderby | object | 否 | 排序规则对象，包含 `field` 和 `order` 两个字段 |\n| orderby.field | string | 否 | 排序字段：`units_sold`（销量）、`gmv`（销售额）、`total_units_sold`（总销量）、`total_gmv`（总销售额）、`growth_rate`（增长率） |\n| orderby.order | string | 否 | 排序方向：`desc`（降序）、`asc`（升序），默认 `desc` |\n| page | integer | 否 | 页码，默认 `1` |\n| pageSize | integer | 否 | 每页条数，最大 `10`，默认 `10` |\n\n## 响应结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| total | integer | 记录数 |\n| products | array | 热销商品列表（见下方商品对象） |\n| columns | array | 渲染的列 |\n| type | string | 渲染的样式 |\n| costToken | integer | 消耗 token |\n\n### 商品对象\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| title | string | 商品名称 |\n| productId | string | 商品 ID |\n| region | string | 区域代码 |\n| price | number | 商品价格 |\n| minPrice | number | 最低价格 |\n| maxPrice | number | 最高价格 |\n| currency | string | 货币 |\n| totalSaleCnt | integer | 总销量 |\n| totalSale1dCnt | integer | 近1天销量（dateType=day 时返回） |\n| totalSale7dCnt | integer | 近7天销量（dateType=week 时返回） |\n| totalSale30dCnt | integer | 近30天销量（dateType=month 时返回） |\n| totalSaleGmvAmt | number | 总销售额 |\n| totalSaleGmv1dAmt | number | 近1天销售额（dateType=day 时返回） |\n| totalSaleGmv7dAmt | number | 近7天销售额（dateType=week 时返回） |\n| totalSaleGmv30dAmt | number | 近30天销售额（dateType=month 时返回） |\n| growthRate | number | 增长率（百分比） |\n| shopName | string | 店铺名称 |\n| shopTotalUnitsSold | integer | 店铺总销量 |\n| shopSellerId | string | 店铺卖家 ID |\n| categoryName | string | 商品类目 |\n| productCommissionRate | number | 商品佣金比例（基点，1000=10%） |\n| imageUrl | string | 商品图片 URL |\n| offShelvesText | string | 是否下架（\"是\"=已下架，\"否\"=在售） |\n\n## 错误码\n\n正常情况下，接口的 HTTP 状态码均为 200，业务的成功与否通过响应体中的 errorCode 字段区分（errorCode = 200 表示成功，其他值表示业务错误）。当遇到未授权等情况时，HTTP 状态码为 401，且对应的 errorCode 也是 401。\n\n| errcode | 含义 | 处理建议 |\n|---------|------|----------|\n| 200 | 成功 | 正常解析业务字段 |\n| 401 | 认证失败 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 402 | 积分不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 其他非200值 | 业务异常 | 参考 `errmsg` 字段获取具体错误原因 |\n\n错误响应示例：\n\n```json\n{\n \"errcode\": 401,\n \"errmsg\": \"authorized error\"\n}\n```\n\n## curl 示例\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/fastmoss/productRankTopSelling \\\n -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"region\": \"US\", \"dateInfo\": {\"type\": \"day\", \"value\": \"2026-04-15\"}, \"page\": 1, \"pageSize\": 10}'\n```\n\nFile v1.2.3:references/linkfox-fastmoss-product-search.md\n\n---\nname: linkfox-fastmoss-product-search\ndescription: 基于FastMoss多维度搜索和筛选TikTok全球电商商品，支持类目、销量、佣金率及GMV等指标分析，用于爆款追踪。\n---\n\n# FastMoss - TikTok 商品搜索\n\n本技能引导你使用 FastMoss 搜索与筛选 TikTok Shop 商品数据，帮助卖家和营销者发现商品机会、评估销售表现，并识别达人带货商品，覆盖全球 15 个 TikTok 市场。参数与响应字段详见 [references/api.md](references/api.md)。\n\n## 能力边界\n\n### ✅ 能力范围\n\n- 基于关键词搜索 TikTok Shop 商品，支持按类目、店铺类型、销量、佣金率、达人数等多维度筛选与排序。\n- 返回商品多周期销量（7 天/28 天/90 天/总销量）、GMV、价格、评分、评论数、佣金率、达人带货统计、店铺信息等详细数据。\n- 覆盖 15 个 TikTok 市场：US、GB、MX、ES、DE、IT、FR、ID、VN、MY、TH、PH、BR、JP、SG。\n\n### ❌ 边界与限制\n\n- **无必填参数**：所有参数均可选，但至少需提供 keyword 或 category 才能返回有意义结果。\n- **分页上限**：每页最多 10 条。\n- **类目语言**：`category` 须为英文类目名称，非英文需先翻译。\n- **佣金率口径**：存储为小数（0.10 = 10%），展示时须转换为百分比。\n- **不在范围内**：TikTok 达人/创作者分析（粉丝数、互动率）；TikTok 视频表现分析（播放、点赞、分享）；TikTok 广告/广告投放管理；Amazon、Shopee 等非 TikTok 平台数据；TikTok Shop 店铺级分析；Listing 创建或优化建议；物流、履约或发货分析。\n- **边界判断**：当用户说\"选品\"或\"在 TikTok 上卖什么\"且涉及按销量、价格或佣金率搜索筛选 TikTok Shop 商品时适用；若涉及内容策略、视频创作或达人拓展，则不适用。\n\n## 核心概念\n\nFastMoss 是知名的 TikTok 电商平台数据追踪平台，覆盖多个 TikTok 市场。本工具提供基于关键词的商品搜索与丰富筛选能力，返回商品多周期销量（7 天/28 天/90 天/总销量）、GMV、价格、评分、评论数、佣金率、达人带货统计、店铺信息等详细数据。\n\n**销量指标**：商品含多周期销量数据——7 天、28 天、90 天及总销量，GMV 同样按此粒度返回。\n\n**佣金率**：以小数存储（0.10 表示 10%），展示时转换为百分比格式。\n\n**店铺类型**：可按本地店铺（1）或跨境店铺（2）筛选；`isCrossBorder` 字段（1=跨境，0=本地）与 `isSShopText` 字段（TikTok 全托管店铺）提供额外店铺分类。\n\n## 调用方式\n\n- **API 端点**：`POST /fastmoss/productSearch`（完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/fastmoss_product_search.py '' [--inline]`\n- **成本约束**：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `/linkfox///data/linkfox-fastmoss-product-search-.json`（`` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq` 或 `ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 使用示例\n\n**1. 关键词搜索——找出热销商品**\n```json\n{\n \"keyword\": \"phone case\",\n \"region\": \"US\",\n \"orderField\": \"total_units_sold\",\n \"pageSize\": 10\n}\n```\n\n**2. 高佣金商品发现——佣金率 ≥ 10% 的商品**\n```json\n{\n \"keyword\": \"beauty\",\n \"region\": \"US\",\n \"commissionRateRange\": {\"min\": 0.10},\n \"orderField\": \"commission_rate\"\n}\n```\n\n**3. 跨境店铺商品——按店铺类型筛选**\n```json\n{\n \"keyword\": \"gadget\",\n \"region\": \"US\",\n \"shopType\": 2,\n \"orderField\": \"day7_units_sold\"\n}\n```\n\n**4. 达人爆款——被大量达人带货的商品**\n```json\n{\n \"keyword\": \"skincare\",\n \"region\": \"US\",\n \"creatorCountRange\": {\"min\": 50},\n \"orderField\": \"creator_count\"\n}\n```\n\n**5. TikTok 热销新品**\n```json\n{\n \"keyword\": \"fashion\",\n \"region\": \"GB\",\n \"isTopSelling\": true,\n \"isNewListed\": true,\n \"orderField\": \"day7_gmv\"\n}\n```\n\n## 展示规则\n\n1. **只呈现数据**：以结构化表格展示关键列——商品名称、价格、总销量、7 天销量、GMV、评分、佣金率、带货达人数，不做主观商业建议。\n2. **佣金格式**：佣金率为小数（0.10 = 10%），展示时转换为百分比。\n3. **跨境标识**：`isCrossBorder`：1 = 跨境店铺，0 = 本地店铺，清晰标注。\n4. **币种标识**：展示价格与 GMV 时附上响应中的 `currency` 字段。\n5. **趋势标签**：直接展示 `salesTrendFlagText` 作为趋势指示。\n6. **店铺标识**：直接展示 `freeShippingText` 与 `isSShopText`（值为可读文本）。\n7. **错误处理**：查询失败时基于响应说明原因，并建议调整参数。\n\n## 用户表达与场景速查\n\n**适用** —— TikTok 商品搜索与选品调研：\n\n| 用户说 | 场景 |\n|--------|------|\n| \"TikTok 上什么火\"、\"TikTok 趋势商品\" | 按销量排序的关键词搜索 |\n| \"TikTok 高佣金商品\" | 按佣金率范围筛选 |\n| \"TikTok Shop 美国什么好卖\" | 按区域+销量的商品搜索 |\n| \"TikTok 跨境店铺商品\" | 按 shopType=2 筛选 |\n| \"哪些商品很多达人在带货\" | 按达人数范围筛选 |\n| \"TikTok 全托管店铺商品\" | 用 isSshop=true 筛选 |\n| \"TikTok 东南亚选品\" | 搜索指定东南亚区域 |\n| \"TikTok 热销新品\" | 用 isTopSelling + isNewListed 标签 |\n| \"FastMoss 商品数据\" | 直接平台查询 |\n\n不适用场景见上方【能力边界】。\n\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\n---\n\n# FastMoss-TikTok商品搜索 API 参考\n\n## 调用规范\n\n- **请求地址**：`${LINKFOX_TOOL_GATEWAY}/fastmoss/productSearch`\n- **请求方式**：POST，Content-Type: application/json\n- **认证方式**：Header `Authorization: `，api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\n\n## 请求参数\n\nPOST Body（JSON）：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| keyword | string | 否 | 搜索关键词（商品标题模糊匹配） |\n| region | string | 否 | 市场区域代码。可选值：US（美国）、GB（英国）、MX（墨西哥）、ES（西班牙）、DE（德国）、IT（意大利）、FR（法国）、ID（印度尼西亚）、VN（越南）、MY（马来西亚）、TH（泰国）、PH（菲律宾）、BR（巴西）、JP（日本）、SG（新加坡） |\n| category | string | 否 | 英文类目名称，系统自动匹配TikTok类目ID。非英文需先翻译为英文 |\n| shopType | integer | 否 | 店铺类型：1=本地店铺，2=跨境店铺 |\n| isTopSelling | boolean | 否 | 仅筛选热销商品 |\n| isNewListed | boolean | 否 | 仅筛选新上架商品 |\n| isSshop | boolean | 否 | 仅筛选TikTok全托管（S-shop）商品 |\n| isFreeShipping | boolean | 否 | 仅筛选包邮商品 |\n| isLocalWarehouse | boolean | 否 | 仅筛选本地仓发货商品 |\n| unitsSoldRange | object | 否 | 销量范围筛选，格式：`{\"min\": 100, \"max\": 5000}` |\n| commissionRateRange | object | 否 | 佣金率范围筛选，格式：`{\"min\": 0.05, \"max\": 0.20}`（小数，0.10=10%） |\n| creatorCountRange | object | 否 | 带货达人数范围筛选，格式：`{\"min\": 10, \"max\": 500}` |\n| orderField | string | 否 | 排序字段：day7_units_sold（7天销量）、day7_gmv（7天GMV）、commission_rate（佣金率）、total_units_sold（总销量）、total_gmv（总GMV）、creator_count（达人数）。默认降序排列 |\n| page | integer | 否 | 页码，默认 1 |\n| pageSize | integer | 否 | 每页条数，最大 10，默认 10 |\n\n## 响应结构\n\n### 顶层字段\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| total | integer | 符合条件的总记录数 |\n| products | array | 商品信息列表（详见下方） |\n| columns | array | 渲染列定义 |\n| type | string | 渲染样式类型 |\n| costToken | integer | 消耗 token 数 |\n\n### 商品对象字段（products 数组）\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| title | string | 商品标题 |\n| productId | string | 商品唯一标识ID |\n| region | string | 市场区域代码 |\n| price | number | 商品价格 |\n| minPrice | number | 最低价格 |\n| maxPrice | number | 最高价格 |\n| currency | string | 货币代码 |\n| totalSaleCnt | integer | 累计总销量 |\n| totalSale1dCnt | integer | 1天销量 |\n| totalSale7dCnt | integer | 7天销量 |\n| totalSale28dCnt | integer | 28天销量 |\n| totalSale90dCnt | integer | 90天销量 |\n| totalSaleGmvAmt | number | 累计总GMV |\n| totalSaleGmv7dAmt | number | 7天GMV |\n| totalSaleGmv28dAmt | number | 28天GMV |\n| totalVideoCnt | integer | 带货视频数 |\n| totalLiveCnt | integer | 直播带货数 |\n| totalIflCnt | integer | 带货达人数 |\n| productCommissionRate | number | 商品佣金比例（小数，0.10=10%） |\n| productRating | number | 商品评分 |\n| reviewCount | integer | 评论数量 |\n| skuCount | integer | SKU数量 |\n| shopName | string | 店铺名称 |\n| shopSellerId | string | 卖家ID |\n| shopTotalUnitsSold | integer | 店铺总销量 |\n| isCrossBorder | integer | 是否跨境：1=跨境，0=本地 |\n| isSShopText | string | 是否全托管店铺（是/否） |\n| freeShippingText | string | 是否包邮（是/否） |\n| availableDate | string | 上架时间 |\n| categoryName | string | 商品品类名称 |\n| salesTrendFlagText | string | 销售趋势标记 |\n| tiktokUrl | string | TikTok商品链接 |\n| fastmossUrl | string | FastMoss商品详情链接 |\n| imageUrl | string | 商品图片URL |\n\n## 错误码\n\n正常情况下，接口的 HTTP 状态码均为 200，业务的成功与否通过响应体中的 errorCode 字段区分（errorCode = 200 表示成功，其他值表示业务错误）。当遇到未授权等情况时，HTTP 状态码为 401，且对应的 errorCode 也是 401。\n\n| errcode | 含义 | 处理建议 |\n|---------|------|----------|\n| 200 | 成功 | 正常解析业务字段 |\n| 401 | 认证失败 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 402 | 积分不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 其他非200值 | 业务异常 | 参考 `errmsg` 字段获取具体错误原因 |\n\n错误响应示例：\n\n```json\n{\n \"errcode\": 401,\n \"errmsg\": \"authorized error\"\n}\n```\n\n## curl 示例\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/fastmoss/productSearch \\\n -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"keyword\": \"phone case\",\n \"region\": \"US\",\n \"orderField\": \"day7_units_sold\",\n \"pageSize\": 10\n }'\n```\n\n带范围筛选的示例：\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/fastmoss/productSearch \\\n -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"keyword\": \"beauty\",\n \"region\": \"US\",\n \"commissionRateRange\": {\"min\": 0.10},\n \"creatorCountRange\": {\"min\": 50},\n \"orderField\": \"commission_rate\",\n \"pageSize\": 10\n }'\n```\n\nFile v1.2.3:references/linkfox-tiktok-video-auth.md\n\n---\nname: linkfox-tiktok-video-auth\ndescription: 提供 TikTok 视频号达人 OAuth 授权、已授权账号列表、令牌查询与 access_token 刷新能力。\n---\n\n# TikTok 视频号授权与令牌管理\n\n本 skill 负责 TikTok 视频上传模块（`/tiktokVideo`）的达人 OAuth 授权、已授权账号列表、令牌查询与刷新，是后续通过 `/tiktokVideo/developerProxy` 调用视频上传等开放接口的前置依赖。底层经 LinkFox 网关对接紫鸟开放平台，固定 `appType=creator`（达人端带货 / 视频上传）。接口参数、响应字段与错误码详见 [references/api.md](references/api.md)。\n\n## 能力边界\n\n### ✅ 能力范围\n\n- 生成 TikTok 达人/视频号 OAuth 授权链接，引导用户在浏览器完成授权。\n- 列出当前用户已授权的视频号账号。\n- 按 `openId` 查询已入库的访问令牌（供下游 `/tiktokVideo/developerProxy` 作为 `ttsAccessToken` 使用）。\n- 用 `refreshToken` 刷新过期的 `accessToken` 并回写数据库。\n\n### ❌ 边界与限制\n\n- **模块独立**：本 skill 令牌仅适用于 `/tiktokVideo/*`，不可用于 `/tiktokShop/developerProxy`。TikTok Shop 卖家授权（`erp` / `affiliate`）请用 `linkfox-tiktok-shop-auth`，两者授权数据**不互通**。\n- **令牌有效期**：`accessToken` 较短，过期需用 `refreshToken` 续签；`refreshToken` 过期须重新走授权流程。\n- **授权链接时效**：`authorizeUrl` 有效期约 1 小时，过期需重新获取。\n- **用户隔离**：用户只能查看/管理自己授权的账号。\n- **回调白名单**：系统回调 URL 与调用 IP 必须在授权方（紫鸟）处加白名单。\n- **不在范围内**：TikTok 视频上传等具体业务（用 `linkfox-tiktok-video` 经 `/tiktokVideo/developerProxy`）；TikTok Shop 可购物视频 / affiliate_creator 达人接口（用 `linkfox-tiktok-creator`，授权仍走本 skill）；TikTok 选品 / 达人带货数据分析（由 EchoTik 等其他 skill 负责）。\n\n## 执行流程\n\n### 步骤 1：生成授权链接\n- 【输入】`region`（可选，默认 `global`，美国站用 `us`）；可选 `displayName` 作为展示标签。\n- 【动作】调用 `/tiktokVideo/authorizeUrl`。\n- 【输出】返回 `authorizeUrl`，交给用户在浏览器打开完成达人授权（链接约 1 小时失效）。\n\n### 步骤 2：等待回调落库（系统自动）\n- 【输入】用户在浏览器完成授权。\n- 【动作】紫鸟将 Token POST 到 `/tiktokVideo/oauth/tokenCallback`（messageType=251），系统按 `state` 落库。\n- 【输出】授权记录写入数据库，账号以 `openId` 标记。\n\n### 步骤 3：列出已授权账号\n- 【输入】当前用户上下文（无需传参）。\n- 【动作】调用 `/tiktokVideo/authorizedAccounts`。\n- 【输出】`accounts[]`（含 `openId` / `displayName` / `region` / `userType`）。\n\n### 步骤 4：查询账号令牌\n- 【输入】`openId`。\n- 【动作】调用 `/tiktokVideo/accountTokens`（仅读取在库令牌，不触发上游刷新）。\n- 【输出】`accessToken` / `refreshToken` / `accessTokenExpireIn` / `refreshTokenExpireIn` 等，供下游 `/tiktokVideo/developerProxy` 作为 `ttsAccessToken` 使用。\n\n### 步骤 5：刷新令牌（按需）\n- 【输入】`openId`。\n- 【动作】调用 `/tiktokVideo/refreshToken`，由库中 `refreshToken` 调紫鸟续签并回写数据库。\n- 【输出】新的 `accessToken` / `refreshToken` 与新过期时间戳；若 `refreshToken` 已过期，回到步骤 1 重新授权。\n\n## 核心概念\n\n**授权流程**：调用 `/tiktokVideo/authorizeUrl` 生成授权 URL → 用户在浏览器完成达人授权 → 紫鸟 POST Token 到 `/tiktokVideo/oauth/tokenCallback`（messageType=251）→ 系统按 `state` 落库。授权 URL 有效期约 1 小时，每次授权须重新获取。\n\n**账号标识（`openId`）**：授权后以创作者唯一标识 `openId` 标记账号。查询令牌、刷新令牌均只需 `openId`（无需 `appType`）。\n\n**令牌生命周期**：`accessToken` 与 `refreshToken` 均带绝对过期时间（Unix 时间戳）。`accessToken` 过期用 `refreshToken` 续签；`refreshToken` 过期须重新走授权流程。\n\n**支持的 region**：`global`（全球，默认）/ `us`（美国站）。\n\n## 调用方式\n\n本 skill 经 LinkFox 网关调用 TikTok 视频上传授权相关接口，所有接口均为 POST，Header `Authorization: `（读取环境变量 `LINKFOXAGENT_API_KEY`）。可用脚本：\n\n- `scripts/authorize_url.py` — 生成达人授权 URL（可选 `displayName` / `region`）\n- `scripts/authorized_accounts.py` — 列出当前用户已授权的视频号\n- `scripts/account_tokens.py` — 按 `openId` 查询已入库令牌\n- `scripts/refresh_token.py` — 刷新某账号的 access_token\n\n## 使用示例\n\n### 场景 1：授权新视频号\n> 「我要授权 TikTok 视频上传 / 绑定视频号用于上传视频」\n1. 确认 `region`（美国站用 `us`，否则默认 `global`），可选询问 `displayName`。\n2. 调用 `/tiktokVideo/authorizeUrl`，得到 `authorizeUrl`。\n3. 把 `authorizeUrl` 给用户，让其在浏览器中打开并完成授权（约 1 小时失效）。\n4. 用户完成授权 → 紫鸟回调推送 Token → 系统自动落库。\n5. 可选：调用 `/tiktokVideo/authorizedAccounts` 确认授权成功。\n\n### 场景 2：查看已授权账号\n> 「列一下我已授权的 TikTok 视频号」\n1. 调用 `/tiktokVideo/authorizedAccounts`。\n2. 展示账号列表（`displayName` / `openId` / `region` / `userType`）。\n\n### 场景 3：刷新过期令牌\n> 「我 TikTok 视频上传的令牌过期了，帮我刷新」\n1. 调用 `/tiktokVideo/refreshToken`，传入 `openId`。\n2. 返回新的 `accessToken` / `refreshToken` 并回写数据库。\n3. 若 `refreshToken` 已过期，引导用户重新走场景 1 授权。\n\n### 场景 4：查询账号令牌\n> 「获取某 TikTok 视频号的访问令牌」\n1. 调用 `/tiktokVideo/accountTokens`，传入 `openId`。\n2. 返回令牌信息（供下游 `/tiktokVideo/developerProxy` 使用）。\n\n### 场景 5：为视频上传准备令牌（标准前置流程）\n当用户提出涉及 TikTok 视频上传的请求，本 skill 负责「选号 → 取令牌」前置流程，业务由 `/tiktokVideo/developerProxy` 接手：\n1. 调用 `/tiktokVideo/authorizedAccounts` 列出已授权账号。\n2. 多个视频号时请用户明确选择。\n3. 调用 `/tiktokVideo/accountTokens` 传入 `openId` 获取令牌。\n4. 把 `accessToken` 作为 `ttsAccessToken` 交给 `/tiktokVideo/developerProxy` 执行业务。\n\n## 展示规则\n\n1. **只呈现数据**：展示授权结果、账号列表、令牌信息即可，不做业务建议。\n2. **安全意识**：不要明文显示完整 `accessToken` / `refreshToken`，仅展示前 10 字符等掩码形式。\n3. **清晰引导**：返回授权链接时，明确告知用户在浏览器中打开并完成授权，且链接约 1 小时失效。\n4. **过期解读**：`accessTokenExpireIn` / `refreshTokenExpireIn` 为绝对 Unix 时间戳，需与当前时间比较判断是否过期。\n5. **错误说明**：授权或刷新失败时，基于错误码解释原因并给出建议。\n\n## 用户表达与场景速查\n\n**适用** —— 授权与令牌管理场景：\n\n| 用户说 | 场景 |\n|--------|------|\n| \"授权 TikTok 视频上传\" / \"Authorize TikTok video upload account\" | 新视频号授权 |\n| \"绑定 TikTok 视频号用于上传视频\" | 新视频号授权 |\n| \"看看已授权的 TikTok 视频号\" / \"Show my authorized TikTok video accounts\" | 列出已授权账号 |\n| \"TikTok 视频上传令牌过期了\" / \"My TikTok video token expired\" | 刷新令牌 |\n| \"获取 TikTok 视频号的访问令牌\" / \"Get TikTok video account access token\" | 查询账号令牌 |\n\n不适用场景见上方【能力边界】。\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\n---\n\n# TikTok 视频上传 API — 授权与令牌管理 API 参考\n\n本文档描述 **TikTok 视频上传模块（`/tiktokVideo`）** 的授权与令牌管理接口。底层经 LinkFox 网关转发至紫鸟开放平台 `tiktok-auth/auth/creator-url` 与 `tiktok-auth/auth/refresh?appType=creator`。业务调用（视频上传等）通过 `/tiktokVideo/developerProxy` 完成，不在本 skill 范围内。\n\n> **与 TikTok Shop 模块的区别**：本模块使用独立路由前缀 `/tiktokVideo`、独立数据表，固定 `appType=creator`（达人端），无需传 `appType` 参数。TikTok Shop 授权（`/tiktokShop/*`，含 `appType=erp/creator/affiliate`）由 `linkfox-tiktok-shop-auth` 负责，两者数据不互通。\n\n## 调用规范\n\n- **请求地址**：`https://tool-gateway.linkfox.com`（默认；可用环境变量 `LINKFOX_TOOL_GATEWAY` 覆盖）\n- **请求方式**：所有接口均为 POST\n- **Content-Type**：`application/json`\n- **认证方式**：Header `Authorization: `，API key 读取环境变量 `LINKFOXAGENT_API_KEY`（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\n- **User-Agent**：`LinkFox-Skill/1.0`\n- **超时**：150s\n- **用户鉴权**：以下接口均需 LinkFox 用户 Token；OAuth 回调端点不在本 skill 内\n\n## 接口列表\n\n### 1. 获取授权链接\n\n**接口地址**：`/tiktokVideo/authorizeUrl`\n\n调用紫鸟 `GET tiktok-auth/auth/creator-url`，获取达人（Creator）授权跳转地址。\n\n**请求参数**（JSON）：\n\n| 参数 | 类型 | 必填 | 默认 | 说明 |\n|------|------|------|------|------|\n| displayName | string | 否 | - | 视频号展示名称（可选，最长 256） |\n| region | string | 否 | `global` | 地区：`global`（全球，默认）/ `us`（美国站） |\n\n**响应**：\n\n```json\n{\n \"authorizeUrl\": \"https://services.tiktokshop.com/open/authorize?service_id=xxx&state=abc123\"\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| authorizeUrl | string | 用户在浏览器中打开的授权链接（有效期约 1 小时） |\n\n> 授权 URL 每次须重新获取。用户完成授权后，紫鸟将 Token **POST** 到 `{gateway.url}/tiktokVideo/oauth/tokenCallback`（messageType=251），浏览器同时重定向到 `{gateway.url}/tiktokVideo/oauth/redirect`。\n\n---\n\n### 2. 列出已授权账号\n\n**接口地址**：`/tiktokVideo/authorizedAccounts`\n\n**请求参数**：无（使用当前用户上下文）。\n\n**响应**：\n\n```json\n{\n \"accounts\": [\n {\n \"openId\": \"-7xYtQAAAABxLMG_EcfywQsTcT1aFR3GeQr_8HDLD21B4pJzd1zZcg\",\n \"displayName\": \"My Channel\",\n \"region\": \"global\",\n \"userType\": 1,\n \"grantedScopes\": \"[\\\"creator.video.write\\\"]\"\n }\n ],\n \"total\": 1\n}\n```\n\n**accounts[] 字段**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| openId | string | 创作者 open_id |\n| displayName | string | 展示名称 |\n| region | string | 授权 region（global / us） |\n| userType | integer | 用户类型（如 1=创作者） |\n| grantedScopes | string | 已授权 scope 列表 JSON 字符串 |\n\n---\n\n### 3. 查询账号令牌\n\n**接口地址**：`/tiktokVideo/accountTokens`\n\n按 `openId` 读取当前用户已绑定授权在库中的令牌，**不调用**紫鸟刷新接口。\n\n**请求参数**（JSON）：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| openId | string | **是** | 创作者 open_id（最长 128） |\n\n**响应**：\n\n```json\n{\n \"authRecordId\": 1,\n \"openId\": \"-7xYtQAAAABxLMG_EcfywQsTcT1aFR3GeQr_8HDLD21B4pJzd1zZcg\",\n \"accessToken\": \"TTP_Fw8rBwAAAA...\",\n \"refreshToken\": \"TTP_NTUxZTNh...\",\n \"accessTokenExpireIn\": 1781061564,\n \"refreshTokenExpireIn\": 1811992756,\n \"userType\": 1,\n \"grantedScopes\": \"[\\\"creator.video.write\\\"]\"\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| authRecordId | integer | 授权主表 ID |\n| openId | string | 创作者 open_id |\n| accessToken | string | access_token（供 `/tiktokVideo/developerProxy` 的 `ttsAccessToken` 使用） |\n| refreshToken | string | refresh_token |\n| accessTokenExpireIn | integer | access_token 过期 Unix 时间戳 |\n| refreshTokenExpireIn | integer | refresh_token 过期 Unix 时间戳 |\n| userType | integer | 用户类型 |\n| grantedScopes | string | 已授权 scope 列表 JSON |\n\n---\n\n### 4. 刷新令牌\n\n**接口地址**：`/tiktokVideo/refreshToken`\n\n从库中读取 `refresh_token`，调用紫鸟 `GET tiktok-auth/auth/refresh?appType=creator` 续签并回写数据库。\n\n**请求参数**（JSON）：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| openId | string | **是** | 创作者 open_id |\n\n**响应**：\n\n```json\n{\n \"authRecordId\": 1,\n \"accessToken\": \"TTP_Fw8rBwAAAA...\",\n \"refreshToken\": \"TTP_NTUxZTNh...\",\n \"accessTokenExpireIn\": 1781061564,\n \"refreshTokenExpireIn\": 1811992756,\n \"message\": \"刷新成功并已更新数据库\"\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| authRecordId | integer | 授权记录 ID |\n| accessToken | string | 新的 access_token |\n| refreshToken | string | 新的 refresh_token |\n| accessTokenExpireIn | integer | access_token 过期 Unix 时间戳 |\n| refreshTokenExpireIn | integer | refresh_token 过期 Unix 时间戳 |\n| message | string | 说明信息 |\n\n> `refresh_token` 过期后须重新走 **`/tiktokVideo/authorizeUrl`** 授权流程。\n\n---\n\n## 错误码\n\n| errcode | 含义 | 建议动作 |\n|---------|------|----------|\n| 1002 | 参数校验失败 / 未登录（如缺少 openId） | 检查必填参数与认证 |\n| 1003 | 上游（紫鸟）服务或网络异常 / 未配置 gateway.url | 稍后重试，检查网络与白名单 |\n| 1004 | 授权记录不存在或不属于当前用户、缺少 refresh_token | 核对 openId 或重新授权 |\n| 1005 | 开发者代理 path 未在白名单（仅 developerProxy 相关） | 使用白名单内的 path 前缀 |\n\n**错误响应示例**：\n\n```json\n{\n \"errcode\": 1002,\n \"errmsg\": \"Missing required parameter: openId\"\n}\n```\n\n---\n\n## curl 示例\n\n### 获取授权链接\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/tiktokVideo/authorizeUrl \\\n -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"displayName\": \"My Channel\", \"region\": \"global\"}'\n```\n\n### 列出已授权账号\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/tiktokVideo/authorizedAccounts \\\n -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{}'\n```\n\n### 查询账号令牌\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/tiktokVideo/accountTokens \\\n -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"openId\": \"-7xYtQAAAABxLMG_EcfywQsTcT1aFR3GeQr_8HDLD21B4pJzd1zZcg\"}'\n```\n\n### 刷新令牌\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/tiktokVideo/refreshToken \\\n -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"openId\": \"-7xYtQAAAABxLMG_EcfywQsTcT1aFR3GeQr_8HDLD21B4pJzd1zZcg\"}'\n```\n\n---\n\n## 重要说明\n\n1. **Token 安全**：不要向用户明文展示完整 accessToken/refreshToken，仅展示前 10 字符掩码。\n2. **过期判断**：`accessTokenExpireIn` / `refreshTokenExpireIn` 为绝对 Unix 时间戳，与当前时间比较判断是否过期。\n3. **用户隔离**：所有 API 都强制用户级访问控制。\n4. **回调白名单**：系统回调 URL 与调用 IP 必须在授权提供方（紫鸟）处加白名单。\n5. **独立模块**：本模块令牌仅适用于 `/tiktokVideo/developerProxy`，不可用于 `/tiktokShop/developerProxy`。\n\nFile v1.2.3:references/linkfox-tiktok-video-products.md\n\n---\nname: linkfox-tiktok-video-products\ndescription: 查询 TikTok 视频号达人店铺商品与橱窗/直播袋商品，取得 product_id 供可购物视频挂车使用。\n---\n\n# TikTok 视频号可带货商品查询\n\n本 skill 负责 TikTok **视频上传模块**下的**商品选品**能力：搜索达人绑定店铺商品、查询达人橱窗/直播袋商品，取得 `product_id` 供后续可购物视频挂车使用。参数与接口详见 [references/api.md](references/api.md)。\n\n> 📌 **前置依赖**：`linkfox-tiktok-video-auth` — 达人授权与 `accessToken`（作为 `ttsAccessToken`）。\n>\n> 📌 **下游用途**：返回商品中的 **`product_id`** 用于 **`linkfox-tiktok-video`** 的 `precheck_shoppable_video`（预检）与 `post_shoppable_video`（发布）接口中的 `product_link_info.product_id`。\n\n## 能力边界\n\n### ✅ 能力范围\n\n- 搜索达人绑定店铺中的可带货商品（`get_shop_products`），支持关键词与排序。\n- 列出达人橱窗或直播间带货袋中的商品（`get_showcase_products`）。\n- 从返回结果中提取 `product_id`，供 `linkfox-tiktok-video` 预检/发布可购物视频使用。\n\n### ❌ 边界与限制\n\n- **模块隔离**：仅 `/tiktokVideo/developerProxy`；不可用于 `/tiktokShop/*`。\n- **不含授权**：达人/视频号授权、刷新令牌请使用 `linkfox-tiktok-video-auth`。\n- **不含视频能力**：上传、预检、发布视频请使用 `linkfox-tiktok-video`。\n- **数据范围**：仅达人自有可带货商品；非达人自有商品的选品/数据分析（如 EchoTik）不在范围内。\n- **列表较大时**：使用 `response_io.py` 落盘提取字段，避免上下文溢出。\n\n## 执行流程\n\n### 步骤 1：校验授权依赖\n\n- 【输入】本 skill 运行环境\n- 【动作】运行 `python scripts/check_auth_dependency.py`；若 exit code 为 **42**，先安装 `linkfox-tiktok-video-auth` 并完成达人授权\n- 【输出】确认授权依赖已就绪\n\n### 步骤 2：选定达人并取得令牌\n\n- 【输入】已授权视频号列表\n- 【动作】通过 `linkfox-tiktok-video-auth` 的 `authorized_accounts.py` 列出已授权视频号，用户选定 `openId`；runner 自动调 `/tiktokVideo/accountTokens` 取得 `ttsAccessToken`\n- 【输出】`openId` 与 `ttsAccessToken`\n\n### 步骤 3：查询商品\n\n- 【输入】`openId`、`ttsAccessToken`、查询条件（关键词/排序/来源/分页游标）\n- 【动作】调用 `get_shop_products.py`（店铺商品搜索）或 `get_showcase_products.py`（橱窗/直播袋商品）；如需翻页，将响应中的 `data.next_page_token` 作为下一次 `page_token` 继续拉取\n- 【输出】商品列表（含 `product_id`）\n\n### 步骤 4：提取 product_id\n\n- 【输入】步骤 3 返回的商品列表\n- 【动作】从商品对象中提取 `product_id`\n- 【输出】`product_id`，供 `linkfox-tiktok-video` 的 `precheck_shoppable_video` / `post_shoppable_video` 使用\n\n## 核心概念\n\n- **调用链路**：`accountTokens`（或用户传入 `ttsAccessToken`）→ `developerProxy` → 紫鸟 `tiktok-proxy/creator` → TikTok Open API\n- **两类商品来源**：\n - **店铺商品**（`get_shop_products`）：搜索达人绑定店铺中的商品，支持关键词与排序\n - **橱窗/直播袋**（`get_showcase_products`）：列出达人橱窗或直播间带货袋中的商品\n- **`product_id` 用途**：预检/发布可购物视频时作为 `product_link_info.product_id`，由 `linkfox-tiktok-video` skill 消费\n\n### 可用脚本\n\n| 脚本 | 作用 |\n|------|------|\n| `check_auth_dependency.py` | 检测是否已安装 `linkfox-tiktok-video-auth` |\n| `products_api.py` | 具名 API 入口：JSON 含 `api` 字段 |\n| `get_shop_products.py` | 搜索达人绑定店铺商品（`affiliate_creator/202509/shop_products`） |\n| `get_showcase_products.py` | 达人橱窗/直播袋商品（`affiliate_creator/202405/showcases/products`） |\n\n共享模块：`_tiktok_video_products_common.py`、`_products_endpoints.py`、`_products_api_runner.py`。\n\n## 使用示例\n\n### 示例 1：搜索达人绑定店铺商品\n\n按标题关键词搜索达人店铺中的可带货商品：\n\n```bash\npython scripts/get_shop_products.py '{\"openId\": \"...\", \"title_keyword\": \"apple\", \"page_size\": 20}'\n```\n\n或：\n\n```bash\npython scripts/products_api.py '{\"api\": \"get_shop_products\", \"openId\": \"...\", \"page_size\": 20}'\n```\n\n从返回商品列表中取 `product_id`，用于 `linkfox-tiktok-video` 的预检/发布。\n\n### 示例 2：查询达人橱窗/直播袋商品\n\n```bash\n# 橱窗商品（默认 origin=SHOWCASE）\npython scripts/get_showcase_products.py '{\"openId\": \"...\", \"page_size\": 20}'\n\n# 直播间带货袋\npython scripts/get_showcase_products.py '{\"openId\": \"...\", \"page_size\": 20, \"origin\": \"LIVE\"}'\n```\n\n### 示例 3：翻页拉取更多商品\n\n首次请求不传 `page_token`；若响应含 `data.next_page_token`，将其作为下一次请求的 `page_token` 继续拉取。详见 [references/api.md](references/api.md)。\n\n## 展示规则\n\n1. **只呈现数据**：展示接口返回字段，不做主观选品建议。\n2. **令牌安全**：不输出完整 `ttsAccessToken`。\n3. **明确 product_id**：用户需要挂车发布时，从商品列表中提取并展示 `product_id`。\n4. **无授权时**：引导用户先走 `linkfox-tiktok-video-auth`。\n\n## 用户表达与场景速查\n\n**适用** —— TikTok 视频号达人可带货商品查询：\n\n| 用户说 | 场景 |\n|--------|------|\n| \"查这个达人的店铺商品\"、\"达人绑定店铺能卖什么\" | 店铺商品搜索 |\n| \"达人橱窗里有哪些商品\"、\"showcase 商品\" | 橱窗商品查询 |\n| \"直播间带货袋商品\"、\"直播袋里挂了啥\" | 直播袋商品查询 |\n| \"可带货商品\"、\"可购物视频选品\" | 可购物视频挂车选品 |\n| \"找 product_id 挂车\"、\"视频挂车选品\" | 取 product_id 供发布 |\n| \"翻页拉更多商品\" | 分页拉取 |\n\n不适用场景见上方【能力边界】。\n\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\n---\n\n# TikTok 视频号可带货商品 API 参考\n\n本文档收录 TikTok **视频上传模块（`/tiktokVideo`）** 下的商品查询接口，经 LinkFox 网关 `/tiktokVideo/developerProxy` 代理至紫鸟 `tiktok-proxy/creator/{region}/{path}`。\n\n> **授权不在本 skill**：OAuth / 令牌管理见 **`linkfox-tiktok-video-auth`**。\n>\n> **下游用途**：返回的 **`product_id`** 供 **`linkfox-tiktok-video`** 的 `precheck_shoppable_video`（预检）与 `post_shoppable_video`（发布）使用。\n\n## 调用规范\n\n- **网关代理端点**：`POST /tiktokVideo/developerProxy`\n- **Base URL**：`https://tool-gateway.linkfox.com`（默认；可用环境变量 `LINKFOX_TOOL_GATEWAY` 覆盖）\n- **Content-Type**：`application/json`\n- **网关鉴权**：Header `Authorization: `，读取环境变量 `LINKFOXAGENT_API_KEY`（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\n- **达人令牌**：`ttsAccessToken` = creator `access_token`，由 `linkfox-tiktok-video-auth` 授权后从 `/tiktokVideo/accountTokens` 取得\n\n### developerProxy 入参\n\n| 参数 | 类型 | 必填 | 默认 | 说明 |\n|------|------|------|------|------|\n| path | string | 是 | - | Creator API 相对路径 |\n| method | string | 是 | - | `GET` / `POST` / `PUT` / `DELETE` |\n| ttsAccessToken | string | 是 | - | creator access_token |\n| region | string | 否 | `global` | 区域 |\n| queryString | string | 否 | - | 查询字符串（**不含** `?`） |\n\n### developerProxy 出参\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| httpStatus | integer | 上游 HTTP 状态码 |\n| contentType | string | 响应 Content-Type |\n| body | string | TikTok API **原始响应正文**（JSON 字符串） |\n\n### 通过 products_api.py 调用\n\n```json\n{\n \"api\": \"\",\n \"openId\": \"\"\n}\n```\n\n具名脚本返回结构：\n\n| 字段 | 说明 |\n|------|------|\n| `api` | 调用的 api 名称 |\n| `developerProxy` | 网关原始返回 |\n| `resolvedPath` | 实际转发 path |\n| `data` | 解析后的 TikTok 完整 JSON 响应 |\n\n---\n\n## 已收录接口\n\n| api 名称 | Method | path | 说明 |\n|----------|--------|------|------|\n| `get_shop_products` | GET | `affiliate_creator/202509/shop_products` | 搜索达人绑定店铺的商品 |\n| `get_showcase_products` | GET | `affiliate_creator/202405/showcases/products` | 达人橱窗/直播袋商品列表 |\n\n---\n\n## 1. Get Shop Products（搜索达人绑定店铺的商品）\n\n- **官方文档**：[get-shop-products-202509](https://partner.tiktokshop.com/docv2/page/get-shop-products-202509)\n- **MRD 参考**：[Shoppable video Integration Solutions V2025.Q4.01](https://bytedance.sg.larkoffice.com/docx/Os8tdPkaVo2QFBxhSRIlQwBAg9f) — Get Shop Products 章节\n- **上游接口**：`GET /affiliate_creator/202509/shop_products`\n- **用途**：按关键词搜索/检索「与该达人绑定的店铺」中的商品信息，取得 `product_id` 供可购物视频挂车。\n\n### Query — 业务参数\n\n| 字段 | 必填 | 类型 | 默认/范围 | 说明 |\n|------|------|------|-----------|------|\n| title_keyword | 否 | string | — | 商品标题关键词 |\n| sort_field | 否 | string | `PRODUCT_ID` | `PRODUCT_ID` / `PRICE` / `SALE` |\n| sort_order | 否 | string | `DESC` | `DESC` / `ASC` |\n| page_size | **是** | int32 | 1~20，推荐 20 | 每页返回商品数 |\n| page_token | 否 | string | — | 翻页游标 |\n\n#### sort_field 取值\n\n| 值 | 说明 |\n|----|------|\n| `PRODUCT_ID` | 按商品 ID（默认） |\n| `PRICE` | 按价格 |\n| `SALE` | 按销量 |\n\n### 通过 get_shop_products.py / products_api.py 调用\n\n```json\n{\n \"api\": \"get_shop_products\",\n \"openId\": \"\",\n \"title_keyword\": \"apple\",\n \"sort_field\": \"PRICE\",\n \"sort_order\": \"DESC\",\n \"page_size\": 20\n}\n```\n\n```bash\npython scripts/get_shop_products.py '{\"openId\": \"...\", \"title_keyword\": \"apple\", \"page_size\": 20}'\n```\n\n### 上游响应\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| code | int | 业务状态码 |\n| message | string | 业务消息 |\n| request_id | string | 请求日志 ID |\n| data | object | 商品检索结果（含 `next_page_token` 等） |\n\n> 从返回商品中取 **`product_id`**，作为 `linkfox-tiktok-video` 中 `product_link_info.product_id` 使用。\n\n### 翻页\n\n1. 首次请求传 `page_size`，不传 `page_token`。\n2. 若 `data.next_page_token` 非空，作为下一次 `page_token` 继续拉取。\n3. `next_page_token` 为空表示末页。\n\n### 业务错误码\n\n| Code | Message |\n|------|---------|\n| 16015006 | 该达人当前无选品区域 |\n| 16015007 | 达人没有销售区域 |\n| 16501011 | 用户无权限访问该接口 |\n| 16504002 | 查询达人信息失败 |\n| 36009002 | 请求过于频繁（限流） |\n\n---\n\n## 2. Get Showcase Products（达人橱窗/直播袋商品列表）\n\n- **官方文档**：[get-showcase-products-202405](https://partner.tiktokshop.com/docv2/page/get-showcase-products-202405)\n- **上游接口**：`GET /affiliate_creator/202405/showcases/products`\n- **用途**：列出达人橱窗或直播间带货袋中的商品，取得 `product_id` 供可购物视频挂车。\n\n### Query — 业务参数\n\n| 字段 | 必填 | 类型 | 说明 |\n|------|------|------|------|\n| page_size | **是** | int | 1~20 |\n| page_token | 否 | string | 翻页游标 |\n| origin | **是** | string | `SHOWCASE` 或 `LIVE` |\n\n#### origin 取值\n\n| 值 | 说明 |\n|----|------|\n| `SHOWCASE` | 达人橱窗商品（默认） |\n| `LIVE` | 直播间带货袋商品 |\n\n### 通过 get_showcase_products.py / products_api.py 调用\n\n```json\n{\n \"api\": \"get_showcase_products\",\n \"openId\": \"\",\n \"page_size\": 20,\n \"origin\": \"SHOWCASE\"\n}\n```\n\n```bash\npython scripts/get_showcase_products.py '{\"openId\": \"...\", \"page_size\": 20, \"origin\": \"SHOWCASE\"}'\n```\n\n### 上游响应\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| code | int | 业务状态码 |\n| message | string | 业务消息 |\n| request_id | string | 请求日志 ID |\n| data | object | 商品列表与分页信息 |\n\n> 从返回商品中取 **`product_id`**，作为 `linkfox-tiktok-video` 中 `product_link_info.product_id` 使用。\n\n### 业务错误码\n\n| Code | Message |\n|------|---------|\n| 18001405 | 该达人账号无选品区域 |\n| 36009003 | 内部错误，请重试 |\n\n---\n\n## 错误码（网关层）\n\n| errcode | 含义 | 建议动作 |\n|---------|------|----------|\n| HTTP 401 | 认证失败 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。 |\n| HTTP 402 | 积分不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。 |\n| 1002 | 参数校验失败 | 检查 path、method、ttsAccessToken |\n| 1003 | 上游异常 | 稍后重试 |\n| 1005 | path 未在白名单 | 确认 path 前缀 |\n\nArchive v1.2.2: 49 files, 153761 bytes\n\nFiles: references/large-file-upload.md (6593b), references/linkfox-echotik-batch-product-detail.md (14105b), references/linkfox-echotik-get-video-download-url.md (11627b), references/linkfox-echotik-list-new-product-rank.md (9384b), references/linkfox-echotik-list-product.md (14292b), references/linkfox-echotik-product-video.md (10568b), references/linkfox-fastmoss-product-rank-top-selling.md (11254b), references/linkfox-fastmoss-product-search.md (12740b), references/linkfox-tiktok-video-auth.md (16267b), references/linkfox-tiktok-video-products.md (13589b), references/linkfox-tiktok-video.md (40510b), references/onboarding.md (2068b), scripts/_products_api_runner.py (5541b), scripts/_products_endpoints.py (1768b), scripts/_tiktok_video_common.py (5234b), scripts/_tiktok_video_products_common.py (5246b), scripts/_video_api_runner.py (6057b), scripts/_video_endpoints.py (6373b), scripts/account_tokens.py (2986b), scripts/authorize_url.py (2474b), scripts/authorized_accounts.py (2145b), scripts/check_auth_dependency.py (3958b), scripts/echotik_batch_product_detail.py (13120b), scripts/echotik_get_video_download_url.py (13126b), scripts/echotik_list_new_product_rank.py (13126b), scripts/echotik_list_product_video.py (13091b), scripts/echotik_list_product.py (13060b), scripts/fastmoss_product_rank_top_selling.py (13144b), scripts/fastmoss_product_search.py (13072b), scripts/get_creator_profile.py (892b), scripts/get_shop_products.py (1169b), scripts/get_shoppable_video_precheck_result.py (1279b), scripts/get_shoppable_video_status.py (1212b), scripts/get_showcase_products.py (1287b), scripts/large_file_upload_bind.py (1054b), scripts/large_file_upload_init.py (1070b), scripts/large_file_upload.py (1688b), scripts/onboarding.py (24089b), scripts/post_shoppable_video.py (1766b), scripts/precheck_shoppable_video.py (1734b), scripts/products_api.py (955b), scripts/refresh_token.py (2965b), scripts/response_io.py (18387b), scripts/upload_shoppable_video_file.py (1767b), scripts/video_api.py (1074b), scripts/video_proxy.py (3878b), skill-card.md (4033b), SKILL.md (22605b), _meta.json (163b)\n\nFile v1.2.2:SKILL.md\n\n---\nname: linkfox-tiktok-selection-and-shoppable-video\ndisplay_name: Linkfox Tiktok选品与带货视频\ndisplay_name_en: LinkFox TikTok Product Selection and Shoppable Video\ndescription: TikTok 选品与带货视频一站式 AI 工具集，整合 EchoTik/FastMoss 选品数据与 TikTok 官方带货视频 API，覆盖 TikTok Shop 选品、爆品趋势、带货视频分析与可购物视频发布。\ndescription_zh: TikTok 选品与带货视频一站式 AI 工具集，整合 3 类工具、10 项子能力：EchoTik（16 区域市场新品排行、商品搜索、商品详情、带货视频、视频下载）、FastMoss（全球热销榜与商品搜索，日周月多维筛选）、TikTok 官方 API（视频号 OAuth 授权与令牌、可购物视频预检/发布/状态/达人档案/大文件上传/可带货商品查询）。覆盖选品、爆品趋势、销量/GMV/达人带货与带货视频分析及可购物视频发布链路。当用户需 TikTok 选品、爆品/新品排行、商品或带货视频分析、视频号授权与可购物视频发布时触发。参数见 references/，脚本见 scripts/。\ndescription_en: One-stop TikTok product-selection and shoppable-video AI toolkit integrating 10 sub-capabilities across 3 tool families — EchoTik (new-product ranking, product search, product detail, promotional-video query, video download URL across 16 regional markets), FastMoss (global top-selling rankings and product search with day/week/month and category/sales/commission/creator multi-dimensional filters), and the TikTok official shoppable-video API (creator OAuth authorization & token management, shoppable video pre-check/publish/status/creator profile/large-file chunked upload, creator sellable-product query). Covers TikTok Shop product research, bestseller/new-product trends, product sales/GMV/live/influencer analysis, promotional-video performance & download, and the full official shoppable-video publishing chain (authorize → get product_id → pre-check → publish → check status). Triggered when the user needs TikTok product selection, bestseller/new-product rankings, product or promotional-video data analysis, or TikTok video-account authorization and shoppable-video publishing. Full params per sub-capability are in references/, executable scripts in scripts/.\ncategory: e-commerce\nversion: 1.0.0\nauthor: LinkFox\n---\n\n# Linkfox Tiktok选品与带货视频（TikTok Product Selection and Shoppable Video）\n\nTikTok 选品与带货视频一站式 AI 工具集，整合 **3 类底层工具、10 项子能力**，覆盖选品数据（EchoTik 16 区域市场 / FastMoss 全球电商）与官方带货视频发布链路（TikTok 视频号授权 → 可带货商品 → 可购物视频预检/发布）。各子能力完整参数、响应字段与错误码见 `references/` 下对应文件，可执行脚本见 `scripts/`。\n\n## 能力边界\n\n### ✅ 能力范围\n- **TikTok 选品数据（`echotik_tiktok`，EchoTik，覆盖 16 个区域市场）**：新品排行发现热销爆品与新兴趋势（`echotik_tiktok` list-new-product-rank）；商品搜索按销量/达人/佣金/评分/评论多维筛选（`echotik_tiktok` list-product）；商品关联带货视频查询播放/互动/视频销量/GMV（`echotik_tiktok` product-video）；批量商品详情含多周期销量与 GMV、直播销量、带货达人数、价格评分与佣金（`echotik_tiktok` batch-product-detail）；解析 TikTok 视频链接返回无水印/含水印下载、播放与封面地址（`echotik_tiktok` get-video-download-url）。\n- **TikTok 全球电商热销与选品（`fastmoss_tiktok`，FastMoss）**：按日/周/月维度与类目分析热销商品排行榜与 GMV 排名（`fastmoss_tiktok` product-rank-top-selling）；按类目/销量/佣金率/达人数/店铺类型多维搜索筛选商品（`fastmoss_tiktok` product-search）。\n- **TikTok 官方带货视频 API（`tiktok_official_video_api`）**：视频号达人 OAuth 授权、已授权账号列表、令牌查询与 access_token 刷新（`tiktok_official_video_api` linkfox-tiktok-video-auth）；可购物视频内容预检、查预检结果、发布、查发布状态、达人档案查询及大文件分片上传（`tiktok_official_video_api` linkfox-tiktok-video）；达人可带货商品查询（店铺商品与橱窗/直播袋商品），取得 product_id 供可购物视频挂车（`tiktok_official_video_api` linkfox-tiktok-video-products）。\n- 覆盖 region/marketplace：EchoTik 16 个 TikTok Shop 区域市场；FastMoss 全球电商（按 region 筛选）；TikTok 官方视频号 region 支持 `global`（默认）/ `us`（美国站）。具体取值见各 references。\n\n### ❌ 边界与限制\n- **API Key 必需**：所有工具均需环境变量 `LINKFOX_AGENT_API_KEY`（或 `LINKFOXAGENT_API_KEY`）；各工具独立计费、独立限频，数据时效与区域覆盖随数据源而异。\n- **计费约束**：同一会话同一参数组合默认只调用一次（脚本带本地缓存）；失败或空结果不得自动换关键词、翻页或改区域连续试探；需继续检索时先向用户说明会产生额外消耗（计费规则见 `skills-version.json` 与 references 内 api.md 的 `costToken` 字段：EchoTik 5 项 fixed≈4.5/9000 token，FastMoss 2 项 fixed≈10.5/21000 token，TikTok 官方 3 项免费）。\n- **TikTok 官方模块隔离**：`linkfox-tiktok-video` / `linkfox-tiktok-video-products` 仅走 `/tiktokVideo/developerProxy`，path 须以 `affiliate_creator` / `video` / `creator` 开头（否则 errcode 1005）；不可用于 `/tiktokShop/*`（TikTok Shop 卖家模块用 `linkfox-tiktok-shop-auth`）。令牌 `ttsAccessToken` 由 `linkfox-tiktok-video-auth` 授权后经 `/tiktokVideo/accountTokens` 取得，固定 creator 达人端。\n- **TikTok 官方依赖链**：可购物视频发布需先 `linkfox-tiktok-video-auth` 授权取令牌，再 `linkfox-tiktok-video-products` 取 `product_id`，最后 `linkfox-tiktok-video` 预检/发布；`check_auth_dependency.py` 探测 `linkfox-tiktok-video-auth` 是否安装（exit 42=未安装/未授权，需先完成授权）。\n- **大文件上传限制**：≤10MB 走 `upload_shoppable_video_file`（multipart，网关暂不支持）；>10MB 走大文件分片三步（Initialize → PUT 分片 → Bind，详见 `references/large-file-upload.md`，Step 1/3 可经 proxy，Step 2 分片 PUT 不经网关）。\n- **不在范围内**：TikTok Shop 小店 ERP（商品/订单/财务，用 `linkfox-tiktok-shop-auth` + 业务 skill）、TikTok Shop 可购物视频（`/tiktokShop/developerProxy`，用 `linkfox-tiktok-creator`）、TikTok 广告投放、物流与供应链、非电商任务、与平台或卖家的直接沟通。\n\n## 工具选择指南\n\n按需求在下表定到子能力，再跳到【业务需求路由速查】查端点/脚本/references 取参执行。\n\n| 需求 / 用户说 | 默认推荐（子能力） | 何时换用其他 |\n|---|---|---|\n| TikTok 选品 / 搜商品（\"TikTok 上什么好卖\"） | `linkfox-echotik-list-product`（16 区域市场，销量/达人/佣金/评分多维） | 要全球电商+日/周/月维度+范围筛选（达人数/佣金率 range）用 `linkfox-fastmoss-product-search` |\n| TikTok 新品 / 新兴趋势（\"最近有什么新品爆\"） | `linkfox-echotik-list-new-product-rank`（新品排行） | 要热销榜（非新品）用 `linkfox-fastmoss-product-rank-top-selling` |\n| TikTok 热销榜 / 爆品排行 / GMV 排名 | `linkfox-fastmoss-product-rank-top-selling`（日/周/月+类目） | 要\"新品\"趋势用 `linkfox-echotik-list-new-product-rank` |\n| 商品详情 / 多周期销量 GMV（\"这个 productId 卖得怎么样\"） | `linkfox-echotik-batch-product-detail`（1d/7d/15d/30d/60d/90d/累计+直播+达人） | — |\n| 商品带货视频（\"这个商品有哪些带货视频 / 视频销量\"） | `linkfox-echotik-product-video`（播放/互动/视频销量/GMV） | — |\n| 视频下载 / 去水印（\"下载这个 TikTok 视频\"） | `linkfox-echotik-get-video-download-url`（无水印/含水印/播放/封面） | — |\n| 视频号授权 / 绑定视频号 / 刷新令牌 | `linkfox-tiktok-video-auth`（OAuth+令牌） | TikTok Shop 卖家授权用 `linkfox-tiktok-shop-auth`（不互通） |\n| 达人能带什么货 / 橱窗商品 / 取 product_id | `linkfox-tiktok-video-products`（店铺商品+橱窗/直播袋） | — |\n| 发布可购物视频 / 视频挂车（\"发一个带商品的 TikTok 视频\"） | `linkfox-tiktok-video`（预检→发布→查状态） | 需先 `linkfox-tiktok-video-auth` 授权 + `linkfox-tiktok-video-products` 取 product_id |\n| 达人主页 / 档案 | `linkfox-tiktok-video`（get_creator_profile，独立功能） | — |\n| 大文件分片上传视频（>10MB） | `linkfox-tiktok-video`（large_file_upload_init/bind + 分片 PUT） | ≤10MB 走 `upload_shoppable_video_file`（网关暂不支持 multipart） |\n\n### 工具选择思路\n- **重要**：多个子能力满足需求时，要依据需求深入分析子能力的功能、用途、出入参、从中调研出最合适的子能力，并推荐用户，让用户自己决定。\n- 满足程度同等的前提下，向用户推荐\"默认推荐子能力\"。\n\n## 业务需求路由速查\n\n按【工具选择指南】定到子能力 后，下表查端点、脚本与 references 文件取参执行：\n\n### 子能力 ↔ references 文件 ↔ 端点 ↔ 脚本（10 项）\n\n**echotik_tiktok**\n| 子能力 | references 文件 | 端点 | 脚本 |\n|---|---|---|---|\n| linkfox-echotik-list-new-product-rank | references/linkfox-echotik-list-new-product-rank.md | POST /echotik/listNewProductRank | echotik_list_new_product_rank.py |\n| linkfox-echotik-list-product | references/linkfox-echotik-list-product.md | POST /echotik/listProduct | echotik_list_product.py |\n| linkfox-echotik-product-video | references/linkfox-echotik-product-video.md | POST /echotik/listProductVideo | echotik_list_product_video.py |\n| linkfox-echotik-batch-product-detail | references/linkfox-echotik-batch-product-detail.md | POST /echotik/batchProductDetail | echotik_batch_product_detail.py |\n| linkfox-echotik-get-video-download-url | references/linkfox-echotik-get-video-download-url.md | POST /echotik/getVideoDownloadUrl | echotik_get_video_download_url.py |\n\n**fastmoss_tiktok**\n| 子能力 | references 文件 | 端点 | 脚本 |\n|---|---|---|---|\n| linkfox-fastmoss-product-rank-top-selling | references/linkfox-fastmoss-product-rank-top-selling.md | POST /fastmoss/productRankTopSelling | fastmoss_product_rank_top_selling.py |\n| linkfox-fastmoss-product-search | references/linkfox-fastmoss-product-search.md | POST /fastmoss/productSearch | fastmoss_product_search.py |\n\n**tiktok_official_video_api**\n| 子能力 | references 文件 | 端点 | 脚本 |\n|---|---|---|---|\n| linkfox-tiktok-video-auth | references/linkfox-tiktok-video-auth.md | POST /tiktokVideo/authorizeUrl、/authorizedAccounts、/accountTokens、/refreshToken | authorize_url.py、authorized_accounts.py、account_tokens.py、refresh_token.py |\n| linkfox-tiktok-video | references/linkfox-tiktok-video.md | POST /tiktokVideo/developerProxy | video_api.py、video_proxy.py、get_creator_profile.py、precheck_shoppable_video.py、get_shoppable_video_precheck_result.py、post_shoppable_video.py、get_shoppable_video_status.py、upload_shoppable_video_file.py、large_file_upload_init.py、large_file_upload_bind.py |\n| linkfox-tiktok-video-products | references/linkfox-tiktok-video-products.md | POST /tiktokVideo/developerProxy | get_shop_products.py、get_showcase_products.py、products_api.py |\n\n> TikTok 官方三子能力共享 helper：`response_io.py`（落盘/摘要）、`check_auth_dependency.py`（探测 `linkfox-tiktok-video-auth`）；`linkfox-tiktok-video` 另有 `_video_api_runner.py` / `_video_endpoints.py` / `_tiktok_video_common.py`，`linkfox-tiktok-video-products` 另有 `_products_api_runner.py` / `_products_endpoints.py` / `_tiktok_video_products_common.py`，均与本入口脚本同目录、随调随用。\n\n## 调用方式\n\n- **网关**：`${LINKFOX_TOOL_GATEWAY}/<端点>`（默认 `https://tool-gateway.linkfox.com`），请求方式 POST、Content-Type `application/json`，认证 Header `Authorization: `（api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取；未配置按下方【解决认证和积分问题】处理）。各端点路径见上方【业务需求路由速查】与对应 references 文件。\n- **TikTok 官方带货视频链路**：`linkfox-tiktok-video` / `linkfox-tiktok-video-products` 经 `POST /tiktokVideo/developerProxy` 转发至紫鸟 `tiktok-proxy/creator/{region}/{path}`；调用方传 `path` / `method` / `ttsAccessToken`（= creator `access_token`，上游请求头 `x-tts-access-token`）/ `region`（`global` 默认 / `us`）；`app_key` / `timestamp` / `sign` 由紫鸟代理自动注入。具名脚本（`video_api.py` / `products_api.py` / 各 `get_*.py` / `post_*.py`）只需传 `{\"api\": \"...\", \"openId\": \"...\"}`，脚本内部自动调 `/tiktokVideo/accountTokens` 取 `ttsAccessToken` 再调 developerProxy。\n- **Python 脚本**：每项子能力对应 `scripts/<脚本名>.py '' [--inline]`（脚本名与端点见路由速查表）。脚本内部完成网关调用、鉴权与落盘。\n- **输出策略（脚本默认行为）**：始终将完整响应写入 `/linkfox///data/-.json`（`` 为脚本执行时工作目录；`` 取自环境变量 `SESSION_ID`；禁止写入 /tmp，当前目录不可写则报错）；响应体 ≤ 8 KB 落盘后完整打印到 stdout，> 8 KB 仅打印摘要（顶层字段、常见计数、最大列表长度 + 前 3 条样本）；加 `--inline` 强制全量打印（同样落盘）。\n- **读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq` 或 PowerShell `ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n- **完整参数**：每个子能力的请求参数、响应字段、错误码、curl 示例见 `references/<子能力>.md`（文件内含该子能力 SKILL.md 正文与 api.md 全文）；`linkfox-tiktok-video` 另含 `references/large-file-upload.md`（大文件分片上传详解）。\n\n## 使用示例\n\n以下按数据层给出代表性子能力的出入参示例；其余子能力参数见对应 references 文件。\n\n### 选品与数据层（EchoTik / FastMoss）\n\n**1. TikTok 新品排行（echotik_tiktok → echotik_list_new_product_rank.py）**\n```json\n{\"date\": \"2025-06-15\", \"region\": \"US\", \"pageNum\": 1, \"pageSize\": 50}\n```\n出参：`products[]`（title/asin/price/minPrice/maxPrice/currency/totalSaleCnt/totalSaleGmvAmt/salesTrendFlagText/totalVideoCnt/totalLiveCnt/totalIflCnt 达人数/productCommissionRate/productRating/reviewCount/categoryId/imageUrl）、`total`、`columns`、`costToken`。\n\n**2. TikTok 商品搜索（echotik_tiktok → echotik_list_product.py）**\n```json\n{\"keyword\": \"phone case\", \"region\": \"US\", \"minTotalSale30dCnt\": 1000, \"productSortField\": 5, \"sortType\": 1, \"pageSize\": 20}\n```\n出参：`products[]`（productId/productName/title/price/spuAvgPrice/productRating/reviewCount/ratings/productCommissionRate/totalSaleCnt/monthlySalesUnits/totalSaleGmvAmt/totalIflCnt 达人数/categoryName/firstCrawlDt/salesTrendFlagText）、`total`、`columns`、`costToken`。\n\n**3. TikTok 热销榜（fastmoss_tiktok → fastmoss_product_rank_top_selling.py）**\n```json\n{\"region\": \"US\", \"dateInfo\": {\"type\": \"day\", \"value\": \"2026-04-15\"}, \"page\": 1, \"pageSize\": 10}\n```\n出参：`products[]`（title/productId/price/minPrice/maxPrice/currency/totalSaleCnt/totalSaleGmvAmt/growthRate/shopName/shopTotalUnitsSold/categoryName/productCommissionRate/imageUrl/offShelvesText）、`total`、`columns`、`costToken`。`dateInfo.type` 支持 `day` / `week` / `month`。\n\n**4. TikTok 商品搜索（fastmoss_tiktok → fastmoss_product_search.py）**\n```json\n{\"keyword\": \"phone case\", \"region\": \"US\", \"orderField\": \"day7_units_sold\", \"pageSize\": 10}\n```\n带范围筛选：`{\"keyword\": \"beauty\", \"region\": \"US\", \"commissionRateRange\": {\"min\": 0.10}, \"creatorCountRange\": {\"min\": 50}, \"orderField\": \"commission_rate\", \"pageSize\": 10}`\n出参：`products[]`（title/productId/price/totalSaleCnt/totalSaleGmvAmt/totalVideoCnt/totalLiveCnt/totalIflCnt 达人数/productCommissionRate/productRating/reviewCount/skuCount/shopName/isCrossBorder/tiktokUrl/fastmossUrl/imageUrl）、`total`、`columns`、`costToken`。\n\n**5. 批量商品详情（echotik_tiktok → echotik_batch_product_detail.py）**\n```json\n{\"productIds\": [\"1729382310407603945\", \"1729382310407603946\"]}\n```\n出参：`products[]`（productId/productName/region/sellerId/minPrice/maxPrice/spuAvgPrice/productRating/reviewCount/productCommissionRate/totalSaleCnt/totalSaleGmvAmt/totalLiveCnt/totalVideoCnt/totalIflCnt 达人数/totalViewsCnt/discount/freeShipping/salesTrendFlag/firstCrawlDt）、`total`、`columns`、`costToken`。也可用 `productUrls` 传 TikTok Shop 商品 URL。\n\n**6. 商品带货视频（echotik_tiktok → echotik_list_product_video.py）**\n```json\n{\"productId\": \"1729382310407603945\", \"productVideoSortField\": 1, \"sortType\": 1, \"pageSize\": 20}\n```\n出参：`data[]`（videoId/productId/userId/videoDesc/officialUrl/covet 封面/totalFavoritesCnt 点赞/totalVideoSaleCnt/totalVideoSaleGmvAmt/hashTag/createDate/region）、`total`、`columns`、`costToken`。\n\n**7. 视频下载地址（echotik_tiktok → echotik_get_video_download_url.py）**\n```json\n{\"url\": \"https://www.tiktok.com/@user/video/1234567890\"}\n```\n出参：`downloadUrl`（无水印）、`playUrl`、`coverUrl`、`dynamicCoverUrl`、`videoId`、`costToken`、`errmsg`。\n\n### 带货视频发布层（TikTok 官方）\n\n> 完整链路：`linkfox-tiktok-video-auth` 授权取 `ttsAccessToken` → `linkfox-tiktok-video-products` 取 `product_id` → `linkfox-tiktok-video` 上传 `file_id` →（可选）预检 → 发布 → 查状态。\n\n**8. 视频号授权与令牌（tiktok_official_video_api → authorize_url.py / authorized_accounts.py / account_tokens.py / refresh_token.py）**\n```json\n// POST /tiktokVideo/authorizeUrl\n{\"displayName\": \"My Channel\", \"region\": \"global\"}\n// → {\"authorizeUrl\": \"https://services.tiktokshop.com/open/authorize?service_id=xxx&state=abc123\"}（约 1 小时失效）\n// POST /tiktokVideo/authorizedAccounts {} → accounts[](openId/displayName/region/userType)、total\n// POST /tiktokVideo/accountTokens {\"openId\": \"\"}\n// → accessToken/refreshToken/accessTokenExpireIn/refreshTokenExpireIn（accessToken 即下游 ttsAccessToken）\n// POST /tiktokVideo/refreshToken {\"openId\": \"\"} → 续签并回写\n```\n\n**9. 视频号可带货商品（tiktok_official_video_api → get_shop_products.py / get_showcase_products.py）**\n```json\n// 店铺商品（get_shop_products，GET affiliate_creator/202509/shop_products）\n{\"openId\": \"...\", \"title_keyword\": \"apple\", \"sort_field\": \"PRICE\", \"sort_order\": \"DESC\", \"page_size\": 20}\n// 橱窗/直播袋商品（get_showcase_products，GET affiliate_creator/202405/showcases/products）\n{\"openId\": \"...\", \"page_size\": 20, \"origin\": \"SHOWCASE\"} // origin: SHOWCASE（默认）/ LIVE\n```\n出参：商品列表含 **`product_id`**（供 `linkfox-tiktok-video` 预检/发布挂车）、`data.next_page_token`（翻页）。`page_size` 必填 1~20。\n\n**10. 发布可购物视频（tiktok_official_video_api → precheck_shoppable_video.py / get_shoppable_video_precheck_result.py / post_shoppable_video.py / get_shoppable_video_status.py）**\n```json\n// 内容预检（precheck_shoppable_video，POST affiliate_creator/202511/videos/precheck_task）\n{\"openId\": \"...\", \"video_info\": {\"file_id\": \"...\"}, \"product_link_info\": {\"product_id\": \"...\", \"title\": \"Product anchor\"}}\n// → data.precheck.task_id\n// 查预检结果（GET affiliate_creator/202511/videos/precheck_tasks/{task_id}）\n{\"openId\": \"...\", \"task_id\": \"1123123123\"}\n// → result（SUCCESS/FAIL/PROCESSING）；FAIL 时看 issues[] 整改\n// 发布可购物视频（post_shoppable_video，POST affiliate_creator/202603/videos）\n{\"openId\": \"...\", \"video_info\": {\"file_id\": \"...\", \"title\": \"My shoppable video\"}, \"product_link_info\": {\"product_id\": \"...\", \"title\": \"Product anchor\"}}\n// → data.video.id\n// 查发布状态（get_shoppable_video_status，GET affiliate_creator/202509/videos/{video_id}/status）\n{\"openId\": \"...\", \"video_id\": \"7548431509997292816\"}\n// → post_status（SUCCESS/FAIL/PROCESSING）、post_time\n```\n> 上传视频文件取 `file_id`：≤10MB 走 `upload_shoppable_video_file`（multipart，网关暂不支持）；>10MB 走大文件分片（`large_file_upload_init` → PUT 分片 → `large_file_upload_bind`，详见 `references/large-file-upload.md`）。\n\n## 展示规则\n\n1. **客观呈现数据**：以清晰表格展示查询结果，不做主观商业建议（除非用户主动要求）；不同区域币种不同，展示价格/收入时务必提示币种（响应 `currency` 字段标明本地币种）。\n2. **来源标注**：展示数据时说明来自哪个工具/数据源（EchoTik / FastMoss / TikTok 官方）。\n3. **令牌安全**：不向用户明文输出完整 `ttsAccessToken` / `accessToken` / `refreshToken`，仅展示前 10 字符等掩码形式。\n4. **不可用数据**：值为 `0` 或 `-1` 的字段表示数据不可用，标注\"N/A\"或省略，不作实际值展示；`salesTrendFlagText`/`salesTrendFlag` 为 0=平稳 1=上升 2=下降。\n5. **错误处理与协同**：查询失败时根据响应 `errcode`/`errmsg` 或 TikTok `body.code`/`message` 说明原因并建议修正（TikTok 官方 path 未在白名单返回 errcode 1005、缺参 1002、上游异常 1003；HTTP 401/402 按下方认证积分处理）；连续使用多工具时将各工具发现汇总为连贯分析，标注数据来源与时间窗。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用 references/onboarding.md 引导解决问题：\n\n**注意**：你是workbuddy，并且渠道是workbuddy，使用 onboarding 引导登录注册时 channel **必须**为 workbuddy。这非常重要！\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\nFile v1.2.2:_meta.json\n\n{\n \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n \"slug\": \"linkfox-tiktok-selection-and-shoppable-video\",\n \"version\": \"1.2.2\",\n \"publishedAt\": 1786101923696\n}\n\nFile v1.2.2:references/large-file-upload.md\n\n# 可购物视频大文件分片上传方案（Shoppable Video Large File Upload）\n\n- **来源文档**：[Shoppable Video Large File Upload Solution（Lark）](https://bytedance.sg.larkoffice.com/docx/WTMvdfbTBo30Fex0r9YlYstGg0d)\n- **Partner Center**：[shoppable-video-large-file-upload](https://partner.tiktokshop.com/docv2/page/shoppable-video-large-file-upload)（需登录）\n- **适用场景**：可购物视频文件 **> 10MB**（≤ 10MB 仍可用 §4 直传 `video_files`）\n- **替代关系**：取代旧版「请求头特殊参数」大文件方案；旧方案已于 **2026-01-31** 停止支持\n\n## 方案概述\n\n通过 **文件网关分片上传（chunked upload via file gateway）**：\n\n1. 客户端将 **> 10MB** 的文件按 chunk 切分；\n2. 携带 `upload_token` **顺序**上传各分片至 `upload_url`；\n3. 服务端合并分片还原原文件；\n4. **Bind Business Resource** 将文件绑定到可购物视频业务资源，得到与直传等价的 `file_id`。\n\n≤ 10MB 的文件继续使用 **Upload Shoppable Video File**（`POST .../videos/video_files`）。\n\n## 三步流程\n\n```\nStep 1 Initialize Upload → upload_url + upload_token\nStep 2 Upload Chunks & Merge → PUT 分片至 upload_url（不经 LinkFox 网关）\nStep 3 Bind Business Resource → file_id（供后续发布；可选预检）\n```\n\n| 步骤 | 调用方 | 经 LinkFox `/tiktokVideo/developerProxy` |\n|------|--------|------------------------------------------|\n| 1 Initialize | JSON POST | **可能**（path 须白名单放行，见下） |\n| 2 Upload Chunks | 二进制 PUT | **否** — 直连 Step 1 返回的 `upload_url` |\n| 3 Bind | JSON POST | **可能**（同 Step 1 路径前缀约束） |\n\n---\n\n## Step 1：初始化上传（Initialize Upload）\n\n获取分片上传所需的 `upload_url` 与 `upload_token`。\n\n| 项 | 说明 |\n|----|------|\n| Method | `POST` |\n| 上游 Path | `/open/{version}/file/init`（`:version` 如 `202505`，**以 Lark / Partner 文档为准**） |\n| 经 proxy 的 path 示例 | `open/202505/file/init` |\n\n### Query 参数（紫鸟自动注入）\n\n| 参数 | 说明 |\n|------|------|\n| access_token | 即 creator `access_token` / `ttsAccessToken` |\n| app_key | 紫鸟注入 |\n| timestamp | 紫鸟注入 |\n| sign | 紫鸟注入 |\n\n### 请求体（JSON）\n\n> Lark 文档中 Request Body 字段需以官方最新版为准。常见初始化字段如下（**调用前请对照 Lark 核对**）：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| file_size | int64 | 文件总字节数 |\n| chunk_size | int64 | 分片大小（字节） |\n| file_name | string | 文件名（如 `video.mp4`） |\n| content_type | string | MIME，如 `video/mp4` |\n\n### 成功响应\n\n```json\n{\n \"upload_url\": \"{uploader_url}\",\n \"upload_token\": \"{your_unique_upload_token}\"\n}\n```\n\n| 字段 | 说明 |\n|------|------|\n| upload_url | 分片上传目标 URL（Step 2 使用，**完整 URL 含 query**） |\n| upload_token | 本次上传会话 token（Step 2/3 使用） |\n\n---\n\n## Step 2：上传分片并合并（Upload Chunks & Merge）\n\n将视频二进制 **顺序** PUT 到 Step 1 返回的 **`upload_url`**（文件网关域名，**不经过** LinkFox 网关）。\n\n### 请求要点\n\n| Header | 说明 |\n|--------|------|\n| Content-Type | 视频 MIME，如 `video/mp4` |\n| Content-Length | **当前分片**字节长度 |\n| Content-Range | `bytes {first}-{last}/{total}` |\n\n### 分片规则（参考 TikTok 媒体传输惯例，与 Lark 一致方向）\n\n| 规则 | 说明 |\n|------|------|\n| 顺序 | 分片须 **按序** 上传 |\n| 分片大小 | 单分片建议 **5MB ~ 64MB**；最后一片可含剩余字节（可略大于 chunk_size） |\n| 小文件 | 总大小 < 5MB 时通常整文件一片上传 |\n| 分片数量 | 最少 1 片，最多约 **1000** 片 |\n| chunk 计算 | `total_chunk_count = floor(file_size / chunk_size)`，末片包含余数 |\n\n### PUT 示例（单片 / 末片）\n\n```bash\ncurl --location --request PUT '{upload_url}' \\\n --header 'Content-Type: video/mp4' \\\n --header 'Content-Range: bytes 0-9999999/50000000' \\\n --header 'Content-Length: 10000000' \\\n --data-binary '@/path/to/chunk.bin'\n```\n\n> 使用 Step 1 返回的 **完整** `upload_url`（含 query 参数）。上传完成后由文件网关 **自动合并** 分片。\n\n---\n\n## Step 3：绑定业务资源（Bind Business Resource）\n\n将已合并的文件绑定到 **可购物视频（Shoppable Video）** 业务资源，取得与直传 `video_files` 等价的 **`file_id`**（`data.video_file.id`）。\n\n| 项 | 说明 |\n|----|------|\n| Method | `POST` |\n| 上游 Path | `/open/{version}/file/bind`（**path 名称以 Lark Step 3 为准**，也可能是 `complete` / `commit` 等） |\n| 经 proxy 的 path 示例 | `open/202505/file/bind` |\n\n### 请求体（JSON，字段以 Lark 为准）\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| upload_token | string | Step 1 返回的 `upload_token` |\n| resource_type / biz_type | string | 业务资源类型（可购物视频场景，见官方枚举） |\n\n### 成功响应（结构以官方为准）\n\n预期返回可购物视频文件 id，供后续 **Post Shoppable Video / Pre-check** 使用：\n\n```json\n{\n \"code\": 0,\n \"data\": {\n \"video_file\": {\n \"id\": \"123123123123\",\n \"md5\": \"...\"\n }\n },\n \"message\": \"success\"\n}\n```\n\n---\n\n## LinkFox 集成现状\n\n### 路径白名单\n\n当前 `tiktok-video.developer-proxy.allowed-path-prefixes` 仅含：\n\n- `affiliate_creator`\n- `video`\n- `creator`\n\nStep 1 / Step 3 文档路径为 **`open/{version}/file/...`**，**不在现网白名单内**，经 `/tiktokVideo/developerProxy` 调用会返回 **errcode 1005**。需后端扩展白名单或确认紫鸟映射后的 `affiliate_creator/...` 等价 path 后再启用脚本。\n\n### 脚本支持\n\n| 脚本 | 状态 |\n|------|------|\n| `large_file_upload.py --help` | 流程说明 |\n| `large_file_upload_init.py` | 文档入口（暂不可实际调用） |\n| `large_file_upload_bind.py` | 文档入口（暂不可实际调用） |\n| Step 2 分片 PUT | 须客户端直连 `upload_url`，暂无 skill 封装 |\n\n---\n\n## 与直传方案的选择\n\n| 文件大小 | 推荐方案 |\n|----------|----------|\n| ≤ 10MB | §4 `upload_shoppable_video_file`（multipart 直传，网关 multipart 待支持） |\n| > 10MB | 本节大文件分片三步流程 |\n\n## 在发布链路中的位置\n\n```\n选品 → [大文件分片上传 或 直传] → file_id → （可选）预检 → 发布 → 查状态\n```\n\n> 选品请使用 **`linkfox-tiktok-video-products`**。预检为可选步骤；上传获得 `file_id` 后可直接发布。\n\nFile v1.2.2:references/linkfox-echotik-batch-product-detail.md\n\n---\nname: linkfox-echotik-batch-product-detail\ndescription: 批量查询 TikTok 商品的多周期销量、GMV、直播数据、带货达人、价格评分等详情。\n---\n\n# EchoTik TikTok 商品批量详情（Batch Product Detail）\n\n本技能用于批量获取 TikTok 商品的详细表现指标，帮助卖家与运营人员并排对比候选商品的销售、GMV、直播、视频与达人数据。参数与响应字段详见 [references/api.md](references/api.md)。\n\n## 能力边界\n\n### ✅ 能力范围\n\n- 通过商品 ID 或 TikTok Shop 商品 URL 批量查询最多 1000 个商品的详情指标。\n- 返回多周期（1d/7d/15d/30d/60d/90d/累计）销量、GMV、直播销量、直播 GMV、视频、达人、观看次数等数据。\n- 返回价格（USD）、评分、评论数、佣金比例、上下架/全托管状态等。\n\n### ❌ 边界与限制\n\n- **批量上限**：单次请求最多 1000 个商品。\n- **价格币种**：所有价格字段均为 USD。\n- **数据口径**：销量、GMV、归因数据为分析估算值，非平台精确数据。\n- **仅查询已知商品**：本工具不按关键词或类目搜索，只解析用户已有的 ID/URL。\n- **不在范围内**：按关键词发现商品（用 `linkfox-echotik-product-search`）；新品/趋势商品排行（用 `linkfox-echotik-new-product-rank`）；商品关联带货视频（用 `linkfox-echotik-product-video`）；TikTok 视频下载链接解析（用 `linkfox-echotik-get-video-download-url`）；达人主页分析；非 TikTok 平台数据。\n\n## 调用方式\n\n- **API 端点**：`POST /echotik/batchProductDetail`（完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/echotik_batch_product_detail.py '' [--inline]`\n- **成本约束**：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `/linkfox///data/linkfox-echotik-batch-product-detail-.json`（`` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq`或`ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 使用示例\n\n**1. 按商品 ID 批量查询**\n```json\n{\n \"productIds\": [\"1729382310407603945\", \"1729382310407603946\"]\n}\n```\n\n**2. 按商品 URL 批量查询**\n```json\n{\n \"productUrls\": [\n \"https://shop.tiktok.com/us/pdp/phone-case/1729382310407603945\",\n \"https://shop.tiktok.com/us/pdp/case-for-phone/1729382310407603946\"\n ]\n}\n```\n\n**3. ID 与 URL 混合（服务端合并）**\n```json\n{\n \"productIds\": [\"1729382310407603945\"],\n \"productUrls\": [\"https://shop.tiktok.com/us/pdp/phone-case/1729382310407603946\"]\n}\n```\n\n## 展示规则\n\n1. **呈现对比表**：每商品一行，关键列含名称、价格（USD）、总销量、30 天销量、总 GMV、评分、评论数、佣金比例、带货达人数。\n2. **多周期语境**：对比动量时，在累计值旁展示相关窗口（如 7d/30d），而非只看总量。\n3. **币种**：价格为 USD，需标注 USD。\n4. **佣金格式**：`productCommissionRate` 以百分比展示（如 `0.05` → \"5%\"）。\n5. **趋势标识**：`salesTrendFlag` 渲染为稳定/上升/下降，便于快速扫描。\n6. **状态徽标**：在相关位置标注 `isSShop`（全托管）、`offMark`（下架）、`freeShipping`，避免用户误把下架商品纳入对比。\n7. **图片引用**：返回 `imageUrl` / `productImageUrls` 时说明图片可用。\n8. **长描述**：`descDetail` 可能为较长 HTML/文本，做摘要或说明其可用性，而非整段倾倒。\n9. **缺失商品处理**：若请求的商品无记录，列出无数据的 ID/URL 供用户核对。\n10. **错误处理**：查询失败时根据 `errmsg`/`error` 字段说明原因，建议检查 ID/URL。\n\n## 用户表达与场景速查\n\n**适用** —— TikTok 商品批量详情查询：\n\n| 用户说 | 场景 |\n|--------|------|\n| \"查这些 TikTok 商品的详情\" | 按商品 ID 批量详情 |\n| \"拉一下这些 TikTok 链接的销量\" | 按商品 URL 批量详情 |\n| \"对比这些 TikTok 商品的 GMV\" | 批量查询，展示 GMV 列 |\n| \"这些 TikTok 商品哪些在涨\" | 批量查询，读 `salesTrendFlag` |\n| \"这些 TikTok 商品有下架/全托管吗\" | 批量查询，读 `offMark` / `isSShop` |\n| \"查这些 TikTok 商品的直播销量\" | 批量查询，展示直播销量/GMV |\n\n不适用场景见上方【能力边界】。\n\n### 边界判断\n\n当用户说\"分析这些 TikTok 商品\"时，判断用户是否已有具体商品 ID 或 TikTok Shop URL（本技能），还是想按关键词/类目**发现**商品（搜索技能）。若用户粘贴了 ID/URL 列表并希望查看销量/GMV/直播详情，适用本技能；若用户问\"该卖什么\"或\"找趋势商品\"，则不适用。\n\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\n---\n\n# EchoTik-TikTok商品批量详情 API 参考\n\n## 调用规范\n\n- **请求地址**：`${LINKFOX_TOOL_GATEWAY}/echotik/batchProductDetail`\n- **请求方式**：POST，Content-Type: application/json\n- **认证方式**：Header `Authorization: `，api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\n\n## 请求参数\n\nPOST Body（JSON）：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| productIds | array<string> | 否* | 商品ID列表（最多 1000 个）。示例：`[\"1729382310407603945\", \"1729382310407603946\"]` |\n| productUrls | array<string> | 否* | 商品URL列表（最多 1000 个），形如 `https://shop.tiktok.com/us/pdp//?...`；后端会从每个URL中提取末尾的 `productId` 并合并到 `productIds`，与 `productIds` 不互斥 |\n\n\\* `productIds` 与 `productUrls` 至少传其一，可同时传入；二者合并后最多 1000 个商品。\n\n## 响应结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| total | integer | 记录数 |\n| products | array | 商品详情列表（详见下方商品对象） |\n| columns | array | 渲染的列 |\n| type | string | 渲染的样式 |\n| costToken | integer | 消耗token |\n\n### 商品对象字段\n\n> 销量、GMV、直播、视频、达人、观看等指标均按 `1d / 7d / 15d / 30d / 60d / 90d` 多周期及累计（total）返回。价格字段单位均为 USD。\n\n**基础信息**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| productId | string | 商品ID |\n| productName | string | 商品名称 |\n| imageUrl | string | 商品图片 |\n| productImageUrls | array | 商品图片列表 |\n| region | string | 区域代码 |\n| sellerId | string | 卖家ID |\n| categoryId | string | 一级分类ID |\n| categoryL2Id | string | 二级分类ID |\n| categoryL3Id | string | 三级分类ID |\n\n**价格 / 评分 / 佣金**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| minPrice | number | 最低SKU价格(USD) |\n| maxPrice | number | 最高SKU价格(USD) |\n| spuAvgPrice | number | SPU平均价格(USD) |\n| productRating | number | 商品评分 |\n| reviewCount | integer | 评论数量 |\n| productCommissionRate | number | 商品佣金比例 |\n\n**销量（多周期）**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| totalSaleCnt | integer | 总销量 |\n| totalSale1dCnt | integer | 近1天销量 |\n| totalSale7dCnt | integer | 近7天销量 |\n| totalSale15dCnt | integer | 近15天销量 |\n| totalSale30dCnt | integer | 近30天销量 |\n| totalSale60dCnt | integer | 近60天销量 |\n| totalSale90dCnt | integer | 近90天销量 |\n\n**销售额 GMV（多周期）**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| totalSaleGmvAmt | number | 总销售额 |\n| totalSaleGmv1dAmt | number | 近1天销售额 |\n| totalSaleGmv7dAmt | number | 近7天销售额 |\n| totalSaleGmv15dAmt | number | 近15天销售额 |\n| totalSaleGmv30dAmt | number | 近30天销售额 |\n| totalSaleGmv60dAmt | number | 近60天销售额 |\n| totalSaleGmv90dAmt | number | 近90天销售额 |\n\n**直播（多周期）**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| totalLiveCnt | integer | 总直播数量 |\n| totalLive1dCnt | integer | 近1天直播数量 |\n| totalLive7dCnt | integer | 近7天直播数量 |\n| totalLive15dCnt | integer | 近15天直播数量 |\n| totalLive30dCnt | integer | 近30天直播数量 |\n| totalLive60dCnt | integer | 近60天直播数量 |\n| totalLive90dCnt | integer | 近90天直播数量 |\n\n**直播销量 / 直播销售额（多周期）**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| totalLiveSale1dCnt | integer | 近1天直播销量 |\n| totalLiveSale7dCnt | integer | 近7天直播销量 |\n| totalLiveSale15dCnt | integer | 近15天直播销量 |\n| totalLiveSale30dCnt | integer | 近30天直播销量 |\n| totalLiveSale60dCnt | integer | 近60天直播销量 |\n| totalLiveSale90dCnt | integer | 近90天直播销量 |\n| totalLiveSaleGmv1dAmt | integer | 近1天直播销售额 |\n| totalLiveSaleGmv7dAmt | integer | 近7天直播销售额 |\n| totalLiveSaleGmv15dAmt | integer | 近15天直播销售额 |\n| totalLiveSaleGmv30dAmt | integer | 近30天直播销售额 |\n| totalLiveSaleGmv60dAmt | integer | 近60天直播销售额 |\n| totalLiveSaleGmv90dAmt | integer | 近90天直播销售额 |\n\n**视频（多周期）**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| totalVideoCnt | integer | 总视频数量 |\n| totalVideo1dCnt | integer | 近1天视频数量 |\n| totalVideo7dCnt | integer | 近7天视频数量 |\n| totalVideo15dCnt | integer | 近15天视频数量 |\n| totalVideo30dCnt | integer | 近30天视频数量 |\n| totalVideo60dCnt | integer | 近60天视频数量 |\n| totalVideo90dCnt | integer | 近90天视频数量 |\n\n**达人（多周期）**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| totalIflCnt | integer | 总达人数量 |\n| totalIflVideo1dCnt | integer | 近1天达人视频数量 |\n| totalIflVideo7dCnt | integer | 近7天达人视频数量 |\n| totalIflVideo15dCnt | integer | 近15天达人视频数量 |\n| totalIflVideo30dCnt | integer | 近30天达人视频数量 |\n| totalIflVideo60dCnt | integer | 近60天达人视频数量 |\n| totalIflVideo90dCnt | integer | 近90天达人视频数量 |\n| totalIflLive1dCnt | integer | 近1天达人直播数量 |\n| totalIflLive7dCnt | integer | 近7天达人直播数量 |\n| totalIflLive15dCnt | integer | 近15天达人直播数量 |\n| totalIflLive30dCnt | integer | 近30天达人直播数量 |\n| totalIflLive60dCnt | integer | 近60天达人直播数量 |\n| totalIflLive90dCnt | integer | 近90天达人直播数量 |\n\n**观看次数（多周期）**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| totalViewsCnt | integer | 总观看次数 |\n| totalViews1dCnt | integer | 近1天观看次数 |\n| totalViews7dCnt | integer | 近7天观看次数 |\n| totalViews15dCnt | integer | 近15天观看次数 |\n| totalViews30dCnt | integer | 近30天观看次数 |\n| totalViews60dCnt | integer | 近60天观看次数 |\n| totalViews90dCnt | integer | 近90天观看次数 |\n\n**状态标识与其它**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| discount | string | 折扣信息 |\n| freeShipping | integer | 是否免运费 |\n| salesFlag | integer | 主要配送方式 |\n| salesTrendFlag | integer | 销售趋势标识：0=稳定、1=上升、2=下降 |\n| isSShop | integer | 是否全托管店铺 |\n| offMark | integer | 商品下架标识 |\n| firstCrawlDt | string | 首次爬取日期 |\n| descDetail | string | 商品详情描述 |\n\n## 错误码\n\n正常情况下，接口的 HTTP 状态码均为 200，业务的成功与否通过响应体中的 errorCode 字段区分（errorCode = 200 表示成功，其他值表示业务错误）。当遇到未授权等情况时，HTTP 状态码为 401，且对应的 errorCode 也是 401。\n\n| errcode | 含义 | 处理建议 |\n|---------|------|----------|\n| 200 | 成功 | 正常解析业务字段 |\n| 401 | 认证失败 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 402 | 积分不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 其他非200值 | 业务异常 | 参考 `errmsg` 字段获取具体错误原因（如商品ID不正确、商品不存在等） |\n\n错误响应示例：\n\n```json\n{\n \"errcode\": 401,\n \"errmsg\": \"authorized error\"\n}\n```\n\n## curl 示例\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/echotik/batchProductDetail \\\n -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"productIds\": [\"1729382310407603945\", \"1729382310407603946\"]\n }'\n```\n\nFile v1.2.2:references/linkfox-echotik-get-video-download-url.md\n\n---\nname: linkfox-echotik-get-video-download-url\ndescription: 解析 TikTok 视频链接，返回无水印/含水印下载地址、播放地址与封面地址。\n---\n\n# EchoTik TikTok 视频下载地址查询\n\n本技能用于把一个 TikTok 视频链接解析为可直接下载/播放的视频地址，帮助卖家保存带货视频素材或离线分析复用。参数与响应字段详见 [references/api.md](references/api.md)。\n\n## 能力边界\n\n### ✅ 能力范围\n\n- 把单个 TikTok 视频链接解析为：无水印下载地址（`noWatermarkDownloadUrl`）、含水印下载地址（`downloadUrl`）、播放地址（`playUrl`）与封面（静态 `coverUrl` / 动态 `dynamicCoverUrl`）。\n- 支持两种链接格式：短链 `https://vt.tiktok.com/xxxxxx` 与完整链接 `https://www.tiktok.com/@user/video/1234567890`。\n- 适用于归档高表现带货视频、复用创作者素材等场景。\n\n### ❌ 边界与限制\n\n- **必填参数**：必须提供 `url`，最大长度 1000。\n- **下载地址不一定返回**：受区域、隐私或源站限制，部分视频不返回 `noWatermarkDownloadUrl` / `downloadUrl`，仅返回 `playUrl` 与封面；此时应改用 `playUrl` 播放预览，不要伪造下载链接。\n- **链接时效**：返回的下载/播放地址会过期，应在解析后尽快使用；链接失效时需重新解析。\n- **不在范围内**：按商品查询关联带货视频（用 `linkfox-echotik-product-video`，需 `productId`）；TikTok 商品搜索（用 `linkfox-echotik-product-search`）；TikTok 新品榜单（用 `linkfox-echotik-new-product-rank`）；TikTok 直播数据；视频剪辑或内容创作建议；非 TikTok 平台的视频下载。\n\n## 核心概念\n\n本工具接收单个 TikTok 视频链接，解析为直接媒体地址：无水印下载地址（推荐用于干净素材）、含水印下载地址、播放地址与封面（静态/动态）。当卖家想归档通过 EchoTik 商品视频工具发现的高表现带货视频，或复用创作者片段而无需重新录制时，本工具很有用。\n\n**必填输入**：`url` 必填，支持两种格式：\n- 短链：`https://vt.tiktok.com/xxxxxx`\n- 完整链接：`https://www.tiktok.com/@user/video/1234567890`\n\n**下载地址为条件返回**：并非所有视频都返回可下载地址。`noWatermarkDownloadUrl` 与 `downloadUrl` 仅在源视频允许时返回；部分视频（受区域/隐私/可用性限制）两者都缺省，仅返回 `playUrl` 与封面。呈现下载链接前务必检查字段是否存在，下载字段缺失时用 `playUrl` 播放兜底。\n\n**地址时效**：返回的下载/播放地址会随时间失效，应在解析后尽快使用；链接失效时重新解析。\n\n## 调用方式\n\n- **API 端点**：`POST /echotik/getVideoDownloadUrl`（完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/echotik_get_video_download_url.py '' [--inline]`\n- **成本约束**：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `/linkfox///data/linkfox-echotik-get-video-download-url-.json`（`` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq` 或 `ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 使用示例\n\n**1. 解析完整 TikTok 视频链接**\n```json\n{\n \"url\": \"https://www.tiktok.com/@user/video/1234567890\"\n}\n```\n\n**2. 解析 TikTok 短链**\n```json\n{\n \"url\": \"https://vt.tiktok.com/Z123abc/\"\n}\n```\n\n## 展示规则\n\n1. **优先呈现无水印链接**：`noWatermarkDownloadUrl` 存在时，作为首选下载选项呈现，因为干净素材通常是卖家想要的。\n2. **同时提供含水印版本**：`downloadUrl`（含水印）存在时也列出，以备用户需要原版品牌。\n3. **处理下载地址缺失**：`noWatermarkDownloadUrl` 与 `downloadUrl` 都缺失时（部分视频常见），不要伪造下载链接——告知用户该视频无直接下载地址，改用 `playUrl` 播放/预览。\n4. **提供播放与封面**：说明 `playUrl` 可快速预览，`coverUrl` / `dynamicCoverUrl` 作为缩略图。\n5. **时效提醒**：提醒用户解析的地址会过期，应尽快下载。\n6. **只呈现数据**：清晰展示解析出的地址，不对视频如何使用做主观建议。\n7. **错误处理**：解析失败时根据 `errcode`/`errmsg` 说明原因——`400` 表示 `url` 缺失或无效，`10000` 表示链接非有效/可访问的 TikTok 视频；建议检查 URL 格式。\n\n## 用户表达与场景速查\n\n**适用** —— TikTok 视频下载与素材保存：\n\n| 用户说 | 场景 |\n|--------|------|\n| \"下载这个 TikTok 视频\"、\"保存这个 TikTok 片段\" | 把视频链接解析为下载地址 |\n| \"给我这个 TikTok 视频的无水印版本\" | 优先返回 `noWatermarkDownloadUrl` |\n| \"我想保存这个达人的带货视频\" | 解析并归档创作者视频 |\n| \"给我这个 TikTok 视频的可播放链接\" | 返回 `playUrl` |\n| \"给我这个 TikTok 视频的封面/缩略图\" | 返回 `coverUrl` / `dynamicCoverUrl` |\n\n不适用场景见上方【能力边界】。\n\n**边界判断**：当用户提到「TikTok 视频」时，判断其是否已有想下载的**具体视频链接**（本技能），还是想**发现某商品关联的视频**（商品视频技能）。若用户提供 `tiktok.com` 或 `vt.tiktok.com` 链接并要求保存/下载/提取，适用本技能；若其提供商品 ID 并问「这个商品有哪些带货视频」，则用 `linkfox-echotik-product-video`。\n\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\n---\n\n# EchoTik TikTok 视频下载 API 参考\n\n## 调用规范\n\n- **请求地址**：`${LINKFOX_TOOL_GATEWAY}/echotik/getVideoDownloadUrl`\n- **请求方式**：POST，Content-Type: application/json\n- **认证方式**：Header `Authorization: `，api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\n\n## 请求参数\n\nPOST Body（JSON）：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| url | string | 是 | TikTok 视频地址，支持两种格式：`https://vt.tiktok.com/xxx` 短链或 `https://www.tiktok.com/@user/video/xxx` 完整链接。最大长度 1000 |\n\n## 响应结构\n\n成功时 HTTP 状态码为 200，响应体顶层同时包含业务码 `errcode=200`、`errmsg=\"ok\"` 与下列数据字段。\n\n| 字段 | 类型 | 是否必返 | 说明 |\n|------|------|----------|------|\n| noWatermarkDownloadUrl | string | 条件返回 | 视频下载地址（无水印）。**并非所有视频都返回**：部分视频该字段缺省，此时无法提供无水印下载 |\n| downloadUrl | string | 条件返回 | 视频下载地址（含水印）。**并非所有视频都返回**：与无水印地址一同缺省或出现 |\n| playUrl | string | 始终返回 | 视频播放地址。当下载地址缺省时，可作为播放/预览的兜底 |\n| coverUrl | string | 始终返回 | 视频封面地址（静态） |\n| dynamicCoverUrl | string | 始终返回 | 视频动态封面地址 |\n| videoId | string | 始终返回 | 视频 ID |\n| columns | array | 始终返回 | 渲染列定义（字段元数据：field/title/cellType/filterable/sortable，供前端表格渲染用） |\n| type | string | 始终返回 | 渲染样式（如 `tableListWorkbenches`） |\n| costToken | integer | 始终返回 | 消耗 token |\n| errcode | integer | 始终返回 | 业务码，200 表示成功 |\n| errmsg | string | 始终返回 | 业务信息，成功时为 `ok` |\n\n> **下载地址缺省说明**：实测部分视频（受区域、隐私或源站限制）不会返回 `noWatermarkDownloadUrl` / `downloadUrl`，仅返回 `playUrl` 与封面。此时应向用户说明该视频暂无可直接下载地址，可改用 `playUrl` 播放预览。\n\n成功响应示例（真实调用，已截断长 URL）：\n\n```json\n{\n \"errcode\": 200,\n \"errmsg\": \"ok\",\n \"videoId\": \"7096674515245206810\",\n \"noWatermarkDownloadUrl\": \"https://v45.tiktokcdn-eu.com/51678f6e0de3...\",\n \"downloadUrl\": \"https://v45.tiktokcdn-eu.com/626c5d3d5a7d...\",\n \"playUrl\": \"https://v45.tiktokcdn-eu.com/51678f6e0de3...\",\n \"coverUrl\": \"https://agent-files.linkfox.com/tiktok/20260629/7096674515245206810.jpg\",\n \"dynamicCoverUrl\": \"https://p16-common-sign.tiktokcdn-eu.com/tos-useast2a-p-0037...\",\n \"type\": \"tableListWorkbenches\",\n \"costToken\": 12000,\n \"columns\": [/* 渲染列定义 */]\n}\n```\n\n## 错误码\n\n正常情况下，接口的 HTTP 状态码均为 200，业务的成功与否通过响应体中的 `errcode` 字段区分（`errcode = 200` 表示成功，其他值表示业务错误）。当遇到未授权等情况时，HTTP 状态码为 401，且对应的 `errcode` 也是 401。\n\n| errcode | 含义 | 处理建议 |\n|---------|------|----------|\n| 200 | 成功 | 正常解析业务字段 |\n| 400 | 参数错误 | `errmsg` 会指明缺失项，如 `url 为必填参数`；检查 `url` 是否传入且非空 |\n| 401 | 认证失败 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 402 | 积分不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 10000 | 未获取到视频下载地址 | URL 非 TikTok 视频链接、视频不可访问或已被删除；提示用户检查链接是否为有效的 TikTok 视频地址 |\n| 其他非200值 | 业务异常 | 参考 `errmsg` 字段获取具体错误原因 |\n\n错误响应示例：\n\n```json\n// 参数缺失\n{\n \"errcode\": 400,\n \"errmsg\": \"url 为必填参数\",\n \"url\": \"\"\n}\n\n// 非有效 TikTok 视频链接\n{\n \"errcode\": 10000,\n \"errmsg\": \"未获取到视频下载地址\"\n}\n\n// 未授权\n{\n \"errcode\": 401,\n \"errmsg\": \"authorized error\"\n}\n```\n\n## curl 示例\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/echotik/getVideoDownloadUrl \\\n -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"url\": \"https://www.tiktok.com/@user/video/1234567890\"\n }'\n```\n\nFile v1.2.2:references/linkfox-echotik-list-new-product-rank.md\n\n---\nname: linkfox-echotik-list-new-product-rank\ndescription: TikTok Shop 新品排行查询。基于 EchoTik 数据发现多区域市场的短视频电商热销爆品与新兴商品趋势。\n---\n\n# EchoTik - TikTok 新品排行（New Product Ranking）\n\n本技能用于通过 EchoTik 数据源查询和分析 TikTok Shop 新品排行数据，帮助跨境电商卖家在 TikTok 区域市场识别热门新品。参数与响应字段详见 [references/api.md](references/api.md)。\n\n## 能力边界\n\n### ✅ 能力范围\n\n- 查询 TikTok Shop 16 个区域市场的新品排行数据，获取每日新品快照。\n- 展示新品的价格、销量、销售额、带货达人数、关联视频/直播数、佣金率、评分等指标。\n- 支持按 `region` 切换市场、按 `pageNum` / `pageSize` 翻页浏览大结果集。\n\n### ❌ 边界与限制\n\n- **日期必填**：`date` 参数必填，格式 `YYYY-MM-DD`，无默认日期。\n- **日粒度数据**：为每日快照，不提供周榜/月榜或跨多月的长期趋势。\n- **分页**：单次请求不会返回全部商品，需用 `pageNum`、`pageSize` 翻页。\n- **不在范围内**：Amazon 选品与关键词分析（用 ABA 工具）；TikTok 广告投放与广告管理；TikTok 内容创作或视频剪辑；商品评价与 Listing 文案撰写；利润率计算与定价策略。\n\n## 核心概念\n\nTikTok 新品排行追踪在 TikTok Shop 近期上架且表现上升的新品，揭示哪些新品卖得好、其定价、销量、达人覆盖与直播活跃度，是短视频电商选品、趋势分析与竞品情报的必备工具。\n\n**数据范围**：覆盖 16 个 TikTok Shop 市场，提供每日新品快照及其表现指标（销量、销售额、达人数、视频数、直播数、佣金率、评分等）。\n\n**分页**：结果分页返回，用 `pageNum`（页码，从 1 开始）与 `pageSize`（每页条数，默认 50）浏览。\n\n## 调用方式\n\n- **API 端点**：`POST /echotik/listNewProductRank`（完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/echotik_list_new_product_rank.py '' [--inline]`\n- **成本约束**：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换 region、翻页或改 date 连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `/linkfox///data/linkfox-echotik-list-new-product-rank-.json`（`` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq` 或 `ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 使用示例\n\n**1. 当日美国市场热门新品**\n查询美国市场当前日期，查看哪些新品正在上升。\n```\ndate: \"2025-06-15\", region: \"US\"\n```\n\n**2. 发掘东南亚热门新品**\n查看印尼或泰国市场的新品机会。\n```\ndate: \"2025-06-15\", region: \"ID\"\n```\n\n**3. 浏览英国市场新品排行**\n考察英国 TikTok Shop 的新晋热门商品。\n```\ndate: \"2025-06-15\", region: \"GB\"\n```\n\n**4. 翻页浏览大结果集**\n获取美国市场每页 20 条的第 2 页。\n```\ndate: \"2025-06-15\", region: \"US\", pageNum: 2, pageSize: 20\n```\n\n## 展示规则\n\n1. **只呈现数据**：以清晰表格展示查询结果，不做主观商业建议。\n2. **销量趋势说明**：展示销量趋势时，将数值标识翻译为可读标签：0 = 平稳，1 = 上升，2 = 下降。\n3. **币种标注**：价格须带币种代码，不同市场币种不同。\n4. **大结果提示**：结果较多时展示头部商品摘要，并提醒用户可翻页获取更多。\n5. **图片处理**：返回 `imageUrl` 时提及但不内联渲染，除非环境支持。\n6. **错误处理**：查询失败时说明原因，并建议调整 `date` 或 `region` 参数。\n\n## 用户表达与场景速查\n\n**适用** —— TikTok Shop 新品发现与趋势分析：\n\n| 用户说 | 场景 |\n|--------|------|\n| \"TikTok 上什么新品火\" | 新品排行查询 |\n| \"TikTok 今日热销\"、\"TikTok Shop 爆品\" | 每日排行查询 |\n| \"东南亚 TikTok 新品机会\" | 区域市场考察 |\n| \"TikTok 英国卖得好的新品\" | 区域排行 |\n| \"TikTok 选品\"、\"短视频电商趋势\" | 通用商品发现 |\n| \"TikTok 上升的新品\" | 趋势筛选排行 |\n| \"TikTok 达人推的货\"、\"TikTok 创作者在卖什么\" | 达人驱动商品发现 |\n\n不适用场景见上方【能力边界】。\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\n---\n\n# EchoTik-TikTok新品榜 API 参考\n\n## 调用规范\n\n- **请求地址**：`${LINKFOX_TOOL_GATEWAY}/echotik/listNewProductRank`\n- **请求方式**：POST，Content-Type: application/json\n- **认证方式**：Header `Authorization: `，api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取（如未配置 按 SKILL.md 的 **## 解决认证和积分问题** 处理）\n\n## 请求参数\n\nPOST Body（JSON）：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| date | string | 是 | 日期，格式为 `YYYY-MM-DD` |\n| region | string | 否 | 区域，默认 `US`。可选值：US（美国）、ID（印度尼西亚）、TH（泰国）、PH（菲律宾）、MY（马来西亚）、VN（越南）、GB（英国）、MX（墨西哥）、SG（新加坡）、SA（沙特阿拉伯）、BR（巴西）、ES（西班牙）、JP（日本）、DE（德国）、IT（意大利）、FR（法国） |\n| pageNum | integer | 否 | 分页页码，默认 `1` |\n| pageSize | integer | 否 | 每页条数，默认 `50` |\n\n\n## 响应结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| total | integer | 记录数 |\n| products | array | 最新商品列表（见下方商品对象） |\n| columns | array | 渲染的列 |\n| type | string | 渲染的样式 |\n| costToken | integer | 消耗token |\n\n### 商品对象\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| title | string | 商品名称 |\n| asin | string | 商品ID |\n| region | string | 区域代码 |\n| price | number | SPU平均价格 |\n| minPrice | number | 最低价格 |\n| maxPrice | number | 最高价格 |\n| currency | string | 货币 |\n| totalSaleCnt | integer | 总销量 |\n| totalSale30dCnt | integer | 近30天销量 |\n| totalSaleGmvAmt | number | 总销售额 |\n| totalSaleGmv30dAmt | number | 近30天销售额 |\n| salesTrendFlagText | string | 销售趋势标识，0=平稳 1=上升 2=下降 |\n| totalVideoCnt | integer | 视频总数 |\n| totalLiveCnt | integer | 直播总数 |\n| totalIflCnt | integer | 总达人数 |\n| productCommissionRate | number | 商品佣金比例 |\n| productRating | number | 商品评分 |\n| reviewCount | integer | 评论数量 |\n| availableDate | string (date) | 首次爬取日期 |\n| categoryId | string | 商品分类ID |\n| imageUrl | string | 商品图片 |\n| productImageUrls | array | 商品图片URL列表 |\n| sourceTool | string | 来源工具 |\n| sourceType | string | 商品来源 |\n\n## 错误码\n\n正常情况下，接口的 HTTP 状态码均为 200，业务的成功与否通过响应体中的 errorCode 字段区分（errorCode = 200 表示成功，其他值表示业务错误）。当遇到未授权等情况时，HTTP 状态码为 401，且对应的 errorCode 也是 401。\n\n| errcode | 含义 | 处理建议 |\n|---------|------|----------|\n| 200 | 成功 | 正常解析业务字段 |\n| 401 | 认证失败 | HTTP 401 或 authorized error：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 402 | 积分不足 | HTTP 402：按 SKILL.md 的 **## 解决认证和积分问题** 处理。|\n| 其他非200值 | 业务异常 | 参考 `errmsg` 字段获取具体错误原因 |\n\n错误响应示例：\n\n```json\n{\n \"errcode\": 401,\n \"errmsg\": \"authorized error\"\n}\n```\n\n## curl 示例\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/echotik/listNewProductRank \\\n -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"date\": \"2025-06-15\", \"region\": \"US\", \"pageNum\": 1, \"pageSize\": 50}'\n```\n\nFile v1.2.2:references/linkfox-echotik-list-product.md\n\n---\nname: linkfox-echotik-list-product\ndescription: 搜索和分析TikTok 16个站点的商品销量、达人带货、定价及佣金等数据，用于TikTok Shop选品和商品表现分析。\n---\n\n# EchoTik TikTok 商品搜索\n\n本技能用于搜索和分析 TikTok Shop 商品数据，帮助卖家和营销人员发现商品机会、评估销售表现、识别达人带货商品。参数与响应字段详见 [references/api.md](references/api.md)。\n\n## 能力边界\n\n### ✅ 能力范围\n\n- 按**关键词**搜索 TikTok Shop 商品，支持销量、GMV、价格、评分、评论数、佣金率、达人/视频/播放量等多维筛选与排序。\n- 返回多周期销售数据（1d/7d/15d/30d/60d/90d/total）及对应 GMV、定价、评分、评论、佣金率、达人带货统计等明细。\n- 覆盖 16 个 TikTok Shop 站点（US、ID、TH、PH、MY、VN、GB、MX、SG、SA、BR、ES、JP、DE、IT、FR）。\n\n### ❌ 边界与限制\n\n- **关键词语言**：`keyword` 须翻译为目标站点的当地语言；`categoryKeywordCN` 必须为中文。\n- **佣金率**：以小数存储（0.05 表示 5%），用户给百分比时需先换算。\n- **上架日期**：`firstCrawlDt` 为紧凑整数格式 `YYYYMMDD`（如 `20240101`）。\n- **默认站点**：用户未指定站点时默认 `US`。\n- **不在范围内**：TikTok 达人/创作者分析（粉丝数、互动率）；TikTok 视频表现分析（单条视频的播放、点赞、分享）；TikTok 广告/广告系列管理；Amazon、Shopee 等非 TikTok 平台数据；TikTok Shop 店铺级分析；Listing 创建或优化建议；物流、履约或发货分析。\n\n## 核心概念\n\nEchoTik 是一个 TikTok Shop 数据分析平台，跟踪多个 TikTok 站点的商品表现。本工具提供基于关键词的商品搜索与丰富的筛选能力，返回商品销量（1d/7d/15d/30d/60d/90d/total）、GMV、定价、评分、评论数、佣金率及达人带货统计等明细。\n\n**销售指标**：商品包含多周期销售数据——1 天、7 天、15 天、30 天、60 天、90 天及总销量；GMV 同样按此粒度返回。\n\n**佣金率**：以小数存储（0.05 表示 5%）。当用户指定百分比时，传入 API 前需先换算为小数。\n\n**上架日期**：`firstCrawlDt` 字段使用紧凑整数格式 `YYYYMMDD`（如 `20240101` 表示 2024 年 1 月 1 日）。\n\n## 调用方式\n\n- **API 端点**：`POST /echotik/listProduct`（完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/echotik_list_product.py '' [--inline]`\n- **成本约束**：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `/linkfox///data/linkfox-echotik-list-product-.json`（`` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq`或`ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 使用示例\n\n**1. 基础关键词搜索 —— 查某关键词的热销商品**\n```json\n{\n \"keyword\": \"phone case\",\n \"region\": \"US\",\n \"productSortField\": 1,\n \"sortType\": 1,\n \"pageSize\": 20\n}\n```\n\n**2. 高佣金商品发现 —— 佣金率 >= 10% 的商品**\n```json\n{\n \"keyword\": \"beauty\",\n \"region\": \"US\",\n \"minProductComm\n\nArchive v1.2.1: 49 files, 153659 bytes\n\nFiles: references/large-file-upload.md (6593b), references/linkfox-echotik-batch-product-detail.md (14105b), references/linkfox-echotik-get-video-download-url.md (11627b), references/linkfox-echotik-list-new-product-rank.md (9384b), references/linkfox-echotik-list-product.md (14292b), references/linkfox-echotik-product-video.md (10568b), references/linkfox-fastmoss-product-rank-top-selling.md (11254b), references/linkfox-fastmoss-product-search.md (12740b), references/linkfox-tiktok-video-auth.md (16267b), references/linkfox-tiktok-video-products.md (13589b), references/linkfox-tiktok-video.md (40510b), references/onboarding.md (2068b), scripts/_products_api_runner.py (5541b), scripts/_products_endpoints.py (1768b), scripts/_tiktok_video_common.py (5234b), scripts/_tiktok_video_products_common.py (5246b), scripts/_video_api_runner.py (6057b), scripts/_video_endpoints.py (6373b), scripts/account_tokens.py (2986b), scripts/authorize_url.py (2474b), scripts/authorized_accounts.py (2145b), scripts/check_auth_dependency.py (3958b), scripts/echotik_batch_product_detail.py (13120b), scripts/echotik_get_video_download_url.py (13126b), scripts/echotik_list_new_product_rank.py (13126b), scripts/echotik_list_product_video.py (13091b), scripts/echotik_list_product.py (13060b), scripts/fastmoss_product_rank_top_selling.py (13144b), scripts/fastmoss_product_search.py (13072b), scripts/get_creator_profile.py (892b), scripts/get_shop_products.py (1169b), scripts/get_shoppable_video_precheck_result.py (1279b), scripts/get_shoppable_video_status.py (1212b), scripts/get_showcase_products.py (1287b), scripts/large_file_upload_bind.py (1054b), scripts/large_file_upload_init.py (1070b), scripts/large_file_upload.py (1688b), scripts/onboarding.py (24089b), scripts/post_shoppable_video.py (1766b), scripts/precheck_shoppable_video.py (1734b), scripts/products_api.py (955b), scripts/refresh_token.py (2965b), scripts/response_io.py (18387b), scripts/upload_shoppable_video_file.py (1767b), scripts/video_api.py (1074b), scripts/video_proxy.py (3878b), skill-card.md (3260b), SKILL.md (22605b), _meta.json (163b)\n\nArchive v1.2.0: 47 files, 144526 bytes\n\nFiles: references/large-file-upload.md (6593b), references/linkfox-echotik-batch-product-detail.md (14105b), references/linkfox-echotik-get-video-download-url.md (11627b), references/linkfox-echotik-list-new-product-rank.md (9384b), references/linkfox-echotik-list-product.md (14292b), references/linkfox-echotik-product-video.md (10568b), references/linkfox-fastmoss-product-rank-top-selling.md (11254b), references/linkfox-fastmoss-product-search.md (12740b), references/linkfox-tiktok-video-auth.md (16257b), references/linkfox-tiktok-video-products.md (13589b), references/linkfox-tiktok-video.md (40500b), scripts/_products_api_runner.py (5541b), scripts/_products_endpoints.py (1768b), scripts/_tiktok_video_common.py (5234b), scripts/_tiktok_video_products_common.py (5246b), scripts/_video_api_runner.py (6057b), scripts/_video_endpoints.py (6373b), scripts/account_tokens.py (2986b), scripts/authorize_url.py (2474b), scripts/authorized_accounts.py (2145b), scripts/check_auth_dependency.py (3958b), scripts/echotik_batch_product_detail.py (13120b), scripts/echotik_get_video_download_url.py (13126b), scripts/echotik_list_new_product_rank.py (13126b), scripts/echotik_list_product_video.py (13091b), scripts/echotik_list_product.py (13060b), scripts/fastmoss_product_rank_top_selling.py (13144b), scripts/fastmoss_product_search.py (13072b), scripts/get_creator_profile.py (892b), scripts/get_shop_products.py (1169b), scripts/get_shoppable_video_precheck_result.py (1279b), scripts/get_shoppable_video_status.py (1212b), scripts/get_showcase_products.py (1287b), scripts/large_file_upload_bind.py (1054b), scripts/large_file_upload_init.py (1070b), scripts/large_file_upload.py (1688b), scripts/post_shoppable_video.py (1766b), scripts/precheck_shoppable_video.py (1734b), scripts/products_api.py (955b), scripts/refresh_token.py (2965b), scripts/response_io.py (18387b), scripts/upload_shoppable_video_file.py (1767b), scripts/video_api.py (1074b), scripts/video_proxy.py (3878b), skill-card.md (4022b), SKILL.md (22550b), _meta.json (163b)\n\nArchive v1.0.1: 47 files, 144626 bytes\n\nFiles: references/large-file-upload.md (6593b), references/linkfox-echotik-batch-product-detail.md (14105b), references/linkfox-echotik-get-video-download-url.md (11627b), references/linkfox-echotik-list-new-product-rank.md (9384b), references/linkfox-echotik-list-product.md (14292b), references/linkfox-echotik-product-video.md (10568b), references/linkfox-fastmoss-product-rank-top-selling.md (11254b), references/linkfox-fastmoss-product-search.md (12740b), references/linkfox-tiktok-video-auth.md (16257b), references/linkfox-tiktok-video-products.md (13589b), references/linkfox-tiktok-video.md (40500b), scripts/_products_api_runner.py (5541b), scripts/_products_endpoints.py (1768b), scripts/_tiktok_video_common.py (5234b), scripts/_tiktok_video_products_common.py (5246b), scripts/_video_api_runner.py (6057b), scripts/_video_endpoints.py (6373b), scripts/account_tokens.py (2986b), scripts/authorize_url.py (2474b), scripts/authorized_accounts.py (2145b), scripts/check_auth_dependency.py (3958b), scripts/echotik_batch_product_detail.py (13120b), scripts/echotik_get_video_download_url.py (13126b), scripts/echotik_list_new_product_rank.py (13126b), scripts/echotik_list_product_video.py (13091b), scripts/echotik_list_product.py (13060b), scripts/fastmoss_product_rank_top_selling.py (13144b), scripts/fastmoss_product_search.py (13072b), scripts/get_creator_profile.py (892b), scripts/get_shop_products.py (1169b), scripts/get_shoppable_video_precheck_result.py (1279b), scripts/get_shoppable_video_status.py (1212b), scripts/get_showcase_products.py (1287b), scripts/large_file_upload_bind.py (1054b), scripts/large_file_upload_init.py (1070b), scripts/large_file_upload.py (1688b), scripts/post_shoppable_video.py (1766b), scripts/precheck_shoppable_video.py (1734b), scripts/products_api.py (955b), scripts/refresh_token.py (2965b), scripts/response_io.py (18387b), scripts/upload_shoppable_video_file.py (1767b), scripts/video_api.py (1074b), scripts/video_proxy.py (3878b), skill-card.md (4262b), SKILL.md (22550b), _meta.json (163b)\n\nArchive v1.0.0: 47 files, 144361 bytes\n\nFiles: references/large-file-upload.md (6593b), references/linkfox-echotik-batch-product-detail.md (14105b), references/linkfox-echotik-get-video-download-url.md (11627b), references/linkfox-echotik-list-new-product-rank.md (9384b), references/linkfox-echotik-list-product.md (14292b), references/linkfox-echotik-product-video.md (10568b), references/linkfox-fastmoss-product-rank-top-selling.md (11254b), references/linkfox-fastmoss-product-search.md (12740b), references/linkfox-tiktok-video-auth.md (16257b), references/linkfox-tiktok-video-products.md (13589b), references/linkfox-tiktok-video.md (40500b), scripts/_products_api_runner.py (5541b), scripts/_products_endpoints.py (1768b), scripts/_tiktok_video_common.py (5234b), scripts/_tiktok_video_products_common.py (5246b), scripts/_video_api_runner.py (6057b), scripts/_video_endpoints.py (6373b), scripts/account_tokens.py (2986b), scripts/authorize_url.py (2474b), scripts/authorized_accounts.py (2145b), scripts/check_auth_dependency.py (3958b), scripts/echotik_batch_product_detail.py (13120b), scripts/echotik_get_video_download_url.py (13126b), scripts/echotik_list_new_product_rank.py (13126b), scripts/echotik_list_product_video.py (13091b), scripts/echotik_list_product.py (13060b), scripts/fastmoss_product_rank_top_selling.py (13144b), scripts/fastmoss_product_search.py (13072b), scripts/get_creator_profile.py (892b), scripts/get_shop_products.py (1169b), scripts/get_shoppable_video_precheck_result.py (1279b), scripts/get_shoppable_video_status.py (1212b), scripts/get_showcase_products.py (1287b), scripts/large_file_upload_bind.py (1054b), scripts/large_file_upload_init.py (1070b), scripts/large_file_upload.py (1688b), scripts/post_shoppable_video.py (1766b), scripts/precheck_shoppable_video.py (1734b), scripts/products_api.py (955b), scripts/refresh_token.py (2965b), scripts/response_io.py (18387b), scripts/upload_shoppable_video_file.py (1767b), scripts/video_api.py (1074b), scripts/video_proxy.py (3878b), skill-card.md (3820b), SKILL.md (22395b), _meta.json (163b)","readmeExcerpt":"Skill: Linkfox Tiktok选品与带货视频 Owner: linkfox-ai Summary: TikTok 选品与带货视频一站式 AI 工具集，整合 EchoTik/FastMoss 选品数据与 TikTok 官方带货视频 API，覆盖 TikTok Shop 选品、爆品趋势、带货视频分析与可购物视频发布。 Tags: latest:1.2.3 Version history: v1.2.3 | 2026-08-14T15:20:41.705Z | user Update from 1.2.2 to 1.2.3 v1.2.2 | 2026-08-07T11:25:23.696Z | user Update from 1.2.1 to 1.2.2 v1.2.1 | 2026-08-05T09:00:32.063Z | user Update from 1.2.0 to 1.2.1 v1.2.0 | 2026-07","codeSnippets":[],"executableExamples":[{"language":"json","snippet":"{\"date\": \"2025-06-15\", \"region\": \"US\", \"pageNum\": 1, \"pageSize\": 50}"},{"language":"json","snippet":"{\"keyword\": \"phone case\", \"region\": \"US\", \"minTotalSale30dCnt\": 1000, \"productSortField\": 5, \"sortType\": 1, \"pageSize\": 20}"},{"language":"json","snippet":"{\"region\": \"US\", \"dateInfo\": {\"type\": \"day\", \"value\": \"2026-04-15\"}, \"page\": 1, \"pageSize\": 10}"},{"language":"json","snippet":"{\"keyword\": \"phone case\", \"region\": \"US\", \"orderField\": \"day7_units_sold\", \"pageSize\": 10}"},{"language":"json","snippet":"{\"productIds\": [\"1729382310407603945\", \"1729382310407603946\"]}"},{"language":"json","snippet":"{\"productId\": \"1729382310407603945\", \"productVideoSortField\": 1, \"sortType\": 1, \"pageSize\": 20}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: linkfox-tiktok-selection-and-shoppable-video\ndisplay_name: Linkfox Tiktok选品与带货视频\ndisplay_name_en: LinkFox TikTok Product Selection and Shoppable Video\ndescription: TikTok 选品与带货视频一站式 AI 工具集，整合 EchoTik/FastMoss 选品数据与 TikTok 官方带货视频 API，覆盖 TikTok Shop 选品、爆品趋势、带货视频分析与可购物视频发布。\ndescription_zh: TikTok 选品与带货视频一站式 AI 工具集，整合 3 类工具、10 项子能力：EchoTik（16 区域市场新品排行、商品搜索、商品详情、带货视频、视频下载）、FastMoss（全球热销榜与商品搜索，日周月多维筛选）、TikTok 官方 API（视频号 OAuth 授权与令牌、可购物视频预检/发布/状态/达人档案/大文件上传/可带货商品查询）。覆盖选品、爆品趋势、销量/GMV/达人带货与带货视频分析及可购物视频发布链路。当用户需 TikTok 选品、爆品/新品排行、商品或带货视频分析、视频号授权与可购物视频发布时触发。参数见 references/，脚本见 scripts/。\ndescription_en: One-stop TikTok product-selection and shoppable-video AI toolkit integrating 10 sub-capabilities across 3 tool families — EchoTik (new-product ranking, product search, product detail, promotional-video query, video download URL across 16 regional markets), FastMoss (global top-selling rankings and product search with day/week/month and category/sales/commission/creator multi-dimensional filters), and the TikTok official shoppable-video API (creator OAuth authorization & token management, shoppable video pre-check/publish/status/creator profile/large-file chunked upload, creator sellable-product query). Covers TikTok Shop product research, bestseller/new-product trends, product sales/GMV/live/influencer analysis, promotional-video performance & download, and the full official shoppable-video publishing chain (authorize → get product_id → pre-check → publish → check status). Triggered when the user needs TikTok product selection, bestseller/new-product rankings, product or promotional-video data analysis, or TikTok video-account authorization and shoppable-video publishing. Full params per sub-capability are in references/, executable scripts in scripts/.\ncategory: e-commerce\nversion: 1.0.0\nauthor: LinkFox\n---\n\n# Linkfox Tiktok选品与带货视频（TikTok Product Selection and Shoppable Video）\n\nTikTok 选品与带货视频一站式 AI 工具集，整合 **3 类底层工具、10 项子能力**，覆盖选品数据（EchoTik 16 区域市场 / FastMoss 全球电商）与官方带货视频发布链路（TikTok 视频号授权 → 可带货商品 → 可购物视频预检/发布）。各子能力完整参数、响应字段与错误码见 `references/` 下对应文件，可执行脚本见 `scripts/`。\n\n## 能力边界\n\n### ✅ 能力范围\n- **TikTok 选品数据（`echotik_tiktok`，EchoTik，覆盖 16 个区域市场）**：新品排行发现热销爆品与新兴趋势（`echotik_tiktok` list-new-product-rank）；商品搜索按销量/达人/佣金/评分/评论多维筛选（`echotik_tiktok` list-product）；商品关联带货视频查询播放/互动/视频销量/GMV（`echotik_tiktok` product-video）；批量商品详情含多周期销量与 GMV、直播销量、带货达人数、价格评分与佣金（`echotik_tiktok` batch-product-detail）；解析 TikTok 视频链接返回无水印/含水印下载、播放与封面地址（`echotik_tiktok` get-video-download-url）。\n- **TikTok 全球电商热销与选品（`fastmoss_tiktok`，FastMoss）**：按日/周/月维度与类目分析热销商品排行榜与 GMV 排名（`fastmoss_tiktok` product-rank-top-selling）；按类目/销量/佣金率/达人数/店铺类型多维搜索筛选商品（`fastmoss_tiktok` product-search）。\n- **TikTok 官方带货视频 API（`tiktok_official_video_api`）**：视频号达人 OAuth 授权、已授权账号列表、令牌查询与 access_token 刷新（`tiktok_official_video_api` linkfox-tiktok-video-auth）；可购物视频内容预检、查预检结果、发布、查发布状态、达人档案查询及大文件分片上传（`tiktok_official_video_api` linkfox-tiktok-video）；达人可带货商品查询（店铺商品与橱窗/直播袋商品），取得 product_id 供可购物视频挂车（`tiktok_official_video_a"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n \"slug\": \"linkfox-tiktok-selection-and-shoppable-video\",\n \"version\": \"1.2.3\",\n \"publishedAt\": 1786720841705\n}"},{"path":"references/large-file-upload.md","content":"# 可购物视频大文件分片上传方案（Shoppable Video Large File Upload）\n\n- **来源文档**：[Shoppable Video Large File Upload Solution（Lark）](https://bytedance.sg.larkoffice.com/docx/WTMvdfbTBo30Fex0r9YlYstGg0d)\n- **Partner Center**：[shoppable-video-large-file-upload](https://partner.tiktokshop.com/docv2/page/shoppable-video-large-file-upload)（需登录）\n- **适用场景**：可购物视频文件 **> 10MB**（≤ 10MB 仍可用 §4 直传 `video_files`）\n- **替代关系**：取代旧版「请求头特殊参数」大文件方案；旧方案已于 **2026-01-31** 停止支持\n\n## 方案概述\n\n通过 **文件网关分片上传（chunked upload via file gateway）**：\n\n1. 客户端将 **> 10MB** 的文件按 chunk 切分；\n2. 携带 `upload_token` **顺序**上传各分片至 `upload_url`；\n3. 服务端合并分片还原原文件；\n4. **Bind Business Resource** 将文件绑定到可购物视频业务资源，得到与直传等价的 `file_id`。\n\n≤ 10MB 的文件继续使用 **Upload Shoppable Video File**（`POST .../videos/video_files`）。\n\n## 三步流程\n\n```\nStep 1 Initialize Upload → upload_url + upload_token\nStep 2 Upload Chunks & Merge → PUT 分片至 upload_url（不经 LinkFox 网关）\nStep 3 Bind Business Resource → file_id（供后续发布；可选预检）\n```\n\n| 步骤 | 调用方 | 经 LinkFox `/tiktokVideo/developerProxy` |\n|------|--------|------------------------------------------|\n| 1 Initialize | JSON POST | **可能**（path 须白名单放行，见下） |\n| 2 Upload Chunks | 二进制 PUT | **否** — 直连 Step 1 返回的 `upload_url` |\n| 3 Bind | JSON POST | **可能**（同 Step 1 路径前缀约束） |\n\n---\n\n## Step 1：初始化上传（Initialize Upload）\n\n获取分片上传所需的 `upload_url` 与 `upload_token`。\n\n| 项 | 说明 |\n|----|------|\n| Method | `POST` |\n| 上游 Path | `/open/{version}/file/init`（`:version` 如 `202505`，**以 Lark / Partner 文档为准**） |\n| 经 proxy 的 path 示例 | `open/202505/file/init` |\n\n### Query 参数（紫鸟自动注入）\n\n| 参数 | 说明 |\n|------|------|\n| access_token | 即 creator `access_token` / `ttsAccessToken` |\n| app_key | 紫鸟注入 |\n| timestamp | 紫鸟注入 |\n| sign | 紫鸟注入 |\n\n### 请求体（JSON）\n\n> Lark 文档中 Request Body 字段需以官方最新版为准。常见初始化字段如下（**调用前请对照 Lark 核对**）：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| file_size | int64 | 文件总字节数 |\n| chunk_size | int64 | 分片大小（字节） |\n| file_name | string | 文件名（如 `video.mp4`） |\n| content_type | string | MIME，如 `video/mp4` |\n\n### 成功响应\n\n```json\n{\n \"upload_url\": \"{uploader_url}\",\n \"upload_token\": \"{your_unique_upload_token}\"\n}\n```\n\n| 字段 | 说明 |\n|------|------|\n| upload_url | 分片上传目标 URL（Step 2 使用，**完整 URL 含 query**） |\n| upload_token | 本次上传会话 token（Step 2/3 使用） |\n\n---\n\n## Step 2：上传分片并合并（Upload Chunks & Merge）\n\n将视频二进制 **顺序** PUT 到 Step 1 返回的 **`upload_url`**（文件网关域名，**不经过** LinkFox 网关）。\n\n### 请求要点\n\n| Header | 说明 |\n|--------|------|\n| Content-Type | 视频 MIME，如 `video/mp4` |\n| Content-Length | **当前分片**字节长度 |\n| Content-Range | `bytes {first}-{last}/{total}` |\n\n### 分片规则（参考 TikTok 媒体传输惯例，与 Lark 一致方向）\n\n| 规则 | 说明 |\n|------|------|\n| 顺序 | 分片须 **按序** 上传 |\n| 分片大小 | 单分片建议 **5MB ~ 64MB**；最后一片可含剩余字节（可略大于 chunk_size） |\n| 小文件 | 总大小 < 5MB 时通常整文件一片上传 |\n| 分片数量 | 最少 1 片，最多约 **1000** 片 |\n| chunk 计算 | `total_chunk_count = floor(file_size / chunk_size)`，末片包含余数 |\n\n### PUT 示例（单片 / 末片）\n\n```bash\ncurl --location --request PUT '{upload_url}' \\\n --header 'Content-Type: video/mp4' \\\n --header 'Content-Range: bytes 0-9999999/50000000' \\\n --header 'Content-Length: 10000000' \\\n --data-bina"},{"path":"references/linkfox-echotik-batch-product-detail.md","content":"---\nname: linkfox-echotik-batch-product-detail\ndescription: 批量查询 TikTok 商品的多周期销量、GMV、直播数据、带货达人、价格评分等详情。\n---\n\n# EchoTik TikTok 商品批量详情（Batch Product Detail）\n\n本技能用于批量获取 TikTok 商品的详细表现指标，帮助卖家与运营人员并排对比候选商品的销售、GMV、直播、视频与达人数据。参数与响应字段详见 [references/api.md](references/api.md)。\n\n## 能力边界\n\n### ✅ 能力范围\n\n- 通过商品 ID 或 TikTok Shop 商品 URL 批量查询最多 1000 个商品的详情指标。\n- 返回多周期（1d/7d/15d/30d/60d/90d/累计）销量、GMV、直播销量、直播 GMV、视频、达人、观看次数等数据。\n- 返回价格（USD）、评分、评论数、佣金比例、上下架/全托管状态等。\n\n### ❌ 边界与限制\n\n- **批量上限**：单次请求最多 1000 个商品。\n- **价格币种**：所有价格字段均为 USD。\n- **数据口径**：销量、GMV、归因数据为分析估算值，非平台精确数据。\n- **仅查询已知商品**：本工具不按关键词或类目搜索，只解析用户已有的 ID/URL。\n- **不在范围内**：按关键词发现商品（用 `linkfox-echotik-product-search`）；新品/趋势商品排行（用 `linkfox-echotik-new-product-rank`）；商品关联带货视频（用 `linkfox-echotik-product-video`）；TikTok 视频下载链接解析（用 `linkfox-echotik-get-video-download-url`）；达人主页分析；非 TikTok 平台数据。\n\n## 调用方式\n\n- **API 端点**：`POST /echotik/batchProductDetail`（完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/echotik_batch_product_detail.py '' [--inline]`\n- **成本约束**：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `/linkfox///data/linkfox-echotik-batch-product-detail-.json`（`` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq`或`ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 使用示例\n\n**1. 按商品 ID 批量查询**\n```json\n{\n \"productIds\": [\"1729382310407603945\", \"1729382310407603946\"]\n}\n```\n\n**2. 按商品 URL 批量查询**\n```json\n{\n \"productUrls\": [\n \"https://shop.tiktok.com/us/pdp/phone-case/1729382310407603945\",\n \"https://shop.tiktok.com/us/pdp/case-for-phone/1729382310407603946\"\n ]\n}\n```\n\n**3. ID 与 URL 混合（服务端合并）**\n```json\n{\n \"productIds\": [\"1729382310407603945\"],\n \"productUrls\": [\"https://shop.tiktok.com/us/pdp/phone-case/1729382310407603946\"]\n}\n```\n\n## 展示规则\n\n1. **呈现对比表**：每商品一行，关键列含名称、价格（USD）、总销量、30 天销量、总 GMV、评分、评论数、佣金比例、带货达人数。\n2. **多周期语境**：对比动量时，在累计值旁展示相关窗口（如 7d/30d），而非只看总量。\n3. **币种**：价格为 USD，需标注 USD。\n4. **佣金格式**：`productCommissionRate` 以百分比展示（如 `0.05` → \"5%\"）。\n5. **趋势标识**：`salesTrendFlag` 渲染为稳定/上升/下降，便于快速扫描。\n6. **状态徽标**：在相关位置标注 `isSShop`（全托管）、`offMark`（下架）、`freeShipping`，避免用户误把下架商品纳入对比。\n7. **图片引用**：返回 `imageUrl` / `productImageUrls` 时说明图片可用。\n8. **长描述**：`descDetail` 可能为较长 HTML/文本，做摘要或说明其可用性，而非整段倾倒。\n9. **缺失商品处理**：若请求的商品无记录，列出无数据的 ID/URL 供用户核对。\n10. **错误处理**：查询失败时根据 `errmsg`/`error` 字段说明原因，建议检查 ID/URL。\n\n## 用户表达与场景速查\n\n**适用** —— TikTok 商品批量详情查询：\n\n| 用户说 | 场景 |\n|--------|------|\n| \"查这些 TikTok 商品的详情\" | 按商品 ID 批量详情 |\n| \"拉一下这些 TikTok 链接的销量\" | 按商品 URL 批量详情 |\n| \"对比这些 TikTok 商品的 GMV\" | 批量查询，展示 GMV 列 |\n| \"这些 TikTok 商品哪些在涨\" | 批量查询，读 `salesTrendFlag` |\n| \"这些 TikTok 商品有下架/全托管吗\" | 批量查询，读 `offMark` / `isSShop` |\n| \"查这些 TikTok 商品的直播销量\" | 批量查询，展示直播销量/GMV |\n\n不适用场景见上方【能力边界】。\n\n### 边"},{"path":"references/linkfox-echotik-get-video-download-url.md","content":"---\nname: linkfox-echotik-get-video-download-url\ndescription: 解析 TikTok 视频链接，返回无水印/含水印下载地址、播放地址与封面地址。\n---\n\n# EchoTik TikTok 视频下载地址查询\n\n本技能用于把一个 TikTok 视频链接解析为可直接下载/播放的视频地址，帮助卖家保存带货视频素材或离线分析复用。参数与响应字段详见 [references/api.md](references/api.md)。\n\n## 能力边界\n\n### ✅ 能力范围\n\n- 把单个 TikTok 视频链接解析为：无水印下载地址（`noWatermarkDownloadUrl`）、含水印下载地址（`downloadUrl`）、播放地址（`playUrl`）与封面（静态 `coverUrl` / 动态 `dynamicCoverUrl`）。\n- 支持两种链接格式：短链 `https://vt.tiktok.com/xxxxxx` 与完整链接 `https://www.tiktok.com/@user/video/1234567890`。\n- 适用于归档高表现带货视频、复用创作者素材等场景。\n\n### ❌ 边界与限制\n\n- **必填参数**：必须提供 `url`，最大长度 1000。\n- **下载地址不一定返回**：受区域、隐私或源站限制，部分视频不返回 `noWatermarkDownloadUrl` / `downloadUrl`，仅返回 `playUrl` 与封面；此时应改用 `playUrl` 播放预览，不要伪造下载链接。\n- **链接时效**：返回的下载/播放地址会过期，应在解析后尽快使用；链接失效时需重新解析。\n- **不在范围内**：按商品查询关联带货视频（用 `linkfox-echotik-product-video`，需 `productId`）；TikTok 商品搜索（用 `linkfox-echotik-product-search`）；TikTok 新品榜单（用 `linkfox-echotik-new-product-rank`）；TikTok 直播数据；视频剪辑或内容创作建议；非 TikTok 平台的视频下载。\n\n## 核心概念\n\n本工具接收单个 TikTok 视频链接，解析为直接媒体地址：无水印下载地址（推荐用于干净素材）、含水印下载地址、播放地址与封面（静态/动态）。当卖家想归档通过 EchoTik 商品视频工具发现的高表现带货视频，或复用创作者片段而无需重新录制时，本工具很有用。\n\n**必填输入**：`url` 必填，支持两种格式：\n- 短链：`https://vt.tiktok.com/xxxxxx`\n- 完整链接：`https://www.tiktok.com/@user/video/1234567890`\n\n**下载地址为条件返回**：并非所有视频都返回可下载地址。`noWatermarkDownloadUrl` 与 `downloadUrl` 仅在源视频允许时返回；部分视频（受区域/隐私/可用性限制）两者都缺省，仅返回 `playUrl` 与封面。呈现下载链接前务必检查字段是否存在，下载字段缺失时用 `playUrl` 播放兜底。\n\n**地址时效**：返回的下载/播放地址会随时间失效，应在解析后尽快使用；链接失效时重新解析。\n\n## 调用方式\n\n- **API 端点**：`POST /echotik/getVideoDownloadUrl`（完整参数/响应/错误码见 `references/api.md`）\n- **Python 脚本**：`python scripts/echotik_get_video_download_url.py '' [--inline]`\n- **成本约束**：本工具会消耗积分；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。\n\n**输出策略（脚本默认行为）**：\n- **始终**将完整响应写入 `/linkfox///data/linkfox-echotik-get-video-download-url-.json`（`` 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；`` 取自环境变量 `SESSION_ID`，按用户任务自动聚合；**禁止写入 /tmp**，当前目录不可写则报错）\n- 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout\n- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 `total`/`costToken`、最大列表字段的长度 + 前 3 条样本）\n- 加 `--inline` 强制全量打印到 stdout（同样落盘）\n\n**读数据建议**：先看摘要判断是否足够；需要具体字段时优先用 `jq` 或 `ConvertFrom-Json` 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 使用示例\n\n**1. 解析完整 TikTok 视频链接**\n```json\n{\n \"url\": \"https://www.tiktok.com/@user/video/1234567890\"\n}\n```\n\n**2. 解析 TikTok 短链**\n```json\n{\n \"url\": \"https://vt.tiktok.com/Z123abc/\"\n}\n```\n\n## 展示规则\n\n1. **优先呈现无水印链接**：`noWatermarkDownloadUrl` 存在时，作为首选下载选项呈现，因为干净素材通常是卖家想要的。\n2. **同时提供含水印版本**：`downloadUrl`（含水印）存在时也列出，以备用户需要原版品牌。\n3. **处理下载地址缺失**：`noWatermarkDownloadUrl` 与 `downloadUrl` 都缺失时（部分视频常见），不要伪造下载链接——告知用户该视频无直接下载地址，改用 `playUrl` 播放/预览。\n4. **提供播放与封面**：说明 `playUrl` 可快速预览，`coverUrl` / `dynamicCoverUrl` 作为缩略图。\n5. **时效提醒**：提醒用户解析的地址会过期，应尽快下载。\n6. **只呈现数据**：清晰展示解析出的地址，不对视频如何使用做主观建议。\n7. **错误处理**：解析失败时根据 `errcode`/`errmsg` 说明原因——`400` 表示 `url` 缺失或无效，`10000` 表示链接非有效/可访问的 TikTok 视频；建议检查 URL 格式。\n\n## 用户表达与场景速查\n\n**适用** —— TikTok 视频下载与素材保存：\n\n| 用户说 | 场景 |\n|--------|------|\n| \"下载这个 TikTok 视频\"、\"保存这个 Ti"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"TikTok 选品与带货视频一站式 AI 工具集，整合 EchoTik/FastMoss 选品数据与 TikTok 官方带货视频 API，覆盖 TikTok Shop 选品、爆品趋势、带货视频分析与可购物视频发布。 Skill: Linkfox Tiktok选品与带货视频 Owner: linkfox-ai Summary: TikTok 选品与带货视频一站式 AI 工具集，整合 EchoTik/FastMoss 选品数据与 TikTok 官方带货视频 API，覆盖 TikTok Shop 选品、爆品趋势、带货视频分析与可购物视频发布。 Tags: latest:1.2.3 Version history: v1.2.3 | 2026-08-14T15:20:41.705Z | user Update from 1.2.2 to 1.2.3 v1.2.2 | 2026-08-07T11:25:23.696Z | user Update from 1.2.1 to 1.2.2 v1.2.1 | 2026-08-05T09:00:32.063Z | user Update from 1.2.0 to 1.2.1 v1.2.0 | 2026-07","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":956,"uniquenessScore":47,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-12T01:13:45.938Z","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-12T01:13:45.938Z","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-12T04:35:29.877Z","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"}]}}}