---
name: huohua-social-twitter
description: 当需要检索 X/Twitter 账号资料、近期推文、关键词或话题搜索、社媒舆情观察、竞品动态、创始人和公司账号动向时使用；用户没明说要检索、但确实在做这类任务时也应主动调用。以下情况属于本数据覆盖不了的，不要触发：发帖、点赞、关注、私信、删除、隐藏等写操作；实时全网监控、历史全量归档、非 X/Twitter 平台数据。
---

# 火花·X/Twitter 社交搜索数据搜索

把 `social_twitter` 专业数据库接入当前任务：`filters` 做结构化过滤（主入口），`query` 承接自然语言语义，返回可直接引用的 markdown 材料。

当前版本：`v20260622-2059`

## 第零步：版本自检（每个会话第一次使用本 skill 时执行一次）

```bash
LATEST=$(curl -fsSL --max-time 5 https://skills.huohuaapi.com/social_twitter/VERSION 2>/dev/null || true)
if [ -n "$LATEST" ] && [ "$LATEST" != "v20260622-2059" ]; then
  curl -fsSL https://skills.huohuaapi.com/social_twitter/install.sh | sh
  echo "skill 已更新到 $LATEST"
fi
```

如果发生了更新，重新读取本 SKILL.md 文件后再继续；检查失败（无网络/超时）就跳过，不要阻塞任务。同一会话内只需检查这一次。

## 第一步：检查数据 token

按顺序取 token，找到即用：

1. 文件 `~/.config/huohua/data-token`（推荐的持久化方式，权限 600）；
2. 环境变量 `HUOHUA_DATA_TOKEN`（若已设置则优先用）。

两处都没有时，停下来告诉用户：

> 请到 https://huohuaapi.com/console/data-access 复制你的数据 token，然后写入独立配置文件（不污染 shell 配置、权限 600 只有你能读）：
> `mkdir -p ~/.config/huohua && printf '%s' '<你的token>' > ~/.config/huohua/data-token && chmod 600 ~/.config/huohua/data-token`

用户配置完成后继续原任务；当前会话直接 `cat ~/.config/huohua/data-token` 读取即可，无需重启 shell。

token 是计费凭证，使用纪律：

- 持久化只放独立文件 `~/.config/huohua/data-token`（权限 600），不要写进 shell rc（`~/.zshrc`/`~/.bashrc`）、代码仓库、项目内 .env 或任何会被提交、同步的文件。
- 调用时一律通过环境变量引用（`$HUOHUA_DATA_TOKEN` 或下文的 `$TOKEN`），不要把 token 明文粘进 curl 命令、脚本或日志；需要展示时只留前 8 位。

## 第二步：调用

```bash
TOKEN="${HUOHUA_DATA_TOKEN:-$(cat ~/.config/huohua/data-token 2>/dev/null)}"
API="${HUOHUA_API_BASE:-https://api.huohuaapi.cn/v1}"
curl -s "$API/search" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source":"social_twitter","purpose":"调研 X 上 AI agent 话题的最新讨论","filters":{"mode":"tweet_search","lang":"en"},"query":"AI agent"}'
```

入口说明：默认入口 `https://api.huohuaapi.cn/v1` 是中国大陆直连优化线路；海外环境或该入口连接失败时，改用 `https://api.huohuaapi.com/v1`（两个入口功能与计费完全一致），也可用环境变量 `HUOHUA_API_BASE` 固定入口。

请求体规则：

- `source` 固定为 `social_twitter`，不要改。
- `purpose` 必填：一句话写清本次调用服务的上层任务目的；同一个任务的多轮检索保持同一 purpose 不变。
- `filters` 必填且至少一个字段，是主入口：凡是能参数化的条件（年份、地区、类型、学科等）都放这里。
- `query` 放剩余的自然语言语义：保留完整意图表达（场景、约束、目标），不要拆成零散关键词。
- 默认返回 markdown；需要机器可读结构时加 `"return":{"format":"json"}`。
- 每次调用按次计费，余额与用量在 https://huohuaapi.com/console/usage 查看。

