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

search-engine-widget（任务清单）

目标：在 WIDGET 场景实现确定性 Beam Search（文档 9.2），支持 widthMode=MEASURE/APPROX，并输出最优 layout 或可解释失败原因。

0. 对齐与准备

• 阅读并对齐口径
  • 阅读 spec_kit/Text Wrap/modules/search-engine-widget/spec.md
  • 阅读 spec_kit/Text Wrap/modules/search-engine-widget/plan.md
  • 阅读 设计说明文档/文档换行算法.md 的 9.2/9.3/11 章节
• 创建客户端模块目录
  • 新建 client/src/features/textWrap/searchWidget/

1. 类型定义与导出

• 新建 client/src/features/textWrap/searchWidget/types.ts
  • 定义 WidthMode = 'MEASURE' | 'APPROX'
  • 定义 SearchWidgetConfig：beamK、expandM、tooLongThresholds
  • 定义 SearchWidgetInput：
    • tokens/lang/breakpoints/availableWidth/maxLines/context='WIDGET'
    • measure: { widthMode; contextProfile?; fontSpec?; measureWidthImpl? }
    • scoring: { config; lexicons; debug? }
  • 定义 SearchWidgetResult：
    • 成功：bestLayout { breaks; lines; wrappedText; meta }
    • 失败：{ ok:false; reason:'TOO_LONG'|'NO_CANDIDATE'; meta? }
• 新建 client/src/features/textWrap/searchWidget/index.ts
  • 统一导出 types 与入口 searchBestLayoutWidget()

2. TopK/BeamK 维护（确定性）

• 新建 client/src/features/textWrap/searchWidget/topK.ts
  • 实现 compare：score desc；tieKey asc；breaks 字典序
  • 实现去重：同 breaks 只保留最优
  • 实现 insertTopK（用于全局 beamK 保留）

3. 约束与降级 meta

• 新建 client/src/features/textWrap/searchWidget/constraints.ts
  • isTooLong（TC>60 / EN>30）
  • isLineStartPunctTC(tokens, nextPos, tcPunctuations)（H6）
  • approxWidth(line, lang)（EN=tokenCount / TC=charCount）

4. Beam Search 主流程

• 新建 client/src/features/textWrap/searchWidget/beam.ts
  • 初始化 beams：[{pos:0, breaks:[], lines:[], score:0}]
  • 循环 lineIndex=1..maxLines
    • 对每个 beam 枚举 nextPos（breakpoints>pos + N）
    • 裁剪：仅取前 expandM 个 nextPos（pos 升序）
    • 构造行文本：joinTokens
    • 计算行宽：
      • widthMode=MEASURE：尝试 measureSliceWidthCached；失败则降级 approx 并 meta.reason 标记
      • widthMode=APPROX：直接 approx，并 meta.reason=WIDTH_UNKNOWN
    • 硬约束过滤：
      • 禁止空行、maxLines、TC H6
      • 若 width 可用且 > availableWidth：过滤（仅 MEASURE 可信）
    • 评分：scoreLayout + buildTieKey
    • 全局 newBeams 维护 TopK（beamK）
  • 结束：从 beams 中选 pos==N 最优，否则 NO_CANDIDATE

5. 单测（Vitest）

• 新建 client/src/features/textWrap/searchWidget/__tests__/searchWidget.test.ts
  • 确定性：同输入重复执行结果一致
  • widthMode=APPROX：仍可输出，且 meta.reason=WIDTH_UNKNOWN
  • 性能约束：expandM/beamK 生效（可统计测量/扩展次数）
  • TC H6：行首标点被禁止

6. 收尾

• 跑测试与类型检查
  • npm test
  • npx tsc --noEmit
• 将本 tasks.md 全部勾选完成
• 更新 spec_kit/overview.md
  • 标记 search-engine-widget 已完成编码（阶段性）
  • 写入变更文件清单