# 使用本地清洗评审页面

项目已经生成 `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 可以通过回环服务读取；
- 未读取或复制真实文档，也未写入调用项目目录。

这次验证覆盖安装、数据校验和服务路径，不替代真实浏览器中的最终视觉、长文滚动和交互人工确认。