mindfulness/spec_kit/Text Wrap/modules/scoring-tiebreak/plan.md

scoring-tiebreak（技术计划）

1. 计划目标

基于 spec.md 与 设计说明文档/文档换行算法.md v1.2.1，在客户端实现可解释的评分模型与确定性 tie-break，保证：

• 整数评分：所有评分项使用整数，避免浮点误差
• 权重写死客户端：首版权重/词表内置在客户端代码（后续如需灰度，用 configVersion 管理）
• 短语匹配口径固定：emotionPhrases/protectedPhrases 必须是“连续 token 完全匹配”
• 更长短语优先：采用方案 A——在触发拆分惩罚时按“被拆分短语长度”追加惩罚（确定性）
• debug 可解释：输出 score breakdown；debug=true 时输出 Top-3，按规则优先级排序（不是按 |delta|）
• tieKey 固定：严格按文档第 11 节顺序构造 tieKey；Widget approx mode 仍使用数值 width（可为近似单位），确保 tie-break 可用

本模块不负责搜索（DP/Beam），只负责对“候选 layout”打分并给出可比较的 tieKey。

2. 默认技术决策（本计划采用）

2.1 评分数值体系

• 全部评分项使用 整数
• 不引入 EPS（因为不使用浮点）；分数相等即为相等

2.2 权重与默认值（写死客户端）

首版采用文档 10.3 的建议量级（可在实现中集中定义为常量/配置对象）：

• P_EMOTION_SPLIT = 10000
• P_PROTECTED_SPLIT = 10000
• P_WIDOW_WORD = 800
• P_WIDOW_LINE = 500
• P_SHORT_LASTLINE = 300
• P_PARTICLE_ISO = 200
• R_PUNCT_BREAK = 80
• R_SHIFT_BREAK = 60
• R_ACCUM_BREAK = 40
• R_SELF_BREAK = 20
• P_OVER_MAXLEN = 30
• P_TOO_SHORT = 10

说明：权重必须集中在一个文件，禁止散落在各函数内；后续调整通过 configVersion 记录。

2.3 最小词表（TC/EN）

首版提供最小可用词表（来源：文档第 7 节）：

• TC：
  • shift：但/可是/然而/却/只是/偏偏
  • accum：已经/一直/曾经/终于/还是/到现在
  • self：你/我/自己/我们/别人
  • emotionWords（可选）：累/痛/怕/孤单/委屈/撑/崩溃/放弃
• EN（全词等值匹配，使用 core-contract 的 normalize 规则）：
  • shift：but/yet/so（and 轻量可选）
  • accum：already/still/even/just/really
  • self：you/yourself/me/we
  • emotionWords（可选）：tired/afraid/lonely/hurt/overwhelmed/give up

emotionPhrasesTC/EN 与 protectedPhrases：

• 首版允许为空数组（先把匹配与惩罚机制写死）
• 若业务侧已有短语清单，后续直接填充并通过 Golden Cases 回归

2.4 宽度派（tieKey 使用 width）

• layoutCandidate.lines[*].width 字段作为 tieKey 的 width 来源
• 在 width unknown/approx mode 时，上游仍需给出“数值宽度”（例如用 wordCount/graphemeCount 作为 width 近似值），保证 tie-break 可执行

3. 目录与产物（客户端侧实现）

建议代码落位：

• client/src/features/textWrap/scoring/
  • types.ts（Layout/LineSegment/ScoreBreakdown）
  • weights.ts（权重常量，写死）
  • lexicons.ts（最小词表，写死）
  • phraseMatch.ts（连续 token 完全匹配 + span 预计算）
  • score.ts（按 10.1 顺序累计分数）
  • tieKey.ts（按 11 节构造 tieKey）
  • debug.ts（Top-3 提取与排序）
  • index.ts
  • __tests__/scoringTiebreak.test.ts

4. 输入/输出契约（实现阶段写死）

4.1 输入

• layoutCandidate：
  • breaks: number[]
  • lines: Array<{ start; end; text; width; tokenCount; charCount }>
