mindfulness/spec_kit/Text Wrap/modules/search-engine-app/spec.md

search-engine-app（子模块规范）

子模块名称

search-engine-app（APP 搜索器：DP + TopK）

目标描述

在 APP 场景实现多行换行的确定性组合搜索：

• 使用 DP + TopK 生成候选 layout
• 对每个候选应用硬约束过滤
• 调用 scoring-tiebreak 计算评分与 tieKey
• 保留 TopK 并在结束时选最优

要求性能可控且输出完全确定性。

输入/输出定义

输入

• tokens: Token[]
• breakpoints: Breakpoint[]（来自 breakpoint-candidates）
• availableWidth: number
• maxLines: number
• lineMode: 'AUTO' | 'FIXED'
• context: 'APP'
• measure: { measureWidth?: fn; fontSpec?: any; cache: ... }（来自 width-measurement 的实现）
• config: { topK: number }

输出

• bestLayout: { breaks: number[]; lines: string[]; wrappedText: string; meta?: { breaks: number[]; scoreTopTerms?: ... } }
• 若无解：返回可解释的 fallback（由 overflow-fallback 统一处理语义）

验收标准（可验证）

• 确定性：同输入（tokens/breakpoints/availableWidth/maxLines/configVersion）必定同输出（breaks 与 lines 完全一致）
• TopK 维护一致：
  • K 默认 10（可配置但必须固定）
  • 排序：score desc；tieKey 逐项比较
  • 去重：同 breaks 序列只保留最高分
• lineMode=FIXED 行为：
  • 优先选刚好 maxLines 的解；无解时按固定降级链路处理并打点
• 复杂度可控：超长输入触发裁剪/兜底并返回 reason（如 TOO_LONG）

依赖与关联

• 依赖：core-contract、width-measurement、breakpoint-candidates、scoring-tiebreak、overflow-fallback
• 被依赖：integration、golden-tests