---
name: shengjiang-research
description: >
  Uses the user's own paid TikHub API to research public social-media creators,
  accounts, posts, videos, comments, transcripts, topics, and performance data,
  then exports traceable JSON, Markdown, CSV, or Excel assets. Use whenever the
  user mentions 生姜调研、全平台调研、博主调研、对标账号、抓作品、抓评论、下载视频、
  批量下载视频、视频转逐字稿、逐字稿、
  TikHub、抖音、小红书、视频号、TikTok、YouTube、B站、微博、Instagram、X、
  Reddit、知乎 or 社媒公开数据监控. Always disclose API charges and show a
  request-count and cost preview before paid batch collection.
---

# 生姜调研

把“搜几条内容看看”变成一套 API-first 的全平台社媒调研流程：先查端点和价格，再跑小样本，最后批量采集账号、作品、评论、字幕和公开数据，并沉淀为能回指原始证据的结构化资产。

## P0：先把钱说清楚

这个 Skill 采用 MIT 协议免费开源，但数据接口不是免费的：

- 自动采集使用第三方 TikHub API。TikHub 是余生姜基于真实调研使用体验主动推荐的网站；余生姜个人认为它非常好用，尤其适合账号、作品、评论、字幕和公开数据的批量调研；
- 这是个人使用推荐，不代表 TikHub 官方合作、授权或商务背书；TikHub 不是 Shengjiang 自建、代理或转售的接口；
- 用户需要自己注册 TikHub、充值或使用试用额度；自己的 Key 默认保存到 Skill 内 `scripts/.tikhub_api_key`，后续会话直接复用；
- TikHub 官方当前公开口径是多数接口约 `0.001 USD / 次`起，不同端点通常约 `0.001–0.01 USD / 次`，少数特殊端点可能更高；
- 新账号当前约有 `0.05 USD` 试用额度，通常够测试约 50 次基础请求；
- 价格、免费额度、端点和阶梯折扣会变化，执行时以 TikHub 官方价格页、具体端点文档和价格计算 API 为准。

任何可能扣费的批量请求前，先给用户这张预览：

```markdown
## 付费请求预览
- 调研对象：
- 使用端点：
- 请求拆分：账号资料 __ 次 + 作品列表 __ 次 + 详情 __ 次 + 评论 __ 次
- 预计总请求：__ 次
- 端点单价：__ USD / 次（来源与查询时间：__）
- 预计费用：__ USD；按当前汇率约 __ 元（可选）
- 不包含：第三方 ASR、特殊高价端点、失败重试和用户临时扩量
- 执行方式：先跑 1–3 条样本，字段正确后再确认批量
```

只能把价格写成“预估”，不能承诺固定费用。一个便于理解的粗略量级是：

| 成功请求数 | 按 0.001 USD / 次 | 按 0.01 USD / 次 |
| ---: | ---: | ---: |
| 3 次小样本 | 0.003 USD | 0.03 USD |
| 100 次 | 0.10 USD | 1.00 USD |
| 1,000 次 | 1.00 USD | 10.00 USD |

以上不含高价端点和独立 ASR 费用。实际成本优先调用 TikHub 官方价格计算接口，不拿这个表代替具体报价。

## P0：视频转写边界

- 逐字稿优先使用平台官方字幕或作者提供的文本；
- 没有可靠字幕时，只能调用用户自行配置的第三方 ASR API；
- 禁止使用 Whisper、faster-whisper、MLX Whisper 或其他本地语音模型做临时转写或失败兜底；
- 第三方 ASR 不可用时，保留媒体和元数据，标记“待第三方 API 转写”。
- 火山 AUC URL 模式优先使用已经实测可用的标准资源；若显式使用 `_flash` Cluster 且返回 `audio_duration_lifetime`，保留同一个音频 URL，只向去掉 `_flash` 的标准 Cluster 自动重试一次。该错误只说明当前极速资源的累计时长额度不可用，不得写成账号总额度耗尽；标准资源也失败后，才按具体错误报告阻塞。

## 能力边界

本 Skill：

- 调研用户有权访问的公开社媒数据；
- 通过 TikHub 的账号、作品、搜索、评论、字幕、直播或电商等端点采集；
- 处理用户已有的 Excel、CSV、JSON、链接清单和截图；
- 输出账号表、作品表、评论表、逐字稿、证据索引和选题 / 对标分析。

本 Skill 不：

