🎯 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 중의성 해소 규칙 (반드시 준수)
- "동영상"이라는 단어만 단독으로 나오면 기본적으로
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 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: 토큰 누락 또는 형식 오류 | 즉시 중단, 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. 환경 및 지원
- 환경: Node.js ≥ 16.14.0, Windows/macOS/Linux 전체 플랫폼;
GUAIKEI_API_TOKEN필수. - 공식 웹사이트: TikTok 경쟁사 인사이트 분석 공식 웹사이트 (토큰 자체 발급, 사용량 및 인터페이스 설명 확인 가능).
- 변경 기록: references/changelog.md