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	能力描述
发现	creator-search	三个平台的自然语言语义搜索与多维度结构化搜索
发现	video-search	跨平台短视频多维度搜索（Hashtag／标题／播放量／互动率）
发现	creator-lookalike	种子达人相似匹配与跨平台发现
采集	creator-collection	批量异步采集与多格式导出
建联	creator-outreach	邮件建联全流程（代发、跟进、待办）
审核	fake-follower-audit	单个达人的假粉率估算、互动质量和账号风险检测
审核	video-script-audit	单条视频 12 个维度的异步拆解（Hook／选题／痛点／植入／镜头／情绪／文案等）
工作流	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 エージェント根据用户意图匹配上表中的关键词，并加载对应的子 skill。无法匹配时，展示本表供用户选择。

ランタイムプロファイル

この Skill は単一のソースコードを管理し、ランタイムプロファイルによって common／Navos の実行上の違いを制御します。OpenAPI の機能、クリエイター検索の表示ルール、アプローチ文、エクスポート／収集／審査の説明は共有し、2 種類のドキュメントに分けて個別に管理しないでください。

プロファイルの読み込み優先順位：

1. CV_SKILL_PROFILE 環境変数
2. Navos identity ファイル ~/.navos/identity/navos-userinfo.json 内の app_id
3. skill.json 内の profile
4. デフォルトの common

組み込みプロファイル：

プロファイル	認証	言語	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 のメインドメインを共用し、プロファイルによってデフォルトのレスポンス言語、デフォルトのサービスレベル、partner_code を区別します。Navos デスクトップクライアントは identity ファイルに app_id を書き込みます。国内版は navos-cn、海外版は navos-global です。app_id を取得できない場合は、デフォルトで海外版の navos-global として実行します。国内版を CV に登録する際、CV に渡すユーザー ID には区別のため 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"}'

前提条件

Common プロファイルでは、次の更新用変数を任意で設定できます：

• CV_SKILL_UPDATE_MANIFEST_URL - Skill の更新チェックに使用するリモートマニフェスト URL。
• CV_SKILL_AUTO_UPDATE=true - API がこの Skill の古さを報告した場合に、自動更新を許可します。

手動で確認：

node scripts/skill_update.mjs --check

更新を確定：

node scripts/skill_update.mjs --yes

リリースマニフェストを生成：

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

次の環境変数を設定します：

• CV_API_KEY — Creativault Open API Key（管理者ダッシュボードから取得）
• CV_USER_IDENTITY — オペレーターのメールアドレス
• CV_API_BASE_URL（任意）— API ベース URL。デフォルトは https://api.creativault.vip/skill/creativault（安定版チャンネル）です。安定版以外のチャンネルでは、CV_API_BASE_STAGING_URL に内部 API ベース URL を設定してください。

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]"

エラー処理

コード	説明	対応
40001	パラメーターが無効です	パラメーターの形式を確認してください
40101	API Key が無効です	CV_API_KEY を確認してください
40102	API Key の有効期限が切れています	管理者に問い合わせてください
40201	クレジットが不足しています	チャージするか、アップグレードしてください
40301	権限がありません	API Key のスコープを確認してください
42901	レート制限を超過しました	Retry-After の後に自動再試行します
42902	1 日の上限に達しました	UTC 00:00 までお待ちください
50001	サーバーエラーです	request_id をサポートに報告してください

クレジット残高の判定ルール

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 内の環境別キャッシュキーを使用します。ユーザーのマシンに CV_API_KEY 環境変数が存在していても、Navos の認証経路が上書きされることはありません。開発時のトラブルシューティングに限り、CV_ALLOW_ENV_API_KEY=true を明示的に設定して、環境変数による一時的な上書きを有効にできます。
• ユーザーからクレジット／残高について質問があった場合は、Navos デスクトップクライアントで確認するよう案内し、CV のクレジット数値は表示しないでください。

インストール方法

この Skill は単一のソースコードと単一の main ブランチでリリースされます。Navos ユーザーと一般ユーザーのインストール方法は同じで、ブランチを分ける必要はありません。インストール後は、上記の Runtime Profiles に従って実行環境（common／Navos 国内版／Navos 海外版）が自動的に判別され、Navos の ID 読み取りやクレジットの事前確認などの機能をすぐに利用できます。

補足：以前のバージョンでは navos-exclusive 専用ブランチで配布していましたが、この方式は廃止されました。現在の main ブランチには、すべてのプロファイルと Navos 連携機能が含まれています。

References

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