使用本地清洗评审页面

项目已经生成 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 来自调用项目已有的内存清洗流程：

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. 启动页面

mdpolish-reviewer --review-dir artifacts/reviews

也可以使用等价入口：

python -m mdpolish.reviewer --review-dir artifacts/reviews

默认由系统选择空闲端口。成功时终端会显示类似结果：

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

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

3.7 KiB Raw Blame History Unescape Escape