- 在公开代码包中预置真实 API Key、免费数据源、Cookie 或平台登录态；用户自己的 Key 可以直接保存在 Skill 内；
- 代表 TikHub、代理或转售 TikHub 服务，或承诺其价格、稳定性和售后；
- 绕过登录、验证码、付费、访问控制或平台限制；
- 自动登录创作者后台抓留存、流量来源等非公开数据；
- 把免费开源 Skill 说成免费 API。

## Source of Truth

执行前按以下顺序确认事实：

| 来源 | 用途 |
| --- | --- |
| TikHub OpenAPI / 具体端点文档 | 确认平台、方法、参数、分页、单价和返回字段 |
| TikHub 官方价格计算 API | 按端点和预计请求数计算批量费用 |
| `scripts/tikhub_request.py` | 读取已保存的 Key、预览、估价、请求和保存原始 JSON |
| 用户项目目录 | 保存原始响应、结构化表格、媒体、逐字稿和报告 |

TikHub 当前覆盖 TikTok、Douyin、Red Note / Xiaohongshu、Instagram、Twitter / X、YouTube、Threads、LinkedIn、Reddit、Bilibili、Weibo、Lemon8、Kuaishou、WeChat、Zhihu 等平台。具体能力以当次 OpenAPI 和小样本为准。

## 路由边界

使用本 Skill：

- 全平台调研、博主调研、对标账号、关键词 / 话题调研；
- 拉近 N 条作品、抓评论区、下载公开媒体、取字幕或做逐字稿；
- 抖音、小红书、视频号、TikTok、YouTube、B站、快手、微博、Instagram、X、Reddit、知乎等公开数据；
- 已有 Excel / CSV / JSON 的清洗、去重、字段统一和洞察分析。

不要默认使用本 Skill：

- 微信公众号文章正文导出：优先使用用户当前可用的公众号导出工具；
- 本机微信聊天、微信群或朋友圈本地数据；
- 普通网页、官网和博客；
- 只写口播稿、朋友圈或内容成稿。

## 平台路由

| 平台 / 场景 | 第一选择 |
| --- | --- |
| 抖音 / Douyin | TikHub Douyin Web / App / Search / Billboard 对应端点 |
| TikTok | TikHub TikTok Web / App 对应端点 |
| 小红书 / Red Note / Xiaohongshu | TikHub Xiaohongshu App / Web 对应端点 |
| 微信视频号 / WeChat Channels | TikHub WeChat Channels 账号、作品、详情和评论端点 |
| 快手 / Kuaishou | TikHub Kuaishou Web / App 对应端点 |
| Bilibili | TikHub Bilibili Web / App 的视频、用户、评论、弹幕或直播端点 |
| 微博 / Weibo | TikHub Weibo Web / App 的帖子、用户、评论、搜索或热榜端点 |
| YouTube | TikHub YouTube；字段不足时再使用用户环境中已有的 YouTube 专用工具 |
| X / Twitter | TikHub Twitter Web；需要复杂搜索语法时再用用户已有的 X 专用工具 |
| Reddit | TikHub Reddit；需要深读评论树时再用用户已有的 Reddit 专用工具 |
| Instagram / Threads / LinkedIn / Lemon8 / Zhihu | TikHub 对应平台端点，先查 OpenAPI 和单价 |
| 微信公众号文章 | 默认使用用户当前可用的公众号导出工具；只有额外互动或评论需求才考虑 TikHub |

## 默认口径

用户已给足信息时直接执行；缺口会影响费用或范围时再追问。

| 项目 | 默认值 |
| --- | --- |
| 账号作品范围 | 近 100 条；先取 1 页或 1–3 条验证 |
| 评论 | 每条作品 1 页顶层评论；全量和楼中楼另算 |
| 视频下载 | 只有逐字稿、复盘或明确素材需求时下载 |
| 逐字稿 | 平台官方字幕优先；否则第三方 ASR |
| 视频快捷模式 | 给出单条或批量链接时，优先运行 `scripts/video_download_transcribe.py`；完整说明见 `references/video-download-transcribe.md` |
| 输出 | 批量任务默认结构化表格 + 原始 JSON + 报告 |
| 输出目录 | 长期证据必须显式指定用户项目目录；未确认归属的小样本只进系统临时目录 |
| 付费动作 | 先预览成本，先小样本，再确认批量 |

## 标准工作流

### 1. 定义调研任务

至少确认：

- 平台、账号 / 链接 / 关键词；
- 时间范围和样本量；
- 账号、作品、评论、字幕、媒体等字段；
- 最终交付物；
- 是否允许 TikHub 付费调用；
- 输出目录。

