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

core-contract（子模块规范）

子模块名称

core-contract（核心口径与契约）

目标描述

定义并固化跨端一致的“基础口径”，为后续断点生成、搜索与评分提供统一契约，避免实现偏差：

• 索引体系：EN/TC 的 token 与断点 pos 语义
• 文本重组：从 token 区间稳定重组回行文本
• 规范化：空白归一化策略（默认折叠空白、去首尾）
• EN 关键词命中规则：全词等值匹配（lowercase → strip 两端常见标点 → 等值比较），禁止 substring/contains
• 配置与版本：configVersion 的语义与回溯字段；全端一致的默认值入口
• 确定性比较：layout tie-break 的字典序比较口径（作为后续模块复用工具）

本模块不负责“换行搜索”，只负责定义数据结构与基础函数。

输入/输出定义

输入

• text: string
• lang: 'TC' | 'EN'
• options?: { preserveRawSeparators?: boolean }
• config: { punctuationStripSetEN: string[]; whitespacePolicy: 'NORMALIZE' | 'PRESERVE' }

输出

• normalizedText: string
• tokens: Array<{ text: string; start: number; end: number }>
  • EN：token 仅为 WORD（不产生 SPACE token；标点视为词内字符）
  • TC：token 为 grapheme cluster（具体分割由 grapheme-segmentation 模块实现/提供）
• rawSeparators?: string[]
  • 可选：当选择保留原始空白时，输出 token 间分隔符映射
• 基础工具函数（逻辑输出）：
  • joinTokens(start, end) -> string
  • normalizeENKeyword(tokenText) -> string
  • matchENKeyword(tokenText, keyword) -> boolean

验收标准（可验证）

• 索引语义一致：
  • EN："I am so tired" tokens=[I, am, so, tired]，断点 pos=2 必然切为 "I am" / "so tired"
  • TC：断点 pos 表示在第 pos 个 grapheme 之前断开
• EN 标点极简派一致：
  • "tired." 作为一个 token；断点只允许在词与词之间
• EN 关键词命中无误伤：
  • keyword="but"："but," 命中；"rebuttal" 不命中
• 空白归一化确定性：
  • 输入含多空格/首尾空白时，输出 normalizedText 可预测且稳定
• 工具函数确定性：相同输入在多次调用与多端实现中输出一致

依赖与关联

• 被依赖：breakpoint-candidates、scoring-tiebreak、search-engine-*、overflow-fallback、integration
• 依赖：TC token 分割依赖 grapheme-segmentation