Tiktok Research

🚀 TikTok数据分析与市场调研

1. 能力概览

💡一句话价值：一个口语化指令拿到TikTok公开的视频/作者/评论数据，直接输出结构化JSON——做数据分析、市场调研、爆款选题、对标账号监控、评论舆情分析、热点追踪，不用再手动刷TikTok。

前置条件：必须在技能根目录执行，且环境变量 GUAIKEI_API_TOKEN 已配置。未配置时所有命令返回退出码 3、error_code=AUTH_REQUIRED——此时直接提示用户配置 Token，不要重试、不要换参数。

2. 何时调用 / 何时不调用

2.1 应该调用

• 用户要查 TikTok 的公开内容（视频 / 图文 / 作者 / 评论 / 趋势）。
• 用户要做爆款选题调研、竞品账号监控、红人筛选、评论舆情分析、内容风格拆解。
• 用户已给出 TikTok 关键词、视频链接、博主主页链接，希望拿到结构化数据。
• 用户拿到数据后还要继续做总结、对比、排序、聚类、出报告 / 表格。

2.2 不应调用

• 用户只要文案 / 标题 / 脚本，没有要查 TikTok 数据。
• 平台不是 TikTok，而是其他平台的（抖音、小红书、B 站、微博、公众号）→ 路由到对应技能。本技能只处理 TikTok。
• 要求登录态、私密、隐藏数据 → 不支持。
• 既有关键词又有可识别链接且目标不明 → 先追问，不要猜。

2.3 能力边界（明确不做）

发布 / 点赞 / 评论 / 关注 / 私信等写操作一律不支持；不登录任何账号；不采集手机号、位置、私信等隐私字段；不替用户做营销决策——职责是把数据拿回来，分析交给上层。

3. 调用路由（先判断，再执行）

3.1 消歧义规则（必须遵守）

1. 单独出现"视频"二字，不要默认归 post-cli。
   • 有"关键词"且无"评论" → search-cli（用户想搜这类视频）。
   • 明确"这个视频的评论 / 留言" → comment-cli。
   • 只有出现"作品 / 主页 / 账号 / 博主 / 达人" → post-cli。
2. 评论优先级高于作品：若给的链接是 /video/<id> 且问的是评论 → comment-cli；若问的是"这个人的作品" → post-cli（用 @username）。
3. 用户给了 /video/<id> 链接却要"作品列表" → 先确认是要该作者的作品还是该视频的评论。

3.2 参数推断规则

默认值：sort=0、time=0、limit=10。

⚠️ 搜索的 --sort 与作品的 --sort 不要混用：前者是"相关度 / 最多点赞"，后者是"最新 / 最热"。

任何参数被非法值回退，都会出现在输出 JSON 的 warnings 数组里，必须回显给用户，不要当成原样生效。

4. 执行方式

完整参数说明见 references/options.md；字段级 Schema 见 assets/ 下的 6 个 JSON Schema（draft-07）。

# 关键词搜索
node scripts/tiktok/search-cli.js --keyword "AI" --sort 1 --limit 20
node scripts/tiktok/search-cli.js --keyword "AI model" --time 7 --limit 20

# 博主作品
node scripts/tiktok/post-cli.js --url "https://www.tiktok.com/@username" --limit 30
node scripts/tiktok/post-cli.js --url "https://www.tiktok.com/@username" --sort 1 --limit 30

# 视频评论
node scripts/tiktok/comment-cli.js --url "https://www.tiktok.com/@username/video/1234567890123456789" --limit 40

可用的输入形态

• 博主：https://www.tiktok.com/@username、带参数链接 https://www.tiktok.com/@username?lang=en、或直接 author_sec_uid
• 视频：https://www.tiktok.com/@username/video/<id>、短链、或直接作品 <id>

执行纪律

• 只把 stdout 当机器可读输出（纯 JSON）；banner / 进度 / 错误日志都在 stderr，不要混在一起解析。
• 单次 --limit 建议 ≤ 1000。
• 不要因为一次空结果就自动放宽条件重试：先把空结果告诉用户，由用户决定是否换关键词 / 放宽 --time。

5. 输出契约（AI 解析必读）

所有入口输出同一个信封，成功与失败结构一致：

{
  "status": "success | empty | error",
  "error_code": "OK | NO_MATCH | AUTH_REQUIRED | INVALID_KEYWORD | ...",
  "message": "人类可读说明",
  "timestamp": "2026-09-16 21:00:00",
  "request": {
    "command": "search",
    "keyword": "AI",
    "sort": 1,
    "time": 0,
    "limit": 20
  },
  "metadata": {
    "skill_version": "1.0.0",
    "skill_name": "tiktok-creator-videos",
    "runtime_version": "22.22.2",
    "execution_time": 8421
  },
  "results": [],
  "warnings": ["数量 99999 无效，已回退为 10"]
}

5.1 status 语义

5.2 退出码

5.3 错误码处理

5.4 warnings 必须回显

当传入参数不合法被自动回退时（如 --sort 9、--limit 99999），warnings 数组会说明"哪个参数被改成了什么"。必须原样转告用户，不能假装参数按原值生效了。

5.5 禁止行为

• ❌ 不编造、不补全、不凭记忆填充任何数据。
• ❌ 收到 AUTH_REQUIRED 后不重试、不换脚本、不改参数。
• ❌ 不把 empty 当成"用户要的内容不存在"以外的结论（不等于接口坏了）。
• ❌ 不在用户未同意时自动放宽搜索条件。

6. 结果消费建议（提升最终交付质量）

拿到 results 后，按用户原始目标组织输出，而不是原样吐 JSON：

• 选题调研 → 按 digg_count 降序取 Top N，归纳标题句式 / 标签 / 时长分布规律
• 竞品监控 → 按 create_time 排发布节奏，统计更新频率与爆款占比
• 评论洞察 → 按 digg_count 取高赞评论做观点聚类，输出正负向占比
• 红人筛选 → 交叉 author_nickname / 平均互动 / 发布频次，给出候选清单
• 需要留档 → 每次运行会自动写入日志文件，路径在 stderr 的"已保存到 …"一行

7. 安全与合规（Trust）

• 只读：不登录 TikTok 账号，不执行发布 / 点赞 / 评论 / 关注 / 私信等任何写操作，无风控封号风险。
• 最小权限：仅请求业务所需的一个环境变量 GUAIKEI_API_TOKEN；不读取本地其他文件、不写技能目录以外路径（日志写入系统临时目录）。
• 凭据保护：Token 只从环境变量读取，不写入 stdout、不写进日志、不出现在错误信息里。
• 数据外发范围（务必知悉）：调用时会向 https://www.guaikei.com 发送：你的 API Token、查询关键词或目标 URL/ID，以及技能名与 Node 版本。除此之外不采集任何本地信息。
• 数据合规：仅获取 TikTok 公开可见数据（昵称、公开作品、公开评论）。不含手机号、位置、私信等隐私字段。数据仅限个人 / 团队内部分析；对外发布或商用前请自行确认授权，并对用户昵称等做脱敏处理。
• 无第三方依赖：仅使用 Node.js 内置模块（https / fs / path / os / querystring），无 npm 依赖、无远程脚本加载、无 eval / child_process。

8. 常见问题

9. 环境与支持

• 环境：Node.js ≥ 16.14.0，Windows / macOS / Linux 全平台；必需 GUAIKEI_API_TOKEN。
• 官网：TikTok数据分析与市场调研技能（自助开通 Token、查阅用量与接口说明）。
• 支持：微信 13395823479（备注：TikTok 技能）。
• 变更记录：references/changelog.md