feat: generalize mapped line joining

README.md

@@ -14,7 +14,7 @@
 | 精确编辑执行器 | 校验快照、范围、原文、重复和冲突后原子应用一个批次 | 不判断项目业务语义 |
 | `Pipeline` | 按调用方顺序运行修改器，并对最终快照做只读稳定性复查 | 不自动选规则、不重排、不循环执行 |
 | `regex_replace()` | 把非空正则匹配转换为精确编辑 | 不提供规则注册表、配置加载或默认模式 |
-| `mapped_line_join()` | 按调用方提供的映射合并跨行片段 | 库内没有默认词表，不猜测未知词 |
+| `mapped_line_join()` | 用精确、正则或可选本地词典规则合并跨行片段 | 无默认规则；代码、表格、未知结构和歧义失败关闭 |
 | HTML 表格修改器 | 处理严格表格子集的实体和单行布局 | 不是完整 HTML parser，也不是 HTML→GFM 转换器 |
 
 一次运行会返回 `success`、`failed` 或 `unstable`：
@@ -40,7 +40,14 @@ python -m venv .venv
 .venv/bin/python -m pip install -e '.[dev]'
 ```
 
-运行时只依赖 Python 标准库，支持 Python 3.11 及以上版本。
+核心运行时只依赖 Python 标准库，支持 Python 3.11 及以上版本。自动词典规则需要调用方明确安装并选择对应 extra：
+
+```bash
+python -m pip install '/path/to/mdpolish[lexical]'   # pyspellchecker + Pyphen
+python -m pip install '/path/to/mdpolish[frequency]' # wordfreq，体积和传递依赖更大
+```
+
+安装 extra 不会自动启用规则，也不会触发在线下载或改变精确/正则规则行为。
 
 ## 组装自己的流水线
 
@@ -142,8 +149,16 @@ remove_marker = Modifier(
 
 ## 通用修改器的严格边界
 
-`mapped_line_join()` 只使用调用方显式传入的三元组：左片段、右片段和最终文本。它只处理相邻物理行或中间恰好一个
-同风格空行的情况，并检查 ASCII 词边界。
+`mapped_line_join()` 保留 `(left, right, replacement)` 三元组，也接受模块
+`mdpolish.modifiers.mapped_line_join` 中的不可变规则值。规则可以使用精确片段、两侧命名正则、只约束右侧的行尾正则，
+或从行尾与行首自动生成 `JOINED` / `HYPHENATED` / `SPACED` 候选并查询显式选择的本地词典。自动规则不要求逐词维护
+映射；精确规则和 `KeepLineJoinRule` 用于项目词、例外与否决。
+
+调用方还要显式决定块范围、换行处理、冲突策略、大小写和 Unicode 规范化。默认区分大小写且不规范化；支持相邻行或
+中间最多一个同风格空行，并可在一次提议内完成多行链式合并。保守词法扫描只正向识别段落、ATX 标题 continuation、
+列表 continuation 和同深度引用；代码块、GFM pipe table、raw HTML table、混合候选行尾及无法确认的容器保持原文。
+完整公共模型、选择流程和限制见
+[`0009-generalized-mapped-line-join.md`](research-wiki/design/0009-generalized-mapped-line-join.md)。
 
 `html_table_entity_unescape()` 只在严格完整的 `<td>` / `<th>` 文本中处理 `&amp;lt;`、`&amp;gt;` 和
 `&amp;amp;`。`html_table_layout()` 只调整严格单行表格的外层行布局，并保留标签、属性和单元格内容。
@@ -174,7 +189,7 @@ research-wiki/
 
 - 文件适配器、公共 CLI、配置文件、profile 或批处理协议；
 - 自动规则发现、注册表或默认流水线；
-- Markdown AST、完整 HTML parser 或新运行依赖；
+- Markdown AST、完整 HTML parser 或必装的第三方运行依赖；
 - artifact、报告、Web/桌面评审器；
 - 任何业务项目的规则、固定参数、文档 ID、数据或验收统计。
 
@@ -202,7 +217,7 @@ git status --short
 ```
 
 上述检查已于 2026-08-26 在 Python 3.13.11 环境实际运行：Ruff 通过，mypy 检查 21 个源码和测试文件无问题，
-pytest 共 104 项测试通过，`mdpolish-0.2.0-py3-none-any.whl` 构建成功。wheel 内容已单独检查，只包含通用 Python
-包、类型标记和包元数据，不包含项目规则、实验脚本、评审器或 Node.js 文件。
+pytest 共 168 项通过、2 项因本环境未安装可选词典 backend 而跳过，`mdpolish-0.2.0-py3-none-any.whl` 构建成功。
+wheel 内容已单独检查，只包含通用 Python 包、类型标记和包元数据，不包含项目规则、实验脚本、评审器或 Node.js 文件。
 
 `pyproject.toml` 声明的 Python 3.11 及以上为支持范围；本次结果不表示已经在每个受支持版本上完成兼容性验证。