🎯 TikTok競合分析とブランド比較
1. 機能概要
💡一言で言うと:カジュアルな指示でTikTokの公開動画/作者/コメントデータを取得し、構造化JSONを直接出力。クリエイター発掘、データ分析、市場調査、ソーシャルリスニング、バズり企画、ベンチマークアカウント監視、コメント分析、トレンド追跡を、手動でTikTokをスクロールする必要なく実現します。
| 機能 | エントリスクリプト | 必須パラメータ | 戻り値 |
|---|---|---|---|
| キーワード検索 | scripts/tiktok/search-cli.js | --keyword | 作品一覧:作者、いいね/コメント/共有/保存、タグ、再生URL |
| クリエイター作品 | scripts/tiktok/post-cli.js | --url(プロフィールページまたはユーザー名) | 該当クリエイターの公開作品一覧(最新 / 人気順ソート対応) |
| 動画コメント | scripts/tiktok/comment-cli.js | --url(動画リンクまたはID) | コメント本文、コメント投稿者、いいね数、返信数 |
対象ユーザー
- 🎯 ブランド企業 — トレンドに乗ったコンテンツ制作
- 🏢 MCN機関 — 高エンゲージメントの有望アカウント発掘
- ✍️ 個人クリエイター — ベンチマークサンプル探し、制作インスピレーション取得
- 📊 コンテンツ運用担当 — 週報のテーマ選定と競合分析
前提条件:スキルルートディレクトリで実行し、環境変数
GUAIKEI_API_TOKENが設定されている必要があります。設定されていない場合、すべてのコマンドは終了コード3、error_code=AUTH_REQUIREDを返します。その場合はユーザーにTokenの設定を直接促し、再試行やパラメータ変更は行わないでください。
2. 呼び出しの判断基準
2.1 呼び出すべきケース
- ユーザーが TikTok の公開コンテンツ(動画/画像/作者/コメント/トレンド)を調べたい場合。
- ユーザーがバズり企画の調査、競合アカウントの監視、インフルエンサーの選定、コメント分析、コンテンツスタイルの分析を行いたい場合。
- ユーザーがTikTokのキーワード、動画リンク、クリエイタープロフィールリンクを既に提供し、構造化データを希望している場合。
- ユーザーがデータ取得後にさらに要約、比較、ソート、クラスタリング、レポート/表作成を行いたい場合。
2.2 呼び出すべきでないケース
- ユーザーが単にコピー/タイトル/スクリプトのみを必要とし、TikTokデータの調査を求めていない場合。
- プラットフォームがTikTokではなく、他のプラットフォーム(抖音、小紅書、Bilibili、微博、微信公衆号)の場合 → 対応するスキルにルーティングします。本スキルはTikTokのみを処理します。
- ログイン状態、非公開データ、非表示データを要求する場合 → 非対応。
- キーワードと識別可能なリンクの両方があり、目的が不明な場合 → まず質問してから、推測しないでください。
2.3 機能範囲の明確な限界
投稿/いいね/コメント/フォロー/ダイレクトメッセージなどの書き込み操作は一切サポートしません。アカウントへのログインは行いません。電話番号、位置情報、DMなどのプライバシーフィールドは収集しません。ユーザーに代わってマーケティング判断は行いません。データを取得するまでが役割であり、分析は上位レイヤーに任せます。
3. 呼び出しルーティング(判断後に実行)
| ユーザーの意図 | スクリプト | 判断キーワード |
|---|---|---|
| キーワード検索、特定ジャンルのコンテンツ、バズりコンテンツを探す | search-cli | 検索 / 探す / キーワード / バズり / 人気 |
| 特定クリエイター/インフルエンサーの作品、プロフィール、アカウント、最近の投稿を見る | post-cli | 作品 / プロフィール / アカウント / クリエイター / インフルエンサー / KOL |
| 特定動画のコメント、メッセージを見る | comment-cli | コメント / メッセージ / コメント欄の意見 |
3.1 曖昧性解消ルール(必須遵守)
- 「動画」という単語のみの場合、安易に
post-cliと見なさない。- 「キーワード」があり「コメント」がない場合 →
search-cli(ユーザーはその種の動画を検索したい)。 - 「この動画のコメント/メッセージ」と明確に指定 →
comment-cli。 - 「作品 / プロフィール / アカウント / クリエイター / インフルエンサー」という単語がある場合のみ →
post-cli。
- 「キーワード」があり「コメント」がない場合 →
- コメントの優先順位は作品より高い:リンクが
/video/<id>でコメントについて尋ねている場合 →comment-cli。「この人の作品」について尋ねている場合 →post-cli(@usernameを使用)。 - ユーザーが
/video/<id>リンクを提供したが「作品一覧」を要求 → まず、その作者の作品か、その動画のコメントか確認する。
3.2 パラメータ推論ルール
| ユーザーの表現 | パラメータ |
|---|---|
| 関連度 / デフォルト | --sort 0(検索) |
| 一番人気 / いいね最多 / バズり / 最もホット | --sort 1(検索) |
| 最近投稿 / 時間降順 | --sort 0(作品) |
| 最もホットな作品 | --sort 1(作品) |
| 1日 / 24時間 | --time 1 |
| 1週間 / 7日 | --time 7 |
| 1ヶ月 / 3ヶ月 / 半年 | --time 30 / 90 / 180 |
| N件 / 上位N件 / N個必要 | --limit N |
デフォルト値:sort=0、time=0、limit=10。
⚠️ 検索の
--sortと作品の--sortを混同しないこと:前者は「関連度 / 最大いいね数」、後者は「最新 / 人気」です。
不正な値が指定されてデフォルト値に戻った場合、その情報は出力JSONの warnings 配列に含まれます。ユーザーに必ず伝え、元の値がそのまま有効になったと見なさないでください。
4. 実行方法
完全なパラメータ説明は references/options.md を参照。フィールドレベルスキーマは
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)として扱う。バナー/進捗/エラーログは全て 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 の意味
| status | 意味 | results | すべきこと |
|---|---|---|---|
success | データ取得成功 | 空でない配列 | 直接分析 |
empty | リクエスト成功、ただしデータなし | null | 有効な結果として扱い、見つからなかったことをユーザーに伝える。失敗として扱わない。 |
error | リクエスト失敗 | null | error_code に従って処理し、データを捏造しない。 |
5.2 終了コード
| 終了コード | 意味 | Agentの動作 |
|---|---|---|
0 | 成功(success または empty) | 分析を続行 |
1 | 実行エラー(ネットワーク / タイムアウト / API異常 / 不正なパラメータ) | message を表示し、ユーザーにパラメータ変更して再試行するか尋ねる。 |
3 | AUTH_REQUIRED:Token欠落または形式エラー | 即時停止し、GUAIKEI_API_TOKEN の設定を促す。再試行禁止。 |
5.3 エラーコードの処理
| error_code | 処理方法 |
|---|---|
AUTH_REQUIRED | 停止し、Tokenの設定を促す。再試行禁止、パラメータ変更禁止。 |
INVALID_KEYWORD | キーワードは2~100文字、< > " ' & およびhttpリンクを含まないこと。 |
NO_MATCH | 有効な空結果。キーワード変更か --time の緩和を提案。 |
NETWORK_ERROR | 内部リトライ済み。それでも失敗する場合はネットワーク確認を促し、最大1回手動リトライ可能。 |
TIMEOUT_ERROR | 内部リトライ済み。それでも失敗する場合は --limit を減らして再試行を提案。 |
| その他(サーバーコード) | error_code + message をそのまま表示。自分で意味を推測しない。 |
5.4 warnings は必ず表示
入力パラメータが不正で自動的にデフォルト値に戻された場合(例:--sort 9、--limit 99999)、warnings 配列に「どのパラメータが何に変更されたか」が記載されます。ユーザーにそのまま伝える必要があります。パラメータが元の値で有効になったふりをしてはいけません。
5.5 禁止行為
- ❌ データを捏造、補完、記憶に基づいて補わない。
- ❌
AUTH_REQUIREDを受信した後、再試行、スクリプト変更、パラメータ変更を行わない。 - ❌
emptyを「ユーザーが求めるコンテンツが存在しない」以外の結論(例:APIが壊れている)と見なさない。 - ❌ ユーザーの同意なしに自動的に検索条件を緩めない。
6. 結果の活用提案(最終成果物の品質向上)
results を取得した後、ユーザーの本来の目的に沿って出力を構成し、JSONをそのまま吐き出さないこと。
- 企画調査 →
digg_count降順で上位N件を取得し、タイトルのパターン/タグ/動画時間分布を要約。 - 競合監視 →
create_timeで投稿ペースを並べ、更新頻度とバズり率を統計。 - コメント分析 →
digg_countで高評価コメントを取得し、意見をクラスタリング、ポジティブ/ネガティブ比率を出力。 - インフルエンサー選定 →
author_nickname/ 平均エンゲージメント / 投稿頻度をクロス集計し、候補リストを提示。 - 保存が必要な場合 → 実行ごとに自動的にログファイルが作成されます。パスはstderrの「已保存到 …」行に表示されます。
7. セキュリティとコンプライアンス(Trust)
- 読み取り専用:TikTokアカウントにログインせず、投稿/いいね/コメント/フォロー/ダイレクトメッセージなどの書き込み操作は一切行いません。アカウント停止リスクはありません。
- 最小権限:業務に必要な環境変数
GUAIKEI_API_TOKENのみを要求します。他のローカルファイルは読み取らず、スキルディレクトリ外への書き込みは行いません(ログはシステム一時ディレクトリに書き込みます)。 - 認証情報の保護:Tokenは環境変数からのみ読み取り、stdout、ログ、エラーメッセージに書き込まれません。
- データの送信範囲(必ず把握すること):呼び出し時に
www.guaikei.comに送信されるのは、API Token、検索キーワードまたは対象URL/ID、スキル名、Nodeバージョンです。これ以外のローカル情報は収集されません。 - データコンプライアンス:TikTokの公開データ(ニックネーム、公開作品、公開コメント)のみを取得します。電話番号、位置情報、DMなどのプライバシーフィールドは含みません。データは個人/チーム内部分析に限定されます。外部公開または商用利用の前に、ご自身で権限を確認し、ユーザーニックネームなどの匿名化処理を行ってください。
- サードパーティ依存なし:Node.js内蔵モジュール(
https/fs/path/os/querystring)のみを使用。npm依存、リモートスクリプトの読み込み、eval/child_processは一切使用しません。
8. よくある質問
| 現象 | 原因と対処 |
|---|---|
| 終了コード3 / AUTH_REQUIRED | Token未設定または形式不正(16~256文字の英数字、アンダースコア、ハイフンのみ許可) |
| 検索結果が空 | より一般的なキーワードに変更、または --time 0 で時間制限を解除。empty は正常な結果でありエラーではない。 |
結果数が --limit より少ない | サーバー側でこれ以上返せない、または単一回の上限で打ち切られた可能性。≤ 1000 に減らして分割取得。 |
| タイムアウトが続く | --limit を減らして再試行。スクリプトは内部で指数バックオフリトライを実装済み。 |
| 「最もホットな作品」を見たいのに時間降順になる | post-cli では --sort 1 を使用する必要がある。 |
| パラメータが効かない / 結果の並び順が期待と異なる | 出力の warnings を確認。不正なパラメータは静かにデフォルト値に戻される。 |
| ログファイルの場所 | stderrの「已保存到 …」の行を参照(システム一時ディレクトリ tiktok-guaikei/logs/<日付>/) |
9. 環境とサポート
- 環境:Node.js ≥ 16.14.0、Windows / macOS / Linux 全プラットフォーム。
GUAIKEI_API_TOKEN必須。 - 公式サイト:TikTok競合分析とブランド比較(セルフサービスでTokenを開通、使用量とAPI説明を確認)。
- 変更履歴:references/changelog.md