Social Media Scout

Social Media Scout — 跨平台社交媒体数据查询

作者：43 COLLEGE 凯寓 (KAIYU) 出品 版本：v1.0

通过 TikHub API 获取 926+ 个社交媒体接口的数据。

首次配置

如果命令报错找不到 config.json、api_key 为占位符、或返回 401，读取本目录下的 SETUP.md 并按其中的流程引导用户完成配置。

跨平台兼容

调用架构（重要，先读这段）

本 skill 有两条调用路径，理解这个是避免踩坑的前提：

call_tool() 已实现自动降级：先尝试 MCP，404/连接失败时自动切换 REST。也可用 rest_call() 或 CLI rest-call 命令直接走 REST。

工具名 → REST 路径映射规则：

{platform}_{module}_{method} → /api/v1/{platform}/{module}/{method}

示例：

• douyin_search_fetch_user_search → /api/v1/douyin/search/fetch_user_search
• douyin_web_handler_user_profile → /api/v1/douyin/web/handler_user_profile

HTTP 方法规则：搜索类（工具名含 _search_）用 POST + JSON body，其余用 GET + query params。如果猜错会自动 405 重试。

资源位置

• 脚本目录: scripts/（skill 根目录下，相对路径）
• API 配置: scripts/config.json（含 API Key、MCP 代理路径）
• MCP 代理（Windows）: 按 config.json 中 mcp_proxy_exe 路径配置
• MCP 代理（Mac）: 不适用，使用 REST 直调模式即可
• TikHub 文档: https://docs.tikhub.io
• API Key 管理: https://user.tikhub.io

使用场景

• 查询用户资料（抖音/TikTok/小红书等）
• 搜索关键词相关的视频、笔记、帖子
• 通过分享链接解析视频数据
• 获取视频评论、用户粉丝/关注列表
• 查看平台热搜榜单
• 下载无水印视频
• 获取微信公众号文章列表（需 ghid）
• 提取微信公众号指定文章内容

调用方式

所有命令必须先 cd 到 skill 根目录再执行。 Python 命令参考跨平台兼容表。

# macOS/Linux 示例（Windows 将 python3 替换为 python，单引号替换为转义双引号）

# 调用工具（MCP 优先，自动降级 REST）
python3 scripts/tikhub_client.py call <tool_name> --args '{"param": "value"}'

# 直接走 REST API（推荐，跳过 MCP 代理）
python3 scripts/tikhub_client.py rest-call <tool_name> --args '{"param": "value"}'

# 按平台列出工具
python3 scripts/tikhub_client.py list --platform douyin

# 按关键词搜索工具
python3 scripts/tikhub_client.py list --keyword search

Python 内联调用（推荐用于复杂任务）:

import os, sys
# 必须用绝对路径，确保从任何 cwd 都能加载
skill_dir = os.path.expanduser("~/.claude/skills/social-media-scout")
sys.path.insert(0, os.path.join(skill_dir, "scripts"))
from tikhub_client import call_tool, rest_call, parse_user_search_results, extract_video_url, download_file

常用工具速查

抖音 (douyin)

搜索类（推荐 douyin_search_*，比 douyin_web_fetch_*_search_* 更稳定）:

用户资料:

作品获取（获取全部作品用 App 接口，Web 接口有分页深度限制约 80 条）:

互动数据:

小红书 (xiaohongshu)

B站 (bilibili)

重要：B站接口稳定性差，web 和 app 的用户资料/作品列表接口经常 500。以下是经过实测验证的可靠路径。

搜索类:

用户资料（获取粉丝数的可靠方法）:

如果 TikHub 接口全部 500，可用 Python 直接调 B站公开 API 作为备选（仅使用内置库，无需安装额外依赖）:

import urllib.request, json
mid = '目标UID'
headers = {'User-Agent': 'Mozilla/5.0 (compatible)', 'Referer': 'https://space.bilibili.com/'}
req = urllib.request.Request(f'https://api.bilibili.com/x/relation/stat?vmid={mid}', headers=headers)
with urllib.request.urlopen(req, timeout=10) as r:
    data = json.loads(r.read())
