更新换行算法和APP-PUSH

2026-02-10 11:39:33 +08:00
parent f03d36b5e9
commit ee2d9f44ea
105 changed files with 9967 additions and 233 deletions
--- a/spec_kit/Text
+++ b/spec_kit/Text
@@ -0,0 +1,109 @@
+# Text Wrap（大需求总览）
+
+> 本文件只保留高层背景、总览与模块拆分；各子模块可独立实现与验收。
+> 详细算法口径以 `设计说明文档/文档换行算法.md`（v1.2.1）为准。
+
+## 1. Overview（背景/目标/非目标）
+
+Home 页面与 iOS 桌面小组件（Widget）都会展示“情绪文案/正念短句”。若依赖系统默认换行，会出现不可控、不可解释、跨端不一致的问题。
+
+本需求要求把“文案换行算法”从 UI 组件中**独立成一个可复用模块**，用于：
+
+- Home 页面文案渲染
+- Widget 文案渲染（允许测量能力不同，但规则与决策必须一致）
+
+### 目标
+
+- **确定性**：同输入（含配置版本）必定同输出
+- **跨端一致口径**：索引体系、断点定义、关键词命中与 tie-break 规则完全一致
+- **可治理**：支持 debug meta、线上打点、Golden Case 回归
+- **可复用**：算法作为纯函数核心，UI 仅消费 `lines[]/wrappedText/meta`
+
+### 非目标
+
+- 不做语义理解/情绪识别/机器学习
+- 不做通用排版引擎
+- 不承诺 Widget 场景做到像 App 一样的像素级测量（Widget 可使用估算/常量）
+
+## 2. 对外接口（统一口径）
+
+模块对外暴露 `wrapText()`（纯函数）：
+
+```ts
+wrapText({
+  text: string,
+  lang: 'TC' | 'EN',
+  availableWidth: number,
+  maxLines: number,
+  context: 'APP' | 'WIDGET',
+  fontSpec?: { fontSize: number; fontWeight?: string; fontFamily?: string },
+  overflowMode?: 'ELLIPSIS' | 'CLIP' | 'SYSTEM_DEFAULT',
+  lineMode?: 'AUTO' | 'FIXED',
+  constraints?: {
+    protectedPhrases?: string[];
+    forbiddenBreakRanges?: Array<{ start: number; end: number }>;
+  },
+  configVersion?: string,
+  debug?: boolean
+}) => {
+  lines: string[];
+  wrappedText: string;
+  meta?: {
+    configVersion?: string;
+    fallback_type?: 'NONE' | 'RELAX_RULES' | 'SYSTEM_DEFAULT';
+    overflow_type?: 'NONE' | 'ELLIPSIS' | 'CLIP';
+    reason?: 'NO_CANDIDATE' | 'WIDTH_UNKNOWN' | 'WIDOW' | 'PARTICLE' | 'TOO_LONG';
+    breaks?: number[];
+    scoreTopTerms?: Array<{ key: string; delta: number; detail?: any }>;
+  }
+}
+```
+
+## 3. 模块拆分（modules）与依赖关系
+
+### 3.1 `modules/` 目录结构
+
+```text
+spec_kit/Text Wrap/
+├ spec.md
+└ modules/
+   ├ core-contract/spec.md
+   ├ grapheme-segmentation/spec.md
+   ├ width-measurement/spec.md
+   ├ breakpoint-candidates/spec.md
+   ├ scoring-tiebreak/spec.md
+   ├ search-engine-app/spec.md
+   ├ search-engine-widget/spec.md
+   ├ overflow-fallback/spec.md
+   ├ golden-tests/spec.md
+   └ integration/spec.md
+```
+
+### 3.2 模块职责概览
+
+- **`core-contract`**：EN/TC token 索引体系、文本重组、EN 关键词命中“全词等值”、配置/版本化与确定性比较口径 ✅
+- **`grapheme-segmentation`**：TC 字符簇分割的推荐实现与无库兜底 + 回归样例 ✅
+- **`width-measurement`**：测量接口、缓存、宽度不可用降级（approx mode）与打点  ✅
+- **`breakpoint-candidates`**：候选断点生成（PUNCT/SPACE/BALANCE）、去重排序、约束过滤与规模上限 ✅
+- **`scoring-tiebreak`**：评分项顺序、可解释 breakdown、tieKey/tie-break 规则与整数分/EPS ✅
+- **`search-engine-app`**：APP 场景 DP + TopK 的确定性实现
+- **`search-engine-widget`**：WIDGET 场景 Beam Search 的确定性实现
+- **`overflow-fallback`**：ELLIPSIS/CLIP/SYSTEM_DEFAULT 语义、ellipsis 细则与兜底链路
+- **`golden-tests`**：Golden Cases 与性质测试（确定性、近似单调性、maxLines 不变差）
+- **`integration`**：Home/Widget 接入约定（参数映射、渲染策略、fallback 语义对齐）
+
+## 4. 实现顺序（推荐）
+
+> 目标是“先锁口径，再做搜索与评分，再做溢出与回归”，避免后期重构。
+
+1. `core-contract`
+2. `grapheme-segmentation`
+3. `width-measurement`
+4. `breakpoint-candidates`
+5. `scoring-tiebreak`
+6. `search-engine-app`
+7. `search-engine-widget`
+8. `overflow-fallback`
+9. `golden-tests`
+10. `integration`
+