feat: generalize mapped line joining

2026-08-26 20:52:42 +08:00
parent bb0507db30
commit 11349e007a
5 changed files with 2647 additions and 143 deletions
@@ -0,0 +1,762 @@
+# 0009：通用映射驱动的跨行片段合并
+
+## 状态
+
+已批准（2026-08-26）。
+
+`supersedes: 0008`（范围有限）：本文替代 `0008` 第 6.1 节中“保留当前左片段、右片段、结果文本算法”
+的窄接口，并为调用方显式启用的词典规则放宽“运行时只依赖标准库”这一点。核心安装仍然零依赖；精确和正则规则
+仍然只处理内存字符串。词典规则只允许在构造修改器时读取已安装 optional package 自带的版本化词典资源，
+不读取调用方文档、任意路径或网络。`propose()` 仍然是只读快照的纯函数。
+
+`0008` 确定的函数式 `Modifier`、无默认启用行为、无项目固定词表、无网络和无模型推断等边界继续有效。
+
+本文批准后才能实施。批准本文不等于批准提交、推送、创建 PR、发布、修改其他仓库或处理真实材料。
+
+## 1. 问题与可观察现象
+
+当前 `mapped_line_join()` 只接受 `(left, right, replacement)` 三元组。它能处理调用方已经确认的少量精确断词，
+但遇到下列情况时，调用方只能复制整个修改器或在库外另写一套边界扫描逻辑：
+
+- 同一类断词需要用命名正则捕获不同词干；
+- 只需要匹配下一行开头，左侧只要求位于当前行尾；
+- OCR 把一个词连续拆到三行以上，需要在一次提议中完成链式合并；
+- 同一位置有多条规则，需要显式选择第一条、最高优先级或报错；
+- 规则只允许用于段落、标题、列表项或引用，不能进入表格和代码块；
+- 合并后需要保留换行、删除换行、换成空格或形成段落分隔；
+- 文本和规则可能使用不同 Unicode 规范形式，或调用方明确需要忽略大小写。
+
+更根本的问题是：如果每个 `example`、`international`、`database` 都要先手写一条映射，调用方实际上要自己维护
+一份英语词典。成熟的通用方案应能从行尾和行首自动生成候选词，查询明确配置的词典或词频资源；精确映射只负责
+项目术语、误判否决和其他例外，不应成为处理普通英文断词的唯一入口。
+
+当前实现还会在整个物理行内容上匹配。它不知道 Markdown 围栏、缩进代码、pipe table、列表和引用前缀，
+因此无法可靠表达“只在某类块中生效”。
+
+这些都属于清洗语义、规则格式和冲突策略变化，不能作为 `0008` 已批准实现的机械扩展。
+
+## 2. 调研结论及其边界
+
+本次调研只用于确定库边界，不把外部工具行为直接变成 `mdpolish` 的默认规则。
+
+### 2.1 Pandoc：软换行语义与源码重排是两件事
+
+Pandoc 默认把段落内普通换行当作空格。`hard_line_breaks` 会把段落内每个换行解释为硬换行，
+`ignore_line_breaks` 和 `east_asian_line_breaks` 则提供另外两种读取语义。输出侧的 `--wrap=auto|none|preserve`
+决定生成源码怎样折行，不负责判断 OCR 断词。
+
+当前 Pandoc 手册没有 `reflowed_text` 扩展。与“reflowed text”最接近的当前公共能力是输出侧 `--wrap`，
+不能把这个非现行名称设计成库兼容目标。
+
+来源：
+
+- <https://pandoc.org/MANUAL.html#paragraphs>
+- <https://pandoc.org/MANUAL.html#extension-hard_line_breaks>
+- <https://pandoc.org/MANUAL.html#option--wrap>
+
+因此，本修改器不能把所有物理换行统一解释成一种语义。每条规则必须明确怎样处理命中的边界，代码块和表格等结构
+必须先排除。
+
+### 2.2 OCR 去连字符：成熟方案仍然需要证据来源和取舍
+
+常见 OCR 后处理会组合以下信号：
+
+| 信号 | 能解决的问题 | 不能单独保证的事情 |
+| --- | --- | --- |
+| 词典查表 | 判断拼接词是否为已知词 | 专名、新词、领域词和真正带连字符的词 |
+| 词缀与形态分析 | 识别屈折、派生和复合词 | 依赖语言及词典质量 |
+| 词频或统计语言模型 | 在“连写、保留连字符、加空格”之间排序 | 结果依赖训练语料和领域分布 |
+| OCR 置信度与版面元数据 | 利用识别器对字符、词或断词的显式证据 | 普通 Markdown 通常已经丢失这些信息 |
+
+ALTO 可以用 `SUBS_TYPE=HypPart1/HypPart2` 和 `SUBS_CONTENT` 表达断词及完整词，并提供词置信度；hOCR 定义了
+`x_wconf`。这说明如果上游仍持有结构化 OCR 证据，优先在上游使用它比从 Markdown 猜测更可靠。
+
+来源：
+
+- <https://www.loc.gov/standards/alto/>
+- <https://kba.github.io/hocr-spec/1.2/>
+- <https://aclanthology.org/L18-1113/>
+- <https://arxiv.org/abs/1204.0188>
+
+本仓库当前只有 Markdown 字符串，没有 OCR 置信度、坐标或上游候选。因此本轮只实现调用方显式配置的本地词典判断
+和统计打分，不实现依赖版面证据的判断或模型推断。词典结果是候选证据，不绕过歧义策略和精确覆盖规则。
+
+### 2.3 Python 词典与断词库可以提供证据，但必须显式选择
+
+| 工具 | 主要能力 | 本轮不直接集成的原因 |
+| --- | --- | --- |
+| `wordninja` | 按 unigram 概率拆分粘连英文词 | 目标是拆词，不是恢复 Markdown 跨行结构；默认模型有语言和语料偏置 |
+| `pyspellchecker` | 基于词频和编辑距离给出拼写候选 | 候选不是唯一正确修改，默认大小写和词典行为也需项目决定 |
+| `PyEnchant` | 通过 Enchant provider 检查和建议拼写 | 依赖系统 provider 与外部词典，安装结果不完全由 Python 包锁定 |
+| `wordfreq` | 查询多语言词频 | 能排序候选，但不能确定是否应保留自然连字符 |
+| `PyHyphen` / `Pyphen` | 使用 TeX/Hunspell 断词模式找合法断点 | 正向排版断词不等于逆向 OCR 去断词 |
+| Hunspell | 拼写检查、词缀、复合词和形态分析 | 需要语言词典；不同词典的形态字段和能力不同 |
+
+来源：
+
+- <https://github.com/keredson/wordninja>
+- <https://pyspellchecker.readthedocs.io/>
+- <https://pyenchant.github.io/pyenchant/>
+- <https://rspeer.github.io/wordfreq/>
+- <https://pyhyphen.readthedocs.io/>
+- <https://pyphen.org/>
+- <https://github.com/hunspell/hunspell>
+
+调研后的采用边界如下：
+
+- `pyspellchecker` 具有随包分发的多语言词频词典，能够同时做精确 `known()` 查询和频率比较，适合作为第一种较轻的
+  自动词典 backend；不使用它的编辑距离纠错，因为本任务只在几个明确候选之间选择，不改写 OCR 字符；
+- `wordfreq` 提供可比较的 Zipf 频率和更广的多语言数据，适合作为可选的频率 backend；它的数据主要截至 2021 年，
+  且官方明确说明多 token 查询会高估罕见组合，因此不能把任意短语分数当作可靠词典命中；
+- `Pyphen` 能列出一个词的合法断词位置，适合作为“这个行尾位置是否可能是排版断词”的附加门槛，但它不能单独证明
+  拼接词真实存在；
+- `PyEnchant` / Hunspell 能处理词缀、复合词和自然连字符，但依赖系统 provider 和外部词典，环境可复现性较差；
+  本轮记录边界但不实现该 backend；
+- `wordninja` 的目标是把粘连字符串拆成多个词，方向与本任务相反，本轮不集成。
+
+这些 backend 必须由 `LexicalLineJoinRule` 显式选择。缺少请求的 extra 时立即报错，不退回另一个词典，也不改成只靠
+正则猜测。
+
+### 2.4 Markdown lint 工具负责语法和风格，不负责 OCR 语义修复
+
+`markdownlint` 的规则集中有行长、尾随空格、空行、标题和列表等结构/风格检查；`remark-lint` 的规则检查 mdast，
+并允许项目自行编写插件。两者都没有“判断行尾连字符是不是排版断词并自动拼回”的内置规则。
+
+这不是遗漏：lint 工具可以判断 Markdown 是否符合某种书写约定，却没有词典、原始页面或 OCR 置信度来唯一决定正文
+应该怎样改。OCR 语义修复应由上游转换器、专用后处理器或项目明确规则负责。
+
+来源：
+
+- <https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md>
+- <https://github.com/remarkjs/remark-lint>
+
+## 3. 目标与非目标
+
+### 3.1 目标
+
+- 保留旧三元组精确映射的调用方式；
+- 增加不可变、带类型的精确规则和正则规则；
+- 增加自动词典规则：从行尾、separator 和行首生成候选，查询显式配置的本地词典或词频资源；
+- 让一条语言级规则可以复用于任意文档，不要求调用方逐词枚举普通英文；
+- 所有规则仍由调用方显式传入，不内置词表或模式；
+- 在一次 `propose()` 中处理独立命中和跨多行链式命中；
+- 显式配置块范围、边界替换、冲突策略、大小写和 Unicode 规范化；
+- 对代码块和表格失败关闭；
+- 最终只产生绑定当前快照的非重叠精确 `TextEdit`；
+- 规则、选项和顺序完整记录在 `Modifier.parameters` 中。
+
+### 3.2 非目标
+
+- 不实现自动语言识别、在线词典发现或模型调用；语言、backend、候选形式和阈值必须显式配置；
+- 不读取 ALTO、hOCR、PDF、DOCX、图片或外部文件；
+- 核心安装不引入 Markdown parser 或 OCR 库；词典能力只通过明确安装的 optional extra 启用；
+- 不声称这个词法块分类器覆盖全部 CommonMark、GFM、Pandoc Markdown 或任意嵌套 HTML；
+- 不自动选择规则、重排规则或循环运行整个 `Pipeline`；
+- 不修改 `_text_ranges.py`；
+- 不提供配置文件、CLI、默认映射或默认流水线。
+
+## 4. 公共规则模型
+
+新值类型均放在 `mapped_line_join.py`，使用 `@dataclass(frozen=True, slots=True)`。为避免扩大原始任务的源码范围，
+它们先通过 `mdpolish.modifiers.mapped_line_join` 模块路径提供；本轮不要求修改 `modifiers/__init__.py`。
+
+### 4.1 枚举
+
+```python
+class LineJoinBlock(StrEnum):
+    PARAGRAPH = "paragraph"
+    HEADING = "heading"
+    LIST_ITEM = "list_item"
+    BLOCK_QUOTE = "block_quote"
+
+
+class LineBreakPolicy(StrEnum):
+    PRESERVE = "preserve"
+    DELETE = "delete"
+    SPACE = "space"
+    PARAGRAPH = "paragraph"
+
+
+class LineJoinConflictPolicy(StrEnum):
+    PRIORITY = "priority"
+    FIRST = "first"
+    ERROR = "error"
+
+
+class UnicodeNormalization(StrEnum):
+    NFC = "NFC"
+    NFD = "NFD"
+    NFKC = "NFKC"
+    NFKD = "NFKD"
+
+
+class LexiconBackend(StrEnum):
+    SPELLCHECKER = "pyspellchecker"
+    WORDFREQ = "wordfreq"
+
+
+class LexicalCandidateForm(StrEnum):
+    JOINED = "joined"
+    HYPHENATED = "hyphenated"
+    SPACED = "spaced"
+
+
+class LexicalAmbiguityPolicy(StrEnum):
+    KEEP = "keep"
+    ERROR = "error"
+```
+
+默认可匹配块为四种 `LineJoinBlock` 的不可变集合。代码块和表格不是可选块类型，因为它们始终排除，调用方不能通过
+普通规则意外打开。
+
+### 4.2 精确规则
+
+```python
+@dataclass(frozen=True, slots=True)
+class ExactLineJoinRule:
+    rule_id: str
+    left: str
+    right: str
+    replacement: str
+    separator: str = ""
+    blocks: frozenset[LineJoinBlock] = ALL_LINE_JOIN_BLOCKS
+    line_break: LineBreakPolicy = LineBreakPolicy.DELETE
+    priority: int = 0
+    case_sensitive: bool = True
+    normalization: UnicodeNormalization | None = None
+    require_word_boundaries: bool = True
+```
+
+`separator` 是紧跟在 `left` 后、位于物理换行前的显式文本。它可以是 `"-"`，也可以是空字符串：
+
+```python
+ExactLineJoinRule(
+    rule_id="example.dehyphenate",
+    left="exam",
+    separator="-",
+    right="ple",
+    replacement="example",
+)
+
+ExactLineJoinRule(
+    rule_id="example.join_split_word",
+    left="exam",
+    separator="",
+    right="ple",
+    replacement="example",
+)
+```
+
+这样不需要靠“`left` 是否碰巧以连字符结尾”推断规则类型。`replacement` 是完整的替换片段；库不会自动拼接
+`left`、`separator` 或 `right`。
+
+自动词典不可避免会遇到项目专名和自然连字符例外。为让映射表能明确否决而不是只能增加修改，再提供同样不可变的
+精确保护规则：
+
+```python
+@dataclass(frozen=True, slots=True)
+class KeepLineJoinRule:
+    rule_id: str
+    left: str
+    right: str
+    separator: str = ""
+    blocks: frozenset[LineJoinBlock] = ALL_LINE_JOIN_BLOCKS
+    priority: int = 0
+    case_sensitive: bool = True
+    normalization: UnicodeNormalization | None = None
+    require_word_boundaries: bool = True
+```
+
+它命中并赢得冲突选择后保留原文，不产生无效 `TextEdit`，同时阻止低优先级词典规则处理该边界。保护规则会进入
+`Modifier.parameters`；由于没有实际修改，不伪造 `Change`。
+
+### 4.3 左右正则规则
+
+```python
+@dataclass(frozen=True, slots=True)
+class RegexLineJoinRule:
+    rule_id: str
+    left_pattern: str
+    right_pattern: str
+    replacement: str
+    separator: str = ""
+    blocks: frozenset[LineJoinBlock] = ALL_LINE_JOIN_BLOCKS
+    line_break: LineBreakPolicy = LineBreakPolicy.DELETE
+    priority: int = 0
+    case_sensitive: bool = True
+    normalization: UnicodeNormalization | None = None
+```
+
+- `left_pattern` 必须匹配左侧逻辑内容的非空后缀；
+- `right_pattern` 必须匹配右侧逻辑内容的非空前缀；
+- 捕获组必须命名，左右两侧的组名不能重复；
+- `replacement` 只支持 `\g<name>` 命名反向引用，不支持数字组和动态回调；
+- 非捕获组、lookaround 和普通正则语法可以使用，但最终左右匹配本身必须消耗字符；
+- 正则按 Python `re` 语义编译，不启用 `MULTILINE` 或 `DOTALL`，因为物理行边界由修改器负责。
+
+示例：
+
+```python
+RegexLineJoinRule(
+    rule_id="example.named_regex",
+    left_pattern=r"(?P<stem>[A-Za-z]+)",
+    separator="-",
+    right_pattern=r"(?P<suffix>[a-z]+)",
+    replacement=r"\g<stem>\g<suffix>",
+)
+```
+
+### 4.4 只指定右侧的行尾正则规则
+
+```python
+@dataclass(frozen=True, slots=True)
+class LineEndRegexRule:
+    rule_id: str
+    right_pattern: str
+    separator: str = ""
+    blocks: frozenset[LineJoinBlock] = ALL_LINE_JOIN_BLOCKS
+    line_break: LineBreakPolicy = LineBreakPolicy.DELETE
+    priority: int = 0
+    case_sensitive: bool = True
+    normalization: UnicodeNormalization | None = None
+```
+
+这类规则把左侧定义为逻辑行尾的零宽锚点。`right_pattern` 必须匹配右侧逻辑内容的非空前缀，但只作为边界条件；
+右侧匹配文本不进入编辑范围，也不会被重新输出。实际编辑只覆盖可选 `separator`、物理行尾、允许的空行和右侧重复
+块前缀：
+
+```python
+LineEndRegexRule(
+    rule_id="example.line_end_and_right",
+    right_pattern=r"(?P<right>[a-z])",
+    line_break=LineBreakPolicy.SPACE,
+)
+```
+
+上例把 `foo\nbar` 变成 `foo bar`，而不是把空格放到 `b` 之后。规则不会猜测左侧单词，只明确表示
+“当前逻辑行尾 + 下一逻辑行首命中该正则时怎样改”。它仍然是映射表规则，不是对所有小写行首自动生效的隐藏默认值。
+
+`LineEndRegexRule` 不允许 `PRESERVE`，因为它不会改变 separator、边界或右侧文本，只会产生无效编辑。
+
+### 4.5 自动词典规则
+
+普通英文断词不要求逐词映射。调用方配置一条语言级规则，修改器从每个合格边界提取左右单词片段并自动查询本地词典：
+
+```python
+@dataclass(frozen=True, slots=True)
+class LexicalLineJoinRule:
+    rule_id: str
+    left_pattern: str
+    right_pattern: str
+    separator: str
+    backend: LexiconBackend
+    language: str
+    candidate_forms: tuple[LexicalCandidateForm, ...]
+    minimum_score: float
+    minimum_score_margin: float = 0.0
+    hyphenation_language: str | None = None
+    ambiguity: LexicalAmbiguityPolicy = LexicalAmbiguityPolicy.KEEP
+    blocks: frozenset[LineJoinBlock] = ALL_LINE_JOIN_BLOCKS
+    priority: int = 0
+    case_sensitive: bool = True
+    normalization: UnicodeNormalization | None = None
+```
+
+示例配置一次后可以复用于任意英文文档：
+
+```python
+LexicalLineJoinRule(
+    rule_id="english.dictionary_dehyphenation",
+    left_pattern=r"[A-Za-z]{2,}",
+    right_pattern=r"[a-z]{2,}",
+    separator="-",
+    backend=LexiconBackend.SPELLCHECKER,
+    language="en",
+    candidate_forms=(
+        LexicalCandidateForm.JOINED,
+        LexicalCandidateForm.HYPHENATED,
+    ),
+    minimum_score=1.0,
+    minimum_score_margin=0.5,
+    hyphenation_language="en_US",
+)
+```
+
+这条规则会自动处理 `exam-\nple`、`inter-\nnational` 等候选，不需要为 `example`、`international` 分别写映射。
+规则表在这里表达的是“什么文本形态、用哪个词典、比较哪些候选、阈值多保守”，不是穷举英语单词。
+
+左右 pattern 分别锚定逻辑行尾和行首，整个非空匹配就是候选片段。`separator` 本轮只允许 `"-"` 或 `""`。
+修改器生成调用方列出的候选：
+
+| 候选 | 输出 |
+| --- | --- |
+| `JOINED` | `left + right` |
+| `HYPHENATED` | `left + "-" + right` |
+| `SPACED` | `left + " " + right` |
+
+规则必须包含 `JOINED`，并包含与源边界对应的竞争形式：`separator="-"` 时包含 `HYPHENATED`，空 separator 时包含
+`SPACED`。这样“拼接词在词典中”不会自动压过同样合理的自然连字符或两个独立单词。
+
+backend 行为：
+
+- `SPELLCHECKER` 用 `SpellChecker.known()` 判断单 token 是否存在，并把 `word_usage_frequency()` 换算到每十亿词的
+  对数尺度。`SPACED` 或需要拆成多个单 token 验证的 `HYPHENATED` 只在各组成 token 分别已知时成立，准入分数取
+  各 token 的最低值；这个值不是短语频率，也不能与单 token 分数按 `minimum_score_margin` 排序；
+- `WORDFREQ` 使用 `zipf_frequency(candidate, language)`；它可以评价多 token 字符串，但调用方必须考虑官方说明的
+  罕见组合高估问题，并通过 `minimum_score_margin`、精确否决规则和合成反例收紧；
+- `hyphenation_language` 非空时，再用 Pyphen 检查 `len(left)` 是否在 `positions(left + right)` 中。这个门槛只作用于
+  `JOINED` 候选，不替代词典存在性和候选比较。
+
+`minimum_score` 和 `minimum_score_margin` 是 backend 内部的阈值，不是跨 backend 的统一物理量。对 `WORDFREQ`，二者
+都是 Zipf 尺度；对 `SPELLCHECKER`，`minimum_score` 可以过滤单 token 或各组成 token 中明显低频的候选，但
+`minimum_score_margin` 只适用于两个都有可比单 token 分数的候选。调用方不能把同一个数值配置在两个 backend 间
+直接搬用并期待相同含义。
+
+选择流程固定为：
+
+1. 为每个显式候选查询 backend，得到“是否存在”、准入分数和可选的可比分数；
+2. 丢弃不存在、准入分数低于 `minimum_score` 或未通过可选 Pyphen 门槛的候选；
+3. 没有候选时保留原文；
+4. 只有一个候选时选择它；
+5. 多个候选且所有候选都有同一尺度的可比分数时，只有存在唯一最高分，且它比第二名至少高
+   `minimum_score_margin` 才选择；
+6. 存在不可排序候选、仍然并列或差距不足时，按 `ambiguity` 处理：`KEEP` 保留原文，`ERROR` 抛出包含
+   `rule_id` 和位置但不包含正文的错误；
+7. 选中候选后，把左右片段和物理边界合成一个精确替换；若选中的是自然连字符或空格形式，也会删除物理换行，
+   但保留 `-` 或一个空格。
+
+因此，`SPELLCHECKER + SPACED` 的两个单 token 最低频率只用于准入，不冒充短语频率。它与 `JOINED` 同时存活时属于
+不可排序歧义，不能靠 margin 自动裁决。`SPELLCHECKER + HYPHENATED` 在 backend 只能按组成 token 验证时遵循同一规则。
+
+因此，“拼起来查词典，命中就合并”是自动规则的基础，但不是唯一判断。至少还要让源形式参与竞争，并对多候选歧义
+失败关闭。项目专名、缩写和已知例外仍可用更高优先级的精确/正则规则覆盖。
+
+### 4.6 旧三元组兼容
+
+以下调用继续有效：
+
+```python
+mapped_line_join((("exam-", "ple", "example"),))
+```
+
+旧三元组等价于一条精确规则：`left` 保持原值、`separator=""`、删除换行、区分大小写、不做 Unicode 规范化、
+启用词边界并允许四种文本块。它不会被改写成词典或正则规则。
+
+旧三元组没有 `rule_id`。工厂按声明位置为审计和冲突消息生成 `legacy.0000`、`legacy.0001` 等内部 ID；
+因此旧映射的声明顺序也会进入参数记录。这里保留的是调用语法和精确映射能力，不承诺继续在代码块或表格中修改，
+因为本文明确把这两类区域改为始终排除。
+
+旧类型别名保留：
+
+```python
+LineJoinMapping = tuple[str, str, str]
+LineJoinRule = ExactLineJoinRule | KeepLineJoinRule | RegexLineJoinRule | LineEndRegexRule | LexicalLineJoinRule
+```
+
+工厂签名为：
+
+```python
+def mapped_line_join(
+    mappings: Iterable[LineJoinMapping | LineJoinRule],
+    *,
+    conflict_policy: LineJoinConflictPolicy = LineJoinConflictPolicy.PRIORITY,
+    max_intervening_blank_lines: int = 1,
+) -> Modifier:
+    ...
+```
+
+保留 `max_intervening_blank_lines=1` 是为了兼容当前“可以隔一个同风格空行”的已实现行为。调用方可以设为 `0`，
+禁止跨空行。这里只接受类型严格为 `int` 的 `0` 或 `1`，`bool`、负数和 `2` 以上都拒绝。两个及以上连续空行更像
+结构边界；在没有 OCR provenance、版面置信度或真实样本证据时，本轮不允许用一个任意整数把搜索扩大到更远段落。
+如果后续证据表明某个上游稳定地产生多空行误断，应以有上限的新设计明确扩大范围，而不是静默放宽本参数。
+
+## 5. 匹配与替换语义
+
+### 5.1 逻辑内容和锚点
+
+修改器仍使用 `_text_ranges.py` 的 `PhysicalLine` 和 `physical_lines()` 获取准确范围，不改变底层工具。
+
+目标文件内新增保守的块扫描，把每条物理行分成：
+
+- Markdown 容器/块前缀，例如 `> `、列表 marker 后的缩进或 `# `；
+- 可匹配逻辑内容；
+- 精确物理行尾。
+
+左规则只在逻辑内容末尾匹配，右规则只在逻辑内容开头匹配。删除或替换物理边界时，右行为了表达同一块而重复的
+引用前缀或 continuation 缩进一并按第 7 节处理，不会残留在拼接词中。
+
+### 5.2 精确词边界
+
+`require_word_boundaries=True` 时：
+
+- 左匹配前一个字符不能是 Unicode 字母、数字或下划线；
+- 右匹配后一个字符不能是 Unicode 字母、数字或下划线。
+
+这替代当前只检查 ASCII 字母的窄规则。调用方确实要匹配词内片段时必须显式设为 `False`。正则规则不另加自动词边界，
+调用方用正则本身表达边界。
+
+### 5.3 空规则集和无命中
+
+空映射仍创建合法的 no-op `Modifier`。没有规则命中时返回空提议，不修改换行、Unicode 或任何其他内容。
+
+## 6. Markdown 块范围
+
+本轮不引入 parser。目标文件内使用失败关闭的词法扫描，只为跨行候选提供最小结构边界。
+
+扫描器内部必须有独立的 `UNKNOWN` 分类；它不是公共 `LineJoinBlock`，任何规则都不能选择它。`PARAGRAPH` 必须由
+“普通文本行、容器前缀一致且两侧都没有未识别块 marker”正向识别，不能作为“不像其他块”的兜底。`EXCLUDED`
+用于已确认的代码和表格范围，`UNKNOWN` 用于 marker 损坏、容器深度不一致、缩进关系不足或方言结构无法确认的范围；
+两者都不产生候选。
+
+### 6.1 始终排除
+
+- backtick 或 tilde fenced code block，包括 fence 行；
+- 保守识别的四空格或 tab 缩进代码；
+- 有 delimiter row 的 GFM pipe table 整个连续区域；
+- 从 `<table` 开始到配对 `</table>` 的 raw HTML table 区域；不完整 opening 从该处排除到文档末尾。
+
+围栏识别支持至多三个前导空格、相同 fence 字符和不短于 opening 的 closing。它不解释 fence 内语言。
+
+### 6.2 可选块
+
+| `LineJoinBlock` | 词法范围 |
+| --- | --- |
+| `PARAGRAPH` | 不属于其他支持块的连续普通文本行 |
+| `HEADING` | ATX heading 的内容及其紧邻、没有新块 marker 的 OCR continuation；Setext underline 本身不参与匹配 |
+| `LIST_ITEM` | list marker 行与达到该 item 内容列的 continuation；遇到下一个同级 marker 或块边界结束 |
+| `BLOCK_QUOTE` | 具有相同 quote depth 的普通引用内容；引用内的 heading/list 使用更具体的块类型 |
+
+块类型取最内层可识别类型。例如引用中的列表项是 `LIST_ITEM`，引用中的普通段落是 `BLOCK_QUOTE`。
+
+Markdown 允许 lazy continuation，标题后也允许紧接普通段落；仅靠文本无法总是区分这些情况。因此：
+
+- 规则映射仍是决定修改正确性的主要证据；
+- 块分类只缩小规则适用范围，不证明词语一定应该合并；
+- 无法确认同一块、容器深度不一致或前缀损坏时归入 `UNKNOWN`，不回退成 `PARAGRAPH`，也不提出修改；
+- 合法且前缀对称的多层引用或嵌套列表可以正向识别；深度、item content column 或 continuation 缩进不一致时
+  失败关闭。`> > >` 和多级有序列表本身不自动等于损坏语法，测试必须同时固定合法嵌套和损坏变体。
+
+## 7. 换行策略
+
+一个候选的“原始边界”包括左物理行尾、允许的空行，以及右侧重复的块前缀。精确和左右正则规则先把左右匹配片段
+变成 `replacement`，再把所选边界输出放在 replacement 之后、右侧未匹配内容之前。行尾正则规则不消费右侧匹配，
+只按下表替换原始边界：
+
+| 策略 | 输出 |
+| --- | --- |
+| `PRESERVE` | 保留原始物理行尾、空行和右侧块前缀 |
+| `DELETE` | 删除整个边界和右侧重复前缀 |
+| `SPACE` | 用一个 ASCII 空格替换整个边界和右侧重复前缀 |
+| `PARAGRAPH` | 用左物理行尾样式生成恰好一个空行，并恢复右侧所需块前缀 |
+
+`PARAGRAPH` 在普通段落中分别产生 `EOL + EOL`；在 block quote 中产生合法的空 quote 行和下一行 quote 前缀；
+在 list item 中保留 continuation 所需缩进。具体字节由合成测试固定，不根据操作系统默认换行。
+
+候选内部出现混合 CR、LF、CRLF 时失败关闭，不匹配该候选。文档其他位置可以使用不同换行风格，不做全文规范化。
+
+## 8. 冲突与链式合并
+
+### 8.1 同一边界多规则冲突
+
+每个候选边界先按调用方给出的规则顺序收集全部命中，再执行：
+
+| 策略 | 行为 |
+| --- | --- |
+| `FIRST` | 选择声明顺序最早的规则 |
+| `PRIORITY` | 选择最高 `priority`；最高值相同时选择声明顺序最早的规则 |
+| `ERROR` | 两条及以上规则命中即抛出 `ModifierContractError`，消息只含位置和 `rule_id` |
+
+自动词典规则只有在结构 pattern 命中且第 4.5 节选出了一个候选形式后才进入冲突集合；无词典候选或 `ambiguity=KEEP`
+不算命中。`ambiguity=ERROR` 的词典歧义直接报错，不先交给规则冲突策略掩盖。
+
+规则顺序因此是参数和行为的一部分，不再为了得到顺序无关结果而排序。`PRIORITY` 的同优先级 tie-break 明确采用
+声明顺序，不把集合迭代顺序或 replacement 字典序当作隐藏规则。
+
+`KeepLineJoinRule` 与其他规则参加同一次冲突选择；它只有在赢得选择后才阻止修改。这样精确项目例外可以用更高
+优先级覆盖语言级词典规则，而不会让一条低优先级保护规则意外屏蔽更明确的替换。
+
+### 8.2 跨多行链式合并
+
+修改器从前到后处理物理边界，并维护只存在于当前 `propose()` 调用内的不可变中间片段。选中一条规则后：
+
+1. 组合该边界的虚拟输出；
+2. 标记该原始物理边界已经消费；
+3. 如果输出与下一原始物理行形成新的候选，继续匹配下一边界；
+4. 每个原始物理边界最多消费一次，因此最多执行 `physical_line_count - 1` 次，不存在无界循环；
+5. 相连边界最终合成一个覆盖原始连续范围的 `TextEdit`。
+
+例如两条显式规则可以把：
+
+```text
+exam-
+ple-
+based
+```
+
+在一次提议中变成 `example-based`。修改器不会依赖 `Pipeline` 自动运行第二轮，也不会先提交两个重叠编辑再让执行器猜测。
+
+不相连的链生成不同且不重叠的 `TextEdit`。最终按原文起点排序。若内部规划仍产生重叠、无实际变化或无法映射回原始
+范围，修改器抛出契约错误，不静默丢弃整批正确候选。
+
+## 9. 大小写和 Unicode 规范化
+
+- `case_sensitive=True` 是默认值；
+- `normalization=None` 是默认值；
+- 规范化只建立匹配视图，不规范化整篇文档；
+- 固定 replacement 按调用方原样输出；
+- 正则反向引用使用映射回原文的捕获文本，不借匹配视图静默改变大小写或规范形式；
+- 如果规范化后的匹配边界不能唯一映射回 Python 原字符串索引，该候选失败关闭；
+- 兼容等价匹配、NFKC/NFKD 兼容匹配和忽略大小写都必须由规则显式开启。
+
+实现可以为一个逻辑内容建立规范化视图及源索引边界表，但不能把规范化后的全文作为 `expected_text`，也不能绕过
+`TextSpan` 的原始 Python 字符索引契约。
+
+## 10. 验证、错误与审计
+
+工厂构造时验证：
+
+- 输入可迭代且每项是合法三元组或规则 dataclass；
+- `rule_id` 非空、稳定、唯一；
+- 枚举、布尔值、整数和块集合类型准确，不接受用真值冒充布尔值；
+- 左右精确片段、separator 和 replacement 不包含 CR/LF；
+- 精确规则的 `left`、`right` 和 replacement 非空；separator 可以为空；
+- 正则可以编译，左右正则规则的两侧及行尾正则规则的右侧不会只产生零长度匹配；
+- 捕获组均有名称、左右名称不重复、replacement 引用存在；
+- 行尾正则规则不接受 `PRESERVE`；
+- 自动词典规则的 separator 只能是 `"-"` 或 `""`，pattern 必须消费非空片段；
+- 自动词典规则必须包含 `JOINED` 和对应源形式，候选形式不能重复；
+- backend、非空语言代码、有限且非负的 `minimum_score` / `minimum_score_margin` 和可选 Pyphen 语言合法；
+- 请求的 backend 或 Pyphen 不可用时明确报错，不创建行为不完整的修改器；
+- `max_intervening_blank_lines` 的类型严格为 `int` 且只能是 `0` 或 `1`；
+- 旧三元组仍拒绝空字段、换行和重复的 `(left, right)`。
+
+运行时冲突、无法映射的内部范围和不变量破坏抛出明确异常。普通无匹配、结构排除和不能唯一映射的 Unicode 候选是
+失败关闭条件，返回无提议，不是异常。
+
+每个实际链生成一个 `ProposedChange` 和一个 `TextEdit`。`reason` 包含所用 `rule_id` 序列，不记录未命中规则，
+也不输出候选周围正文。`Modifier.parameters` 记录：
+
+- 调用顺序中的完整规则；
+- 规则类型、pattern/literal、replacement、separator、块范围、换行策略、优先级、大小写和规范化选项；
+- 冲突策略和允许的空行数。
+
+修改器版本从 `1.0.0` 更新为 `2.0.0`，表示规则语义和参数记录发生变化。
+
+## 11. 依赖和函数式边界
+
+- 核心安装仍只依赖 Python 标准库；
+- `pyproject.toml` 新增 `lexical` optional extra，包含受限版本的 `pyspellchecker` 和 `pyphen`；
+- `wordfreq` 体积和传递依赖更大，放入单独的 `frequency` optional extra，不随 `lexical` 或核心安装；
+- optional import 使用模块级 `try/except ImportError` 保存“不可用”状态；只有规则明确请求对应 backend 时才报
+  `ModifierContractError`，精确和正则规则不受未安装 extra 影响；
+- backend 和 Pyphen 实例在 `mapped_line_join()` 构造修改器时建立一次，不在每个文档或每个候选上重复加载词典；
+- 参数记录 backend、第三方包版本、语言、阈值、候选形式和 Pyphen 语言；
+- 不在 import 时读取词典、环境变量、当前时间或网络；
+- 规则 dataclass、编译后的内部规则和扫描结果不可变；
+- 闭包只捕获构造时验证和冻结的数据；
+- `propose()` 只读取 `DocumentSnapshot` 并返回 tuple，不应用编辑或写文件。
+
+`pyspellchecker` 和 `wordfreq` 自带的数据版本随包版本冻结；本轮不下载更新。Pyphen 使用其已安装包内词典。
+调用方仅安装 extra 不会自动启用任何规则，因而不会出现“环境里碰巧多了一个包，清洗结果就改变”的隐式行为。
+
+PyEnchant/Hunspell backend 若以后进入运行时，需要新的 design 解决系统 provider、词典版本和可复现记录，不能在本轮
+用宽泛 `try/except` 悄悄替代已选择的 backend。
+
+## 12. 文档与兼容范围
+
+实现后的模块顶层 docstring 记录第 2 节的简短结论、支持模式和限制，不新增同目录 `NOTES.md`，避免形成第二份接口事实。
+具体签名和运行行为以代码与测试为准。
+
+根 `README.md` 当前明确写着 `mapped_line_join()` 只使用三元组并只处理当前窄边界。实现本文后该说明会过期。
+按照 README 的事实权威要求，实施范围必须允许同步更新 README 的当前能力和示例。若仍要求 Git diff 只能包含目标源码
+和 tests，则本文不能实施。
+
+本轮不承诺新 dataclass 从 `mdpolish.modifiers` 聚合模块导出。受支持导入路径是：
+
+```python
+from mdpolish.modifiers import mapped_line_join
+from mdpolish.modifiers.mapped_line_join import (
+    ExactLineJoinRule,
+    KeepLineJoinRule,
+    LexicalLineJoinRule,
+    LineEndRegexRule,
+    RegexLineJoinRule,
+)
+```
+
+旧 `mapped_line_join()` 和 `LineJoinMapping` 聚合导入保持可用。
+
+## 13. 测试与验收
+
+测试只使用虚构 Markdown，不读取真实或外部数据。至少覆盖：
+
+- 旧三元组精确匹配和新 `ExactLineJoinRule`；
+- `separator="-"` 与 `separator=""`；
+- 左右命名正则和跨两侧 backreference；
+- `LineEndRegexRule` 的行尾锚点 + 行首正则，并确认右侧条件文本不被消费；
+- 小型合成词典 backend 自动把行尾和行首组成 `JOINED`、`HYPHENATED`、`SPACED` 候选；
+- 拼接词唯一命中自动合并，不需要逐词精确映射；
+- 拼接词与源形式都有可比分数时按分差选择，分差不足按 `KEEP`/`ERROR` 处理；
+- Pyphen 合法断点门槛允许和拒绝 `JOINED` 候选；
+- 高优先级 `KeepLineJoinRule` 能否决自动词典规则；
+- 请求未安装 backend 明确失败，绝不退回另一 backend 或正则猜测；
+- 已安装 optional extra 时分别做最小真实 adapter 测试；未安装时明确 skip 并报告，不把 skip 写成通过；
+- 段落、ATX 标题 continuation、列表 continuation 和同深度引用的正向范围；
+- 合法的三层引用和正确缩进的嵌套有序列表可以合并；
+- 引用深度不一致、损坏 quote 前缀、相邻同级列表项、缩进不足的嵌套列表 continuation，以及未识别的 marker-like
+  结构归入内部 `UNKNOWN`，不合并且绝不回退成段落；
+- heading/list/quote 前缀在四种换行策略下的准确输出；
+- fenced code、缩进代码、GFM pipe table 和 raw HTML table 不合并；
+- 空文档、空规则、文末无换行；
+- LF、CR、CRLF 以及候选内混合行尾失败关闭；
+- 隔零个或一个空行的配置，以及 `-1`、`True`、`2` 被构造期拒绝；
+- 三行及以上链式合并、同一合并后逻辑行继续匹配；
+- 一篇文档中的多个独立链按原文顺序报告；
+- `FIRST`、`PRIORITY`、同优先级 tie-break 和 `ERROR`；
+- 默认区分大小写和显式忽略大小写；
+- 默认不规范化、NFC/NFD 匹配、不能唯一回映时失败关闭；
+- Unicode 词边界和显式关闭词边界；
+- 无效 dataclass 字段、正则、捕获组、replacement 引用和重复 `rule_id` 明确失败；
+- 无效 backend、语言、候选组合、score 阈值和 margin 明确失败；
+- `WORDFREQ` 候选按 Zipf margin 比较；`SPELLCHECKER` 单 token 与 `SPACED`/拆分验证的 `HYPHENATED`
+  同时存活时按不可排序歧义处理，不用 margin 强行选择；
+- 参数记录完整且确定；
+- 所有正向输出再次运行零修改；
+- 精确/正则规则不读取文件、网络、词典或环境；词典规则只读取已安装 extra 自带资源，且不访问网络或任意路径。
+
+实现后运行根 README 届时列出的全部基础检查：
+
+```bash
+.venv/bin/ruff check .
+.venv/bin/mypy src tests
+.venv/bin/pytest
+.venv/bin/python -m pip wheel . --no-deps --wheel-dir /tmp/mdpolish-wheel-check
+git diff --check
+git status --short
+```
+
+最终报告只贴本轮真实输出。失败必须修复或明确报告，不能放宽断言掩盖。
+
+## 14. 风险与代价
+
+- **词法块扫描不是完整 parser：** 它能保守排除常见代码和表格，并处理约定的四类块；复杂嵌套或方言结构可能漏匹配。
+- **显式正则仍可能写错：** 库保证锚点、冲突和精确编辑安全，不保证调用方规则符合具体业务语义。
+- **heading continuation 有歧义：** 紧随标题的普通行可能本来就是段落；只有映射本身已获项目确认时才应允许 heading 规则。
+- **兼容规范化可能多对一：** 无法唯一回映时选择漏处理，不猜测源范围。
+- **链式规划增加实现复杂度：** 用每个物理边界最多消费一次和单个连续编辑限制状态空间，换取一次提议内稳定完成。
+- **规则顺序成为契约：** 这是支持 `FIRST` 以及优先级 tie-break 的必要代价，调用方必须把顺序纳入版本和评审。
+- **词典仍会漏掉专名和新词：** 自动规则对无命中和歧义失败关闭；项目可用精确规则补充，不把低覆盖伪装成全文正确。
+
+## 15. 批准后的实施边界
+
+批准本文将授权：
+
+1. 重构 `src/mdpolish/modifiers/mapped_line_join.py`；
+2. 新增或扩展 `tests/test_mapped_line_join.py`，必要时只在 `tests/` 增加同主题测试文件；
+3. 更新 `pyproject.toml`，只增加第 11 节批准的 optional extras；
+4. 更新根 `README.md` 中已经过期的当前能力边界、安装方式和调用示例；
+5. 在不改变正文的前提下检查 `AGENTS.md` 与 `CLAUDE.md` 镜像；
+6. 运行第 13 节检查并查看 Git diff、wheel 内容和工作区状态。
+
+批准本文不授权修改 `_text_ranges.py`、其他 modifier、其他 Wiki 文档、真实数据、外部系统，
+也不授权提交、推送、创建 PR 或发布。