实现本地 Markdown 清洗评审器

README.md

@@ -7,7 +7,8 @@
 profile 表达论文、政务文档、RAG、文档对比等不同需求。
 
 仓库当前已从纯文档治理进入第一版核心和 ClinDB 第一批组件实现阶段：已经提供可安装的 Python 内存处理包、
-8 个论文清洗组件和本地实验入口，能够保存指定论文的成功输出、审计和 diff。仓库仍不提供面向任意数据集的完整规则集、
+8 个论文清洗组件、本地实验入口，以及同仓但与清洗运行解耦的只读评审前端。实验可以保存指定论文的成功输出、
+审计和 diff；评审前端可以同时查看清洗前后全文，并逐组件复放修改。仓库仍不提供面向任意数据集的完整规则集、
 公共命令行工具、通用文件适配器或生产接口，因此目前还不是拿来即可完成任意 Markdown 清洗的成品工具。
 
 ## 当前阶段
@@ -18,13 +19,18 @@ profile 表达论文、政务文档、RAG、文档对比等不同需求。
 - 已实现不可变数据契约、组件基类、原子修改执行器、顺序流水线、审计记录和最终稳定性复查；
 - 已实现 ClinDB 第一批 8 个正式组件，覆盖 Word 批注、手稿行号、arXiv 戳、重复页眉、批准映射断词、
   HTML 表格实体与布局、参考文献空行；
-- 已有仓库内实验运行层，能严格读取显式清单、保存成功 Markdown、JSON 审计和 unified diff，并保持输入不变；
+- 已有仓库内实验运行层，能严格读取显式清单、保存成功 Markdown、JSON 审计、unified diff 和评审定位文件，
+  并保持输入不变；
+- 已有独立的 `reviewer/` 本地只读前端，服务只消费一次已发布的产物和定位文件，并与报告层共用纯 Python 快照重放逻辑，
+  不导入组件、不调用流水线，也不重新清洗；
 - 第一批流水线已对 5 份论文 Markdown 完成保存型实验，5/5 成功，共记录 155 条修改，第二次运行零修改；
-- 当前基础检查为 Ruff、mypy 和 204 项 pytest 测试，实际命令见本文“当前可用检查”。
+- 当前基础检查为 Ruff、mypy、229 项 pytest 测试，以及前端 ESLint、TypeScript、6 项 Vitest 测试和生产构建，
+  实际命令见本文“当前可用检查”。
 
 项目还没有面向任意数据集的完整清洗规则集、Markdown/HTML 通用 parser、profile 格式、通用文件输入接口、公共 CLI、
-通用批处理或生产接口。当前 first-batch 实验脚本只固定运行已批准的 5 份论文和 8 个组件；它只能证明当前 8 类确定规则
-已经闭环，不能据此认为论文中的缺失内容、乱码、复杂表格、图片或 GovDoc 已具备完整清洗能力。
+通用批处理或生产接口。评审前端也不是公共 Web 服务：它只绑定本机回环地址，只读展示 Markdown 源文和审计，不提供
+渲染预览、在线编辑或重新清洗。当前 first-batch 实验脚本只固定运行已批准的 5 份论文和 8 个组件；它只能证明当前
+8 类确定规则已经闭环，不能据此认为论文中的缺失内容、乱码、复杂表格、图片或 GovDoc 已具备完整清洗能力。
 
 ## 服务对象与复用目标
 
@@ -46,8 +52,9 @@ GovDoc 目录、具体客户名称或某一转换器的固定输出路径。
 
 两组数据都不是可提交的自动测试 fixture。`data/` 已被 Git 忽略，清洗实验不得覆盖这些输入。
 
-本地清洗实验产物位于 `artifacts/<YYYY-MM-DD>/runs/<run_id>/`。产物可能包含完整原文，同样受 Git 忽略，
-默认保留 30 个日历日，不得提交或复制到外部系统。当前只批准为上述 5 份论文副本保存产物，未批准保存 GovDoc 输出。
+本地清洗实验产物位于 `artifacts/<YYYY-MM-DD>/runs/<run_id>/`。产物可能包含完整原文；其中评审定位文件还包含
+输入源的绝对路径，因此整个目录均受 Git 忽略，默认保留 30 个日历日，不得提交或复制到外部系统。当前只批准为上述
+5 份论文副本保存产物，未批准保存 GovDoc 输出。
 
 ## 面向复用的设计原则
 
@@ -70,6 +77,7 @@ mdpolish/
 ├── src/
 │   └── mdpolish/
 │       ├── __init__.py               # 第一版核心公共导出
+│       ├── _artifact_replay.py        # 报告与评审器共用的纯快照重放
 │       ├── component.py              # 组件基类和元数据契约
 │       ├── edits.py                  # 文本编辑验证与原子应用
 │       ├── experiment.py             # 本地实验输入预检与批量编排
