/bird-twitter

name: bird-twitter
description: "Read X/Twitter content via Bird CLI. Actions: read tweets, search, view all bookmarks or bookmark folders, trending, news, timeline, mentions, lists. Keywords: twitter, x, tweet, trending, bookmarks, bookmark folder, 收藏夹, timeline."

Bird Twitter Skill (Read-Only)

Read X/Twitter content using the Bird CLI tool. This skill only exposes read-only operations to avoid account suspension risks.

When to Use This Skill

Triggered by:

• "read tweet [id/url]", "show tweet [id/url]"
• "search twitter [query]", "search x [query]"
• "my bookmarks", "twitter bookmarks"
• "bookmark folder", "收藏夹文件夹", "待办收藏夹", "推特收藏夹中的[folder name]"
• "trending", "twitter trends", "what's trending"
• "twitter news", "x news"
• "timeline", "i/timeline", "通知时间线", "device follow"
• "for you", "home", "home timeline", "首页推荐"
• "following", "following timeline", "首页关注流"
• "user timeline [username]", "timeline [username]", "user tweets [username]"
• "my mentions", "twitter mentions"
• "twitter lists", "my lists"
• "my feed"

Terminology Mapping (Unified)

• `timeline` -> `x.com/i/timeline` (`device_follow` endpoint)
• `for you` / `首页推荐` / `home` -> `bird home -n 20`
• `following` / `首页关注流` -> `bird home --following -n 100`
• `timeline [username]` -> `bird user-tweets <username> -n 20`

Default rule: if user says only `timeline` with no qualifier, treat it as `i/timeline`.

Prerequisites

1. Bird CLI must be installed: 优先使用仓库内置包 `vendor/bird-macos-universal-v0.8.0.tar.gz`；外部来源可用时可选 `brew install steipete/tap/bird` 2. Must be logged into X/Twitter in Chrome browser 3. In this environment, network access to X should go through local proxy:

• `HTTP_PROXY=http://127.0.0.1:7897`
• `HTTPS_PROXY=http://127.0.0.1:7897`

4. Run `HTTP_PROXY=http://127.0.0.1:7897 HTTPS_PROXY=http://127.0.0.1:7897 bird --cookie-source chrome --timeout 15000 whoami` to verify authentication 5. If Python requests fail with SSL certificate verification behind proxy, ensure `certifi` is available (`python3 -c "import certifi; print(certifi.where())"`); when needed, pass the CA bundle explicitly via `--cafile`.

Global Options

All commands should use:

• proxy env (`HTTP_PROXY` / `HTTPS_PROXY`)
• `--cookie-source chrome` to only use Chrome cookies (skip Safari/Firefox)
• `--timeout 15000` to avoid hanging requests

Recommended command prefix:

HTTP_PROXY=http://127.0.0.1:7897 HTTPS_PROXY=http://127.0.0.1:7897 bird --cookie-source chrome --timeout 15000 <command>

For `device_follow_timeline.py`:

• In this proxy environment, prefer a single-shot command with explicit `--cafile`; do not first try a bare command and then retry.
• Script now auto-detects `certifi` CA bundle and logs `SSL trust source`.
• You can explicitly force trust source with `--cafile <path>` / `--capath <dir>`; environment variables `SSL_CERT_FILE` / `SSL_CERT_DIR` are still supported.
• Emergency fallback only: set `BIRD_INSECURE_SSL=1` to retry once without SSL verification.

Example:

HTTP_PROXY=http://127.0.0.1:7897 HTTPS_PROXY=http://127.0.0.1:7897 bird --cookie-source chrome --timeout 15000 home -n 20

Commands

1. Check Auth Status

**Triggers:** "twitter auth", "bird whoami", "check twitter login"

HTTP_PROXY=http://127.0.0.1:7897 HTTPS_PROXY=http://127.0.0.1:7897 bird --cookie-source chrome --timeout 15000 whoami

2. Read Tweet

**Triggers:** "read tweet [id]", "show tweet [url]", "get tweet"

HTTP_PROXY=http://127.0.0.1:7897 HTTPS_PROXY=http://127.0.0.1:7897 bird --cookie-source chrome --timeout 15000 read <tweet-id-or-url>

Options: `--plain` for stable output without emoji/color Notes:

• `--plain` 仅用于临时阅读/命令行快速查看，不得用于“收录/归档/完整保存”任务。
• 归档任务必须使用 `--json-full`，并从 `article.article_results.result.content_state`（正文结构）+ `media_entities`（图片资源）恢复图文顺序。

2b. Archive Tweet/Article (Text + Media)

**Use when:** 用户要求“收录/归档/完整保存/原文保留（含图）”

HTTP_PROXY=http://127.0.0.1:7897 HTTPS_PROXY=http://127.0.0.1:7897 bird --cookie-source chrome --timeout 15000 read --json-full <tweet-id-or-url>

Requirements:

• 保留原文结构（标题、列表、引用、代码块）
• 图片按原文顺序本地化并在文内原位引用
• 必做三数一致校验：预期图片数 = 下载成功数 = 文内引用数
• 结构重建必须以 `content_state.blocks` 为唯一顺序源，禁止用 `--plain` 文本推断结构
• `atomic` 块类型必须从 `entityMap.value.type` 判定（`MEDIA` / `MARKDOWN` / `DIVIDER`），禁止猜测
• `MEDIA` 必须通过 `mediaItems[].mediaId -> media_entities[].media_info.original_img_url` 映射原图
• 下载前先清理目标目录中“同编号不同扩展名”的旧文件，避免 `img-N.jpg/png` 并存
• 收尾必须做块级一致性校验：`MEDIA=标准图片引用数`、`MARKDOWN=代码块数`、`DIVIDER=分隔线数`
• 若存在人工补充图，必须显式标注“补充内容，非 X 原文正文”
• 最后执行一次未引用资产扫描，删除 `assets/hitw93-*/` 下未被任何 `.md` 引用的冗余文件

3. Read Thread

**Triggers:** "read thread [id]", "show thread [url]"

HTTP_PROXY=http://127.0.0.1:7897 HTTPS_PROXY=http://127.0.0.1:7897 bird --cookie-source chrome --timeout 15000 thread <tweet-id-or-url>

4. Read Replies

**Triggers:** "show replies to [id]", "tweet replies"

HTTP_PROXY=http://127.0.0.1:7897 HTTPS_PROXY=http://127.0.0.1:7897 bird --cookie-source chrome --timeout 15000 replies <tweet-id-or-url>

Notes:

• `replies` does not support `-n` / `--count` in current Bird CLI versions.
• Use `--max-pages <number>` or `--all` to control pagination when needed.

5. Search

**Triggers:** "search twitter [query]", "search x [query]", "find tweets about"

HTTP_PROXY=http://127.0.0.1:7897 HTTPS_PROXY=http://127.0.0.1:7897 bird --cookie-source chrome --timeout 15000 search "<query>" -n 10

6. View Bookmarks

**Triggers:** "my bookmarks", "twitter bookmarks", "saved tweets"

HTTP_PROXY=http://127.0.0.1:7897 HTTPS_PROXY=http://127.0.0.1:7897 bird --cookie-source chrome --timeout 15000 bookmarks -n 20

Notes:

• `bookmarks` without `--folder-id` reads **All Bookmarks**, not a user-created bookmark folder.
• If the user names a folder such as `待办`, do not summarize All Bookmarks as a substitute. Resolve the folder id first, then read that folder.

6b. View Bookmark Folder

**Triggers:** "bookmark folder [name/id]",