shengjiang-research

生姜调研

把“搜几条内容看看”变成一套 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 为准。

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

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

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

以上不含高价端点和独立 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 当前覆盖 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：

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

平台路由

默认口径

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

标准工作流

1. 定义调研任务

至少确认：

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

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

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

2. 查端点

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

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

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

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

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

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

3. 拆请求数并估价

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

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

先用脚本做离线预览：

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

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

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

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

4. 小样本验证

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

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. 保存原始证据

推荐目录：

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；只给带来源和查询时间的估算，不承诺固定金额。