@@ -93,6 +101,14 @@ mdpolish/
 ├── scripts/
 │   ├── run_clindb_arxiv_experiment.py      # 只含 arXiv 组件的历史实验入口
 │   └── run_clindb_first_batch_experiment.py # ClinDB 第一批 8 组件实验入口
+├── reviewer/                          # 与组件和流水线解耦的本地只读评审器
+│   ├── .nvmrc                         # 前端开发使用 Node.js 24
+│   ├── package.json                   # React 依赖、检查和构建命令
+│   ├── server/                        # Python 产物适配、快照重放接口和本地 HTTP 服务
+│   ├── src/
+│   │   ├── client/                    # React 全文对比、组件时间线和审计界面
+│   │   └── shared/                    # 浏览器使用的内部 API 类型
+│   └── tests/                         # 前端响应、界面和源码安全测试
 ├── tests/
 │   ├── test_arxiv_submission_stamp.py
 │   ├── test_artifact_store.py
@@ -109,7 +125,10 @@ mdpolish/
 │   ├── test_reference_spacing.py
 │   ├── test_repeated_running_header.py
 │   ├── test_reporting.py
-│   └── test_word_review_comment.py
+│   ├── test_word_review_comment.py
+│   ├── test_artifact_replay.py
+│   ├── test_reviewer_artifacts.py
+│   └── test_reviewer_server.py
 ├── data/                              # 本地测试数据；Git 忽略；此处只展开常用入口
 │   └── md/
 │       ├── dmp.md
@@ -119,6 +138,9 @@ mdpolish/
 │       └── springer.md
 ├── artifacts/                         # 本地敏感实验产物；Git 忽略
 │   └── <YYYY-MM-DD>/runs/<run_id>/
+│       ├── manifest.json
+│       ├── review-locator.json         # 输入源定位和哈希；仅供本地评审
+│       └── documents/
 └── research-wiki/
     ├── README.md                       # Wiki 分类与维护规则
     ├── design/                         # 批准前的选择；批准后冻结
@@ -139,9 +161,11 @@ mdpolish/
 
 第一版核心机制见 `research-wiki/explanation/first-executable-core.md`，ClinDB 第一批组件见
 `research-wiki/explanation/clindb-first-batch-components.md`，本地实验产物机制见
-`research-wiki/explanation/local-experiment-artifacts.md`，实际运行步骤见
-`research-wiki/guides/run-local-clindb-first-batch-experiment.md`。解析器、CLI、文件适配器、profile 格式、图片资产打包和
-独立检查能力仍需分别设计；当前本地实验适配器不能被推导成这些公共接口已经获批。
+`research-wiki/explanation/local-experiment-artifacts.md`，本地评审器机制见
+`research-wiki/explanation/local-markdown-reviewer.md`。实验和评审器的实际操作分别见
+`research-wiki/guides/run-local-clindb-first-batch-experiment.md` 和 `research-wiki/guides/review-local-cleaning-run.md`。
+解析器、CLI、文件适配器、profile 格式、图片资产打包和独立检查能力仍需分别设计；当前本地实验适配器和评审器不能
+被推导成这些公共接口已经获批。
 
 ## 当前可用检查
 
@@ -155,6 +179,13 @@ python -m venv .venv
 .venv/bin/mypy src tests scripts/run_clindb_arxiv_experiment.py scripts/run_clindb_first_batch_experiment.py
 .venv/bin/pytest
 
+# 本地评审器要求 Node.js 24 LTS；安装依赖后依次执行静态检查、测试和生产构建
+cd reviewer
+nvm use
+npm ci
+npm run check
+cd ..
+
 # 两份 Agent 入口除标题外必须一致；无输出且退出码为 0 表示通过
 diff -u <(tail -n +2 AGENTS.md) <(tail -n +2 CLAUDE.md)
 
@@ -165,6 +196,8 @@ find research-wiki -maxdepth 2 -type f | sort
 git status --short
 ```
 
-上述安装和三项基础验收已于 2026-08-22 在 Python 3.13.11 环境实际运行：Ruff 通过，mypy 检查 37 个源码、
-测试和实验脚本文件无问题，pytest 共 204 项测试通过。`requires-python` 仍以 `pyproject.toml` 声明的 Python 3.11 及以上为准；
-本次结果不等于已经在每个受支持版本上完成兼容性验证。
+上述 Python 验收已于 2026-08-23 在 Python 3.13.11 环境实际运行：Ruff 通过，mypy 检查 43 个源码、测试和实验脚本文件
+无问题，pytest 共 229 项测试通过。评审器验收也在当前用户 nvm 的 Node.js 24.19.0 环境实际运行：ESLint 和 TypeScript
+通过，Vitest 共 6 项测试通过，生产构建成功；并以一批真实的 5 文档、8 组件、155 条修改产物验证了接口读取和逐阶段哈希。
+当前环境没有可用的图形浏览器，因此页面视觉布局尚未进行真实浏览器人工验收。`requires-python` 仍以
+`pyproject.toml` 声明的 Python 3.11 及以上为准；本次结果不等于已经在每个受支持版本上完成兼容性验证。