🎯 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이 아니라 다른 플랫폼(틱톡, 샤오홍슈, 빌리빌리, 웨이보, 위챗 공식계정)인 경우 → 해당 스킬로 라우팅하십시오. 본 스킬은 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를 참조하십시오. 필드 수준 스키마는
assets/아래 6개의 JSON 스키마(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 | 실행 오류 (네트워크/시간 초과/인터페이스 예외/매개변수 불법) | 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기준 내림차순으로 상위 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