marketplace-search-recsys-planning

双边信任型 Marketplace 搜索与推荐系统规划最佳实践

面向双边信任型 Marketplace 中搜索与推荐系统的全面规划、设计和诊断指南。涵盖 OpenSearch 索引、查询和排序模式、规划检索工作的整体方法、与推荐专用工具的交接点，以及将测量转化为持续决策的埋点和仪表板层。包含 10 个类别中的 57 条规则，按级联影响排序；另有两份操作手册（从零规划新系统、诊断现有系统）和明确的持续维护型文档规范（决策日志、黄金集、注意事项）。

适用场景

在以下情况下参考此技能：

• 从零规划新的 Marketplace 检索项目
• 审查感觉陈旧、不公平或缺乏个性化的现有检索系统
• 设计 OpenSearch 索引映射、分析器或查询 DSL
• 按产品界面选择检索基础方案（搜索、推荐、混合、精选）
• 决定要跟踪哪些搜索质量指标并将其添加到仪表板
• 开展每周搜索质量评审
• 诊断排序、覆盖率或零结果率方面的隐性退化
• 判断检索问题是否实际上是个性化问题

此技能是 marketplace-personalisation 的前置环节。从这里开始规划和搜索工作；如果诊断出的瓶颈是曝光跟踪、反馈循环偏差或 AWS Personalize 专属设计，则交接给个性化技能。

持续维护的上下文

此技能将系统视为持续演进的系统。三份持续维护的文档可在不同会话、版本发布和团队变动之间延续上下文——提出建议前先阅读，每次变更上线后都要更新：

