feat: 增加项目无关的本地清洗评审器

2026-08-28 19:06:10 +08:00
parent 10c026c7ad
commit 6c0dd5974b
82 changed files with 9335 additions and 48 deletions
@@ -1,8 +1,9 @@
 # ReviewDocument 机器投影 schema 1.0

-本文记录 `mdpolish.review.review_document_to_dict()` 和 `render_json_report()` 当前稳定的跨进程查询口径。公共 Python 类型和
-运行校验以 `src/mdpolish/review.py` 与测试为准；设计理由和批准边界见
-[`0012-review-document-machine-projection.md`](../design/0012-review-document-machine-projection.md)。
+本文记录 `mdpolish.review.review_document_to_dict()`、`render_json_report()` 和 `parse_json_report()` 当前稳定的跨进程查询
+口径。公共 Python 类型和运行校验以代码与测试为准；生产契约的设计理由见
+[`0012-review-document-machine-projection.md`](../design/0012-review-document-machine-projection.md)，只读解析与本地页面边界见
+[`0014-generic-local-reviewer.md`](../design/0014-generic-local-reviewer.md)。

 ## 1. Schema 身份与入口

@@ -18,13 +19,15 @@
 schema 版本独立于 `mdpolish` 包版本和 modifier 版本。公共入口是：

 ```python
-from mdpolish.review import render_json_report, review_document_to_dict
+from mdpolish.review import parse_json_report, render_json_report, review_document_to_dict

 payload = review_document_to_dict(review, detail="summary")
 json_text = render_json_report(review, detail="full")
+parsed = parse_json_report(json_text, expected_detail="full")
 ```

-两者只接受内存中的 `ReviewDocument`。JSON reporter 编码同 detail 的正式 dict，不定义另一套字段，也不读写文件。
+前两个生产入口只接受内存中的 `ReviewDocument`。JSON reporter 编码同 detail 的正式 dict，不定义另一套字段，也不读写文件。
+reader 只接受内存字符串，返回新的普通 JSON 基本值容器；它不接收路径，也不恢复 `ReviewDocument`。

 ## 2. 顶层字段

@@ -234,7 +237,40 @@ array，不根据二元组外形猜成 JSON object：

 返回值是 Python `str`。调用方保存或发送时负责 UTF-8 编码、媒体类型、权限和保留周期。库不接收路径或文件对象。

-## 7. 兼容策略
+## 7. 只读解析保证
+
+```python
+from mdpolish.review import ReviewParseError, parse_json_report
+
+payload = parse_json_report(json_text)
+full_payload = parse_json_report(json_text, expected_detail="full")
+```
+
+`expected_detail` 可以省略，也可以显式指定 `summary`、`changes` 或 `full`。报告自己的 detail 不匹配时失败。返回结果是本次
+解析新建的 dict/list；修改它不会恢复或改变 producer 侧的 `ReviewDocument`。
+
+所有 detail 都检查：
+
+- JSON object key 唯一，字符串可以严格编码为 UTF-8，整数和浮点数满足第 4 节范围；
+- schema、detail、enum、稳定错误代码、数组顺序、引用位置和计数；
+- `summary` / `changes` 没有越过各自的正文暴露边界；
+- 状态、`current_kind`、错误阶段、完成阶段和残留候选相容。
+
+`summary` 和 `changes` 没有完整阶段正文，reader 不会声称能验证不存在的文本。`full` 另外检查：
+
+- input、current、所有 stage before/after 的码点长度和 SHA-256；
+- 第一个阶段从 input 开始，相邻阶段首尾相接，最后一个完成阶段等于 current；
+- Change span 的原文、位置、哈希、proposal/edit index、冲突和正式报告顺序；
+- 用核心共用的精确编辑原语重放每个 Change 批次，结果与 stage after 完全相同；
+- 零修改阶段的 before 和 after 完全相同；
+- residual edit 的原文、范围、顺序和冲突。
+
+任一步失败都抛出 `ReviewParseError`。顶层错误消息只包含字段路径和契约类别，不包含正文、modifier 参数、reason 或诊断消息。
+reader 不调用 Modifier，不修复、截断或猜测损坏结果。
+
+这是只读解析，不是反序列化。返回 dict 不能重新运行 Pipeline、恢复 Python 模型或获得原始 `TransformResult` 的权威身份。
+
+## 8. 兼容策略

 `schema_version` 使用 `MAJOR.MINOR`：

@@ -247,4 +283,5 @@ array，不根据二元组外形猜成 JSON object：
 同一 major 的消费者必须忽略未知 object 字段，但必须保持 array 顺序；不得把未知状态当成 `success`。消费者应拒绝自己不
 支持的 schema major。

-schema `1.0` 是单向生产契约。当前没有官方反序列化器、JSON Schema 文件、历史迁移器或数据库 schema。
+schema `1.0` 仍是单向生产契约。官方 reader 接受同一 major 的已知字段语义，并忽略未知 object 字段的语义；未知状态、
+detail、enum 或坐标契约仍会失败。当前没有 `ReviewDocument` 反序列化器、JSON Schema 文件、历史迁移器或数据库 schema。