{"id":"fdc31cf2-4a45-41e5-8ccd-bb05f04e7c13","entityType":"agent","slug":"clawhub-creativault-cv-creator-scraper","name":"Creativault Creator Scraper","canonicalUrl":"https://www.xpersona.co/agent/clawhub-creativault-cv-creator-scraper","canonicalPath":"/agent/clawhub-creativault-cv-creator-scraper","generatedAt":"2026-10-10T17:34:12.582Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T14:34:01.311Z","emptyReason":null},"description":"Creativault creator data collection and outreach skill. Search and collect creator/influencer data from TikTok, YouTube, Instagram, and Twitter. Send outreac...","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.4K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s175rhgkqrbn4p21m7we31s2jn859srf:cv-creator-scraper","sourceUrl":"https://clawhub.ai/creativault/cv-creator-scraper","homepage":"https://clawhub.ai/creativault/skills/cv-creator-scraper","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/creativault/cv-creator-scraper","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/creativault/skills/cv-creator-scraper","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":63,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Creativault Creator Scraper technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T14:34:01.311Z","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-10T14:34:01.311Z","emptyReason":null},"stars":null,"forks":null,"downloads":1384,"packageName":null,"latestVersion":"1.8.0","tractionLabel":"1.4K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T14:34:01.311Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T14:34:01.311Z","lastCrawledAt":"2026-10-10T14:34:01.311Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T14:34:01.311Z","lastVerifiedAt":null,"highlights":[{"version":"1.8.0","createdAt":"2026-06-10T02:35:06.042Z","changelog":"- Added scripts for skill update checks and manifest generation. - Introduced skill-manifest.json and skill.json for improved version and release management. - Updated prerequisites and documentation to support optional auto-update and manual update via CLI scripts. - Enhanced version update notification rules and guidance in the documentation. - Removed obsolete skill-card.md file. - Bumped internal version to 1.8.0.","fileCount":38,"zipByteSize":74129},{"version":"1.0.8","createdAt":"2026-06-04T14:19:44.326Z","changelog":"- Major update: skills have been modularized into sub-skills for search, lookalike discovery, batch collection, outreach, and workflow, each with its own documentation. - Now includes support for Twitter platform in addition to TikTok, YouTube, and Instagram. - Introduced a clear ecosystem overview and routing table matching user intentions to specific sub-skills. - Updated error handling section and clarified points system logic—only error code 40201 should trigger balance warnings. - Deprecated the monolithic SKILL.md in favor of a structured, multi-file documentation system.","fileCount":34,"zipByteSize":60222},{"version":"1.0.7","createdAt":"2026-05-29T10:52:52.864Z","changelog":"update","fileCount":26,"zipByteSize":47728},{"version":"1.0.6","createdAt":"2026-05-29T09:17:24.449Z","changelog":"- No other changes to functionality or documentation.","fileCount":26,"zipByteSize":47364},{"version":"1.0.5","createdAt":"2026-05-29T08:56:07.383Z","changelog":"**Outreach email and campaign management added.** - Added outreach capabilities, including new scripts for sending emails, querying contact info, managing outreach tasks, and follow-up tracking. - Updated SKILL.md to describe new outreach features and decision rules for email-related actions. - Added scripts: outreach_contact.mjs, outreach_send.mjs, outreach_task.mjs, outreach_todo.mjs. - Description and use case expanded to cover outreach, campaign tracking, and related workflows.","fileCount":25,"zipByteSize":46288},{"version":"1.0.4","createdAt":"2026-05-09T11:12:13.116Z","changelog":"No functional changes detected. Version and documentation updated only. - Increased version in metadata from 1.2.0 to 1.5.0. - Updated S2 and S3 service level field descriptions for greater detail in SKILL.md. - No changes made to code, scripts, or logic.","fileCount":21,"zipByteSize":38500},{"version":"1.0.3","createdAt":"2026-04-29T08:17:12.400Z","changelog":"cv-creator-scraper 1.0.3 - Added new script: scripts/_industry_mapper.mjs - No changes to existing functionality; existing SKILL.md remains unchanged. - The new script may support future or internal features (e.g., industry mapping).","fileCount":20,"zipByteSize":35803},{"version":"1.0.2","createdAt":"2026-04-24T04:41:52.228Z","changelog":"- Removed the script scripts/resolve_creator.mjs. - Updated documentation to use find_lookalike.mjs directly for \"similar creator\" discovery (username/URL is now auto-resolved). - The \"Resolve creator username\" capability and workflow were removed from the capabilities list and decision rules. - \"Find similar/lookalike creators\" workflow now simplified in both capabilities and approach tables.","fileCount":19,"zipByteSize":30358}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s175rhgkqrbn4p21m7we31s2jn859srf:cv-creator-scraper","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s175rhgkqrbn4p21m7we31s2jn859srf:cv-creator-scraper` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/creativault/cv-creator-scraper before using production credentials."],"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-creativault-cv-creator-scraper/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-creativault-cv-creator-scraper/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-creativault-cv-creator-scraper/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-creativault-cv-creator-scraper/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-creativault-cv-creator-scraper/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-creativault-cv-creator-scraper/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-10T17:34:12.577Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-creativault-cv-creator-scraper/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-creativault-cv-creator-scraper/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-creativault-cv-creator-scraper/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-creativault-cv-creator-scraper/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":"medium","updatedAt":"2026-10-10T14:34:01.311Z","emptyReason":null},"readme":"Skill: Creativault Creator Scraper\n\nOwner: creativault\n\nSummary: Creativault creator data collection and outreach skill. Search and collect creator/influencer data from TikTok, YouTube, Instagram, and Twitter. Send outreac...\n\nTags: KOL:1.0.0, creator:1.0.0, data-collection:1.0.0, influencer:1.0.0, instagram:1.0.0, latest:1.8.0, scraper:1.0.0, social-media:1.0.0, tiktok:1.0.0, youtube:1.0.0\n\nVersion history:\n\nv1.8.0 | 2026-06-10T02:35:06.042Z | user\n\n- Added scripts for skill update checks and manifest generation.\n- Introduced skill-manifest.json and skill.json for improved version and release management.\n- Updated prerequisites and documentation to support optional auto-update and manual update via CLI scripts.\n- Enhanced version update notification rules and guidance in the documentation.\n- Removed obsolete skill-card.md file.\n- Bumped internal version to 1.8.0.\n\nv1.0.8 | 2026-06-04T14:19:44.326Z | user\n\n- Major update: skills have been modularized into sub-skills for search, lookalike discovery, batch collection, outreach, and workflow, each with its own documentation.\n- Now includes support for Twitter platform in addition to TikTok, YouTube, and Instagram.\n- Introduced a clear ecosystem overview and routing table matching user intentions to specific sub-skills.\n- Updated error handling section and clarified points system logic—only error code 40201 should trigger balance warnings.\n- Deprecated the monolithic SKILL.md in favor of a structured, multi-file documentation system.\n\nv1.0.7 | 2026-05-29T10:52:52.864Z | user\n\nupdate\n\nv1.0.6 | 2026-05-29T09:17:24.449Z | user\n\n- No other changes to functionality or documentation.\n\nv1.0.5 | 2026-05-29T08:56:07.383Z | user\n\n**Outreach email and campaign management added.**\n\n- Added outreach capabilities, including new scripts for sending emails, querying contact info, managing outreach tasks, and follow-up tracking.\n- Updated SKILL.md to describe new outreach features and decision rules for email-related actions.\n- Added scripts: outreach_contact.mjs, outreach_send.mjs, outreach_task.mjs, outreach_todo.mjs.\n- Description and use case expanded to cover outreach, campaign tracking, and related workflows.\n\nv1.0.4 | 2026-05-09T11:12:13.116Z | user\n\nNo functional changes detected. Version and documentation updated only.\n\n- Increased version in metadata from 1.2.0 to 1.5.0.\n- Updated S2 and S3 service level field descriptions for greater detail in SKILL.md.\n- No changes made to code, scripts, or logic.\n\nv1.0.3 | 2026-04-29T08:17:12.400Z | user\n\ncv-creator-scraper 1.0.3\n\n- Added new script: scripts/_industry_mapper.mjs\n- No changes to existing functionality; existing SKILL.md remains unchanged.\n- The new script may support future or internal features (e.g., industry mapping).\n\nv1.0.2 | 2026-04-24T04:41:52.228Z | user\n\n- Removed the script scripts/resolve_creator.mjs.\n- Updated documentation to use find_lookalike.mjs directly for \"similar creator\" discovery (username/URL is now auto-resolved).\n- The \"Resolve creator username\" capability and workflow were removed from the capabilities list and decision rules.\n- \"Find similar/lookalike creators\" workflow now simplified in both capabilities and approach tables.\n\nv1.0.0 | 2026-04-21T04:16:43.149Z | user\n\nInitial release of creator-scraper-cv skill for creator data collection across TikTok, YouTube, and Instagram.\n\n- Supports creator/influencer search with filters, similar/lookalike creator discovery, and batch data collection by links/usernames/keywords.\n- Includes task management, status polling, and export features (xlsx, csv, html).\n- Output results in structured, easy-to-read tables with quota/credit statistics and explicit service level display.\n- Service level (S1, S2, S3) selection enforced, with clear user prompts and stats disclosure.\n- Multilingual output based on user language (Chinese/English); dedicated formatting templates for each platform.\n- Prompts users for data export after displaying results.\n\nArchive index:\n\nArchive v1.8.0: 38 files, 74129 bytes\n\nFiles: collection/creator-collection/SKILL.md (7853b), discovery/creator-lookalike/SKILL.md (5182b), discovery/creator-search/SKILL.md (11301b), outreach/creator-outreach/SKILL.md (6640b), references/api-reference.md (12445b), references/country-codes.md (2150b), references/error-codes.md (2699b), references/industry-categories.md (10763b), references/language-codes.md (1373b), references/platform-params.md (16727b), scripts/_api_client.mjs (9107b), scripts/_industry_mapper.mjs (27879b), scripts/export_task_data.mjs (1116b), scripts/export_to_csv.mjs (4133b), scripts/find_lookalike.mjs (945b), scripts/generate_manifest.mjs (6088b), scripts/get_download_url.mjs (644b), scripts/get_task_data.mjs (522b), scripts/get_task_status.mjs (456b), scripts/influencer_industry_tree.json (36021b), scripts/langfuse/test_cases.json (5616b), scripts/outreach_contact.mjs (671b), scripts/outreach_send.mjs (1711b), scripts/outreach_task.mjs (2484b), scripts/outreach_todo.mjs (574b), scripts/poll_task_status.mjs (2041b), scripts/search_creators.mjs (873b), scripts/skill_update.mjs (10732b), scripts/submit_collection_task.mjs (1317b), scripts/submit_keyword_task.mjs (859b), skill-card.md (2689b), skill-manifest.json (9989b), skill.json (351b), SKILL.md (6062b), workflow/SKILL.md (4283b), workflow/workflows/batch-outreach.md (2341b), workflow/workflows/full-campaign.md (3258b), _meta.json (137b)\n\nFile v1.8.0:collection/creator-collection/SKILL.md\n\n---\r\nname: creator-collection\r\ndescription: |\r\n  批量达人数据采集与导出能力，支持 TikTok、YouTube、Instagram、Twitter 四平台。支持链接批量、用户名批量、关键词采集三种模式。异步任务机制，含提交、轮询、取数、导出完整生命周期。\r\n  Use when: 批量采集, 数据导出, 离线采集, batch collection, data export, keyword collection\r\ncompatibility: Node.js 20.6+\r\nmetadata:\r\n  layer: collection\r\n  parent: creator-scraper-cv\r\n---\r\n\r\n## 概述\r\n\r\n批量达人数据采集与导出能力。支持通过链接、用户名或关键词提交异步采集任务，自动轮询任务状态，完成后导出为 xlsx/csv/html 文件并提供下载链接。\r\n\r\n支持平台：TikTok、YouTube、Instagram、Twitter。\r\n\r\n> **Twitter 平台限制**：仅支持 `LINK_BATCH`（链接采集）和 `FILE_UPLOAD`（用户名采集），不支持视频采集（`CREATOR_VIDEO`、`POST_VIDEO`）。\r\n\r\n## 脚本引用\r\n\r\n| # | 脚本 | 路径 | 状态 |\r\n|---|------|------|------|\r\n| 1 | submit_collection_task.mjs | `../../scripts/submit_collection_task.mjs` | ✅ |\r\n| 2 | submit_keyword_task.mjs | `../../scripts/submit_keyword_task.mjs` | ✅ |\r\n| 3 | poll_task_status.mjs | `../../scripts/poll_task_status.mjs` | ✅ |\r\n| 4 | get_task_status.mjs | `../../scripts/get_task_status.mjs` | ✅ |\r\n| 5 | get_task_data.mjs | `../../scripts/get_task_data.mjs` | ✅ |\r\n| 6 | export_task_data.mjs | `../../scripts/export_task_data.mjs` | ✅ |\r\n| 7 | export_to_csv.mjs | `../../scripts/export_to_csv.mjs` | ✅ |\r\n| 8 | get_download_url.mjs | `../../scripts/get_download_url.mjs` | ✅ |\r\n\r\n## 异步任务生命周期\r\n\r\n采集任务为异步操作（耗时 5~30 分钟），遵循四阶段流程：\r\n\r\n```\r\n提交(submit) → 轮询(poll) → 取数(get data) → 导出(export)\r\n```\r\n\r\n| 阶段 | 脚本 | 说明 |\r\n|------|------|------|\r\n| 1. 提交 | `submit_collection_task.mjs` / `submit_keyword_task.mjs` | 返回 task_id |\r\n| 2. 轮询 | `poll_task_status.mjs` | 每 60s 自动轮询直到终态 |\r\n| 3. 取数 | `get_task_data.mjs` | 分页获取原始 JSON 数据（仅在用户明确要求时使用） |\r\n| 4. 导出 | `export_task_data.mjs` | 生成文件并返回下载链接 |\r\n\r\n### 任务状态与终态判断\r\n\r\n| 状态 | 含义 | 是否终态 |\r\n|------|------|---------|\r\n| `processing` | 处理中（爬取中或数据入库中） | ❌ 继续轮询 |\r\n| `completed` | 已完成 | ✅ 可取数/导出 |\r\n| `failed` | 失败 | ✅ 报告错误 |\r\n| `timeout` | 超时 | ✅ 报告超时 |\r\n\r\n> **[禁止] 在 `status: \"processing\"` 时提前报告结果。**\r\n> 即使 `progress: 100%`，只要 `status` 仍为 `processing`，说明数据仍在入库处理中，**不能**判定为\"0 条数据\"或\"无匹配结果\"。\r\n> 必须等到 `status` 变为 `completed` / `failed` / `timeout` 之一后，才能向用户报告最终结果。\r\n>\r\n> **典型场景**：`progress: 100%, completed: 0, status: processing` — 爬取已完成但数据尚未入库，继续轮询等待 `completed` 状态。\r\n\r\n> **规则**：采集完成后（`status: completed`），**必须**先调用 `export_task_data.mjs` 生成可下载文件并展示链接给用户。不要直接调用 `get_task_data.mjs` 输出原始 JSON。\r\n\r\n> **积分提醒规则**：仅当接口明确返回错误码 `40201` 时提示积分不足。`meta.quota_remaining` 是当天剩余 API 请求次数，不是积分余额；采集、轮询或导出成功后，禁止根据该字段生成“剩余积分不足”提醒。\r\n\r\n辅助脚本：\r\n- `get_task_status.mjs` — 单次查询任务状态（不轮询）\r\n- `export_to_csv.mjs` — 管道式本地 CSV 导出（接收 stdin JSON）\r\n- `get_download_url.mjs` — 获取已生成文件的下载链接\r\n\r\n## 采集类型\r\n\r\n| 类型 | task_type 值 | 触发场景 | 提交脚本 |\r\n|------|-------------|----------|----------|\r\n| 链接批量 | `LINK_BATCH` | 用户提供达人主页链接列表 | `submit_collection_task.mjs` |\r\n| 用户名批量 | `FILE_UPLOAD` | 用户提供用户名列表 | `submit_collection_task.mjs` |\r\n| 关键词采集 | — | 用户提供关键词，按关键词批量采集 | `submit_keyword_task.mjs` |\r\n\r\n**使用示例**：\r\n\r\n```bash\r\n# 链接批量采集\r\nnode ../../scripts/submit_collection_task.mjs '{\"task_type\":\"LINK_BATCH\",\"platform\":\"tiktok\",\"values\":[\"https://www.tiktok.com/@creator1\",\"https://www.tiktok.com/@creator2\"],\"task_name\":\"Q1 collection\"}'\r\n\r\n# 用户名批量采集\r\nnode ../../scripts/submit_collection_task.mjs '{\"task_type\":\"FILE_UPLOAD\",\"platform\":\"tiktok\",\"values\":[\"creator1\",\"creator2\"],\"task_name\":\"username batch\"}'\r\n\r\n# 关键词采集\r\nnode ../../scripts/submit_keyword_task.mjs '{\"platform\":\"tiktok\",\"keywords\":[\"beauty tips\",\"skincare routine\"]}'\r\n\r\n# Twitter 链接批量采集\r\nnode ../../scripts/submit_collection_task.mjs '{\"task_type\":\"LINK_BATCH\",\"platform\":\"twitter\",\"values\":[\"https://x.com/creator1\",\"https://x.com/creator2\"],\"task_name\":\"Twitter collection\"}'\r\n```\r\n\r\n## 平台支持矩阵\r\n\r\n| 平台 | `LINK_BATCH` | `FILE_UPLOAD` | `CREATOR_VIDEO` | `POST_VIDEO` | 关键词采集 |\r\n|------|:---:|:---:|:---:|:---:|:---:|\r\n| TikTok | ✅ | ✅ | ✅ | ✅ | ✅ |\r\n| YouTube | ✅ | ✅ | ✅ | ✅ | ✅ |\r\n| Instagram | ✅ | ✅ | ✅ | ✅ | ✅ |\r\n| Twitter | ✅ | ✅ | ❌ | ❌ | ✅ |\r\n\r\n> **Twitter 限制**：仅支持链接采集和用户名采集，不支持视频采集（`CREATOR_VIDEO`、`POST_VIDEO`）。\r\n\r\n## 参数说明\r\n\r\n### submit_collection_task.mjs\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `task_type` | string | **必填**。`LINK_BATCH`（链接）/ `FILE_UPLOAD`（用户名） |\r\n| `platform` | string | **必填**。`tiktok` / `youtube` / `instagram` / `twitter` |\r\n| `values` | string[] | **必填**。链接或用户名数组，最多 200 条 |\r\n| `task_name` | string | 任务名称 |\r\n| `webhook_url` | string | 完成回调 URL（HTTPS） |\r\n\r\n### submit_keyword_task.mjs\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `platform` | string | **必填**。`tiktok` / `youtube` / `instagram` / `twitter` |\r\n| `keywords` | string[] | **必填**。关键词列表，最多 10 个 |\r\n| `task_name` | string | 任务名称 |\r\n| `webhook_url` | string | 完成回调 URL（HTTPS） |\r\n\r\n### poll_task_status.mjs\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `task_id` | string | **必填**。任务 ID |\r\n| `interval` | integer | 轮询间隔秒数，默认 60 |\r\n| `max_attempts` | integer | 最大轮询次数，默认 45（约 45 分钟） |\r\n\r\n### get_task_data.mjs\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `task_id` | string | **必填**。任务 ID |\r\n| `page` | integer | 页码，默认 1 |\r\n| `size` | integer | 每页条数，默认 20，最大 100 |\r\n\r\n### export_task_data.mjs\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `task_id` | string | **必填**。任务 ID（必须已完成） |\r\n| `format` | string | **必填**。`xlsx` / `csv` / `html` |\r\n\r\n> 重复调用相同 task_id + format 会返回缓存文件，不会重复生成。\r\n\r\n## 输出格式\r\n\r\n### 导出格式\r\n\r\n| 格式 | 说明 |\r\n|------|------|\r\n| `xlsx` | Excel 格式（默认推荐） |\r\n| `csv` | CSV 格式 |\r\n| `html` | HTML 表格格式 |\r\n\r\n### 下载链接\r\n\r\n`export_task_data.mjs` 返回 `file_url` 字段，为 OSS 签名下载链接。如需重新获取链接，使用 `get_download_url.mjs`：\r\n\r\n```bash\r\nnode ../../scripts/get_download_url.mjs '{\"file_id\":\"xxx\"}'\r\n# 或\r\nnode ../../scripts/get_download_url.mjs '{\"file_name\":\"task_xxx.xlsx\"}'\r\n```\r\n\r\n`export_to_csv.mjs` 为本地管道导出，通过 stdin 接收 JSON 数据：\r\n\r\n```bash\r\nnode ../../scripts/get_task_data.mjs '{\"task_id\":\"xxx\",\"size\":100}' | node ../../scripts/export_to_csv.mjs '{\"output\":\"creators.csv\"}'\r\n```\n\nFile v1.8.0:discovery/creator-lookalike/SKILL.md\n\n---\r\nname: creator-lookalike\r\ndescription: |\r\n  相似达人发现能力，支持种子达人解析、相似度匹配、跨平台搜索。通过 username、profile_url 或自动全平台搜索找到风格相似的创作者。\r\n  Use when: 相似达人, 类似达人, similar creators, lookalike, find similar\r\ncompatibility: Node.js 20.6+\r\nmetadata:\r\n  layer: discovery\r\n  parent: creator-scraper-cv\r\n---\r\n\r\n## 概述\r\n\r\n基于种子达人查找风格相似的创作者，支持同平台匹配和跨平台发现（如从 TikTok 达人找到 YouTube 上的相似创作者）。\r\n\r\n## 脚本引用\r\n\r\n| 脚本 | 路径 | 模式 | 状态 |\r\n|------|------|------|------|\r\n| find_lookalike.mjs | `../../scripts/find_lookalike.mjs` | Sync, 自动解析 username/URL | ✅ |\r\n\r\n## 输入方式\r\n\r\nAPI 内部自动将 username/URL 解析为平台 ID，无需额外 resolve 步骤。\r\n\r\n### 方式一：username + platform（指定平台）\r\n\r\n明确指定达人所在平台，直接在该平台查找相似达人：\r\n\r\n```bash\r\nnode ../../scripts/find_lookalike.mjs '{\"username\":\"creator_demo\",\"platform\":\"tiktok\",\"limit\":10}'\r\n```\r\n\r\n### 方式二：profile_url（自动识别平台）\r\n\r\n传入达人主页链接，API 自动解析平台和用户名：\r\n\r\n```bash\r\nnode ../../scripts/find_lookalike.mjs '{\"profile_url\":\"https://www.tiktok.com/@creator_demo\",\"limit\":10}'\r\n```\r\n\r\n支持的 URL 格式：\r\n- TikTok: `https://www.tiktok.com/@username`\r\n- YouTube: `https://www.youtube.com/@username`\r\n- Instagram: `https://www.instagram.com/username`\r\n\r\n### 方式三：username only（搜索全平台）\r\n\r\n仅传入用户名，不指定平台，API 自动在 TikTok、YouTube、Instagram 三个平台搜索匹配：\r\n\r\n```bash\r\nnode ../../scripts/find_lookalike.mjs '{\"username\":\"creator_demo\",\"limit\":10}'\r\n```\r\n\r\n## 参数说明\r\n\r\n| 参数 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `username` | string | 二选一 | 达人用户名（不含 `@`），与 `profile_url` 二选一 |\r\n| `platform` | string | 否 | 种子达人平台：`tiktok` / `youtube` / `instagram`，省略则搜索全平台 |\r\n| `profile_url` | string | 二选一 | 达人主页链接（自动识别平台），与 `username` 二选一 |\r\n| `target_platform` | string | 否 | 目标搜索平台，省略则与种子达人同平台。设为不同平台可实现跨平台搜索 |\r\n| `target_region` | string | 否 | 目标国家代码，`all` 表示不限 |\r\n| `target_language` | string | 否 | 目标语言代码，`all` 表示不限 |\r\n| `limit` | integer | 否 | 返回数量，默认 20，最大 50 |\r\n| `follower_min` | integer | 否 | 最小粉丝数 |\r\n| `follower_max` | integer | 否 | 最大粉丝数 |\r\n| `avg_views_min` | integer | 否 | 最小平均播放量 |\r\n| `avg_views_max` | integer | 否 | 最大平均播放量 |\r\n| `female_rate_min` | number | 否 | 最小女性受众比例（0~100） |\r\n| `lang` | string | 否 | 响应语言：`cn` / `en`，仅控制返回字段翻译，不筛选达人 |\r\n| `service_level` | string | 否 | 服务等级，默认 `S1` |\r\n\r\n### 跨平台搜索说明\r\n\r\n设置 `target_platform` 与种子达人不同平台，可发现跨平台相似达人：\r\n\r\n```bash\r\n# 从 TikTok 达人找 YouTube 上的相似创作者\r\nnode ../../scripts/find_lookalike.mjs '{\"username\":\"creator_demo\",\"platform\":\"tiktok\",\"target_platform\":\"youtube\",\"limit\":10}'\r\n```\r\n\r\n## 输出格式\r\n\r\n```\r\n🔍 找到 N 个与 @seed_username 相似的达人\r\n\r\n📊 相似达人列表\r\n\r\n| #   | 用户名      | 昵称        | 粉丝数  | 平均播放 | 互动率  | 相似度  | 国家 | 主页链接          |\r\n| --- | ----------- | ----------- | ------- | -------- | ------- | ------ | ---- | ----------------- |\r\n| 1   | username1   | Nickname1   | 120K    | 3.8万    | 7.20%   | 85.0%  | US   | [查看][link1]     |\r\n| 2   | username2   | Nickname2   | 95.5K   | 2.1万    | 5.50%   | 78.3%  | US   | [查看][link2]     |\r\n\r\n[link1]: https://www.tiktok.com/@username1\r\n[link2]: https://www.tiktok.com/@username2\r\n\r\n📈 统计信息\r\n• 种子达人：@seed_username（平台ID：7123456789）\r\n• 结果总数：N 个相似达人\r\n• 本次消耗：10 积分\r\n• 剩余配额：xxx 次\r\n• 请求ID：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\r\n```\r\n\r\n返回字段：`uid`、`username`、`nickname`、`avatar_url`、`profile_url`、`country_code`、`followers_count`、`avg_views`、`engagement_rate`、`match_score`。\r\n\r\n其中 `match_score` 为相似度评分（0~100），按相似度降序排列。\r\n\r\n## 错误处理\r\n\r\n| 错误码 | 说明 | 处理方式 |\r\n|--------|------|----------|\r\n| 40401 | 达人不在数据库中 | 告知用户该达人尚未被平台收录，建议换一个达人或提交采集任务 |\r\n| 40001 | 参数无效 | 检查 username/profile_url 格式 |\r\n| 42902 | 每日配额耗尽 | 等待 UTC 00:00 重置或升级套餐 |\r\n\r\n## 决策规则\r\n\r\n- 用户给出主页链接 → 使用 `profile_url` 参数\r\n- 用户给出用户名 + 平台 → 使用 `username` + `platform`\r\n- 用户仅给出用户名 → 仅传 `username`，API 搜索全平台\r\n- 用户要求\"找 YouTube 上类似的\" → 设置 `target_platform: \"youtube\"`\n\nFile v1.8.0:discovery/creator-search/SKILL.md\n\n---\nname: creator-search\ndescription: |\n  三平台达人搜索能力，支持 TikTok、YouTube、Instagram 多维度筛选（关键词、国家、粉丝数、互动率、类目等）。\n  Use when: 达人搜索, KOL搜索, 找达人, creator search, influencer discovery, search creators\ncompatibility: Node.js 20.6+\nmetadata:\n  layer: discovery\n  parent: creator-scraper-cv\n---\n\n# Creator Search（达人搜索）\n\n## 概述\n\n三平台（TikTok、YouTube、Instagram）达人实时搜索，支持关键词、国家、粉丝数、互动率、行业等多维度筛选，结果即时返回。\n\n## 脚本引用\n\n| 脚本 | 相对路径 | 状态 |\n|------|----------|------|\n| search_creators.mjs | `../../scripts/search_creators.mjs` | ✅ 可用 |\n\n调用格式：\n\n```bash\nnode {baseDir}/scripts/search_creators.mjs '{\"platform\":\"tiktok\",\"country_code\":\"US\",\"gender\":\"0\",\"followers_cnt_gte\":100000,\"service_level\":\"S2\"}'\n```\n\n## 参数提取强制规则\n\n1. `platform` 必须转换为小写：`tiktok` / `youtube` / `instagram`。\n2. 达人性别必须映射为编码：女性/女/female → `\"0\"`，男性/男/male → `\"1\"`。禁止传 `\"女性\"`、`\"男性\"`、`\"female\"`、`\"male\"`。\n3. 所有比例筛选参数使用 **0~100 的百分比数值**：用户说“互动率至少 3%”时传 `3`，不能传 `0.03`；“女性受众至少 70%”传 `70`。\n4. boolean 参数必须传 JSON boolean：`true` / `false`，不能传 `\"true\"` / `\"false\"`、`1` / `0`。`has_email`、`has_whatsapp`、`is_ai_creator`、`is_product_kol` 等均属于 boolean。\n5. 国家和语言必须转换为代码；多选使用英文逗号连接，例如 `country_code: \"US,CA\"`、`language_code: \"en,fr\"`。\n6. 日期筛选统一传 `YYYY-MM-DD`。\n7. `lang` 只控制响应码值翻译，不用于筛选达人，默认 `en`。筛选达人内容语言使用 `language_code`。\n8. 只传目标平台支持的字段。三平台播放量、互动率、受众语言等字段名并不完全相同。\n9. 当前 HTTP Open API 不支持 Instagram 的 GMV、销售商品数筛选，不要发送这些字段。\n10. 不要发送旧字段名。HTTP Open API 请求模型会忽略未声明字段，旧字段可能请求成功但实际没有产生筛选效果。\n11. **行业 vs 关键词的决策逻辑**：\n    - **用户明确指定**\"行业\"或\"关键词\"时，按用户意图走,不要替换。例如用户说\"关键词搜 funny\"就用 `keyword`，说\"行业选美妆\"就用 `industry`。\n    - **用户未明确区分**时（如\"找搞笑达人\"、\"美妆博主\"），优先映射为 `industry`。常见映射：搞笑/funny → Comedy & Humor, 美妆/beauty → Skincare 或 Beauty, 科技/tech → Technology, 宠物/pet → Pet Supplies, 美食/food → Food & Beverage。\n    - **行业搜索结果为空时**（返回 0 条），自动用同义词降级为 `keyword` 重新搜索,并告知用户\"行业筛选无结果,已改用关键词搜索\"。例如 `industry: \"Comedy & Humor\"` 返回空 → 用 `keyword: \"funny\"` 重搜。\n    - `keyword` 仅用于：搜索具体用户名/昵称、精确主题词、或行业降级兜底。\n\n## 服务等级\n\n`service_level` 控制返回字段与积分消耗。面向用户发起搜索前，必须让用户清楚三档含义：\n\n- 用户未指定等级时，先展示下方简短表格，并说明默认推荐 `S2`。\n- 用户确认“默认/推荐/直接搜”时，使用 `S2`。\n- 用户明确指定 `S1` / `S2` / `S3`，或本轮对话已展示过等级说明时，可直接执行，避免重复打断。\n\n| 等级 | 名称 | 积分/条 | 返回范围 |\n|------|------|---------|----------|\n| S1 | 纯名单筛选 | 1 | 基础身份、主页、联系方式存在性、最近发布时间；具体字段因平台而异 |\n| S2 | 精准触达 | 3 | S1 + 国家、性别、粉丝/播放/互动、行业、邮箱等；具体字段因平台而异 |\n| S3 | 深度画像 | 4 | S2 + 受众性别、国家、语言、年龄分布 |\n\n## 通用请求参数\n\n除 `platform` 为脚本路由参数外，其余字段会作为 JSON Body 发送到对应平台搜索接口。\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `platform` | string | 必填：`tiktok` / `youtube` / `instagram` |\n| `keyword` | string | 搜索关键词 |\n| `country_code` | string | 国家代码，多选逗号分隔 |\n| `gender` | string | `\"0\"`=女性，`\"1\"`=男性 |\n| `has_email` | boolean | 是否有邮箱 |\n| `language_code` | string | 达人内容语言代码，多选逗号分隔 |\n| `followers_cnt_gte` / `followers_cnt_lte` | integer | 粉丝数/订阅数范围 |\n| `industry` | string | 行业类目；脚本支持类目 ID、中文/英文名称和常用别名 |\n| `audience_country_code_list` | string | 受众国家代码，多选逗号分隔 |\n| `audience_age_list` | string | 受众年龄，多选逗号分隔 |\n| `audience_female_rate_gte` / `audience_female_rate_lte` | number | 受众女性比例，传 0~100 百分比数值 |\n| `page` | integer | 页码，默认 1 |\n| `size` | integer | 每页数量，默认 50；普通 Open API 调用最大 100 |\n| `sort_field` | string | 排序字段，必须使用目标平台支持的字段 |\n| `sort_order` | string | `asc` / `desc`，默认 `desc` |\n| `service_level` | string | `S1` / `S2` / `S3`，默认 `S2` |\n| `lang` | string | 响应显示语言：`cn` / `en`，默认 `en`，不参与筛选 |\n\n## TikTok 参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `has_mcn` / `has_line` / `has_zalo` | boolean | 是否绑定 MCN / 有 Line / 有 Zalo |\n| `last10_avg_video_views_cnt_gte` / `_lte` | number | 近 10 条视频平均播放量范围 |\n| `last10_avg_video_interaction_rate_gte` / `_lte` | number | 近 10 条视频平均互动率范围，传 0~100 |\n| `last_video_publish_date_gte` / `_lte` | string | 最近视频发布日期范围，`YYYY-MM-DD` |\n| `product_category_id_array` | string | 带货类目 ID，多选逗号分隔 |\n| `audience_language_code_list` | string | 受众语言代码，多选逗号分隔 |\n| `last30day_gmv_gte` / `_lte` | number | 近 30 天 GMV 范围 |\n| `last30day_gpm_gte` / `_lte` | number | 近 30 天 GPM 范围 |\n| `last30day_gmv_per_buyer_gte` / `_lte` | number | 近 30 天客单价范围 |\n| `last30day_commission_rate_gte` / `_lte` | number | 近 30 天佣金率范围，传 0~100 |\n\nTikTok `sort_field`：`followers_cnt` / `last10_avg_video_views_cnt` / `last10_avg_video_interaction_rate`。\n\n## YouTube 参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `has_whatsapp` / `is_ai_creator` | boolean | 是否有 WhatsApp / 是否 AI 达人 |\n| `last10_avg_video_view_count_all_gte` / `_lte` | number | 近 10 条全部视频平均播放量范围 |\n| `last10_avg_video_view_count_short_gte` / `_lte` | number | 近 10 条短视频平均播放量范围 |\n| `last10_avg_interaction_rate_all_gte` / `_lte` | number | 近 10 条全部视频平均互动率范围，传 0~100 |\n| `last10_avg_interaction_rate_short_gte` / `_lte` | number | 近 10 条短视频平均互动率范围，传 0~100 |\n| `last_video_publish_date_gte` / `_lte` | string | 最近视频发布日期范围，`YYYY-MM-DD` |\n| `audience_language_code_list` | string | 受众语言代码，多选逗号分隔 |\n\nYouTube 不要使用旧字段名 `last10_avg_video_views_cnt_*`、`last10_avg_video_views_cnt_short_*`、`last10_avg_video_interaction_rate_*`、`last10_avg_video_interaction_rate_short_*`。\n\n## Instagram 参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `has_whatsapp` / `is_product_kol` / `is_ai_creator` | boolean | 是否有 WhatsApp / 带货达人 / AI 达人 |\n| `last10_avg_video_view_count_gte` / `_lte` | number | 近 10 条视频平均播放量范围 |\n| `last10_avg_video_interaction_rate_gte` / `_lte` | number | 近 10 条视频平均互动率范围，传 0~100 |\n| `last_video_publish_time_gte` / `_lte` | string | 最近视频发布日期范围，`YYYY-MM-DD` |\n| `female_ratio_gte` / `_lte` | number | 受众女性占比范围，传 0~100（Instagram 专用，替代通用 `audience_female_rate_*`） |\n| `audience_language_list` | string | 受众语言，多选逗号分隔 |\n\nInstagram 不要使用旧字段名 `last10_avg_video_views_cnt_*`、`last_video_publish_date_*`、`audience_female_rate_*`、`is_top_creator`。\n\n## Category Input（industry 参数说明）\n\n`industry` 参数在 HTTP Open API 中要求传 level-3 数字类目 ID。通过本 skill 的脚本调用时，脚本支持以下输入并自动转换为 level-3 类目 ID：\n\n- **三级类目 ID**：`5001001,25009001,24001001`（真实 ID 可能为 7 位或 8 位）\n- **一级类目 ID**：`5,25`（真实 ID 可能为 1 位或 2 位，自动展开为所有三级子类目）\n- **中文类目名**：`美妆,科技数码`\n- **英文类目名**：`Skincare,Mobile Phones`\n- **常用英文别名**：`Fashion`, `Beauty`, `Sports`, `Tech`, `Food`, `Gaming`, `Travel`\n- **混合输入**：`Fashion,Beauty`（逐项解析）\n\n脚本会校验每个行业值是否存在于完整行业树中。只要有一项无法识别，搜索会在发送 HTTP 请求前失败，不会发送名称、未知数字 ID 或部分转换结果。\n\n## 示例\n\n```json\n{\"platform\":\"tiktok\",\"country_code\":\"US\",\"gender\":\"0\",\"has_email\":true,\"followers_cnt_gte\":100000,\"last10_avg_video_interaction_rate_gte\":3,\"service_level\":\"S2\"}\n```\n\n```json\n{\"platform\":\"youtube\",\"country_code\":\"US\",\"last10_avg_video_view_count_short_gte\":50000,\"audience_female_rate_gte\":70,\"service_level\":\"S3\"}\n```\n\n```json\n{\"platform\":\"instagram\",\"industry\":\"Beauty\",\"is_product_kol\":true,\"audience_language_list\":\"en\",\"service_level\":\"S2\"}\n```\n\n## 输出格式\n\n### TikTok\n\n```\n| # | 用户名 | 昵称 | 粉丝数 | 获赞数 | 平均播放 | 互动率 | 国家 | 主页链接 |\n```\n\n### YouTube\n\n```\n| # | 用户名 | 频道名 | 订阅数 | 总观看 | 平均播放 | 互动率 | 国家 | 频道链接 |\n```\n\n### Fuzzy Industry Guidance\n\n- High confidence terms can be searched directly. Examples: `skincare`, `skin care`, `funny`, `home cleaning`, `pet supplies`, `kids toys`, `phone accessories`.\n- If the user gives a broad business phrase, map it to the closest supported category and briefly state the interpretation before searching. Example: \"cleaning creators\" -> `Home Cleaning`; \"funny creators\" -> `Comedy & Humor`.\n- If the phrase is ambiguous, do not silently guess. Show 2-3 likely categories and ask the user to confirm. Examples: \"toy\" may mean `Children's Toys`, `Pet Toys`, `Model Toys`, or `Adult Art Toys`; \"home\" may mean `Home Cleaning`, `Home Decoration`, `Home Appliances`, or `Kitchen & Tableware`.\n- When the script returns `suggestions`, present those category names to the user and ask which one to use instead of sending a request with an unknown industry value.\n\n### Instagram\n\n```\n| # | 用户名 | 昵称 | 粉丝数 | 帖子数 | 平均播放 | 互动率 | 国家 | 主页链接 |\n```\n\n### 通用格式规则\n\n- 仅展示实际返回的字段，不能假设低服务等级包含 S2/S3 字段\n- 表格内链接用 `[查看][linkN]` 引用式，表格下方定义完整 URL\n- 统计信息单独列出：总匹配数、服务等级、消耗积分、剩余配额、请求 ID\n- `meta.total` 为 null 时不展示总匹配数\n- 默认展示 5~10 条，超过时询问用户\n- 展示后主动询问是否需要导出 CSV/Excel\n\nFile v1.8.0:outreach/creator-outreach/SKILL.md\n\n---\r\nname: creator-outreach\r\ndescription: |\r\n  邮件建联全流程能力，覆盖发送、任务查询、沟通历史、待办跟进、效果指标、渠道配置、附件上传。平台代发机制，无需用户提供 SMTP 配置。\r\n  Use when: 建联, 发邮件, 批量发送, email outreach, send email, outreach\r\ncompatibility: Node.js 20.6+\r\nmetadata:\r\n  layer: outreach\r\n  parent: creator-scraper-cv\r\n---\r\n\r\n# Creator Outreach — 邮件建联\r\n\r\n## 概述\r\n\r\n邮件建联全流程能力：搜索达人后一键发送邮件，支持单发/批量发送、任务轮询、沟通历史查询、待办跟进、效果指标分析，平台统一代发无需用户配置。\r\n\r\n## 脚本引用\r\n\r\n| 脚本路径 | 状态 | 说明 |\r\n|----------|------|------|\r\n| `../../scripts/outreach_send.mjs` | ✅ 已实现 | 发送邮件（单发/批量） |\r\n| `../../scripts/outreach_task.mjs` | ✅ 已实现 | 查询发送任务状态与结果 |\r\n| `../../scripts/outreach_contact.mjs` | ✅ 已实现 | 查询联系人沟通历史 |\r\n| `../../scripts/outreach_todo.mjs` | ✅ 已实现 | 待办跟进（超时/未读） |\r\n| `../../scripts/outreach_metrics.mjs` | 🔮 待实现 | 效果指标（发送量/打开率/回复率） |\r\n| `../../scripts/outreach_config.mjs` | 🔮 待实现 | 渠道与模板配置查询 |\r\n| `../../scripts/outreach_upload.mjs` | 🔮 待实现 | 附件上传（max 10MB） |\r\n\r\n> 🔮 标注的脚本尚未部署，调用将返回错误。待后端实现后可直接启用。\r\n\r\n## 架构原则\r\n\r\n**Skill = 纯 HTTP 客户端，不做任何本地业务逻辑处理。**\r\n\r\n- 脚本只负责组装 JSON 参数并调用 OpenAPI 接口\r\n- 所有业务逻辑（创建提报、查找会话、判断新建/回复）由 OpenAPI 内部完成\r\n- Skill 不需要知道 `submission_id`、`influencer_id` 等内部概念\r\n- 搜索后发送时，将搜索结果中的 `uid` + `platform` 传给 outreach_send，OpenAPI 内部自动从 Holo 查完整达人数据\r\n\r\n## 发送机制\r\n\r\n**邮件由 Creativault 平台后端统一代发（AWS SES），用户无需提供任何发信配置。**\r\n\r\n- **[禁止]** 向用户索要 SMTP 配置、邮箱密码、授权码、发信服务器地址\r\n- **[禁止]** 建议用户\"用自己的邮箱手动发送\"——平台已具备发送能力\r\n- `channel` 参数当前仅 `ses` 生效（默认值）；`gmail`/`outlook` 为预留字段，后端未实现\r\n- 若用户问\"邮件怎么发出去的\" → 回答：\"由 Creativault 平台统一代发，无需配置任何邮箱或 SMTP。\"\r\n\r\n## 参数说明\r\n\r\n### outreach_send.mjs\r\n\r\n`to` 和 `recipients` 互斥，传其一。\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `to` | string | 收件人邮箱（单发） |\r\n| `uid` | string | 达人平台 UID（单发必填，来自搜索结果的 uid 字段） |\r\n| `nickname` | string | 达人昵称（可选，用于会话展示） |\r\n| `platform` | string | 达人平台：tiktok/youtube/instagram |\r\n| `recipients` | object[] | 批量发送：`{email, uid, nickname, platform}` 数组 |\r\n| `subject` | string | 邮件主题 |\r\n| `body_html` | string | HTML 正文（支持 `{{creator_name}}` 变量） |\r\n| `body_text` | string | 纯文本正文 |\r\n| `channel` | string | `ses`（默认，唯一生效渠道） |\r\n| `template_id` | integer | 模板 ID（覆盖 subject/body） |\r\n| `send_mode` | string | `immediate`（默认）/ `smart`（时区优化） |\r\n| `force_new` | boolean | 强制新建会话（默认 false） |\r\n| `attachment_ids` | string[] | 附件 ID 列表 |\r\n\r\n### outreach_task.mjs\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `task_id` | string | **必填**。发送返回的任务 ID |\r\n| `include_result` | boolean | 附带逐收件人结果（默认 false） |\r\n| `result_filter` | string | 结果过滤：`all`/`sent`/`failed` |\r\n| `poll` | boolean | 自动轮询至终态（默认 false） |\r\n| `poll_interval` | integer | 轮询间隔秒数（默认 5） |\r\n| `poll_max_attempts` | integer | 最大轮询次数（默认 60） |\r\n\r\n### outreach_contact.mjs\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `email` | string | **必填**。达人邮箱 |\r\n| `include_history` | boolean | 包含消息历史（默认 true） |\r\n| `include_summary` | boolean | 包含 AI 摘要（默认 true） |\r\n\r\n### outreach_todo.mjs\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `overdue_hours` | integer | 超时阈值小时数（默认 24） |\r\n| `include_unread` | boolean | 包含未读会话（默认 true） |\r\n| `include_overdue` | boolean | 包含超时会话（默认 true） |\r\n\r\n## 安全规则\r\n\r\n**邮件发送是高风险操作，每次发送前必须获得用户明确确认。**\r\n\r\n**[禁止]** 用户说\"帮我发邮件\"后直接执行发送脚本。\r\n\r\n**[必须]** 在执行 `outreach_send.mjs` 之前，展示收件人列表并等待用户确认：\r\n\r\n1. **单笔发送**：展示收件人邮箱、主题、正文预览\r\n2. **批量发送**：展示收件人数量（≤5 全部展示，>5 展示前 5 个 + \"...及其他 N 个\"）、主题、正文预览\r\n3. 用户说\"确认\"/\"发送\"/\"是\"/\"Y\" → 执行发送\r\n4. 用户说\"取消\"/\"不发\"/\"修改\" → 不执行，询问修改意见\r\n5. 回复已有会话也需要确认\r\n6. 唯一例外：用户明确说\"直接发送不用确认\"时可跳过\r\n\r\n## 输出格式\r\n\r\n### 发送确认格式\r\n\r\n```\r\n📧 发送确认\r\n\r\n• 收件人：{email 或 N 个收件人列表}\r\n• 主题：{subject}\r\n• 渠道：{channel}\r\n• 模式：{send_mode}\r\n• 正文预览：{前 100 字符...}\r\n\r\n确认发送吗？(Y/N)\r\n```\r\n\r\n### 任务状态格式\r\n\r\n```\r\n📬 发送结果\r\n\r\n• 任务ID：{task_id}\r\n• 状态：{completed/partial/failed}\r\n• 成功：{sent_count} 封\r\n• 失败：{failed_count} 封\r\n• 耗时：{duration}\r\n• 消耗积分：{credits_consumed}\r\n```\r\n\r\n### 积分说明\r\n\r\n| 操作 | 积分消耗 |\r\n|------|----------|\r\n| 发送邮件（每封） | 1 |\r\n| 所有查询接口 | 0（免费） |\r\n\r\n### 决策规则\r\n\r\n- \"发邮件\"/\"建联\"/\"reach out\" → `outreach_send.mjs`\r\n- 搜索结果列表 → `outreach_send.mjs` + `recipients`\r\n- 发送后 → `outreach_task.mjs` + `poll:true` 确认投递\r\n- \"待办\"/\"follow-up\" → `outreach_todo.mjs`\r\n- \"沟通历史\"/\"what did I discuss\" → `outreach_contact.mjs`\r\n- \"效果\"/\"metrics\" → `outreach_metrics.mjs`（🔮 待实现）\r\n- \"渠道\"/\"模板\" → `outreach_config.mjs`（🔮 待实现）\r\n- 模板变量：`{{creator_name}}`、`{{creator_email}}`、`{{platform}}`\r\n- 搜索后发送时，**必须**传 `uid` + `platform`（OpenAPI 自动从 Holo 查完整达人数据）\n\nFile v1.8.0:SKILL.md\n\n---\r\nname: creator-scraper-cv\r\ndescription: |\r\n  Creativault creator data collection and outreach skill. Search and collect creator/influencer\r\n  data from TikTok, YouTube, Instagram, and Twitter. Send outreach emails to discovered creators with\r\n  automatic conversation management, batch sending, and follow-up tracking.\r\n  Supports multi-dimensional search, similar/lookalike creator discovery, batch collection by\r\n  links/usernames/keywords, task tracking, data export (xlsx/csv/html), and email outreach\r\n  (single/batch send, templates, smart timing, metrics).\r\n  Use when: creator search, influencer scraping, KOL search, KOL analytics,\r\n  social media data extraction, TikTok scraper, YouTube scraper, Instagram scraper, Twitter scraper,\r\n  influencer discovery, similar creators, lookalike, outreach, email outreach,\r\n  send email to creator, batch email, follow-up, 达人采集, KOL 搜索, 网红数据,\r\n  达人分析, 达人搜索, 相似达人, 社交媒体数据, 建联, 发邮件, 批量发送.\r\ncompatibility: Node.js 20.6+\r\nmetadata:\r\n  author: creativault\r\n  version: \"1.8.0\"\r\n---\r\n\r\n# Creativault Creator Ecosystem\r\n\r\n## 生态总览\r\n\r\n| 领域 | 子 Skill | 能力描述 |\r\n|------|----------|----------|\r\n| discovery | creator-search | 三平台达人多维度实时搜索 |\r\n| discovery | creator-lookalike | 种子达人相似匹配与跨平台发现 |\r\n| collection | creator-collection | 批量异步采集与多格式导出 |\r\n| outreach | creator-outreach | 邮件建联全流程（代发、跟进、待办） |\r\n| workflow | workflow | 剧本式工作流编排与 AI 自主调度 |\r\n\r\n## 路由索引\r\n\r\n| 子 Skill | 中文关键词 | 英文关键词 | 路径 |\r\n|----------|-----------|-----------|------|\r\n| creator-search | 达人搜索, KOL搜索, 找达人 | creator search, influencer discovery, search creators | discovery/creator-search/SKILL.md |\r\n| creator-lookalike | 相似达人, 类似达人 | similar creators, lookalike, find similar | discovery/creator-lookalike/SKILL.md |\r\n| creator-collection | 批量采集, 数据导出, 离线采集 | batch collection, data export, keyword collection | collection/creator-collection/SKILL.md |\r\n| creator-outreach | 建联, 发邮件, 批量发送 | email outreach, send email, outreach | outreach/creator-outreach/SKILL.md |\r\n| workflow | 工作流, 流程编排, 批量建联流程 | workflow orchestration, campaign flow, batch outreach flow | workflow/SKILL.md |\r\n\r\n**路由规则**：AI Agent 根据用户意图匹配上表关键词，加载对应子 skill。无法匹配时展示本表供用户选择。\r\n\r\n## Prerequisites\r\n\r\nOptional update variables:\r\n\r\n- `CV_SKILL_UPDATE_MANIFEST_URL` - Remote manifest URL for skill update checks.\r\n- `CV_SKILL_AUTO_UPDATE=true` - Allow automatic update when the API reports this skill is outdated.\r\n\r\nManual check:\r\n\r\n```bash\r\nnode scripts/skill_update.mjs --check\r\n```\r\n\r\nConfirmed update:\r\n\r\n```bash\r\nnode scripts/skill_update.mjs --yes\r\n```\r\n\r\nGenerate release manifest:\r\n\r\n```bash\r\nnode scripts/generate_manifest.mjs --note \"Describe this release\"\r\n```\r\n\r\nSet the following environment variables:\r\n\r\n- `CV_API_KEY` — Creativault Open API Key (obtain from admin dashboard)\r\n- `CV_USER_IDENTITY` — Operator email address\r\n- `CV_API_BASE_URL` (optional) — API base URL, defaults to `http://api.creativault.vip`\r\n\r\n**Linux / macOS**:\r\n\r\n```bash\r\nexport CV_API_KEY=cv_live_your_key_here\r\nexport CV_USER_IDENTITY=your_email@example.com\r\n```\r\n\r\n**Windows PowerShell**:\r\n\r\n```powershell\r\n$env:CV_API_KEY = \"cv_live_your_key_here\"\r\n$env:CV_USER_IDENTITY = \"your_email@example.com\"\r\n```\r\n\r\n## Error Handling\r\n\r\n| Code | Description | Action |\r\n|------|-------------|--------|\r\n| 40001 | Invalid parameters | Check parameter format |\r\n| 40101 | Invalid API Key | Check CV_API_KEY |\r\n| 40102 | API Key expired | Contact admin |\r\n| 40201 | Insufficient credits | Top up or upgrade |\r\n| 40301 | No permission | Check API Key scopes |\r\n| 42901 | Rate limit exceeded | Auto-retry after Retry-After |\r\n| 42902 | Daily quota exhausted | Wait until UTC 00:00 |\r\n| 50001 | Server error | Report request_id to support |\r\n\r\n## 积分余额判断规则\r\n\r\n**只有 OpenAPI 明确返回错误码 `40201` 时，才能提示用户“积分不足”。**\r\n\r\n- `meta.quota_remaining` 表示当天剩余 API 请求次数，不是积分余额。即使该值为 `0`、`8` 或其他较小数字，也禁止解释为“剩余积分”或提示充值。\r\n- `meta.credits_remaining` 才表示真实 OpenAPI 积分余额；字段缺失或值为 `-1` 时，不要自行估算余额。\r\n- `meta.credits_consumed` 只表示本次请求消耗的积分。\r\n- 请求成功时，不要因为任何 quota 数值主动发布“积分余额不足提醒”。\r\n- 只有收到 `40201` 后，才停止后续付费调用并提示用户充值或调整任务规模。\r\n\r\n## 版本更新提示规则\r\n\r\n当 API 响应 `meta` 中 `skill_update_available: true` 时，需要提示用户更新：\r\n\r\n> ⚠️ **Skill 有新版本可用**\r\n> 当前版本：{skill_current_version} → 最新版本：{skill_latest_version}\r\n> 更新命令：`node scripts/skill_update.mjs --yes`\r\n> 新版本可能包含字段修正、行业映射优化或新平台支持，建议尽快更新。\r\n\r\n规则：\r\n- `skill_update_available: true` 且 `skill_update_required: false` → 建议更新（非强制），展示提示但不阻断操作\r\n- `skill_update_required: true` → 强制更新提示，告知用户当前版本低于最低支持版本，继续使用可能导致参数不兼容或结果异常\r\n- `skill_update_available: false` → 不提示，已是最新\r\n- 所有 `skill_*` 字段为 null → 不提示（Postman 等非 skill 客户端调用）\r\n\r\n## References\r\n\r\n- [API Reference](references/api-reference.md)\r\n- [Platform Parameters](references/platform-params.md)\r\n- [Industry Categories](references/industry-categories.md)\r\n- [Country Codes](references/country-codes.md)\r\n- [Language Codes](references/language-codes.md)\r\n- [Error Codes](references/error-codes.md)\n\nFile v1.8.0:workflow/SKILL.md\n\n---\r\nname: workflow\r\ndescription: |\r\n  工作流编排层，通过剧本式步骤描述实现 AI 自主调度底层子 skill 能力。支持批量建联、战役闭环等复合流程编排。\r\n  Use when: 工作流, 流程编排, 批量建联流程, workflow orchestration, campaign flow, batch outreach flow\r\ncompatibility: Node.js 20.6+\r\nmetadata:\r\n  layer: workflow\r\n  parent: creator-scraper-cv\r\n---\r\n\r\n# Workflow Orchestration（工作流编排）\r\n\r\n## 概述\r\n\r\n工作流编排层，将底层子 skill 的原子能力组合为端到端的复合流程，通过剧本式步骤描述实现 AI 自主调度。\r\n\r\n## 脚本引用\r\n\r\n本层不直接引用脚本。工作流编排通过调度子 skill 间接使用底层脚本能力：\r\n\r\n| 层级 | 说明 |\r\n|------|------|\r\n| workflow 层 | 定义步骤序列与数据流转，不持有脚本 |\r\n| 子 skill 层 | 每个步骤调用对应子 skill，由子 skill 持有并执行脚本 |\r\n\r\n路径示例：`workflow 步骤 → discovery/creator-search → ../../scripts/search_creators.mjs`\r\n\r\n## 参数说明\r\n\r\n本层不直接调用脚本参数，通过编排子 skill 间接使用。各步骤的具体参数由对应子 skill 定义，工作流层仅负责步骤编排与数据流转。\r\n\r\n## 编排层定位\r\n\r\n### 设计理念\r\n\r\n1. **剧本式编排**：每个工作流是一个 Markdown 剧本文件（位于 `workflows/` 目录），定义步骤序列、数据流转和决策点。AI Agent 按剧本逐步执行，无需额外编程。\r\n\r\n2. **AI 自主调度**：AI Agent 读取剧本后，按步骤顺序调用对应子 skill 的能力。每步的产出自动作为下一步的输入，形成数据管道。\r\n\r\n3. **用户确认点**：关键决策步骤（如发送邮件、批量操作）标注 `[需用户确认]`，AI 暂停执行并展示当前数据，等待用户明确授权后继续。\r\n\r\n### 适用场景\r\n\r\n- 用户提出跨领域的复合需求（如\"找达人并发建联邮件\"）\r\n- 需要多步骤协作且有明确先后顺序的流程\r\n- 需要在关键节点获取用户决策的半自动化流程\r\n\r\n## 工作流索引\r\n\r\n| 剧本文件 | 描述 | 步骤数 |\r\n|---------|------|--------|\r\n| `workflows/batch-outreach.md` | 批量建联流程：从搜索到发送到跟进的 6 步闭环 | 6 |\r\n| `workflows/full-campaign.md` | 战役闭环流程：从发现到复盘的 ≥8 步完整链路 | ≥8 |\r\n\r\n## 调度规则\r\n\r\nAI Agent 执行工作流剧本时，遵循以下规则：\r\n\r\n### 执行规则\r\n\r\n1. **顺序执行**：按步骤编号顺序执行，每步调用标注的子 skill（格式 `[领域/子skill名]`）\r\n2. **数据传递**：步骤间数据通过上下文传递——上一步产出 = 下一步输入\r\n3. **错误中断**：任一步骤执行失败时，暂停流程并向用户报告错误原因及当前进度\r\n\r\n### 特殊标注处理\r\n\r\n| 标注 | AI 行为 |\r\n|------|---------|\r\n| `[需用户确认]` | 暂停执行，展示当前数据摘要，等待用户明确确认后继续 |\r\n| `🔮 待补` | 跳过该步骤，告知用户该能力尚未实现及预期归属领域 |\r\n| `[AI 辅助]` | AI 自主完成该步骤，无需调用子 skill 脚本 |\r\n\r\n### 上下文管理\r\n\r\n- 每步执行前，AI 汇总前序步骤的关键产出作为当前步骤输入\r\n- 用户确认步骤中，AI 展示结构化数据摘要（数量、关键字段预览）\r\n- 流程结束后，AI 输出完整执行报告\r\n\r\n## 输出格式\r\n\r\n工作流执行过程中，AI 按以下格式报告进度：\r\n\r\n```\r\n📋 工作流：{剧本名称}\r\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━\r\n✅ Step 1: {步骤描述} — 完成（产出: {摘要}）\r\n✅ Step 2: {步骤描述} — 完成（产出: {摘要}）\r\n⏳ Step 3: {步骤描述} — 执行中...\r\n⬚ Step 4: {步骤描述} — 待执行\r\n⬚ Step 5: {步骤描述} — 待执行\r\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━\r\n进度: 2/5 完成 | 当前: Step 3\r\n```\r\n\r\n流程完成后输出执行摘要：\r\n\r\n```\r\n✅ 工作流执行完成：{剧本名称}\r\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━\r\n总步骤: {N} | 成功: {N} | 跳过: {N}\r\n关键产出:\r\n  - {产出 1 摘要}\r\n  - {产出 2 摘要}\r\n```\n\nFile v1.8.0:_meta.json\n\n{\n  \"ownerId\": \"kn7dvhveaa0kchtkpq8xzbbq998585wp\",\n  \"slug\": \"cv-creator-scraper\",\n  \"version\": \"1.8.0\",\n  \"publishedAt\": 1781058906042\n}\n\nFile v1.8.0:references/api-reference.md\n\n# API Reference\r\n\r\n## Protocol\r\n\r\n| Item | Description |\r\n|------|-------------|\r\n| Base URL | `https://{host}/openapi/v1/` |\r\n| Protocol | HTTPS |\r\n| Method | All endpoints use **POST** |\r\n| Format | JSON (`Content-Type: application/json`) |\r\n| Auth | `X-API-Key` + `X-User-Identity` headers |\r\n| Encoding | UTF-8 |\r\n| Timestamps | ISO 8601 (e.g., `2026-03-15T10:30:00Z`) |\r\n| Pagination | `page` (starts at 1), `size` (default 50) |\r\n\r\n## Response Structure\r\n\r\n```json\r\n{\r\n  \"success\": true,\r\n  \"data\": { ... },\r\n  \"error\": null,\r\n  \"meta\": {\r\n    \"request_id\": \"req_abc123\",\r\n    \"page\": 1,\r\n    \"size\": 50,\n    \"total\": 1200,\n    \"quota_remaining\": -1,\n    \"credits_consumed\": 150,\n    \"credits_remaining\": 131500\n  }\n}\n```\n\n`meta.quota_remaining`: remaining daily API request quota. It is **not** a credits balance. `-1` means unlimited.\n`meta.service_level`: service level used for this search request (`S1`/`S2`/`S3`). Only present in search responses. Default is `S2`.\n`meta.credits_consumed`: credits deducted for this request. `0` means no charge.\n`meta.credits_remaining`: actual OpenAPI credits balance. `-1` means unlimited. This field may be absent from non-billed endpoints.\n`meta.total`: total matching records. For search endpoints, only returned when filter conditions > 2 (excluding `page`, `size`, `sort_field`, `sort_order`, `service_level`). Returns `null` when ≤ 2 filters.\n`meta.lang`: response translation language (`cn`/`en`). `null` when `lang` param not provided.\n\nNever report insufficient credits from `quota_remaining`. Only error code `40201` confirms insufficient credits.\n\r\n## Endpoints\r\n\r\n| Endpoint | Path | Description |\r\n|----------|------|-------------|\r\n| Search TikTok creators | `/openapi/v1/creators/tiktok/search` | Multi-dimensional filtering, supports `service_level` (S1/S2/S3) |\r\n| Search YouTube creators | `/openapi/v1/creators/youtube/search` | Multi-dimensional filtering, supports `service_level` (S1/S2/S3) |\r\n| Search Instagram creators | `/openapi/v1/creators/instagram/search` | Multi-dimensional filtering, supports `service_level` (S1/S2/S3) |\r\n| Submit collection task | `/openapi/v1/collection/tasks/submit` | Batch collect by links/usernames |\r\n| Submit keyword collection | `/openapi/v1/collection/tasks/keyword-submit` | Collect by keywords |\r\n| Query task status | `/openapi/v1/collection/tasks/status` | Check collection progress |\r\n| Get task data | `/openapi/v1/collection/tasks/data` | Paginated results |\r\n| Export task data | `/openapi/v1/collection/tasks/export` | Export to xlsx/csv/html file |\r\n| Get file download URL | `/openapi/v1/files/download-url` | Get temporary download URL |\r\n| Find similar creators | `/openapi/v1/creators/lookalike` | Lookalike search by username/URL, auto-resolves platform ID |\r\n\r\n## Task Types\r\n\r\n| task_type | Description | values content | Max items |\r\n|-----------|-------------|---------------|-----------|\r\n| `LINK_BATCH` | Link collection | Creator profile URLs | 500 |\r\n| `FILE_UPLOAD` | Username collection | Creator usernames | 500 |\r\n\r\n## Task Status\r\n\r\n| status | Description |\r\n|--------|-------------|\r\n| `processing` | In progress (collecting or importing data) |\r\n| `completed` | Completed |\r\n| `failed` | Failed |\r\n| `timeout` | Timed out |\r\n\r\n## Supported Platforms\r\n\r\n| Platform | ID | Search | Link Collection | Username Collection | Keyword Collection |\r\n|----------|----|--------|----------------|--------------------|--------------------|\r\n| TikTok | `tiktok` | ✅ | ✅ | ✅ | ✅ |\r\n| YouTube | `youtube` | ✅ | ✅ | ✅ | ✅ |\r\n| Instagram | `instagram` | ✅ | ✅ | ✅ | ✅ |\r\n\r\n## Search Response Fields by Service Level\r\n\r\n### TikTok\r\n\r\n| Field | Type | Level | Description |\r\n|-------|------|-------|-------------|\r\n| `uid` | string | S1 | Creator unique ID |\r\n| `username` | string | S1 | Username |\r\n| `nickname` | string | S1 | Nickname |\r\n| `avatar_url` | string | S1 | Avatar URL |\r\n| `profile_url` | string | S1 | Profile URL |\r\n| `followers_count` | integer | S1 | Followers count |\r\n| `likes_count` | integer | S1 | Likes count |\r\n| `video_count` | integer | S1 | Total videos |\r\n| `has_showcase` | boolean | S1 | Has showcase/store |\r\n| `has_email` | boolean | S1 | Has email |\r\n| `has_mcn` | boolean | S1 | Has MCN |\r\n| `has_line` | boolean | S1 | Has Line |\r\n| `has_zalo` | boolean | S1 | Has Zalo |\r\n| `last_video_publish_date` | string | S1 | Last video publish date (YYYY-MM-DD) |\r\n| `country_code` | string | S2 | Country/region code |\r\n| `gender` | string | S2 | Gender (translated when `lang` is set) |\r\n| `avg_views` | integer | S2 | Avg views of last 10 videos |\r\n| `engagement_rate` | number | S2 | Avg interaction rate of last 10 videos |\r\n| `views_per_follower` | number | S2 | Views per follower ratio |\r\n| `is_verified` | boolean | S2 | Whether verified |\r\n| `last10_video_views_per_sub` | number | S2 | Last 10 video views per subscriber |\r\n| `last10_med_video_views_cnt` | integer | S2 | Last 10 video views median |\r\n| `last10_med_video_views_per_sub` | number | S2 | Last 10 video views median per subscriber |\r\n| `product_categories` | string[] | S2 | Product categories |\r\n| `industry_categories` | array | S2 | Industry categories (primary/secondary/tertiary) |\r\n| `bio` | string | S2 | Bio / profile description |\r\n| `hashtags` | string[] | S2 | Hashtag list |\r\n| `language` | string | S2 | Language |\r\n| `email` | string | S2 | Email address |\r\n| `link_whatsapp` | string | S2 | WhatsApp link |\r\n| `link_line` | string | S2 | Line link |\r\n| `link_zalo` | string | S2 | Zalo link |\r\n| `mcn` | string | S2 | MCN agency |\r\n| `audience_female_rate` | number | S3 | Female audience ratio (percentage, e.g. 78.65 = 78.65%) |\r\n| `audience_country_code_list` | string[] | S3 | Audience country distribution |\r\n| `audience_language_code_list` | string[] | S3 | Audience language distribution |\r\n| `audience_age_id_list` | string[] | S3 | Audience age distribution (translated when `lang` is set) |\r\n\r\n### YouTube\r\n\r\n| Field | Type | Level | Description |\r\n|-------|------|-------|-------------|\r\n| `uid` | string | S1 | Creator unique ID |\r\n| `username` | string | S1 | Username |\r\n| `nickname` | string | S1 | Channel name |\r\n| `avatar_url` | string | S1 | Avatar URL |\r\n| `channel_url` | string | S1 | Channel URL |\r\n| `has_email` | boolean | S1 | Has email |\r\n| `has_whatsapp` | boolean | S1 | Has WhatsApp |\r\n| `last_video_publish_time` | string | S1 | Last video publish time (ISO 8601) |\r\n| `country_code` | string | S2 | Country/region code |\r\n| `language` | string | S2 | Language |\r\n| `gender` | string | S2 | Gender |\r\n| `bio` | string | S2 | Channel bio / description |\r\n| `followers_count` | integer | S2 | Subscribers count |\r\n| `video_count` | integer | S2 | Video count |\r\n| `view_count` | integer | S2 | Total views |\r\n| `avg_views` | integer | S2 | Avg views of last 10 videos (all) |\r\n| `avg_views_short` | integer | S2 | Avg views of last 10 short videos |\r\n| `avg_views_long` | integer | S2 | Avg views of last 10 long videos |\r\n| `engagement_rate` | number | S2 | Interaction rate of last 10 videos (all) |\r\n| `engagement_rate_short` | number | S2 | Interaction rate of last 10 short videos |\r\n| `engagement_rate_long` | number | S2 | Interaction rate of last 10 long videos |\r\n| `is_verified` | boolean | S2 | Whether verified |\r\n| `last10_video_views_per_sub` | number | S2 | Last 10 video views per subscriber (all) |\r\n| `last10_video_views_per_sub_short` | number | S2 | Last 10 short video views per subscriber |\r\n| `last10_video_views_per_sub_long` | number | S2 | Last 10 long video views per subscriber |\r\n| `last10_med_video_views_cnt` | integer | S2 | Last 10 video views median (all) |\r\n| `last10_med_video_views_cnt_short` | integer | S2 | Last 10 short video views median |\r\n| `last10_med_video_views_cnt_long` | integer | S2 | Last 10 long video views median |\r\n| `last10_med_video_views_per_sub` | number | S2 | Last 10 video views median per subscriber (all) |\r\n| `last10_med_video_views_per_sub_short` | number | S2 | Last 10 short video views median per subscriber |\r\n| `last10_med_video_views_per_sub_long` | number | S2 | Last 10 long video views median per subscriber |\r\n| `industry_categories` | array | S2 | Industry categories (primary/secondary/tertiary) |\r\n| `hashtags` | string[] | S2 | Hashtag list |\r\n| `email` | string | S2 | Email address |\r\n| `whatsapp` | string | S2 | WhatsApp |\r\n| `audience_female_rate` | number | S3 | Female audience ratio (percentage) |\r\n| `audience_country_code_list` | string[] | S3 | Audience country distribution |\r\n| `audience_language_list` | string[] | S3 | Audience language distribution |\r\n| `audience_age_list` | string[] | S3 | Audience age distribution (translated when `lang` is set) |\r\n\r\n### Instagram\r\n\r\n| Field | Type | Level | Description |\r\n|-------|------|-------|-------------|\r\n| `uid` | string | S1 | Creator unique ID |\r\n| `username` | string | S1 | Username |\r\n| `nickname` | string | S1 | Nickname |\r\n| `avatar_url` | string | S1 | Avatar URL |\r\n| `profile_url` | string | S1 | Profile URL |\r\n| `has_email` | boolean | S1 | Has email |\r\n| `has_whatsapp` | boolean | S1 | Has WhatsApp |\r\n| `last_video_publish_time` | string | S1 | Last post/video publish time |\r\n| `country_code` | string | S2 | Country/region code |\r\n| `language` | string | S2 | Language |\r\n| `gender` | string | S2 | Gender (translated when `lang` is set) |\r\n| `bio` | string | S2 | Bio / profile description |\r\n| `followers_count` | integer | S2 | Followers count |\r\n| `video_count` | integer | S2 | Posts/videos count |\r\n| `avg_views` | integer | S2 | Avg views of last 10 videos |\r\n| `engagement_rate` | number | S2 | Avg interaction rate of last 10 videos |\r\n| `is_verified` | boolean | S2 | Whether verified |\r\n| `last10_video_views_per_sub` | number | S2 | Last 10 video views per subscriber |\r\n| `last10_med_video_views_cnt` | integer | S2 | Last 10 video views median |\r\n| `last10_med_video_views_per_sub` | number | S2 | Last 10 video views median per subscriber |\r\n| `industry_categories` | array | S2 | Industry categories (primary/secondary/tertiary) |\r\n| `hashtags` | string[] | S2 | Hashtag list |\r\n| `email` | string | S2 | Email address |\r\n| `link_whatsapp` | string | S2 | WhatsApp |\r\n| `audience_female_rate` | number | S3 | Female audience ratio (percentage) |\r\n| `audience_country_code_list` | string[] | S3 | Audience country distribution |\r\n| `audience_language_code_list` | string[] | S3 | Audience language distribution |\r\n| `audience_age_id_list` | string[] | S3 | Audience age distribution (translated when `lang` is set) |\r\n\r\n### Lookalike\r\n\r\n| Field | Type | Description |\r\n|-------|------|-------------|\r\n| `uid` | string | Creator unique ID |\r\n| `username` | string / null | Username |\r\n| `nickname` | string / null | Nickname |\r\n| `avatar_url` | string / null | Avatar URL |\r\n| `profile_url` | string / null | Profile URL |\r\n| `country_code` | string / null | Country/region code |\r\n| `followers_count` | integer / null | Followers count |\r\n| `avg_views` | integer / null | Avg views of last 10 videos |\r\n| `engagement_rate` | number / null | Avg interaction rate of last 10 videos |\r\n| `match_score` | number / null | Similarity match score |\r\n\r\n## Export Formats\r\n\r\n| format | Description |\r\n|--------|-------------|\r\n| `xlsx` | Excel file with bold headers, background colors, auto column width |\r\n| `csv` | CSV file, UTF-8 BOM encoding (Excel compatible) |\r\n| `html` | HTML table page, viewable in browser |\r\n| `feishu_doc` | Feishu document (not yet available, returns 400) |\r\n\r\n## Export Response Fields\r\n\r\n| Field | Type | Description |\r\n|-------|------|-------------|\r\n| `file_id` | string | Unique file identifier (reusable via get_download_url) |\r\n| `file_name` | string | File name |\r\n| `file_url` | string | Authenticated temporary download URL |\r\n| `file_expire_at` | string | URL expiration time (ISO 8601 UTC) |\r\n| `format` | string | Export format |\r\n| `row_count` | integer | Number of data rows |\r\n\r\n## Webhook\r\n\r\nPass `webhook_url` when submitting collection tasks for completion notification.\r\n\r\nCallback payload:\r\n\r\n```json\r\n{\r\n  \"event\": \"collection.completed\",\r\n  \"task_id\": \"task_xxx\",\r\n  \"task_type\": \"LINK_BATCH\",\r\n  \"status\": \"completed\",\r\n  \"total\": 2,\r\n  \"completed\": 2,\r\n  \"failed\": 0,\r\n  \"timestamp\": \"2026-03-15T10:45:00Z\"\r\n}\r\n```\r\n\r\nSignature: `X-Webhook-Signature` header, HMAC-SHA256.\r\nRetry policy: max 3 attempts (10s → 30s → 90s).\n\nFile v1.8.0:references/country-codes.md\n\n# 国家代码映射表\r\n\r\n用户说中文国家名时，agent 需要转换为 ISO 3166-1 alpha-2 代码传给 API。\r\n\r\n## 常用国家（高频）\r\n\r\n| 代码 | 中文 | English |\r\n|------|------|---------|\r\n| US | 美国 | United States |\r\n| GB | 英国 | United Kingdom |\r\n| CA | 加拿大 | Canada |\r\n| AU | 澳大利亚 | Australia |\r\n| DE | 德国 | Germany |\r\n| FR | 法国 | France |\r\n| JP | 日本 | Japan |\r\n| KR | 韩国 | South Korea |\r\n| CN | 中国 | China |\r\n| HK | 香港 | Hong Kong |\r\n| TW | 台湾 | Taiwan |\r\n| SG | 新加坡 | Singapore |\r\n| MY | 马来西亚 | Malaysia |\r\n| TH | 泰国 | Thailand |\r\n| VN | 越南 | Vietnam |\r\n| ID | 印度尼西亚 | Indonesia |\r\n| PH | 菲律宾 | Philippines |\r\n| IN | 印度 | India |\r\n| BR | 巴西 | Brazil |\r\n| MX | 墨西哥 | Mexico |\r\n| SA | 沙特阿拉伯 | Saudi Arabia |\r\n| AE | 阿联酋 | United Arab Emirates |\r\n| RU | 俄罗斯 | Russia |\r\n| ES | 西班牙 | Spain |\r\n| IT | 意大利 | Italy |\r\n| NL | 荷兰 | Netherlands |\r\n| SE | 瑞典 | Sweden |\r\n| NO | 挪威 | Norway |\r\n| PL | 波兰 | Poland |\r\n| TR | 土耳其 | Turkey |\r\n| EG | 埃及 | Egypt |\r\n| NG | 尼日利亚 | Nigeria |\r\n| ZA | 南非 | South Africa |\r\n| KE | 肯尼亚 | Kenya |\r\n| AR | 阿根廷 | Argentina |\r\n| CO | 哥伦比亚 | Colombia |\r\n| CL | 智利 | Chile |\r\n| PE | 秘鲁 | Peru |\r\n| NZ | 新西兰 | New Zealand |\r\n| IE | 爱尔兰 | Ireland |\r\n| IL | 以色列 | Israel |\r\n| PK | 巴基斯坦 | Pakistan |\r\n| BD | 孟加拉 | Bangladesh |\r\n| KH | 柬埔寨 | Cambodia |\r\n| MM | 缅甸 | Myanmar |\r\n| LA | 老挝 | Laos |\r\n\r\n## 区域快捷映射\r\n\r\n用户说区域名称时，agent 应展开为对应的国家代码列表：\r\n\r\n| 用户说法 | 展开为 |\r\n|----------|--------|\r\n| 东南亚 | TH,VN,ID,PH,MY,SG,KH,MM,LA |\r\n| 欧洲 | GB,DE,FR,ES,IT,NL,SE,NO,PL,PT,IE,AT,CH,BE,DK,FI,GR,CZ,RO,HU |\r\n| 中东 | SA,AE,QA,KW,BH,OM,JO,IL,EG,IQ |\r\n| 拉美 / 南美 | BR,MX,AR,CO,CL,PE,EC,VE |\r\n| 北美 | US,CA |\r\n| 东亚 | JP,KR,CN,HK,TW |\r\n| 南亚 | IN,PK,BD,LK,NP |\r\n| 非洲 | NG,ZA,KE,EG,GH,ET,TZ |\r\n\r\n> 多国家搜索时用逗号分隔传入 `country_code` 参数，如 `US,CA,GB`\n\nFile v1.8.0:references/error-codes.md\n\n# Error Codes\r\n\r\n## Error Code Table\r\n\r\n| Code | HTTP | Description | Action |\r\n|------|------|-------------|--------|\r\n| 40001 | 400 | Invalid parameters | Check JSON format, field names, value ranges |\r\n| 40101 | 401 | Invalid API Key | Verify `CV_API_KEY` environment variable |\r\n| 40102 | 401 | API Key expired | Contact admin to renew or regenerate |\r\n| 40103 | 401 | API Key revoked | Contact admin |\r\n| 40104 | 401 | Missing X-User-Identity | Verify `CV_USER_IDENTITY` environment variable |\r\n| 40201 | 402 | Insufficient credits | Top up or upgrade plan |\r\n| 40301 | 403 | No permission for endpoint | Check API Key scopes |\r\n| 42901 | 429 | Rate limit exceeded | Script auto-retries; wait for Retry-After header |\r\n| 42902 | 402 | Daily quota exhausted | Wait until UTC 00:00 reset or upgrade plan |\r\n| 50001 | 500 | Server error | Record request_id, contact support |\r\n\r\n## Export-Specific Errors\r\n\r\n| Scenario | HTTP | Description |\r\n|----------|------|-------------|\r\n| Unsupported format (e.g., `feishu_doc`) | 400 | Format not yet supported |\r\n| Task not found or not owned by tenant | 404 | Task not found |\r\n| Task has no data to export | 404 | No data available for export |\r\n| OSS upload / DB insert / signing failed | 500 | Export failed |\r\n\r\n## Troubleshooting\r\n\r\n### Environment variables not set\r\n\r\n```\r\nError: CV_API_KEY environment variable is not set\r\n```\r\n\r\n**Fix**: Set environment variables and restart terminal/IDE.\r\n\r\n### API Key format\r\n\r\nValid format: `cv_live_` prefix + random string, e.g., `cv_live_Y8nil_BsKAbITdqj...`\r\n\r\n### Rate limiting\r\n\r\n- Default limit: 60 requests/minute (per tenant)\r\n- Script auto-retries up to 3 times on 429\r\n- `Retry-After` response header indicates wait time in seconds\r\n\r\n### Daily quota\n\n- Resets at UTC 00:00 daily\n- `meta.quota_remaining` shows remaining daily API request count, not credits\n- `-1` means unlimited\n- Do not display a credits warning based on `quota_remaining`\n\n### Insufficient credits\n\n- Only error code `40201` confirms insufficient credits\n- `meta.credits_remaining` is the actual OpenAPI credits balance when present\n- A successful response must never be converted into an insufficient-credits warning\n\n### Collection task timeout\n\r\n- Collection tasks are async, typically 5~30 minutes\r\n- Recommended poll interval: 60 seconds\r\n- Status `timeout` means the task timed out; try resubmitting\r\n\r\n### Permission denied\r\n\r\nAPI Key `scopes` field controls endpoint access:\r\n- `[\"*\"]` — full access\r\n- `[\"collection:submit\"]` — link/username collection only\r\n- `[\"collection:keyword-submit\"]` — keyword collection only\r\n- `[\"collection:export\"]` — export only\r\n- `[\"file:download\"]` — file download only\n\nFile v1.8.0:references/industry-categories.md\n\n# 行业类目映射表\r\n\r\n**所有平台统一使用三级数字类目 ID。ID 位数随所属一级类目变化，当前可能为 7 位或 8 位。**\n\r\n- 所有平台统一使用 `industry` 参数传三级 ID（逗号分隔）\r\n\r\n用户输入中文/英文类目名时，skill 会自动转换为对应的三级 ID 传给 API。\r\n\r\n## 一级类目总览\r\n\r\n| ID | 英文 | 中文 |\r\n|----|------|------|\r\n| 19 | Games | 游戏 |\r\n| 25 | Beauty & Personal Care | 美妆与个人护理 |\r\n| 16 | Clothing & Fashion | 服装与时尚 |\r\n| 3 | Healthcare | 医疗保健 |\r\n| 12 | Outdoor & Sports | 户外与运动 |\r\n| 26 | Food & Beverages | 美食与饮品 |\r\n| 24 | Technology & Electronics | 科技数码 |\r\n| 15 | Travel & Lifestyle | 旅行与生活方式 |\r\n| 28 | Art | 艺术 |\r\n| 5 | Entertainment | 娱乐 |\r\n| 9 | Pets | 宠物 |\r\n| 1 | Parenting & Family | 亲子与家庭 |\r\n| 17 | Automotive & Transportation | 汽车与交通 |\r\n| 10 | Home & Living | 家居 |\r\n| 20 | Toys | 玩具 |\r\n| 30 | Software | 软件 |\r\n| 29 | Finance | 财经 |\r\n| 4 | Books | 图书 |\r\n| 6 | Learning & Education | 学习与教育 |\r\n| 27 | Career Development | 职业发展 |\r\n| 11 | Architecture | 建筑 |\r\n| 23 | Science | 科学 |\r\n| 14 | Culture & Customs | 文化与习俗 |\r\n| 8 | Religion & Beliefs | 宗教与信仰 |\r\n| 22 | Social Welfare | 社会公益 |\r\n| 21 | Environmental Protection | 环保 |\r\n| 2 | Agriculture & Rural Areas | 农业与乡村 |\r\n| 7 | Safety & Emergency | 安全与应急 |\r\n| 13 | Politics | 政治 |\r\n| 18 | Rule of Law | 法治 |\r\n\r\n## 快速查询：常用三级类目 ID\r\n\r\n| 中文 | 英文 | 三级 ID |\r\n|------|------|---------|\r\n| 护肤 | Skincare | 25009001 |\r\n| 面部彩妆 | Facial Makeup | 25006004 |\r\n| 眼妆 | Eye Makeup | 25006003 |\r\n| 唇妆 | Lip Makeup | 25006002 |\r\n| 美甲 | Nail Art & Tools | 25012001 |\r\n| 女装 | Women's Clothing | 16002001 |\r\n| 男装 | Men's Clothing | 16003001 |\r\n| 童装 | Kids' Clothing | 16004001 |\r\n| 鞋履 | Footwear | 16001001 |\r\n| 手机 | Mobile Phones | 24001001 |\r\n| 电脑 | Computers | 24002001 |\r\n| 相机 | Photography & Video Equipment | 24003001 |\r\n| 耳机 | Headphones | 24006001 |\r\n| 健身 | Aerobic Training | 12001001 |\r\n| 篮球 | Basketball | 12002001 |\r\n| 足球 | Football | 12002002 |\r\n| 跑步 | Running | 12003001 |\r\n| 游戏 | Shooter | 19006001 |\r\n| 美食 | Food | 26001001 |\r\n| 咖啡 | Coffee | 26002001 |\r\n| 旅行 | Travel Guides | 15001001 |\r\n\r\n## 二级 & 三级类目明细\r\n\r\n### Games 游戏\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| Shooter | Shooter | 射击类 |\r\n| MOBA | MOBA | MOBA类 |\r\n| Strategy & Battle | PvP / Strategy Survival / Card Battle | 策略对战类 |\r\n| Sports & Racing | Sports / Racing | 体育竞速类 |\r\n| Action | Fighting / Action Adventure / Platformer | 动作类 |\r\n| Role-Playing | RPG / Open World / MMORPG | 角色扮演类 |\r\n| Simulation & Management | Simulation & Management | 模拟经营类 |\r\n| Casual & Social | Puzzle & Casual / Party & Social | 休闲社交类 |\r\n| Rhythm | Rhythm | 音乐节奏类 |\r\n| Horror & Mystery | Horror & Mystery | 恐怖悬疑类 |\r\n| Anime | Anime | 二次元类 |\r\n| Text Adventure | Text Adventure | 文字冒险类 |\r\n| Sandbox | Sandbox | 沙盒类 |\r\n| Gaming Equipment | Gaming Equipment | 游戏设备 |\r\n\r\n### Beauty & Personal Care 美妆与个人护理\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| Makeup | Facial Makeup / Eye Makeup / Lip Makeup | 彩妆 |\r\n| Tattoo | Tattoo | 纹身 |\r\n| Nail Art & Tools | Nail Art & Tools | 美甲及工具 |\r\n| Makeup Tools & Accessories | Makeup Tools & Accessories | 化妆工具和配件 |\r\n| Wigs | Wigs | 假发 |\r\n| Skincare | Skincare | 护肤 |\r\n| Hair Care | Hair Care | 护发 |\r\n| Oral Care | Oral Care | 口腔护理 |\r\n| Body Care | Body Care | 身体护理 |\r\n| Beauty Devices & Accessories | Beauty Devices & Accessories | 护理仪器和配件 |\r\n| Feminine Care | Feminine Care | 女性护理 |\r\n| Men's Care | Men's Care | 男性护理 |\r\n| Adult Products | Adult Products | 两性用品 |\r\n| Perfume | Perfume | 香水 |\r\n\r\n### Clothing & Fashion 服装与时尚\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| Women's Clothing | Women's Clothing | 女装 |\r\n| Men's Clothing | Men's Clothing | 男装 |\r\n| Kids' Clothing | Kids' Clothing | 童装 |\r\n| Footwear | Footwear | 鞋履 |\r\n| Bags & Luggage | Bags & Luggage | 箱包 |\r\n| Jewelry | Jewelry | 首饰 |\r\n| Accessories | Watches / Sunglasses / Belts / Hats / Ties / Hair Accessories / Scarves | 配饰 |\r\n| Occasion Wear | Workplace & Business / Daily Casual / Sports / Travel & Dating / Weddings & Banquets / Campus / Niche Hobbies | 场景着装 |\r\n\r\n### Outdoor & Sports 户外与运动\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| Fitness | Aerobic Training / Strength Training / Healthy Recipes / Fitness Equipment / Yoga & Pilates | 健身 |\r\n| Ball Sports | Basketball / Football / Volleyball / Tennis / Table Tennis / Badminton / Baseball / Rugby / Hockey / Golf | 球类运动 |\r\n| Running | Running | 跑步 |\r\n| Water Sports | Swimming / Diving / Rowing & Boating | 水上运动 |\r\n| Ice & Snow Sports | Skiing / Skating | 冰雪运动 |\r\n| Cycling | Cycling | 骑行 |\r\n| Combat & Martial Arts | Combat & Martial Arts | 格斗与武术 |\r\n| Camping & Gear | Camping & Gear | 露营与装备 |\r\n| Hiking & Mountaineering | Hiking & Mountaineering | 徒步与登山 |\r\n| Extreme Sports | Surfing / Rock Climbing / Skateboarding | 极限运动 |\r\n\r\n### Food & Beverages 美食与饮品\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| Food | Food | 食物 |\r\n| Beverages | Coffee / Tea Drinks / Alcoholic Drinks | 饮品 |\r\n| Cooking | Cooking | 烹饪 |\r\n| Food Exploration & Reviews | Food Exploration & Reviews | 探店与测评 |\r\n| Food Live Streaming | Food Live Streaming | 吃播 |\r\n\r\n### Technology & Electronics 科技数码\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| Electronics | Mobile Phones / Computers / Photography & Video Equipment / VR & AR / Smart Watches & Bands / Headphones | 数码产品 |\r\n| Digital Accessories | Mobile Phone Accessories / Computer Accessories | 数码产品配件 |\r\n| Technology News | Technology News | 科技资讯 |\r\n\r\n### Travel & Lifestyle 旅行与生活方式\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| Travel | Travel Guides / Hotel Experiences / Natural Scenery / Cultural Experiences | 旅行 |\r\n| Lifestyle | Lifestyle | 生活方式 |\r\n\r\n### Art 艺术\r\n\r\n| 二级 | 中文 |\r\n|------|------|\r\n| Music | 音乐 |\r\n| Dance | 舞蹈 |\r\n| Crafts & Handmade | 工艺与手作 |\r\n| Painting | 绘画 |\r\n\r\n### Entertainment 娱乐\r\n\r\n| 二级 | 中文 |\r\n|------|------|\r\n| Film & TV Editing & Commentary | 影视剪辑与解说 |\r\n| Variety Shows & Reality TV | 综艺与真人秀 |\r\n| Celebrity News | 明星与艺人资讯 |\r\n| Comics & Animation | 漫画与动画 |\r\n| Comedy & Humor | 幽默搞笑类 |\r\n| Cosplay | 角色扮演 |\r\n\r\n### Pets 宠物\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| Pet Supplies | Pet Food / Pet Lifestyle Products / Pet Toys | 宠物用品 |\r\n| Pet Entertainment | Pet Entertainment | 宠物娱乐 |\r\n\r\n### Parenting & Family 亲子与家庭\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| Family Daily Life | Parent-Child Interaction / Couple Interaction | 家庭日常 |\r\n| Maternity & Baby Products | Maternal Products / Baby Products | 母婴产品 |\r\n\r\n### Automotive & Transportation 汽车与交通\r\n\r\n| 二级 | 中文 |\r\n|------|------|\r\n| Automobiles | 汽车 |\r\n| Motorcycles | 摩托车 |\r\n| Car Maintenance | 汽车养护 |\r\n| In-Vehicle Products | 车载产品 |\r\n| Auto Parts (Car Parts / Motorcycle Parts) | 配件 |\r\n| Car Modification | 改装 |\r\n| Self-Driving Travel | 自驾游 |\r\n\r\n### Home & Living 家居\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| Furniture | Furniture | 家具 |\r\n| Home Decoration | Home Decoration | 家居装饰 |\r\n| Home Appliances | Kitchen Appliances / Bathroom Appliances / Household Appliances / Lighting Fixtures / Audio-Visual & Entertainment | 家用电器 |\r\n| Bedding | Bedding | 床上用品 |\r\n| Home Textiles | Home Textiles | 居家布艺 |\r\n| Daily Necessities | Daily Necessities | 生活日用 |\r\n| Kitchen & Tableware | Kitchen & Tableware | 厨房与餐厨用品 |\r\n| Bathroom Supplies | Bathroom Supplies | 卫浴 |\r\n| Home Cleaning | Home Cleaning | 家居清洁 |\r\n| Home Storage & Organization | Home Storage & Organization | 家居收纳与整理 |\r\n| Room Renovation | Room Renovation | 房间改造 |\r\n| Gardening & Plants | Gardening & Plants | 园艺绿植 |\r\n\r\n### Toys 玩具\r\n\r\n| 二级 | 中文 |\r\n|------|------|\r\n| Children's Toys | 儿童玩具 |\r\n| Adult Art Toys | 成人潮玩 |\r\n| Building Block Toys | 积木玩具 |\r\n| Educational Toys | 益智玩具 |\r\n| Model Toys | 模型玩具 |\r\n\r\n### Software 软件\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| AI | AI | AI |\r\n| Mobile Apps | Social / Music / Video & Live Streaming / Learning / Tools / Shopping / Fitness / Finance | 应用程序 |\r\n| Web3 | NFT / Cryptocurrency / Decentralized Finance | Web3 |\r\n\r\n## 使用说明\r\n\r\n### 所有平台统一规则\r\n\r\n**所有平台参数名**：`industry`\r\n\r\n**传值格式**：所有平台统一传**三级数字类目 ID**，逗号分隔。不要依赖固定长度判断层级，应以完整行业树中的真实节点关系为准。\n\r\n**映射规则**：\r\n- 用户说\"美妆\" → 查找一级类目 `Beauty & Personal Care` (ID: 25) → 获取所有三级 ID → 传 `25006004,25006003,25006002,25006001,25011001,25012001,25003001,25002001,25009001,25007001,25004001,25013001,25008001,25005001,25010001,25001001,25014001`\r\n- 用户说\"护肤\" → 查找三级类目 `Skincare` → 传 `25009001`\r\n- 用户说\"手机\" → 查找三级类目 `Mobile Phones` → 传 `24001001`\n- 用户说\"Comedy\" / \"Comedy & Humor\" → 查找三级类目 `Comedy & Humor` → 传 `5001001`\n- 用户说\"Entertainment\" → 查找一级类目 `Entertainment` (ID: 5) → 展开并传所有三级子类目 ID\n\r\n**示例**：\r\n\r\n```json\r\n// TikTok / YouTube / Instagram — 所有平台统一使用 \"industry\" 参数\r\n{\r\n  \"platform\": \"tiktok\",\r\n  \"industry\": \"25009001,25006004\"\r\n}\r\n\r\n// YouTube\r\n{\r\n  \"platform\": \"youtube\",\r\n  \"industry\": \"25009001,25006004\"\r\n}\r\n\r\n// Instagram\r\n{\r\n  \"platform\": \"instagram\",\r\n  \"industry\": \"25009001,25006004\"\r\n}\r\n```\r\n\r\n### 映射逻辑总结\r\n\r\n| 用户输入 | 所有平台参数值 |\r\n|---------|---------------|\r\n| 美妆（一级） | 所有三级 ID（如 `25009001,25006004,...`） |\r\n| 护肤（三级） | 三级 ID（`25009001`） |\r\n| 手机（三级） | 三级 ID（`24001001`） |\n\nFile v1.8.0:references/language-codes.md\n\n# 语言代码映射表\r\n\r\n用户说中文语言名时，agent 需要转换为 ISO 639-1 代码传给 API 的 `language_code` 参数。\r\n\r\n## 常用语言\r\n\r\n| 代码 | 中文 | English |\r\n|------|------|---------|\r\n| en | 英语 | English |\r\n| zh | 中文 | Chinese |\r\n| es | 西班牙语 | Spanish |\r\n| fr | 法语 | French |\r\n| de | 德语 | German |\r\n| ja | 日语 | Japanese |\r\n| ko | 韩语 | Korean |\r\n| pt | 葡萄牙语 | Portuguese |\r\n| ru | 俄语 | Russian |\r\n| ar | 阿拉伯语 | Arabic |\r\n| hi | 印地语 | Hindi |\r\n| it | 意大利语 | Italian |\r\n| nl | 荷兰语 | Dutch |\r\n| sv | 瑞典语 | Swedish |\r\n| no | 挪威语 | Norwegian |\r\n| da | 丹麦语 | Danish |\r\n| fi | 芬兰语 | Finnish |\r\n| pl | 波兰语 | Polish |\r\n| tr | 土耳其语 | Turkish |\r\n| th | 泰语 | Thai |\r\n| vi | 越南语 | Vietnamese |\r\n| id | 印度尼西亚语 | Indonesian |\r\n| ms | 马来语 | Malay |\r\n| tl | 他加禄语 | Tagalog |\r\n| uk | 乌克兰语 | Ukrainian |\r\n| el | 希腊语 | Greek |\r\n| cs | 捷克语 | Czech |\r\n| ro | 罗马尼亚语 | Romanian |\r\n| hu | 匈牙利语 | Hungarian |\r\n| he | 希伯来语 | Hebrew |\r\n| bn | 孟加拉语 | Bengali |\r\n| ur | 乌尔都语 | Urdu |\r\n| sw | 斯瓦希里语 | Swahili |\r\n| km | 高棉语 | Khmer |\r\n| my | 缅甸语 | Burmese |\r\n| lo | 老挝语 | Lao |\r\n\r\n> 多语言搜索时用逗号分隔传入，如 `en,zh`\n\nArchive v1.0.8: 34 files, 60222 bytes\n\nFiles: collection/creator-collection/SKILL.md (7004b), discovery/creator-lookalike/SKILL.md (5182b), discovery/creator-search/SKILL.md (9339b), outreach/creator-outreach/SKILL.md (6640b), references/api-reference.md (12445b), references/country-codes.md (2150b), references/error-codes.md (2699b), references/industry-categories.md (10763b), references/language-codes.md (1373b), references/platform-params.md (16628b), scripts/_api_client.mjs (6083b), scripts/_industry_mapper.mjs (20213b), scripts/export_task_data.mjs (1116b), scripts/export_to_csv.mjs (4133b), scripts/find_lookalike.mjs (945b), scripts/get_download_url.mjs (644b), scripts/get_task_data.mjs (522b), scripts/get_task_status.mjs (456b), scripts/influencer_industry_tree.json (36021b), scripts/langfuse/test_cases.json (5616b), scripts/outreach_contact.mjs (671b), scripts/outreach_send.mjs (1711b), scripts/outreach_task.mjs (2484b), scripts/outreach_todo.mjs (574b), scripts/poll_task_status.mjs (2041b), scripts/search_creators.mjs (873b), scripts/submit_collection_task.mjs (1317b), scripts/submit_keyword_task.mjs (859b), skill-card.md (2817b), SKILL.md (4717b), workflow/SKILL.md (4283b), workflow/workflows/batch-outreach.md (2341b), workflow/workflows/full-campaign.md (3258b), _meta.json (137b)\n\nFile v1.0.8:collection/creator-collection/SKILL.md\n\n---\r\nname: creator-collection\r\ndescription: |\r\n  批量达人数据采集与导出能力，支持 TikTok、YouTube、Instagram、Twitter 四平台。支持链接批量、用户名批量、关键词采集三种模式。异步任务机制，含提交、轮询、取数、导出完整生命周期。\r\n  Use when: 批量采集, 数据导出, 离线采集, batch collection, data export, keyword collection\r\ncompatibility: Node.js 20.6+\r\nmetadata:\r\n  layer: collection\r\n  parent: creator-scraper-cv\r\n---\r\n\r\n## 概述\r\n\r\n批量达人数据采集与导出能力。支持通过链接、用户名或关键词提交异步采集任务，自动轮询任务状态，完成后导出为 xlsx/csv/html 文件并提供下载链接。\r\n\r\n支持平台：TikTok、YouTube、Instagram、Twitter。\r\n\r\n> **Twitter 平台限制**：仅支持 `LINK_BATCH`（链接采集）和 `FILE_UPLOAD`（用户名采集），不支持视频采集（`CREATOR_VIDEO`、`POST_VIDEO`）。\r\n\r\n## 脚本引用\r\n\r\n| # | 脚本 | 路径 | 状态 |\r\n|---|------|------|------|\r\n| 1 | submit_collection_task.mjs | `../../scripts/submit_collection_task.mjs` | ✅ |\r\n| 2 | submit_keyword_task.mjs | `../../scripts/submit_keyword_task.mjs` | ✅ |\r\n| 3 | poll_task_status.mjs | `../../scripts/poll_task_status.mjs` | ✅ |\r\n| 4 | get_task_status.mjs | `../../scripts/get_task_status.mjs` | ✅ |\r\n| 5 | get_task_data.mjs | `../../scripts/get_task_data.mjs` | ✅ |\r\n| 6 | export_task_data.mjs | `../../scripts/export_task_data.mjs` | ✅ |\r\n| 7 | export_to_csv.mjs | `../../scripts/export_to_csv.mjs` | ✅ |\r\n| 8 | get_download_url.mjs | `../../scripts/get_download_url.mjs` | ✅ |\r\n\r\n## 异步任务生命周期\r\n\r\n采集任务为异步操作（耗时 5~30 分钟），遵循四阶段流程：\r\n\r\n```\r\n提交(submit) → 轮询(poll) → 取数(get data) → 导出(export)\r\n```\r\n\r\n| 阶段 | 脚本 | 说明 |\r\n|------|------|------|\r\n| 1. 提交 | `submit_collection_task.mjs` / `submit_keyword_task.mjs` | 返回 task_id |\r\n| 2. 轮询 | `poll_task_status.mjs` | 每 60s 自动轮询直到完成 |\r\n| 3. 取数 | `get_task_data.mjs` | 分页获取原始 JSON 数据（仅在用户明确要求时使用） |\r\n| 4. 导出 | `export_task_data.mjs` | 生成文件并返回下载链接 |\r\n\r\n> **规则**：采集完成后，**必须**先调用 `export_task_data.mjs` 生成可下载文件并展示链接给用户。不要直接调用 `get_task_data.mjs` 输出原始 JSON。\r\n\r\n> **积分提醒规则**：仅当接口明确返回错误码 `40201` 时提示积分不足。`meta.quota_remaining` 是当天剩余 API 请求次数，不是积分余额；采集、轮询或导出成功后，禁止根据该字段生成“剩余积分不足”提醒。\r\n\r\n辅助脚本：\r\n- `get_task_status.mjs` — 单次查询任务状态（不轮询）\r\n- `export_to_csv.mjs` — 管道式本地 CSV 导出（接收 stdin JSON）\r\n- `get_download_url.mjs` — 获取已生成文件的下载链接\r\n\r\n## 采集类型\r\n\r\n| 类型 | task_type 值 | 触发场景 | 提交脚本 |\r\n|------|-------------|----------|----------|\r\n| 链接批量 | `LINK_BATCH` | 用户提供达人主页链接列表 | `submit_collection_task.mjs` |\r\n| 用户名批量 | `FILE_UPLOAD` | 用户提供用户名列表 | `submit_collection_task.mjs` |\r\n| 关键词采集 | — | 用户提供关键词，按关键词批量采集 | `submit_keyword_task.mjs` |\r\n\r\n**使用示例**：\r\n\r\n```bash\r\n# 链接批量采集\r\nnode ../../scripts/submit_collection_task.mjs '{\"task_type\":\"LINK_BATCH\",\"platform\":\"tiktok\",\"values\":[\"https://www.tiktok.com/@creator1\",\"https://www.tiktok.com/@creator2\"],\"task_name\":\"Q1 collection\"}'\r\n\r\n# 用户名批量采集\r\nnode ../../scripts/submit_collection_task.mjs '{\"task_type\":\"FILE_UPLOAD\",\"platform\":\"tiktok\",\"values\":[\"creator1\",\"creator2\"],\"task_name\":\"username batch\"}'\r\n\r\n# 关键词采集\r\nnode ../../scripts/submit_keyword_task.mjs '{\"platform\":\"tiktok\",\"keywords\":[\"beauty tips\",\"skincare routine\"]}'\r\n\r\n# Twitter 链接批量采集\r\nnode ../../scripts/submit_collection_task.mjs '{\"task_type\":\"LINK_BATCH\",\"platform\":\"twitter\",\"values\":[\"https://x.com/creator1\",\"https://x.com/creator2\"],\"task_name\":\"Twitter collection\"}'\r\n```\r\n\r\n## 平台支持矩阵\r\n\r\n| 平台 | `LINK_BATCH` | `FILE_UPLOAD` | `CREATOR_VIDEO` | `POST_VIDEO` | 关键词采集 |\r\n|------|:---:|:---:|:---:|:---:|:---:|\r\n| TikTok | ✅ | ✅ | ✅ | ✅ | ✅ |\r\n| YouTube | ✅ | ✅ | ✅ | ✅ | ✅ |\r\n| Instagram | ✅ | ✅ | ✅ | ✅ | ✅ |\r\n| Twitter | ✅ | ✅ | ❌ | ❌ | ✅ |\r\n\r\n> **Twitter 限制**：仅支持链接采集和用户名采集，不支持视频采集（`CREATOR_VIDEO`、`POST_VIDEO`）。\r\n\r\n## 参数说明\r\n\r\n### submit_collection_task.mjs\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `task_type` | string | **必填**。`LINK_BATCH`（链接）/ `FILE_UPLOAD`（用户名） |\r\n| `platform` | string | **必填**。`tiktok` / `youtube` / `instagram` / `twitter` |\r\n| `values` | string[] | **必填**。链接或用户名数组，最多 200 条 |\r\n| `task_name` | string | 任务名称 |\r\n| `webhook_url` | string | 完成回调 URL（HTTPS） |\r\n\r\n### submit_keyword_task.mjs\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `platform` | string | **必填**。`tiktok` / `youtube` / `instagram` / `twitter` |\r\n| `keywords` | string[] | **必填**。关键词列表，最多 10 个 |\r\n| `task_name` | string | 任务名称 |\r\n| `webhook_url` | string | 完成回调 URL（HTTPS） |\r\n\r\n### poll_task_status.mjs\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `task_id` | string | **必填**。任务 ID |\r\n| `interval` | integer | 轮询间隔秒数，默认 60 |\r\n| `max_attempts` | integer | 最大轮询次数，默认 45（约 45 分钟） |\r\n\r\n### get_task_data.mjs\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `task_id` | string | **必填**。任务 ID |\r\n| `page` | integer | 页码，默认 1 |\r\n| `size` | integer | 每页条数，默认 20，最大 100 |\r\n\r\n### export_task_data.mjs\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `task_id` | string | **必填**。任务 ID（必须已完成） |\r\n| `format` | string | **必填**。`xlsx` / `csv` / `html` |\r\n\r\n> 重复调用相同 task_id + format 会返回缓存文件，不会重复生成。\r\n\r\n## 输出格式\r\n\r\n### 导出格式\r\n\r\n| 格式 | 说明 |\r\n|------|------|\r\n| `xlsx` | Excel 格式（默认推荐） |\r\n| `csv` | CSV 格式 |\r\n| `html` | HTML 表格格式 |\r\n\r\n### 下载链接\r\n\r\n`export_task_data.mjs` 返回 `file_url` 字段，为 OSS 签名下载链接。如需重新获取链接，使用 `get_download_url.mjs`：\r\n\r\n```bash\r\nnode ../../scripts/get_download_url.mjs '{\"file_id\":\"xxx\"}'\r\n# 或\r\nnode ../../scripts/get_download_url.mjs '{\"file_name\":\"task_xxx.xlsx\"}'\r\n```\r\n\r\n`export_to_csv.mjs` 为本地管道导出，通过 stdin 接收 JSON 数据：\r\n\r\n```bash\r\nnode ../../scripts/get_task_data.mjs '{\"task_id\":\"xxx\",\"size\":100}' | node ../../scripts/export_to_csv.mjs '{\"output\":\"creators.csv\"}'\r\n```\n\nFile v1.0.8:discovery/creator-lookalike/SKILL.md\n\n---\r\nname: creator-lookalike\r\ndescription: |\r\n  相似达人发现能力，支持种子达人解析、相似度匹配、跨平台搜索。通过 username、profile_url 或自动全平台搜索找到风格相似的创作者。\r\n  Use when: 相似达人, 类似达人, similar creators, lookalike, find similar\r\ncompatibility: Node.js 20.6+\r\nmetadata:\r\n  layer: discovery\r\n  parent: creator-scraper-cv\r\n---\r\n\r\n## 概述\r\n\r\n基于种子达人查找风格相似的创作者，支持同平台匹配和跨平台发现（如从 TikTok 达人找到 YouTube 上的相似创作者）。\r\n\r\n## 脚本引用\r\n\r\n| 脚本 | 路径 | 模式 | 状态 |\r\n|------|------|------|------|\r\n| find_lookalike.mjs | `../../scripts/find_lookalike.mjs` | Sync, 自动解析 username/URL | ✅ |\r\n\r\n## 输入方式\r\n\r\nAPI 内部自动将 username/URL 解析为平台 ID，无需额外 resolve 步骤。\r\n\r\n### 方式一：username + platform（指定平台）\r\n\r\n明确指定达人所在平台，直接在该平台查找相似达人：\r\n\r\n```bash\r\nnode ../../scripts/find_lookalike.mjs '{\"username\":\"creator_demo\",\"platform\":\"tiktok\",\"limit\":10}'\r\n```\r\n\r\n### 方式二：profile_url（自动识别平台）\r\n\r\n传入达人主页链接，API 自动解析平台和用户名：\r\n\r\n```bash\r\nnode ../../scripts/find_lookalike.mjs '{\"profile_url\":\"https://www.tiktok.com/@creator_demo\",\"limit\":10}'\r\n```\r\n\r\n支持的 URL 格式：\r\n- TikTok: `https://www.tiktok.com/@username`\r\n- YouTube: `https://www.youtube.com/@username`\r\n- Instagram: `https://www.instagram.com/username`\r\n\r\n### 方式三：username only（搜索全平台）\r\n\r\n仅传入用户名，不指定平台，API 自动在 TikTok、YouTube、Instagram 三个平台搜索匹配：\r\n\r\n```bash\r\nnode ../../scripts/find_lookalike.mjs '{\"username\":\"creator_demo\",\"limit\":10}'\r\n```\r\n\r\n## 参数说明\r\n\r\n| 参数 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `username` | string | 二选一 | 达人用户名（不含 `@`），与 `profile_url` 二选一 |\r\n| `platform` | string | 否 | 种子达人平台：`tiktok` / `youtube` / `instagram`，省略则搜索全平台 |\r\n| `profile_url` | string | 二选一 | 达人主页链接（自动识别平台），与 `username` 二选一 |\r\n| `target_platform` | string | 否 | 目标搜索平台，省略则与种子达人同平台。设为不同平台可实现跨平台搜索 |\r\n| `target_region` | string | 否 | 目标国家代码，`all` 表示不限 |\r\n| `target_language` | string | 否 | 目标语言代码，`all` 表示不限 |\r\n| `limit` | integer | 否 | 返回数量，默认 20，最大 50 |\r\n| `follower_min` | integer | 否 | 最小粉丝数 |\r\n| `follower_max` | integer | 否 | 最大粉丝数 |\r\n| `avg_views_min` | integer | 否 | 最小平均播放量 |\r\n| `avg_views_max` | integer | 否 | 最大平均播放量 |\r\n| `female_rate_min` | number | 否 | 最小女性受众比例（0~100） |\r\n| `lang` | string | 否 | 响应语言：`cn` / `en`，仅控制返回字段翻译，不筛选达人 |\r\n| `service_level` | string | 否 | 服务等级，默认 `S1` |\r\n\r\n### 跨平台搜索说明\r\n\r\n设置 `target_platform` 与种子达人不同平台，可发现跨平台相似达人：\r\n\r\n```bash\r\n# 从 TikTok 达人找 YouTube 上的相似创作者\r\nnode ../../scripts/find_lookalike.mjs '{\"username\":\"creator_demo\",\"platform\":\"tiktok\",\"target_platform\":\"youtube\",\"limit\":10}'\r\n```\r\n\r\n## 输出格式\r\n\r\n```\r\n🔍 找到 N 个与 @seed_username 相似的达人\r\n\r\n📊 相似达人列表\r\n\r\n| #   | 用户名      | 昵称        | 粉丝数  | 平均播放 | 互动率  | 相似度  | 国家 | 主页链接          |\r\n| --- | ----------- | ----------- | ------- | -------- | ------- | ------ | ---- | ----------------- |\r\n| 1   | username1   | Nickname1   | 120K    | 3.8万    | 7.20%   | 85.0%  | US   | [查看][link1]     |\r\n| 2   | username2   | Nickname2   | 95.5K   | 2.1万    | 5.50%   | 78.3%  | US   | [查看][link2]     |\r\n\r\n[link1]: https://www.tiktok.com/@username1\r\n[link2]: https://www.tiktok.com/@username2\r\n\r\n📈 统计信息\r\n• 种子达人：@seed_username（平台ID：7123456789）\r\n• 结果总数：N 个相似达人\r\n• 本次消耗：10 积分\r\n• 剩余配额：xxx 次\r\n• 请求ID：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\r\n```\r\n\r\n返回字段：`uid`、`username`、`nickname`、`avatar_url`、`profile_url`、`country_code`、`followers_count`、`avg_views`、`engagement_rate`、`match_score`。\r\n\r\n其中 `match_score` 为相似度评分（0~100），按相似度降序排列。\r\n\r\n## 错误处理\r\n\r\n| 错误码 | 说明 | 处理方式 |\r\n|--------|------|----------|\r\n| 40401 | 达人不在数据库中 | 告知用户该达人尚未被平台收录，建议换一个达人或提交采集任务 |\r\n| 40001 | 参数无效 | 检查 username/profile_url 格式 |\r\n| 42902 | 每日配额耗尽 | 等待 UTC 00:00 重置或升级套餐 |\r\n\r\n## 决策规则\r\n\r\n- 用户给出主页链接 → 使用 `profile_url` 参数\r\n- 用户给出用户名 + 平台 → 使用 `username` + `platform`\r\n- 用户仅给出用户名 → 仅传 `username`，API 搜索全平台\r\n- 用户要求\"找 YouTube 上类似的\" → 设置 `target_platform: \"youtube\"`\n\nFile v1.0.8:discovery/creator-search/SKILL.md\n\n---\nname: creator-search\ndescription: |\n  三平台达人搜索能力，支持 TikTok、YouTube、Instagram 多维度筛选（关键词、国家、粉丝数、互动率、类目等）。\n  Use when: 达人搜索, KOL搜索, 找达人, creator search, influencer discovery, search creators\ncompatibility: Node.js 20.6+\nmetadata:\n  layer: discovery\n  parent: creator-scraper-cv\n---\n\n# Creator Search（达人搜索）\n\n## 概述\n\n三平台（TikTok、YouTube、Instagram）达人实时搜索，支持关键词、国家、粉丝数、互动率、行业等多维度筛选，结果即时返回。\n\n## 脚本引用\n\n| 脚本 | 相对路径 | 状态 |\n|------|----------|------|\n| search_creators.mjs | `../../scripts/search_creators.mjs` | ✅ 可用 |\n\n调用格式：\n\n```bash\nnode {baseDir}/scripts/search_creators.mjs '{\"platform\":\"tiktok\",\"country_code\":\"US\",\"gender\":\"0\",\"followers_cnt_gte\":100000,\"service_level\":\"S2\"}'\n```\n\n## 参数提取强制规则\n\n1. `platform` 必须转换为小写：`tiktok` / `youtube` / `instagram`。\n2. 达人性别必须映射为编码：女性/女/female → `\"0\"`，男性/男/male → `\"1\"`。禁止传 `\"女性\"`、`\"男性\"`、`\"female\"`、`\"male\"`。\n3. 所有比例筛选参数使用 **0~100 的百分比数值**：用户说“互动率至少 3%”时传 `3`，不能传 `0.03`；“女性受众至少 70%”传 `70`。\n4. boolean 参数必须传 JSON boolean：`true` / `false`，不能传 `\"true\"` / `\"false\"`、`1` / `0`。`has_email`、`has_whatsapp`、`is_ai_creator`、`is_top_creator` 等均属于 boolean。\n5. 国家和语言必须转换为代码；多选使用英文逗号连接，例如 `country_code: \"US,CA\"`、`language_code: \"en,fr\"`。\n6. 日期筛选统一传 `YYYY-MM-DD`。\n7. `lang` 只控制响应码值翻译，不用于筛选达人，默认 `en`。筛选达人内容语言使用 `language_code`。\n8. 只传目标平台支持的字段。三平台播放量、互动率、受众语言等字段名并不完全相同。\n9. 当前 HTTP Open API 不支持 Instagram 的 `is_product_kol`、GMV、销售商品数筛选，不要发送这些字段。\n10. 不要发送旧字段名。HTTP Open API 请求模型会忽略未声明字段，旧字段可能请求成功但实际没有产生筛选效果。\n\n## 服务等级\n\n`service_level` 控制返回字段与积分消耗。面向用户发起搜索前，必须让用户清楚三档含义：\n\n- 用户未指定等级时，先展示下方简短表格，并说明默认推荐 `S2`。\n- 用户确认“默认/推荐/直接搜”时，使用 `S2`。\n- 用户明确指定 `S1` / `S2` / `S3`，或本轮对话已展示过等级说明时，可直接执行，避免重复打断。\n\n| 等级 | 名称 | 积分/条 | 返回范围 |\n|------|------|---------|----------|\n| S1 | 纯名单筛选 | 1 | 基础身份、主页、联系方式存在性、最近发布时间；具体字段因平台而异 |\n| S2 | 精准触达 | 3 | S1 + 国家、性别、粉丝/播放/互动、行业、邮箱等；具体字段因平台而异 |\n| S3 | 深度画像 | 4 | S2 + 受众性别、国家、语言、年龄分布 |\n\n## 通用请求参数\n\n除 `platform` 为脚本路由参数外，其余字段会作为 JSON Body 发送到对应平台搜索接口。\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `platform` | string | 必填：`tiktok` / `youtube` / `instagram` |\n| `keyword` | string | 搜索关键词 |\n| `country_code` | string | 国家代码，多选逗号分隔 |\n| `gender` | string | `\"0\"`=女性，`\"1\"`=男性 |\n| `has_email` | boolean | 是否有邮箱 |\n| `language_code` | string | 达人内容语言代码，多选逗号分隔 |\n| `followers_cnt_gte` / `followers_cnt_lte` | integer | 粉丝数/订阅数范围 |\n| `industry` | string | 行业类目；脚本支持类目 ID、中文/英文名称和常用别名 |\n| `audience_country_code_list` | string | 受众国家代码，多选逗号分隔 |\n| `audience_age_list` | string | 受众年龄，多选逗号分隔 |\n| `audience_female_rate_gte` / `audience_female_rate_lte` | number | 受众女性比例，传 0~100 百分比数值 |\n| `page` | integer | 页码，默认 1 |\n| `size` | integer | 每页数量，默认 50；普通 Open API 调用最大 100 |\n| `sort_field` | string | 排序字段，必须使用目标平台支持的字段 |\n| `sort_order` | string | `asc` / `desc`，默认 `desc` |\n| `service_level` | string | `S1` / `S2` / `S3`，默认 `S2` |\n| `lang` | string | 响应显示语言：`cn` / `en`，默认 `en`，不参与筛选 |\n\n## TikTok 参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `has_mcn` / `has_line` / `has_zalo` | boolean | 是否绑定 MCN / 有 Line / 有 Zalo |\n| `last10_avg_video_views_cnt_gte` / `_lte` | number | 近 10 条视频平均播放量范围 |\n| `last10_avg_video_interaction_rate_gte` / `_lte` | number | 近 10 条视频平均互动率范围，传 0~100 |\n| `last_video_publish_date_gte` / `_lte` | string | 最近视频发布日期范围，`YYYY-MM-DD` |\n| `product_category_id_array` | string | 带货类目 ID，多选逗号分隔 |\n| `audience_language_code_list` | string | 受众语言代码，多选逗号分隔 |\n| `last30day_gmv_gte` / `_lte` | number | 近 30 天 GMV 范围 |\n| `last30day_gpm_gte` / `_lte` | number | 近 30 天 GPM 范围 |\n| `last30day_gmv_per_buyer_gte` / `_lte` | number | 近 30 天客单价范围 |\n| `last30day_commission_rate_gte` / `_lte` | number | 近 30 天佣金率范围，传 0~100 |\n\nTikTok `sort_field`：`followers_cnt` / `last10_avg_video_views_cnt` / `last10_avg_video_interaction_rate`。\n\n## YouTube 参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `has_whatsapp` / `is_ai_creator` | boolean | 是否有 WhatsApp / 是否 AI 达人 |\n| `last10_avg_video_views_cnt_gte` / `_lte` | number | 近 10 条全部视频平均播放量范围 |\n| `last10_avg_video_views_cnt_short_gte` / `_lte` | number | 近 10 条短视频平均播放量范围 |\n| `last10_avg_video_interaction_rate_gte` / `_lte` | number | 近 10 条全部视频平均互动率范围，传 0~100 |\n| `last10_avg_video_interaction_rate_short_gte` / `_lte` | number | 近 10 条短视频平均互动率范围，传 0~100 |\n| `last_video_publish_date_gte` / `_lte` | string | 最近视频发布日期范围，`YYYY-MM-DD` |\n| `audience_language_code_list` | string | 受众语言代码，多选逗号分隔 |\n\nYouTube 不要使用旧字段名 `last10_avg_video_view_count_all_*`、`last10_avg_interaction_rate_all_*`、`female_ratio_*`。\n\n## Instagram 参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `has_whatsapp` / `is_top_creator` / `is_ai_creator` | boolean | 是否有 WhatsApp / Amazon 顶级带货达人 / AI 达人 |\n| `last10_avg_video_views_cnt_gte` / `_lte` | number | 近 10 条视频平均播放量范围 |\n| `last10_avg_video_interaction_rate_gte` / `_lte` | number | 近 10 条视频平均互动率范围，传 0~100 |\n| `last_video_publish_date_gte` / `_lte` | string | 最近视频发布日期范围，`YYYY-MM-DD` |\n| `audience_language_list` | string | 受众语言，多选逗号分隔 |\n\nInstagram 不要使用旧字段名 `last10_avg_video_view_count_*`、`last_video_publish_time_*`、`female_ratio_*`。\n\n## Category Input（industry 参数说明）\n\n`industry` 参数在 HTTP Open API 中要求传 level-3 数字类目 ID。通过本 skill 的脚本调用时，脚本支持以下输入并自动转换为 level-3 类目 ID：\n\n- **三级类目 ID**：`5001001,25009001,24001001`（真实 ID 可能为 7 位或 8 位）\n- **一级类目 ID**：`5,25`（真实 ID 可能为 1 位或 2 位，自动展开为所有三级子类目）\n- **中文类目名**：`美妆,科技数码`\n- **英文类目名**：`Skincare,Mobile Phones`\n- **常用英文别名**：`Fashion`, `Beauty`, `Sports`, `Tech`, `Food`, `Gaming`, `Travel`\n- **混合输入**：`Fashion,Beauty`（逐项解析）\n\n脚本会校验每个行业值是否存在于完整行业树中。只要有一项无法识别，搜索会在发送 HTTP 请求前失败，不会发送名称、未知数字 ID 或部分转换结果。\n\n## 示例\n\n```json\n{\"platform\":\"tiktok\",\"country_code\":\"US\",\"gender\":\"0\",\"has_email\":true,\"followers_cnt_gte\":100000,\"last10_avg_video_interaction_rate_gte\":3,\"service_level\":\"S2\"}\n```\n\n```json\n{\"platform\":\"youtube\",\"country_code\":\"US\",\"last10_avg_video_views_cnt_short_gte\":50000,\"audience_female_rate_gte\":70,\"service_level\":\"S3\"}\n```\n\n```json\n{\"platform\":\"instagram\",\"industry\":\"Beauty\",\"is_top_creator\":true,\"audience_language_list\":\"en\",\"service_level\":\"S2\"}\n```\n\n## 输出格式\n\n### TikTok\n\n```\n| # | 用户名 | 昵称 | 粉丝数 | 获赞数 | 平均播放 | 互动率 | 国家 | 主页链接 |\n```\n\n### YouTube\n\n```\n| # | 用户名 | 频道名 | 订阅数 | 总观看 | 平均播放 | 互动率 | 国家 | 频道链接 |\n```\n\n### Instagram\n\n```\n| # | 用户名 | 昵称 | 粉丝数 | 帖子数 | 平均播放 | 互动率 | 国家 | 主页链接 |\n```\n\n### 通用格式规则\n\n- 仅展示实际返回的字段，不能假设低服务等级包含 S2/S3 字段\n- 表格内链接用 `[查看][linkN]` 引用式，表格下方定义完整 URL\n- 统计信息单独列出：总匹配数、服务等级、消耗积分、剩余配额、请求 ID\n- `meta.total` 为 null 时不展示总匹配数\n- 默认展示 5~10 条，超过时询问用户\n- 展示后主动询问是否需要导出 CSV/Excel\n\nFile v1.0.8:outreach/creator-outreach/SKILL.md\n\n---\r\nname: creator-outreach\r\ndescription: |\r\n  邮件建联全流程能力，覆盖发送、任务查询、沟通历史、待办跟进、效果指标、渠道配置、附件上传。平台代发机制，无需用户提供 SMTP 配置。\r\n  Use when: 建联, 发邮件, 批量发送, email outreach, send email, outreach\r\ncompatibility: Node.js 20.6+\r\nmetadata:\r\n  layer: outreach\r\n  parent: creator-scraper-cv\r\n---\r\n\r\n# Creator Outreach — 邮件建联\r\n\r\n## 概述\r\n\r\n邮件建联全流程能力：搜索达人后一键发送邮件，支持单发/批量发送、任务轮询、沟通历史查询、待办跟进、效果指标分析，平台统一代发无需用户配置。\r\n\r\n## 脚本引用\r\n\r\n| 脚本路径 | 状态 | 说明 |\r\n|----------|------|------|\r\n| `../../scripts/outreach_send.mjs` | ✅ 已实现 | 发送邮件（单发/批量） |\r\n| `../../scripts/outreach_task.mjs` | ✅ 已实现 | 查询发送任务状态与结果 |\r\n| `../../scripts/outreach_contact.mjs` | ✅ 已实现 | 查询联系人沟通历史 |\r\n| `../../scripts/outreach_todo.mjs` | ✅ 已实现 | 待办跟进（超时/未读） |\r\n| `../../scripts/outreach_metrics.mjs` | 🔮 待实现 | 效果指标（发送量/打开率/回复率） |\r\n| `../../scripts/outreach_config.mjs` | 🔮 待实现 | 渠道与模板配置查询 |\r\n| `../../scripts/outreach_upload.mjs` | 🔮 待实现 | 附件上传（max 10MB） |\r\n\r\n> 🔮 标注的脚本尚未部署，调用将返回错误。待后端实现后可直接启用。\r\n\r\n## 架构原则\r\n\r\n**Skill = 纯 HTTP 客户端，不做任何本地业务逻辑处理。**\r\n\r\n- 脚本只负责组装 JSON 参数并调用 OpenAPI 接口\r\n- 所有业务逻辑（创建提报、查找会话、判断新建/回复）由 OpenAPI 内部完成\r\n- Skill 不需要知道 `submission_id`、`influencer_id` 等内部概念\r\n- 搜索后发送时，将搜索结果中的 `uid` + `platform` 传给 outreach_send，OpenAPI 内部自动从 Holo 查完整达人数据\r\n\r\n## 发送机制\r\n\r\n**邮件由 Creativault 平台后端统一代发（AWS SES），用户无需提供任何发信配置。**\r\n\r\n- **[禁止]** 向用户索要 SMTP 配置、邮箱密码、授权码、发信服务器地址\r\n- **[禁止]** 建议用户\"用自己的邮箱手动发送\"——平台已具备发送能力\r\n- `channel` 参数当前仅 `ses` 生效（默认值）；`gmail`/`outlook` 为预留字段，后端未实现\r\n- 若用户问\"邮件怎么发出去的\" → 回答：\"由 Creativault 平台统一代发，无需配置任何邮箱或 SMTP。\"\r\n\r\n## 参数说明\r\n\r\n### outreach_send.mjs\r\n\r\n`to` 和 `recipients` 互斥，传其一。\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `to` | string | 收件人邮箱（单发） |\r\n| `uid` | string | 达人平台 UID（单发必填，来自搜索结果的 uid 字段） |\r\n| `nickname` | string | 达人昵称（可选，用于会话展示） |\r\n| `platform` | string | 达人平台：tiktok/youtube/instagram |\r\n| `recipients` | object[] | 批量发送：`{email, uid, nickname, platform}` 数组 |\r\n| `subject` | string | 邮件主题 |\r\n| `body_html` | string | HTML 正文（支持 `{{creator_name}}` 变量） |\r\n| `body_text` | string | 纯文本正文 |\r\n| `channel` | string | `ses`（默认，唯一生效渠道） |\r\n| `template_id` | integer | 模板 ID（覆盖 subject/body） |\r\n| `send_mode` | string | `immediate`（默认）/ `smart`（时区优化） |\r\n| `force_new` | boolean | 强制新建会话（默认 false） |\r\n| `attachment_ids` | string[] | 附件 ID 列表 |\r\n\r\n### outreach_task.mjs\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `task_id` | string | **必填**。发送返回的任务 ID |\r\n| `include_result` | boolean | 附带逐收件人结果（默认 false） |\r\n| `result_filter` | string | 结果过滤：`all`/`sent`/`failed` |\r\n| `poll` | boolean | 自动轮询至终态（默认 false） |\r\n| `poll_interval` | integer | 轮询间隔秒数（默认 5） |\r\n| `poll_max_attempts` | integer | 最大轮询次数（默认 60） |\r\n\r\n### outreach_contact.mjs\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `email` | string | **必填**。达人邮箱 |\r\n| `include_history` | boolean | 包含消息历史（默认 true） |\r\n| `include_summary` | boolean | 包含 AI 摘要（默认 true） |\r\n\r\n### outreach_todo.mjs\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `overdue_hours` | integer | 超时阈值小时数（默认 24） |\r\n| `include_unread` | boolean | 包含未读会话（默认 true） |\r\n| `include_overdue` | boolean | 包含超时会话（默认 true） |\r\n\r\n## 安全规则\r\n\r\n**邮件发送是高风险操作，每次发送前必须获得用户明确确认。**\r\n\r\n**[禁止]** 用户说\"帮我发邮件\"后直接执行发送脚本。\r\n\r\n**[必须]** 在执行 `outreach_send.mjs` 之前，展示收件人列表并等待用户确认：\r\n\r\n1. **单笔发送**：展示收件人邮箱、主题、正文预览\r\n2. **批量发送**：展示收件人数量（≤5 全部展示，>5 展示前 5 个 + \"...及其他 N 个\"）、主题、正文预览\r\n3. 用户说\"确认\"/\"发送\"/\"是\"/\"Y\" → 执行发送\r\n4. 用户说\"取消\"/\"不发\"/\"修改\" → 不执行，询问修改意见\r\n5. 回复已有会话也需要确认\r\n6. 唯一例外：用户明确说\"直接发送不用确认\"时可跳过\r\n\r\n## 输出格式\r\n\r\n### 发送确认格式\r\n\r\n```\r\n📧 发送确认\r\n\r\n• 收件人：{email 或 N 个收件人列表}\r\n• 主题：{subject}\r\n• 渠道：{channel}\r\n• 模式：{send_mode}\r\n• 正文预览：{前 100 字符...}\r\n\r\n确认发送吗？(Y/N)\r\n```\r\n\r\n### 任务状态格式\r\n\r\n```\r\n📬 发送结果\r\n\r\n• 任务ID：{task_id}\r\n• 状态：{completed/partial/failed}\r\n• 成功：{sent_count} 封\r\n• 失败：{failed_count} 封\r\n• 耗时：{duration}\r\n• 消耗积分：{credits_consumed}\r\n```\r\n\r\n### 积分说明\r\n\r\n| 操作 | 积分消耗 |\r\n|------|----------|\r\n| 发送邮件（每封） | 1 |\r\n| 所有查询接口 | 0（免费） |\r\n\r\n### 决策规则\r\n\r\n- \"发邮件\"/\"建联\"/\"reach out\" → `outreach_send.mjs`\r\n- 搜索结果列表 → `outreach_send.mjs` + `recipients`\r\n- 发送后 → `outreach_task.mjs` + `poll:true` 确认投递\r\n- \"待办\"/\"follow-up\" → `outreach_todo.mjs`\r\n- \"沟通历史\"/\"what did I discuss\" → `outreach_contact.mjs`\r\n- \"效果\"/\"metrics\" → `outreach_metrics.mjs`（🔮 待实现）\r\n- \"渠道\"/\"模板\" → `outreach_config.mjs`（🔮 待实现）\r\n- 模板变量：`{{creator_name}}`、`{{creator_email}}`、`{{platform}}`\r\n- 搜索后发送时，**必须**传 `uid` + `platform`（OpenAPI 自动从 Holo 查完整达人数据）\n\nFile v1.0.8:SKILL.md\n\n---\r\nname: creator-scraper-cv\r\ndescription: |\r\n  Creativault creator data collection and outreach skill. Search and collect creator/influencer\r\n  data from TikTok, YouTube, Instagram, and Twitter. Send outreach emails to discovered creators with\r\n  automatic conversation management, batch sending, and follow-up tracking.\r\n  Supports multi-dimensional search, similar/lookalike creator discovery, batch collection by\r\n  links/usernames/keywords, task tracking, data export (xlsx/csv/html), and email outreach\r\n  (single/batch send, templates, smart timing, metrics).\r\n  Use when: creator search, influencer scraping, KOL search, KOL analytics,\r\n  social media data extraction, TikTok scraper, YouTube scraper, Instagram scraper, Twitter scraper,\r\n  influencer discovery, similar creators, lookalike, outreach, email outreach,\r\n  send email to creator, batch email, follow-up, 达人采集, KOL 搜索, 网红数据,\r\n  达人分析, 达人搜索, 相似达人, 社交媒体数据, 建联, 发邮件, 批量发送.\r\ncompatibility: Node.js 20.6+\r\nmetadata:\r\n  author: creativault\r\n  version: \"1.5.0\"\r\n---\r\n\r\n# Creativault Creator Ecosystem\r\n\r\n## 生态总览\r\n\r\n| 领域 | 子 Skill | 能力描述 |\r\n|------|----------|----------|\r\n| discovery | creator-search | 三平台达人多维度实时搜索 |\r\n| discovery | creator-lookalike | 种子达人相似匹配与跨平台发现 |\r\n| collection | creator-collection | 批量异步采集与多格式导出 |\r\n| outreach | creator-outreach | 邮件建联全流程（代发、跟进、待办） |\r\n| workflow | workflow | 剧本式工作流编排与 AI 自主调度 |\r\n\r\n## 路由索引\r\n\r\n| 子 Skill | 中文关键词 | 英文关键词 | 路径 |\r\n|----------|-----------|-----------|------|\r\n| creator-search | 达人搜索, KOL搜索, 找达人 | creator search, influencer discovery, search creators | discovery/creator-search/SKILL.md |\r\n| creator-lookalike | 相似达人, 类似达人 | similar creators, lookalike, find similar | discovery/creator-lookalike/SKILL.md |\r\n| creator-collection | 批量采集, 数据导出, 离线采集 | batch collection, data export, keyword collection | collection/creator-collection/SKILL.md |\r\n| creator-outreach | 建联, 发邮件, 批量发送 | email outreach, send email, outreach | outreach/creator-outreach/SKILL.md |\r\n| workflow | 工作流, 流程编排, 批量建联流程 | workflow orchestration, campaign flow, batch outreach flow | workflow/SKILL.md |\r\n\r\n**路由规则**：AI Agent 根据用户意图匹配上表关键词，加载对应子 skill。无法匹配时展示本表供用户选择。\r\n\r\n## Prerequisites\r\n\r\nSet the following environment variables:\r\n\r\n- `CV_API_KEY` — Creativault Open API Key (obtain from admin dashboard)\r\n- `CV_USER_IDENTITY` — Operator email address\r\n- `CV_API_BASE_URL` (optional) — API base URL, defaults to `http://api.creativault.vip`\r\n\r\n**Linux / macOS**:\r\n\r\n```bash\r\nexport CV_API_KEY=cv_live_your_key_here\r\nexport CV_USER_IDENTITY=your_email@example.com\r\n```\r\n\r\n**Windows PowerShell**:\r\n\r\n```powershell\r\n$env:CV_API_KEY = \"cv_live_your_key_here\"\r\n$env:CV_USER_IDENTITY = \"your_email@example.com\"\r\n```\r\n\r\n## Error Handling\r\n\r\n| Code | Description | Action |\r\n|------|-------------|--------|\r\n| 40001 | Invalid parameters | Check parameter format |\r\n| 40101 | Invalid API Key | Check CV_API_KEY |\r\n| 40102 | API Key expired | Contact admin |\r\n| 40201 | Insufficient credits | Top up or upgrade |\r\n| 40301 | No permission | Check API Key scopes |\r\n| 42901 | Rate limit exceeded | Auto-retry after Retry-After |\r\n| 42902 | Daily quota exhausted | Wait until UTC 00:00 |\r\n| 50001 | Server error | Report request_id to support |\r\n\r\n## 积分余额判断规则\r\n\r\n**只有 OpenAPI 明确返回错误码 `40201` 时，才能提示用户“积分不足”。**\r\n\r\n- `meta.quota_remaining` 表示当天剩余 API 请求次数，不是积分余额。即使该值为 `0`、`8` 或其他较小数字，也禁止解释为“剩余积分”或提示充值。\r\n- `meta.credits_remaining` 才表示真实 OpenAPI 积分余额；字段缺失或值为 `-1` 时，不要自行估算余额。\r\n- `meta.credits_consumed` 只表示本次请求消耗的积分。\r\n- 请求成功时，不要因为任何 quota 数值主动发布“积分余额不足提醒”。\r\n- 只有收到 `40201` 后，才停止后续付费调用并提示用户充值或调整任务规模。\r\n\r\n## References\r\n\r\n- [API Reference](references/api-reference.md)\r\n- [Platform Parameters](references/platform-params.md)\r\n- [Industry Categories](references/industry-categories.md)\r\n- [Country Codes](references/country-codes.md)\r\n- [Language Codes](references/language-codes.md)\r\n- [Error Codes](references/error-codes.md)\n\nFile v1.0.8:workflow/SKILL.md\n\n---\r\nname: workflow\r\ndescription: |\r\n  工作流编排层，通过剧本式步骤描述实现 AI 自主调度底层子 skill 能力。支持批量建联、战役闭环等复合流程编排。\r\n  Use when: 工作流, 流程编排, 批量建联流程, workflow orchestration, campaign flow, batch outreach flow\r\ncompatibility: Node.js 20.6+\r\nmetadata:\r\n  layer: workflow\r\n  parent: creator-scraper-cv\r\n---\r\n\r\n# Workflow Orchestration（工作流编排）\r\n\r\n## 概述\r\n\r\n工作流编排层，将底层子 skill 的原子能力组合为端到端的复合流程，通过剧本式步骤描述实现 AI 自主调度。\r\n\r\n## 脚本引用\r\n\r\n本层不直接引用脚本。工作流编排通过调度子 skill 间接使用底层脚本能力：\r\n\r\n| 层级 | 说明 |\r\n|------|------|\r\n| workflow 层 | 定义步骤序列与数据流转，不持有脚本 |\r\n| 子 skill 层 | 每个步骤调用对应子 skill，由子 skill 持有并执行脚本 |\r\n\r\n路径示例：`workflow 步骤 → discovery/creator-search → ../../scripts/search_creators.mjs`\r\n\r\n## 参数说明\r\n\r\n本层不直接调用脚本参数，通过编排子 skill 间接使用。各步骤的具体参数由对应子 skill 定义，工作流层仅负责步骤编排与数据流转。\r\n\r\n## 编排层定位\r\n\r\n### 设计理念\r\n\r\n1. **剧本式编排**：每个工作流是一个 Markdown 剧本文件（位于 `workflows/` 目录），定义步骤序列、数据流转和决策点。AI Agent 按剧本逐步执行，无需额外编程。\r\n\r\n2. **AI 自主调度**：AI Agent 读取剧本后，按步骤顺序调用对应子 skill 的能力。每步的产出自动作为下一步的输入，形成数据管道。\r\n\r\n3. **用户确认点**：关键决策步骤（如发送邮件、批量操作）标注 `[需用户确认]`，AI 暂停执行并展示当前数据，等待用户明确授权后继续。\r\n\r\n### 适用场景\r\n\r\n- 用户提出跨领域的复合需求（如\"找达人并发建联邮件\"）\r\n- 需要多步骤协作且有明确先后顺序的流程\r\n- 需要在关键节点获取用户决策的半自动化流程\r\n\r\n## 工作流索引\r\n\r\n| 剧本文件 | 描述 | 步骤数 |\r\n|---------|------|--------|\r\n| `workflows/batch-outreach.md` | 批量建联流程：从搜索到发送到跟进的 6 步闭环 | 6 |\r\n| `workflows/full-campaign.md` | 战役闭环流程：从发现到复盘的 ≥8 步完整链路 | ≥8 |\r\n\r\n## 调度规则\r\n\r\nAI Agent 执行工作流剧本时，遵循以下规则：\r\n\r\n### 执行规则\r\n\r\n1. **顺序执行**：按步骤编号顺序执行，每步调用标注的子 skill（格式 `[领域/子skill名]`）\r\n2. **数据传递**：步骤间数据通过上下文传递——上一步产出 = 下一步输入\r\n3. **错误中断**：任一步骤执行失败时，暂停流程并向用户报告错误原因及当前进度\r\n\r\n### 特殊标注处理\r\n\r\n| 标注 | AI 行为 |\r\n|------|---------|\r\n| `[需用户确认]` | 暂停执行，展示当前数据摘要，等待用户明确确认后继续 |\r\n| `🔮 待补` | 跳过该步骤，告知用户该能力尚未实现及预期归属领域 |\r\n| `[AI 辅助]` | AI 自主完成该步骤，无需调用子 skill 脚本 |\r\n\r\n### 上下文管理\r\n\r\n- 每步执行前，AI 汇总前序步骤的关键产出作为当前步骤输入\r\n- 用户确认步骤中，AI 展示结构化数据摘要（数量、关键字段预览）\r\n- 流程结束后，AI 输出完整执行报告\r\n\r\n## 输出格式\r\n\r\n工作流执行过程中，AI 按以下格式报告进度：\r\n\r\n```\r\n📋 工作流：{剧本名称}\r\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━\r\n✅ Step 1: {步骤描述} — 完成（产出: {摘要}）\r\n✅ Step 2: {步骤描述} — 完成（产出: {摘要}）\r\n⏳ Step 3: {步骤描述} — 执行中...\r\n⬚ Step 4: {步骤描述} — 待执行\r\n⬚ Step 5: {步骤描述} — 待执行\r\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━\r\n进度: 2/5 完成 | 当前: Step 3\r\n```\r\n\r\n流程完成后输出执行摘要：\r\n\r\n```\r\n✅ 工作流执行完成：{剧本名称}\r\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━\r\n总步骤: {N} | 成功: {N} | 跳过: {N}\r\n关键产出:\r\n  - {产出 1 摘要}\r\n  - {产出 2 摘要}\r\n```\n\nFile v1.0.8:_meta.json\n\n{\n  \"ownerId\": \"kn7dvhveaa0kchtkpq8xzbbq998585wp\",\n  \"slug\": \"cv-creator-scraper\",\n  \"version\": \"1.0.8\",\n  \"publishedAt\": 1780582784326\n}\n\nFile v1.0.8:references/api-reference.md\n\n# API Reference\r\n\r\n## Protocol\r\n\r\n| Item | Description |\r\n|------|-------------|\r\n| Base URL | `https://{host}/openapi/v1/` |\r\n| Protocol | HTTPS |\r\n| Method | All endpoints use **POST** |\r\n| Format | JSON (`Content-Type: application/json`) |\r\n| Auth | `X-API-Key` + `X-User-Identity` headers |\r\n| Encoding | UTF-8 |\r\n| Timestamps | ISO 8601 (e.g., `2026-03-15T10:30:00Z`) |\r\n| Pagination | `page` (starts at 1), `size` (default 50) |\r\n\r\n## Response Structure\r\n\r\n```json\r\n{\r\n  \"success\": true,\r\n  \"data\": { ... },\r\n  \"error\": null,\r\n  \"meta\": {\r\n    \"request_id\": \"req_abc123\",\r\n    \"page\": 1,\r\n    \"size\": 50,\n    \"total\": 1200,\n    \"quota_remaining\": -1,\n    \"credits_consumed\": 150,\n    \"credits_remaining\": 131500\n  }\n}\n```\n\n`meta.quota_remaining`: remaining daily API request quota. It is **not** a credits balance. `-1` means unlimited.\n`meta.service_level`: service level used for this search request (`S1`/`S2`/`S3`). Only present in search responses. Default is `S2`.\n`meta.credits_consumed`: credits deducted for this request. `0` means no charge.\n`meta.credits_remaining`: actual OpenAPI credits balance. `-1` means unlimited. This field may be absent from non-billed endpoints.\n`meta.total`: total matching records. For search endpoints, only returned when filter conditions > 2 (excluding `page`, `size`, `sort_field`, `sort_order`, `service_level`). Returns `null` when ≤ 2 filters.\n`meta.lang`: response translation language (`cn`/`en`). `null` when `lang` param not provided.\n\nNever report insufficient credits from `quota_remaining`. Only error code `40201` confirms insufficient credits.\n\r\n## Endpoints\r\n\r\n| Endpoint | Path | Description |\r\n|----------|------|-------------|\r\n| Search TikTok creators | `/openapi/v1/creators/tiktok/search` | Multi-dimensional filtering, supports `service_level` (S1/S2/S3) |\r\n| Search YouTube creators | `/openapi/v1/creators/youtube/search` | Multi-dimensional filtering, supports `service_level` (S1/S2/S3) |\r\n| Search Instagram creators | `/openapi/v1/creators/instagram/search` | Multi-dimensional filtering, supports `service_level` (S1/S2/S3) |\r\n| Submit collection task | `/openapi/v1/collection/tasks/submit` | Batch collect by links/usernames |\r\n| Submit keyword collection | `/openapi/v1/collection/tasks/keyword-submit` | Collect by keywords |\r\n| Query task status | `/openapi/v1/collection/tasks/status` | Check collection progress |\r\n| Get task data | `/openapi/v1/collection/tasks/data` | Paginated results |\r\n| Export task data | `/openapi/v1/collection/tasks/export` | Export to xlsx/csv/html file |\r\n| Get file download URL | `/openapi/v1/files/download-url` | Get temporary download URL |\r\n| Find similar creators | `/openapi/v1/creators/lookalike` | Lookalike search by username/URL, auto-resolves platform ID |\r\n\r\n## Task Types\r\n\r\n| task_type | Description | values content | Max items |\r\n|-----------|-------------|---------------|-----------|\r\n| `LINK_BATCH` | Link collection | Creator profile URLs | 500 |\r\n| `FILE_UPLOAD` | Username collection | Creator usernames | 500 |\r\n\r\n## Task Status\r\n\r\n| status | Description |\r\n|--------|-------------|\r\n| `processing` | In progress (collecting or importing data) |\r\n| `completed` | Completed |\r\n| `failed` | Failed |\r\n| `timeout` | Timed out |\r\n\r\n## Supported Platforms\r\n\r\n| Platform | ID | Search | Link Collection | Username Collection | Keyword Collection |\r\n|----------|----|--------|----------------|--------------------|--------------------|\r\n| TikTok | `tiktok` | ✅ | ✅ | ✅ | ✅ |\r\n| YouTube | `youtube` | ✅ | ✅ | ✅ | ✅ |\r\n| Instagram | `instagram` | ✅ | ✅ | ✅ | ✅ |\r\n\r\n## Search Response Fields by Service Level\r\n\r\n### TikTok\r\n\r\n| Field | Type | Level | Description |\r\n|-------|------|-------|-------------|\r\n| `uid` | string | S1 | Creator unique ID |\r\n| `username` | string | S1 | Username |\r\n| `nickname` | string | S1 | Nickname |\r\n| `avatar_url` | string | S1 | Avatar URL |\r\n| `profile_url` | string | S1 | Profile URL |\r\n| `followers_count` | integer | S1 | Followers count |\r\n| `likes_count` | integer | S1 | Likes count |\r\n| `video_count` | integer | S1 | Total videos |\r\n| `has_showcase` | boolean | S1 | Has showcase/store |\r\n| `has_email` | boolean | S1 | Has email |\r\n| `has_mcn` | boolean | S1 | Has MCN |\r\n| `has_line` | boolean | S1 | Has Line |\r\n| `has_zalo` | boolean | S1 | Has Zalo |\r\n| `last_video_publish_date` | string | S1 | Last video publish date (YYYY-MM-DD) |\r\n| `country_code` | string | S2 | Country/region code |\r\n| `gender` | string | S2 | Gender (translated when `lang` is set) |\r\n| `avg_views` | integer | S2 | Avg views of last 10 videos |\r\n| `engagement_rate` | number | S2 | Avg interaction rate of last 10 videos |\r\n| `views_per_follower` | number | S2 | Views per follower ratio |\r\n| `is_verified` | boolean | S2 | Whether verified |\r\n| `last10_video_views_per_sub` | number | S2 | Last 10 video views per subscriber |\r\n| `last10_med_video_views_cnt` | integer | S2 | Last 10 video views median |\r\n| `last10_med_video_views_per_sub` | number | S2 | Last 10 video views median per subscriber |\r\n| `product_categories` | string[] | S2 | Product categories |\r\n| `industry_categories` | array | S2 | Industry categories (primary/secondary/tertiary) |\r\n| `bio` | string | S2 | Bio / profile description |\r\n| `hashtags` | string[] | S2 | Hashtag list |\r\n| `language` | string | S2 | Language |\r\n| `email` | string | S2 | Email address |\r\n| `link_whatsapp` | string | S2 | WhatsApp link |\r\n| `link_line` | string | S2 | Line link |\r\n| `link_zalo` | string | S2 | Zalo link |\r\n| `mcn` | string | S2 | MCN agency |\r\n| `audience_female_rate` | number | S3 | Female audience ratio (percentage, e.g. 78.65 = 78.65%) |\r\n| `audience_country_code_list` | string[] | S3 | Audience country distribution |\r\n| `audience_language_code_list` | string[] | S3 | Audience language distribution |\r\n| `audience_age_id_list` | string[] | S3 | Audience age distribution (translated when `lang` is set) |\r\n\r\n### YouTube\r\n\r\n| Field | Type | Level | Description |\r\n|-------|------|-------|-------------|\r\n| `uid` | string | S1 | Creator unique ID |\r\n| `username` | string | S1 | Username |\r\n| `nickname` | string | S1 | Channel name |\r\n| `avatar_url` | string | S1 | Avatar URL |\r\n| `channel_url` | string | S1 | Channel URL |\r\n| `has_email` | boolean | S1 | Has email |\r\n| `has_whatsapp` | boolean | S1 | Has WhatsApp |\r\n| `last_video_publish_time` | string | S1 | Last video publish time (ISO 8601) |\r\n| `country_code` | string | S2 | Country/region code |\r\n| `language` | string | S2 | Language |\r\n| `gender` | string | S2 | Gender |\r\n| `bio` | string | S2 | Channel bio / description |\r\n| `followers_count` | integer | S2 | Subscribers count |\r\n| `video_count` | integer | S2 | Video count |\r\n| `view_count` | integer | S2 | Total views |\r\n| `avg_views` | integer | S2 | Avg views of last 10 videos (all) |\r\n| `avg_views_short` | integer | S2 | Avg views of last 10 short videos |\r\n| `avg_views_long` | integer | S2 | Avg views of last 10 long videos |\r\n| `engagement_rate` | number | S2 | Interaction rate of last 10 videos (all) |\r\n| `engagement_rate_short` | number | S2 | Interaction rate of last 10 short videos |\r\n| `engagement_rate_long` | number | S2 | Interaction rate of last 10 long videos |\r\n| `is_verified` | boolean | S2 | Whether verified |\r\n| `last10_video_views_per_sub` | number | S2 | Last 10 video views per subscriber (all) |\r\n| `last10_video_views_per_sub_short` | number | S2 | Last 10 short video views per subscriber |\r\n| `last10_video_views_per_sub_long` | number | S2 | Last 10 long video views per subscriber |\r\n| `last10_med_video_views_cnt` | integer | S2 | Last 10 video views median (all) |\r\n| `last10_med_video_views_cnt_short` | integer | S2 | Last 10 short video views median |\r\n| `last10_med_video_views_cnt_long` | integer | S2 | Last 10 long video views median |\r\n| `last10_med_video_views_per_sub` | number | S2 | Last 10 video views median per subscriber (all) |\r\n| `last10_med_video_views_per_sub_short` | number | S2 | Last 10 short video views median per subscriber |\r\n| `last10_med_video_views_per_sub_long` | number | S2 | Last 10 long video views median per subscriber |\r\n| `industry_categories` | array | S2 | Industry categories (primary/secondary/tertiary) |\r\n| `hashtags` | string[] | S2 | Hashtag list |\r\n| `email` | string | S2 | Email address |\r\n| `whatsapp` | string | S2 | WhatsApp |\r\n| `audience_female_rate` | number | S3 | Female audience ratio (percentage) |\r\n| `audience_country_code_list` | string[] | S3 | Audience country distribution |\r\n| `audience_language_list` | string[] | S3 | Audience language distribution |\r\n| `audience_age_list` | string[] | S3 | Audience age distribution (translated when `lang` is set) |\r\n\r\n### Instagram\r\n\r\n| Field | Type | Level | Description |\r\n|-------|------|-------|-------------|\r\n| `uid` | string | S1 | Creator unique ID |\r\n| `username` | string | S1 | Username |\r\n| `nickname` | string | S1 | Nickname |\r\n| `avatar_url` | string | S1 | Avatar URL |\r\n| `profile_url` | string | S1 | Profile URL |\r\n| `has_email` | boolean | S1 | Has email |\r\n| `has_whatsapp` | boolean | S1 | Has WhatsApp |\r\n| `last_video_publish_time` | string | S1 | Last post/video publish time |\r\n| `country_code` | string | S2 | Country/region code |\r\n| `language` | string | S2 | Language |\r\n| `gender` | string | S2 | Gender (translated when `lang` is set) |\r\n| `bio` | string | S2 | Bio / profile description |\r\n| `followers_count` | integer | S2 | Followers count |\r\n| `video_count` | integer | S2 | Posts/videos count |\r\n| `avg_views` | integer | S2 | Avg views of last 10 videos |\r\n| `engagement_rate` | number | S2 | Avg interaction rate of last 10 videos |\r\n| `is_verified` | boolean | S2 | Whether verified |\r\n| `last10_video_views_per_sub` | number | S2 | Last 10 video views per subscriber |\r\n| `last10_med_video_views_cnt` | integer | S2 | Last 10 video views median |\r\n| `last10_med_video_views_per_sub` | number | S2 | Last 10 video views median per subscriber |\r\n| `industry_categories` | array | S2 | Industry categories (primary/secondary/tertiary) |\r\n| `hashtags` | string[] | S2 | Hashtag list |\r\n| `email` | string | S2 | Email address |\r\n| `link_whatsapp` | string | S2 | WhatsApp |\r\n| `audience_female_rate` | number | S3 | Female audience ratio (percentage) |\r\n| `audience_country_code_list` | string[] | S3 | Audience country distribution |\r\n| `audience_language_code_list` | string[] | S3 | Audience language distribution |\r\n| `audience_age_id_list` | string[] | S3 | Audience age distribution (translated when `lang` is set) |\r\n\r\n### Lookalike\r\n\r\n| Field | Type | Description |\r\n|-------|------|-------------|\r\n| `uid` | string | Creator unique ID |\r\n| `username` | string / null | Username |\r\n| `nickname` | string / null | Nickname |\r\n| `avatar_url` | string / null | Avatar URL |\r\n| `profile_url` | string / null | Profile URL |\r\n| `country_code` | string / null | Country/region code |\r\n| `followers_count` | integer / null | Followers count |\r\n| `avg_views` | integer / null | Avg views of last 10 videos |\r\n| `engagement_rate` | number / null | Avg interaction rate of last 10 videos |\r\n| `match_score` | number / null | Similarity match score |\r\n\r\n## Export Formats\r\n\r\n| format | Description |\r\n|--------|-------------|\r\n| `xlsx` | Excel file with bold headers, background colors, auto column width |\r\n| `csv` | CSV file, UTF-8 BOM encoding (Excel compatible) |\r\n| `html` | HTML table page, viewable in browser |\r\n| `feishu_doc` | Feishu document (not yet available, returns 400) |\r\n\r\n## Export Response Fields\r\n\r\n| Field | Type | Description |\r\n|-------|------|-------------|\r\n| `file_id` | string | Unique file identifier (reusable via get_download_url) |\r\n| `file_name` | string | File name |\r\n| `file_url` | string | Authenticated temporary download URL |\r\n| `file_expire_at` | string | URL expiration time (ISO 8601 UTC) |\r\n| `format` | string | Export format |\r\n| `row_count` | integer | Number of data rows |\r\n\r\n## Webhook\r\n\r\nPass `webhook_url` when submitting collection tasks for completion notification.\r\n\r\nCallback payload:\r\n\r\n```json\r\n{\r\n  \"event\": \"collection.completed\",\r\n  \"task_id\": \"task_xxx\",\r\n  \"task_type\": \"LINK_BATCH\",\r\n  \"status\": \"completed\",\r\n  \"total\": 2,\r\n  \"completed\": 2,\r\n  \"failed\": 0,\r\n  \"timestamp\": \"2026-03-15T10:45:00Z\"\r\n}\r\n```\r\n\r\nSignature: `X-Webhook-Signature` header, HMAC-SHA256.\r\nRetry policy: max 3 attempts (10s → 30s → 90s).\n\nFile v1.0.8:references/country-codes.md\n\n# 国家代码映射表\r\n\r\n用户说中文国家名时，agent 需要转换为 ISO 3166-1 alpha-2 代码传给 API。\r\n\r\n## 常用国家（高频）\r\n\r\n| 代码 | 中文 | English |\r\n|------|------|---------|\r\n| US | 美国 | United States |\r\n| GB | 英国 | United Kingdom |\r\n| CA | 加拿大 | Canada |\r\n| AU | 澳大利亚 | Australia |\r\n| DE | 德国 | Germany |\r\n| FR | 法国 | France |\r\n| JP | 日本 | Japan |\r\n| KR | 韩国 | South Korea |\r\n| CN | 中国 | China |\r\n| HK | 香港 | Hong Kong |\r\n| TW | 台湾 | Taiwan |\r\n| SG | 新加坡 | Singapore |\r\n| MY | 马来西亚 | Malaysia |\r\n| TH | 泰国 | Thailand |\r\n| VN | 越南 | Vietnam |\r\n| ID | 印度尼西亚 | Indonesia |\r\n| PH | 菲律宾 | Philippines |\r\n| IN | 印度 | India |\r\n| BR | 巴西 | Brazil |\r\n| MX | 墨西哥 | Mexico |\r\n| SA | 沙特阿拉伯 | Saudi Arabia |\r\n| AE | 阿联酋 | United Arab Emirates |\r\n| RU | 俄罗斯 | Russia |\r\n| ES | 西班牙 | Spain |\r\n| IT | 意大利 | Italy |\r\n| NL | 荷兰 | Netherlands |\r\n| SE | 瑞典 | Sweden |\r\n| NO | 挪威 | Norway |\r\n| PL | 波兰 | Poland |\r\n| TR | 土耳其 | Turkey |\r\n| EG | 埃及 | Egypt |\r\n| NG | 尼日利亚 | Nigeria |\r\n| ZA | 南非 | South Africa |\r\n| KE | 肯尼亚 | Kenya |\r\n| AR | 阿根廷 | Argentina |\r\n| CO | 哥伦比亚 | Colombia |\r\n| CL | 智利 | Chile |\r\n| PE | 秘鲁 | Peru |\r\n| NZ | 新西兰 | New Zealand |\r\n| IE | 爱尔兰 | Ireland |\r\n| IL | 以色列 | Israel |\r\n| PK | 巴基斯坦 | Pakistan |\r\n| BD | 孟加拉 | Bangladesh |\r\n| KH | 柬埔寨 | Cambodia |\r\n| MM | 缅甸 | Myanmar |\r\n| LA | 老挝 | Laos |\r\n\r\n## 区域快捷映射\r\n\r\n用户说区域名称时，agent 应展开为对应的国家代码列表：\r\n\r\n| 用户说法 | 展开为 |\r\n|----------|--------|\r\n| 东南亚 | TH,VN,ID,PH,MY,SG,KH,MM,LA |\r\n| 欧洲 | GB,DE,FR,ES,IT,NL,SE,NO,PL,PT,IE,AT,CH,BE,DK,FI,GR,CZ,RO,HU |\r\n| 中东 | SA,AE,QA,KW,BH,OM,JO,IL,EG,IQ |\r\n| 拉美 / 南美 | BR,MX,AR,CO,CL,PE,EC,VE |\r\n| 北美 | US,CA |\r\n| 东亚 | JP,KR,CN,HK,TW |\r\n| 南亚 | IN,PK,BD,LK,NP |\r\n| 非洲 | NG,ZA,KE,EG,GH,ET,TZ |\r\n\r\n> 多国家搜索时用逗号分隔传入 `country_code` 参数，如 `US,CA,GB`\n\nFile v1.0.8:references/error-codes.md\n\n# Error Codes\r\n\r\n## Error Code Table\r\n\r\n| Code | HTTP | Description | Action |\r\n|------|------|-------------|--------|\r\n| 40001 | 400 | Invalid parameters | Check JSON format, field names, value ranges |\r\n| 40101 | 401 | Invalid API Key | Verify `CV_API_KEY` environment variable |\r\n| 40102 | 401 | API Key expired | Contact admin to renew or regenerate |\r\n| 40103 | 401 | API Key revoked | Contact admin |\r\n| 40104 | 401 | Missing X-User-Identity | Verify `CV_USER_IDENTITY` environment variable |\r\n| 40201 | 402 | Insufficient credits | Top up or upgrade plan |\r\n| 40301 | 403 | No permission for endpoint | Check API Key scopes |\r\n| 42901 | 429 | Rate limit exceeded | Script auto-retries; wait for Retry-After header |\r\n| 42902 | 402 | Daily quota exhausted | Wait until UTC 00:00 reset or upgrade plan |\r\n| 50001 | 500 | Server error | Record request_id, contact support |\r\n\r\n## Export-Specific Errors\r\n\r\n| Scenario | HTTP | Description |\r\n|----------|------|-------------|\r\n| Unsupported format (e.g., `feishu_doc`) | 400 | Format not yet supported |\r\n| Task not found or not owned by tenant | 404 | Task not found |\r\n| Task has no data to export | 404 | No data available for export |\r\n| OSS upload / DB insert / signing failed | 500 | Export failed |\r\n\r\n## Troubleshooting\r\n\r\n### Environment variables not set\r\n\r\n```\r\nError: CV_API_KEY environment variable is not set\r\n```\r\n\r\n**Fix**: Set environment variables and restart terminal/IDE.\r\n\r\n### API Key format\r\n\r\nValid format: `cv_live_` prefix + random string, e.g., `cv_live_Y8nil_BsKAbITdqj...`\r\n\r\n### Rate limiting\r\n\r\n- Default limit: 60 requests/minute (per tenant)\r\n- Script auto-retries up to 3 times on 429\r\n- `Retry-After` response header indicates wait time in seconds\r\n\r\n### Daily quota\n\n- Resets at UTC 00:00 daily\n- `meta.quota_remaining` shows remaining daily API request count, not credits\n- `-1` means unlimited\n- Do not display a credits warning based on `quota_remaining`\n\n### Insufficient credits\n\n- Only error code `40201` confirms insufficient credits\n- `meta.credits_remaining` is the actual OpenAPI credits balance when present\n- A successful response must never be converted into an insufficient-credits warning\n\n### Collection task timeout\n\r\n- Collection tasks are async, typically 5~30 minutes\r\n- Recommended poll interval: 60 seconds\r\n- Status `timeout` means the task timed out; try resubmitting\r\n\r\n### Permission denied\r\n\r\nAPI Key `scopes` field controls endpoint access:\r\n- `[\"*\"]` — full access\r\n- `[\"collection:submit\"]` — link/username collection only\r\n- `[\"collection:keyword-submit\"]` — keyword collection only\r\n- `[\"collection:export\"]` — export only\r\n- `[\"file:download\"]` — file download only\n\nFile v1.0.8:references/industry-categories.md\n\n# 行业类目映射表\r\n\r\n**所有平台统一使用三级数字类目 ID。ID 位数随所属一级类目变化，当前可能为 7 位或 8 位。**\n\r\n- 所有平台统一使用 `industry` 参数传三级 ID（逗号分隔）\r\n\r\n用户输入中文/英文类目名时，skill 会自动转换为对应的三级 ID 传给 API。\r\n\r\n## 一级类目总览\r\n\r\n| ID | 英文 | 中文 |\r\n|----|------|------|\r\n| 19 | Games | 游戏 |\r\n| 25 | Beauty & Personal Care | 美妆与个人护理 |\r\n| 16 | Clothing & Fashion | 服装与时尚 |\r\n| 3 | Healthcare | 医疗保健 |\r\n| 12 | Outdoor & Sports | 户外与运动 |\r\n| 26 | Food & Beverages | 美食与饮品 |\r\n| 24 | Technology & Electronics | 科技数码 |\r\n| 15 | Travel & Lifestyle | 旅行与生活方式 |\r\n| 28 | Art | 艺术 |\r\n| 5 | Entertainment | 娱乐 |\r\n| 9 | Pets | 宠物 |\r\n| 1 | Parenting & Family | 亲子与家庭 |\r\n| 17 | Automotive & Transportation | 汽车与交通 |\r\n| 10 | Home & Living | 家居 |\r\n| 20 | Toys | 玩具 |\r\n| 30 | Software | 软件 |\r\n| 29 | Finance | 财经 |\r\n| 4 | Books | 图书 |\r\n| 6 | Learning & Education | 学习与教育 |\r\n| 27 | Career Development | 职业发展 |\r\n| 11 | Architecture | 建筑 |\r\n| 23 | Science | 科学 |\r\n| 14 | Culture & Customs | 文化与习俗 |\r\n| 8 | Religion & Beliefs | 宗教与信仰 |\r\n| 22 | Social Welfare | 社会公益 |\r\n| 21 | Environmental Protection | 环保 |\r\n| 2 | Agriculture & Rural Areas | 农业与乡村 |\r\n| 7 | Safety & Emergency | 安全与应急 |\r\n| 13 | Politics | 政治 |\r\n| 18 | Rule of Law | 法治 |\r\n\r\n## 快速查询：常用三级类目 ID\r\n\r\n| 中文 | 英文 | 三级 ID |\r\n|------|------|---------|\r\n| 护肤 | Skincare | 25009001 |\r\n| 面部彩妆 | Facial Makeup | 25006004 |\r\n| 眼妆 | Eye Makeup | 25006003 |\r\n| 唇妆 | Lip Makeup | 25006002 |\r\n| 美甲 | Nail Art & Tools | 25012001 |\r\n| 女装 | Women's Clothing | 16002001 |\r\n| 男装 | Men's Clothing | 16003001 |\r\n| 童装 | Kids' Clothing | 16004001 |\r\n| 鞋履 | Footwear | 16001001 |\r\n| 手机 | Mobile Phones | 24001001 |\r\n| 电脑 | Computers | 24002001 |\r\n| 相机 | Photography & Video Equipment | 24003001 |\r\n| 耳机 | Headphones | 24006001 |\r\n| 健身 | Aerobic Training | 12001001 |\r\n| 篮球 | Basketball | 12002001 |\r\n| 足球 | Football | 12002002 |\r\n| 跑步 | Running | 12003001 |\r\n| 游戏 | Shooter | 19006001 |\r\n| 美食 | Food | 26001001 |\r\n| 咖啡 | Coffee | 26002001 |\r\n| 旅行 | Travel Guides | 15001001 |\r\n\r\n## 二级 & 三级类目明细\r\n\r\n### Games 游戏\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| Shooter | Shooter | 射击类 |\r\n| MOBA | MOBA | MOBA类 |\r\n| Strategy & Battle | PvP / Strategy Survival / Card Battle | 策略对战类 |\r\n| Sports & Racing | Sports / Racing | 体育竞速类 |\r\n| Action | Fighting / Action Adventure / Platformer | 动作类 |\r\n| Role-Playing | RPG / Open World / MMORPG | 角色扮演类 |\r\n| Simulation & Management | Simulation & Management | 模拟经营类 |\r\n| Casual & Social | Puzzle & Casual / Party & Social | 休闲社交类 |\r\n| Rhythm | Rhythm | 音乐节奏类 |\r\n| Horror & Mystery | Horror & Mystery | 恐怖悬疑类 |\r\n| Anime | Anime | 二次元类 |\r\n| Text Adventure | Text Adventure | 文字冒险类 |\r\n| Sandbox | Sandbox | 沙盒类 |\r\n| Gaming Equipment | Gaming Equipment | 游戏设备 |\r\n\r\n### Beauty & Personal Care 美妆与个人护理\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| Makeup | Facial Makeup / Eye Makeup / Lip Makeup | 彩妆 |\r\n| Tattoo | Tattoo | 纹身 |\r\n| Nail Art & Tools | Nail Art & Tools | 美甲及工具 |\r\n| Makeup Tools & Accessories | Makeup Tools & Accessories | 化妆工具和配件 |\r\n| Wigs | Wigs | 假发 |\r\n| Skincare | Skincare | 护肤 |\r\n| Hair Care | Hair Care | 护发 |\r\n| Oral Care | Oral Care | 口腔护理 |\r\n| Body Care | Body Care | 身体护理 |\r\n| Beauty Devices & Accessories | Beauty Devices & Accessories | 护理仪器和配件 |\r\n| Feminine Care | Feminine Care | 女性护理 |\r\n| Men's Care | Men's Care | 男性护理 |\r\n| Adult Products | Adult Products | 两性用品 |\r\n| Perfume | Perfume | 香水 |\r\n\r\n### Clothing & Fashion 服装与时尚\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| Women's Clothing | Women's Clothing | 女装 |\r\n| Men's Clothing | Men's Clothing | 男装 |\r\n| Kids' Clothing | Kids' Clothing | 童装 |\r\n| Footwear | Footwear | 鞋履 |\r\n| Bags & Luggage | Bags & Luggage | 箱包 |\r\n| Jewelry | Jewelry | 首饰 |\r\n| Accessories | Watches / Sunglasses / Belts / Hats / Ties / Hair Accessories / Scarves | 配饰 |\r\n| Occasion Wear | Workplace & Business / Daily Casual / Sports / Travel & Dating / Weddings & Banquets / Campus / Niche Hobbies | 场景着装 |\r\n\r\n### Outdoor & Sports 户外与运动\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| Fitness | Aerobic Training / Strength Training / Healthy Recipes / Fitness Equipment / Yoga & Pilates | 健身 |\r\n| Ball Sports | Basketball / Football / Volleyball / Tennis / Table Tennis / Badminton / Baseball / Rugby / Hockey / Golf | 球类运动 |\r\n| Running | Running | 跑步 |\r\n| Water Sports | Swimming / Diving / Rowing & Boating | 水上运动 |\r\n| Ice & Snow Sports | Skiing / Skating | 冰雪运动 |\r\n| Cycling | Cycling | 骑行 |\r\n| Combat & Martial Arts | Combat & Martial Arts | 格斗与武术 |\r\n| Camping & Gear | Camping & Gear | 露营与装备 |\r\n| Hiking & Mountaineering | Hiking & Mountaineering | 徒步与登山 |\r\n| Extreme Sports | Surfing / Rock Climbing / Skateboarding | 极限运动 |\r\n\r\n### Food & Beverages 美食与饮品\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| Food | Food | 食物 |\r\n| Beverages | Coffee / Tea Drinks / Alcoholic Drinks | 饮品 |\r\n| Cooking | Cooking | 烹饪 |\r\n| Food Exploration & Reviews | Food Exploration & Reviews | 探店与测评 |\r\n| Food Live Streaming | Food Live Streaming | 吃播 |\r\n\r\n### Technology & Electronics 科技数码\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| Electronics | Mobile Phones / Computers / Photography & Video Equipment / VR & AR / Smart Watches & Bands / Headphones | 数码产品 |\r\n| Digital Accessories | Mobile Phone Accessories / Computer Accessories | 数码产品配件 |\r\n| Technology News | Technology News | 科技资讯 |\r\n\r\n### Travel & Lifestyle 旅行与生活方式\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| Travel | Travel Guides / Hotel Experiences / Natural Scenery / Cultural Experiences | 旅行 |\r\n| Lifestyle | Lifestyle | 生活方式 |\r\n\r\n### Art 艺术\r\n\r\n| 二级 | 中文 |\r\n|------|------|\r\n| Music | 音乐 |\r\n| Dance | 舞蹈 |\r\n| Crafts & Handmade | 工艺与手作 |\r\n| Painting | 绘画 |\r\n\r\n### Entertainment 娱乐\r\n\r\n| 二级 | 中文 |\r\n|------|------|\r\n| Film & TV Editing & Commentary | 影视剪辑与解说 |\r\n| Variety Shows & Reality TV | 综艺与真人秀 |\r\n| Celebrity News | 明星与艺人资讯 |\r\n| Comics & Animation | 漫画与动画 |\r\n| Comedy & Humor | 幽默搞笑类 |\r\n| Cosplay | 角色扮演 |\r\n\r\n### Pets 宠物\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| Pet Supplies | Pet Food / Pet Lifestyle Products / Pet Toys | 宠物用品 |\r\n| Pet Entertainment | Pet Entertainment | 宠物娱乐 |\r\n\r\n### Parenting & Family 亲子与家庭\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| Family Daily Life | Parent-Child Interaction / Couple Interaction | 家庭日常 |\r\n| Maternity & Baby Products | Maternal Products / Baby Products | 母婴产品 |\r\n\r\n### Automotive & Transportation 汽车与交通\r\n\r\n| 二级 | 中文 |\r\n|------|------|\r\n| Automobiles | 汽车 |\r\n| Motorcycles | 摩托车 |\r\n| Car Maintenance | 汽车养护 |\r\n| In-Vehicle Products | 车载产品 |\r\n| Auto Parts (Car Parts / Motorcycle Parts) | 配件 |\r\n| Car Modification | 改装 |\r\n| Self-Driving Travel | 自驾游 |\r\n\r\n### Home & Living 家居\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| Furniture | Furniture | 家具 |\r\n| Home Decoration | Home Decoration | 家居装饰 |\r\n| Home Appliances | Kitchen Appliances / Bathroom Appliances / Household Appliances / Lighting Fixtures / Audio-Visual & Entertainment | 家用电器 |\r\n| Bedding | Bedding | 床上用品 |\r\n| Home Textiles | Home Textiles | 居家布艺 |\r\n| Daily Necessities | Daily Necessities | 生活日用 |\r\n| Kitchen & Tableware | Kitchen & Tableware | 厨房与餐厨用品 |\r\n| Bathroom Supplies | Bathroom Supplies | 卫浴 |\r\n| Home Cleaning | Home Cleaning | 家居清洁 |\r\n| Home Storage & Organization | Home Storage & Organization | 家居收纳与整理 |\r\n| Room Renovation | Room Renovation | 房间改造 |\r\n| Gardening & Plants | Gardening & Plants | 园艺绿植 |\r\n\r\n### Toys 玩具\r\n\r\n| 二级 | 中文 |\r\n|------|------|\r\n| Children's Toys | 儿童玩具 |\r\n| Adult Art Toys | 成人潮玩 |\r\n| Building Block Toys | 积木玩具 |\r\n| Educational Toys | 益智玩具 |\r\n| Model Toys | 模型玩具 |\r\n\r\n### Software 软件\r\n\r\n| 二级 | 三级 | 中文 |\r\n|------|------|------|\r\n| AI | AI | AI |\r\n| Mobile Apps | Social / Music / Video & Live Streaming / Learning / Tools / Shopping / Fitness / Finance | 应用程序 |\r\n| Web3 | NFT / Cryptocurrency / Decentralized Finance | Web3 |\r\n\r\n## 使用说明\r\n\r\n### 所有平台统一规则\r\n\r\n**所有平台参数名**：`industry`\r\n\r\n**传值格式**：所有平台统一传**三级数字类目 ID**，逗号分隔。不要依赖固定长度判断层级，应以完整行业树中的真实节点关系为准。\n\r\n**映射规则**：\r\n- 用户说\"美妆\" → 查找一级类目 `Beauty & Personal Care` (ID: 25) → 获取所有三级 ID → 传 `25006004,25006003,25006002,25006001,25011001,25012001,25003001,25002001,25009001,25007001,25004001,25013001,25008001,25005001,25010001,25001001,25014001`\r\n- 用户说\"护肤\" → 查找三级类目 `Skincare` → 传 `25009001`\r\n- 用户说\"手机\" → 查找三级类目 `Mobile Phones` → 传 `24001001`\n- 用户说\"Comedy\" / \"Comedy & Humor\" → 查找三级类目 `Comedy & Humor` → 传 `5001001`\n- 用户说\"Entertainment\" → 查找一级类目 `Entertainment` (ID: 5) → 展开并传所有三级子类目 ID\n\r\n**示例**：\r\n\r\n```json\r\n// TikTok / YouTube / Instagram — 所有平台统一使用 \"industry\" 参数\r\n{\r\n  \"platform\": \"tiktok\",\r\n  \"industry\": \"25009001,25006004\"\r\n}\r\n\r\n// YouTube\r\n{\r\n  \"platform\": \"youtube\",\r\n  \"industry\": \"25009001,25006004\"\r\n}\r\n\r\n// Instagram\r\n{\r\n  \"platform\": \"instagram\",\r\n  \"industry\": \"25009001,25006004\"\r\n}\r\n```\r\n\r\n### 映射逻辑总结\r\n\r\n| 用户输入 | 所有平台参数值 |\r\n|---------|---------------|\r\n| 美妆（一级） | 所有三级 ID（如 `25009001,25006004,...`） |\r\n| 护肤（三级） | 三级 ID（`25009001`） |\r\n| 手机（三级） | 三级 ID（`24001001`） |\n\nFile v1.0.8:references/language-codes.md\n\n# 语言代码映射表\r\n\r\n用户说中文语言名时，agent 需要转换为 ISO 639-1 代码传给 API 的 `language_code` 参数。\r\n\r\n## 常用语言\r\n\r\n| 代码 | 中文 | English |\r\n|------|------|---------|\r\n| en | 英语 | English |\r\n| zh | 中文 | Chinese |\r\n| es | 西班牙语 | Spanish |\r\n| fr | 法语 | French |\r\n| de | 德语 | German |\r\n| ja | 日语 | Japanese |\r\n| ko | 韩语 | Korean |\r\n| pt | 葡萄牙语 | Portuguese |\r\n| ru | 俄语 | Russian |\r\n| ar | 阿拉伯语 | Arabic |\r\n| hi | 印地语 | Hindi |\r\n| it | 意大利语 | Italian |\r\n| nl | 荷兰语 | Dutch |\r\n| sv | 瑞典语 | Swedish |\r\n| no | 挪威语 | Norwegian |\r\n| da | 丹麦语 | Danish |\r\n| fi | 芬兰语 | Finnish |\r\n| pl | 波兰语 | Polish |\r\n| tr | 土耳其语 | Turkish |\r\n| th | 泰语 | Thai |\r\n| vi | 越南语 | Vietnamese |\r\n| id | 印度尼西亚语 | Indonesian |\r\n| ms | 马来语 | Malay |\r\n| tl | 他加禄语 | Tagalog |\r\n| uk | 乌克兰语 | Ukrainian |\r\n| el | 希腊语 | Greek |\r\n| cs | 捷克语 | Czech |\r\n| ro | 罗马尼亚语 | Romanian |\r\n| hu | 匈牙利语 | Hungarian |\r\n| he | 希伯来语 | Hebrew |\r\n| bn | 孟加拉语 | Bengali |\r\n| ur | 乌尔都语 | Urdu |\r\n| sw | 斯瓦希里语 | Swahili |\r\n| km | 高棉语 | Khmer |\r\n| my | 缅甸语 | Burmese |\r\n| lo | 老挝语 | Lao |\r\n\r\n> 多语言搜索时用逗号分隔传入，如 `en,zh`\n\nArchive v1.0.7: 26 files, 47728 bytes\n\nFiles: references/api-reference.md (11850b), references/country-codes.md (2079b), references/error-codes.md (2314b), references/industry-categories.md (10118b), references/language-codes.md (1327b), references/platform-params.md (15185b), scripts/_api_client.mjs (5737b), scripts/_industry_mapper.mjs (19526b), scripts/export_task_data.mjs (1085b), scripts/export_to_csv.mjs (4008b), scripts/find_lookalike.mjs (925b), scripts/get_download_url.mjs (624b), scripts/get_task_data.mjs (505b), scripts/get_task_status.mjs (441b), scripts/langfuse/test_cases.json (5403b), scripts/outreach_contact.mjs (671b), scripts/outreach_send.mjs (1711b), scripts/outreach_task.mjs (2484b), scripts/outreach_todo.mjs (574b), scripts/poll_task_status.mjs (1984b), scripts/search_creators.mjs (852b), scripts/submit_collection_task.mjs (1282b), scripts/submit_keyword_task.mjs (834b), skill-card.md (2674b), SKILL.md (37312b), _meta.json (137b)\n\nFile v1.0.7:SKILL.md\n\n---\r\nname: creator-scraper-cv\r\ndescription: |\r\n  Creativault creator data collection and outreach skill. Search and collect creator/influencer\r\n  data from TikTok, YouTube, and Instagram. Send outreach emails to discovered creators with\r\n  automatic conversation management, batch sending, and follow-up tracking.\r\n  Supports multi-dimensional search, similar/lookalike creator discovery, batch collection by\r\n  links/usernames/keywords, task tracking, data export (xlsx/csv/html), and email outreach\r\n  (single/batch send, templates, smart timing, metrics).\r\n  Use when: creator search, influencer scraping, KOL search, KOL analytics, social media\r\n  data extraction, TikTok scraper, YouTube scraper, Instagram scraper, influencer discovery,\r\n  similar creators, lookalike, outreach, email outreach, send email to creator, batch email,\r\n  follow-up, 达人采集, KOL 搜索, 网红数据, 达人分析, 达人搜索, 相似达人, 社交媒体数据, 建联, 发邮件, 批量发送.\r\ncompatibility: Node.js 20.6+\r\nmetadata:\r\n  author: creativault\r\n  version: \"1.5.0\"\r\n---\r\n\r\n# Creativault Creator Data Collection\r\n\r\n## Prerequisites\r\n\r\nSet the following environment variables:\r\n\r\n- `CV_API_KEY` — Creativault Open API Key (obtain from admin dashboard)\r\n- `CV_USER_IDENTITY` — Operator email address\r\n- `CV_API_BASE_URL` (optional) — API base URL, defaults to `http://api.creativault.vip`\r\n\r\n**Linux / macOS**:\r\n\r\n```bash\r\nexport CV_API_KEY=cv_live_your_key_here\r\nexport CV_USER_IDENTITY=your_email@example.com\r\n```\r\n\r\n**Windows PowerShell**:\r\n\r\n```powershell\r\n$env:CV_API_KEY = \"cv_live_your_key_here\"\r\n$env:CV_USER_IDENTITY = \"your_email@example.com\"\r\n```\r\n\r\n## Capabilities\r\n\r\n| Capability | Script | Mode |\r\n|------------|--------|------|\r\n| Search creators | `scripts/search_creators.mjs` | Sync, real-time |\r\n| Submit collection task | `scripts/submit_collection_task.mjs` | Async, returns task_id |\r\n| Submit keyword collection | `scripts/submit_keyword_task.mjs` | Async, returns task_id |\r\n| Check task status | `scripts/get_task_status.mjs` | Sync, single query |\r\n| Poll task status | `scripts/poll_task_status.mjs` | Auto-poll every 60s |\r\n| Get collection data | `scripts/get_task_data.mjs` | Sync, paginated |\r\n| Export task data (server) | `scripts/export_task_data.mjs` | Returns file download URL |\r\n| Export to local CSV | `scripts/export_to_csv.mjs` | Pipe input, incremental append |\r\n| Get file download URL | `scripts/get_download_url.mjs` | Sync |\r\n| Find similar creators | `scripts/find_lookalike.mjs` | Sync, auto-resolves username/URL |\r\n| Send outreach email | `scripts/outreach_send.mjs` | Async, returns task_id |\r\n| Query outreach task | `scripts/outreach_task.mjs` | Sync or auto-poll |\r\n| Query creator contact | `scripts/outreach_contact.mjs` | Sync |\r\n| Get follow-up todos | `scripts/outreach_todo.mjs` | Sync |\r\n| Get outreach metrics | `scripts/outreach_metrics.mjs` | Sync |\r\n| Get outreach config | `scripts/outreach_config.mjs` | Sync |\r\n| Upload attachment | `scripts/outreach_upload.mjs` | Sync |\r\n\r\nAll scripts accept a JSON string as command-line argument. Results are output as JSON to stdout.\r\n\r\n**Language**: Always respond to the user in the same language they use. If the user writes in Chinese, respond in Chinese. If in English, respond in English.\r\n\r\n## Choosing the Right Approach\r\n\r\nBefore executing, determine the best approach based on user intent:\r\n\r\n| User Intent | Approach | Response Time |\r\n|-------------|----------|---------------|\r\n| \"Search/find creators\" with filters (keyword, country, followers) | `search_creators.mjs` | Instant (~1s) |\r\n| \"Find similar/lookalike creators\" given a profile link or username | `find_lookalike.mjs` | Instant (~2s) |\r\n| \"Collect/scrape data\" for specific creators (links or usernames) | `submit_collection_task.mjs` → poll → get data | 5~30 minutes |\r\n| \"Find creators by keyword\" and collect detailed data | `submit_keyword_task.mjs` → poll → get data | 5~30 minutes |\r\n| \"Send email to creator\" / \"reach out\" / \"建联\" | `outreach_send.mjs` → poll status | 3~10 seconds |\r\n| \"Batch send emails\" to a list of creators | `outreach_batch_send.mjs` → poll status | 1~5 minutes |\r\n| \"Who needs follow-up?\" / \"待办\" | `outreach_todo.mjs` | Instant |\r\n| \"How are my campaigns doing?\" / \"效果\" | `outreach_metrics.mjs` | Instant |\r\n| \"What did I discuss with X?\" / \"沟通历史\" | `outreach_history.mjs` | Instant |\r\n\r\n**Decision rules:**\r\n- If the user gives filter conditions (keyword, country, follower count) → use **search** first. It returns results instantly.\r\n- If the user gives a specific creator link/username and asks for \"similar\"/\"lookalike\"/\"相似达人\" → use **lookalike** directly (no resolve needed).\r\n- If the user gives specific profile links or usernames → use **collection** (async).\r\n- If search results satisfy the user's needs → no need to submit a collection task.\r\n- Only use collection when the user explicitly needs detailed/enriched data for specific creators.\r\n- **When the user's goal is to send emails / outreach / 建联, recommend adding `has_email: true`** to avoid returning creators without contact info. If the user didn't specify, ask: \"是否只筛选有邮箱的达人？\"\r\n- **`lang` parameter only controls response display language (cn/en), it does NOT filter creators by their language.** Use `language_code` parameter to filter creators by their content language (e.g., `language_code: \"zh\"` for Chinese-speaking creators).\r\n- **After any collection task completes, ALWAYS call `export_task_data.mjs` to generate a downloadable file (default xlsx) and present the download link to the user. Do NOT just call `get_task_data.mjs` and show raw JSON.**\r\n\r\n### Service Level Selection\r\n\r\nUsers may not know what S1/S2/S3 means. The agent MUST ask the user to confirm the service level before executing a search. Never auto-select silently.\r\n\r\n**Service level reference (show to user when asking):**\r\n\r\n| 等级 | 名称 | 返回内容 | 积分/条 |\r\n|------|------|----------|---------|\r\n| S1 | 纯名单筛选 | 基础信息（用户名、昵称、头像、粉丝数、主页链接） | 1 |\r\n| S2 | 精准触达 | S1 + 国家、性别、互动率、平均播放、均播/粉丝比、认证状态、带货类目、达人领域、bio、hashtags、邮箱标识、语言 | 3 |\r\n| S3 | 深度画像 | S2 + 受众女性比例、受众国家分布、受众语言分布、受众年龄分布 | 4 |\r\n\r\n**Rules:**\r\n- If user does NOT specify a service level → show the table above and ask: \"请选择服务等级：S1（基础名单，1积分/条）、S2（精准触达，3积分/条）、S3（深度画像，4积分/条）？\"\r\n- If user explicitly says \"S1\"/\"S2\"/\"S3\" or \"深度画像\"/\"精准触达\"/\"名单\" → use as specified, no need to ask again\r\n- If user has already chosen a level in the current conversation → reuse that level for subsequent searches unless they say otherwise\r\n- **ALWAYS show the service level and credits consumed in the stats section after search results**\r\n- After showing results, display: \"本次使用 S2（精准触达）等级，消耗 60 积分，剩余配额 xxx\"\r\n\r\n## Output Formatting\r\n\r\n展示搜索或采集结果时，使用以下分区格式。字段要展示齐全，表格要对齐整齐。\r\n\r\n### TikTok 输出模板\r\n\r\n```\r\n✅ 搜索成功！找到 N 个 [国家] [平台] [关键词]达人\r\n\r\n📊 采集结果\r\n\r\n| #   | 用户名      | 昵称        | 粉丝数  | 获赞数   | 平均播放 | 互动率  | 国家 | 主页链接          |\r\n| --- | ----------- | ----------- | ------- | -------- | -------- | ------- | ---- | ----------------- |\r\n| 1   | username1   | Nickname1   | 33.1K   | 95.5万   | 1.2万    | 6.50%   | US   | [查看][link1]     |\r\n| 2   | username2   | Nickname2   | 59.2K   | 146.0万  | 3.8万    | 3.75%   | US   | [查看][link2]     |\r\n\r\n[link1]: https://www.tiktok.com/@username1\r\n[link2]: https://www.tiktok.com/@username2\r\n\r\n📈 统计信息\r\n• 总匹配数：12,652 个达人\r\n• 服务等级：S2（精准触达）\r\n• 本次消耗：60 积分\r\n• 剩余配额：992 次\r\n• 请求ID：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\r\n```\r\n\r\n### YouTube 输出模板\r\n\r\n```\r\n| #   | 用户名      | 频道名      | 订阅数  | 总观看    | 平均播放 | 互动率  | 国家 | 频道链接          |\r\n| --- | ----------- | ----------- | ------- | --------- | -------- | ------- | ---- | ----------------- |\r\n| 1   | username1   | Channel1    | 120K    | 5,200万   | 8.5万    | 4.20%   | US   | [查看][link1]     |\r\n```\r\n\r\n### Instagram 输出模板\r\n\r\n```\r\n| #   | 用户名      | 昵称        | 粉丝数  | 帖子数   | 平均播放 | 互动率  | 国家 | 主页链接          |\r\n| --- | ----------- | ----------- | ------- | -------- | -------- | ------- | ---- | ----------------- |\r\n| 1   | username1   | Nickname1   | 85.3K   | 342      | 2.1万    | 5.30%   | US   | [查看][link1]     |\r\n```\r\n\r\n### 相似达人输出模板\r\n\r\n```\r\n🔍 找到 N 个与 @seed_username 相似的达人\r\n\r\n📊 相似达人列表\r\n\r\n| #   | 用户名      | 昵称        | 粉丝数  | 平均播放 | 互动率  | 相似度  | 国家 | 主页链接          |\r\n| --- | ----------- | ----------- | ------- | -------- | ------- | ------ | ---- | ----------------- |\r\n| 1   | username1   | Nickname1   | 120K    | 3.8万    | 7.20%   | 85.0%  | US   | [查看][link1]     |\r\n| 2   | username2   | Nickname2   | 95.5K   | 2.1万    | 5.50%   | 78.3%  | US   | [查看][link2]     |\r\n\r\n[link1]: https://www.tiktok.com/@username1\r\n[link2]: https://www.tiktok.com/@username2\r\n\r\n📈 统计信息\r\n• 种子达人：@seed_username（平台ID：7123456789）\r\n• 结果总数：N 个相似达人\r\n• 本次消耗：10 积分\r\n• 剩余配额：xxx 次\r\n• 请求ID：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\r\n```\r\n\r\n### 格式规则\r\n\r\n- **分区结构**：用 emoji 标题分隔不同区域（✅ 搜索结果、📊 采集结果、📈 统计信息）\r\n- **字段齐全**：展示 API 返回的所有核心字段，不省略\r\n- **表格对齐**：每列用固定宽度对齐，分隔线用 `---` 填充，确保列宽一致\r\n- **链接处理**：表格内用 `[查看][linkN]` 引用式链接，在表格下方定义完整 URL，避免撑坏表格\r\n- **数字格式**：\r\n  - 粉丝/播放等数值：≥1万 用 K（如 33.1K）、≥100万 用 M（如 1.2M）；<1万 用逗号分隔（如 3,911）\r\n  - 获赞/总观看等大数值：用万/亿简写（如 95.5万、5.2亿）\r\n  - 互动率：转为百分比，保留两位小数（如 0.065 → 6.50%）\r\n- **统计信息**：单独列出总匹配数、服务等级、本次消耗积分、剩余配额、请求 ID，用无序列表展示\r\n- **总匹配数展示规则**：API 的 `meta.total` 仅在筛选条件 > 2 个时返回数值，≤ 2 个筛选条件时返回 null。当 total 为 null 时，统计信息中不展示\"总匹配数\"这一行，避免显示\"总匹配数：null\"\r\n- **默认展示 5~10 条**，超过时询问用户是否需要更多\r\n- 展示结果后主动询问：\"需要导出完整数据到 CSV/Excel 吗？\"\r\n\r\n## Quota Awareness\r\n\r\nEvery API response includes `meta.quota_remaining` and search responses include `meta.credits_consumed`. Monitor these values:\r\n- `credits_consumed` shows how many credits were deducted for the current request (varies by `service_level`: S1=1/record, S2=3/record, S3=4/record)\r\n- If `quota_remaining` < 50: warn the user that quota is running low\r\n- If `quota_remaining` < 10: strongly recommend the user to conserve quota\r\n- If `quota_remaining` = 0 or error 42902: inform the user that daily quota is exhausted (resets at UTC 00:00)\r\n- When using S2/S3 service levels, remind the user that credits are consumed faster\r\n\r\n## Workflows\r\n\r\n### Workflow 1: Search Creators (instant)\r\n\r\n```bash\r\nnode {baseDir}/scripts/search_creators.mjs '{\"platform\":\"tiktok\",\"keyword\":\"beauty\",\"country_code\":\"US\",\"followers_cnt_gte\":10000,\"size\":20,\"service_level\":\"S2\"}'\r\n```\r\n\r\n### Workflow 2: Search + Export (instant)\r\n\r\n```bash\r\n# Search and export to local CSV in one pipeline\r\nnode {baseDir}/scripts/search_creators.mjs '{\"platform\":\"tiktok\",\"keyword\":\"beauty\",\"country_code\":\"US\",\"size\":50,\"service_level\":\"S2\"}' | node {baseDir}/scripts/export_to_csv.mjs '{\"output\":\"creators.csv\"}'\r\n\r\n# Append page 2 to the same file\r\nnode {baseDir}/scripts/search_creators.mjs '{\"platform\":\"tiktok\",\"keyword\":\"beauty\",\"country_code\":\"US\",\"size\":50,\"page\":2,\"service_level\":\"S2\"}' | node {baseDir}/scripts/export_to_csv.mjs '{\"output\":\"creators.csv\"}'\r\n```\r\n\r\n### Workflow 3: Batch Collection (async, 5~30 min)\r\n\r\n> **Important**: Collection tasks are async and take 5~30 minutes. You MUST poll for completion before fetching data.\r\n\r\n**Step 1** — Submit task:\r\n\r\n```bash\r\nnode {baseDir}/scripts/submit_collection_task.mjs '{\"task_type\":\"LINK_BATCH\",\"platform\":\"tiktok\",\"values\":[\"https://www.tiktok.com/@creator1\",\"https://www.tiktok.com/@creator2\"],\"task_name\":\"Q1 collection\"}'\r\n```\r\n\r\n**Step 2** — Poll until completed (auto-polls every 60s):\r\n\r\n```bash\r\nnode {baseDir}/scripts/poll_task_status.mjs '{\"task_id\":\"task_xxx\"}'\r\n```\r\n\r\nAfter submitting, inform the user: \"Collection task submitted. This typically takes 5~30 minutes. I'll monitor the progress for you.\"\r\n\r\n**Step 3** — After task is completed, **ALWAYS export the data as a file first**, then show the download link to the user. Only use `get_task_data.mjs` if the user explicitly asks for raw JSON data.\r\n\r\n```bash\r\n# PREFERRED: Export as file and give user the download link\r\nnode {baseDir}/scripts/export_task_data.mjs '{\"task_id\":\"task_xxx\",\"format\":\"xlsx\"}'\r\n\r\n# Only if user explicitly requests raw JSON:\r\nnode {baseDir}/scripts/get_task_data.mjs '{\"task_id\":\"task_xxx\",\"page\":1,\"size\":50}'\r\n```\r\n\r\n> **Rule**: When a collection task completes, the default action is to call `export_task_data.mjs` with `format:\"xlsx\"` and present the `file_url` download link to the user. Do NOT just call `get_task_data.mjs` and dump raw JSON — users want a downloadable file.\r\n\r\n### Workflow 4: Keyword Collection (async)\r\n\r\n```bash\r\n# Step 1: Submit\r\nnode {baseDir}/scripts/submit_keyword_task.mjs '{\"platform\":\"tiktok\",\"keywords\":[\"beauty tips\",\"skincare routine\"]}'\r\n\r\n# Step 2: Poll\r\nnode {baseDir}/scripts/poll_task_status.mjs '{\"task_id\":\"task_xxx\"}'\r\n\r\n# Step 3: ALWAYS export as file after completion\r\nnode {baseDir}/scripts/export_task_data.mjs '{\"task_id\":\"task_xxx\",\"format\":\"xlsx\"}'\r\n```\r\n\r\n### Workflow 5: Find Similar/Lookalike Creators (instant)\r\n\r\nWhen the user provides a creator profile link or username and asks for similar creators, call `find_lookalike.mjs` directly — the API internally resolves username/URL to platform ID, no separate resolve step needed.\r\n\r\n**By username + platform:**\r\n\r\n```bash\r\nnode {baseDir}/scripts/find_lookalike.mjs '{\"username\":\"creator_demo\",\"platform\":\"tiktok\",\"limit\":10}'\r\n```\r\n\r\n**By profile URL (auto-detects platform):**\r\n\r\n```bash\r\nnode {baseDir}/scripts/find_lookalike.mjs '{\"profile_url\":\"https://www.tiktok.com/@creator_demo\",\"limit\":10}'\r\n```\r\n\r\n**By username only (auto-searches all platforms):**\r\n\r\n```bash\r\nnode {baseDir}/scripts/find_lookalike.mjs '{\"username\":\"creator_demo\",\"limit\":10}'\r\n```\r\n\r\n**Cross-platform search**: Set `target_platform` different from the seed creator's platform to find similar creators on another platform (e.g., find YouTube creators similar to a TikTok creator).\r\n\r\nOptional filters: `target_region`, `target_language`, `follower_min`, `follower_max`, `avg_views_min`, `avg_views_max`, `female_rate_min`, `lang`, `service_level`.\r\n\r\n**Decision rules for lookalike:**\r\n- If user gives a profile URL → pass it as `profile_url`, the API auto-parses platform and username\r\n- If user gives a username + platform → pass both\r\n- If user gives only a username → pass just `username`, the API searches all three platforms\r\n- If API returns error 40401 → inform user the creator is not in the database\r\n\r\n## Script Parameters\r\n\r\n### search_creators.mjs\r\n\r\n`platform` is required. All other parameters are optional filters.\r\n\r\n| Parameter | Type | Description |\r\n|-----------|------|-------------|\r\n| `platform` | string | **Required**. `tiktok` / `youtube` / `instagram` |\r\n| `keyword` | string | Search keyword |\r\n| `country_code` | string | Country code, comma-separated (e.g., `US,CA`) |\r\n| `language_code` | string | Creator language filter, comma-separated (e.g., `en,zh,ja`). Filters by creator's content language |\r\n| `gender` | string | Gender filter |\r\n| `has_email` | boolean | Has email contact |\r\n| `has_mcn` | boolean | Has MCN (TikTok) |\r\n| `has_line` | boolean | Has Line (TikTok) |\r\n| `has_zalo` | boolean | Has Zalo (TikTok) |\r\n| `has_whatsapp` | boolean | Has WhatsApp (YouTube/Instagram) |\r\n| `followers_cnt_gte` | integer | Followers ≥ |\r\n| `followers_cnt_lte` | integer | Followers ≤ |\r\n| `last10_avg_video_views_cnt_gte` | number | Avg views (last 10 videos) ≥ |\r\n| `last10_avg_video_views_cnt_lte` | number | Avg views (last 10 videos) ≤ |\r\n| `last10_avg_video_interaction_rate_gte` | number | Avg engagement rate ≥ |\r\n| `last10_avg_video_interaction_rate_lte` | number | Avg engagement rate ≤ |\r\n| `last_video_publish_date_gte` | string | Last video date ≥ (YYYY-MM-DD) |\r\n| `last_video_publish_date_lte` | string | Last video date ≤ (YYYY-MM-DD) |\r\n| `industry` | string | Industry category (Chinese/English names, IDs, comma-separated) |\r\n| `audience_female_rate_gte` | number | Audience female ratio ≥ |\r\n| `audience_female_rate_lte` | number | Audience female ratio ≤ |\r\n| `audience_country_code_list` | string | Audience country codes, comma-separated |\r\n| `audience_language_code_list` | string | Audience language codes, comma-separated |\r\n| `audience_age_list` | string | Audience age ranges, comma-separated |\r\n| `page` | integer | Page number, default 1 |\r\n| `size` | integer | Page size, default 50, max 100 |\r\n| `sort_field` | string | Sort field: `followers_cnt` / `last10_avg_video_views_cnt` / `last10_avg_video_interaction_rate` |\r\n| `sort_order` | string | `asc` / `desc` (default `desc`) |\r\n| `service_level` | string | `S1` (1 credit) / `S2` (3 credits, default) / `S3` (4 credits) |\r\n| `lang` | string | Response display language: `cn` / `en`. ⚠️ Only translates response values, does NOT filter creators. Use `language_code` to filter |\r\n\r\n**Platform-specific category parameters:**\r\n\r\nAll platforms use the same format: **level-3 category IDs** (8-digit codes). The skill automatically converts user input to the correct format.\r\n\r\nAll platforms use the **`industry`** parameter for category filtering.\r\n\r\n**Supported input formats** (all platforms):\r\n- **Level-3 category IDs** (8-digit codes): `25009001,24001001` (Skincare + Mobile Phones)\r\n- **Level-1 category IDs** (2-digit codes): `25` (expands to all Beauty & Personal Care subcategories)\r\n- **Chinese category names**: `美妆,科技数码` (auto-converts to IDs)\r\n- **English category names**: `Skincare,Mobile Phones` (auto-converts to IDs)\r\n- **Common English aliases**: `Fashion`, `Beauty`, `Sports`, `Tech`, `Food`, `Gaming`, `Travel` (auto-converts to IDs)\r\n- **Comma-separated mixed input**: `Fashion,Beauty` (each part resolved independently)\r\n\r\n**Common aliases reference:**\r\n\r\n| Alias | Maps to | ID |\r\n|-------|---------|-----|\r\n| Fashion / Clothing | Clothing & Fashion | 16 |\r\n| Beauty / Cosmetics | Beauty & Personal Care | 25 |\r\n| Sports / Fitness / Outdoor | Outdoor & Sports | 12 |\r\n| Tech / Technology / Electronics | Technology & Electronics | 24 |\r\n| Food / Cooking | Food & Beverages | 26 |\r\n| Gaming / Games / Esports | Games | 19 |\r\n| Travel / Lifestyle | Travel & Lifestyle | 15 |\r\n\r\nSee [Industry Categories Reference](references/industry-categories.md) for complete mapping.\r\n\r\n**Category Input Examples:**\r\n\r\n```bash\r\n# All platforms: use \"industry\" parameter, auto-converted to level-3 IDs\r\nnode scripts/search_creators.mjs '{\"platform\":\"tiktok\",\"industry\":\"Fashion\"}'\r\nnode scripts/search_creators.mjs '{\"platform\":\"tiktok\",\"industry\":\"美妆\"}'\r\nnode scripts/search_creators.mjs '{\"platform\":\"tiktok\",\"industry\":\"Skincare\"}'\r\nnode scripts/search_creators.mjs '{\"platform\":\"youtube\",\"industry\":\"25\"}'\r\nnode scripts/search_creators.mjs '{\"platform\":\"instagram\",\"industry\":\"25009001\"}'\r\nnode scripts/search_creators.mjs '{\"platform\":\"tiktok\",\"industry\":\"Fashion,Beauty\"}'\r\n```\r\n\r\n#### Service Level Details\r\n\r\n| Level | Name | Included Fields | Credits/Record |\r\n|-------|------|----------------|----------------|\r\n| S1 | List only | uid, username, nickname, avatar_url, profile_url, followers_count, likes_count, video_count, has_showcase, has_email, has_mcn, has_line, has_zalo, last_video_publish_date | 1 |\r\n| S2 | Precise reach | S1 + country_code, gender, engagement_rate, avg_views, views_per_follower, is_verified, last10_video_views_per_sub, last10_med_video_views_cnt, last10_med_video_views_per_sub, product_categories, industry_categories, bio, hashtags, email, contact fields, mcn, language | 3 |\r\n| S3 | Deep profile | S2 + audience_female_rate (percentage), audience_country_code_list, audience_language_code_list, audience_age_id_list | 4 |\r\n\r\nPlatform-specific parameters: see [Platform Parameters Reference](references/platform-params.md).\r\n\r\n### submit_collection_task.mjs\r\n\r\n| Parameter | Type | Description |\r\n|-----------|------|-------------|\r\n| `task_type` | string | **Required**. `LINK_BATCH` (links) / `FILE_UPLOAD` (usernames) |\r\n| `platform` | string | **Required**. `tiktok` / `youtube` / `instagram` |\r\n| `values` | string[] | **Required**. Links or usernames, max 500 |\r\n| `task_name` | string | Task name |\r\n| `webhook_url` | string | Completion callback URL (HTTPS) |\r\n\r\n### submit_keyword_task.mjs\r\n\r\n| Parameter | Type | Description |\r\n|-----------|------|-------------|\r\n| `platform` | string | **Required**. `tiktok` / `youtube` / `instagram` |\r\n| `keywords` | string[] | **Required**. Keyword list, max 10 |\r\n| `task_name` | string | Task name |\r\n| `webhook_url` | string | Completion callback URL (HTTPS) |\r\n\r\n### poll_task_status.mjs\r\n\r\n| Parameter | Type | Description |\r\n|-----------|------|-------------|\r\n| `task_id` | string | **Required**. Task ID |\r\n| `interval` | integer | Poll interval in seconds, default 60 |\r\n| `max_attempts` | integer | Max poll attempts, default 45 (~45 min) |\r\n\r\n### get_task_status.mjs\r\n\r\n| Parameter | Type | Description |\r\n|-----------|------|-------------|\r\n| `task_id` | string | **Required**. Task ID |\r\n\r\n### get_task_data.mjs\r\n\r\n| Parameter | Type | Description |\r\n|-----------|------|-------------|\r\n| `task_id` | string | **Required**. Task ID |\r\n| `page` | integer | Page number, default 1 |\r\n| `size` | integer | Page size, default 20, max 100 |\r\n\r\n### export_task_data.mjs\r\n\r\nExports task data to file (server-side), uploads to OSS, returns download URL. Repeated calls with same task_id + format return cached file.\r\n\r\n| Parameter | Type | Description |\r\n|-----------|------|-------------|\r\n| `task_id` | string | **Required**. Task ID (must be completed) |\r\n| `format` | string | **Required**. `xlsx` / `csv` / `html` |\r\n\r\n### export_to_csv.mjs\r\n\r\nPipe JSON from search or collection results to export as local CSV file. Supports incremental append.\r\n\r\n| Parameter | Type | Description |\r\n|-----------|------|-------------|\r\n| `output` | string | Output file path, default `output.csv` |\r\n| `mode` | string | `append` (default) / `overwrite` |\r\n\r\n### get_download_url.mjs\r\n\r\n| Parameter | Type | Description |\r\n|-----------|------|-------------|\r\n| `file_id` | string | File ID (either file_id or file_name required) |\r\n| `file_name` | string | File name (either file_id or file_name required) |\r\n\r\n### find_lookalike.mjs\r\n\r\nFind similar/lookalike creators. Supports username, profile URL, or cross-platform search. The API internally resolves username/URL to platform ID.\r\n\r\n| Parameter | Type | Description |\r\n|-----------|------|-------------|\r\n| `username` | string | Creator username (without `@`), either this or `profile_url` required |\r\n| `platform` | string | Creator platform: `tiktok` / `youtube` / `instagram`. Optional — if omitted, searches all platforms |\r\n| `profile_url` | string | Creator profile URL (auto-detects platform), either this or `username` required |\r\n| `target_platform` | string | Target search platform. If omitted, same as seed creator's platform |\r\n| `target_region` | string | Target country code, `all` for no filter |\r\n| `target_language` | string | Target language code, `all` for no filter |\r\n| `limit` | integer | Number of results, default 20, max 50 |\r\n| `follower_min` | integer | Minimum followers |\r\n| `follower_max` | integer | Maximum followers |\r\n| `avg_views_min` | integer | Minimum average views |\r\n| `avg_views_max` | integer | Maximum average views |\r\n| `female_rate_min` | number | Minimum female audience ratio (0~100) |\r\n| `lang` | string | Response language: `cn` / `en` |\r\n| `service_level` | string | Service level, default `S1` |\r\n\r\nReturns: `items` array with `uid`, `username`, `nickname`, `avatar_url`, `profile_url`, `country_code`, `followers_count`, `avg_views`, `engagement_rate`, `match_score`.\r\n\r\n## Error Handling\r\n\r\n| Code | HTTP | Description | Action |\r\n|------|------|-------------|--------|\r\n| 40001 | 400 | Invalid parameters | Check parameter format and values |\r\n| 40101 | 401 | Invalid API Key | Check CV_API_KEY env variable |\r\n| 40102 | 401 | API Key expired | Contact admin to renew |\r\n| 40103 | 401 | API Key revoked | Contact admin |\r\n| 40104 | 401 | Missing user identity | Check CV_USER_IDENTITY env variable |\r\n| 40201 | 402 | Insufficient credits | Top up or upgrade plan |\r\n| 40301 | 403 | No permission for this endpoint | Check API Key scopes |\r\n| 42901 | 429 | Rate limit exceeded | Auto-retry after Retry-After seconds |\r\n| 42902 | 402 | Daily quota exhausted | Wait until UTC 00:00 or upgrade plan |\r\n| 50001 | 500 | Server error | Report request_id to support |\r\n\r\n## References\r\n\r\n- [API Reference](references/api-reference.md) — Full request/response field documentation\r\n- [Platform Parameters](references/platform-params.md) — TikTok/YouTube/Instagram specific filters\r\n- [Industry Categories](references/industry-categories.md) — Industry category tree with Chinese/English mapping (for `industry` param)\r\n- [Country Codes](references/country-codes.md) — ISO country codes with Chinese/English names and region shortcuts\r\n- [Language Codes](references/language-codes.md) — ISO language codes with Chinese/English names\r\n- [Error Codes](references/error-codes.md) — Complete error code list and troubleshooting\r\n\r\n## Changelog\r\n\r\n### v1.5.0\r\n- Aligned with API v1.5\r\n- All platforms: added `is_verified`(S2), `last10_video_views_per_sub`(S2), `last10_med_video_views_cnt`(S2), `last10_med_video_views_per_sub`(S2)\r\n- YouTube: added short/long variants (`last10_video_views_per_sub_short/long`, `last10_med_video_views_cnt_short/long`, `last10_med_video_views_per_sub_short/long`)\r\n- TikTok search: `industry_category_levels_list` parameter unified to `industry` (same as YouTube/Instagram)\r\n- `lang` parameter now also translates `audience_age_id_list`\r\n\r\n### v1.4.0\r\n- Aligned with API v1.4: added `bio`, `industry_categories`, `hashtags` to S2 for all three platforms\r\n- TikTok: added `video_count`(S1), `views_per_follower`(S2), `audience_age_id_list`(S3)\r\n- YouTube: added `bio`(S2), `audience_female_rate`(S3)\r\n- Instagram: added `gender`(S2), `bio`(S2), `industry_categories`(S2), `hashtags`(S2), `audience_age_id_list`(S3)\r\n- `audience_female_rate` now returns percentage value (e.g., 78.65 = 78.65%)\r\n- `gender` and `audience_age_id_list` support `lang` i18n translation\r\n- `lang` parameter available on all search endpoints and lookalike\r\n\r\n### v1.3.0\r\n- Updated all three platform search response fields per v1.4 API doc\r\n- TikTok: added `video_count`(S1), `views_per_follower`(S2), `bio`(S2), `industry_categories`(S2), `hashtags`(S2), `audience_age_id_list`(S3), contact fields\r\n- YouTube: added `bio`(S2), `industry_categories`(S2), `hashtags`(S2), `audience_female_rate`(S3)\r\n- Instagram: added `gender`(S2), `bio`(S2), `industry_categories`(S2), `hashtags`(S2), `audience_age_id_list`(S3)\r\n- Added `lang` parameter support for i18n (cn/en) on all search and lookalike endpoints\r\n- `audience_female_rate` now returns percentage value (e.g., 78.65 = 78.65%)\r\n- Removed `resolve_creator.mjs` — lookalike API now auto-resolves username/URL internally\r\n- Simplified `find_lookalike.mjs` to accept `username`/`profile_url` directly (no more `seed_platform_id`)\r\n- Simplified Workflow 5 to single-step lookalike call\r\n\r\n### v1.2.0\r\n- Added similar/lookalike creator discovery via `find_lookalike.mjs`\r\n- Search API now defaults to S2 (precise reach) service level\r\n- `meta.total` only returned when filter conditions > 2; output formatting hides total when null\r\n- Added cross-platform lookalike search support\r\n- Added Workflow 5 for lookalike creator discovery\r\n\r\n### v1.1.0\r\n- Added server-side export (xlsx/csv/html) via `export_task_data.mjs`\r\n- Added auto-retry on 429 rate limit in API client\r\n- Added quota awareness guidance\r\n- Added output formatting guidance for agents\r\n- Added smart workflow selection (search vs collection)\r\n- Unified all script logs and SKILL.md to English\r\n\r\n### v1.0.0\r\n- Initial release: search, collection, polling, local CSV export\r\n\r\n---\r\n\r\n## Outreach (Email Outreach)\r\n\r\nSend outreach emails to creators discovered via search. 7 scripts covering the full outreach workflow.\r\n\r\n### ⚠️ Architecture Principle\r\n\r\n**Skill = 纯 HTTP 客户端，不做任何业务逻辑处理。**\r\n\r\n- Skill 脚本只负责组装 JSON 参数并调用 OpenAPI 接口\r\n- 所有业务逻辑（创建提报、创建达人记录、查找活跃会话、判断新建/回复）由 OpenAPI 接口内部完成\r\n- Skill 不需要知道 submission_id、influencer_id 等内部概念\r\n- 搜索后发送时，Skill 应将搜索结果中的 `uid` 和 `platform` 传给 outreach_send（OpenAPI 内部会根据 uid 从 Holo 查完整达人数据，自动创建与 web 端一致的提报达人记录）\r\n\r\n### Outreach Capabilities\r\n\r\n| Capability | Script | Mode |\r\n|------------|--------|------|\r\n| Send email (single/batch) | `scripts/outreach_send.mjs` | Async, returns task_id |\r\n| Query task (status+result) | `scripts/outreach_task.mjs` | Sync or auto-poll |\r\n| Query creator contact info | `scripts/outreach_contact.mjs` | Sync |\r\n| Get follow-up todo list | `scripts/outreach_todo.mjs` | Sync |\r\n| Get outreach metrics | `scripts/outreach_metrics.mjs` | Sync |\r\n| Get config (channels+templates) | `scripts/outreach_config.mjs` | Sync |\r\n| Upload attachment | `scripts/outreach_upload.mjs` | Sync |\r\n\r\n### Outreach Workflow: Search → Send → Track\r\n\r\n```bash\r\n# Step 1: Search creators with email\r\nnode {baseDir}/scripts/search_creators.mjs '{\"platform\":\"tiktok\",\"keyword\":\"beauty\",\"has_email\":true,\"service_level\":\"S2\"}'\r\n\r\n# Step 2: Check available channels and templates\r\nnode {baseDir}/scripts/outreach_config.mjs '{}'\r\n\r\n# Step 3: Batch send (recipients format compatible with search results)\r\nnode {baseDir}/scripts/outreach_send.mjs '{\"recipients\":[{\"email\":\"c1@x.com\",\"nickname\":\"Creator1\"},{\"email\":\"c2@x.com\",\"nickname\":\"Creator2\"}],\"template_id\":123}'\r\n\r\n# Step 4: Poll until complete (auto-poll mode)\r\nnode {baseDir}/scripts/outreach_task.mjs '{\"task_id\":\"batch_xxx\",\"poll\":true,\"include_result\":true}'\r\n\r\n# Step 5: Check follow-up todos after a few days\r\nnode {baseDir}/scripts/outreach_todo.mjs '{\"overdue_hours\":48}'\r\n\r\n# Step 6: View creator's contact info + history + AI summary\r\nnode {baseDir}/scripts/outreach_contact.mjs '{\"email\":\"c1@x.com\"}'\r\n\r\n# Step 7: Reply (system auto-detects existing conversation)\r\nnode {baseDir}/scripts/outreach_send.mjs '{\"to\":\"c1@x.com\",\"body_html\":\"<p>Thanks!</p>\"}'\r\n\r\n# Step 8: Check overall metrics\r\nnode {baseDir}/scripts/outreach_metrics.mjs '{\"date_from\":\"2025-05-01\",\"group_by\":\"week\"}'\r\n```\r\n\r\n### Outreach Script Parameters\r\n\r\n#### outreach_send.mjs\r\n\r\n`to` and `recipients` are mutually exclusive — pass exactly one.\r\n\r\n| Parameter | Type | Description |\r\n|-----------|------|-------------|\r\n| `to` | string | Creator email (single send) |\r\n| `uid` | string | **Required for single send**. Creator platform UID (from search result's `uid` field, OpenAPI auto-fetches full data) |\r\n| `nickname` | string | Creator nickname (optional, for session display) |\r\n| `platform` | string | Creator platform: tiktok/youtube/instagram (recommended) |\r\n| `recipients` | object[] | Array of `{email, uid, nickname, platform}` (batch send) |\r\n| `subject` | string | Email subject |\r\n| `body_html` | string | HTML body (supports `{{creator_name}}` variables) |\r\n| `body_text` | string | Plain text body |\r\n| `channel` | string | `ses` (default) / `gmail` / `outlook` |\r\n| `template_id` | integer | Template ID (overrides subject/body) |\r\n| `send_mode` | string | `immediate` (default) / `smart` (timezone-optimized) |\r\n| `force_new` | boolean | Force new conversation (default false) |\r\n| `attachment_ids` | string[] | Attachment IDs from upload |\r\n\r\n#### outreach_task.mjs\r\n\r\n| Parameter | Type | Description |\r\n|-----------|------|-------------|\r\n| `task_id` | string | **Required**. Task ID from send |\r\n| `include_result` | boolean | Attach per-recipient results when completed (default false) |\r\n| `result_filter` | string | Filter results: `all` / `sent` / `failed` |\r\n| `poll` | boolean | Auto-poll until terminal status (default false) |\r\n| `poll_interval` | integer | Poll interval seconds (default 5) |\r\n| `poll_max_attempts` | integer | Max poll attempts (default 60) |\r\n\r\n#### outreach_contact.mjs\r\n\r\n| Parameter | Type | Description |\r\n|-----------|------|-------------|\r\n| `email` | string | **Required**. Creator email |\r\n| `include_history` | boolean | Include message history (default true) |\r\n| `include_summary` | boolean | Include AI summary (default true) |\r\n\r\n#### outreach_todo.mjs\r\n\r\n| Parameter | Type | Description |\r\n|-----------|------|-------------|\r\n| `overdue_hours` | integer | Overdue threshold in hours (default 24) |\r\n| `include_unread` | boolean | Include unread conversations (default true) |\r\n| `include_overdue` | boolean | Include overdue conversations (default true) |\r\n\r\n#### outreach_metrics.mjs\r\n\r\n| Parameter | Type | Description |\r\n|-----------|------|-------------|\r\n| `date_from` | string | Start date YYYY-MM-DD (default: last 7 days) |\r\n| `date_to` | string | \n\nArchive v1.0.6: 26 files, 47364 bytes\n\nFiles: references/api-reference.md (11850b), references/country-codes.md (2079b), references/error-codes.md (2314b), references/industry-categories.md (10118b), references/language-codes.md (1327b), references/platform-params.md (15185b), scripts/_api_client.mjs (5737b), scripts/_industry_mapper.mjs (19526b), scripts/export_task_data.mjs (1085b), scripts/export_to_csv.mjs (4008b), scripts/find_lookalike.mjs (925b), scripts/get_download_url.mjs (624b), scripts/get_task_data.mjs (505b), scripts/get_task_status.mjs (441b), scripts/langfuse/test_cases.json (5403b), scripts/outreach_contact.mjs (671b), scripts/outreach_send.mjs (1711b), scripts/outreach_task.mjs (2484b), scripts/outreach_todo.mjs (574b), scripts/poll_task_status.mjs (1984b), scripts/search_creators.mjs (852b), scripts/submit_collection_task.mjs (1282b), scripts/submit_keyword_task.mjs (834b), skill-card.md (2786b), SKILL.md (35590b), _meta.json (137b)\n\nArchive v1.0.5: 25 files, 46288 bytes\n\nFiles: references/api-reference.md (11850b), references/country-codes.md (2079b), references/error-codes.md (2314b), references/industry-categories.md (10118b), references/language-codes.md (1327b), references/platform-params.md (15185b), scripts/_api_client.mjs (5737b), scripts/_industry_mapper.mjs (19526b), scripts/export_task_data.mjs (1085b), scripts/export_to_csv.mjs (4008b), scripts/find_lookalike.mjs (925b), scripts/get_download_url.mjs (624b), scripts/get_task_data.mjs (505b), scripts/get_task_status.mjs (441b), scripts/outreach_contact.mjs (671b), scripts/outreach_send.mjs (1711b), scripts/outreach_task.mjs (2484b), scripts/outreach_todo.mjs (574b), scripts/poll_task_status.mjs (1984b), scripts/search_creators.mjs (852b), scripts/submit_collection_task.mjs (1282b), scripts/submit_keyword_task.mjs (834b), skill-card.md (2628b), SKILL.md (35590b), _meta.json (137b)\n\nArchive v1.0.4: 21 files, 38500 bytes\n\nFiles: references/api-reference.md (12104b), references/country-codes.md (2150b), references/error-codes.md (2380b), references/industry-categories.md (10403b), references/language-codes.md (1373b), references/platform-params.md (15453b), scripts/_api_client.mjs (5437b), scripts/_industry_mapper.mjs (17204b), scripts/export_task_data.mjs (1116b), scripts/export_to_csv.mjs (4133b), scripts/find_lookalike.mjs (945b), scripts/get_download_url.mjs (644b), scripts/get_task_data.mjs (522b), scripts/get_task_status.mjs (456b), scripts/poll_task_status.mjs (2041b), scripts/search_creators.mjs (873b), scripts/submit_collection_task.mjs (1317b), scripts/submit_keyword_task.mjs (859b), skill-card.md (2508b), SKILL.md (25656b), _meta.json (137b)\n\nArchive v1.0.3: 20 files, 35803 bytes\n\nFiles: references/api-reference.md (4507b), references/country-codes.md (2150b), references/error-codes.md (2380b), references/industry-categories.md (10509b), references/language-codes.md (1373b), references/platform-params.md (13836b), scripts/_api_client.mjs (6117b), scripts/_industry_mapper.mjs (17204b), scripts/export_task_data.mjs (1116b), scripts/export_to_csv.mjs (4133b), scripts/find_lookalike.mjs (945b), scripts/get_download_url.mjs (610b), scripts/get_task_data.mjs (522b), scripts/get_task_status.mjs (456b), scripts/poll_task_status.mjs (2041b), scripts/search_creators.mjs (915b), scripts/submit_collection_task.mjs (1317b), scripts/submit_keyword_task.mjs (859b), SKILL.md (24869b), _meta.json (137b)\n\nArchive v1.0.2: 19 files, 30358 bytes\n\nFiles: references/api-reference.md (4507b), references/country-codes.md (2150b), references/error-codes.md (2380b), references/industry-categories.md (8720b), references/language-codes.md (1373b), references/platform-params.md (13836b), scripts/_api_client.mjs (3939b), scripts/export_task_data.mjs (1116b), scripts/export_to_csv.mjs (4133b), scripts/find_lookalike.mjs (945b), scripts/get_download_url.mjs (610b), scripts/get_task_data.mjs (522b), scripts/get_task_status.mjs (456b), scripts/poll_task_status.mjs (2041b), scripts/search_creators.mjs (559b), scripts/submit_collection_task.mjs (1317b), scripts/submit_keyword_task.mjs (859b), SKILL.md (23163b), _meta.json (137b)\n\nArchive v1.0.0: 20 files, 29657 bytes\n\nFiles: references/api-reference.md (4479b), references/country-codes.md (2150b), references/error-codes.md (2380b), references/industry-categories.md (8720b), references/language-codes.md (1373b), references/platform-params.md (10549b), scripts/_api_client.mjs (3939b), scripts/export_task_data.mjs (1116b), scripts/export_to_csv.mjs (4133b), scripts/find_lookalike.mjs (660b), scripts/get_download_url.mjs (610b), scripts/get_task_data.mjs (522b), scripts/get_task_status.mjs (456b), scripts/poll_task_status.mjs (2041b), scripts/resolve_creator.mjs (514b), scripts/search_creators.mjs (559b), scripts/submit_collection_task.mjs (1317b), scripts/submit_keyword_task.mjs (859b), SKILL.md (22196b), _meta.json (137b)","readmeExcerpt":"Skill: Creativault Creator Scraper Owner: creativault Summary: Creativault creator data collection and outreach skill. Search and collect creator/influencer data from TikTok, YouTube, Instagram, and Twitter. Send outreac... Tags: KOL:1.0.0, creator:1.0.0, data-collection:1.0.0, influencer:1.0.0, instagram:1.0.0, latest:1.8.0, scraper:1.0.0, social-media:1.0.0, tiktok:1.0.0, youtube:1.0.0 Version history: v1.8.0 | 202","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"File v1.8.0:discovery/creator-lookalike/SKILL.md\n\n---\r\nname: creator-lookalike\r\ndescription: |\r\n  相似达人发现能力，支持种子达人解析、相似度匹配、跨平台搜索。通过 username、profile_url 或自动全平台搜索找到风格相似的创作者。\r\n  Use when: 相似达人, 类似达人, similar creators, lookalike, find similar\r\ncompatibility: Node.js 20.6+\r\nmetadata:\r\n  layer: discovery\r\n  parent: creator-scraper-cv\r\n---\r\n\r\n## 概述\r\n\r\n基于种子达人查找风格相似的创作者，支持同平台匹配和跨平台发现（如从 TikTok 达人找到 YouTube 上的相似创作者）。\r\n\r\n## 脚本引用\r\n\r\n| 脚本 | 路径 | 模式 | 状态 |\r\n|------|------|------|------|\r\n| find_lookalike.mjs | `../../scripts/find_lookalike.mjs` | Sync, 自动解析 username/URL | ✅ |\r\n\r\n## 输入方式\r\n\r\nAPI 内部自动将 username/URL 解析为平台 ID，无需额外 resolve 步骤。\r\n\r\n### 方式一：username + platform（指定平台）\r\n\r\n明确指定达人所在平台，直接在该平台查找相似达人："},{"language":"bash","snippet":"node {baseDir}/scripts/search_creators.mjs '{\"platform\":\"tiktok\",\"country_code\":\"US\",\"gender\":\"0\",\"followers_cnt_gte\":100000,\"service_level\":\"S2\"}'"},{"language":"json","snippet":"{\"platform\":\"tiktok\",\"country_code\":\"US\",\"gender\":\"0\",\"has_email\":true,\"followers_cnt_gte\":100000,\"last10_avg_video_interaction_rate_gte\":3,\"service_level\":\"S2\"}"},{"language":"json","snippet":"{\"platform\":\"youtube\",\"country_code\":\"US\",\"last10_avg_video_view_count_short_gte\":50000,\"audience_female_rate_gte\":70,\"service_level\":\"S3\"}"},{"language":"json","snippet":"{\"platform\":\"instagram\",\"industry\":\"Beauty\",\"is_product_kol\":true,\"audience_language_list\":\"en\",\"service_level\":\"S2\"}"},{"language":"text","snippet":"| # | 用户名 | 昵称 | 粉丝数 | 获赞数 | 平均播放 | 互动率 | 国家 | 主页链接 |"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"collection/creator-collection/SKILL.md","content":"---\r\nname: creator-collection\r\ndescription: |\r\n  批量达人数据采集与导出能力，支持 TikTok、YouTube、Instagram、Twitter 四平台。支持链接批量、用户名批量、关键词采集三种模式。异步任务机制，含提交、轮询、取数、导出完整生命周期。\r\n  Use when: 批量采集, 数据导出, 离线采集, batch collection, data export, keyword collection\r\ncompatibility: Node.js 20.6+\r\nmetadata:\r\n  layer: collection\r\n  parent: creator-scraper-cv\r\n---\r\n\r\n## 概述\r\n\r\n批量达人数据采集与导出能力。支持通过链接、用户名或关键词提交异步采集任务，自动轮询任务状态，完成后导出为 xlsx/csv/html 文件并提供下载链接。\r\n\r\n支持平台：TikTok、YouTube、Instagram、Twitter。\r\n\r\n> **Twitter 平台限制**：仅支持 `LINK_BATCH`（链接采集）和 `FILE_UPLOAD`（用户名采集），不支持视频采集（`CREATOR_VIDEO`、`POST_VIDEO`）。\r\n\r\n## 脚本引用\r\n\r\n| # | 脚本 | 路径 | 状态 |\r\n|---|------|------|------|\r\n| 1 | submit_collection_task.mjs | `../../scripts/submit_collection_task.mjs` | ✅ |\r\n| 2 | submit_keyword_task.mjs | `../../scripts/submit_keyword_task.mjs` | ✅ |\r\n| 3 | poll_task_status.mjs | `../../scripts/poll_task_status.mjs` | ✅ |\r\n| 4 | get_task_status.mjs | `../../scripts/get_task_status.mjs` | ✅ |\r\n| 5 | get_task_data.mjs | `../../scripts/get_task_data.mjs` | ✅ |\r\n| 6 | export_task_data.mjs | `../../scripts/export_task_data.mjs` | ✅ |\r\n| 7 | export_to_csv.mjs | `../../scripts/export_to_csv.mjs` | ✅ |\r\n| 8 | get_download_url.mjs | `../../scripts/get_download_url.mjs` | ✅ |\r\n\r\n## 异步任务生命周期\r\n\r\n采集任务为异步操作（耗时 5~30 分钟），遵循四阶段流程：\r\n\r\n```\r\n提交(submit) → 轮询(poll) → 取数(get data) → 导出(export)\r\n```\r\n\r\n| 阶段 | 脚本 | 说明 |\r\n|------|------|------|\r\n| 1. 提交 | `submit_collection_task.mjs` / `submit_keyword_task.mjs` | 返回 task_id |\r\n| 2. 轮询 | `poll_task_status.mjs` | 每 60s 自动轮询直到终态 |\r\n| 3. 取数 | `get_task_data.mjs` | 分页获取原始 JSON 数据（仅在用户明确要求时使用） |\r\n| 4. 导出 | `export_task_data.mjs` | 生成文件并返回下载链接 |\r\n\r\n### 任务状态与终态判断\r\n\r\n| 状态 | 含义 | 是否终态 |\r\n|------|------|---------|\r\n| `processing` | 处理中（爬取中或数据入库中） | ❌ 继续轮询 |\r\n| `completed` | 已完成 | ✅ 可取数/导出 |\r\n| `failed` | 失败 | ✅ 报告错误 |\r\n| `timeout` | 超时 | ✅ 报告超时 |\r\n\r\n> **[禁止] 在 `status: \"processing\"` 时提前报告结果。**\r\n> 即使 `progress: 100%`，只要 `status` 仍为 `processing`，说明数据仍在入库处理中，**不能**判定为\"0 条数据\"或\"无匹配结果\"。\r\n> 必须等到 `status` 变为 `completed` / `failed` / `timeout` 之一后，才能向用户报告最终结果。\r\n>\r\n> **典型场景**：`progress: 100%, completed: 0, status: processing` — 爬取已完成但数据尚未入库，继续轮询等待 `completed` 状态。\r\n\r\n> **规则**：采集完成后（`status: completed`），**必须**先调用 `export_task_data.mjs` 生成可下载文件并展示链接给用户。不要直接调用 `get_task_data.mjs` 输出原始 JSON。\r\n\r\n> **积分提醒规则**：仅当接口明确返回错误码 `40201` 时提示积分不足。`meta.quota_remaining` 是当天剩余 API 请求次数，不是积分余额；采集、轮询或导出成功后，禁止根据该字段生成“剩余积分不足”提醒。\r\n\r\n辅助脚本：\r\n- `get_task_status.mjs` — 单次查询任务状态（不轮询）\r\n- `export_to_csv.mjs` — 管道式本地 CSV 导出（接收 stdin JSON）\r\n- `get_download_url.mjs` — 获取已生成文件的下载链接\r\n\r\n## 采集类型\r\n\r\n| 类型 | task_type 值 | 触发场景 | 提交脚本 |\r\n|------|-------------|----------|----------|\r\n| 链接批量 | `LINK_BATCH` | 用户提供达人主页链接列表 | `submit_collection_task.mjs` |\r\n| 用户名批量 | `FILE_UPLOAD` | 用户提供用户名列表 | `submit_collection_task.mjs` |\r\n| 关键词采集 | — | 用户提供关键词，按关键词批量采集 | `submit_keyword_task.mjs` |\r\n\r\n**使用示例**：\r\n\r\n```bash\r\n# 链接批量采集\r\nnode ../../scripts/submit_collection_task.mjs '{\"task_type\":\"LINK_BATCH\",\"platform\":\"tiktok\",\"values\":[\"https://www.tiktok.com/@creator1"},{"path":"discovery/creator-lookalike/SKILL.md","content":"---\r\nname: creator-lookalike\r\ndescription: |\r\n  相似达人发现能力，支持种子达人解析、相似度匹配、跨平台搜索。通过 username、profile_url 或自动全平台搜索找到风格相似的创作者。\r\n  Use when: 相似达人, 类似达人, similar creators, lookalike, find similar\r\ncompatibility: Node.js 20.6+\r\nmetadata:\r\n  layer: discovery\r\n  parent: creator-scraper-cv\r\n---\r\n\r\n## 概述\r\n\r\n基于种子达人查找风格相似的创作者，支持同平台匹配和跨平台发现（如从 TikTok 达人找到 YouTube 上的相似创作者）。\r\n\r\n## 脚本引用\r\n\r\n| 脚本 | 路径 | 模式 | 状态 |\r\n|------|------|------|------|\r\n| find_lookalike.mjs | `../../scripts/find_lookalike.mjs` | Sync, 自动解析 username/URL | ✅ |\r\n\r\n## 输入方式\r\n\r\nAPI 内部自动将 username/URL 解析为平台 ID，无需额外 resolve 步骤。\r\n\r\n### 方式一：username + platform（指定平台）\r\n\r\n明确指定达人所在平台，直接在该平台查找相似达人：\r\n\r\n```bash\r\nnode ../../scripts/find_lookalike.mjs '{\"username\":\"creator_demo\",\"platform\":\"tiktok\",\"limit\":10}'\r\n```\r\n\r\n### 方式二：profile_url（自动识别平台）\r\n\r\n传入达人主页链接，API 自动解析平台和用户名：\r\n\r\n```bash\r\nnode ../../scripts/find_lookalike.mjs '{\"profile_url\":\"https://www.tiktok.com/@creator_demo\",\"limit\":10}'\r\n```\r\n\r\n支持的 URL 格式：\r\n- TikTok: `https://www.tiktok.com/@username`\r\n- YouTube: `https://www.youtube.com/@username`\r\n- Instagram: `https://www.instagram.com/username`\r\n\r\n### 方式三：username only（搜索全平台）\r\n\r\n仅传入用户名，不指定平台，API 自动在 TikTok、YouTube、Instagram 三个平台搜索匹配：\r\n\r\n```bash\r\nnode ../../scripts/find_lookalike.mjs '{\"username\":\"creator_demo\",\"limit\":10}'\r\n```\r\n\r\n## 参数说明\r\n\r\n| 参数 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `username` | string | 二选一 | 达人用户名（不含 `@`），与 `profile_url` 二选一 |\r\n| `platform` | string | 否 | 种子达人平台：`tiktok` / `youtube` / `instagram`，省略则搜索全平台 |\r\n| `profile_url` | string | 二选一 | 达人主页链接（自动识别平台），与 `username` 二选一 |\r\n| `target_platform` | string | 否 | 目标搜索平台，省略则与种子达人同平台。设为不同平台可实现跨平台搜索 |\r\n| `target_region` | string | 否 | 目标国家代码，`all` 表示不限 |\r\n| `target_language` | string | 否 | 目标语言代码，`all` 表示不限 |\r\n| `limit` | integer | 否 | 返回数量，默认 20，最大 50 |\r\n| `follower_min` | integer | 否 | 最小粉丝数 |\r\n| `follower_max` | integer | 否 | 最大粉丝数 |\r\n| `avg_views_min` | integer | 否 | 最小平均播放量 |\r\n| `avg_views_max` | integer | 否 | 最大平均播放量 |\r\n| `female_rate_min` | number | 否 | 最小女性受众比例（0~100） |\r\n| `lang` | string | 否 | 响应语言：`cn` / `en`，仅控制返回字段翻译，不筛选达人 |\r\n| `service_level` | string | 否 | 服务等级，默认 `S1` |\r\n\r\n### 跨平台搜索说明\r\n\r\n设置 `target_platform` 与种子达人不同平台，可发现跨平台相似达人：\r\n\r\n```bash\r\n# 从 TikTok 达人找 YouTube 上的相似创作者\r\nnode ../../scripts/find_lookalike.mjs '{\"username\":\"creator_demo\",\"platform\":\"tiktok\",\"target_platform\":\"youtube\",\"limit\":10}'\r\n```\r\n\r\n## 输出格式\r\n\r\n```\r\n🔍 找到 N 个与 @seed_username 相似的达人\r\n\r\n📊 相似达人列表\r\n\r\n| #   | 用户名      | 昵称        | 粉丝数  | 平均播放 | 互动率  | 相似度  | 国家 | 主页链接          |\r\n| --- | ----------- | ----------- | ------- | -------- | ------- | ------ | ---- | ----------------- |\r\n| 1   | username1   | Nickname1   | 120K    | 3.8万    | 7.20%   | 85.0%  | US   | [查看][link1]     |\r\n| 2   | username2   | Nickname2   | 95.5K   | 2.1万    | 5.50%   | 78.3%  | US   | [查看][link2]     |\r\n\r\n[link1]: https://www.tiktok.com/@username1\r\n[link2]: https://www.tiktok.com/@username2\r\n\r\n📈 统计信息\r\n• 种子达人：@seed_username（平台ID：7123456789）\r\n• 结果总数：N 个相似达人\r\n• 本次消耗：10 积"},{"path":"discovery/creator-search/SKILL.md","content":"---\nname: creator-search\ndescription: |\n  三平台达人搜索能力，支持 TikTok、YouTube、Instagram 多维度筛选（关键词、国家、粉丝数、互动率、类目等）。\n  Use when: 达人搜索, KOL搜索, 找达人, creator search, influencer discovery, search creators\ncompatibility: Node.js 20.6+\nmetadata:\n  layer: discovery\n  parent: creator-scraper-cv\n---\n\n# Creator Search（达人搜索）\n\n## 概述\n\n三平台（TikTok、YouTube、Instagram）达人实时搜索，支持关键词、国家、粉丝数、互动率、行业等多维度筛选，结果即时返回。\n\n## 脚本引用\n\n| 脚本 | 相对路径 | 状态 |\n|------|----------|------|\n| search_creators.mjs | `../../scripts/search_creators.mjs` | ✅ 可用 |\n\n调用格式：\n\n```bash\nnode {baseDir}/scripts/search_creators.mjs '{\"platform\":\"tiktok\",\"country_code\":\"US\",\"gender\":\"0\",\"followers_cnt_gte\":100000,\"service_level\":\"S2\"}'\n```\n\n## 参数提取强制规则\n\n1. `platform` 必须转换为小写：`tiktok` / `youtube` / `instagram`。\n2. 达人性别必须映射为编码：女性/女/female → `\"0\"`，男性/男/male → `\"1\"`。禁止传 `\"女性\"`、`\"男性\"`、`\"female\"`、`\"male\"`。\n3. 所有比例筛选参数使用 **0~100 的百分比数值**：用户说“互动率至少 3%”时传 `3`，不能传 `0.03`；“女性受众至少 70%”传 `70`。\n4. boolean 参数必须传 JSON boolean：`true` / `false`，不能传 `\"true\"` / `\"false\"`、`1` / `0`。`has_email`、`has_whatsapp`、`is_ai_creator`、`is_product_kol` 等均属于 boolean。\n5. 国家和语言必须转换为代码；多选使用英文逗号连接，例如 `country_code: \"US,CA\"`、`language_code: \"en,fr\"`。\n6. 日期筛选统一传 `YYYY-MM-DD`。\n7. `lang` 只控制响应码值翻译，不用于筛选达人，默认 `en`。筛选达人内容语言使用 `language_code`。\n8. 只传目标平台支持的字段。三平台播放量、互动率、受众语言等字段名并不完全相同。\n9. 当前 HTTP Open API 不支持 Instagram 的 GMV、销售商品数筛选，不要发送这些字段。\n10. 不要发送旧字段名。HTTP Open API 请求模型会忽略未声明字段，旧字段可能请求成功但实际没有产生筛选效果。\n11. **行业 vs 关键词的决策逻辑**：\n    - **用户明确指定**\"行业\"或\"关键词\"时，按用户意图走,不要替换。例如用户说\"关键词搜 funny\"就用 `keyword`，说\"行业选美妆\"就用 `industry`。\n    - **用户未明确区分**时（如\"找搞笑达人\"、\"美妆博主\"），优先映射为 `industry`。常见映射：搞笑/funny → Comedy & Humor, 美妆/beauty → Skincare 或 Beauty, 科技/tech → Technology, 宠物/pet → Pet Supplies, 美食/food → Food & Beverage。\n    - **行业搜索结果为空时**（返回 0 条），自动用同义词降级为 `keyword` 重新搜索,并告知用户\"行业筛选无结果,已改用关键词搜索\"。例如 `industry: \"Comedy & Humor\"` 返回空 → 用 `keyword: \"funny\"` 重搜。\n    - `keyword` 仅用于：搜索具体用户名/昵称、精确主题词、或行业降级兜底。\n\n## 服务等级\n\n`service_level` 控制返回字段与积分消耗。面向用户发起搜索前，必须让用户清楚三档含义：\n\n- 用户未指定等级时，先展示下方简短表格，并说明默认推荐 `S2`。\n- 用户确认“默认/推荐/直接搜”时，使用 `S2`。\n- 用户明确指定 `S1` / `S2` / `S3`，或本轮对话已展示过等级说明时，可直接执行，避免重复打断。\n\n| 等级 | 名称 | 积分/条 | 返回范围 |\n|------|------|---------|----------|\n| S1 | 纯名单筛选 | 1 | 基础身份、主页、联系方式存在性、最近发布时间；具体字段因平台而异 |\n| S2 | 精准触达 | 3 | S1 + 国家、性别、粉丝/播放/互动、行业、邮箱等；具体字段因平台而异 |\n| S3 | 深度画像 | 4 | S2 + 受众性别、国家、语言、年龄分布 |\n\n## 通用请求参数\n\n除 `platform` 为脚本路由参数外，其余字段会作为 JSON Body 发送到对应平台搜索接口。\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `platform` | string | 必填：`tiktok` / `youtube` / `instagram` |\n| `keyword` | string | 搜索关键词 |\n| `country_code` | string | 国家代码，多选逗号分隔 |\n| `gender` | string | `\"0\"`=女性，`\"1\"`=男性 |\n| `has_email` | boolean | 是否有邮箱 |\n| `language_code` | string | 达人内容语言代码，多选逗号分隔 |\n| `followers_cnt_gte` / `followers_cnt_lte` | integer | 粉丝数/订阅数范围 |\n| `industry` | string | 行业类目；脚本支持类目 ID、中文/英文名称和常用别名 |\n| `audience_country_code_list` | string | 受众国家代码，多选逗号分隔 |\n| `audience_age_list` | string | 受众年龄，多选逗号分隔 |\n| `audience_female_rate_gte` / `audience_female_rate_lte` | number | 受众女性比例，传 0~100 百分比数值 |\n| `page` | integ"},{"path":"outreach/creator-outreach/SKILL.md","content":"---\r\nname: creator-outreach\r\ndescription: |\r\n  邮件建联全流程能力，覆盖发送、任务查询、沟通历史、待办跟进、效果指标、渠道配置、附件上传。平台代发机制，无需用户提供 SMTP 配置。\r\n  Use when: 建联, 发邮件, 批量发送, email outreach, send email, outreach\r\ncompatibility: Node.js 20.6+\r\nmetadata:\r\n  layer: outreach\r\n  parent: creator-scraper-cv\r\n---\r\n\r\n# Creator Outreach — 邮件建联\r\n\r\n## 概述\r\n\r\n邮件建联全流程能力：搜索达人后一键发送邮件，支持单发/批量发送、任务轮询、沟通历史查询、待办跟进、效果指标分析，平台统一代发无需用户配置。\r\n\r\n## 脚本引用\r\n\r\n| 脚本路径 | 状态 | 说明 |\r\n|----------|------|------|\r\n| `../../scripts/outreach_send.mjs` | ✅ 已实现 | 发送邮件（单发/批量） |\r\n| `../../scripts/outreach_task.mjs` | ✅ 已实现 | 查询发送任务状态与结果 |\r\n| `../../scripts/outreach_contact.mjs` | ✅ 已实现 | 查询联系人沟通历史 |\r\n| `../../scripts/outreach_todo.mjs` | ✅ 已实现 | 待办跟进（超时/未读） |\r\n| `../../scripts/outreach_metrics.mjs` | 🔮 待实现 | 效果指标（发送量/打开率/回复率） |\r\n| `../../scripts/outreach_config.mjs` | 🔮 待实现 | 渠道与模板配置查询 |\r\n| `../../scripts/outreach_upload.mjs` | 🔮 待实现 | 附件上传（max 10MB） |\r\n\r\n> 🔮 标注的脚本尚未部署，调用将返回错误。待后端实现后可直接启用。\r\n\r\n## 架构原则\r\n\r\n**Skill = 纯 HTTP 客户端，不做任何本地业务逻辑处理。**\r\n\r\n- 脚本只负责组装 JSON 参数并调用 OpenAPI 接口\r\n- 所有业务逻辑（创建提报、查找会话、判断新建/回复）由 OpenAPI 内部完成\r\n- Skill 不需要知道 `submission_id`、`influencer_id` 等内部概念\r\n- 搜索后发送时，将搜索结果中的 `uid` + `platform` 传给 outreach_send，OpenAPI 内部自动从 Holo 查完整达人数据\r\n\r\n## 发送机制\r\n\r\n**邮件由 Creativault 平台后端统一代发（AWS SES），用户无需提供任何发信配置。**\r\n\r\n- **[禁止]** 向用户索要 SMTP 配置、邮箱密码、授权码、发信服务器地址\r\n- **[禁止]** 建议用户\"用自己的邮箱手动发送\"——平台已具备发送能力\r\n- `channel` 参数当前仅 `ses` 生效（默认值）；`gmail`/`outlook` 为预留字段，后端未实现\r\n- 若用户问\"邮件怎么发出去的\" → 回答：\"由 Creativault 平台统一代发，无需配置任何邮箱或 SMTP。\"\r\n\r\n## 参数说明\r\n\r\n### outreach_send.mjs\r\n\r\n`to` 和 `recipients` 互斥，传其一。\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `to` | string | 收件人邮箱（单发） |\r\n| `uid` | string | 达人平台 UID（单发必填，来自搜索结果的 uid 字段） |\r\n| `nickname` | string | 达人昵称（可选，用于会话展示） |\r\n| `platform` | string | 达人平台：tiktok/youtube/instagram |\r\n| `recipients` | object[] | 批量发送：`{email, uid, nickname, platform}` 数组 |\r\n| `subject` | string | 邮件主题 |\r\n| `body_html` | string | HTML 正文（支持 `{{creator_name}}` 变量） |\r\n| `body_text` | string | 纯文本正文 |\r\n| `channel` | string | `ses`（默认，唯一生效渠道） |\r\n| `template_id` | integer | 模板 ID（覆盖 subject/body） |\r\n| `send_mode` | string | `immediate`（默认）/ `smart`（时区优化） |\r\n| `force_new` | boolean | 强制新建会话（默认 false） |\r\n| `attachment_ids` | string[] | 附件 ID 列表 |\r\n\r\n### outreach_task.mjs\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `task_id` | string | **必填**。发送返回的任务 ID |\r\n| `include_result` | boolean | 附带逐收件人结果（默认 false） |\r\n| `result_filter` | string | 结果过滤：`all`/`sent`/`failed` |\r\n| `poll` | boolean | 自动轮询至终态（默认 false） |\r\n| `poll_interval` | integer | 轮询间隔秒数（默认 5） |\r\n| `poll_max_attempts` | integer | 最大轮询次数（默认 60） |\r\n\r\n### outreach_contact.mjs\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `email` | string | **必填**。达人邮箱 |\r\n| `include_history` | boolean | 包含消息历史（默认 true） |\r\n| `include_summary` | boolean | 包含 AI 摘要（默认 true） |\r\n\r\n### outreach_todo.mjs\r\n\r\n| 参数 | 类型 | 说明 |\r\n|------|------|------|\r\n| `overdue_hours` | integer | 超时阈值小时数（默认 24） |\r\n| `include_unread` | boolean | 包含未读会话（默认 true） |\r\n| `include_overdue` | boolean | 包含超时会话（默认 tru"},{"path":"SKILL.md","content":"---\r\nname: creator-scraper-cv\r\ndescription: |\r\n  Creativault creator data collection and outreach skill. Search and collect creator/influencer\r\n  data from TikTok, YouTube, Instagram, and Twitter. Send outreach emails to discovered creators with\r\n  automatic conversation management, batch sending, and follow-up tracking.\r\n  Supports multi-dimensional search, similar/lookalike creator discovery, batch collection by\r\n  links/usernames/keywords, task tracking, data export (xlsx/csv/html), and email outreach\r\n  (single/batch send, templates, smart timing, metrics).\r\n  Use when: creator search, influencer scraping, KOL search, KOL analytics,\r\n  social media data extraction, TikTok scraper, YouTube scraper, Instagram scraper, Twitter scraper,\r\n  influencer discovery, similar creators, lookalike, outreach, email outreach,\r\n  send email to creator, batch email, follow-up, 达人采集, KOL 搜索, 网红数据,\r\n  达人分析, 达人搜索, 相似达人, 社交媒体数据, 建联, 发邮件, 批量发送.\r\ncompatibility: Node.js 20.6+\r\nmetadata:\r\n  author: creativault\r\n  version: \"1.8.0\"\r\n---\r\n\r\n# Creativault Creator Ecosystem\r\n\r\n## 生态总览\r\n\r\n| 领域 | 子 Skill | 能力描述 |\r\n|------|----------|----------|\r\n| discovery | creator-search | 三平台达人多维度实时搜索 |\r\n| discovery | creator-lookalike | 种子达人相似匹配与跨平台发现 |\r\n| collection | creator-collection | 批量异步采集与多格式导出 |\r\n| outreach | creator-outreach | 邮件建联全流程（代发、跟进、待办） |\r\n| workflow | workflow | 剧本式工作流编排与 AI 自主调度 |\r\n\r\n## 路由索引\r\n\r\n| 子 Skill | 中文关键词 | 英文关键词 | 路径 |\r\n|----------|-----------|-----------|------|\r\n| creator-search | 达人搜索, KOL搜索, 找达人 | creator search, influencer discovery, search creators | discovery/creator-search/SKILL.md |\r\n| creator-lookalike | 相似达人, 类似达人 | similar creators, lookalike, find similar | discovery/creator-lookalike/SKILL.md |\r\n| creator-collection | 批量采集, 数据导出, 离线采集 | batch collection, data export, keyword collection | collection/creator-collection/SKILL.md |\r\n| creator-outreach | 建联, 发邮件, 批量发送 | email outreach, send email, outreach | outreach/creator-outreach/SKILL.md |\r\n| workflow | 工作流, 流程编排, 批量建联流程 | workflow orchestration, campaign flow, batch outreach flow | workflow/SKILL.md |\r\n\r\n**路由规则**：AI Agent 根据用户意图匹配上表关键词，加载对应子 skill。无法匹配时展示本表供用户选择。\r\n\r\n## Prerequisites\r\n\r\nOptional update variables:\r\n\r\n- `CV_SKILL_UPDATE_MANIFEST_URL` - Remote manifest URL for skill update checks.\r\n- `CV_SKILL_AUTO_UPDATE=true` - Allow automatic update when the API reports this skill is outdated.\r\n\r\nManual check:\r\n\r\n```bash\r\nnode scripts/skill_update.mjs --check\r\n```\r\n\r\nConfirmed update:\r\n\r\n```bash\r\nnode scripts/skill_update.mjs --yes\r\n```\r\n\r\nGenerate release manifest:\r\n\r\n```bash\r\nnode scripts/generate_manifest.mjs --note \"Describe this release\"\r\n```\r\n\r\nSet the following environment variables:\r\n\r\n- `CV_API_KEY` — Creativault Open API Key (obtain from admin dashboard)\r\n- `CV_USER_IDENTITY` — Operator email address\r\n- `CV_API_BASE_URL` (optional) — API base URL, defaults to `http://api.creativault.vip`\r\n\r\n**Linux / macOS**:\r\n\r\n```bash\r\nexport CV_API_KEY=cv_live_your_key_here\r\nexport CV_USER_IDENTITY"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1697,"uniquenessScore":37,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T14:34:01.311Z","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-10T14:34:01.311Z","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-10T17:34:12.582Z","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"}]}}}