mindfulness/spec_kit/Text Wrap/modules/search-engine-widget/plan.md

search-engine-widget（技术计划）

1. 计划目标

在 WIDGET 场景实现确定性的 Beam Search（文档 9.2）：

• 每一行扩展时只保留 TopK partial layouts（beam）
• 每步扩展断点数 M 受控（更强裁剪）
• 支持 widthMode='MEASURE' | 'APPROX'
• 结束时从 pos==N 的 beams 中选最优；若无解返回可解释的失败原因（最终由 overflow-fallback 统一语义）

2. 确定性与性能约束

2.1 确定性（必须）

• beams 的遍历顺序固定（按当前 beams 排序后的顺序）
• nextPos 候选顺序固定（pos 升序）
• pruning 固定（先按候选优先级/位置排序，再取前 M）
• beam 的 TopK 维护固定：score 降序；再 tieKey；再 breaks 字典序

2.2 性能参数（写死默认值）

来自文档 9.3：

• beamK=5
• expandM=12

3. Beam Search 设计（对应文档 9.2）

令 N=tokens.length，token 边界为 pos in [0..N]。

3.1 beam 状态

一个 beam（partial layout）包含：

• pos：当前已覆盖到的 token 边界
• breaks: number[]
• lines: LineInfo[]
• score + tieKey
• meta（可选）：debug Top-3 terms、approx reason 等

3.2 扩展 nextPos（每步最多 M）

对每个 beam，从 pos 扩展到若干 nextPos：

• nextPos 来源：breakpoints[].pos > pos（按 pos 升序）
• 额外包含 nextPos=N（结束边界）
• 为控制复杂度：对候选 nextPos 进行裁剪，仅保留前 expandM

裁剪规则（确定性，首版简单可控）：

• 先取 nextPos 最小的 expandM 个（最短前缀优先，利于早结束）

注：后续可升级为“优先级 + 距理想切分点近”裁剪，但首版以确定性与稳定为主。

3.3 宽度模式

• widthMode='MEASURE'：
  • 若提供测量能力：使用 measureSliceWidthCached 获取 lineWidth
  • 若测量不可用/失败：降级为 approx（记录 reason=WIDTH_UNKNOWN 或 MEASURE_FAILED），lineWidth 采用近似值
• widthMode='APPROX'：
  • 不调用测量；lineWidth 使用近似值：
    • EN：tokenCount
    • TC：charCount
  • meta 标记 reason=WIDTH_UNKNOWN

3.4 硬约束（最小集）

与 App 一致的最小硬约束：

• 禁止空行：nextPos > pos
• 最大行数：lineIndex 不超过 maxLines
• TC 禁止行首标点（H6）：若 tokens[nextPos] 属于 tcPunctuations 则该转移无效
• 超宽约束：
  • MEASURE 模式下若 width 可用且 lineWidth > availableWidth，转移无效
  • APPROX 模式下不执行超宽硬过滤（因为单位不一致），交给评分处理

3.5 每轮保留 beamK

对所有扩展出来的新 beams：

• 使用 TopK 维护（去重同 breaks，排序按 score/tieKey/breaks）
• 全局只保留 beamK 个作为下一轮 beams

3.6 结束选择

重复扩展最多 maxLines 轮后：

• 优先从 beams 中选 pos==N 的最优
• 若无 pos==N：返回 NO_CANDIDATE（由 overflow-fallback 统一兜底语义）

4. 代码落位（客户端）

• client/src/features/textWrap/searchWidget/
  • types.ts
  • beam.ts
  • topK.ts（可复用 App 逻辑，首版复制一份避免耦合）
  • constraints.ts
  • index.ts
  • __tests__/searchWidget.test.ts

5. 测试计划（Vitest）

• 确定性：同输入重复执行输出一致
• 性能约束：beamK/expandM 生效（可通过构造大量断点断言扩展次数上限）
• widthMode=APPROX：仍能产出结果，且 meta.reason=WIDTH_UNKNOWN
• TC H6：行首标点转移被禁止

6. 完成定义（DoD）

• Beam Search 可运行，且确定性单测通过
• 宽度模式与降级 meta 符合 spec
• 性能参数默认值写死且可覆盖
• 更新 overview 标记阶段性完成并记录变更文件