Bird
Bird 是單一的 X/Twitter 路由器。預設使用 SocialData 作為低成本讀取層。僅在任務需要已驗證的帳戶上下文、X 原生物件或明確核准的帳戶變更時，才使用官方的 xurl CLI。不要讓兩個提供者回答同一個例行讀取請求。
觸發條件與相容性
用於處理 X/Twitter URL、推文/討論串/文章提取、搜尋、個人資料、回覆/引用/上下文、媒體擷取以及 X 帳戶操作。
保留以下進入點：
/bird <請求>— 標準路由器。- 舊版
bird.py <URL-or-ID>— 仍然透過 SocialData 讀取。 /xurl ...— 相容性進入點，供明確要求使用 xurl 的用戶使用；必須遵循 Bird 的路由與寫入閘門。
決定性路由
| 意圖 | 主要 | 備援 | 邊界 |
|---|---|---|---|
| 透過 URL/ID 讀取推文 | SocialData | 僅用於公開可見證據的網路/瀏覽器 | 絕不因 xurl 存在就升級使用 |
| 讀取討論串/對話/回覆 | SocialData | 僅在 uniquely 需要 X 原生上下文且支援時使用 xurl 讀取 | 根據取得的資料判斷討論串，而非 URL 格式 |
| 搜尋貼文 | SocialData 有限搜尋 | 現有的 SocialData/網路研究路徑 | 假設當前的 xurl recent-search 存取不可用 |
| 讀取公開個人資料 | SocialData | 需要帳戶特定/當前 X 視圖時使用 xurl 使用者查詢 | 不進行大量圖譜收集 |
| X Article | 先使用 SocialData 推文酬載；解析巢狀文章 | 使用帶有 article 欄位的 xurl 原始推文端點 | 當文章文字缺失時，遵循連結的第一方頁面 |
| 下載附件媒體 | SocialData 元資料 + 有限 HTTPS 下載 | 僅用於可見公開媒體的瀏覽器 | URL/日誌中不含 cookies；驗證主機/大小/類型 |
| 我是誰 / 已驗證身份 | xurl | 無 | 唯讀帳戶上下文 |
| 後續互動所需的確切 X 原生物件 | xurl | SocialData 用於探索/上下文 | 僅對確切物件/端點使用 xurl |
| 發文、回覆、引用、刪除、按讚、轉推、書籤、跟隨、封鎖、靜音、私訊、上傳 | xurl | 無 | 必須明確核准確切的目標、內容與效果 |
載入提供者路由以取得端點配方、錯誤處理與備援規則。僅在處理 xurl 特定任務時載入 xurl 操作。
提供者與成本契約
- SocialData 是每項例行讀取的預設選項。在當前執行環境中，優先使用已設定的直接
SOCIALDATA_API_KEY。當直接金鑰不存在且 H20 客戶金鑰具有socialdata能力時，使用已核准的 Human20 Keys SocialData 代理。通用的 H20 模型金鑰可能存在，但會回傳provider not allowed: socialdata；這不構成切換到 xurl 的理由。 - Human20 Keys 的
social-request即時預設價格等級已驗證為0 credits/request；請將其視為可變的執行時期狀態，並在聲稱成本前重新檢查。 - 一個用戶請求通常應消耗一次查詢/搜尋，加上僅限於討論串或請求上下文所需的有界依賴讀取。請勿進行擴散、抓取追隨者/追蹤中、匯出、串流、輪詢或大量擷取。
- 絕不從 SocialData 無聲地降級到付費的 X API 呼叫。
xurl是根據能力需求選擇，而非提供者失敗。
秘密與執行安全性
- 絕不讀取、列印、解析、摘要或暴露密鑰儲存、
~/.xurl、cookies、授權標頭、API 金鑰、Bearer Token、請求簽章或環境變數值。 - 僅透過安全的狀態/探查命令驗證憑證。請勿使用 xurl
--verbose/-v或內聯憑證標誌。 - SocialData 呼叫是唯讀且受限的。將
401/403視為憑證/政策問題，402視為信用額度/帳單問題，404視為不存在/私人/已刪除，429視為速率限制，5xx視為提供者故障。請勿將一類錯誤誤標為另一類。 - 瀏覽器/中繼是最後手段，絕非 cookie 提取機制。
- 寫入操作是受保護的效果。在任何 xurl 變更之前，重新讀取確切的目標與酬載，要求用戶明確核准該確切效果，執行一次，並從原始 xurl/X 回應進行驗證。研究核准不等於參與或發布核准。
- 私訊、刪除、封鎖、帳戶變更、媒體上傳與公開貼文絕不會隱含發生。
工作流程
- 分類請求：
read、search、profile、thread、article、media、account-read或write。 - 標準化 X URL/ID，不更改識別符。在決定是推文還是討論串之前先進行擷取。
- 根據表格進行路由。對於例行讀取，首先精確呼叫 SocialData 一次。
- 防禦性解析。Article 酬載可能位於
article.title、article.preview_text與article.content_state.blocks[]下；媒體可能巢狀於引用或轉推的物件中。 - 若用戶詢問某項目是否重要，請開啟連結的第一方儲存庫/文件/文章並檢查附件媒體。將 X 貼文視為聲明/來源，而非自動證明。
- 若所選提供者失敗，請報告確切的失敗原因。僅在備援方案仍能在不增加成本、隱私或效果的情況下回答相同請求時，才使用規定的備援方案。
- 回傳忠於來源的輸出與簡潔的提供者收據。
輸出契約
回傳：
Result: <完整請求內容或簡潔忠實的答案>
Type: tweet | thread | article | profile | search | account-action
Author/source: <安全的公開身份 + 標準 URL>
Provider: SocialData | xurl | web/browser fallback
Evidence: <ID、時間戳記、指標/上下文（如可用）>
Action receipt: <僅用於已核准的 xurl 變更；確切狀態/物件 ID>
Limitation: <缺失/私人/已刪除/速率/方案/提供者差距，或無>
請勿在面向用戶的收據中暴露內部金鑰、驗證模式、秘密位置或私有執行時期詳細資訊。
快速測試檢查清單
-
/bird <推文 URL>選擇 SocialData，而非 xurl。 -
/bird search from:handle選擇有限的 SocialData 搜尋。 -
/bird whoami選擇唯讀 xurl 身份。 -
/bird reply <URL> <text>在 xurl 前停下來要求精確核准。 - SocialData
402不會被回報為缺少憑證；xurl recent-search 失敗不會禁用身份/個人資料讀取。 - 討論串與文章解析使用取得的結構，而非 URL 猜測。
- 移除 SocialData 預設或寫入核准契約會導致驗證失敗。
完成標準
- 請求的 X 內容/操作已完成，或回報了一個確切的阻礙因素。
- 例行讀取優先使用 SocialData，避免了重複的提供者支出。
- xurl 僅因特定能力需求而被使用。
- 任何寫入操作均已獲得精確核准並有原始 API 回讀。
- 沒有任何秘密/cookie/私有憑證資料進入輸出、工件或日誌。