Search 模块（搜索）

search 模块提供 Twitter 帖子搜索功能，支持按热度（Top）和时间倒序（Latest）两种排序方式，并支持游标翻页。

目录

• search top — 搜索热门帖子
• search latest — 搜索最新帖子
• query 搜索语法
• cursor 分页翻页
• 频率限制警告

---

search top — 搜索热门帖子

按相关性和热度排序搜索帖子（Twitter 的 "Top" 标签）。适合查找讨论热度高的内容。

语法

twitter-cli [全局 flags] search top \
  --query <QUERY> \
  [--cursor <CURSOR>]

参数

参数	类型	必填	说明
--query <QUERY>	string	是	搜索关键词，支持 Twitter 搜索语法（见下方）
--cursor <CURSOR>	string	否	分页游标（来自上一次响应的 next_cursor）

成功示例

twitter-cli --cookies-file cookies.txt search top --query "rust programming"

输出：

{"success":true,"data":{"tweets":[{"tweet_id":"1811234567890123456","text":"Rust is amazing for systems programming! The ownership model prevents so many bugs. #rust","author_id":"6253282","author_name":"Rustacean","author_screen_name":"rustacean_dev","created_at":"2026-04-17T09:30:00Z","like_count":1523,"retweet_count":342,"reply_count":87,"view_count":45123,"lang":"en"},{"tweet_id":"1811234567890123300","text":"Just rewrote my HTTP client in Rust. 10x faster than Python. #rust #performance","author_id":"1234567890","author_name":"Dev Guy","author_screen_name":"devguy","created_at":"2026-04-17T08:15:00Z","like_count":891,"retweet_count":156,"reply_count":43,"view_count":23456,"lang":"en"}],"next_cursor":"DAABCgABGBi-NkIAAA","prev_cursor":null,"result_count":20},"error":null,"meta":{"module":"search","action":"top","elapsed_ms":687,"timestamp":"2026-04-17T10:45:00Z","cli_version":"1.0.0","schema_version":"1.0"}}

失败示例

{"success":false,"data":null,"error":{"code":"RATE_LIMIT","message":"搜索 API 请求过于频繁，Twitter 返回 429","retryable":true,"retry_after_secs":900,"docs_url":null,"recovery_actions":["等待 retry_after_secs 秒后重试","降低搜索请求频率","避免并发运行多个搜索命令"],"issue_url":null,"details":{"http_status":429}},"meta":{"module":"search","action":"top","elapsed_ms":145,"timestamp":"2026-04-17T10:46:00Z","cli_version":"1.0.0","schema_version":"1.0"}}

---

search latest — 搜索最新帖子

按时间倒序搜索帖子（Twitter 的 "Latest" 标签）。适合监控实时动态。

语法

twitter-cli [全局 flags] search latest \
  --query <QUERY> \
  [--cursor <CURSOR>]

参数

参数	类型	必填	说明
--query <QUERY>	string	是	搜索关键词，支持 Twitter 搜索语法
--cursor <CURSOR>	string	否	分页游标（来自上一次响应的 next_cursor）

成功示例

twitter-cli --cookies-file cookies.txt search latest \
  --query "from:elonmusk lang:en"

输出：

{"success":true,"data":{"tweets":[{"tweet_id":"1811234567890123999","text":"The future of AI is multimodal. Text, images, code, all together.","author_id":"44196397","author_name":"Elon Musk","author_screen_name":"elonmusk","created_at":"2026-04-17T10:30:00Z","like_count":45231,"retweet_count":8923,"reply_count":3421,"view_count":5123456,"lang":"en"}],"next_cursor":"DAABCgABGBi-NkIBBB","prev_cursor":null,"result_count":20},"error":null,"meta":{"module":"search","action":"latest","elapsed_ms":531,"timestamp":"2026-04-17T10:45:00Z","cli_version":"1.0.0","schema_version":"1.0"}}

---

query 搜索语法

--query 支持完整的 Twitter 搜索语法：

基础关键词

# 搜索包含关键词的帖子
--query "rust programming"

# 搜索精确短语（用引号包裹）
--query '"memory safety"'

# 排除关键词（-）
--query "rust -rustacean"