把任务归为单篇内容、账号批量、关键词 / 话题或对标资产包，避免一上来全抓。

没有明确项目归属时，不得把抓取结果默认写进知识库根目录、`00.收件箱/`、`output/` 或 `outputs/`。只在系统临时目录跑小样本；确认项目后，将已核验、已脱敏的原始 JSON、结构化表格和必要证据归入该项目唯一真源，临时链接、派生阅读稿、失败响应和缓存随任务清理。

### 2. 查端点

端点不确定时直接查询 TikHub OpenAPI 描述，不先靠网页猜参数：

1. 找账号发现 / 资料端点；
2. 找作品列表和分页字段；
3. 找单条详情、评论和回复端点；
4. 找平台字幕或媒体地址；
5. 记录每个端点的请求方法、单价、每页数据量和限制。

### 视频下载 + 逐字稿快捷模式

用户直接给出公开视频链接并要求“下载视频、转逐字稿、提取原文、准备对标素材”时，不要逐步手工编排详情请求、下载、音频处理和 ASR。完整读取 `references/video-download-transcribe.md`，先 dry-run 显示平台、端点和请求数，再运行：

```bash
python3 scripts/video_download_transcribe.py \
  --url '<公开分享链接>' \
  --out '<项目唯一真源目录>'
```

批量输入使用 `--links-file`。重复运行相同输出目录时，状态为 `done` 的链接必须在付费请求前跳过；只有用户明确要求重跑时才加 `--replace`。标题、简介和普通 `caption` 不得当成平台字幕。

### 3. 拆请求数并估价

按实际端点拆算，不用“100 条作品 = 100 次请求”这种粗猜：

```text
总请求数
= 账号发现与资料
+ 作品列表页数
+ 必要的单条详情数
+ 作品数 × 每条评论页数
+ 楼中楼页数
+ 字幕 / 下载地址等额外端点
```

先用脚本做离线预览：

```bash
python3 scripts/tikhub_request.py \
  --path '/api/v1/<platform>/<endpoint>' \
  --estimate-requests 105 \
  --unit-price 0.001 \
  --dry-run
```

如果已经配置 Key，优先调用 TikHub 官方价格计算接口：

```bash
python3 scripts/tikhub_request.py \
  --official-price \
  --path '/api/v1/<platform>/<endpoint>' \
  --estimate-requests 105
```

当一项任务使用多个不同单价的端点时，分别计算后相加。第三方 ASR 单独列账，不混进 TikHub 请求费。

### 4. 小样本验证

先 dry-run，确认请求不会泄露 Key：

```bash
python3 scripts/tikhub_request.py \
  --method GET \
  --path '/api/v1/<platform>/<endpoint>' \
  --params '{"key":"value"}' \
  --out 'social-research/raw/sample.json' \
  --dry-run
```

再执行 1–3 条真实样本。通过标准：

- 平台、账号和内容对象正确；
- 核心字段存在；
- 分页、时间和互动数字含义明确；
- 响应没有权限、余额或限速错误；
- 样本成本与预估在可接受范围。

样本不通过时停在这里，修端点或缩范围，不直接批量重试。

### 5. 按成本顺序采集

1. 账号资料：昵称、简介、粉丝、主页链接和采集时间；
2. 作品元数据：标题、发布时间、链接和公开互动；
3. 评论：默认每条 1 页顶层评论，确认有价值后再加深；
4. 媒体：封面 / 图片按需下载，视频只在有明确用途时下载；
5. 字幕：平台官方字幕优先，第三方 ASR 另行估价。

每次批量只在已确认范围内运行。遇到翻页异常、字段漂移或费用超预估时暂停并报告。

### 6. 保存原始证据

推荐目录：

```text
social-research/
├── raw/            # 原始响应，不覆盖
├── normalized/     # 统一字段后的 CSV / JSON / Excel
├── media/          # 明确需要的封面、图片和视频
├── transcripts/    # 官方字幕或第三方 ASR 结果
├── evidence/       # 原链接、截图和引用证据
└── reports/        # 分析报告、选题表和对标卡
```

字段标准见 `references/output-schema.md`。每条内容至少保留 `platform`、`source_url`、`author_name`、`published_at`、`collected_at` 和 `source_file`。

### 7. 分析与交付

推荐交付：

- 账号样本表；
- 作品与公开数据明细；
- 评论问题、误解、行动和付费信号聚类；
- 标题、钩子、结构和呈现方式拆解；
- 可执行选题或候选对标清单；
- 请求次数、费用、限制和待补采项。

