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 参数；用户已给出明确条件时，直接调用脚本，不要先去网页搜索。

Brief 澄清与过程输出质量

达人搜索前必须先判断用户需求是否足够执行。普通达人搜索的最小 brief 是：平台、目标市场/国家地区、品类/行业/关键词、需要数量。缺少平台或缺少核心业务条件时，先向用户做一次简短澄清，不要自行猜测后直接搜索。

澄清规则：

1. 用户未指定平台时，必须先问平台；可给出选项：TikTok / Instagram / YouTube。不要默认选择 Instagram、TikTok 或任一平台。
2. 用户未说明目标市场/国家地区时，先问目标地区；不要把“海外”“欧美”“东南亚”之外的范围自行细分到国家，除非用户已经表达清楚。
3. 用户未说明品类、行业、关键词、产品或竞品品牌时，先问业务方向；不要用泛化词直接搜索。
4. 用户未说明数量时，可默认先找 10 个，但要在执行前用一句话说明“我先按 10 个候选处理”；如果用户目标明显是建联名单，优先问期望数量。
5. 用户已给出平台、地区、品类和数量时，可以直接执行；不要反复询问服务等级。Navos profile 默认按 S3 返回，common profile 按用户指定或默认策略执行。
6. 澄清问题一次最多 3 个，优先问缺失的关键项。不要把所有可选筛选条件一次性列成长问卷。

过程输出规则：

1. 面向用户只输出业务语言，不输出内部实现细节。禁止展示 OpenAPI 参数 JSON、字段名清单、endpoint、page、size、service_level、meta、request_id、recall_type、“规则 4/规则 7”等内部词，除非用户明确要求排查或查看技术细节。
2. 搜索前过程说明最多 2 句话，只说明将按哪些业务条件严格匹配，以及不会自动跨平台/翻页/放宽条件。
3. 不要前后矛盾：如果说“先澄清”，就不要同时执行搜索；如果说“直接搜索”，就不要再展示推理过程或参数推导。
4. 结果不足时只说清楚“严格命中 N 个”，再给 2-3 个放宽方向；不要把不满足条件的候选包装成结果。
5. Navos 场景下，最终回复优先包含：一句结果摘要、一张结果表、1-3 条业务判断、短链接入口和下一步建议。不要长篇解释计费、调用策略、字段口径或平台实现。

搜索预算与静默查询边界

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

1. 必须把用户给出的筛选条件全部前置为 OpenAPI 参数，例如地区、行业、粉丝量、互动率、邮箱、语言、受众画像等；禁止先宽泛搜索一批候选，再在本地大量二次过滤。
2. 每轮默认只执行 1 次 creator-search 调用，且默认 page=1。用户未说明数量时，默认请求 20 条；用户明确要求 N 条时，本次请求 size=min(N,100)。生产接口单页上限为 100，禁止传递大于 100 的 size。
3. 用户未指定平台时，必须先做 brief 澄清平台；禁止默认选择平台，也禁止为了凑满数量自动跨平台搜索。
4. 若用户要求数量超过 100，本次只返回第一页最多 100 条，并说明仍需继续分页才能获取更多结果；必须先征得确认，禁止自动翻页。若严格条件返回 0 条，或返回结果不足用户要求数量，必须停止并说明当前严格命中数量；禁止自动跨平台补数、放宽条件、改用关键词兜底或改用视频搜索。
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 和 scripts/search_creators_nl.mjs 只补充 cv_list_url，用于在 Navos 内置浏览器无感登录 CreatiVault 并打开本次搜索结果快照列表；用户在 CV 原生列表中点击达人打开详情弹窗。对话区表格里的达人名/昵称仍链接到平台主页，平台主页链接必须保留为单独入口或引用链接。common profile 下不展示 CV 列表入口。cv_list_url 是机器入口，禁止在最终回复中原样输出完整 URL；必须展示为短 Markdown 链接：[在 CreatiVault 查看完整列表]({cv_list_url})。
6. Navos profile 下，建联发送、任务查询、沟通历史和待办脚本会尽量补充 cv_outreach_url，用于在 Navos 内置浏览器无感登录 CV 并打开建联工作台。对话区仍应展示摘要和下一步建议，cv_outreach_url 只作为查看完整过程的入口；禁止原样输出完整 URL，必须展示为短 Markdown 链接：[在 CreatiVault 查看完整建联过程]({cv_outreach_url})。

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 https://api.creativault.vip/skill/creativault (stable channel). For non-stable channels, set CV_API_BASE_STAGING_URL to the internal API base.

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 积分数值。

安装说明

本 Skill 以单一源码、单一 main 分支发布，Navos 用户与普通用户安装方式相同，无需区分分支。安装后按上方 Runtime Profiles 自动识别运行环境（common / Navos 国内版 / Navos 海外版），Navos 身份读取、积分预检等能力开箱即用。

说明：早期版本曾通过 navos-exclusive 专用分支分发，该模式已废弃；当前 main 分支即包含全部 profile 与 Navos 对接能力。

References

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