dbs-video-extract: 짧은 동영상 정보 추출
목표: 하나의 진입점으로 동일한 짧은 동영상 공유 문구를 처리합니다. TikHub는 抖音, 小红书 및 微信视频号의 구조화된 데이터를 제공하고, 轻抖는 짧은 동영상 음성 텍스트를 제공합니다. 최종적으로 데이터 요약과 Markdown 문서 경로를 반환합니다.
먼저 사용 자격 증명 확인
추출 작업을 시작하기 전에 먼저 읽기 전용 사전 검사를 실행합니다:
python3 scripts/extract_video.py --check-keys
credential_state에 따라 처리합니다:
| 상태 | 기능 | 사용자에게 반드시 알려야 할 사항 |
|---|---|---|
complete | 데이터와 텍스트 모두 사용 가능 | 두 부분 모두 실행 가능 |
data_only | TikHub 데이터 조회만 가능 | 작품/계정 데이터만 얻을 수 있으며, 음성 텍스트는 생성 불가 |
transcript_only | 轻抖 텍스트만 가능 | 음성 텍스트만 얻을 수 있으며, TikHub 작품/계정 데이터는 조회 불가 |
unavailable | 두 부분 모두 사용 불가 | 현재 사용 불가; 먼저 사용 자격 증명을 설명한 후, 사용자가 구매 및 설정을 완료하도록 안내 |
Key가 하나만 있어도 계속 진행을 허용하며, 사용자에게 다른 Key를 요구하지 않습니다. 실행 전에 이번에 해결할 수 있는 부분만 명확히 설명하고, 기본적으로 모드를 현재 사용 가능한 측으로 좁힙니다. 사용자가 both를 요청해도 단일 측 결과를 유지하고, 다른 측은 자격 증명이 부족하다고 표시합니다.
두 Key가 모두 없으면 추출을 중단합니다. 결론으로 직접 "API Key", "인터페이스 인증" 등의 용어를 사용하지 마십시오. 먼저 다음 문장으로 설명합니다:
이 Skill이 작동하려면 먼저 외부 데이터 서비스를 개통해야 합니다. API Key는 서비스 제공자가 개통 후 제공하는 일련의 사용 자격 증명으로, 이 Skill이 서비스를 호출하는 전용 통행증으로 이해할 수 있습니다. 기술 원리를 이해할 필요가 없으며, 대화에 보내지 마십시오.
그 후 사용자에게 다음과 같이 알립니다: "현재 두 서비스가 모두 개통되지 않았습니다. 최소한 하나를 구매하여 설정하지 않으면 이 Skill을 사용할 수 없습니다." 그런 다음 references/api-setup.md에 따라 요구 사항 선택, 구매, 자격 증명 저장 및 연결 테스트를 완료합니다.
사용자를 대신하여 비용을 지불하거나, 서비스 계약에 동의하거나, 전체 Key를 처리하지 마십시오. 사용자에게 Key를 대화에 보내도록 요구하지 마십시오. 구매 진입점, 단계별 안내, 안전한 설정 스크립트 및 연결 테스트는 references/api-setup.md를 참조하십시오.
사용자에게 구매 또는 충전 주소를 보여줄 때마다 먼저 다음 알림을 원문 그대로 표시해야 하며, 생략하거나 변경할 수 없습니다:
dbskill은 무료 오픈 소스 프로젝트로, TikHub, 轻抖와 제휴, 협력 또는 이익 관계가 없습니다. 충전은 사용자가 자발적으로 결정하며, 관련 거래, 서비스, 분쟁 및 위험은 사용자가 부담합니다. 법률에 달리 규정된 경우를 제외하고, dbskill은 책임지지 않습니다.
사용자가 구매 또는 충전 안내에 진입하지 않은 경우 반복해서 표시하지 마십시오.
자격 증명 부족 시 대화 요구 사항
어느 한 서비스가 부족할 경우, 응답은 다음 연속된 경로를 형성해야 합니다:
- 먼저 일반 언어로 API Key를 설명합니다;
- 사용자가 결과에 따라 선택하도록 합니다: 전체 기능, 데이터만, 텍스트만;
- 각 선택에 대해 어떤 서비스를 구매해야 하는지, 하나만 구매하면 무엇이 부족한지 설명합니다;
- 고정된 법적 알림을 표시한 후, 해당 충전 주소를 표시합니다;
- 가입/로그인, 요금제 확인, 충전, 개인 센터 또는 키 관리 페이지 진입, 자격 증명 획득을 단계별로 설명합니다;
- 사용자에게 자격 증명을 획득한 후 대화에 보내지 말고, "TikHub 충전 완료", "轻抖 충전 완료" 또는 "둘 다 충전 완료"라고 답변하도록 알립니다;
- 사용자가 충전 완료를 답변하면, 로컬 터미널에서 안전한 설정 스크립트를 실행하도록 안내합니다:
python3 scripts/configure_api_key.py tikhub
python3 scripts/configure_api_key.py qingdou
스크립트는 터미널에서 자격 증명을 은밀하게 읽어 로컬 개인 설정에 저장하며, 완전한 자격 증명을 명령, 응답 또는 로그에 표시해서는 안 됩니다. 저장 후 --check-keys를 다시 실행하여 해당 상태가 사용 가능해질 때까지 확인합니다.
한 번에 링크만 보내지 말고, 사용자가 자격 증명을 어디서 찾을지 알고 있다고 가정하지 마십시오. 서비스 제공자 페이지 이름이 변경된 경우, "개인 센터", "API Key", "키 관리", "개발자 설정" 등의 후보 위치로 안내합니다. 그래도 찾을 수 없는 경우, 사용자가 계정, 잔액 및 자격 증명이 가려진 페이지 스크린샷을 보내도록 한 후 계속 위치를 찾습니다.
사용자가 이 Skill만 호출하고, 아직 링크를 제공하지 않았거나 어떤 종류의 결과가 필요한지 명시하지 않은 경우, 자격 증명 사전 검사를 완료한 후 두 가지만 수행합니다: API Key를 설명하고, 사용자에게 1, 2 또는 3을 응답하여 전체 기능, 데이터만 또는 텍스트만을 선택하도록 요청합니다. 선택을 받은 후 법적 알림, 해당 충전 주소 및 구매 단계를 표시합니다. 사용자가 이미 동영상 링크를 보냈거나 전체 추출을 명시적으로 요청한 경우, 기본적으로 전체 기능을 선택하며 반복적으로 질문할 필요가 없습니다.
기본 실행
표준 입력을 우선 사용하여 공유 문구의 특수 문자가 Shell에 의해 해석되는 것을 방지합니다:
python3 scripts/extract_video.py \
--output-dir "/절대경로/짧은동영상텍스트" \
--stdin
기본 모드는 both입니다:
- 전체 공유 문구에서 링크를 추출합니다;
- 링크 플랫폼에 따라 TikHub MCP를 호출합니다: 抖音은 사용자 홈페이지 또는 단일 작품 지원, 小红书와 视频号는 단일 동영상 지원;
- 전체 공유 문구를 보존하여 轻抖 API에 제출하고, 폴링하여 텍스트를 얻습니다;
{출력 디렉토리}/{저자}/{제목}.md형식으로 텍스트를 저장합니다;- JSON 요약을 출력하며, 자격 증명 상태, TikHub 데이터 요약 및 텍스트 파일 경로를 포함합니다.
TikHub 또는 轻抖 중 한쪽이 실패해도 다른 쪽을 계속 완료하고, 요약에서 partial_success로 표시합니다. 이미 얻은 결과는 단일 측 실패로 인해 폐기해서는 안 됩니다.
선택적 모드
사용자가 명시적으로 한쪽 결과만 필요하거나, 사전 검사에서 한쪽 Key만 있음을 확인한 경우에만 전환합니다:
python3 scripts/extract_video.py --mode data --stdin
python3 scripts/extract_video.py --mode transcript --stdin
data: TikHub 데이터만 조회하며, 抖音, 小红书 및 微信视频号 지원;transcript: 텍스트만 추출하며, 轻抖 API가 구문 분석할 수 있는 플랫폼 지원;both: 양쪽 동시 실행.
동일한 출처가 이미 존재하는 경우 기본적으로 텍스트 쓰기를 건너뛰어 사용자 편집을 보호합니다. 사용자가 명시적으로 재생성을 요청한 경우 --overwrite를 추가합니다. TikHub 전체 응답이 필요한 경우 --raw-data를 추가합니다.
키와 비용
스크립트는 다음 순서로 Key를 읽습니다:
- 환경 변수:
TIKHUB_API_KEY,QINGDOU_API_KEY; - 사용자가 지정한 로컬 파일:
TIKHUB_API_KEYS_FILE,QINGDOU_API_KEYS_FILE; ~/.config/dbs/API_Keys.md;- macOS 키체인:
dbs-tikhub-api-key,dbs-qingdou-api-key.
Key를 Skill, 명령 인수, Markdown, Git 또는 로그에 기록하는 것을 금지합니다. TikHub 조회 및 轻抖 변환은 모두 요금이 부과될 수 있습니다. 실행 전에 사용자에게 알립니다. 사용자가 이미 명시적으로 추출을 요청한 경우 반복적으로 확인할 필요가 없습니다.
데이터 경계
- TikHub는 작품/계정 정보, 통계 및 미디어 메타 정보를 담당합니다. 抖音 작품은 App V3를 우선하며, 유효한 데이터가 없을 때만 1회 Web으로 폴백합니다. 小红书는 App V2 동영상 노트 상세 정보를 사용합니다. 视频号는 Channels V2 작품 상세 정보를 사용합니다.
- 轻抖는 음성 텍스트를 담당합니다. 본문은 API 반환 내용을 충실히 보존하며, 보충, 윤문 또는 구어체 오류 수정을 하지 않습니다.
- 현재 TikHub 전용 데이터 구문 분석은 抖音, 小红书 및 微信视频号를 지원하며, 다른 轻抖가 인식할 수 있는 플랫폼은 텍스트 추출만 실행할 수 있습니다.
- 공개, 삭제, 비공개, 저작권 및 가시성 범위 제한은 인터페이스 반환을 기준으로 하며, 우회를 시도하지 않습니다.
- 미디어 다운로드, 콘텐츠 게시, Git 제출 또는 푸시를 자동으로 수행하지 않습니다.
TikHub 호출 세부 사항은 references/tikhub-api.md를 참조하십시오. 轻抖 상태 코드 및 호환 논리는 references/qingdou-api.md를 참조하십시오. 해당 부분의 문제 해결 또는 유지 보수 시에만 읽습니다.
전달
완료 후 간결하게 보고합니다:
- 현재 구성된 API Key와 사용 가능한 기능 범위;
- 데이터 조회 성공 여부, 사용된 MCP 도구, App → Web 폴백 발생 여부;
- 주요 작품/계정 데이터;
- 텍스트 성공 여부, 생성되거나 건너뛴 Markdown 절대 경로;
- 단일 측 Key 부족 또는 실행 실패의 구체적인 이유;
- 인터페이스가 명시적으로 요금이 부과되었음을 반환했는지 여부.
응답에 API Key, batchId 또는 불필요한 내부 요청 식별자를 표시하지 마십시오.
현재 작업을 완료한 후 직접 종료합니다. 사용자가 명시적으로 다음 단계를 묻고, 현재 환경에 /dbs가 설치된 경우에만 간략히 알립니다: "다음 단계가 확실하지 않으면 /dbs를 입력하십시오."