# 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 経由で取得する