Communitygithub.com

why20261/tiktok-insight

TikTok 경쟁사 인사이트 분석 도구로, 실시간으로 경쟁사의 트래픽 효과를 모니터링하고, 경쟁 대상 콘텐츠를 빠르게 분석하며, 경쟁사의 트래픽 및 전략을 정밀하게 분석하고, 효율적으로 키워드 라이브러리를 구축할 수 있습니다. TikTok 브랜드, 크리에이터 등이 경쟁사 분석, 트래픽 최적화, 키워드 연구를 수행하는 데 적합합니다.

tiktok-insight란 무엇인가요?

이 기술은 TikTok 공개 동영상, 작성자, 댓글 데이터를 구조화된 JSON 형식으로 직접 가져오는 AI 에이전트 기술입니다. TikTok 브랜드, MCN 기관, 콘텐츠 크리에이터에게 경쟁사 분석, 트래픽 최적화, 키워드 연구를 위한 강력한 데이터 수집 기능을 제공합니다. 핵심 기능으로는 키워드 검색(좋아요 수/관련도 순 정렬, 게시 시간 필터링), 작성자 콘텐츠 목록 가져오기(홈페이지 링크 또는 사용자 이름으로 일괄 가져오기, 최신/인기 순 정렬), 동영상 댓글 수집(동영상 링크 또는 ID로 댓글, 댓글 작성자, 상호작용 데이터 수집) 등이 있습니다. 모든 기능은 `GUAIKEI_API_TOKEN` 환경 변수 설정이 필요하며, 설정되지 않은 경우 모든 명령어가 오류 코드 3과 `AUTH_REQUIRED` 오류를 반환합니다. 사용자 의도에 따라 `search-cli`, `post-cli`, `comment-cli` 스크립트를 자동으로 라우팅하며, 불필요한 재시도 없이 오류 메시지를 명확히 표시합니다. 각 명령어는 통일된 JSON 응답 구조를 반환하여 AI 분석가가 데이터를 쉽게 처리하고 요약, 비교, 정렬, 클러스터링, 보고서 생성을 수행할 수 있습니다. 다양한 TikTok 관련 작업을 지원합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add why20261/tiktok-insight

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

🎯 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이 아닌 경우 (Douyin, Xiaohongshu, Bilibili, Weibo, WeChat 공식 계정 등) → 해당 스킬로 라우팅합니다. 이 스킬은 TikTok만 처리합니다.
  • 로그인 상태, 비공개, 숨겨진 데이터가 필요한 경우 → 지원하지 않습니다.
  • 키워드와 식별 가능한 링크가 모두 제공되었으며 목표가 불분명한 경우 → 먼저 질문을 하고 추측하지 마십시오.

2.3 능력 범위 (명시적으로 수행하지 않는 작업)

게시/좋아요/댓글/팔로우/다이렉트 메시지 등 쓰기 작업은 전혀 지원하지 않습니다. 어떤 계정에도 로그인하지 않습니다. 전화번호, 위치, 다이렉트 메시지 등 개인정보 필드를 수집하지 않습니다. 사용자를 대신하여 마케팅 결정을 내리지 않습니다 — 데이터를 가져오는 것이 역할이며, 분석은 상위 계층에 위임됩니다.


3. 호출 라우팅 (판단 후 실행)

사용자 의도스크립트판단 키워드
키워드 검색, 특정 콘텐츠 찾기, 바이럴 콘텐츠 찾기search-cli검색 / 찾기 / 키워드 / 바이럴 / 가장 인기 있는
특정 작성자/인플루언서/유명인의 게시물, 프로필, 계정, 최근 게시물 보기post-cli게시물 / 프로필 / 계정 / 작성자 / 인플루언서 / 유명인 / KOL
특정 동영상의 댓글 보기comment-cli댓글 / 의견 / 댓글 영역의 관점