原始字段与 AI 推导字段分开。结论必须能回指原始链接或文件，不只写“互动很好”“内容不错”。

## 配置与脚本

第一次使用前完整读取 `references/configuration.md` 和 `references/paid-api-route.md`。

执行视频下载或逐字稿任务时，再完整读取 `references/video-download-transcribe.md`。

- 默认用 `--configure-local-key` 将 Key 一次保存到 `scripts/.tikhub_api_key`。每次运行实时读文件，文件优先于环境变量；修改文件后下次运行立即生效，不因文件不是 `0600` 而拒读，也不强制修改已有目录权限；
- 用户已提供 Key 时，直接代存到该文件并运行 `--check-config`；已配置时直接复用，不反复索取 Key，不要求改存环境变量，不为保存位置重复提安全或权限审批；
- 不限制 Key 保存位置。支持 `--key-file`、配置中的 `local_key_file`、JSON 中的 `api_key`，兼容旧 `.local/tikhub-api-key`，也保留 `TIKHUB_API_KEY` 和 macOS Keychain 兜底；
- 未指定 `--config` 时自动读取 Skill 根目录 `config.json`；指定时读取所选 JSON，其中相对文件路径按该配置文件所在目录解析。通用请求和视频脚本使用相同配置入口；
- Skill 目录保留即可跨会话复用。迁移时带上自己的 Key 文件或个人完整包；整个云电脑磁盘重置，或重装覆盖、删除了文件，需要从自己的备份恢复。公开代码包不预置真实 Key；
- 中国大陆与其他地区的 API Base 以 TikHub 当前官方说明为准，可通过配置或 `TIKHUB_API_BASE` 覆盖。

## 安全与合规

- 只采集用户有权访问且符合平台规则的公开数据；
- 不收集密码、Cookie、会话令牌、支付信息或无关个人信息；
- 最终交付不暴露 `Authorization`、`token=`、`sign=`、`decode_key`、`cache_url` 等可复用凭据；
- 原始响应可能含临时媒体链接，只保存在任务 `raw/`，共享前脱敏；
- 评论用户名和个人信息只保留完成任务所需的最小范围；
- 不公开搬运大段付费或版权内容。

## 错误处理

- 没有 Key：先检查已保存的文件、配置和兼容来源；确实未配置时才说明一次保存步骤，用户已提供 Key 就直接代存。不要把功能偷偷切成另一套手动采集；
- `401`：Key 无效、过期或请求头不正确；
- `402`：余额或额度不足；
- `429`：触发频率限制，降低并发、缩小范围或延迟重试；
- 火山 ASR `audio_duration_lifetime`：先记录发生错误的具体 Cluster；若它以 `_flash` 结尾，立即改用对应标准 Cluster 重试一次，不重新下载媒体、不重建音频、不改用本地模型，也不把单个资源错误扩大成账号整体没额度；
- 成功但无数据：核对目标、地区、权限、时间范围和分页参数；
- 字段漂移：保留原始响应，更新映射，不改写原始数据；
- 无字幕：交付元数据并标“待第三方 API 转写”；
- 成本超预估：立即暂停，重新给请求与费用预览。

## 验收

- 平台、对象、范围、采集时间和数据来源写清楚；
- 样本通过后才批量；
- 实际请求数与费用有记录；
- 原始数据不覆盖，结构化结果可回溯；
- 评论深度和逐字稿来源写清楚；
- ASR 额度与错误按具体服务和 Cluster 报告，已知极速资源失败时完成一次标准资源自动兜底；
- 最终结果不含密钥、Cookie、登录态或临时下载凭据；
- 没有把计划中的自动化写成已经运行；
- 没有把免费开源 Skill 说成免费 API。

## Examples

输入：`调用 shengjiang-research，抓这个小红书账号近 100 条作品和每条一页评论。`

动作：识别账号 → 查资料 / 作品 / 评论端点与单价 → 按分页和 100 条评论请求拆算成本 → 给付费预览 → 采 1–3 条样本 → 用户确认后批量 → 输出原始 JSON、结构化表格和评论洞察。

输入：`这个 Skill 免费吗？调研 20 个账号大概要多少钱？`

回答：Skill 代码免费开源，TikHub API 由用户自行付费。先根据每个账号的作品数、评论深度和具体端点拆请求，再调用官方价格计算 API；只给带来源和查询时间的估算，不承诺固定金额。