guaikei-douyin-data-funnel

用数字看技能：4 个 CLI 命令、5 类可查数据（视频/图文/用户/评论/热榜）、5 维筛选参数、10000 条单次上限、3 次网络重试。当用户做抖音搜索、竞品分析、舆情监控、热点追踪、爆款选题时使用，输出纯 JSON。

抖音公开数据采集技能。通过关键词搜索、博主作品抓取、视频评论获取、实时热榜查询四项能力，为内容调研、竞品分析、舆情洞察、热点追踪提供结构化 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_-]
5. 令牌无效后立即停止执行（退出码 3），不重试、不降级、不引导用户到外部渠道

命令

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

所有命令均支持 --help（或 -h）查看用法。完整参数说明与取值范围见 references/options.md。

--url 参数格式

post-cli 的 --url 接受博主主页链接或 sec_uid：

格式	示例
PC 端主页链接	https://www.douyin.com/user/MS4wLjABxxx
移动端短链	https://v.douyin.com/xxx
sec_uid 直传	MS4wLjABxxx（搜索结果 author_sec_uid 字段）

comment-cli 的 --url 接受视频链接或 aweme_id：

格式	示例
视频链接	https://www.douyin.com/video/xxx
图文链接	https://www.douyin.com/note/xxx
aweme_id 直传	7xxxxxxxxxxxx（视频唯一 ID）

意图识别

按优先级从上到下匹配：

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

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

参数推断

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

输入输出规范

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

错误处理

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

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

示例

bash

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

# 2. 找点赞最多的爆款视频（缩写形式）
node src/douyin/search-cli.js -k "AI" -s 1

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

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

# 5. 抓取博主作品（移动短链）
node src/douyin/post-cli.js -u "https://v.douyin.com/abc123" -l 30

# 6. 获取视频评论（舆情分析）
node src/douyin/comment-cli.js --url "https://www.douyin.com/video/xxx" --limit 100

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

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

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

多步工作流示例（舆情监控）：

1. 搜索品牌关键词找到相关视频 → search-cli
2. 对高曝光视频获取评论 → comment-cli
3. 对比热榜话题热度 → hot-cli

限制与合规

1. 仅采集抖音公开数据，不支持私密/隐藏内容；不支持发布、剪辑、下载去水印等操作
2. 单次获取上限 10000 条
3. 数据仅限个人/团队内部合法调研使用，禁止违规分发
4. 纯中文界面，国内服务器可用
5. 令牌管理详见"令牌管理规范"节

参考

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