# breakpoint-candidates（技术计划）

## 1. 计划目标

基于 `spec.md` 与 `设计说明文档/文档换行算法.md v1.2.1`，实现“候选断点生成与裁剪”模块，输出**可控规模、确定性排序**的 breakpoints 集合，保证：

- EN/TC 断点生成口径一致（断点 `pos` 均是 token 边界索引）
- 同输入必定同输出（去重、排序、裁剪与过滤全流程确定性）
- 候选规模上限严格生效（尤其 TC）
- 支持约束过滤：`forbiddenBreakRanges`（必须）与 `protectedPhrases`（可选优化）

本模块只产出 breakpoints，不做组合搜索与评分。

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

- **输出结构**：`Array<{ pos, kind, priority }>`，最终按 `pos` 升序
- **去重策略**：同一 `pos` 若出现多个来源候选，保留 `priority` 更高者（priority 相同按 `kind` 固定序优先）
- **裁剪策略（TC）**：先按“候选重要性排序”截断到 `tcMaxCandidateBreaks`，再按 `pos` 升序输出
- **过滤策略**：
  - 必做：`forbiddenBreakRanges` 命中直接剔除
  - 可选优化：若已计算 `protectedPhrases` 的 span，可在生成阶段剔除 span 内断点（否则交给评分阶段强惩罚淘汰）

## 3. 输入/输出与关键口径

### 3.1 输入（来自上游）

- `tokens: Token[]`
  - EN：WORD tokens（不包含 SPACE token）
  - TC：grapheme cluster tokens（允许包含空格 cluster `" "`，用于 SPACE 断点）
- `lang: 'TC' | 'EN'`
- `maxLines: number`
- `constraints?: { protectedPhrases?: string[]; forbiddenBreakRanges?: Array<{ start: number; end: number }> }`
- `config: { tcMaxCandidateBreaks: number; tcPunctuations: string[]; balanceRange: number }`

### 3.2 输出（确定性）

- `breakpoints: Array<{ pos: number; kind: 'PUNCT' | 'SPACE' | 'BALANCE' | 'OTHER'; priority: number }>`
  - `pos`：token 边界索引，范围 `0..N`
  - **最终输出必须按 `pos` 升序**
- `meta?: { pruned: boolean; originalCount: number; finalCount: number }`

### 3.3 断点边界定义（统一口径）

- 候选断点只生成在“行内断点”位置：`pos ∈ [1, N-1]`
  - `pos=0` 与 `pos=N` 由搜索器作为“起止边界”处理（不作为候选断点输出）

## 4. 生成规则（按语言）

### 4.1 EN：词边界（kind=SPACE）

#### 规则

- tokens 仅为 WORD，不生成 SPACE token
- 对每个词边界产生候选断点：
  - 对 `i in 1..N-1` 生成 `pos=i, kind='SPACE'`
- `priority` 固定为基础值（建议 `priority=10`）

#### 验收要点

- `"I am so tired"`（N=4）→ breakpoints.pos 必为 `[1,2,3]`（升序）

### 4.2 TC：标点/空格/BALANCE

#### 4.2.1 标点后断点（kind=PUNCT，最高优先级）

- 若 `tokens[i].text` 属于 `tcPunctuations`：
  - 生成 `pos=i+1, kind='PUNCT'`
- `priority` 建议最高（例如 `priority=30`）

#### 4.2.2 空格后断点（kind=SPACE，中优先级）

- 若 `tokens[i].text === ' '`：
  - 生成 `pos=i+1, kind='SPACE'`
- `priority` 建议中等（例如 `priority=20`）

> 注：若上游对 TC 也做了空白 NORMALIZE，则空格通常不会连写，断点仍保持确定性。

#### 4.2.3 BALANCE 断点（kind=BALANCE，低优先级）

目的：在无标点时，仍在“接近理想位置”附近提供少量断点，提升可解性与观感。

**理想位置计算（确定性简化版）**：

- `N = tokens.length`
- `targetLines = min(maxLines, N)`（至少 1，且不超过 N）
- 对 `lineIndex in 1..targetLines-1`：
  - `idealPos = round((N * lineIndex) / targetLines)`
  - 在区间 `[idealPos - balanceRange, idealPos + balanceRange]` 生成少量候选 `pos`

**生成细则**：

- 候选 `pos` 必须落在 `[1, N-1]`
- 去重前可以允许重复（后续统一去重）
- `priority` 建议最低（例如 `priority=5`）

> 裁决补充口径：BALANCE 断点允许落在 emotionPhrase/protectedPhrases 的 span 内；是否可用由评分阶段强惩罚决定（本模块不做语义裁决）。

## 5. 过滤、去重、裁剪与排序（必须确定性）

### 5.1 forbiddenBreakRanges 过滤（必须）

- 若 `pos` 落在任一 `forbiddenBreakRanges` 的区间内（按项目约定：`start <= pos <= end` 或半开区间，必须写死一种），则剔除该 breakpoint
- 过滤必须发生在最终输出前，保证确定性

### 5.2 去重（必须）

同一 `pos` 可能来自多个来源（例如 PUNCT 与 BALANCE）：

- 取 `priority` 更高者
- `priority` 相同则按固定 kind 序：`PUNCT > SPACE > BALANCE > OTHER`

### 5.3 TC 规模上限裁剪（必须）

当 `lang=TC` 且候选数超过 `tcMaxCandidateBreaks`：

1. 计算每个 pos 到最近 `idealPos` 的距离 `distToIdeal`（若无 idealPos 列表则设为大值）
2. 按以下 key 排序后截断（排序必须固定）：
   - `priority` 降序
   - `distToIdeal` 升序
   - `pos` 升序
3. 取前 `tcMaxCandidateBreaks`

最后再按 `pos` 升序输出（输出顺序固定）。

### 5.4 meta 输出

- `originalCount`：过滤/去重/裁剪前的候选数量
- `finalCount`：最终输出数量
- `pruned`：是否发生过裁剪（finalCount < originalCount）

## 6. 测试计划（Vitest）

### 6.1 EN 断点生成

- 输入 tokens=[I, am, so, tired] → pos=[1,2,3]（确定性）

### 6.2 TC 标点/空格断点

- `tokens=['我','好','累','，','😮‍💨']` 且 `tcPunctuations` 包含 `，`
  - 必须包含 `pos=4(kind=PUNCT)`

### 6.3 BALANCE 与裁剪

- 构造无标点长文本，balanceRange>0 且 `tcMaxCandidateBreaks` 很小
  - 验证裁剪后数量上限生效
  - 验证输出仍按 pos 升序

### 6.4 forbiddenBreakRanges

- 给定 ranges，断言命中区间内的 pos 一律被剔除

### 6.5 确定性（关键）

- 同输入多次调用 breakpoints 输出完全一致（包括 meta）

## 7. 完成定义（DoD）

- EN/TC 候选断点生成口径与裁剪规则写死并实现
- 去重/排序/裁剪/过滤流程完全确定性
- TC 上限 `tcMaxCandidateBreaks` 生效
- 单测覆盖：EN/TC 基础、BALANCE、裁剪、forbiddenBreakRanges、确定性