• lang: 'TC' | 'EN'
• context: 'APP' | 'WIDGET'
• config：
  • weights: Record<string, number>（首版由内置默认值生成）
  • idealWidthRatio: { APP: 0.90; WIDGET: 0.95 }（来自文档 8.3A）
  • ellipsisToken: "…"（用于溢出模块；本模块只保留配置入口）
  • particleWhitelistTC: string[]（语尾语助词白名单；惩罚减半）
• lexicons（首版使用内置最小词表；允许调用方覆盖）

4.2 输出

• scoredLayout：
  • score: number
  • flags: { emotionSplit?: boolean; overflowed?: boolean; fallback?: boolean }
  • tieKey: Array<number | string>
  • scoreBreakdown?: { total: number; terms: Array<{ key: string; delta: number; detail?: any }> }

5. 实现步骤（按落地顺序）

5.1 Phrase 匹配与 span 预计算（连续 token 完全匹配）

实现口径（必须）：

• EN：对输入 tokens 使用 core-contract 的 normalizeWhitespace + tokenizeEN
• TC：对输入 tokens 使用 grapheme-segmentation 的 clusters
• 对 phrase：
  • EN：先 normalizeWhitespace，再按空格切分为词序列（不做 substring）
  • TC：按 grapheme clusters 切分
• 匹配方式：在 token 序列中寻找 连续区间 完全匹配
• 输出 spans：{ start, end, length }（end 为半开区间）

5.2 评分项（严格按 10.1 顺序累计）

按文档 10.1 固定顺序计算并记录 breakdown：

1. 情绪短语/受保护短语拆分惩罚（最高优先）
   • 若某 phrase span 被 breaks 拆到不同的行：
     • score -= P_*
     • 并按方案 A 追加惩罚：score -= phraseLength（或 k * phraseLength，k 写死为 1，确保确定性）
     • flags：emotionSplit=true（或 protectedSplit 也可复用同一 flag/额外字段，需写死）
2. 行长度（ideal/over/too short）
   • idealWidth = availableWidth * idealWidthRatio[context]（availableWidth 由上游传入）
   • 以 width-based 作为主要项：score += -abs(line.width - idealWidth)
   • overMaxLen/tooShort 按配置阈值与权重惩罚（首版可先按文档默认区间落地）
3. Widow / 单字行惩罚
4. TC 标点断点奖励
5. Shift/Accum/Self 断点奖励（含 EN 行首/行尾感知）
6. 尾行过短惩罚（SHORT_LASTLINE）

注意：必须保留每一项的确定性记录，不允许“覆盖”前序裁决结果（见文档 10.1A）。

5.3 Debug Top-3 输出

• 输出结构：ScoreBreakdown = { total, terms[] }
• debug=true 时只保留 Top-3 term，但排序规则必须按优先级（10.1 顺序），同优先级再按出现顺序稳定排序

5.4 tieKey 构造（按 11 节固定顺序）

按文档顺序生成 tieKey（比较时逐项比较）：

1. emotionSplit=false 优先（可用 0/1）
2. overflowed=false 优先
3. lastLineWidth 更大优先（因此 tieKey 可存 -lastLineWidth 或比较时反向）
4. 行宽分布更均匀优先（maxWidth-minWidth 更小优先）
5. 断点更接近理想切分点优先（距离和更小）
6. breaks 字典序更靠前优先（使用 core-contract 的 breaks 比较规则）

6. 测试计划（Vitest）

6.1 Phrase 匹配

• EN：确保全词等值匹配（but, 命中 but；rebuttal 不命中）
• TC：emoji/组合字符的 phrase 不被拆（依赖 grapheme-segmentation 已覆盖）

6.2 评分顺序与 breakdown

• 构造触发 EmotionSplit 的 layout，断言 breakdown 中第一项为 EMOTION_SPLIT（或对应 key），且其记录不会被后续项覆盖

6.3 tieKey 确定性

• 构造同分 layout，验证 tieKey 顺序能稳定选出同一个最优

7. 完成定义（DoD）

• 整数评分全链路跑通（无浮点）
• phrase 连续 token 完全匹配实现完毕（EN/TC）
• scoring 按 10.1 顺序累计，并输出可解释 breakdown
• debug Top-3 按优先级输出
• tieKey 按 11 节固定顺序构造与比较
• 单测覆盖匹配、评分顺序、tieKey 稳定性