social-fetch

/social-fetch — 按 URL 获取任意社交帖子

跨平台社交帖子标准化获取器。根据 URL 检测平台，按顺序尝试不同策略，无论来源如何都返回相同的 JSON 结构。

第 1 步 — 检测平台

URL 模式	平台
x.com/<user>/status/<id> 或 twitter.com/<user>/status/<id>	x（Twitter）
linkedin.com/posts/<slug> 或 linkedin.com/feed/update/urn:li:activity:<id>	linkedin
linkedin.com/in/<handle>（个人资料、近期动态）	linkedin-profile
instagram.com/p/<id> 或 instagram.com/reel/<id>	instagram
tiktok.com/@<user>/video/<id>	tiktok
bsky.app/profile/<handle>/post/<rkey>	bluesky
reddit.com/r/<sub>/comments/<id>/...	reddit
<mastodon-instance>/@<user>/<id>（例如 mastodon.social、hachyderm.io）	mastodon
threads.net/@<user>/post/<id>	threads
news.ycombinator.com/item?id=<id>	hn
youtube.com/watch?v=<id> 或 youtu.be/<id>	→ 转交给 watch-video

如果 URL 不匹配任何模式，询问用户这是哪个平台。

第 2 步 — 选择策略链

阅读 references/strategies.md，查看各平台对应的策略链。每个平台有 2–5 个按顺序尝试的策略。

关键原则：

• 优先使用免费策略（直接 API、agent-browser）
• 仅在必要时使用付费策略作为后备（ScrapeCreators / Apify），且仅在设置了环境密钥时使用
• Bluesky / Mastodon / HN / Reddit 免费且可靠（公共 API）
• X / LinkedIn / Instagram / TikTok / Threads 若要获取完整数据，需要付费或抓取后备方案

第 3 步 — 执行策略

对于策略链中的每个策略：

1. 尝试该策略
2. 如果成功：解析 → 标准化 → 返回
3. 如果失败（404、402、身份验证墙、响应为空）：记录失败原因，然后尝试下一个策略

尝试完所有策略后，返回明确的错误：列出尝试过的策略、各自失败的原因，以及解锁所需条件（例如：“为 X 添加 $SCRAPECREATORS_API_KEY — 参见 references/auth-keys.md”）。

第 4 步 — 标准化输出

无论平台如何，都返回以下结构（完整规范和各平台示例参见 references/output-schema.md）：

{
  "platform": "x",
  "url": "https://x.com/example/status/1234567890",
  "fetched_at": "2026-06-17T14:35:00Z",
  "raw_source": "scrapecreators",
  "author": {
    "handle": "@example",
    "name": "the user Ganim",
    "verified": true
  },
  "posted_at": "2026-06-17T16:53:00Z",
  "text": "The 80/20 of a useful AI second brain: ...",
  "media": [],
  "engagement": {
    "likes": 51,
    "reposts": 13,
    "replies": 9,
    "bookmarks": 7,
    "views": 32700
  },
  "is_thread": true,
  "thread": [],
  "replies": []
}

平台上没有对应项的字段（例如 Mastodon 上的 bookmarks）应设为 null，而不是 0。缺少数据与数据为零并不相同。

第 5 步 — 可选增强

根据标志 / 请求执行：

标志	行为
--with-replies	获取顶层回复（1 层）。会额外消耗 API 配额。
--thread	如果该帖子属于同一作者发布的帖子串，则获取整个帖子串。
--raw	在输出中包含原始 API / 抓取响应（用于调试）
--media	将媒体文件（图片 / 视频）下载到 ~/Documents/social-fetches/<platform>-<id>/

默认行为：仅获取帖子本身，不获取回复，不下载媒体（只提供 URL）。

第 6 步 — 缓存（可选）

如果 ~/Documents/social-fetches/_cache/ 存在，则将成功获取的内容按 {platform}-{id}.json 缓存 24h。同一帖子在不同技能中反复引用时，可节省 API 配额。

如果设置了 --no-cache 标志，或者使用了 --with-replies / --thread（内容可能已过时），则跳过缓存。

可组合使用

• deep-research — 在研究简报中引用特定帖子。研究发现相关推文 / 帖子 URL 时，获取该内容并纳入简报。
• jab-hook — 获取灵感账号的近期帖子，以深入分析内容形式（目前在行内使用 agent-browser；应改为调用此技能）。
• business-brainstorm — 在评分时获取竞争对手 / 从业者的观点作为证据。
• second-brain — 使用 tweet- / bookmark- 前缀将帖子保存到 raw/；与截图或复制粘贴相比，结构化输出可生成更整洁的原始文件。
• watch-video — 处理 YouTube URL（或任何视频，包括 Loom、Vimeo、Riverside、MP4），改为转交给该技能。

已知限制

• X：免费策略仅返回推文预览（文本、作者和基本互动数据）。完整帖文串和回复需要 $SCRAPECREATORS_API_KEY 或 $APIFY_API_TOKEN。
• LinkedIn：agent-browser 可用于查看个人资料的近期动态（需先关闭弹窗）。特定帖文 URL（linkedin.com/posts/...）通常需要付费备用方案。
• Instagram / TikTok / Threads：反机器人机制很强烈。强烈建议使用付费备用方案。
• Bluesky / Mastodon / HN / Reddit：免费且可靠。
• 私密 / 已删除的帖文：没有办法解决。对于已删除内容，可以尝试 Wayback Machine。

如果某个平台的免费策略持续失败，而用户又经常使用该平台，请提示用户设置付费密钥（参见 references/auth-keys.md）。

质量说明

• 采用策略链，而非单一来源。 每个平台都有备用方案阶梯（原生 oEmbed → agent-browser → SCS API → Apify）。某一步失败时，应平稳切换到下一步。首次尝试失败时，绝不要直接报错。
• 结构化输出优于截图。 下游技能（jab-hook、deep-research、second-brain）需要包含作者、文本和互动数据字段的 JSON，而不是图片。即使底层策略使用截图，也要先提取文本再返回。
• 积极缓存，诚实失效。 ~/Documents/social-fetches/_cache/ 中的 24h TTL 可避免同一会话中多个技能引用同一帖文时重复消耗 API。--with-replies / --thread 会跳过缓存，因为回复变化很快。
• 尊重付费密钥的成本。 ScrapeCreators / Apify 调用会产生实际费用。如果用户尚未确认需要深入抓取，调用付费策略前应先征得同意。始终优先使用免费策略。
• 媒体下载需选择启用。 默认只获取帖文文本；--media 会下载图片 / 视频。静默下载媒体会很快占满磁盘。
• 私密 / 已删除内容无法挽回。 任何策略链都无法获取私密账号或已删除的帖文。对于已删除内容，建议尝试 Wayback Machine，然后停止。
• 各平台的速率限制彼此独立。 X 的免费策略很快会触及速率限制；LinkedIn 的 agent-browser 会消耗会话指纹。在循环中应拉开调用间隔，否则工作流的效果会比手动操作更差。