🎯 TikTok 競品分析與品牌對比
1. 能力概覽
💡一句話價值:一個口語化指令拿到 TikTok 公開的影片/作者/評論資料,直接輸出結構化 JSON——做達人篩選、資料分析、市場調研、輿情監控、爆款選題、對標帳號監控、評論輿情分析、熱點追蹤,不用再手動刷 TikTok。
| 能力 | 入口腳本 | 必填參數 | 返回 |
|---|---|---|---|
| 關鍵字搜尋 | scripts/tiktok/search-cli.js | --keyword | 作品列表:作者、按讚/留言/分享/收藏、標籤、播放位址 |
| 創作者作品 | 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,而是其他平台的(抖音、小紅書、B 站、微博、公眾號)→ 路由到對應技能。本技能只處理 TikTok。
- 要求登入態、私密、隱藏資料 → 不支援。
- 既有關鍵字又有可識別連結且目標不明 → 先追問,不要猜。
2.3 能力邊界(明確不做)
發布 / 按讚 / 評論 / 關注 / 私訊等寫操作一律不支援;不登入任何帳號;不蒐集手機號碼、位置、私訊等隱私欄位;不替用戶做行銷決策——職責是把資料拿回來,分析交給上層。
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(作品) |
| 一天 / 24 小時 | --time 1 |
| 一週 / 7 天 | --time 7 |
| 一個月 / 三個月 / 半年 | --time 30 / 90 / 180 |
| N 條 / 前 N 條 / 要 N 個 | --limit N |
預設值:sort=0、time=0、limit=10。
⚠️ 搜尋的
--sort與作品的--sort不要混用:前者是「相關度 / 最多按讚」,後者是「最新 / 最熱」。
任何參數被非法值回退,都會出現在輸出 JSON 的 warnings 陣列裡,必須回顯給用戶,不要當成原樣生效。
4. 執行方式
完整參數說明見 references/options.md;欄位層級 Schema 見
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);banner / 進度 / 錯誤日誌都在 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 | 執行錯誤(網路 / 超時 / 介面異常 / 參數非法) | 展示 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當成「用戶要的內容不存在」以外的結論(不等於介面壞了)。 - ❌ 不在用戶未同意時自動放寬搜尋條件。
6. 結果消費建議(提升最終交付品質)
拿到 results 後,按用戶原始目標組織輸出,而不是原樣吐 JSON:
- 選題調研 → 按
digg_count降序取 Top 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 公開可見資料(暱稱、公開作品、公開評論)。不含手機號碼、位置、私訊等隱私欄位。資料僅限個人 / 團隊內部分析;對外發布或商用前請自行確認授權,並對用戶暱稱等做去敏處理。
- 無第三方依賴:僅使用 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、查閱用量與介面說明)。
- 變更記錄:references/changelog.md