# data['data']['follower'] = 粉丝数, data['data']['following'] = 关注数
# 此接口无需 wbi 签名，较稳定

作品获取（核心踩坑点）:

互动数据:

B站推荐工作流

下载B站视频（TikHub 不适用，必须用 yt-dlp）:

先检测 yt-dlp 是否已安装：which yt-dlp（macOS/Linux）或 where yt-dlp（Windows）。

如果未安装，引导用户安装：

# macOS（需要 Homebrew）
brew install yt-dlp

# Windows（需要 pip）
pip install yt-dlp

# Linux
pip3 install yt-dlp

下载命令：

yt-dlp \
  --output "/目标目录/文件名.%(ext)s" \
  --format "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best" \
  --no-playlist \
  "https://www.bilibili.com/video/BVxxx"

1080P 60帧需要大会员 cookie（--cookies-from-browser chrome），普通 1080P 无需登录。

查询UP主信息的标准流程（避免踩坑）:

1. 搜索用户 → bilibili_app_fetch_search_by_type（search_type="bili_user"）
   • 返回结果中：item[0].param = UID，item[0].author_new.fans = 粉丝数（可能不精确）
2. 获取精确粉丝数 → bilibili_web_fetch_user_relation_stat（vmid=UID）
   • 如果 500，备选直接 requests 调 api.bilibili.com/x/relation/stat
3. 获取最新视频 → bilibili_web_fetch_user_dynamic（uid=UID, offset=""）
   • 不要用 bilibili_web_fetch_user_post_videos 或 bilibili_app_fetch_user_videos，它们经常 500
   • 动态接口每页约 12 条，用返回的 data.offset 翻页
   • 视频数据在 item.modules.module_dynamic.major.archive 中
4. 解析动态中的视频数据:

items = resp['result']['data']['data']['items']
for item in items:
    archive = item['modules']['module_dynamic']['major'].get('archive', {})
    if archive:  # 跳过纯文字/转发动态
        title = archive['title']
        bvid = archive['bvid']
        stat = archive['stat']  # play, danmaku
        duration = archive['duration_text']
        pub_time = item['modules']['module_author']['pub_time']

TikTok

通用

微信公众号 (wechat_mp)

重要：TikHub 的微信公众号接口必须直接调用 REST API，不能走 MCP 工具系统（/tools 端点返回 404）。

调用方式（固定模板）：

import urllib.request, json, urllib.parse, os

# 从 config.json 读取 API Key
skill_dir = os.path.expanduser("~/.claude/skills/social-media-scout")
with open(os.path.join(skill_dir, "scripts", "config.json")) as f:
    api_key = json.load(f)["api_key"]

headers = {'Authorization': f'Bearer {api_key}', 'User-Agent': 'TikHub/1.0'}

def wechat_mp_get(path, params):
    url = f'https://api.tikhub.io{path}?' + urllib.parse.urlencode(params)
    req = urllib.request.Request(url, headers=headers)
    with urllib.request.urlopen(req, timeout=30) as r:
        return json.loads(r.read())

接口列表：

文章列表返回结构：

data = resp['data']
articles = data['list']   # 文章数组
next_offset = data['offset']  # 翻页游标，传给下次请求的 offset 参数

for a in articles:
    title = a['Title']
    url = a['ContentUrl']       # 文章长链，传给 fetch_mp_article_detail_html（JSON 接口不支持长链）
    send_time = a['send_time']  # Unix 时间戳
    cover = a['CoverImgUrl']

文章详情返回结构：

data = resp['data']
title = data['title']
author = data['author']
ghid = data['publish_info']['user_id']   # 这就是公众号 ghid！
pub_time = data['publish_info'].get('type', '')
content_blocks = data['content']['raw_content']  # 结构化内容块列表
# 每个 block 有 type(p/h5/image/section) 和 text 字段

微信公众号标准工作流

已知文章 URL → 完整流程（推荐入口）:

