guaikei-douyin-trending-to-rank-report

当用户需要搜索抖音关键词（视频/图文/用户）、获取博主作品列表、抓取视频评论或查询实时热榜时，使用本技能。覆盖短视频选题、竞品账号分析、评论区舆情、热点追踪四类任务；用户做内容调研而未点名平台时同样适用。不适用于发布视频、下载去水印或非抖音平台。

guaikei抖音热榜转排行报告

抖音公开数据采集技能。通过关键词搜索、博主作品抓取、视频评论获取、实时热榜查询四项能力，为内容调研、竞品分析、舆情洞察、热点追踪提供结构化 JSON 数据。

何时使用

场景	典型用户表达
关键词搜索	"搜一下抖音上AI教程的视频""找抖音最火的减肥视频""近一周抖音有什么新内容"
博主作品抓取	"看看这个抖音博主的作品""抓取这个账号的主页内容""分析竞品发了什么"
视频评论获取	"这个抖音视频的评论""看看这条视频的留言""分析评论舆情"
实时热榜查询	"抖音今天什么火""抖音热搜榜""热点趋势"

泛化触发：用户做短视频调研、竞品分析、爆款选题未明确提到"抖音"时同样适用；任务埋在多步工作流中（如"帮我调研一下这个赛道"）也应触发。

不应触发：发布/上传视频、视频剪辑、下载去水印、涨粉代运营咨询、写爬虫代码、其他平台（小红书/快手/B站）数据采集、私域后台数据获取。

环境与权限

• 运行时：Node.js ≥ 16.14，仅需 node 命令，无需额外依赖
• 鉴权：环境变量 GUAIKEI_API_TOKEN（令牌获取方式见 readme.md）
• 工作目录：必须在技能根目录执行命令
• 最小权限：仅使用 Node.js 内置模块，不写入文件系统（日志除外），仅联网 API 服务地址

⚠️ 令牌管理规范

此节为审核重点，务必严格遵守。

1. 令牌通过环境变量 GUAIKEI_API_TOKEN 传入，代码中不得硬编码，日志中脱敏
2. 令牌无效时仅输出中性错误信息（如"GUAIKEI_API_TOKEN 未配置或格式无效，技能已暂停"），不输出任何联系方式、官网链接或推广内容
3. 联系方式仅出现在 readme.md（用户文档），不在技能运行时输出
4. 令牌格式校验：长度 16–256，仅含 [0-9a-zA-Z_-]

命令

命令	用途	必填参数	可选参数
node src/douyin/search-cli.js	关键词搜索	--keyword	--sort --time --duration --content --limit
node src/douyin/post-cli.js	博主作品抓取	--url	--limit
node src/douyin/comment-cli.js	视频评论获取	--url	--limit
node src/douyin/hot-cli.js	实时热榜	无	无

完整参数说明与取值范围见 references/options.md。

意图识别

按优先级从上到下匹配：

优先级	触发词	命令
1	热搜/热点/榜单/今天什么火	hot-cli
2	搜索/搜一下/找 + 关键词	search-cli
3	评论/留言/弹幕	comment-cli
4	作品/主页/账号/博主	post-cli

歧义消解：单独出现"视频"不默认归 post-cli。有"关键词"无"评论"→ search；明确"这个视频的评论"→ comment；出现"作品/主页/账号/博主"→ post。

参数推断

参数	用户说法 → 参数值
--sort	综合/默认 → 0 ｜ 点赞最多/最火/爆款 → 1 ｜ 最新/最近发布 → 2
--time	全部 → 0 ｜ 一天/24小时 → 1 ｜ 一周/7天 → 7 ｜ 半年 → 180
--duration	不限 → 0 ｜ 1分钟以下 → 1 ｜ 1-5分钟 → 2 ｜ 5分钟以上 → 3
--content	不限 → 0 ｜ 视频 → 1 ｜ 图文 → 2
--limit	N条/前N条/数量N → N（默认 10，范围 1–10000）

输入输出规范

• stdout：纯 JSON 数据（可直接解析消费）
• stderr：日志与提示信息
• 退出码：0 = 成功（含空结果）｜ 1 = 运行错误 ｜ 3 = 令牌无效
• 输出文件：自动保存至 logs/ 目录，命名含时间戳与查询参数
• 数据格式：遵循 assets/ 目录 JSON Schema（draft-07）规范

错误处理

错误类型	处理方式
令牌无效（退出码 3）	输出中性错误，停止执行，询问用户检查环境变量
API 次数超限	停止执行，告知用户额度已满
网络超时	自动重试最多 3 次，仍失败则停止并报告
空结果	正常退出（退出码 0），输出空 JSON
参数越界	输出参数错误提示，不执行

禁止行为：令牌无效后继续重试；API 返回明确错误码后修改参数重试；用户未要求时自动调整搜索条件。

示例

bash

# 1. 关键词搜索（默认综合排序，10条）
node src/douyin/search-cli.js --keyword "AI教程"

# 2. 找点赞最多的爆款视频
node src/douyin/search-cli.js --keyword "AI" --sort 1

# 3. 近一周最新20条
node src/douyin/search-cli.js --keyword "AI教程" --sort 2 --time 7 --limit 20

# 4. 抓取博主作品
node src/douyin/post-cli.js --url "https://www.douyin.com/user/MS4wLjABxxx" --limit 50

# 5. 获取视频评论
node src/douyin/comment-cli.js --url "https://www.douyin.com/video/xxx" --limit 100

# 6. 实时热榜
node src/douyin/hot-cli.js

多步工作流示例（竞品分析）：

1. 搜索关键词找到竞品账号 → search-cli
2. 抓取竞品博主作品列表 → post-cli
3. 对高赞作品获取评论 → comment-cli
4. 查看当前热榜对比趋势 → hot-cli

限制与合规

1. 仅采集抖音公开数据，不支持私密/隐藏内容；不支持发布、剪辑、下载去水印等操作
2. 单次获取上限 10000 条
3. 数据仅限个人/团队内部合法调研使用，禁止违规分发
4. 纯中文界面，国内服务器可用
5. 令牌走环境变量、不落盘；运行时不输出联系方式或推广内容（详见"令牌管理规范"）

参考

• 完整参数说明：references/options.md
• 入参/出参 JSON Schema：assets/*.schema.json
• 使用文档与令牌获取：readme.md
• 更新日志：references/changelog.md