mindfulness/spec_kit/Text Wrap/modules/breakpoint-candidates/spec.md

breakpoint-candidates（子模块规范）

子模块名称

breakpoint-candidates（候选断点生成与裁剪）

目标描述

基于 token 序列生成“可控规模、确定性排序”的候选断点集合（breakpoints），并应用去重、排序与约束过滤，确保后续搜索器复杂度可控且跨端一致。

本模块输出的是“断点候选集合”，不负责“组合搜索选最优”。

输入/输出定义

输入

• tokens: Token[]
• lang: 'TC' | 'EN'
• maxLines: number
• constraints?: { protectedPhrases?: string[]; forbiddenBreakRanges?: Array<{ start: number; end: number }> }
• config: { tcMaxCandidateBreaks: number; tcPunctuations: string[]; balanceRange: number }

输出

• breakpoints: Array<{ pos: number; kind: 'PUNCT' | 'SPACE' | 'BALANCE' | 'OTHER'; priority: number }>
  • pos：token 边界索引（0..N）
  • 排序：按 pos 升序（最终输出必须确定性）
• meta?: { pruned: boolean; originalCount: number; finalCount: number }

验收标准（可验证）

• EN 口径：
  • tokens 仅为 WORD（不生成 SPACE token），断点仅存在于词间
  • 每个词边界产生 kind=SPACE 的候选断点（按配置可做裁剪，但必须确定性）
• TC 口径：
  • 标点后断点 kind=PUNCT 优先级最高
  • 空格后断点 kind=SPACE 次之
  • BALANCE 断点：围绕理想切分点附近生成少量断点（允许落在短语 span 内，是否可用交给评分惩罚）
• 去重/排序/过滤确定性：
  • 同一 pos 多来源断点：保留 priority 更高者
  • 输出按 pos 升序
  • forbiddenBreakRanges 命中者必定被剔除
• 规模上限生效：
  • TC 输出候选断点数不超过 tcMaxCandidateBreaks
  • 截断策略确定性（按 priority + 距离理想位置等固定规则）

依赖与关联

• 依赖：core-contract（token 与索引语义）、grapheme-segmentation（TC tokens）
• 被依赖：search-engine-app、search-engine-widget