Twitter/X Reader 技能

一项综合型技能，通过多个可靠数据源读取并提取 X（原 Twitter）推文中的数据。

概述

该技能可从 X/Twitter URL 中提取完整的推文信息，包括文本内容、作者详情、互动统计、媒体附件及被引用的推文。它采用多层级策略，以实现最高级别的可靠性与数据完整性。

适用场景

主要触发条件：

• 用户分享一条推文 URL（x.com//status/ 或 twitter.com//status/）
• 用户在提供 URL 的前提下请求“读取这条推文”
• 用户请求对推文进行分析、摘要或数据提取
• 用户提及需从某条特定推文中获取信息

用户请求示例：

• “这条推文说了什么？https://x.com/elonmusk/status/123456789”
• “你能帮我读一下这条推文吗？”
• “请总结这个 Twitter 话题串（thread）”
• “这条推文的互动数据是多少？”
• “请提取这条推文中的媒体内容”

能力说明

提取的数据

• 推文内容：含正确格式化的完整文本
• 作者信息：显示名称与账号（@username）
• 时间戳：同时提供人类可读格式与原始格式
• 互动统计：点赞数、转发数、回复数、引用推文数
• 媒体附件：照片与视频的直接 URL
• 引用推文：被引用推文的全部内容及其作者信息
• 话题串上下文：若可用则一并返回

支持的 URL 格式

• https://x.com/username/status/1234567890
• https://twitter.com/username/status/1234567890
• 含查询参数的 URL（例如 ?s=20、?t=abc123）
• 移动版 URL（m.twitter.com 自动兼容）

使用示例

基础用法

# 读取单条推文
./scripts/read_tweet.sh "https://x.com/username/status/1234567890"

# 读取完整话题串（沿同一作者的回复链向上追溯）
./scripts/read_thread.sh "https://x.com/username/status/1234567890"

# 使用 Nitter 的备用方法
./scripts/read_tweet_nitter.sh "https://x.com/username/status/1234567890"

智能体指令

当用户提供推文 URL 时，请执行以下步骤：

1. 校验 URL 格式 — 确保其为有效的 X/Twitter 状态页 URL
2. 优先调用主脚本 — 首先运行 scripts/read_tweet.sh
3. 容错降级处理 — 若主脚本失败，则尝试 scripts/read_tweet_nitter.sh
4. 清晰呈现结果 — 输出格式需便于人类阅读
5. 保留上下文信息 — 包含互动统计数据与媒体引用链接

响应格式示例

各脚本返回结构化 JSON，格式如下：

{
  "success": true,
  "tweet": {
    "text": "Tweet content here...",
    "author": {
      "name": "Display Name",
      "handle": "username"
    },
    "timestamp": {
      "formatted": "2024-01-15 14:30:25 UTC",
      "original": "Mon Jan 15 14:30:25 +0000 2024"
    },
    "url": "https://x.com/username/status/1234567890",
    "engagement": {
      "likes": 1250,
      "retweets": 340,
      "replies": 89,
      "quotes": 45
    },
    "media": {
      "photos": ["https://pbs.twimg.com/media/..."],
      "video": "https://video.twimg.com/..."
    },
    "quoted_tweet": {
      "text": "Quoted tweet text...",
      "author": {
        "name": "Quoted Author",
        "handle": "quoted_user"
      },
      "url": "https://x.com/quoted_user/status/987654321"
    }
  },
  "source": "fxtwitter",
  "fetched_at": 1705327825
}

智能体响应示例

**来自 @elonmusk 的推文：**
> "Just had a great meeting about sustainable transport. The future is electric! ⚡🚗"

**发布时间：** 2024 年 1 月 15 日 下午 2:30（UTC）
**互动数据：** 1,250 次点赞 • 340 次转发 • 89 条回复 • 45 次引用

**媒体：** 附带 1 张图片
- 图片：https://pbs.twimg.com/media/example.jpg

**引用推文来自 @teslaofficial：**
> "Our latest Model S update includes new charging optimizations..."

技术实现

主方法：FxTwitter API

• 接口地址：https://api.fxtwitter.com/{username}/status/{tweet_id}
• 优势：无需认证、数据全面、稳定性高
• 速率限制：个人使用额度充足
• 响应内容：包含全部推文元数据的完整 JSON

备用方法：Nitter 网页抓取（尽力而为）

• 实例来源：多个公开的 Nitter 实例作为备用节点
• 优势：当 FxTwitter 不可用时仍可工作
• 局限性：仅支持基础数据提取，不提供互动统计数据
• 使用方式：主方法失败时自动启用
• ⚠️ 注意：自 2024 年起，大多数公开 Nitter 实例已关闭或变得不可靠。该备用路径属于尽力而为型，可能无法返回结果。FxTwitter API 应被视为唯一可靠的主方法。

错误处理

• 检测无效 URL 格式
• 处理网络超时
• 解析 API 错误响应
• 在不同方法间平滑降级
• 向用户提供清晰易懂的错误提示

依赖项

必需系统工具：

• curl — 用于向 API 发起 HTTP 请求
• jq — 用于 JSON 解析与格式化
• bash — 脚本执行环境
• grep/sed — 文本处理（仅 Nitter 备用路径使用）

可选增强功能：

