mindfulness/spec_kit/Text Wrap/modules/core-contract/plan.md

core-contract（技术计划）

1. 计划目标

基于 spec.md 与 设计说明文档/文档换行算法.md v1.2.1，落地跨端一致的“基础口径与契约”，为后续断点生成、搜索与评分提供稳定输入与确定性工具，确保：

• EN/TC 的 token 索引体系 与断点 pos 语义固定
• 文本 可重组：任意 [start..end) 区间可稳定还原为行文本
• EN 关键词命中规则严格为 全词等值匹配（避免 substring 误伤）
• 空白归一化策略可配置但默认一致（推荐 NORMALIZE）
• 提供可复用的 确定性比较工具（用于 breaks 字典序/tieKey 比较）

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

• 空白策略：默认 whitespacePolicy=NORMALIZE
  • 行为：折叠连续空白为 1 个空格、去首尾空白
  • 并在 meta（后续模块）中打点 hadMultiWhitespace（本模块先预留布尔返回位）
• EN tokenize：仅生成 WORD token（不生成 SPACE token），以空白分隔；标点按“极简派”保留在词内
• TC tokenize：本模块只定义接口，具体分割由 grapheme-segmentation 提供
• EN 关键词命中：lowercase → strip 两端常见标点 → 等值比较，禁止 contains/substring
• 确定性比较：breaks 字典序比较按“逐项比较 + 公共前缀相同则更短者更小”

3. 目录与产物

本子模块目录：

• spec_kit/Text Wrap/modules/core-contract/spec.md
• spec_kit/Text Wrap/modules/core-contract/plan.md（本文）

建议未来代码落位（实现阶段再定，不在本计划强制）：

• client/src/features/textWrap/core/（或 client/src/utils/textWrap/）

4. 设计与实现要点（按落地顺序）

4.1 文本预处理：normalizeWhitespace

实现 normalizeWhitespace(text) -> { normalizedText, hadMultiWhitespace }：

• 规则：
  • 把任意连续空白（空格/制表/换行等）折叠为单个空格
  • 去除首尾空白
• 注意：
  • 该规范会改变输入文本；必须作为“算法契约”的一部分固定下来
  • 若后续产品需要保留原始空白，则走 PRESERVE 分支并输出 rawSeparators（见 4.3）

4.2 EN tokenize：word tokens（极简派）

实现 tokenizeEN(normalizedText) -> tokens[]：

• 以空格分隔生成 token
• token 只包含 WORD，标点视为词内字符（例如 tired.、Wait...、hello—world、don't 都是单 token）
• 输出 token 的 text/start/end（start/end 为原始或 normalized 的字符区间，需固定口径；建议以 normalizedText 为基准）

4.3 文本重组：joinTokens

实现 joinTokens(tokens, start, end, separators?) -> string：

• EN 默认：使用单空格 " " join [start..end) 的 token.text
• 若 whitespacePolicy=PRESERVE：
  • 需要 rawSeparators[i] 表示 tokens[i] 与 tokens[i+1] 间的原始分隔符
  • 重组时按 separators 拼接（本计划仅定义接口与行为）

4.4 EN 关键词命中：normalizeENKeyword + matchENKeyword

实现：

• normalizeENKeyword(tokenText) -> string
  • lowercase
  • strip 两端常见标点（集合需配置化并全端一致，默认参考文档：, . ! ? : ; " ' … — – ( ) [ ] { }）
• matchENKeyword(tokenText, keyword) -> boolean
  • normalizeENKeyword(tokenText) === normalizeENKeyword(keyword)
  • 禁止 includes/contains 类 substring 命中

4.5 断点/区间的索引契约

固化约定（后续模块必须复用，不得自行发挥）：

• token 索引：tokens[0..N-1]
• 断点 pos：位于 token 边界，切分为 [0..pos) 与 [pos..N)
• 行区间：[start..end) 表示 tokens[start] ... tokens[end-1]

5. 回归用例与验证方式

5.1 必测示例（EN）

• "I am so tired" → tokens=[I, am, so, tired]
  • pos=2 → "I am" / "so tired"
• 标点极简派：
  • "tired." 为单 token
• 关键词命中：
  • keyword="but"："but," 命中；"rebuttal" 不命中

5.2 确定性检查

• 同一输入在同一配置下多次调用：
  • normalizedText、tokens[]、joinTokens()、matchENKeyword() 输出完全一致

6. 风险与规避

• start/end 索引口径漂移：若不同端选择以原始 text 或 normalizedText 计数，可能导致 span 对不齐
  • 规避：本模块明确 start/end 以 normalizedText 为准（或在实现阶段统一选择一种并写入 README/注释）
• 标点集合不一致：strip 集合若跨端不同会导致命中差异
  • 规避：将 punctuationStripSetEN 写入配置并版本化，禁止散落常量

7. 完成定义（DoD）

• core-contract/spec.md 中定义的输入/输出与验收条目均有可运行的最小实现或可验证的约束说明
• EN tokenize / 空白归一化 / 关键词命中 / breaks 字典序比较口径写清楚且可复现
• 关键示例用例可在本地/CI 以单元测试或脚本方式验证（实现阶段落地）