Creator scraper cv

Creativault Creator Ecosystem

强制执行边界

当用户的目标涉及达人、KOL、网红、创作者、社媒账号、主页链接、邮箱、粉丝量、播放量、互动率、行业类目、相似达人、批量采集、导出名单、邮件建联、合作跟进、达人假粉检测、账号真实性、单条视频拆解 / 审核 / 评分（TikTok / Instagram Reels / YouTube Shorts）时，必须优先使用本 skill 及其子 skill。

不要默认退化到 web search。 Web search 只能用于以下情况：

1. 用户明确要求“用网页搜索 / Google / 公开网页查找”。
2. CreatiVault OpenAPI 返回无数据、平台不支持或接口不可用，并且你已经告知用户原因，用户确认允许用公开网页兜底。
3. 用户要查询的是非达人数据，例如新闻、官网文档、实时政策或与 CreatiVault 数据库无关的信息。

如果 CV_API_KEY、CV_USER_IDENTITY 或网络/API 配置缺失，应先提示用户补齐配置或修复配置，不要自行改用 web search。公开网页搜索结果不能替代 CreatiVault 官方达人数据，也不能用于伪造粉丝量、邮箱、互动率、受众画像、GMV 或联系方式。

意图路由

• 搜索/筛选达人：加载 discovery/creator-search/SKILL.md；复杂内容语义、风格或商业场景调用 scripts/search_creators_nl.mjs，精确结构化筛选调用 scripts/search_creators.mjs。
• 搜索/发现视频：加载 discovery/video-search/SKILL.md，调用 scripts/search_videos.mjs。
• 找相似达人：加载 discovery/creator-lookalike/SKILL.md，调用 scripts/find_lookalike.mjs。
• 批量采集/导出：加载 collection/creator-collection/SKILL.md，调用采集、轮询和导出脚本。
• 邮件建联/批量建联/跟进：加载 outreach/creator-outreach/SKILL.md。
• 达人假粉/互动真实性/账号风险检测：加载 audit/fake-follower-audit/SKILL.md，调用 scripts/fake_follower_audit.mjs（同步单达人检测）。
• 单条视频拆解/审核/评分：加载 audit/video-script-audit/SKILL.md，调用 scripts/video_audit_submit.mjs + video_audit_poll.mjs（异步任务）。
• 复合流程，例如"找达人并建联""采集后导出再发邮件""拆解爆款再写 brief""品牌视频发现→分析→建联"：加载 workflow/SKILL.md，由工作流编排子 skill。

执行前应把用户自然语言目标转成 CreatiVault OpenAPI 参数；不确定平台、国家、行业、数量或服务等级时，先做最少必要澄清。用户已给出明确条件时，直接调用脚本，不要先去网页搜索。

搜索预算与静默查询边界

搜索达人时必须优先保护用户的积分可预期性：

1. 必须把用户给出的筛选条件全部前置为 OpenAPI 参数，例如地区、行业、粉丝量、互动率、邮箱、语言、受众画像等；禁止先宽泛搜索一批候选，再在本地大量二次过滤。
2. 默认每轮用户请求只执行 1 次 creator-search 调用；默认 page=1，size 不超过用户要求数量的 2 倍，且最大不超过 20，除非用户明确要求更多结果。
3. 用户未指定平台时，只选择最匹配的 1 个平台先搜；禁止为了凑满数量自动跨平台搜索。
4. 若严格条件返回 0 条，或返回结果不足用户要求数量，必须停止并说明当前严格命中数量；禁止自动翻页、扩大 size、跨平台补数、放宽条件、改用关键词兜底或改用视频搜索。
5. 继续翻页、跨平台、扩大结果数量、放宽条件、切换到视频搜索或使用更高服务等级前，必须先征得用户确认，并说明会产生额外查询消耗。
6. 只展示满足用户筛选条件的达人；如果接口返回数据与用户条件明显不一致，停止并提示可能是字段口径或传参问题，建议用户放宽条件或确认下一步，不要展示无关结果凑数。
7. 自然语言搜索固定按请求计费 15 credits/次，与 limit 和实际返回数量无关；多平台搜索每个平台分别产生一次 15 credits 调用，执行额外平台前必须先告知用户。

