# 使用本地页面评审一次 Markdown 清洗运行 ## 1. 适用范围 本指南用于打开已经发布在 `artifacts//runs//` 的本地清洗运行。完整双栏比较要求运行目录包含 `review-locator.json`，并且原文仍位于运行时记录的位置且哈希未改变。 评审器只读文件，不重新运行组件、不修改原文和产物。当前不适用于 GovDoc、远程目录、多人共享或生产部署。 本指南于 2026-08-23 使用 Python 3.13.11、当前用户 nvm 中的 Node.js 24.19.0 和运行 `clindb-first-batch-reviewer-v1` 实际验证。 ## 2. 准备一次可评审运行 先按 [`run-local-clindb-first-batch-experiment.md`](run-local-clindb-first-batch-experiment.md) 产生一次新的运行。成功终端摘要 会给出绝对 artifact 路径，例如： ```text artifacts=/home/lihaoze/work/mdpolish/artifacts//runs/ ``` 确认该目录内存在： ```text manifest.json review-locator.json documents/ ``` 不要编辑定位文件，也不要向旧运行目录手工补写它。历史运行缺少 locator 时，使用不同运行 ID 重新实验。 ## 3. 准备评审器 评审器前端的安装、检查和构建要求 Node.js 24 LTS。当前用户 nvm 已安装与 `.nvmrc` 匹配的版本。在仓库根目录执行： ```bash cd reviewer nvm use node --version npm --version ``` `node --version` 必须是受支持的 `v24`。本仓库不负责修改系统级 Node.js；版本不符时先在开发环境外准备正确运行时。 首次安装或锁文件变化后，仍在 `reviewer/` 目录执行： ```bash npm ci ``` 当前有效的 Python 与 reviewer 检查命令只以根目录 [`README.md`](../../README.md#当前可用检查) 为准。检查通过后构建页面： ```bash npm run build ``` ## 4. 启动一次运行 回到仓库根目录，用当前 Python 虚拟环境启动只读服务并传入运行目录： ```bash .venv/bin/python -m reviewer.server \ --run-dir /home/lihaoze/work/mdpolish/artifacts//runs/ ``` 启动成功时只打印运行 ID、文档数量和随机本机端口，不打印原文或绝对源路径： ```text mdpolish 评审器已启动：http://127.0.0.1:（， 份文档） ``` 在本机浏览器打开该地址。评审结束后回到终端按 `Ctrl+C` 停止服务。 开发页面时开两个终端。第一个终端在仓库根目录把 Python API 固定到 Vite 代理使用的本机端口： ```bash .venv/bin/python -m reviewer.server \ --run-dir /home/lihaoze/work/mdpolish/artifacts//runs/ \ --port 4174 ``` 第二个终端启动只绑定 `127.0.0.1:5173` 的 Vite 页面；它只把 `/api/` 代理给上述 Python 服务，Node.js 不读取 artifact： ```bash cd reviewer npm run dev ``` ## 5. 页面怎么查看 1. 先确认顶部整体状态和总修改数与 `manifest.json` 一致； 2. 在左侧选择文档，主双栏默认显示清洗前和最终成功输出； 3. 在组件时间线选择一个组件，双栏切换为该组件执行前后； 4. 检查组件版本和修改数，零修改应显示 `0`，而不是从时间线消失； 5. 点击修改详情，跳到对应组件阶段的位置并核对理由、`before` 和 `after`； 6. 对 `failed` / `unstable` 只查看错误和残留候选，不寻找不存在的正式输出。 页面中的总修改数是实际 `Change` 条数，不是 diff hunk 数、字符数或问题数量。 ## 6. 常见错误 ### 原文路径失效或哈希改变 评审器不会搜索同名文件。确认输入没有被移动或修改；如果需要在新位置运行，使用新的运行 ID 重新执行实验。不要改 locator 绕过哈希检查。 ### 历史运行没有 `review-locator.json` 历史产物仍可在页面查看清单和已有审计，也可人工查看 manifest、result 和 diff，但第一版页面不能自动找到完整原文或 组件阶段。不要回写历史目录；需要完整双栏时重新运行一次即可。 ### 不支持 schema 评审器只支持当前文档列出的 schema 版本。不要删除或伪造 `schema_version`；应升级评审器适配器或使用与产物匹配的代码。 ### 没有 `cleaned.md` 对应文档状态是 `failed` 或 `unstable` 时这是正常边界。页面不会从 Change 重建并冒充正式结果。 ### 服务拒绝 Host、Origin 或写请求 评审器只接受本机同源的只读请求。不要通过反向代理、远程端口转发或网页跨域调用它；这些用法没有批准。 ## 7. 数据边界 页面会在本机内存中读取完整原文和成功输出。不要截图、复制或通过浏览器扩展分享真实内容。运行目录继续受 Git 忽略并按 manifest 的 `retention_until` 管理；页面不会自动删除到期产物。