| name | recsys-pipeline-architect |
| description | 使用六阶段 Source->Hydrator->Filter->Scorer->Selector->SideEffect 框架设计可组合的推荐、排序和信息流管道，该框架由 xAI 开源的 For You 算法推广。当用户构建任何"为（用户，上下文）选择前 K 个项目"的系统时使用此技能 —— 社交信息流、内容 CMS、RAG 重排序器、任务优先级排序器、通知分流、搜索重排序、广告排序。 |
| origin | community |
recsys-pipeline-architect
用于构建可组合推荐、排序和信息流管道的规格与脚手架技能。它编码了六阶段模式 —— Source -> Hydrator -> Filter -> Scorer -> Selector -> SideEffect —— 由 xAI 开源的 For You 算法（Apache 2.0）推广。此技能是该模式的独立重新实现（MIT）—— 未从原始代码复制任何代码。
上游：https://github.com/mturac/recsys-pipeline-architect
何时使用
- 用户想要构建任何"为用户/上下文选择前 K 个项目"的系统
- 用户问"我该如何对 X 排序"或描述信息流/个性化问题
- 用户有评分函数并需要围绕它的管道基础设施
- 用户想要从单个相关性分数迁移到带可调权重的多动作预测
- 用户正在包装 LLM/ML 评分器并需要过滤器、水合器、副作用和其技术栈（TypeScript / Go / Python）中的可运行脚手架
- 触发词："推荐系统"、"信息流算法"、"排序管道"、"for you feed"、"候选管道"、"内容推荐器"、"recsys 的管道架构"、"RAG 检索重排序器"
何时不使用
- 模型架构工作（transformer 设计、双塔检索、嵌入训练）—— 此技能是模型周围的基础设施，不是模型本身
- 纯 ML 训练管道 —— 评分函数是用户的责任
- 运营已部署的管道（监控、自动扩展）—— 超出范围
六阶段框架
| # | 阶段 | 任务 | 可并行？ |
|---|
| 1 | Source | 从一个或多个来源获取候选者 | 是 —— 多个来源并行运行 |
| 2 | Hydrator | 用过滤和评分所需的元数据丰富每个候选者 | 是 —— 独立的水合器并行运行 |
| 3 | Filter | 丢弃不应显示的候选者（已阻止、已过期、重复、不合格） | 顺序 —— 每个过滤器看到更少的项目 |
| 4 | Scorer | 为每个存活的候选者分配一个或多个分数 | 顺序 —— 后续评分器看到前面的分数 |
| 5 | Selector | 按最终分数排序，返回前 K 个 | 单操作 |
| 6 | SideEffect | 缓存已服务的 ID、记录展示、发出事件、更新计数器 | 异步 —— 绝不能阻塞响应 |
为什么是这个精确顺序
- 来源在水合之前：在付费丰富之前知道有哪些候选者
- 水合在过滤之前：许多过滤器需要来源未提供的元数据
- 过滤在评分之前：评分是昂贵的阶段；先丢弃不合格的
- 评分器链（不是单个评分器）：真实系统组合 ML 评分 + 多样性重排序 + 业务规则
- 选择器在评分之后：保持评分确定性和可缓存
- 副作用在最后且异步：副作用绝不能阻塞用户响应
调用时的工作流
引导用户完成这八个步骤：
- 明确用例（一轮，三个问题）：排序的项目？输入上下文？语言/运行时？
- 识别候选来源：通常是网络内（关注/拥有/订阅）+ 网络外（ML 检索 / 趋势 / 相似推荐）
- 列出必需的水合：对于每个过滤器和评分器，它需要什么来源未提供的数据？
- 列出过滤器：重复、自身、年龄、阻止/静音、已展示、资格。顺序重要 —— 便宜的在昂贵的之前。
- 设计评分器链：主评分（ML）-> 组合器（带权重的多动作）-> 多样性 -> 业务规则
- 选择器：按最终分数降序排序，取前 K 个（或网络内/网络外的分层混合）
- 副作用：缓存已服务的 ID、发出展示事件、更新计数器、记录分析 —— 全部即发即弃
- 在用户的技术栈中生成脚手架
要展示的关键权衡（不要静默默认）
1. 单一分数 vs 多动作预测
- 单一分数：训练一个模型预测相关性。要改变行为 -> 重新训练。
- 多动作：为多个动作（阅读、点赞、分享、跳过、报告）预测
P(action)，在服务时用权重组合。要改变行为 -> 改变权重。无需重新训练。
X For You 系统使用带正向和负向权重的多动作。当用户期望频繁调整时推荐多动作。
2. 评分中的候选隔离
- 隔离的：每个候选者独立评分。确定性，可缓存。
- 联合的：候选者在评分期间相互关注（例如，批次的 transformer）。更具表达力但跨批次不确定。
默认为隔离。仅当有特定原因时使用联合（例如，明确的批次感知多样性）。
3. 在线 vs 离线
- 请求时（在线）：管道在每个请求上运行。延迟预算：100-300ms。默认。
- 预计算（离线批处理）：管道定期运行，结果缓存。更低延迟，更低新鲜度。
- 混合：候选检索离线，排名在线。
硬性规则
- 不要编造基准数据。 "快多少？" -> "取决于工作负载，自己跑。"
- 归属纪律。 当引用该模式时，归属为"由 xAI 开源的 For You 算法推广" /
github.com/xai-org/x-algorithm（Apache 2.0）。
- 不使用商标。 不要将用户的产物命名为"X-like"或使用"For You"品牌。模式是免费的；品牌不是。建议命名："候选管道"、"信息流管道"、"排序管道"、"recsys 管道"。
- 展示权衡。 多动作 vs 单一、隔离 vs 联合、在线 vs 离线 —— 永远不要静默默认。
- 生成的脚手架必须能运行。 不允许伪代码冒充代码。
- 过滤器顺序重要。 便宜的在昂贵的之前。通用的在用户特定的之前。
- 副作用永不阻塞。 包装在即发即弃模式中（goroutines / 不 await 的 promise / asyncio 任务）。
反模式
- 评分在过滤之前（浪费计算在将被丢弃的候选者上）
- 同步副作用（缓存写入 / 展示发出阻塞响应）
- 当产品需要为多个目标调优时使用单一"相关性"分数（参与度 vs 安全 vs 多样性 vs 广告）
- 默认联合评分（不确定、更难缓存、不与重排序阶段组合）
- 生成伪代码"用于说明" —— 脚手架必须实际能运行
上游内容
https://github.com/mturac/recsys-pipeline-architect 的上游仓库包含：
- 完整的
SKILL.md 带完整 8 步工作流
- 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