1. 提取 ghid：调用 fetch_mp_article_detail_json，从 data.publish_info.user_id 拿到 ghid
2. 获取文章列表：调用 fetch_mp_article_list（ghid=上一步结果）
3. 提取指定文章：对目标文章 URL 调用 fetch_mp_article_detail_json

只有公众号名称 → 获取 ghid 的变通路径（有风险，搜狗可能反爬）:

1. 在微信 app 里打开该公众号任意一篇文章，复制链接
2. 将链接传给 Claude，执行步骤 1

注意：TikHub 无"按公众号名称搜索"的接口，必须从一篇该公众号的文章 URL 中提取 ghid。

工作流程

1. 识别目标平台
2. 根据需求选择工具（搜索/资料/作品/评论/下载）
3. 分享链接优先用 *_by_share_url 或 hybrid_video_data
4. 不确定参数名时用 list --keyword 查找
5. 调用工具并格式化输出

踩坑记录（重要）

以下为正文未覆盖的补充经验，已去除与前文重复的内容。

通用

1. 参数类型: 大部分参数需要传字符串（如 "0" 而非 0）
2. API 计费: 每次成功调用都会计费，避免不必要的重复请求。响应中有 cache_url 可免费重复访问（24h 有效）
3. 分页去重通用策略: 所有平台批量抓取时，用 dict/set 按 ID 去重，并设置"连续 N 页无新数据则停止"的安全机制
4. Windows 内联 Python 编码: 处理中文/emoji 时，在脚本开头加 import sys; sys.stdout.reconfigure(encoding='utf-8')，或用 python -X utf8 启动。tikhub_client.py 已内置此处理

抖音

5. 用户搜索数据结构特殊: douyin_search_fetch_user_search 返回的用户信息嵌套在 dynamic_patch.raw_data（JSON 字符串）中，必须用 parse_user_search_results() 解析
6. 视频下载链接字段不统一: 不同接口返回字段名不同（video_url/play_url/play_addr 等），用 extract_video_url() 统一处理

小红书

7. Web 接口分页重复严重: xiaohongshu_web_get_user_notes_v2 分页有约 60% 重复率。获取全部笔记必须用 xiaohongshu_app_get_user_notes（App 接口），cursor 取每页最后一条笔记的 cursor 字段

B站

8. 搜索结果混合多个UP主: bilibili_app_fetch_search_by_type 搜索视频时，结果包含多个UP主，必须按 item.av.author 和 item.av.mid 过滤目标UP主
9. UID 有两种格式: item.param 是新版长 UID（如 3546620310326128），item.author_new.mid 是旧版短 mid（如 1680175）。调用其他接口时统一用长 UID（param 字段）
10. 动态数据解析路径: result.data.data.items[]，视频在 modules.module_dynamic.major.archive（含 title/bvid/stat/duration_text），作者在 modules.module_author。纯文字/转发动态没有 archive 字段，需跳过

微信公众号

11. 接口必须走 REST API: 微信公众号接口无法通过 MCP /tools 端点调用（返回 404），必须直接 HTTP 请求
12. 无法按名称搜索: 必须传 ghid（格式 gh_xxxxxxxx），从文章详情的 data.publish_info.user_id 获取
13. 搜狗微信反爬严重: 通过搜狗自动化获取 ghid 不可靠，最可靠方式是用户手动提供一篇文章链接
14. 文章 URL 格式影响接口选择: fetch_mp_article_detail_json 只接受短链（mp.weixin.qq.com/s/XXXXX），长链必须用 fetch_mp_article_detail_html。wechat_mp_get_article_detail() 已自动处理

辅助函数说明

tikhub_client.py 提供以下辅助函数:

• call_tool(name, args) - 调用任意 TikHub 工具（MCP 优先，自动降级 REST）
• rest_call(name, args) - 直接走 REST API 调用（跳过 MCP 代理）
• list_tools(keyword, platform) - 搜索可用工具
• parse_user_search_results(response) - 解析抖音用户搜索的嵌套数据
• extract_video_url(post_data, api_response) - 从多种数据结构中提取视频链接
• download_file(url, filepath) - 下载文件到本地
• extract_result_data(response) - 从 API 响应中提取 data 字段