easykol

EasyKOL

适用于完整工作流的创作者情报技能，可在 YouTube、TikTok 和 Instagram 上发现创作者、分析创作者资料与受众、批量提取电子邮件，以及分析视频。

用户通过自然语言交互。由你执行 CLI 命令，并用通俗语言报告结果。绝不要向用户透露原始 CLI 命令或 JSON。

适用场景

• 用户想寻找符合某种描述的创作者／网红／KOL
• 用户想寻找与现有创作者相似的创作者
• 用户想查看创作者资料、粉丝数或联系信息
• 用户想了解受众人口统计信息：年龄、性别、地区或虚假粉丝率
• 用户想批量提取一组创作者 URL 对应的电子邮件
• 用户想分析视频（观看次数、点赞数、作者）
• 用户需要设置 EasyKOL 访问权限或查看剩余额度

此技能不提供的功能

• 发布内容、发送私信或与社交平台互动
• 返回 EasyKOL 数据库中尚无的内容
• 替用户做出最终的活动预算或合作决策
• 起草外联邮件或谈判文案
• 在 ChatGPT 中运行（需要 CLI 执行环境）

核心原则

Agent 优先

用户不操作 CLI，由你操作。静默运行命令，并用通俗语言报告结果。只有在用户需要通过浏览器执行操作时（充值、身份验证），才分享 URL。

CLI 自述

CLI 会说明自身用法——使用它，而不是死记参数：

• 命令架构：easykol schema <cmd>（例如 schema kol、schema search-v2）
• 完整命令树：easykol schema --all
• 退出代码：easykol exit-codes
• 诊断：easykol doctor

路由速查表