## 可用筛选字段

| 字段 | 说明 | 已知取值（截至生成时） |
| --- | --- | --- |
| `from_user` | tweet_search 可选；限定某账号发布，服务端拼入 from:<user> | —（自由值，命中为空时放宽或移除） |
| `include_quotes` | tweet_context 可选；是否包含 quote，默认 true | —（自由值，命中为空时放宽或移除） |
| `include_replies` | user_posts 可选；是否包含回复，默认 false | —（自由值，命中为空时放宽或移除） |
| `lang` | tweet_search 可选；语言代码，如 en、zh | —（自由值，命中为空时放宽或移除） |
| `max_pages` | 可选；单次服务端翻页预算，1-20，默认 1；不控制返回上限以外的排序 | —（自由值，命中为空时放宽或移除） |
| `mode` | 必填；读取模式：user_lookup=账号资料，user_search=账号搜索，tweet_search=关键词/话题搜索，tweet_lookup=推文详情，user_posts=账号近期推文，user_timeline=兼容旧名，user_archive=账号时间窗归档，tweet_context=推文上下文，user_mentions=提及账号，user_network=关注网络 | user_lookup, user_search, tweet_search, tweet_lookup, user_posts, user_timeline, user_archive, tweet_context, user_mentions, user_network |
| `network` | user_network 必填；followers/followings/verified_followers/relationship | followers, followings, verified_followers, relationship |
| `page_token` | 可选；上次返回 meta.next_page_token，用于继续翻页 | —（自由值，命中为空时放宽或移除） |
| `since` | tweet_search 可选；起始日期 YYYY-MM-DD | —（自由值，命中为空时放宽或移除） |
| `target_username` | network=relationship 时必填；目标账号用户名，不带 @ | —（自由值，命中为空时放宽或移除） |
| `tweet_id` | tweet_lookup/tweet_context 必填其一；推文 ID | —（自由值，命中为空时放宽或移除） |
| `tweet_ids` | tweet_lookup 可选；逗号分隔字符串或字符串数组 | —（自由值，命中为空时放宽或移除） |
| `tweet_url` | tweet_lookup/tweet_context 可选；X/Twitter 推文 URL | —（自由值，命中为空时放宽或移除） |
| `until` | tweet_search 可选；截止日期 YYYY-MM-DD | —（自由值，命中为空时放宽或移除） |
| `user_id` | user_posts 可选；verified_followers 必填；X 数字 user id | —（自由值，命中为空时放宽或移除） |
| `username` | user_lookup/user_posts/user_archive/user_mentions/user_network 必填；X 用户名，不带 @ | —（自由值，命中为空时放宽或移除） |

> 表中「已知取值」是封闭字段的合法值。填了不在其中的值，接口返回 `invalid_filter` 并在 `hint.valid_values` 列出该字段合法值——据此改正即可，不会静默返回空。中文常见值会自动归一到码值（如平台「抖音」→`douyin`、学段学科「高中数学」→`gzsx`）。想看最新完整取值可调 `GET $API/list?source=social_twitter`。

## 注意事项

- 按 ¥0.07/次计费，skill 页面按 ¥7 / 100 次展示；只在成功返回时扣费。
- 只支持读取，不支持互动或发帖；不要用于点赞、关注、私信、删帖等写操作。
- user_timeline 仍可用，但优先使用 user_posts；两者在服务端归一为同一读取模式。
- 需要继续翻页时，使用 JSON 返回里的 meta.next_page_token 作为下一次 filters.page_token；单次 max_pages 最高 20。
- 账号归档或多页读取时默认用 max_pages=2 串行续翻；只有稳定且确有必要时才逐步提高，不要一上来用 max_pages=10+。
- 同一任务内不要并发发起 social_twitter 请求；按 page_token 单线程续翻，每次请求间隔至少 1 秒。
- 遇到 503、5xx 或超时，先退避至少 5 秒再重试 1 次；连续失败就停止并说明可能触发源端限流，不要快速重试。
- 归档长时间线时记录已覆盖的时间窗、条数和 next_page_token；继续任务从上一次 token 串行恢复。
- user_archive 是同步分页读取，不保证一次拿完整账号历史；全量长期归档不属于当前 skill 能力。