# OR 搜索（大写 OR）
--query "rust OR golang"

用户筛选

# 指定用户发布的帖子
--query "from:elonmusk"

# 发给指定用户的帖子
--query "to:twitter"

# 提及指定用户
--query "@rustlang"

时间范围

# since: 之后（包含当天）
--query "rust since:2026-01-01"

# until: 之前（不含当天）
--query "rust until:2026-04-17"

# 组合时间范围
--query "rust since:2026-04-01 until:2026-04-17"

内容筛选

# 仅含图片/视频的帖子
--query "rust has:media"

# 仅含链接的帖子
--query "rust has:links"

# 按语言筛选
--query "rust lang:zh"

# 最少回复数
--query "rust min_replies:10"

# 最少点赞数
--query "rust min_faves:100"

# 最少转发数
--query "rust min_retweets:50"

组合示例

# 搜索中文 Rust 讨论，最近7天，有至少10个点赞
--query "rust lang:zh min_faves:10 since:2026-04-10"

# 监控特定账号的最新帖子（配合 search latest）
--query "from:rustlang OR from:rust_async"

# 搜索某 hashtag 的热门内容
--query "#rustlang has:media min_retweets:20"

---

cursor 分页翻页

搜索结果每次返回约 20 条，通过 next_cursor 翻页获取更多：

# 第一页（不带 cursor）
page1=$(twitter-cli --cookies-file cookies.txt search latest \
  --query "rust programming")

# 从第一页提取 next_cursor
cursor=$(echo "$page1" | jq -r '.data.next_cursor')

# 第二页（带 cursor）
if [ "$cursor" != "null" ]; then
  page2=$(twitter-cli --cookies-file cookies.txt search latest \
    --query "rust programming" \
    --cursor "$cursor")
fi

# 提取第二页的 next_cursor，继续翻页
cursor2=$(echo "$page2" | jq -r '.data.next_cursor')

data 字段说明

字段	类型	说明
tweets	array	帖子列表
tweets[].tweet_id	string	帖子 ID
tweets[].text	string	帖子文字内容
tweets[].author_id	string	作者用户 ID
tweets[].author_name	string	作者显示名称
tweets[].author_screen_name	string	作者用户名
tweets[].created_at	string	发布时间（ISO 8601）
tweets[].like_count	number	点赞数
tweets[].retweet_count	number	转发数
tweets[].reply_count	number	回复数
tweets[].view_count	number | null	浏览数（部分帖子可能为 null）
tweets[].lang	string	语言代码（如 "en"、"zh"）
next_cursor	string | null	下一页游标，null 表示无更多数据
prev_cursor	string | null	上一页游标
result_count	number	本次返回的帖子数量

---

频率限制警告

重要: Twitter 搜索 API 对请求频率非常敏感。

已知限制：

• 并发运行多个搜索命令（如同时运行 search top 和 search latest）可能触发 404 频率限制
• 快速连续翻页（在数秒内翻多页）也会触发限流

建议做法：

# 在多次搜索请求之间添加延迟
for query in "rust" "golang" "python"; do
  twitter-cli --cookies-file cookies.txt search latest --query "$query"
  sleep 3  # 间隔 3 秒
done

# 遇到 RATE_LIMIT 时指数退避
result=$(twitter-cli --cookies-file cookies.txt search top --query "test")
if echo "$result" | jq -e '.error.code == "RATE_LIMIT"' > /dev/null; then
  wait_secs=$(echo "$result" | jq '.error.retry_after_secs // 60')
  sleep "$wait_secs"
fi

如果遇到 404（而非 429），单独重试失败的命令：

# 单独验证是否是临时限流
twitter-cli --cookies-file cookies.txt search top --query "test_keyword"

---

常见错误

错误码	原因	解决方法
INVALID_ARGS	--query 为空	提供有效的搜索关键词
AUTH_FAILED	cookies 过期	重新导出 cookies
RATE_LIMIT	请求过于频繁（429）	等待 retry_after_secs，降低频率
NOT_FOUND	搜索 API 返回 404（临时限流）	等待几秒后重试单个命令
SERVER	Twitter 服务端异常	稍后重试