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

2026-08-28 19:06:10 +08:00
parent 10c026c7ad
commit 6c0dd5974b
82 changed files with 9335 additions and 48 deletions
@@ -0,0 +1,80 @@
+# 使用本地清洗评审页面
+
+项目已经生成 `ReviewDocument`，但不希望自己维护 JSON 校验、HTTP 服务和前端时，可以把正式 `full` JSON 保存到一个明确
+目录，再由 `mdpolish-reviewer` 只读展示。评审器不会读取原始 Markdown 路径，也不会运行 Pipeline 或写回结果。
+
+## 前置条件
+
+- 已安装 `mdpolish 0.7.0`；普通 wheel 即可，不需要安装 Node.js 或任何第三方 Python 运行依赖；
+- 调用项目已经显式选择 Modifier、完成 `Pipeline.transform()` 并得到相应输入文本；
+- 项目已经决定评审 JSON 的保存目录、权限、Git 忽略和保留周期。
+
+`full` JSON 会重复包含输入、当前文本和各 Modifier 阶段全文。不要把它放进公开目录、提交到 Git，或当作脱敏日志。
+
+## 1. 保存正式 full JSON
+
+下面的 `input_markdown` 和 `result` 来自调用项目已有的内存清洗流程：
+
+```python
+from pathlib import Path
+
+from mdpolish.review import build_review_document, render_json_report
+
+review = build_review_document(input_markdown, result)
+review_path = Path("artifacts/reviews/example.review.json")
+review_path.parent.mkdir(parents=True, exist_ok=True)
+review_path.write_text(
+    render_json_report(review, detail="full") + "\n",
+    encoding="utf-8",
+)
+```
+
+一个目录可以放多份直属的 `*.review.json`。评审器不会递归查找子目录，也不会跟随文件或目录符号链接。文件名去掉
+`.review.json` 后只是页面标签，不代表原始文件路径或业务身份。
+
+## 2. 启动页面
+
+```bash
+mdpolish-reviewer --review-dir artifacts/reviews
+```
+
+也可以使用等价入口：
+
+```bash
+python -m mdpolish.reviewer --review-dir artifacts/reviews
+```
+
+默认由系统选择空闲端口。成功时终端会显示类似结果：
+
+```text
+mdpolish 评审器已启动：http://127.0.0.1:43127（1 份文档）
+```
+
+在同一台机器的浏览器中打开实际打印的 URL。页面左侧选择文档或 Modifier；总结果比较完整输入与成功输出，Modifier 视图
+比较该阶段的完整 before/after。点击 Change 会切换到所属阶段并定位左栏原文；零修改阶段仍可选择。
+
+按 `Ctrl+C` 停止服务。服务只绑定 `127.0.0.1`，停止时不会改动评审目录。
+
+## 3. 失败时怎么判断
+
+| 现象 | 含义与处理 |
+| --- | --- |
+| `评审目录没有直属 full review JSON` | 检查目录是否正确，以及文件名是否以 `.review.json` 结尾 |
+| `detail does not match the requested value` | 项目保存的不是 `detail="full"`，重新从可信 `ReviewDocument` 生成 |
+| `review JSON parsing failed` | JSON 结构、哈希、阶段链、Change 重放或状态不一致；不要绕过校验展示 |
+| `评审目录不能是符号链接` | 传入真实目录路径，不使用符号链接 |
+| `无法启动本地评审服务` | 指定端口可能被占用；删除 `--port` 让系统选择，或换一个本机端口 |
+
+任意一份 JSON 损坏都会阻止整个集合启动。错误只用于定位契约类别；不要把正文、修改片段或绝对目录补进日志。
+
+## 验证记录
+
+本流程于 2026-08-28 使用发布候选 wheel 和虚构的 emoji、CRLF、一次修改及一个零修改阶段实际验证：
+
+- wheel 在无第三方 Python 依赖的全新环境中安装成功；
+- console script 与模块入口均可用，预期启动错误不产生 traceback；
+- 集合、文档和 Modifier API 返回正确，Python 码点范围正确转换为 UTF-16；
+- wheel 内首页和生产 JavaScript 可以通过回环服务读取；
+- 未读取或复制真实文档，也未写入调用项目目录。
+
+这次验证覆盖安装、数据校验和服务路径，不替代真实浏览器中的最终视觉、长文滚动和交互人工确认。