81 lines
3.7 KiB
Markdown
81 lines
3.7 KiB
Markdown
# 使用本地清洗评审页面
|
||
|
||
项目已经生成 `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 可以通过回环服务读取；
|
||
- 未读取或复制真实文档，也未写入调用项目目录。
|
||
|
||
这次验证覆盖安装、数据校验和服务路径，不替代真实浏览器中的最终视觉、长文滚动和交互人工确认。
|