iomgaa/mdpolish
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add generic review projection and reporting

Browse Source
This commit is contained in:
Bepr4
2026-08-27 22:02:12 +08:00
parent 5b8acc3f4c
commit 668c139168
13 changed files with 2133 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+48 -16
View File
@@ -3,8 +3,8 @@
`mdpolish` 是实验室共用的、项目无关的 Python Markdown 修改库。它提供函数式 `Modifier`、精确文本编辑执行器、
有序 `Pipeline`、正则修改器工厂，以及少量可以用合成样例完整说明的通用修改器。
当前发布版本是 [`v0.3.0`](https://github.com/Bepr4/mdpolish/releases/tag/v0.3.0)。库只处理内存中的 Markdown
字符串，不读取或写入文件，不提供默认流水线，也不包含任何项目的规则集合、数据清单、实验脚本或评审工具。
当前发布版本是 [`v0.4.0`](https://github.com/Bepr4/mdpolish/releases/tag/v0.4.0)。库只处理内存中的 Markdown 字符串，
不读取或写入文件，不提供默认流水线，也不包含任何项目的规则集合、数据清单、实验脚本或评审界面。
## 当前能力
@@ -13,6 +13,8 @@
| `Modifier` | 把不可变元数据与普通提议函数组合起来 | 函数只提议修改，不直接改字符串或文件 |
| 精确编辑执行器 | 校验快照、范围、原文、重复和冲突后原子应用一个批次 | 不判断项目业务语义 |
| `Pipeline` | 按调用方顺序运行修改器，并对最终快照做只读稳定性复查 | 不自动选规则、不重排、不循环执行 |
| `build_review_document()` | 验证并重放已有结果，提供可信阶段、位置、全文和错误/残留证据 | 不重新运行修改器，不猜测损坏或不完整的结果 |
| `render_markdown_report()` | 把评审视图编排成完整 Markdown 源码报告字符串 | 只返回内存字符串，不创建文件或业务页面 |
| `regex_replace()` | 把非空正则匹配转换为精确编辑 | 不提供规则注册表、配置加载或默认模式 |
| `mapped_line_join()` | 用精确、正则或可选本地词典规则合并跨行片段 | 无默认规则；代码、表格、未知结构和歧义失败关闭 |
| HTML 表格修改器 | 处理严格表格子集的实体和单行布局 | 不是完整 HTML parser，也不是 HTML→GFM 转换器 |
@@ -31,15 +33,15 @@
不可移动的 tag：
```bash
python -m pip install 'mdpolish @ git+https://github.com/Bepr4/mdpolish.git@v0.3.0'
python -m pip install 'mdpolish[lexical] @ git+https://github.com/Bepr4/mdpolish.git@v0.3.0'
python -m pip install 'mdpolish[frequency] @ git+https://github.com/Bepr4/mdpolish.git@v0.3.0'
python -m pip install 'mdpolish @ git+https://github.com/Bepr4/mdpolish.git@v0.4.0'
python -m pip install 'mdpolish[lexical] @ git+https://github.com/Bepr4/mdpolish.git@v0.4.0'
python -m pip install 'mdpolish[frequency] @ git+https://github.com/Bepr4/mdpolish.git@v0.4.0'
```
也可以安装同一 GitHub Release 附带的 wheel：
```bash
python -m pip install 'mdpolish[lexical] @ https://github.com/Bepr4/mdpolish/releases/download/v0.3.0/mdpolish-0.3.0-py3-none-any.whl'
python -m pip install 'mdpolish[lexical] @ https://github.com/Bepr4/mdpolish/releases/download/v0.4.0/mdpolish-0.4.0-py3-none-any.whl'
```
Release 页面同时提供 wheel 的 SHA-256 校验值。仓库或 Release 如果是私有的，调用方需要自行配置 GitHub 访问权限；
@@ -156,7 +158,35 @@ if result.status is RunStatus.SUCCESS and result.output_markdown is not None:
output_path.write_text(result.output_markdown, encoding="utf-8")
```
文件读取、输出命名、覆盖策略、批处理、CLI 和报告都属于调用项目，不属于 `mdpolish`。
文件读取、输出命名、覆盖策略、批处理和 CLI 都属于调用项目。`mdpolish` 可以生成通用的内存评审视图与 Markdown 报告
字符串，但不会自动保存它们，也不知道报告来自哪个文件。
## 构建内存评审视图和报告
调用方保留原始 Markdown，并把它与 `TransformResult` 一起传给评审构建函数：
```python
from mdpolish.review import build_review_document, render_markdown_report
input_markdown = "an exam-\nple text"
result = pipeline.transform(input_markdown)
review = build_review_document(input_markdown, result)
report_markdown = render_markdown_report(review)
assert review.current_markdown == "an example text"
assert report_markdown.startswith("# mdpolish review report\n")
```
`build_review_document()` 不调用 `Modifier.propose()`，而是从输入开始重放已经记录的实际修改，逐阶段验证修改器身份、快照
哈希、范围、原文、冲突、排序和阶段结果。无法证明结果一致时会抛出 `ReviewBuildError`，不会生成近似报告。
成功结果的 `stages_complete` 为 `True`。`unstable` 和只有 final review 错误的 `failed` 也已经完成全部 transform 阶段，
但其当前全文仍明确标记为部分输出；preflight 或 transform 失败只包含失败前能够证明完成的阶段。
Markdown reporter 会包含完整输入、当前全文、统一 diff 以及实际修改的 `before` / `after`，因此不是安全日志。它默认只列出
前 20 条残留候选，并且不重复输出残留候选正文；调用项目如果保存报告，仍需负责路径、权限、脱敏和保留周期。每个完整
阶段都会保留前后快照，当前版本没有承诺无限文档长度或修改器数量下的内存上限。
## 编写项目自己的修改器
@@ -232,6 +262,7 @@ src/mdpolish/
├── modifier.py # 函数式 Modifier 契约
├── edits.py # 批次验证与原子应用
├── pipeline.py # 有序执行与最终稳定性复查
├── review.py # 可信评审投影与内存 Markdown reporter
├── regex.py # 正则修改器工厂
└── modifiers/ # 少量项目无关的通用修改器
tests/ # 只使用虚构文本的核心与通用修改器测试
@@ -248,13 +279,14 @@ research-wiki/
- 文件适配器、公共 CLI、配置文件、profile 或批处理协议；
- 自动规则发现、注册表或默认流水线；
- Markdown AST、完整 HTML parser 或必装的第三方运行依赖；
- artifact、报告、Web/桌面评审器；
- artifact、报告文件、JSON/HTML reporter、Web/桌面评审器或项目审核流程；
- 任何业务项目的规则、固定参数、文档 ID、数据或验收统计。
公共边界与原因见
[`0008-generic-functional-library-boundary.md`](research-wiki/design/0008-generic-functional-library-boundary.md)，当前机制见
[`functional-modifier-core.md`](research-wiki/explanation/functional-modifier-core.md)。旧 design 只保存历史决策，不代表当前
交付能力。
[`functional-modifier-core.md`](research-wiki/explanation/functional-modifier-core.md)。通用内存评审能力的批准边界见
[`0011-generic-review-projection-and-reporting.md`](research-wiki/design/0011-generic-review-projection-and-reporting.md)，当前机制见
[`review-projection.md`](research-wiki/explanation/review-projection.md)。旧 design 只保存历史决策，不代表当前交付能力。
## 当前可用检查
@@ -275,12 +307,12 @@ git status --short
```
上述检查已于 2026-08-27 实际运行。Python 3.13.11 核心开发环境中 Ruff 和 mypy 通过，pytest 为
`170 passed, 3 skipped`；三个 skip 是该环境没有安装的真实 optional backend 路径，不计入发布验收。
`211 passed, 3 skipped`；三个 skip 是该环境没有安装的真实 optional backend 路径，不计入发布验收。
从 `mdpolish-0.3.0-py3-none-any.whl` 安装全部 extras 后，Python 3.11.16 和 Python 3.13.11 环境分别得到
`173 passed`，没有 skip。仓库外消费者 smoke test 已覆盖核心精确/正则规则、`pyspellchecker + Pyphen` 和
`wordfreq` 的最终输出与版本审计。wheel 共 16 个文件，只包含通用 Python 包、类型标记和包元数据；不包含 tests、
Wiki、真实数据或项目规则。`v0.3.0` Release wheel 的 SHA-256 是
`a510ae1755c281f7b40262e242441882f3ccbc3fbc2174c6f5db3e8a8ae85060`。
`mdpolish-0.4.0-py3-none-any.whl` 共 17 个文件，包含 `review.py` 和 `py.typed`，不包含 tests、Wiki、artifact、页面或
真实数据。安装全部 extras 后，Python 3.11.16 和 Python 3.13.11 环境分别得到 `214 passed`，没有 skip；仓库外消费者
smoke test 已覆盖核心正则、`pyspellchecker + Pyphen`、`wordfreq`、评审视图和 Markdown reporter。核心运行依赖仍只有
Python 标准库。Release wheel 的 SHA-256 是
`12e24863314958130ed082f78e89ab8bc0dad39a3848f2ae42e273d19a409693`。
上述结果证明当前版本可安装并按合成契约运行，不代表任意词典阈值已经在真实业务语料上达到生产准确率。