128 lines
4.7 KiB
Markdown
128 lines
4.7 KiB
Markdown
# 使用本地页面评审一次 Markdown 清洗运行
|
||
|
||
## 1. 适用范围
|
||
|
||
本指南用于打开已经发布在 `artifacts/<YYYY-MM-DD>/runs/<run_id>/` 的本地清洗运行。完整双栏比较要求运行目录包含
|
||
`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/<YYYY-MM-DD>/runs/<run_id>
|
||
```
|
||
|
||
确认该目录内存在：
|
||
|
||
```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/<YYYY-MM-DD>/runs/<run_id>
|
||
```
|
||
|
||
启动成功时只打印运行 ID、文档数量和随机本机端口，不打印原文或绝对源路径：
|
||
|
||
```text
|
||
mdpolish 评审器已启动：http://127.0.0.1:<port>（<run_id>，<count> 份文档）
|
||
```
|
||
|
||
在本机浏览器打开该地址。评审结束后回到终端按 `Ctrl+C` 停止服务。
|
||
|
||
开发页面时开两个终端。第一个终端在仓库根目录把 Python API 固定到 Vite 代理使用的本机端口：
|
||
|
||
```bash
|
||
.venv/bin/python -m reviewer.server \
|
||
--run-dir /home/lihaoze/work/mdpolish/artifacts/<YYYY-MM-DD>/runs/<run_id> \
|
||
--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` 管理；页面不会自动删除到期产物。
|