Communitygithub.com

why20261/tiktok-insight

TikTok竞品洞察分析工具,实时监测竞品流量效果、快速拆解对标竞对作品、精准拆解透视竞品流量及策略、高效搭建关键词库,适用于TikTok品牌方、创作者等进行竞品分析、流量优化和关键词研究。提供3个能力①关键词搜索(可按点赞/相关度排序、发布时间筛选)②博主作品获取,按主页链接或用户名批量获取公开作品列表,支持最新/最热排序 ③视频评论抓取,按视频链接或作品 ID 获取评论内容、评论者与互动数据,输出结构化 JSON(含作者、互动数据、标签、链接)。

tiktok-insight 是什么?

tiktok-insight is a Claude Code agent skill that tikTok竞品洞察分析工具,实时监测竞品流量效果、快速拆解对标竞对作品、精准拆解透视竞品流量及策略、高效搭建关键词库,适用于TikTok品牌方、创作者等进行竞品分析、流量优化和关键词研究。提供3个能力①关键词搜索(可按点赞/相关度排序、发布时间筛选)②博主作品获取,按主页链接或用户名批量获取公开作品列表,支持最新/最热排序 ③视频评论抓取,按视频链接或作品 ID 获取评论内容、评论者与互动数据,输出结构化 JSON(含作者、互动数据、标签、链接)。.

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add why20261/tiktok-insight

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

🎯 TikTok Competitive Insight Analysis

1. Capability Overview

💡 Value in a nutshell: One conversational command to get TikTok's public video/author/comment data, output as structured JSON—for influencer screening, data analysis, market research, sentiment monitoring, viral topic identification, benchmark account monitoring, comment sentiment analysis, and trend tracking. No more manual TikTok scrolling.

CapabilityEntry ScriptRequired ParametersReturns
Keyword Searchscripts/tiktok/search-cli.js--keywordVideo list: author, likes/comments/shares/favorites, tags, play URL
Creator Videosscripts/tiktok/post-cli.js--url (profile or username)Public video list for that creator (supports Latest / Most Popular sorting)
Video Commentsscripts/tiktok/comment-cli.js--url (video link or ID)Comment text, commenter, like count, reply count

Target Users

  • 🎯 Brands — Ride trending topics for organic content
  • 🏢 MCN Agencies — Discover high-engagement potential accounts
  • ✍️ Content Creators — Find benchmark samples, get creative inspiration
  • 📊 Content Operators — Weekly report topics and competitor analysis

Prerequisite: Must be executed from the skill root directory, and the environment variable GUAIKEI_API_TOKEN must be configured. If not configured, all commands return exit code 3, error_code=AUTH_REQUIRED—in this case, directly prompt the user to configure the Token, do not retry, do not change parameters.


2. When to Call / When Not to Call

2.1 Should Call

  • User wants to query public TikTok content (videos / images / authors / comments / trends).
  • User wants to conduct viral topic research, competitor account monitoring, influencer screening, comment sentiment analysis, content style analysis.
  • User has provided TikTok keywords, video links, or creator profile links, and expects structured data.
  • User wants to summarize, compare, sort, cluster, or generate reports/tables after receiving the data.

2.2 Should Not Call

  • User only needs copy/text/script, not TikTok data.
  • The platform is not TikTok but another platform (Douyin, Xiaohongshu, Bilibili, Weibo, WeChat Official Accounts) → Route to the corresponding skill. This skill only handles TikTok.
  • Login, private, or hidden data is requested → Not supported.
  • Both a keyword and an identifiable link exist, and the intent is unclear → Ask for clarification first, do not guess.

2.3 Capability Boundaries (Explicitly Not Done)

Write operations such as posting, liking, commenting, following, or sending direct messages are not supported; no accounts are logged into; phone numbers, locations, private messages, or other private fields are not collected; marketing decisions are not made on behalf of the user—the responsibility is to retrieve the data; analysis is left to higher levels.


3. Call Routing (Determine First, Then Execute)

User IntentScriptKeywords for Judgment
Search keywords, find specific content, find viral contentsearch-clisearch / find / keyword / viral / most popular
View a creator/influencer/celebrity's videos, profile, recent postspost-clivideos / profile / account / creator / influencer / KOL
View comments on a specific videocomment-clicomments / replies / opinions in the comment section

3.1 Disambiguation Rules (Must Follow)

  1. When "video" appears alone, do not default to post-cli.
    • Has "keyword" and no "comment" → search-cli (user wants to search for this type of video).
    • Clearly "comments / replies on this video" → comment-cli.
    • Only when "videos / profile / account / creator / influencer" appear → post-cli.
  2. Comment priority is higher than videos: If a /video/<id> link is given and the question is about comments → comment-cli; if the question is about "this person's videos" → post-cli (use @username).
  3. User provides a /video/<id> link but asks for "video list" → First confirm whether they want the author's videos or comments on the video.

3.2 Parameter Inference Rules

User StatementParameter
Relevance / Default--sort 0 (Search)
Most Popular / Most Liked / Viral / Hottest--sort 1 (Search)
Most Recent / Reverse Chronological--sort 0 (Videos)
Most Popular Videos--sort 1 (Videos)
One day / 24 hours--time 1
One week / 7 days--time 7
One month / Three months / Six months--time 30 / 90 / 180
N items / Top N / Need N items--limit N

Defaults: sort=0, time=0, limit=10.

⚠️ Do not confuse --sort for search with --sort for videos: The former is "Relevance / Most Likes", the latter is "Latest / Hottest".

Any parameter that falls back to its default due to an invalid value will appear in the warnings array of the output JSON. It must be displayed to the user and not treated as if the original value was used.


4. Execution Method

For complete parameter details, see references/options.md; for field-level schemas, see the 6 JSON Schema files (draft-07) under assets/.