用户意图	命令
查看搜索任务／继续执行下一批	task --task-id / search-next --task-id（使用相同的数据来源模式和筛选条件）
查找符合某种描述的创作者	`search-v2 --mode fast
查找与某个 URL 相似的创作者	similar
通过 URL 获取创作者资料	kol
获取创作者的受众细分数据	audience
获取一组创作者 URL 对应的电子邮件	emails
通过 URL 分析视频／帖子	video
查看剩余额度	quota
设置／诊断	auth、doctor、upgrade

使用具体标志前，务必先运行 easykol schema <cmd>。

---

1. 开始使用

每次 EasyKOL 会话开始时，先静默刷新工具（不要询问用户；除非出现故障，否则不要说明）：

1. 如果已安装 CLI，优先运行 easykol upgrade。
2. 否则运行以下两项（尽力执行；失败时继续）：

   npm install -g @easykol/cli@latest
   npx --yes skills update easykol -y
   

3. 成功刷新技能后，在任何付费搜索之前，重新读取此技能的 SKILL.md 和 references/quota-heuristics.md，以便当前会话应用最新预算规则。

然后运行 easykol doctor，只修复缺失项：

1. 缺少 CLI → 请用户运行 npm install -g @easykol/cli@latest。
2. 没有 API 密钥（hasApiKey: false）→ 向用户索取密钥和电子邮件，然后：

   printf '%s' "<KEY>" | easykol auth --key-stdin --email <email>
   

   绝不要将密钥作为位置参数传入或记录密钥。
3. 已配置 → 运行 easykol quota 并报告任何阻塞问题。
4. 如果 doctor 报告 updateAvailable: true，则在搜索前再运行一次 easykol upgrade。

---

2. 发现创作者

将自然语言请求转化为相关创作者候选名单。

选择模式

使用 CLI 0.2.0 或更高版本以及外部 V2 后端。请阅读 {baseDir}/references/search-modes.md，了解请求 / 结果契约。

用户意图	模式	现有 Web 流程	每批目标数量
快速筛选名单，未指定模式	fast（默认；告知用户）	模式 8 历史数据，已存储数据 + 文本相关性，后台刷新	60
普通 / 标准搜索	standard	模式 8 常规搜索，画像相关性 + 实时刷新和硬性筛选条件复核	50
Beta / Pro、产品推广匹配度或视觉筛选	beta	模式 7，产品要求 + 可选视觉筛选	50

绝不静默替换模式。Beta 每次请求恰好允许一批。 继续现有搜索任务时，保留其模式和筛选条件；继续前请阅读 {baseDir}/references/pro-pagination.md。

搜索工作流

1. 预先检查用户的硬性要求。搜索支持创作者平台、 地区 / 语言、粉丝数 / 表现范围、创作者性别和是否有联系方式。 受众人口统计信息需要单独进行 audience 分析；TikTok Shop 履约率等不受支持的指标 必须保持未验证状态。不要将不受支持的硬性条件转换为关键词后声称已验证。
2. 根据上下文推断平台、国家和所需模式。若缺少关键的平台信息，只询问一次。 将所有目标国家放入同一个 --regions 列表；用户未指定的筛选条件应省略，不要自行设定阈值。 消费者目标年龄 / 性别应通过 Beta 的 --product / --audience 指定，而非创作者筛选条件。
3. 默认提交一次 search-v2。CLI 会在付费请求前获取免费的模式专属准备方案和报价。 parse-v2 可用于展示 / 编辑方案，并非必需的用户确认环节。 用户现有授权适用于其指定范围和预算内的所有必要步骤。
4. 保留返回的 taskId 和 idempotencyKey。默认情况下，search-v2 会等待结果可读； --no-wait 会立即返回。超时不代表搜索失败。免费恢复任务请运行 task --task-id <id>；若提交结果不确定，请根据已保存的本地日志使用 search-v2 --idempotency-key <original-key> 恢复。 绝不要因为轮询超时而启动替代性的付费搜索。
5. 从可读结果中提供所需数量的结果，并按 kolId / URL 去重；根据返回字段核实受支持的硬性条件。 缺失的指标、screening=unverified 或不受支持的要求都应保持未验证状态。诚实说明 部分符合条件的候选者。存在联系方式并不能证明邮箱公开或可交付；如有要求，应统计实际非空邮箱的数量。

RESULT_READY 表示可以读取结果，不表示处理 / 结算已完成。 COMPLETED 且 settlement.pending=true 时，仍需等待退款核对。 未知阶段的数量为 null，而非零。绝不要将失败或未完成的任务标记为零召回，也不要将未知判断视为拒绝。

阅读更多结果并继续搜索

• task --task-id <id> --offset 50 --limit 50 可免费读取另一页已存储的结果。 请求另一个付费批次前，先读完现有任务的 nextOffset。
• 当已授权的目标需要另一个批次时，等待任务变为 COMPLETED，然后使用新的幂等键运行 search-next --task-id <latest-id>。该命令会继承模式、平台和筛选条件。 从每个返回的子任务按顺序继续；不要从更早的父任务分支，也不要并行继续搜索。
• 达到用户要求的数量后停止。批次目标数量并非保证数量。若结果不足，应说明原因，不要自动更换模式、 放宽筛选条件或运行无关搜索。

预算控制

CLI 预留的是服务端报价，而不是显示的行数。1 个任务点等于 10 个原始配额。共享的滚动 CLI 搜索预算默认是每个 2 小时窗口 50 个原始配额（5 个点）；最终退款会在读取任务时进行结算。详情请参阅 {baseDir}/references/quota-heuristics.md。

默认使用一个批次。对于用户授权的较大计划，将各批次的报价相加，并在该授权范围内继续；无需在每个阶段重复请求许可。如果计划超出用户批准的范围或预算，或 CLI 返回退出码 8，请说明额外费用，并在使用 --confirm-spend 前获得批准。已有的明确授权在后续轮次中仍然有效；切勿凭空假设用户已授权。

针对不同细分领域，请使用聚焦的搜索句，并共用国家/地区和筛选设置，然后合并并去重结果。每次搜索都有单独的批次报价：减少显示数量不会降低价格。确保合并后的计划在用户授权的预算范围内。estimatedTotal 不是完整的候选池。

旧版兼容性

search / parse 保留其原有的 V1 名称、选项和行为。它们不遵循 V2 搜索约定，也不支持任务续接。more-words 也是 V1 工具。如果 V2 返回 404 或特定模式的请求失败，请勿悄悄改用这些工具；应报告后端/版本不匹配。现有的 profile、video、emails、similar 和 audience 命令会继续使用各自原有的端点。

相似账号发现

当用户想寻找与特定频道相似的创作者时，使用 easykol similar --url <profile-url>。这是异步操作，耗时约 30 秒；请告知用户你正在搜索。

可选筛选条件：--regions、--languages、--min-subscribers、--max-subscribers、--min-avg-views、--max-avg-views。--dedup-days（默认值为 3）会跳过近期已见过的创作者；设为 0 可禁用。

按与 search 结果相同的方式呈现结果。

---

3. 评估创作者

帮助用户判断是否值得与某位创作者合作。先给出摘要，不要堆砌大量数字。

个人资料

运行 easykol kol --url <profile-url>，获取创作者当前的个人资料：昵称、粉丝数、平均表现、地区、语言和邮箱（如果有记录）。

当用户粘贴创作者 URL 或询问“你能介绍一下这位创作者吗？”时，应首先运行此命令。

受众分析

运行 easykol audience --url <profile-url>，获取：

• 受众画像：年龄分布（18 岁以下 / 18–25 / 25–45 / 45 岁以上）和性别比例
• 地区：受众人数最多的国家/地区，以及其 T1/T2/T3 发展水平
• 虚假粉丝：疑似虚假粉丝比例、虚假粉丝数量、样本总量

结果会缓存 30 天；命中缓存时命令会立即返回。新的分析为异步操作，最多耗时 2 分钟。如果需要等待，请告知用户你正在获取分析结果。

为用户解读结果：重点说明受众是否集中在 T1 市场、性别比例是否符合营销活动的要求，并标出 suspectedFakeRate 是否偏高（超过 20% 需谨慎，超过 40% 则是明显警示）。

请勿根据受众分析声称其结果未包含的精确年龄范围。标准年龄段包含 18–25 和 25–45，无法据此得出 25–40 ≥ 60%。受众分析是针对单个创作者的核验步骤，而非搜索筛选条件，除非 API 明确支持该筛选条件。

4. 获取电子邮件

重要区别：easykol kol 已会返回创作者在平台个人资料中公开显示的电子邮件。用户只询问某位创作者的电子邮件或联系方式时，不要仅因此运行 easykol emails——kol 已涵盖此类信息。

当用户明确想要批量提取一组创作者 URL 的联系邮箱，或想要导出的联系人 Excel 文件时，使用 easykol emails。这是异步操作（约 60 秒）。这不能证明每个地址都是公开、有效或可用的；完成后，请报告缺失结果和覆盖情况。

easykol emails --tt-urls <url1,url2,...>
easykol emails --yt-urls <url1,url2,...>
easykol emails --ins-urls <url1,url2,...>

可组合使用多个标志来处理混合平台批次。每 5 个 URL 消耗 1 个配额（向上取整）。

该命令会返回 Excel 文件的 downloadUrl。告知用户文件已就绪，并分享该 URL。

---

5. 分析视频

运行 easykol video --url <video-url> 获取视频元数据：标题、观看次数、点赞数、评论数、分享数、提供时的 Instagram Repost 次数、发布日期、作者名称和作者粉丝数。shareCount 是分享指标（Instagram 的纸飞机操作）；repostCount 是 Instagram 独立的双箭头 Repost 指标。对于 Instagram，这两个字段均取自 v3 帖子详情响应；不使用 v5 的值。对于任一字段，null 表示 v3 端点未提供该指标（并不表示测得的数值为零）。不要合并或替换这两个字段。

支持：YouTube 视频、TikTok 帖子、Instagram reels/posts。

当用户分享视频链接并想快速查看数据，或想在联系创作者前查看其近期内容时，此工具很有用。

---

错误处理

对于所有失败，请使用 CLI 响应：

• action.url — 用户应前往的位置（充值、验证身份）
• action.hint — 下一步操作

退出代码	含义	操作
2	未通过身份验证	运行 easykol auth --key-stdin --email <email>
3	配额已用尽	停止操作，告知用户；如有 action.url，请分享
4	套餐不包含此功能	说明情况并建议升级
5	网络错误	重试一次，然后报告
6	参数错误	重新读取 easykol schema <cmd>，修正标志后重试
7	速率限制	等待一段时间后重试
8	搜索会话预算	停止操作并询问用户；仅在获得批准后使用 --confirm-spend 重试

对于异步命令（similar、emails、audience），如果命令超时（退出代码为 1，且提示为 "timed out"），请告知用户任务耗时超出预期，并建议使用 --timeout 300 重试。

原因不明确时，先运行 easykol doctor 进行初步诊断。

参考资料

• {baseDir}/references/pro-pagination.md — Pro 单页数据获取、任务续接以及 CLI/API 边界
• {baseDir}/references/search-filters.md — search / parse / more-words 的完整标志参考
• {baseDir}/references/platform-support.md — 各平台和命令的数据可用性
• {baseDir}/references/quota-heuristics.md — 各命令的计费详情
• {baseDir}/references/async-tasks.md — 异步命令（similar / emails / audience）的工作方式
• {baseDir}/references/error-codes.md — 退出代码和输出封装