Navos S3 展示要求

Navos profile 会在结构化达人搜索脚本中自动注入 service_level: "S3"。S3 不只代表“更准的搜索”，也代表响应里可能包含受众画像字段。展示结构化达人搜索结果时必须把 S3 字段当作用户已付费获取的数据来呈现：

1. 不要只输出摘要表头（例如达人、国家、粉丝、均播、互动率、受众女性、主要受众国家、邮箱）。
2. 默认用一张动态宽表展示同一批达人，S1 / S2 / S3 实际返回且有值的字段都在同一张表里展开；不要再把 S3 受众画像单独拆成第二张表。表格变宽可以横向滚动，但不能因此省略受众女性、受众国家、受众语言、受众年龄等 S3 字段。
3. avatar_url 属于 S1 基础字段。只要接口返回 avatar_url，Navos 搜索结果表必须默认增加独立「头像」列，并用 40px 方形外框裁切渲染；不要只保留达人主页文字链，也不要只裸写 <img width height> 导致 Navos 表格把竖图压窄。头像缺失时该单元格留空，不要编造头像或占位图。
4. 字段只有在接口实际返回且至少一条结果有有效值时才展示；不要编造空缺字段。
5. Navos profile 下，scripts/search_creators.mjs 会尽量为每条结果补充 cv_detail_url。如果该字段存在，达人名/昵称优先链接到 cv_detail_url，用于在 Navos 内置浏览器打开 CreatiVault 只读详情预览页；平台主页链接（TikTok/Instagram profile_url，YouTube channel_url）应保留为单独「平台主页」字段或表格下方引用链接。common profile 或 cv_detail_url 缺失时，达人名/昵称仍链接到平台主页，不要声称能打开 CV 详情。

scripts/search_creators_nl.mjs 是例外：自然语言搜索接口不支持 service_level，只返回固定精简字段。不要把 Navos 的 S3 展示规则套到该接口；如果用户需要完整联系方式或受众画像，应说明需要改用结构化搜索，并在再次调用前征得确认。

生态总览

领域	子 Skill	能力描述
discovery	creator-search	三平台自然语言语义搜索与多维度结构化搜索
discovery	video-search	跨平台短视频多维度搜索（Hashtag/标题/播放量/互动率）
discovery	creator-lookalike	种子达人相似匹配与跨平台发现
collection	creator-collection	批量异步采集与多格式导出
outreach	creator-outreach	邮件建联全流程（代发、跟进、待办）
audit	fake-follower-audit	单达人假粉率估算、互动质量和账号风险检测
audit	video-script-audit	单条视频 12 维度异步拆解（Hook/选题/痛点/植入/镜头/情绪/文案等）
workflow	workflow	剧本式工作流编排与 AI 自主调度

路由索引

子 Skill	中文关键词	英文关键词	路径
creator-search	达人搜索, KOL搜索, 找达人	creator search, influencer discovery, search creators	discovery/creator-search/SKILL.md
video-search	视频搜索, 短视频搜索, 找视频, 按话题搜视频, 品牌视频洞察, 竞品视频洞察, 品牌相关视频, 按播放量搜视频, 按互动率搜视频, 热门视频, 爆款视频	video search, short video search, brand video insight, competitor video insight, search videos by hashtag, search by views, content discovery, trending videos	discovery/video-search/SKILL.md
creator-lookalike	相似达人, 类似达人	similar creators, lookalike, find similar	discovery/creator-lookalike/SKILL.md
creator-collection	批量采集, 数据导出, 离线采集	batch collection, data export, keyword collection	collection/creator-collection/SKILL.md
creator-outreach	建联, 发邮件, 批量发送	email outreach, send email, outreach	outreach/creator-outreach/SKILL.md
fake-follower-audit	假粉检测, 假粉率, 粉丝真实性, 互动真实性, 刷粉, 达人风险	fake follower audit, follower authenticity, engagement authenticity, creator risk	audit/fake-follower-audit/SKILL.md
video-script-audit	视频审核, 视频拆解, 爆款拆解, 分镜拆解, 钩子分析	video audit, video script audit, viral breakdown, storyboard	audit/video-script-audit/SKILL.md
workflow	工作流, 流程编排, 批量建联流程	workflow orchestration, campaign flow, batch outreach flow	workflow/SKILL.md

