Skip to content
Back to search

tiktok-duration

SkillWorks with Claude CodeGitHub

"TikTok时间数据只读技能:关键词搜视频、博主作品、视频评论,输出 JSON,不登录不发布。触发词:TikTok、tiktok、抖音国际版、TikTok搜索、TikTok评论、TikTok博主。用户要查 TikTok 视频、评论、爆款选题、竞品监控、KOL 筛选或评论舆情时使用;抖音、小红书、快手、B站、微博、公众号不要用本技能。"

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/guaikei--tiktok-duration/badge.svg)](/listings/guaikei--tiktok-duration)

HTML

<a href="/listings/guaikei--tiktok-duration"><img src="/api/listings/guaikei--tiktok-duration/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 241 lines
  1. ---
  2. summary: TikTok时间数据所需的公开数据(只读):关键词搜索按 --keyword 返回视频列表,--time 按时间范围筛选(0 全部 / 1 近 1 日 / 7 近 7 日 / 30 近 1 月 / 90 近 3 月 / 180 近 6 月);结果含 create_time 与 duration 时长字段,博主作品含 video_duration、music_duration。搜索没有「最新发布」排序。输出多语言结构化 JSON,为时间维度整理提供数据源,按需取回、不自动更新。触发词:TikTok时间数据、TikTok时间筛选、TikTok发布时间、tiktok duration、tiktok time filter。
  3. displayName: TikTok时间数据|时间筛选·时间范围·时长字段·按需取回
  4. slug: tiktok-duration
  5. name: tiktok-duration
  6. description: "TikTok时间数据只读技能:关键词搜视频、博主作品、视频评论,输出 JSON,不登录不发布。触发词:TikTok、tiktok、抖音国际版、TikTok搜索、TikTok评论、TikTok博主。用户要查 TikTok 视频、评论、爆款选题、竞品监控、KOL 筛选或评论舆情时使用;抖音、小红书、快手、B站、微博、公众号不要用本技能。"
  7. license: MIT
  8. version: 1.1.3
  9. metadata:
  10. openclaw:
  11. emoji: "🎵"
  12. primaryEnv: GUAIKEI_API_TOKEN
  13. requires:
  14. bins:
  15. - node
  16. env:
  17. - GUAIKEI_API_TOKEN
  18. enabled: true
  19. type: command
  20. runtime: "nodejs@16.14.0+"
  21. requires:
  22. bins: ["node"]
  23. env: ["GUAIKEI_API_TOKEN"]
  24. env_desc:
  25. GUAIKEI_API_TOKEN: "TikTok 数据 API 访问令牌。未配置时无法调用接口;可通过 https://www.guaikei.com 开通并获取支持。"
  26. keywords:
  27. - "TikTok"
  28. - "tiktok"
  29. - "抖音国际版"
  30. - "TikTok搜索"
  31. - "TikTok评论"
  32. - "TikTok博主"
  33. - "爆款选题"
  34. - "竞品分析"
  35. - "评论舆情"
  36. category:
  37. - "Integrations"
  38. - "Research"
  39. - "数据分析"
  40. - "内容创作"
  41. - "商业运营"
  42. tags:
  43. - "TikTok"
  44. - "tiktok"
  45. - "抖音国际版"
  46. - "关键词搜索"
  47. - "视频评论"
  48. - "博主作品"
  49. - "竞品分析"
  50. - "选题调研"
  51. - "舆情分析"
  52. - "爆款挖掘"
  53. - "KOL筛选"
  54. - "海外短视频"
  55. schemas:
  56. - name: "输出信封"
  57. file: "assets/output_envelope.schema.json"
  58. - name: "搜索入参"
  59. file: "assets/search_cli_req.schema.json"
  60. - name: "搜索出参"
  61. file: "assets/search_cli_resp.schema.json"
  62. - name: "作品入参"
  63. file: "assets/post_cli_req.schema.json"
  64. - name: "作品出参"
  65. file: "assets/post_cli_resp.schema.json"
  66. - name: "评论入参"
  67. file: "assets/comment_cli_req.schema.json"
  68. - name: "评论出参"
  69. file: "assets/comment_cli_resp.schema.json"
  70. examples:
  71. - "帮我搜 TikTok 上 AI 点赞最多的视频 → node scripts/tiktok/search-cli.js --keyword \"AI\" --sort 1 --limit 20"
  72. - "最近一周 TikTok 的 AI model,要 20 条 → node scripts/tiktok/search-cli.js --keyword \"AI model\" --time 7 --limit 20"
  73. - "这个 TikTok 博主最近 30 条作品 → node scripts/tiktok/post-cli.js --url \"https://www.tiktok.com/@username\" --sort 0 --limit 30"
  74. - "这个 TikTok 博主什么最火 → node scripts/tiktok/post-cli.js --url \"https://www.tiktok.com/@username\" --sort 1 --limit 30"
  75. - "这条 TikTok 视频评论区在说什么,帮我归纳舆情 → node scripts/tiktok/comment-cli.js --url \"https://www.tiktok.com/@username/video/1234567890123456789\" --limit 40"
  76. - "盯一下这个竞品账号最近发了什么 → node scripts/tiktok/post-cli.js --url \"https://www.tiktok.com/@competitor\" --limit 10"
  77. ---
  78. # 🎵 TikTok时间数据|时间筛选 · 时间范围 · 时长字段 · 按需取回 (TikTok Duration Data)
  79. 给一个关键词或一条主页链接,拿回 TikTok 时间数据:--time 按时间范围筛选(近 1 日 / 近 7 日 / 近 1 月 / 近 3 月 / 近 6 月);结果含 create_time 与 duration 时长字段,博主作品含 video_duration、music_duration。搜索没有「最新发布」排序。按需取回、不自动更新。不登录,不发布。结果是一份多语言 JSON。
  80. | 你要做的事 | 用哪个命令 | 你拿到什么 |
  81. | --- | --- | --- |
  82. | 找选题、看高赞 | `search-cli.js` | 视频数组。点赞、播放、评论是数字 |
  83. | 看评论区 | `comment-cli.js` | 评论数组 |
  84. | 看博主作品 | `post-cli.js` | 作品数组。没有单独的粉丝总数对象 |
  85. 三个命令成功时 `results` 都是数组。空字符串和数字 0 可能不返回,缺失不一定是没有这个字段。
  86. 本技能没有视频详情命令,也不下载视频。视频链接只能拉评论。播放地址可能过期。
  87. ## 0. 🧭 每次按这个顺序执行
  88. 1. 确认环境变量 `GUAIKEI_API_TOKEN` 已配置。没有配置时直接告诉用户去 [TikTok时间数据说明](https://www.guaikei.com) 开通,不要先跑一遍试探。
  89. 2. 在本技能根目录执行 `node scripts/tiktok/<命令>.js`(或用绝对路径,见 [references/faq.md](references/faq.md))。
  90. 3. stderr 出现「处理中」表示任务还在跑。等进程自己退出,再读 stdout 的最后一份 JSON。不要把 stderr 或整份 JSON 念给用户。
  91. 4. 按「4. 📦 读结果」的退出码表决定:改参数再试、告诉用户,或停止。
  92. 5. **Windows 拼参:cmd 只用双引号**包含空格/中文/URL 的参数;不要用 bash 单引号。引号仍拆坏 → 改用 `--json-args`([faq.md](references/faq.md))。Windows / 弱模型优先 `--json-args`。
  93. 查询最多 20 次。间隔从 2 秒起按 2、4、8、16、32 秒增加,之后每次 60 秒,只算等待大约 15 分钟。每次请求本身还有最多 20 秒超时。宿主如果更早结束进程,按超时处理,不要立刻用同一组参数连打。
  94. 同一组参数再次执行时,服务端会复用还没过期的任务:搜索大约 9 分钟内,作品和评论大约 20 分钟内,不会另开一条。搜索如果已经等到 `TIMEOUT`,9 分钟的复用窗口通常已经过去,立刻重跑可能新建一条任务。
  95. - 没有关键词或链接就先问,不要编造
  96. - 搜索不传 `--limit` 是 10 条。用户说「全部」再加大,不要自行抓 10000 条。**包月 Token** 搜索/作品勿超 30、评论勿超 40,否则 `PLAN_LIMIT`
  97. - `status=empty` 且退出码 0 是「接口已经完成,没有结果」,不是命令失败
  98. - 搜索若一直处理中直到 `TIMEOUT`,可能是没有可保存的结果。告诉用户换关键词或稍后再试,不要立刻连打
  99. ## 1. 🎯 什么时候调用
  100. 满足任一条件即调用:用户提到 TikTok、tiktok 或抖音国际版,并要求搜索、看评论、看博主作品或做选题、竞品、舆情。
  101. 不要调用:只让写文案;平台是抖音、小红书、快手、B 站、微博、公众号;要求登录、发布、点赞、下载文件或私密数据;没有关键词也没有可识别链接。
  102. ## 2. 🔀 路由
  103. 按这个顺序判断,命中即停:
  104. 1. 要评论、留言、舆情,且对象是一条视频 → `comment-cli.js`
  105. 2. 要作品、主页、账号、博主、达人 → `post-cli.js`
  106. 3. 有关键词,且没有上面两类信号 → `search-cli.js`
  107. 4. 以上都不明确 → 先追问
  108. 链接和 id:
  109. - `tiktok.com/@用户名` 只能给 `post-cli.js`。`http`、缺 `www`、`m.tiktok.com` 会在本地改成 `https://www.tiktok.com/@用户名`
  110. - 整段 `MS4w` 开头的 `sec_uid` 只能给 `post-cli.js`。搜索结果用 `author_sec_uid`,或 `author_url`
  111. - `tiktok.com/@用户名/video/数字` 和纯数字 `aweme_id` 只能给 `comment-cli.js`。搜索或作品结果用 `aweme_id`
  112. - `author_id`、`user_id` 是数字 uid,不要交给作品命令
  113. - `vm.tiktok.com`、`vt.tiktok.com`、`tiktok.com/t/` 短链两个命令都不接受。请用户换成标准链接,不要两个命令都试
  114. - `/photo/` 图文链接不支持
  115. - 只拿到一串数字、又没说明是视频 id 还是别的,按评论用;若用户说的是主页,先问
  116. | 用户说 | 应该传 |
  117. | --- | --- |
  118. | 最火、点赞最多、爆款 | `search-cli.js --sort 1` |
  119. | 搜索相关度、默认搜索 | `search-cli.js --sort 0`。搜索没有「按最新发布」 |
  120. | 近一天 | `--time 1` |
  121. | 近一周、这周 | `--time 7` |
  122. | 近一月 / 近三月 / 近半年 | `--time 30` / `90` / `180` |
  123. | 博主最近发了什么 | `post-cli.js --sort 0 --limit N`。不传 sort 就是最新。没说条数用 10 |
  124. | 这个博主什么最火 | `post-cli.js --sort 1` |
  125. | 评论区 | `comment-cli.js`。没说条数用默认 10 |
  126. 搜索的 `--sort 1` 是最多点赞。作品的 `--sort 1` 是最热,`--sort 0` 才是最新。
  127. `--time 2` 不是两天,也不是一周。非法值会直接失败。
  128. ## 3. 🎛️ 参数
  129. 枚举和数量不在允许范围内时,命令直接失败(退出码 2,`INVALID_ARGS`),不会改成默认值再请求。三个命令都支持 `--help` / `-h`:帮助打在 stderr,退出码 0,stdout 为空。短参数大小写都可以。含空格的关键词用双引号包成一个参数。关键词以 `-` 开头时写成 `--keyword=-AI`,或 `node scripts/tiktok/search-cli.js -- -AI`。完整字段见 `assets/*_cli_req.schema.json` 与 [references/options.md](references/options.md)。**Windows**:cmd **只用双引号**;仍拆坏或弱模型 → `--json-args`。双壳例与绝对路径 → [references/faq.md](references/faq.md)。
  130. **Windows 双壳(同一条搜索,先 cd 到技能目录)**:
  131. ```bat
  132. REM cmd —— 不要用单引号
  133. node scripts\tiktok\search-cli.js --keyword "AI tutorial" --sort 1 --limit 20
  134. ```
  135. ```powershell
  136. # PowerShell
  137. node scripts/tiktok/search-cli.js --keyword "AI tutorial" --sort 1 --limit 20
  138. ```
  139. **套餐双上限(重要)**:技能侧硬上限为 10000(按量 Token)。**包月 Token** 超限会返回 `PLAN_LIMIT`(后端 errcode 14),不要当网络错误重试:搜索/作品最多 **30**,评论最多 **40**。具体以官网与本次 `message` 为准。
  140. ### 3.1 🔍 关键词搜索
  141. | 参数 | 必填 | 取值 | 默认 |
  142. | --- | --- | --- | --- |
  143. | `--keyword` `-k` | 是 | 1–100 个字符,不能是链接,不含 `< > " '` | — |
  144. | `--sort` `-s` | 否 | `0` 相关度 / `1` 最多点赞 | `0` |
  145. | `--time` `-t` | 否 | `0` 全部 / `1` 近 1 日 / `7` 近 7 日 / `30` 近 1 月 / `90` 近 3 月 / `180` 近 6 月 | `0` |
  146. | `--limit` `-l` | 否 | 整数 1–10000(**包月 Token 实际最多 30**) | `10` |
  147. ### 3.2 🦸 博主作品
  148. | 参数 | 必填 | 取值 | 默认 |
  149. | --- | --- | --- | --- |
  150. | `--url` `-u` | 是 | 主页链接、`@用户名` 或整段 `sec_uid`,最长 255 | — |
  151. | `--sort` `-s` | 否 | `0` 最新 / `1` 最热 | `0` |
  152. | `--limit` `-l` | 否 | 整数 1–10000(**包月最多 30**) | `10` |
  153. ### 3.3 💬 视频评论
  154. | 参数 | 必填 | 取值 | 默认 |
  155. | --- | --- | --- | --- |
  156. | `--url` `-u` | 是 | 视频链接或纯数字 `aweme_id`,最长 255 | — |
  157. | `--limit` `-l` | 否 | 整数 1–10000(**包月最多 40**) | `10` |
  158. ## 4. 📦 读结果
  159. 成功、空结果、失败都是同一份信封。只读 stdout 的最后一份 JSON。`--help` 时 stdout 为空,帮助在 stderr。字段以 `assets/output_envelope.schema.json` 和 `assets/*_cli_resp.schema.json` 为准。取数成功/empty 时信封顶层可能有 `cost`(花费估算:包月为 `1`,按次为条数×单价);错误响应无此字段。
  160. ```json
  161. {
  162. "status": "success",
  163. "error_code": "OK",
  164. "message": "搜索任务完成",
  165. "timestamp": "2026/10/26 16:20:00",
  166. "request": { "command": "search", "keyword": "AI", "sort": 1, "time": 0, "limit": 20 },
  167. "metadata": { "skill_version": "1.1.3", "runtime_version": "22.22.2", "execution_time": 8421 },
  168. "results": [{ "aweme_id": "123", "desc": "...", "digg_count": 100 }],
  169. "cost": 0.08
  170. }
  171. ```
  172. 空结果仍是退出码 0:`status` 为 `empty`,`error_code` 为 `NO_MATCH`,`results` 为 `null`。失败时 `status` 为 `error`,`results` 为 `null`,`message` 是给人读的原因。
  173. - 搜索、作品、评论成功时 `results` 都是数组
  174. - 搜索作者有三套标识:`aweme_id` 给评论,`author_sec_uid` 或 `author_url` 给作品,`author_id` 是数字 uid
  175. - 评论者同样:`user_sec_uid` 或 `user_url` 给作品,`user_id` 不要交给作品命令
  176. - 作品列表没有粉丝数字段。粉丝在搜索结果的 `author_follower_count`
  177. - 搜索播放地址是字符串 `play_addr`。作品播放地址是字符串数组 `video_url`
  178. - 视频时长用户文档没写单位,按采集端原样的 TikTok 字段理解:视频时长一般为毫秒,音乐时长一般为秒
  179. | 退出码 | error_code | 怎么处理 |
  180. | --- | --- | --- |
  181. | 0 | `OK` / `NO_MATCH` | 没有结果就告诉用户没有匹配内容,不要当成失败重试 |
  182. | 2 | `INVALID_ARGS` / `INVALID_KEYWORD` | 按上一节改参数后再试一次。关键词是链接时改走作品或评论 |
  183. | 1 | `INVALID_URL` | 按路由换命令,或向用户要标准链接。短链不要改命令再试 |
  184. | 3 | `AUTH_REQUIRED` / `AUTH_ERROR` | 停止重试,让用户配置 `GUAIKEI_API_TOKEN` |
  185. | 1 | `TIMEOUT` | 任务仍在处理,搜索也可能是没有可保存的结果。不要立刻重跑。搜索的复用窗口大约只有 9 分钟,等满超时后再跑可能新建一条任务 |
  186. | 1 | `NETWORK_ERROR` / `HTTP_5xx` / `HTTP_429` | 命令内部已经重试过。退出后再失败就告诉用户稍后再试 |
  187. | 1 | `PLAN_LIMIT` | 套餐单次条数超限(常见于包月)。**禁止同参重试**。转述 `message`;可建议降 `--limit`(搜索/作品≤30,评论≤40)或到官网升级按量;**须用户同意后再跑** |
  188. | 1 | `INSUFFICIENT_BALANCE` | 余额不足(搜索常为后端 16,作品/评论常为 15)。**禁止同参重试**。引导官网充值 |
  189. | 1 | `RATE_LIMITED` | 短时间提交过多(作品/评论常为 2;搜索可能为 1 + 文案)。**禁止立即重试** |
  190. | 1 | `DAILY_LIMIT` | 今日消费已达每日上限(后端 18)。**禁止同参重试**。明日再试或到官网调整限额 |
  191. | 1 | 其它十进制数字 | 把 `message` 原样转告 |
  192. | 1 | `API_ERROR` / `UNKNOWN` | 转告 `message`,建议联系官网 |
  193. `error_code` 是字符串。查询还在处理、次数用尽时是 `TIMEOUT`,不是空结果。
  194. ## 5. 🔒 合规
  195. 只处理 TikTok 公开数据。调用时会把关键词或链接发到 `www.guaikei.com`。不上传本地文件,不登录,不发布,不下载视频文件。
  196. 成功结果默认不写文件。需要留底时加 `--save`,或设置 `GUAIKEI_ENABLE_LOG=1`,文件写到系统临时目录的 `tiktok-guaikei/logs/`。POSIX 上权限是仅当前用户可读写;Windows 不使用这组权限位,靠临时目录本身的用户隔离。旧变量 `TT_GUAIKEI_ENABLE_LOG` 已废弃。
  197. 开通 token 或更多帮助:[TikTok时间数据接口](https://www.guaikei.com)。
readme.md · README · 216 lines
  1. # 🚀 TikTok时间数据|时间筛选 · 时间范围 · 时长字段 · 按需取回
  2. > ### 一句话价值
  3. >
  4. > **给 AI 一个能真正"上 TikTok 查数据"的手。** 一句话就能拿到 TikTok 公开的搜索结果、博主作品和视频评论,输出可直接分析的结构化 JSON——不用登录账号、不用养号、不用怕封号、不用自己写爬虫。
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
  6. ![Node](https://img.shields.io/badge/node-%3E%3D16.14.0-brightgreen)
  7. ![Platform](https://img.shields.io/badge/platform-win%20%7C%20mac%20%7C%20linux-blue)
  8. ![Deps](https://img.shields.io/badge/dependencies-0%20(npm-free)-orange)
  9. ---
  10. ## 1. 💡 你为什么需要它(先看这段)
  11. 做 TikTok 内容,最贵的东西不是创意,是**判断依据**。
  12. | 你现在的做法 | 代价 | 用本技能之后 |
  13. | --------------------------------- | ----------------------------------- | ------------------------------------- |
  14. | 手动刷 TikTok 找对标爆款 | 2 小时起步,还容易漏 | 一句话拿到 Top N 高赞视频与互动数据 |
  15. | 用网页爬虫抓 | 反爬、风控、封 IP,脚本三天两头失效 | 走正规 API,无需登录,无封号风险 |
  16. | 买 SaaS 数据平台 | 年费几千到几万,还只能看固定看板 | 数据在 AI 里,想怎么分析就怎么分析 |
  17. | 让 AI 凭记忆给你"TikTok 爆款规律" | 模型没有实时数据,输出的全是想象 | AI 拿到**真实、实时的公开数据**再分析 |
  18. **核心差别**:这不是又一个数据看板,是把 TikTok 数据**接进你的 AI 工作流**——拿到数据后,AI 可以直接帮你做选题归纳、竞品对比、评论聚类、红人清单、周报表格,一条链路走完。
  19. ---
  20. ## 2. ✨ 三大能力
  21. | 能力 | 一句话 | 典型产出 |
  22. | ----------------- | -------------------------------------------------- | ---------------------------------- |
  23. | 🔍 **关键词搜索** | 按关键词搜 TikTok 内容,支持相关度/最多点赞排序与时间窗筛选 | 爆款清单、标题与标签规律、时长分布 |
  24. | 🦸 **博主作品** | 按主页链接或用户名批量拉取博主公开作品,支持最新/最热排序 | 竞品内容策略、更新节奏、爆款占比 |
  25. | 💬 **视频评论** | 按视频链接或作品 ID 拉取评论与互动数据 | 舆情正负向、高赞观点、用户真实诉求 |
  26. ---
  27. ## 3. 👥 谁在用 / 能赚回什么
  28. - **TikTok 创作者 / MCN**:每天省 1–2 小时找选题,爆款命中率靠数据而不是靠猜
  29. - **跨境卖家 / DTC 品牌**:批量筛红人、看竞品内容打法、盯品类动向
  30. - **增长 / 投放团队**:投放前先看这个赛道谁在跑、什么内容跑得动
  31. - **市场研究 / 咨询**:把 TikTok 公开数据变成可交付的表格与报告
  32. - **AI Agent 开发者**:一个可直接编排的只读数据节点,stdout 纯 JSON,零解析成本
  33. > 保守估算:按每周节省 5 小时人工刷数据、时薪 100 元计,**一个月回本 2000 元以上**——而这个技能的定价远低于此。
  34. ---
  35. ## 4. ⚡ 30 秒上手
  36. > **前置(只需做一次)**:到 [TikTok时间数据官网](https://www.guaikei.com) 自助开通 Token,然后配置环境变量:
  37. >
  38. > ```bash
  39. > # Windows
  40. > set GUAIKEI_API_TOKEN=你的TOKEN
  41. > # macOS / Linux
  42. > export GUAIKEI_API_TOKEN=你的TOKEN
  43. > ```
  44. 在**技能根目录**执行:
  45. ```bash
  46. # 🔍 关键词搜索(最简单)
  47. node scripts/tiktok/search-cli.js --keyword "AI"
  48. # 🔥 找点赞最多的爆款(最常用)
  49. node scripts/tiktok/search-cli.js --keyword "AI" --sort 1 --limit 20
  50. # 🦸 抓取某博主最近 30 条作品
  51. node scripts/tiktok/post-cli.js --url "https://www.tiktok.com/@username" --limit 30
  52. # 🦸 抓取某博主最热的 30 条作品
  53. node scripts/tiktok/post-cli.js --url "https://www.tiktok.com/@username" --sort 1 --limit 30
  54. # 💬 拉取某条视频的评论(包月最多 40;按量可更大)
  55. node scripts/tiktok/comment-cli.js --url "https://www.tiktok.com/@username/video/1234567890123456789" --limit 40
  56. ```
  57. **也可以直接对 AI 说人话**(安装技能后):
  58. - "帮我搜 TikTok 上 AI 相关最火的 20 条视频"
  59. - "看看 @username 最近发了什么,分析下他的内容策略"
  60. - "这条视频评论区主要在讨论什么?"
  61. ---
  62. ## 5. ⚖️ 为什么选它(对比表)
  63. | 维度 | 本技能 | 自建爬虫 | SaaS 数据平台 | 让 AI 硬编 |
  64. | ---------- | -------------------------------- | ----------------------- | --------------------- | --------------------- |
  65. | 账号安全 | ✅ 不登录、不写操作、零封号风险 | ❌ 风控封 IP / 封号 | ✅ 无风险 | ❌ 数据本身就是幻觉 |
  66. | 数据真实性 | ✅ 实时真实公开数据 | ⚠️ 结构一变就失效 | ✅ 真实 | ❌ 模型记忆,无实时性 |
  67. | 上手成本 | ✅ 配一个环境变量,30 秒 | ❌ 需研发 + 长期维护 | ⚠️ 学平台、看固定看板 | ✅ 零成本 |
  68. | 分析自由度 | ✅ 数据在 AI 里,任意二次分析 | ✅ 自由 | ❌ 只能用它的看板 | — |
  69. | 费用 | ✅ 一次性 / 低门槛 | ❌ 隐性研发与维护成本高 | ❌ 年费几千至数万 | ✅ 免费(但没用) |
  70. | 依赖与体积 | ✅ 零 npm 依赖,纯 Node 内置模块 | ❌ 一堆依赖 | — | — |
  71. | 可编排 | ✅ stdout 纯 JSON + 明确退出码 | ⚠️ 需自己封装 | ❌ 多为封闭系统 | — |
  72. ---
  73. ## 6. 🛠️ 技术规格
  74. - **运行环境**:Node.js ≥ 16.14.0,Windows / macOS / Linux 全平台
  75. - **依赖**:**零第三方 npm 依赖**,仅用 Node 内置模块(`https` / `fs` / `path` / `os` / `querystring`)
  76. - **输出**:stdout 纯 JSON(统一信封:`status` / `error_code` / `request` / `metadata` / `results`),日志与进度走 stderr
  77. - **退出码**:`0` 成功(含空结果和 `--help`)/ `2` 参数或关键词不合法 / `1` 链接、网络、超时或接口错误 / `3` Token 异常
  78. - **参数校验**:排序、时间、数量不在允许范围内时直接失败,不会改成默认值再请求
  79. - **稳定性**:创建最多重试 3 次;查询最多 20 次,只有「处理中」会继续等,整段等待大约 15 分钟。单次请求超时 20 秒。网络 / 429 / 5xx 及部分瞬时失败(如查价、插入)会内部重试;`AUTH_*`、`PLAN_LIMIT`、`INSUFFICIENT_BALANCE`、`RATE_LIMITED`、`DAILY_LIMIT` 等明确业务错误不重试
  80. - **日志留存**:默认不写文件。需要留底时加 `--save` 或设置 `GUAIKEI_ENABLE_LOG=1`,文件在系统临时目录。POSIX 上仅当前用户可读写;Windows 靠用户目录隔离。旧变量 `TT_GUAIKEI_ENABLE_LOG` 已废弃
  81. - **字段规范**:`assets/` 下提供输出信封和 6 份入参/出参 JSON Schema(draft-07)
  82. ---
  83. ## 7. 📋 参数速查
  84. > 完整说明见 [references/options.md](references/options.md)
  85. **搜索**:`--keyword/-k`(必填,1–100 字符)|`--sort/-s` 0 相关度 / 1 最多点赞|`--time/-t` 0/1/7/30/90/180|`--limit/-l` 1–10000(**包月最多 30**),默认 10
  86. **博主作品**:`--url/-u`(主页、`@用户名` 或 `MS4w` 开头的 sec_uid)|`--sort/-s` 0 最新 / 1 最热,默认最新|`--limit/-l` 1–10000(**包月最多 30**)
  87. **视频评论**:`--url/-u`(`/video/数字id` 或纯数字作品 ID)|`--limit/-l` 1–10000(**包月最多 40**)
  88. > 套餐双上限:技能硬上限 10000(按量);包月超限返回 `PLAN_LIMIT`,不要当网络错误重试。搜索的 `--sort 1` 是最多点赞,作品的 `--sort 1` 是最热。短链 `vm` / `vt` / `/t/` 不支持。
  89. ---
  90. ## 8. ❓ 常见问题
  91. <details>
  92. <summary><b>Q:运行报错,提示无权限 / 退出码 3?</b></summary>
  93. A:环境变量未配置或 Token 格式不对(需 16–256 位,仅字母、数字、下划线、连字符)。
  94. ```bash
  95. # Windows
  96. set GUAIKEI_API_TOKEN=你的TOKEN
  97. # macOS / Linux
  98. export GUAIKEI_API_TOKEN=你的TOKEN
  99. ```
  100. Token 是私有凭证,请勿分享给他人。
  101. </details>
  102. <details>
  103. <summary><b>Q:搜索结果为空?</b></summary>
  104. A:`empty` 是**正常结果**,表示"确实没搜到"。建议:换更通用的关键词;把 `--time` 改为 `0` 放开时间窗。
  105. </details>
  106. <details>
  107. <summary><b>Q:返回的条数少于我设的 limit?</b></summary>
  108. A:该条件下没有更多公开数据。接口按你传入的 `--limit` 一次返回,不支持用偏移量翻页。没说要多少条时用默认 10。
  109. </details>
  110. <details>
  111. <summary><b>Q:我传的参数好像没生效?</b></summary>
  112. A:非法的排序、时间或数量会直接失败,退出码 2,`error_code` 为 `INVALID_ARGS`。按 `message` 改成允许值后再运行。不会悄悄改成默认值。
  113. </details>
  114. <details>
  115. <summary><b>Q:报错 `PLAN_LIMIT` / 提示包月受限?</b></summary>
  116. A:技能侧硬上限仍是 10000 条/次(按量 Token)。**包月 Token** 搜索/作品最多 30、评论最多 40,超限返回 `PLAN_LIMIT`(退出码 1),不要当网络错误同参重试。可降 `--limit` 或到官网升级按量套餐。
  117. </details>
  118. <details>
  119. <summary><b>Q:日志文件在哪?</b></summary>
  120. A:默认不写文件。需要留底时加 `--save` 或设置 `GUAIKEI_ENABLE_LOG=1`,成功后 stderr 会打印"已保存到 …",路径为系统临时目录下的 `tiktok-guaikei/logs/<日期>/`。旧变量 `TT_GUAIKEI_ENABLE_LOG` 已废弃。
  121. </details>
  122. <details>
  123. <summary><b>Q:会不会泄露我的 Token?</b></summary>
  124. A:Token 只从环境变量读取,不会出现在 stdout、日志文件或错误信息中。调用时会随请求头发送到数据服务 `www.guaikei.com`(这是数据获取的必要环节)。
  125. </details>
  126. <details>
  127. <summary><b>Q:支持批量 / 自动化吗?</b></summary>
  128. A:支持。stdout 是纯 JSON、退出码语义明确,可直接被脚本或 AI Agent 编排;也可配合定时任务做每日竞品快照。
  129. </details>
  130. ---
  131. ## 9. 💳 计费与支持
  132. - **计费**:按 API 调用量计费,官方渠道开通,用量透明可查;**失败调用不计费**。按量单次最多 10000;包月搜索/作品最多 30、评论最多 40,超限为 `PLAN_LIMIT`。
  133. - **开通 / 支持**:[TikTok发布时间查询](https://www.guaikei.com) 自助开通 Token,并查阅使用帮助。
  134. - **更新日志**:[references/changelog.md](references/changelog.md)
  135. ---
  136. ## 10. 🔒 合规声明
  137. - 仅获取 TikTok **公开可见**数据;不登录账号,不执行发布 / 点赞 / 评论 / 关注 / 私信等任何写操作。
  138. - 不采集手机号、精确位置、私信等隐私字段。
  139. - 数据仅限个人 / 团队内部分析使用;对外发布或商用前请自行确认授权,并对用户昵称等个人信息做脱敏处理。
  140. - 数据通过第三方服务 `www.guaikei.com` 获取,使用前请确认数据外发范围符合你的合规要求。
  141. ---
  142. **MIT License** · 零依赖 · 全平台 · 只读安全

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.