feat: initial public release (MAESTRO)

2026-06-03 05:08:00 +00:00
commit f5c7666f6b
823 changed files with 184150 additions and 0 deletions
@@ -0,0 +1,134 @@
+# X / Twitter ツール（XSearch / XUserPosts / XPostDetail / 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
+})
+```
+
+## 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 経由で取得する