152 lines
5.4 KiB
Markdown
152 lines
5.4 KiB
Markdown
# X / Twitter ツール（XSearch / XUserPosts / XPostDetail / XTimeline / XFetchCardMedia）
|
||
|
||
twitter-cli を内部で呼び出して X (旧 Twitter) のデータを取得する read-only ツール群。
|
||
|
||
## 認証設定（必須）
|
||
|
||
twitter-cli を動かすには Cookie 認証が必要。Settings UI の "Tools" セクションで設定:
|
||
- **X Auth Token**: ブラウザの `auth_token` cookie の値
|
||
- **X ct0**: ブラウザの `ct0` cookie の値
|
||
|
||
任意:
|
||
- **X Proxy**: `http://proxy:port` 形式
|
||
- **X Chrome Profile**: cookie 抽出元のプロファイルパス
|
||
|
||
設定が無いと「認証エラー」で失敗する。
|
||
|
||
## XSearch — 投稿検索
|
||
|
||
```js
|
||
XSearch({
|
||
query: "ローカル LLM",
|
||
limit: 20,
|
||
tab: "Latest", // Top / Latest / Photos / Videos
|
||
full_text: true, // 長文の省略を避ける
|
||
compact: false, // true で token 節約
|
||
output_path: "x/local-llm.txt" // 任意: output/x/ 配下に保存
|
||
})
|
||
```
|
||
|
||
## XUserPosts — ユーザー投稿一覧
|
||
|
||
```js
|
||
XUserPosts({
|
||
username: "elonmusk", // @ なし
|
||
limit: 50,
|
||
full_text: true
|
||
})
|
||
```
|
||
|
||
## XTimeline — ホームタイムライン（ログイン中アカウント）
|
||
|
||
```js
|
||
XTimeline({
|
||
tab: "for_you", // for_you (デフォルト) / following
|
||
limit: 20, // デフォルト 20, 最大 50
|
||
full_text: true,
|
||
compact: false,
|
||
output_path: "x/timeline.txt" // 任意
|
||
})
|
||
```
|
||
|
||
設定済みの `auth_token` / `ct0` cookie に紐づくアカウントの**ホームタイムライン**を返す。
|
||
`tab: "for_you"`（おすすめ）と `tab: "following"`（フォロー中）を切り替えられる。
|
||
内部的には `twitter feed [-t following]` を呼ぶ。検索ではなく「ログイン中ユーザーが
|
||
普段見るフィード」を取得したいときに使う。出力・メディア DL の扱いは XSearch と共通。
|
||
|
||
## XPostDetail — 投稿の詳細＋リプライ
|
||
|
||
```js
|
||
XPostDetail({
|
||
url: "https://twitter.com/.../status/1234567890",
|
||
// または status_id: "1234567890"
|
||
})
|
||
```
|
||
|
||
返り値にはリプライツリーが含まれる。議論の流れを追いたいときに使う。
|
||
|
||
## 出力フォーマット
|
||
|
||
- デフォルト: 構造化テキスト（投稿者・本文・いいね数等）
|
||
- `compact: true`: token 節約版（簡潔表記）
|
||
- `output_path` 指定時: ファイルにも保存（パスは output/x/ 相対）
|
||
|
||
## メディアの自動ダウンロード
|
||
|
||
X / Twitter ツールは取得した投稿に紐付く画像 / 動画 (poster) を**自動的に
|
||
ワークスペースにダウンロード**して `localPath` を返す。LLM はそのパスを
|
||
ReadImage / AnnotateImage / Bash 等に直接渡せる。
|
||
|
||
```yaml
|
||
# 出力例 (XPostDetail / XUserPosts / XSearch 共通)
|
||
data:
|
||
- id: '1234567890'
|
||
media:
|
||
- type: photo
|
||
url: https://pbs.twimg.com/media/AAA.jpg?name=large
|
||
localPath: logs/x-media/1234567890/0.jpg # ← 自動付与
|
||
bytes: 384172
|
||
```
|
||
|
||
保存先は `{workspace}/logs/x-media/{tweet_id}/{N}.{ext}`。同じ tweet を再取得しても
|
||
既存ファイルは上書きしない (idempotent)。
|
||
|
||
### 動画の扱い
|
||
|
||
設定で挙動を切り替える (`tools.x_download_video`):
|
||
|
||
| モード | 挙動 |
|
||
| --- | --- |
|
||
| `thumbnail` (default) | poster (静止画 jpg) のみ DL。内容把握に十分で軽量 |
|
||
| `full` | variants から最高 bitrate の mp4 を DL。サイズ大なので明示的に有効化 |
|
||
| `never` | 動画系は完全にスキップ |
|
||
|
||
### サイズ上限
|
||
|
||
`tools.x_media_max_mb` (default 25) を超えるメディアはスキップしてログに記録。
|
||
content-length ヘッダで判定し、ボディが膨張した場合も DL 後に再度チェックする。
|
||
|
||
### 完全に無効化したいとき
|
||
|
||
```yaml
|
||
tools:
|
||
x_download_media: never # 全 X ツールでメディア DL を無効化
|
||
```
|
||
|
||
## XFetchCardMedia — quiz / poll / link card の画像取得
|
||
|
||
XSearch / XPostDetail で `media: []` が返るが、tweet が quiz / poll / link card
|
||
形式で card 画像があるはずだと LLM が判断した時のみ呼ぶ専用 tool。
|
||
|
||
```js
|
||
XFetchCardMedia({
|
||
tweet: "https://x.com/someuser/status/1234567890"
|
||
// または tweet: "1234567890" (この場合 screen_name 任意)
|
||
})
|
||
```
|
||
|
||
挙動:
|
||
- Playwright で X.com を開き、GraphQL response + 対象 article の DOM から
|
||
`pbs.twimg.com/(media|card_img)/...` URL を抽出
|
||
- 抽出した URL を `logs/x-media/{tweetId}/` に DL
|
||
- 成功すれば保存パスを返す
|
||
- 0 件なら "no card media found" を返す (LLM は plain text と判断)
|
||
|
||
**重要**: 1 回の呼び出しに Playwright 起動 + ページ遷移で約 14 秒かかる。
|
||
**XSearch / XUserPosts / XPostDetail からは自動発動しない**。LLM が以下の
|
||
状況でのみ明示的に呼ぶこと:
|
||
|
||
- XPostDetail が `media: []` を返した
|
||
- かつ tweet 本文が画像クイズ / 投票 / link preview を示唆する
|
||
- かつその画像の中身が次の判断に必要
|
||
|
||
text-only tweet には呼ばないこと (14 秒を無駄にする)。
|
||
|
||
## トラブルシューティング
|
||
|
||
- **認証エラー**: cookie の有効期限切れ。ブラウザで取得し直して Settings に再投入
|
||
- **rate limit**: しばらく待ってから再実行。検索回数を絞る
|
||
- **twitter-cli not found**: `scripts/install-twitter-cli.sh` で導入が必要
|
||
- **`media: []` のままで画像が取れない**: card / quiz 形式の投稿は X API 自体に
|
||
メディアが乗らない。XFetchCardMedia を呼んで Playwright 経由で取得する
|