3.1 중의성 해소 규칙 (반드시 준수)

  1. "동영상"이라는 단어만 단독으로 나오면 기본적으로 post-cli로 간주하지 마십시오.
    • "키워드"가 있고 "댓글"이 없는 경우 → search-cli (사용자가 해당 유형의 동영상을 검색하려는 경우)
    • "이 동영상의 댓글/의견"이 명확한 경우 → comment-cli
    • "게시물/프로필/계정/작성자/인플루언서"만 나타나는 경우 → post-cli
  2. 댓글은 게시물보다 우선순위가 높습니다. 링크가 /video/<id>이고 댓글에 대해 질문하는 경우 → comment-cli; "이 사람의 게시물"에 대해 묻는 경우 → post-cli (@username 사용)
  3. 사용자가 /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를 참조하십시오. 필드 수준 스키마는 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요청 실패nullerror_code에 따라 처리하고 데이터를 조작하지 않음

5.2 종료 코드

종료 코드의미Agent 동작
0성공 (success 또는 empty)계속 분석
1실행 오류 (네트워크/시간 초과/API 예외/잘못된 매개변수)message 표시, 사용자에게 매개변수 변경 재시도 여부 문의
3AUTH_REQUIRED: 토큰 누락 또는 형식 오류즉시 중단, GUAIKEI_API_TOKEN 설정 안내, 재시도 금지

5.3 오류 코드 처리

error_code처리 방식
AUTH_REQUIRED중단 및 토큰 설정 안내. 재시도, 매개변수 변경 우회 금지
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만 요청합니다. 로컬의 다른 파일을 읽지 않으며, 스킬 디렉토리 외부 경로에 쓰지 않습니다 (로그는 시스템 임시 디렉토리에 기록).
  • 자격 증명 보호: 토큰은 환경 변수에서만 읽으며, stdout, 로그, 오류 메시지에 기록하지 않습니다.
  • 데이터 전송 범위 (반드시 인지): 호출 시 www.guaikei.com에 전송되는 항목: 사용자의 API 토큰, 쿼리 키워드 또는 대상 URL/ID, 스킬 이름 및 Node 버전입니다. 이 외에는 로컬 정보를 수집하지 않습니다.
  • 데이터 규정 준수: TikTok에서 공개적으로 볼 수 있는 데이터 (닉네임, 공개 게시물, 공개 댓글)만 획득합니다. 전화번호, 위치, 다이렉트 메시지 등 개인정보 필드를 포함하지 않습니다. 데이터는 개인/팀 내부 분석용으로만 사용됩니다. 외부 공개 또는 상업적 사용 전에 권한을 직접 확인하고 사용자 닉네임 등을 비식별화 처리하십시오.
  • 타사 종속성 없음: Node.js 내장 모듈 (https/fs/path/os/querystring)만 사용하며, npm 종속성, 원격 스크립트 로드, eval/child_process가 없습니다.

8. 자주 묻는 질문

현상원인 및 처리
종료 코드 3 / AUTH_REQUIRED토큰이 설정되지 않았거나 형식이 잘못됨 (16–256자의 영숫자, 밑줄, 하이픈 필요)
검색 결과가 비어 있음보다 일반적인 키워드로 변경하거나 --time 0으로 시간 범위 해제; empty는 정상적인 결과이지 오류가 아님
결과 수가 --limit보다 적음서버에서 더 이상 반환할 수 없거나 단일 한도 초과로 잘림; ≤1000으로 줄여서 분할 획득
계속 시간 초과 발생--limit를 줄인 후 재시도; 스크립트는 지수 백오프 재시도를 내장
"가장 인기 있는 게시물"을 원했는데 시간 역순으로 정렬됨post-cli는 --sort 1을 사용해야 함
매개변수가 적용되지 않음 / 예상 정렬과 다른 결과출력의 warnings 확인; 매개변수가 유효하지 않으면 자동으로 기본값으로 롤백됨
로그 파일 위치stderr의 "저장됨 …" 행 참조 (시스템 임시 디렉토리 tiktok-guaikei/logs/<날짜>/)

9. 환경 및 지원

관련 스킬