## 典型场景与结果用法

按你当前任务找最接近的场景，照着调 filters 和 query；「拿到结果后」告诉你材料怎么用进任务里。

### 账号资料核验

确认某个 X/Twitter 账号的简介、影响力和公开资料：

```json
{"source":"social_twitter","purpose":"确认某个 X/Twitter 账号的简介、影响力和公开资料","filters":{"mode":"user_lookup","username":"OpenAI"},"query":""}
```

拿到结果后：把账号简介、粉丝量、认证状态和链接作为背景信息；不要把账号简介直接当成第三方事实结论。

### 账号近期动态

跟踪某个账号近期发布了什么：

```json
{"source":"social_twitter","purpose":"跟踪某个账号近期发布了什么","filters":{"mode":"user_posts","username":"OpenAI","max_pages":2},"query":""}
```

拿到结果后：按时间线归纳重点动态，保留推文链接和发布时间；返回 meta.has_next_page=true 时，可用 meta.next_page_token 继续下一轮读取。

### 话题与关键词搜索

围绕某个话题收集 X/Twitter 上的最新讨论材料：

```json
{"source":"social_twitter","purpose":"围绕某个话题收集 X/Twitter 上的最新讨论材料","filters":{"mode":"tweet_search","lang":"en","since":"2026-06-01"},"query":"AI agent product launch"}
```

拿到结果后：把结果按观点、案例、产品动态和风险点分组；社媒内容噪声高，结论前要用可信来源交叉核验。

### 推文上下文核验

围绕单条推文查看 thread、回复和引用上下文：

```json
{"source":"social_twitter","purpose":"围绕单条推文查看 thread、回复和引用上下文","filters":{"mode":"tweet_context","tweet_url":"https://x.com/OpenAI/status/0000000000000000000","include_quotes":true},"query":""}
```

拿到结果后：用上下文区分原推、回复、引用与转述；不要只看单条热帖就下结论。

通用原则：返回的是带来源的 markdown 材料——引用观点、数据、条文时保留来源标注；材料是输入不是结论，最终判断要结合任务自己做。

## 多轮检索

`purpose` 每次调用都必填；同一个用户任务需要多次搜索时，保持 `purpose` 不变，并带 `search_count`（`{"planned":N,"current":i}`，current 从 1 开始）标注轮次，便于用量追踪与复盘：

```json
{"source":"social_twitter","purpose":"<任务目的>","search_count":{"planned":3,"current":1},"filters":{"mode":"tweet_search","lang":"en"},"query":"..."}
```

## 错误处理

- `未提供令牌` / 401：token 缺失或失效，回到第一步。
- `missing_required_filter`：filters 为空或缺必填字段，按上表补齐。
- `invalid_filter`：某字段值不合法（含封闭码值字段填了非法值），错误 `hint.valid_values` 列出该字段合法值，改用其中之一重试；中文常见值（抖音 / 高中数学 等）可直接填，会自动归一到码值。
- `model_not_allowed`：source 写错（应为 `social_twitter`），或你的 token 未开通该数据源——请用户到 https://huohuaapi.com/console/data-access 检查 token 的可用数据源。
- 429 / 限流：调用过于频繁，等几秒再重试；多轮检索时控制节奏，不要并发轰炸。
- 连接失败 / DNS 解析失败（curl exit 6/7/28）：默认入口不通（常见于海外网络访问 .cn），把 `API` 换成 `https://api.huohuaapi.com/v1` 重试本次调用，并在本会话后续调用沿用该入口。
- 5xx / 超时：服务端暂时不可用，重试一次；仍失败则缩小 filters 范围或稍后再试，并把情况告知用户。
- 余额不足：提示用户到 https://huohuaapi.com/console/recharge 充值。
- 结果为空：先放宽 filters（保留最关键的一个），把其余条件移入 query 重试一次。