路由规则：AI Agent 根据用户意图匹配上表关键词，加载对应子 skill。无法匹配时展示本表供用户选择。

Runtime Profiles

本 Skill 维护一套源码，通过 runtime profile 控制 common / Navos 的运行差异。OpenAPI 能力、达人搜索展示规则、建联话术、导出/采集/审核说明应保持共享，不要再复制两套文档分别维护。

Profile 读取优先级：

1. CV_SKILL_PROFILE 环境变量
2. Navos identity 文件 ~/.navos/identity/navos-userinfo.json 中的 app_id
3. skill.json 中的 profile
4. 默认 common

内置 profile：

Profile	认证	语言	Partner Code	默认服务等级	Meta 展示	余额预检
common	CV_API_KEY + CV_USER_IDENTITY	跟随请求	无	不自动覆盖	展示 CV credits / request_id	关闭
navos-cn	Navos 登录态 + ensure/cache	中文 / lang=cn	navos-cn	S3	隐藏 CV credits / request_id / service_level	启用
navos-global	Navos 登录态 + ensure/cache	英文 / lang=en	navos-global	S3	隐藏 CV credits / request_id / service_level	启用

Navos 国内/海外版共用 CreatiVault OpenAPI 主域名；通过 profile 区分默认响应语言、默认服务等级和 partner_code。Navos 桌面端会在 identity 文件中写入 app_id：国内版为 navos-cn，海外版为 navos-global；如果取不到 app_id，默认按海外版 navos-global 运行。国内版注册到 CV 时，传给 CV 的用户身份会加 cn_ 前缀以便区分。

navos-cn / navos-global 会分别作为 partner_code 调用 CV ensure 接口，并在后续 OpenAPI 请求中作为 X-Source 传递。CV 后端需在 open_api_partners 中配置同名记录，由表里的 validate_url / credits_callback_url 决定用户校验和扣费回调域名；旧 navos code 仅用于兼容历史 API Key。Skill 侧不再维护校验/回调域名，余额预检域名则按 navos_region 内置映射选择，并可用 NAVOS_BASE_URL 临时覆盖。

如需临时以通用模式运行当前目录：

CV_SKILL_PROFILE=common node scripts/search_creators.mjs '{"platform":"tiktok","keyword":"beauty"}'

如需临时以 Navos 国内模式运行：

CV_SKILL_PROFILE=navos-cn node scripts/search_creators.mjs '{"platform":"tiktok","keyword":"beauty"}'

如需临时以 Navos 海外模式运行：

CV_SKILL_PROFILE=navos-global node scripts/search_creators.mjs '{"platform":"tiktok","keyword":"beauty"}'

Prerequisites

Common profile 可选更新变量：

• CV_SKILL_UPDATE_MANIFEST_URL - Remote manifest URL for skill update checks.
• CV_SKILL_AUTO_UPDATE=true - Allow automatic update when the API reports this skill is outdated.

Manual check:

node scripts/skill_update.mjs --check

Confirmed update:

node scripts/skill_update.mjs --yes

Generate release manifest:

node scripts/generate_manifest.mjs --note "Describe this release"

Set the following environment variables:

