iomgaa/mdpolish

Fork 0

Files

T

Bepr4 ac798a2610 实现本地 Markdown 清洗评审器

2026-08-24 01:02:16 +08:00

4.7 KiB

Raw Blame History

使用本地页面评审一次 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 产生一次新的运行。成功终端摘要会给出绝对 artifact 路径，例如：

artifacts=/home/lihaoze/work/mdpolish/artifacts/<YYYY-MM-DD>/runs/<run_id>

确认该目录内存在：

manifest.json
review-locator.json
documents/

不要编辑定位文件，也不要向旧运行目录手工补写它。历史运行缺少 locator 时，使用不同运行 ID 重新实验。

3. 准备评审器

评审器前端的安装、检查和构建要求 Node.js 24 LTS。当前用户 nvm 已安装与 .nvmrc 匹配的版本。在仓库根目录执行：

cd reviewer
nvm use
node --version
npm --version

node --version 必须是受支持的 v24。本仓库不负责修改系统级 Node.js；版本不符时先在开发环境外准备正确运行时。

首次安装或锁文件变化后，仍在 reviewer/ 目录执行：

npm ci

当前有效的 Python 与 reviewer 检查命令只以根目录 README.md 为准。检查通过后构建页面：

npm run build

4. 启动一次运行

回到仓库根目录，用当前 Python 虚拟环境启动只读服务并传入运行目录：

.venv/bin/python -m reviewer.server \
  --run-dir /home/lihaoze/work/mdpolish/artifacts/<YYYY-MM-DD>/runs/<run_id>

启动成功时只打印运行 ID、文档数量和随机本机端口，不打印原文或绝对源路径：

mdpolish 评审器已启动：http://127.0.0.1:<port>（<run_id>，<count> 份文档）

在本机浏览器打开该地址。评审结束后回到终端按 Ctrl+C 停止服务。

开发页面时开两个终端。第一个终端在仓库根目录把 Python API 固定到 Vite 代理使用的本机端口：

.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：

cd reviewer
npm run dev

5. 页面怎么查看

先确认顶部整体状态和总修改数与 manifest.json 一致；
在左侧选择文档，主双栏默认显示清洗前和最终成功输出；
在组件时间线选择一个组件，双栏切换为该组件执行前后；
检查组件版本和修改数，零修改应显示 0，而不是从时间线消失；
点击修改详情，跳到对应组件阶段的位置并核对理由、before 和 after；
对 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 管理；页面不会自动删除到期产物。

4.7 KiB Raw Blame History Unescape Escape