recsys-pipeline-architect 是做什麼的？
這是一個用於建構可組合的推薦、排序與資訊流管道的規範與程式碼生成技能。它實作了六階段模式 — Source → Hydrator → Filter → Scorer → Selector → SideEffect — 該模式由 xAI 開源的 For You 演算法（Apache 2.0）推廣普及。此技能是該模式的獨立重新實作（MIT），未複製任何原始程式碼。
上游來源：https://github.com/mturac/recsys-pipeline-architect
使用時機
- 使用者想建構任何能為「使用者/上下文」選出「Top K 項目」的系統
- 使用者問「我該如何對 X 進行排序」，或描述一個資訊流/個人化問題
- 使用者有一個評分函數，需要圍繞它構建管道
- 使用者想從單一相關性分數遷移到可調權重的多動作預測
- 使用者正在封裝一個 LLM/ML 評分器，並需要在其技術堆疊（TypeScript / Go / Python）中建立過濾器、水合器、副作用以及可運行的支架
- 觸發詞：「推薦系統」、「資訊流演算法」、「排名管道」、「為您推薦的資訊流」、「候選管道」、「內容推薦器」、「推薦系統管道架構」、「RAG 檢索重排序」
不當使用時機
- 模型架構工作（Transformer 設計、雙塔檢索、嵌入訓練）— 此技能處理的是模型周圍的管道，而非模型本身
- 純 ML 訓練管道 — 評分函數是使用者的責任
- 營運已部署的管道（監控、自動擴展）— 不在此範圍內
六階段框架
| # | 階段 | 工作 | 可並行？ |
|---|---|---|---|
| 1 | Source | 從一個或多個來源提取候選項目 | 是 — 多個來源可並行執行 |
| 2 | Hydrator | 為每個候選項目補充過濾和評分所需的中繼資料 | 是 — 獨立的水合器可並行執行 |
| 3 | Filter | 丟棄不應顯示的候選項目（被封鎖、已過期、重複、不符合資格） | 順序 — 每個過濾器處理的項目愈來愈少 |
| 4 | Scorer | 為每個剩餘的候選項目分配一個或多個分數 | 順序 — 後面的評分器會看到前面的分數 |
| 5 | Selector | 根據最終分數排序，回傳 Top K | 單一操作 |
| 6 | SideEffect | 快取已服務的 ID、記錄曝光、發出事件、更新計數器 | 非同步 — 絕不能阻塞回應 |
為什麼是這個順序
- 來源先於水合：先知道有哪些候選項目，再投入資源去豐富它們
- 水合先於過濾：許多過濾器需要來源未提供的中繼資料
- 過濾先於評分：評分是最昂貴的階段；先丟棄不符合條件的
- 評分器鏈（非單一評分器）：實際系統會組合 ML 評分 + 多樣性重排序 + 業務規則
- 評分之後選取：保持評分確定性與可快取性
- 副作用最後且非同步：副作用絕不能阻擋使用者回應
呼叫時的工作流程
引導使用者完成以下八個步驟：
- 釐清使用案例（一輪，三個問題）：要排序的項目？輸入上下文？語言/執行環境？
- 識別候選來源：通常是網路內（追蹤/擁有/訂閱）＋ 網路外（ML 檢索 / 熱門 / 類似喜好）
- 列出所需的水合操作：對於每個過濾器和評分器，它需要哪些來源未提供的資料？
- 列出過濾器：重複、自身、年齡、封鎖/靜音、先前已服務、資格。順序很重要 — 便宜的先於昂貴的。
- 設計評分器鏈：主要（ML）→ 組合器（多動作加權）→ 多樣性 → 業務規則
- 選取器：按最終分數降序排序，取 Top K（或針對網路內/網路外進行分層混合）
- 副作用：快取已服務的 ID、發送曝光事件、更新計數器、記錄分析 — 全部 fire-and-forget
- 在使用者的技術堆疊中生成支架
需要提出的關鍵取捨（不要默默接受預設值）
1. 單一分數 vs 多動作預測
- 單一分數：訓練一個模型預測相關性。要改變行為 → 重新訓練。
- 多動作預測：預測多個動作的
P(動作)（閱讀、喜歡、分享、跳過、檢舉），在服務時用權重組合。要改變行為 → 改變權重。無需重新訓練。
X For You 系統使用同時包含正向和負向權重的多動作預測。當使用者預期會頻繁調整時，建議使用多動作預測。
2. 評分中的候選隔離
- 隔離：每個候選項目獨立評分。確定性、可快取。
- 聯合：候選項目在評分時互相關注（例如，批次級別的 Transformer）。表達力更強，但跨批次不具確定性。
預設使用隔離。僅在有特定原因（例如，明確的批次感知多樣性）時才使用聯合。
3. 線上式 vs 離線式
- 請求時（線上式）：每次請求都執行管道。延遲預算：100–300 毫秒。預設值。
- 預先計算（離線批次）：管道定期執行，結果快取。延遲更低，新鮮度更低。
- 混合式：候選檢索離線，排名線上式。
硬性規則
- 不要捏造基準數據。「快多少？」→「取決於工作負載，請自行測試。」
- 歸屬紀律。 引用此模式時，需歸屬為「由 xAI 開源的 For You 演算法推廣普及」/
github.com/xai-org/x-algorithm（Apache 2.0）。 - 切勿使用商標。 不要將使用者的成果命名為「類似 X」或使用「For You」品牌。模式是自由的；品牌不是。建議命名：「候選管道」、「資訊流管道」、「排名管道」、「推薦系統管道」。
- 提出取捨。 多動作 vs 單一、隔離 vs 聯合、線上式 vs 離線式 — 絕不可以默默接受預設值。
- 生成的支架必須能執行。 不允許以偽代碼冒充程式碼。
- 過濾器順序很重要。 便宜的先於昂貴的。通用的先於使用者特定的。
- 副作用絕不能阻塞。 包裝在 fire-and-forget 模式中（goroutines / 不 await 的 promises / asyncio 任務）。
反模式
- 在過濾之前評分（浪費運算資源在最終會被丟棄的候選項目上）
- 同步的副作用（快取寫入 / 曝光發送阻塞回應）
- 當產品需要針對多個目標（互動 vs 安全 vs 多樣性 vs 廣告）進行調整時，使用單一「相關性」分數
- 以聯合評分為預設值（不具確定性、難以快取、無法與重排序階段組合）
- 生成「僅供說明」的偽代碼 — 支架必須能實際執行
上游內容
上游倉庫位於 https://github.com/mturac/recsys-pipeline-architect，提供：
- 完整的
SKILL.md，包含完整的八步驟工作流程 - 5 份按需載入的參考文件：4 種語言的介面（TS/Go/Python/Rust）、多動作評分模式、候選隔離、過濾器食譜（12 種模式）、評分器食譜（加權總和、MMR、多樣性懲罰、位置去偏）
- 3 個可執行的範例支架，每個都在其測試套件中通過：
- Strapi v5 外掛（TypeScript / Jest — 3/3 通過）
- Zentra 相容管道（Go 泛型 — 3/3 通過）
- PMAI 任務優先順序器（Python / FastAPI / pytest — 3/3 通過）
- v0.1.0 版本已標記
- MIT 授權；模式歸屬於 xAI X For You 演算法（Apache 2.0）
透過 skills.sh 安裝：npx skills add mturac/recsys-pipeline-architect