feat: 增加评审文档机器投影与 JSON 报告

2026-08-28 14:23:30 +08:00
parent dd012f4905
commit 843952b194
7 changed files with 2096 additions and 16 deletions
@@ -3,8 +3,9 @@
 `mdpolish` 是实验室共用的、项目无关的 Python Markdown 修改库。它提供函数式 `Modifier`、精确文本编辑执行器、
 有序 `Pipeline`、正则修改器工厂，以及少量可以用合成样例完整说明的通用修改器。

-当前发布版本是 [`v0.4.0`](https://github.com/Bepr4/mdpolish/releases/tag/v0.4.0)。库只处理内存中的 Markdown 字符串，
-不读取或写入文件，不提供默认流水线，也不包含任何项目的规则集合、数据清单、实验脚本或评审界面。
+当前发布版本是 [`v0.4.0`](https://github.com/Bepr4/mdpolish/releases/tag/v0.4.0)，当前源码树的下一候选版本是
+`0.5.0`。库只处理内存中的 Markdown 字符串，不读取或写入文件，不提供默认流水线，也不包含任何项目的规则集合、
+数据清单、实验脚本或评审界面。

 ## 当前能力

@@ -15,6 +16,8 @@
 | `Pipeline` | 按调用方顺序运行修改器，并对最终快照做只读稳定性复查 | 不自动选规则、不重排、不循环执行 |
 | `build_review_document()` | 验证并重放已有结果，提供可信阶段、位置、全文和错误/残留证据 | 不重新运行修改器，不猜测损坏或不完整的结果 |
 | `render_markdown_report()` | 把评审视图编排成完整 Markdown 源码报告字符串 | 只返回内存字符串，不创建文件或业务页面 |
+| `review_document_to_dict()` | 按 schema `1.0` 把评审视图投影成普通 JSON 基本值 | 单向投影，不反序列化或重新应用修改 |
+| `render_json_report()` | 复用正式 dict 投影生成确定的内存 JSON 字符串 | 不创建文件；默认摘要不等于公开安全日志 |
 | `regex_replace()` | 把非空正则匹配转换为精确编辑 | 不提供规则注册表、配置加载或默认模式 |
 | `mapped_line_join()` | 用精确、正则或可选本地词典规则合并跨行片段 | 无默认规则；代码、表格、未知结构和歧义失败关闭 |
 | HTML 表格修改器 | 处理严格表格子集的实体和单行布局 | 不是完整 HTML parser，也不是 HTML→GFM 转换器 |
@@ -45,7 +48,8 @@ python -m pip install 'mdpolish[lexical] @ https://github.com/Bepr4/mdpolish/rel
 ```

 Release 页面同时提供 wheel 的 SHA-256 校验值。仓库或 Release 如果是私有的，调用方需要自行配置 GitHub 访问权限；
-库不会保存凭据。开发环境仍从本地工作树安装：
+库不会保存凭据。以上命令当前安装的是已发布的 `v0.4.0`，不包含本源码树尚未发布的 `0.5.0` 机器投影。开发环境仍从
+本地工作树安装：

 ```bash
 python -m venv .venv
@@ -158,23 +162,33 @@ 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` 可以生成通用的内存评审视图与 Markdown 报告
-字符串，但不会自动保存它们，也不知道报告来自哪个文件。
+文件读取、输出命名、覆盖策略、批处理和 CLI 都属于调用项目。`mdpolish` 可以生成通用的内存评审视图、机器投影、JSON
+字符串与 Markdown 报告字符串，但不会自动保存它们，也不知道报告来自哪个文件。

 ## 构建内存评审视图和报告

 调用方保留原始 Markdown，并把它与 `TransformResult` 一起传给评审构建函数：

 ```python
-from mdpolish.review import build_review_document, render_markdown_report
+from mdpolish.review import (
+    build_review_document,
+    render_json_report,
+    render_markdown_report,
+    review_document_to_dict,
+)

 input_markdown = "an exam-\nple  text"
 result = pipeline.transform(input_markdown)

 review = build_review_document(input_markdown, result)
+review_summary = review_document_to_dict(review)
+report_json = render_json_report(review, detail="changes")
 report_markdown = render_markdown_report(review)

 assert review.current_markdown == "an example text"
+assert review_summary["schema_version"] == "1.0"
+assert review_summary["detail"] == "summary"
+assert report_json.startswith('{\n  "schema_name": "mdpolish.review"')
 assert report_markdown.startswith("# mdpolish review report\n")
 ```

@@ -188,6 +202,16 @@ Markdown reporter 会包含完整输入、当前全文、统一 diff 以及实
 前 20 条残留候选，并且不重复输出残留候选正文；调用项目如果保存报告，仍需负责路径、权限、脱敏和保留周期。每个完整
 阶段都会保留前后快照，当前版本没有承诺无限文档长度或修改器数量下的内存上限。

+机器投影使用独立于包版本的 schema `1.0`，并提供三个显式 detail：
+
+- `summary`：默认值；只含状态、哈希、计数、modifier 身份、阶段摘要和稳定错误代码，不含正文承载字段；
+- `changes`：再加入 modifier 参数、适用说明、实际修改片段、错误消息和未应用残留候选；
+- `full`：再加入完整输入、当前全文和每个阶段的完整前后全文。
+
+高 detail 可能还原敏感内容。即使 `summary` 不含正文，它仍然携带项目元数据和哈希，不能自动视为匿名或适合公开传播。
+dict 和 JSON 都是单向派生视图，不用于恢复 `ReviewDocument` 或重新应用修改。完整 schema、坐标、哈希和兼容口径见
+[`review-projection-schema-v1.md`](research-wiki/reference/review-projection-schema-v1.md)。
+
 ## 编写项目自己的修改器

 复杂规则使用普通函数返回精确候选修改，不需要继承库基类：
@@ -262,7 +286,7 @@ src/mdpolish/
 ├── modifier.py            # 函数式 Modifier 契约
 ├── edits.py               # 批次验证与原子应用
 ├── pipeline.py            # 有序执行与最终稳定性复查
-├── review.py              # 可信评审投影与内存 Markdown reporter
+├── review.py              # 可信评审视图、机器投影及内存 JSON/Markdown reporter
 ├── regex.py               # 正则修改器工厂
 └── modifiers/             # 少量项目无关的通用修改器
 tests/                     # 只使用虚构文本的核心与通用修改器测试
@@ -279,14 +303,17 @@ research-wiki/
 - 文件适配器、公共 CLI、配置文件、profile 或批处理协议；
 - 自动规则发现、注册表或默认流水线；
 - Markdown AST、完整 HTML parser 或必装的第三方运行依赖；
- artifact、报告文件、JSON/HTML reporter、Web/桌面评审器或项目审核流程；
+- artifact、自动保存的报告文件、正式 JSON Schema 文件、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)。通用内存评审能力的批准边界见
 [`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 只保存历史决策，不代表当前交付能力。
+[`review-projection.md`](research-wiki/explanation/review-projection.md)。正式机器投影的批准边界见
+[`0012-review-document-machine-projection.md`](research-wiki/design/0012-review-document-machine-projection.md)，schema `1.0` 的稳定
+查询口径见 [`review-projection-schema-v1.md`](research-wiki/reference/review-projection-schema-v1.md)。旧 design 只保存历史
+决策，不代表当前交付能力。

 ## 当前可用检查

@@ -316,3 +343,11 @@ Python 标准库。Release wheel 的 SHA-256 是
 `12e24863314958130ed082f78e89ab8bc0dad39a3848f2ae42e273d19a409693`。

 上述结果证明当前版本可安装并按合成契约运行，不代表任意词典阈值已经在真实业务语料上达到生产准确率。
+
+`0.5.0` 候选于 2026-08-28 在 Python 3.13.11 开发环境中实际得到：mypy 通过，pytest 为
+`228 passed, 3 skipped`；三个 skip 仍是没有安装的 optional backend。除工作区已有的 `src/mdpolish/regex.py` 中文注释
+改动外，Ruff 全部通过；未排除该文件的全仓 Ruff 因其中 30 个 `RUF002` / `RUF003` 失败，本轮没有擅自修改该用户改动。
+
+候选 `mdpolish-0.5.0-py3-none-any.whl` 构建成功，共 17 个文件，包含更新后的 `review.py` 和 `py.typed`，不包含 tests、Wiki、
+报告或真实数据；在仓库外全新虚拟环境中无依赖安装后，dict 投影与 JSON reporter smoke test 通过。该临时 wheel 不是 Release
+资产，其哈希不构成发布身份；完成全仓 Ruff、提交、合并、tag 和 Release 仍需要分别确认。