# Keyword Search
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

# Creator Videos
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

# Video Comments
node scripts/tiktok/comment-cli.js --url "https://www.tiktok.com/@username/video/1234567890123456789" --limit 40

Acceptable Input Formats

  • Creator: https://www.tiktok.com/@username, link with parameters https://www.tiktok.com/@username?lang=en, or direct author_sec_uid
  • Video: https://www.tiktok.com/@username/video/<id>, short link, or direct video <id>

Execution Discipline

  • Only treat stdout as machine-readable output (pure JSON); banner / progress / error logs go to stderr, do not mix them.
  • It is recommended to keep a single --limit ≤ 1000.
  • Do not automatically relax conditions to retry after a single empty result: first inform the user of the empty result, let the user decide whether to change the keyword or relax --time.

5. Output Contract (Required Reading for AI Agents)

All entries output the same envelope, with a consistent structure for success and failure:

{
  "status": "success | empty | error",
  "error_code": "OK | NO_MATCH | AUTH_REQUIRED | INVALID_KEYWORD | ...",
  "message": "Human-readable explanation",
  "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": ["Limit 99999 is invalid, reverted to 10"]
}

5.1 status Semantics

statusMeaningresultsAction
successData retrievedNon-empty arrayAnalyze directly
emptyRequest succeeded, but no datanullTreat as a valid result; inform user nothing was found; do not treat as a failure
errorRequest failednullHandle based on error_code; do not fabricate data

5.2 Exit Codes

Exit CodeMeaningAgent Behavior
0Success (success or empty)Continue analysis
1Runtime error (network / timeout / API exception / invalid parameter)Display message, ask user if they want to retry with different parameters
3AUTH_REQUIRED: Token missing or malformedStop immediately, prompt to configure GUAIKEI_API_TOKEN, prohibit retries

5.3 Error Code Handling

error_codeHandling Method
AUTH_REQUIREDStop and prompt to configure Token. Prohibit retries and parameter changes.
INVALID_KEYWORDIndicate the keyword must be 2–100 characters, cannot contain < > " ' & or http links
NO_MATCHValid empty result; suggest changing the keyword or relaxing --time
NETWORK_ERRORBuilt-in retry already attempted; if still failing, suggest checking the network; allow at most 1 manual retry
TIMEOUT_ERRORBuilt-in retry already attempted; if still failing, suggest reducing --limit and retrying
Others (server-side codes)Display the original error_code + message; do not guess the meaning

5.4 warnings Must Be Displayed

When an input parameter is invalid and is automatically reverted (e.g., --sort 9, --limit 99999), the warnings array will explain "which parameter was changed to what". This must be communicated verbatim to the user, do not pretend the parameter was applied as originally entered.

5.5 Prohibited Behaviors

  • ❌ Do not fabricate, complete, or fill any data from memory.
  • ❌ Do not retry, change scripts, or modify parameters upon receiving AUTH_REQUIRED.
  • ❌ Do not interpret empty as anything other than "the content the user wants does not exist" (it does not mean the API is broken).
  • ❌ Do not automatically relax search conditions without user consent.

6. Result Consumption Suggestions (For Higher Quality Deliverables)

After receiving results, organize the output according to the user's original goal, rather than dumping the raw JSON:

  • Topic Research → Sort by digg_count descending, take Top N, summarize title patterns / tags / duration distribution
  • Competitor Monitoring → Sort by create_time to analyze posting cadence, calculate update frequency and hit rate
  • Comment Insights → Filter by digg_count for high-liked comments, perform sentiment clustering, output positive/negative ratio
  • Influencer Screening → Cross-reference author_nickname / average engagement / posting frequency, provide a candidate list
  • For Archival Purposes → Each run automatically writes a log file; the path is indicated in the "Saved to …" line in stderr

7. Security and Compliance (Trust)

  • Read-Only: Does not log into TikTok accounts; does not perform any write operations such as posting, liking, commenting, following, or sending DMs; no risk of account suspension.
  • Least Privilege: Only requires one environment variable GUAIKEI_API_TOKEN necessary for the business; does not read other local files; does not write outside the skill directory (logs are written to the system temporary directory).
  • Credential Protection: Token is only read from environment variables; not written to stdout, not written to logs, not exposed in error messages.
  • External Data Scope (Must Be Aware): When invoked, the following is sent to www.guaikei.com: your API Token, the search keywords or target URL/ID, and the skill name and Node version. No other local information is collected.
  • Data Compliance: Only collects publicly visible TikTok data (nickname, public videos, public comments). Does not include private fields such as phone numbers, locations, or DMs. Data is for personal/team internal analysis only; for external publication or commercial use, please confirm authorization and anonymize user nicknames.
  • No Third-Party Dependencies: Uses only Node.js built-in modules (https / fs / path / os / querystring); no npm dependencies, no remote script loading, no eval / child_process.

8. Frequently Asked Questions

ScenarioCause and Handling
Exit code 3 / AUTH_REQUIREDToken not configured or malformed (must be 16–256 characters, alphanumeric with underscores and hyphens)
Search results emptyUse a more generic keyword, or set --time 0 to remove the time window; empty is a normal result, not an error
Result count less than --limitServer has no more results, or the single-request limit was reached; reduce to ≤ 1000 and batch
Persistent timeoutsReduce --limit and retry; the script has built-in exponential backoff retry
Wanted "Most Popular Videos" but got reverse chronologicalUse --sort 1 with post-cli
Parameter didn't apply / sorting differs from expectationCheck the warnings in the output; invalid parameters are silently reverted to defaults
Where is the log file?See the "Saved to …" line in stderr (system temp directory tiktok-guaikei/logs/<date>/)

9. Environment and Support

相关技能