• gotchas.md（位于此技能文件夹中）——只追加的诊断经验。每条经验都包含日期，以及令团队意外的问题和解决方式的简短描述。
• 决策日志（在产品代码库中维护，通常位于 decisions/*.md）——记录每次排序变更、架构调整和同义词编辑，并注明其假设、离线和在线证据、上线标准、结果和回滚路径。参见规则 plan-maintain-a-decisions-log。
• 黄金查询集（每个评估周期冻结一次，并提交到产品代码库）——用于离线评估每次排序变更的查询参考集，然后再进行在线测试。参见规则 plan-version-the-golden-set。

规则类别

类别按其对检索生命周期的级联影响排序：对意图的误解会损害架构；错误的架构会损害索引；错误的索引会使检索结果长期出错，直到重新索引；下游每一层都会继承上游错误。

#	类别	前缀	影响
1	问题定义与用户意图	intent-	CRITICAL
2	产品界面分类与架构	arch-	CRITICAL
3	索引设计与映射	index-	HIGH
4	规划与改进方法	plan-	HIGH
5	查询理解	query-	MEDIUM-HIGH
6	检索策略	retrieve-	MEDIUM-HIGH
7	相关性与排序	rank-	MEDIUM-HIGH
8	搜索与推荐融合	blend-	MEDIUM
9	测量与实验	measure-	MEDIUM
10	埋点、仪表板与决策触发条件	monitor-	MEDIUM

快速参考

1. 问题界定与用户意图（关键）

• intent-map-queries-to-intent-classes — 先分类，再检索
• intent-separate-known-item-from-discovery — 失败模式不同，策略也不同
• intent-audit-live-query-logs-first — 基于真实数据设计，而非凭空设想
• intent-distinguish-transactional-from-exploratory — 精确度与多样性
• intent-reject-one-search-for-everything — 不同界面采用不同的查询形式
• intent-treat-no-search-as-first-class-choice — 精选内容也是合理的答案

2. 界面分类与架构（关键）

• arch-map-surface-to-retrieval-primitive — 以单一事实来源路由表为准
• arch-split-candidate-generation-from-ranking — 两阶段流水线
• arch-design-zero-result-fallback — 为每个界面指定兜底方案的负责人
• arch-design-for-cold-start-from-day-one — 冷启动是长期状态，不是引导阶段
• arch-avoid-mono-stack-retrieval — 让主要依赖多样化
• arch-route-surfaces-deliberately — 记录每项路由决策

3. 索引设计与映射（高优先级）

• index-design-mappings-conservatively — 重建索引代价高昂
• index-use-keyword-and-text-as-multi-fields — 全文检索加精确匹配
• index-match-index-and-query-time-analyzers — 分词结果必须一致
• index-use-language-analyzers-for-language-fields — 根据语言进行词干提取
• index-separate-searchable-from-display-fields — 只索引要搜索的字段
• index-use-index-templates-for-consistency — 防止映射漂移
• index-stream-listing-updates-via-cdc — 以秒而非小时为单位保持数据新鲜度

4. 规划与改进方法（高优先级）

• plan-audit-before-you-build — 启动时设置监测门槛
• plan-build-golden-query-set-first — 它是第一项产出，而非最后一项
• plan-find-bottleneck-before-optimising — 约束理论
• plan-maintain-a-decisions-log — 团队变动期间持续更新背景信息
• plan-version-the-golden-set — 每个评估周期冻结版本
• plan-handoff-to-personalisation-skill — 识别边界

5. 查询理解（中高）

• query-normalise-before-anything-else — 先规范化字符串
• query-use-language-analyzers-for-stemming — 召回率提升两位数
• query-curate-synonyms-by-domain — 领域词汇，而非同义词词典
• query-use-fuzzy-matching-for-typos — 10-15% 的查询存在拼写错误
• query-classify-before-routing — 单次分类器
• query-build-autocomplete-on-separate-index — 隔离延迟

6. 检索策略（中高）

• retrieve-use-filter-clauses-for-exact-matches — 过滤器缓存带来优势
• retrieve-use-bool-structure-deliberately — 有意使用 must、should 和 filter
• retrieve-run-expensive-signals-in-rescore — 重评分窗口限制成本
• retrieve-combine-bm25-and-knn-via-hybrid-search — 词法与语义相结合
• retrieve-paginate-with-search-after — 深度分页成本恒定
• retrieve-choose-embedding-model-deliberately — 重新生成嵌入的成本很高

7. 相关性与排名（中高）

• rank-tune-bm25-parameters-last — 优先调整上游杠杆
• rank-use-function-score-for-business-signals — 使用明确命名的函数
• rank-deploy-ltr-only-after-golden-set-exists — 监督学习需要标签
• rank-apply-diversity-at-rank-time — 在评分之后应用，而非之前
• rank-normalise-scores-across-retrieval-primitives — 使分数具有可比性

8. 搜索与推荐融合（中）

• blend-use-search-alone-for-specific-intent — 精确查询
• blend-combine-search-and-personalisation-scores — 归一化加权和
• blend-keep-hybrid-blending-explainable — 结果可追溯
• blend-never-return-zero-results — 保证逐级回退，最终返回非空结果

9. 衡量与实验（中）

• measure-define-session-success-per-surface — 每个界面定义一种成功标准
• measure-track-ndcg-mrr-zero-result-rate — 用三个指标全面衡量
• measure-track-reformulation-rate-as-failure-signal — 成本最低的失败指标
• measure-use-click-models-for-implicit-judgments — 将评估扩展到人工评审之外
• measure-run-interleaving-as-cheap-ab-proxy — 所需样本量减少 10 倍

10. 仪表化、仪表板与决策触发条件（中）

• monitor-log-every-query-with-full-context — 可结构化重放的事件
• monitor-scrub-pii-from-query-logs — 导入数据仓库前先进行脱敏
• monitor-build-search-health-dashboard — 阈值线、色带
• monitor-alert-on-decision-triggers — 质量指标，而非错误率
• monitor-track-ranking-stability-churn — 将 RBO 排名变动作为领先指标
• monitor-run-weekly-search-quality-review — 由日历驱动的例行活动

规划与改进

两份操作手册将这些规则整合为端到端工作流：

• references/playbooks/planning.md — 从头规划新的市场检索系统。包含九个步骤，从意图审计到首次通过 A/B 测试验证的线上提升，每个步骤都设有明确的退出标准。
• references/playbooks/improving.md — 诊断并改进现有检索系统。决策树按顺序检查遥测、索引新鲜度、覆盖率、基准差距、冷启动、分段回归和算法迭代；如果瓶颈与个性化有关，则提供交接至 marketplace-personalisation 的节点。

如果任务是“设计一个新的搜索与推荐项目”或“这个检索系统需要改进”，请先阅读操作手册。在实施或评审期间遇到具体问题时，再阅读单项规则。

使用方法

• 阅读 references/_sections.md，了解类别结构和级联原则。
• 阅读 gotchas.md，了解从过往事件中积累的诊断经验。
• 阅读 references/playbooks/planning.md，规划新系统。
• 阅读 references/playbooks/improving.md，诊断现有系统。
• 具体任务符合规则标题时，阅读相应的规则文件。
• 随着技能不断扩展，使用 assets/templates/_template.md 编写新规则。

相关技能

• marketplace-personalisation — 配套技能，涵盖 AWS Personalize 实施、展示跟踪、架构设计、双边匹配、反馈循环，以及针对个性化的诊断操作手册。如果诊断发现瓶颈与个性化有关，请交接至此技能。

参考文件

文件	描述
references/_sections.md	类别定义和影响排序
references/playbooks/planning.md	规划新的检索系统
references/playbooks/improving.md	诊断现有检索系统
gotchas.md	积累的诊断经验（持续更新）
assets/templates/_template.md	编写新规则的模板
metadata.json	版本、学科、参考资料