• gdate（macOS 上通过 Homebrew 安装的 GNU date）— 提供更优的时间戳格式化能力

安全与隐私

安全特性

• ✅ 不收集外部数据 — 所有数据保留在本地系统中
• ✅ 无分析或遥测行为 — 不进行任何追踪或使用情况上报
• ✅ 代码完全可审计 — 开源且脚本均为可读的 Shell 脚本
• ✅ 最小化网络调用 — 仅连接至 FxTwitter API 和 Nitter 实例
• ✅ 不暴露敏感数据 — 脚本不会存储或记录任何个人信息
• ✅ 安全的 URL 处理机制 — 包含完善的 URL 校验与清洗逻辑

网络连接

允许访问的外部主机：

• api.fxtwitter.com — 主数据源（FxTwitter API）
• nitter.net 及其他 Nitter 实例 — 备用网页抓取目标
• 不建立任何其他外部连接

数据流向：

1. 用户提交推文 URL
2. 脚本从 URL 中提取用户名与推文 ID
3. 向 FxTwitter 或 Nitter 发起 API 请求
4. 在本地解析响应内容
5. 返回格式化后的 JSON（永不持久化存储）

审计日志

所有网络请求均包含以下要素：

• 明确的 User-Agent 标识
• 仅发送必要最少的请求头
• 不携带任何认证令牌或个人标识符
• 请求目的仅为提取公开推文数据

错误场景与处理

常见错误

URL 格式无效：

{
  "error": "Invalid Twitter/X URL format",
  "expected": "x.com/user/status/123456789 or twitter.com/user/status/123456789"
}

推文未找到：

{
  "error": "API Error",
  "code": 404,
  "message": "NOT_FOUND"
}

网络故障：

{
  "error": "Failed to fetch tweet data",
  "details": "Network request failed"
}

需启用备用方案：

{
  "error": "All Nitter instances failed",
  "suggestion": "Try the main script with FxTwitter API, or wait for Nitter instances to recover"
}

智能体错误处理

发生错误时应执行以下操作：

1. 解析错误 JSON，定位具体问题原因
2. 主方法失败时尝试备用方法
3. 用自然语言向用户说明出错原因
4. 提供替代建议（稍后重试、检查 URL 格式等）

高级功能

话题串读取

通过 read_thread.sh 支持完整的话题串展开：

• 给定话题串中任意一条推文 URL，利用 replying_to 字段向上遍历回复链
• 仅采集同一作者发布的推文（即自我回复类话题串）
• 按时间顺序返回推文组成的 JSON 数组
• 每条话题串最多采集 50 条推文（可通过第二个参数配置）
• 用法：./scripts/read_thread.sh "https://x.com/user/status/123" [max_depth]

媒体处理

• 图片：通过 media.photos 数组提供高清分辨率直链
• 视频：通过 media.videos 提供 MP4 文件链接，并附带缩略图与时长信息
• 全部媒体：统一的 media.all 数组，带类型标注以覆盖全部媒体类型
• 文章封面：针对长文形式的 X 帖子（“articles”），提取 media.article_cover
• GIF：归类为视频内容处理
• 外部链接：保留在推文正文中

引用推文递归提取

该技能支持合理深度的嵌套引用推文提取，避免无限循环。

性能说明

响应时间

• FxTwitter API：通常为 200–500 毫秒
• Nitter 抓取：每个实例约 1–3 秒
• 网络依赖性：实际耗时取决于网络连接质量

缓存考虑

• 默认未实现持久化缓存
• 可考虑对重复请求启用临时缓存
• 须遵守外部服务的速率限制

故障排查

常见问题

“API 响应中无推文数据”

• 该推文可能已被删除或设为私密
• 请检查 URL 格式与推文 ID 是否正确
• 可尝试备用方法

“网络请求失败”

• 请检查网络连接状态
• FxTwitter API 可能处于临时宕机状态
• 可切换至 Nitter 方法

“所有 Nitter 实例均失败”

• Nitter 实例可能被屏蔽或已下线
• 建议等待后重试 FxTwitter API
• 请检查防火墙或代理设置

调试模式

如需调试，请启用详细输出：

bash -x scripts/read_tweet.sh "https://x.com/username/status/123"

开发与定制

新增数据源

如需添加额外的备用数据源，请按以下步骤操作：

1. 在 scripts/ 目录下新建脚本文件
2. 确保输出 JSON 格式与现有脚本一致
3. 更新主技能逻辑，集成新方法
4. 充分测试并同步更新文档

修改输出格式

可通过调整各脚本末尾的 jq 命令来自定义 JSON 结构。请确保所有方法输出格式保持一致。

功能扩展方向

以下为值得考虑的增强方向：

• 推文内容的情感分析
• 话题标签（hashtag）与提及（mention）提取
• 链接展开与预览
• 媒体图片 OCR（识别图中文字）
• 非英语推文的翻译支持

版本历史

• v1.1 — 新增话题串跟踪（read_thread.sh）、全面的媒体提取（图片、视频、全部媒体、文章封面）
• v1.0 — 初始发布，支持 FxTwitter API 与 Nitter 备用路径
• 多源可靠性设计，支持全面数据提取
• 通过完整安全审计
• 已达到生产就绪标准，适用于 ClawHub 分发