• CV_API_KEY — Creativault Open API Key (obtain from admin dashboard)
• CV_USER_IDENTITY — Operator email address
• CV_API_BASE_URL (optional) — API base URL, defaults to http://api.creativault.vip

Linux / macOS:

export CV_API_KEY=cv_live_your_key_here
export [email protected]

Windows PowerShell:

$env:CV_API_KEY = "cv_live_your_key_here"
$env:CV_USER_IDENTITY = "[email protected]"

Error Handling

Code	Description	Action
40001	Invalid parameters	Check parameter format
40101	Invalid API Key	Check CV_API_KEY
40102	API Key expired	Contact admin
40201	Insufficient credits	Top up or upgrade
40301	No permission	Check API Key scopes
42901	Rate limit exceeded	Auto-retry after Retry-After
42902	Daily quota exhausted	Wait until UTC 00:00
50001	Server error	Report request_id to support

积分余额判断规则

只有 OpenAPI 明确返回错误码 40201 时，才能提示用户“积分不足”。

• meta.quota_remaining 表示当天剩余 API 请求次数，不是积分余额。即使该值为 0、8 或其他较小数字，也禁止解释为“剩余积分”或提示充值。
• meta.credits_remaining 才表示真实 OpenAPI 积分余额；字段缺失或值为 -1 时，不要自行估算余额。
• meta.credits_consumed 只表示本次请求消耗的积分。
• 请求成功时，不要因为任何 quota 数值主动发布“积分余额不足提醒”。
• 只有收到 40201 后，才停止后续付费调用并提示用户充值或调整任务规模。

Navos 用户专属说明

Navos 用户（通过 Navos 桌面端使用本 Skill 的用户）的积分管控由 Navos 侧负责，与 CV 积分体系相互独立：

• 积分余额：Navos 用户不展示 CV 积分余额（脚本会自动隐藏 credits_remaining / credits_consumed / quota_remaining 字段）。用户的积分余额在 Navos 桌面端查看。
• 积分预检：脚本在调用 CV 接口前会自动查询 Navos 余额，不足时直接拦截并提示"请在 Navos 端充值"。
• 默认服务等级：Navos 用户搜索达人时默认使用 S3（深度画像，含受众画像等完整字段），无需用户手动指定。
• 凭证优先级：Navos 专用版默认使用 Navos 登录态和 ~/.creativault/skill-credentials.json 中的环境化缓存 key；即使用户机器上存在 CV_API_KEY 环境变量，也不会覆盖 Navos 授权链路。仅开发排障时可显式设置 CV_ALLOW_ENV_API_KEY=true 临时启用环境变量覆盖。
• 若用户询问积分/余额相关问题，引导其到 Navos 桌面端查看，不要展示 CV 积分数值。

Navos 用户安装引导

Navos 用户安装本 Skill 时，应使用专用的 navos-exclusive 分支（针对 Navos 桌面端环境优化，含积分体系对接、身份读取、自动配置等能力）。

安装方式（任选其一）：

1. CLI 安装（推荐）——使用 skills add 命令时指定分支：

   npx skills add creativault/skills#navos-exclusive
   

   ⚠️ 直接执行 npx skills add creativault/skills 会安装默认 main 分支，Navos 用户必须加 #navos-exclusive 后缀。

2. 手动克隆/下载——从 GitHub 指定分支获取：

   • Navos 用户：https://github.com/creativault/skills/tree/navos-exclusive
   • 普通用户：https://github.com/creativault/skills/tree/main（默认）
   • 开发/测试：https://github.com/creativault/skills/tree/dev

⚠️ Navos 用户如果安装了 main 或 dev 分支，可能缺少 Navos 身份读取、积分预检等能力。安装后如遇身份认证失败（如 "Partner user validation failed"），请确认是否使用了 navos-exclusive 分支。

References

• API Reference
• Platform Parameters
• Industry Categories
• Country Codes
• Language Codes
• Error Codes