实现本地 Markdown 清洗评审器

.gitignore

@@ -9,6 +9,8 @@ __pycache__/
 dist/
 build/
 *.egg-info/
+reviewer/node_modules/
+reviewer/coverage/
 
 # Real documents and private datasets
 data/

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 类确定规则
+通用批处理或生产接口。评审前端也不是公共 Web 服务：它只绑定本机回环地址，只读展示 Markdown 源文和审计，不提供
-已经闭环，不能据此认为论文中的缺失内容、乱码、复杂表格、图片或 GovDoc 已具备完整清洗能力。
+渲染预览、在线编辑或重新清洗。当前 first-batch 实验脚本只固定运行已批准的 5 份论文和 8 个组件；它只能证明当前
+8 类确定规则已经闭环，不能据此认为论文中的缺失内容、乱码、复杂表格、图片或 GovDoc 已具备完整清洗能力。
 
 ## 服务对象与复用目标
 
@@ -46,8 +52,9 @@ GovDoc 目录、具体客户名称或某一转换器的固定输出路径。
 
 两组数据都不是可提交的自动测试 fixture。`data/` 已被 Git 忽略，清洗实验不得覆盖这些输入。
 
-本地清洗实验产物位于 `artifacts/<YYYY-MM-DD>/runs/<run_id>/`。产物可能包含完整原文，同样受 Git 忽略，
+本地清洗实验产物位于 `artifacts/<YYYY-MM-DD>/runs/<run_id>/`。产物可能包含完整原文；其中评审定位文件还包含
-默认保留 30 个日历日，不得提交或复制到外部系统。当前只批准为上述 5 份论文副本保存产物，未批准保存 GovDoc 输出。
+输入源的绝对路径，因此整个目录均受 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/explanation/local-experiment-artifacts.md`，本地评审器机制见
-`research-wiki/guides/run-local-clindb-first-batch-experiment.md`。解析器、CLI、文件适配器、profile 格式、图片资产打包和
+`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 个源码、
+上述 Python 验收已于 2026-08-23 在 Python 3.13.11 环境实际运行：Ruff 通过，mypy 检查 43 个源码、测试和实验脚本文件
-测试和实验脚本文件无问题，pytest 共 204 项测试通过。`requires-python` 仍以 `pyproject.toml` 声明的 Python 3.11 及以上为准；
+无问题，pytest 共 229 项测试通过。评审器验收也在当前用户 nvm 的 Node.js 24.19.0 环境实际运行：ESLint 和 TypeScript
-本次结果不等于已经在每个受支持版本上完成兼容性验证。
+通过，Vitest 共 6 项测试通过，生产构建成功；并以一批真实的 5 文档、8 组件、155 条修改产物验证了接口读取和逐阶段哈希。
+当前环境没有可用的图形浏览器，因此页面视觉布局尚未进行真实浏览器人工验收。`requires-python` 仍以
+`pyproject.toml` 声明的 Python 3.11 及以上为准；本次结果不等于已经在每个受支持版本上完成兼容性验证。

research-wiki/design/0007-local-markdown-reviewer.md

@@ -0,0 +1,480 @@
+# 0007：同仓库本地 Markdown 清洗评审器
+
+## 状态
+
+已批准并冻结（2026-08-23）。
+
+本设计已经用户明确批准，授权按第 16 节实施。后续契约或范围变化必须新增 design，不回写本文。
+
+`supersedes: 0005`（范围有限）：本文只替代 `0005` 中“不建设 Web 界面”和运行目录只有既有文件的选择，
+允许在本地实验层增加机器定位文件，并在同一仓库建立独立的只读评审器。`0005` 已确定的输入只读、成功输出边界、
+JSON 审计权威、原子发布、私有权限、30 日保留和真实数据限制继续有效。
+
+## 1. 问题与可观察现象
+
+当前本地实验已经为每份成功文档保存 `cleaned.md`、`result.json` 和 `changes.diff`。这些文件可以证明最终文本和逐项
+修改，但人工评审仍需要分别打开原文、清洗结果和 JSON，难以快速回答三个问题：
+
+1. 原文和最终清洗结果在整篇文档中有什么差异；
+2. 每个组件实际修改了什么、修改了多少处；
+3. 多个组件顺序执行时，某个组件看到的输入和它产生的输出分别是什么。
+
+现有运行层在预检时已经取得每份输入的绝对解析路径，在发布前也知道最终运行目录，但只把用于展示的
+`source_label` 和内容哈希写入清单。运行结束后，评审工具不能只靠运行目录找到完整原文；`changes.diff` 只有差异上下文，
+不能代替完整输入。
+
+`result.json` 中的 `Change.span` 又绑定各组件执行前的中间快照。它使用 Python 字符串下标，不能被浏览器当作 JavaScript
+字符串下标直接使用。前端如果自行猜测坐标或只把所有变化涂在最终文本上，可能把组件归属显示错。
+
+用户已经确定前端与 Python 核心放在同一个仓库，减少跨仓开发、评审和版本协调成本。这里的解耦目标因此不是物理分仓，
+而是保持依赖方向和数据契约清楚，使清洗核心与界面可以分别修改和验证。
+
+## 2. 目标与非目标
+
+### 2.1 目标
+
+- 在本仓库增加一个只服务本机的 Markdown 清洗评审器；
+- 同时展示一份成功文档的完整原文和完整清洗结果；
+- 按流水线顺序列出组件身份、版本和实际修改数量；
+- 选择组件后，准确展示该组件执行前后的 Markdown，而不是把中间坐标错误套到最终文本；
+- 点击修改时显示修改理由、位置、`before` 和 `after`；
+- 运行时记录最终运行目录和每份输入的本机路径，不复制或改写原文；
+- 读取前验证原文、产物和修改链哈希，验证失败时拒绝近似展示；
+- 让浏览器界面只依赖评审器内部的版本化 API，不依赖 Python 类、源码路径或 `TransformResult`；
+- 让报告生成和评审服务共用同一套 Python 快照重放逻辑，不在 TypeScript 中复制审计规则；
+- 前端代码、依赖和检查保存在独立子项目中，不进入 `mdpolish` Python 分发包。
+
+### 2.2 非目标
+
+- 不编辑 Markdown，不批准、拒绝或调整某条修改；
+- 不从页面重新运行清洗，不改变组件、参数或顺序；
+- 不原地覆盖输入，也不把页面状态写回运行目录；
+- 不建设远程服务、多人协作、账户、数据库、上传、分享或长期归档；
+- 不提供安装后的稳定公共 CLI、公共 HTTP API 或生产部署接口；
+- 第一版不渲染 Markdown、原始 HTML、图片或外部资源，只展示忠实的 Markdown 源文本；
+- 不为 `failed` 或 `unstable` 文档构造、保存或展示一份看似正式的完整输出；
+- 不改变清洗语义、组件版本、规则顺序、统计口径或核心数据模型；
+- 不增加 GovDoc 或其他仓库外真实数据的产物保存权限；
+- 不兼容任意历史或未来产物格式，第一版只读取本文明确批准的版本。
+
+源码视图是第一版的有意边界。当前规则包含换行、HTML 源码和精确字符修改，渲染后的页面可能隐藏这些变化；同时允许
+原始 HTML 和远程图片进入页面会扩大安全与数据泄露风险。以后确实需要渲染预览时，应单独决定 Markdown 方言、HTML
+净化、图片寻址和网络策略。
+
+## 3. 不改变的现有事实
+
+本文继续沿用以下权威：
+
+- `manifest.json` 仍是运行身份、环境、流水线、文档索引和汇总的权威；
+- `result.json` 仍是文档状态、修改、错误和残留候选的权威；
+- `cleaned.md` 仍是 `success` 文档最终文本的权威；
+- `changes.diff` 仍只是原文到最终成功输出的人工评审视图；
+- `failed` 和 `unstable` 文档没有 `cleaned.md`，评审器不得把重放得到的部分文本命名或展示为成功结果；
+- 所有产物继续位于 Git 忽略的 `artifacts/`，目录权限为 `0700`、文件权限为 `0600`，默认保留 30 个日历日；
+- 组件和内存核心继续不知道文件路径、运行目录、HTTP 或前端。
+
+本文不修改 `manifest.json` 和 `result.json` 的 `schema_version: 1`。本机路径进入独立定位文件，避免给已存在的审计字段
+增加未版本化含义。
+
+## 4. 方案比较
+
+### 4.1 前端直接导入或调用 `mdpolish`
+
+这种方式可以少写一层适配，但界面会依赖 Python 包布局、类和调用方式，浏览器也不能直接执行 Python。核心升级容易迫使
+前端同步修改。不采用。
+
+### 4.2 纯静态页面要求用户每次选择原文和所有产物
+
+不需要本地服务，但浏览器对本机路径有权限限制，不同浏览器的目录选择能力也不同。每次手工配对多份文档容易选错，且无法
+自然复用运行时已经验证过的路径。不采用为默认流程。
+
+### 4.3 打包为桌面应用
+
+桌面壳可以直接访问文件，但第一版会额外引入安装包、自动更新、签名和多平台问题，超过本地实验评审需要。不采用。
+
+### 4.4 独立前端加 Node.js 本地只读服务
+
+运行层只增加本机路径定位文件；评审器用独立适配器读取产物，校验后通过同源本地 API 提供给界面。前端不接触任意文件
+路径，也不理解 Python 对象。这能让评审器脱离 Python 独立运行，但必须在 TypeScript 中重新实现 Python 已有的组件分批、
+编辑排序、逐项原文验证和逐批哈希验证，还要持续处理 Python 码点与 JavaScript UTF-16 坐标的差异。
+
+哈希校验能阻止错误重放被静默展示，却不能消除两套实现的维护成本。第一版没有“把运行目录交给一台不含 Python 和
+`mdpolish` 的机器独立评审”的目标，因此不采用。
+
+### 4.5 独立前端加 Python 标准库本地只读服务
+
+Python 服务读取已经发布的文件契约，并通过一个从 `reporting.py` 提取的纯重放模块复核组件快照。报告生成和评审服务共用
+同一套应用顺序与哈希验证；服务再把完整阶段文本和派生的编辑器坐标通过同源本地 API 提供给前端。React/TypeScript
+只负责交互和展示，不解释 artifact，也不应用 Python span。
+
+采用此方案。它保留浏览器与核心对象之间的 API 边界，同时把风险最高的可信重放留在唯一的 Python 实现中。代价是启动
+评审器必须具有本仓库支持的 Python 环境和匹配版本的 `mdpolish`；这是第一版本地实验流程可以接受的约束。
+
+## 5. 总体结构与依赖方向
+
+```text
+显式 Markdown 输入
+        │
+        ▼
+mdpolish 本地实验层
+        │
+        ├── 既有 manifest / result / cleaned / diff
+        └── 新增 review-locator.json
+                         │
+                         ▼
+              Python 产物适配与重放服务
+                   │             │
+                   │             ├── 验证路径、哈希和状态
+                   │             └── 用共享 Python 逻辑重放组件快照
+                   ▼
+                 本地只读 API
+                         │
+                         ▼
+                 浏览器评审界面
+```
+
+依赖规则固定为：
+
+- `src/mdpolish/` 不导入 `reviewer/`；
+- `reporting.py` 和评审服务只共同依赖一个不读写文件的 Python 重放模块；
+- `reviewer/server/` 可以导入该重放模块，但不导入或调用组件、`Pipeline`、实验入口，也不重新运行清洗；
+- Python 产物适配器只读取已经发布的文件契约，不把内部模型当作 artifact 格式；
+- 前端组件只读取评审器 API，不读取磁盘，不解析 `manifest.json` 或 `result.json`；
+- Python 服务负责产物版本差异、组件快照重放和编辑器坐标派生，页面不维护第二套产物解释逻辑；
+- 评审器不成为 `mdpolish` wheel 的一部分。
+
+评审服务依赖共享重放模块是本文唯一批准的源码级连接。它用于消除两套可信重放实现，不允许扩展为从页面调用清洗核心。
+除此之外，同仓库只用于共享开发流程、提交历史和契约测试。
+
+## 6. 仓库结构与技术选择
+
+批准后允许新增以下结构：
+
+```text
+src/mdpolish/
+└── _artifact_replay.py          # 无文件 I/O 的共享快照重放逻辑
+reviewer/
+├── .nvmrc
+├── __init__.py
+├── server/                     # Python 标准库 HTTP 服务和产物版本适配器
+├── package.json
+├── package-lock.json
+├── tsconfig.json
+├── vite.config.ts
+├── src/
+│   ├── client/                 # React 浏览器界面，只依赖本地 API
+│   └── shared/                 # 前端使用的 API 类型和运行时校验
+└── tests/                      # 前端合成数据和界面测试
+tests/
+└── test_reviewer_*.py          # Python 产物适配、重放和服务测试
+```
+
+第一版采用：
+
+- 仓库现有 Python 环境运行本地只读服务；
+- Python 标准库实现 HTTP、文件读取和 JSON 解析，不增加 Python 运行依赖；
+- `_artifact_replay.py` 同时供 `reporting.py` 和评审服务调用，保持唯一的可信重放实现；
+- Node.js 24 LTS 只用于前端开发、测试和构建，不负责读取或重放 artifact；
+- TypeScript 表达前端 API 数据和界面类型；
+- React 构建交互界面；
+- Vite 提供开发与构建入口；
+- CodeMirror 6 Merge View 提供只读双栏文本比较；
+- Vitest 和 React Testing Library 覆盖前端 API 数据校验与主要界面状态。
+
+选择 React 与 Vite 是为了在一个独立目录内保留成熟的模块、类型和开发服务器，而不把 JavaScript 构建配置混入
+Python 包。[React 官方文档](https://react.dev/learn/build-a-react-app-from-scratch)把 Vite 列为从零建立客户端应用可用的
+构建工具；[Vite 官方文档](https://vite.dev/guide/features)说明它原生处理 TypeScript，但类型检查需要作为独立检查执行。
+[CodeMirror 的 Merge View](https://codemirror.net/docs/ref/#merge.MergeView)能直接比较两个文本并标记插入与删除，避免本项目
+自行实现文本 diff 编辑器。
+
+精确前端依赖版本只在 `reviewer/package.json` 和锁文件中维护，本文不复制版本清单。运行时不得从 CDN 下载脚本、字体、
+样式或其他资源。根据 [Node.js 官方版本状态](https://nodejs.org/en/about/previous-releases)，当前机器上的 Node.js 20 已结束
+官方支持，不能作为前端实现验收环境。
+
+批准本文同时授权实施者在当前用户已有的 nvm 中执行 `nvm install 24` 和 `nvm use 24`，在 `reviewer/.nvmrc` 固定主版本
+`24`，并在 `package.json` 的 `engines.node` 中限制为 Node.js 24。该授权不包括使用系统包管理器安装 Node.js、替换
+`/usr/bin/node` 或修改其他用户的环境；如果当前用户的 nvm 不可用，应停止并另行确认。
+
+## 7. 本机运行定位文件
+
+每次新实验在运行目录根部增加：
+
+```text
+artifacts/<run_date>/runs/<run_id>/review-locator.json
+```
+
+第一版结构固定为：
+
+```text
+schema_version
+run
+  run_id
+  run_directory
+  manifest_path
+documents[]
+  document_id
+  source_path
+  input_sha256
+```
+
+字段语义如下：
+
+- `schema_version` 固定为整数 `1`；
+- `run_id` 必须与 `manifest.json` 和目录身份一致；
+- `run_directory` 是运行发布时最终目录的绝对解析路径；
+- `manifest_path` 固定为相对路径 `manifest.json`；
+- `source_path` 是预检实际读取的普通文件的绝对解析路径，不保存调用方未解析的写法；
+- `input_sha256` 必须与对应 manifest、result 和预检字节一致；
+- 文档顺序必须与 manifest 一致。
+
+定位文件使用与现有 JSON 相同的 UTF-8、无 BOM、两空格缩进、保留 Unicode 和末尾换行规则，权限为 `0600`。它与其他
+文件一起写入临时运行目录、完成校验后原子发布；任一字段、写入或回读校验失败时不得发布最终运行目录。
+
+职责边界固定为：`experiment.py` 根据已预检的文档身份、解析后的源路径、输入哈希和 artifact store 计算的最终目标目录
+生成定位文件内容；`artifact_store.py` 不猜测或生成 `source_path` 等字段，只负责校验它与目标目录、manifest、result 的
+结构一致性，以及权限、写入、回读和原子发布。最终路径布局仍只由 artifact store 决定，不能在实验层复制日期目录规则。
+
+`review-locator.json` 只是本机寻址信息，不替代 manifest 或 result 的运行事实。绝对路径可能包含用户名和本机目录结构，
+因此它属于本地敏感产物，不得提交、推送、上传、复制到 Wiki 或显示在普通终端摘要中。
+
+评审器启动时由用户明确传入当前运行目录。若目录后来被移动，启动参数中的实际目录是读取产物的依据；定位文件中的
+`run_directory` 只用于提示位置已经变化，不能让服务跳转读取另一个运行目录。`source_path` 失效或哈希不符时，该文档原文
+标记为不可用，不能退化为按文件名搜索或继续展示不匹配内容。
+
+已有运行目录没有定位文件，仍然是合法的历史实验产物。第一版评审器可以展示其清单和审计，但不承诺自动找到完整原文，
+也不向历史目录补写定位文件。要进行完整双栏评审，应产生一次新的、具有不同运行 ID 的实验。
+
+## 8. 本地服务入口与边界
+
+评审器提供仓库内入口，概念调用方式为：
+
+```text
+python -m reviewer.server --run-dir <run_directory>
+```
+
+生产构建得到的静态页面由 Python 服务与 API 一起提供。开发时 Vite 可以通过同源代理连接同一个 Python API，但 Node 进程不读取
+artifact。精确的开发、构建和启动命令在实现并验证后只进入 README 的当前检查入口和对应 guide，不在多份文档维护不同
+写法。入口不安装到系统，也不承诺长期参数兼容。
+
+本地服务必须：
+
+- 只绑定 `127.0.0.1`，默认使用操作系统分配的空闲端口；
+- 只服务启动参数指定的一次运行，不扫描整个 `artifacts/`；
+- 只接受允许的 `GET` 和 `HEAD`，其他方法返回明确错误；
+- 不设置跨域许可，只接受本服务自身页面的同源请求；
+- 校验 `Host`，拒绝非本机目标和路径穿越；
+- 不提供任意文件路径读取接口；
+- 不提供写、删、移动、清理、重新运行或 shell 执行接口；
+- 对页面和 API 设置禁止缓存、内容类型保护和限制脚本来源的安全响应头；
+- 退出时不修改运行目录、原文或浏览器外的任何状态。
+
+服务读取的所有 artifact 相对路径都必须解析在启动运行目录内部。`source_path` 是唯一允许指向运行目录外的文件路径，且只在
+定位文件、manifest 和 result 的文档身份与哈希全部一致后读取。绝对源路径不返回给浏览器，页面只显示 `source_label`。
+
+## 9. 评审器内部 API
+
+浏览器只使用同源 `/api/v1/`。第一版至少提供三个只读资源：
+
+### 9.1 运行摘要
+
+返回运行身份、状态、组件顺序、文档索引和汇总计数，并为每份文档说明原文和成功输出是否可用。它不返回绝对路径、Git
+仓库路径或整篇 Markdown。
+
+### 9.2 文档比较
+
+对 `success` 文档返回：
+
+- 完整且通过哈希验证的原始 Markdown；
+- 完整且通过哈希验证的 `cleaned.md`；
+- 文档状态、前后哈希和总修改数量；
+- 按组件位置分组的修改数量；
+- 每条修改的组件、版本、理由、派生行列、`before` 和 `after`；
+- 由服务端根据对应组件前快照派生的 UTF-16 `editor_range`，只用于 CodeMirror 定位，不作为修改权威。
+
+对 `failed` 和 `unstable` 文档只返回状态、已有审计、错误和残留候选，不返回或重建一份完整部分输出。原文可以作为只读
+诊断背景返回，但页面必须明确该文档没有正式成功结果。
+
+### 9.3 组件阶段比较
+
+只对 `success` 文档提供。调用方按 `component_position` 请求一个组件，服务返回该组件执行前和执行后的完整 Markdown、
+组件元数据和属于该组件的实际修改。零修改组件也返回相同的前后文本和零计数，使流水线顺序完整可见。
+
+这是评审器内部契约，不是面向其他项目的公共 API。服务端和前端同属 `reviewer/`，字段改变仍需同步类型、运行时校验和
+测试；不得让页面回退为直接读取磁盘 JSON。
+
+## 10. 中间快照重放与编辑器坐标
+
+组件阶段视图必须从已验证原文按实际 `Change` 重放，不保存新的中间 Markdown 文件。`manifest.pipeline.components[]`
+是完整组件顺序的权威，`result.json.changes[]` 只记录实际发生的修改。对 `success` 文档，服务按以下规则处理：
+
+1. 从 manifest 的第一个组件开始按位置遍历，先验证 `changes[]` 中的组件位置不倒退、同一位置连续出现，并且组件身份和
+   版本与 manifest 对应项一致；
+2. 收集当前位置的全部 `Change`。没有 Change 时，该组件仍形成一个合法的零修改阶段：前后文本都等于当前重放文本，
+   修改数为零，不要求或伪造不存在的批次哈希；
+3. 有 Change 时，要求该位置所有记录具有相同的 `before_sha256` 和 `after_sha256`，并验证当前文本哈希等于
+   `before_sha256`；
+4. 逐项验证 Python 码点范围合法，且当前范围文字等于 `before`；
+5. 按 `(span.start, span.end, proposal_index, edit_index)` 降序应用该组件的编辑。范围已经由核心冲突契约保证互不冲突，
+   完整排序键用于保持与现有 Python 执行器一致和结果确定；artifact 的记录顺序不是应用顺序；
+6. 验证批次结果哈希等于 `after_sha256`，再把该阶段的前后文本和修改交给 API；
+7. 全部 manifest 组件结束后，验证结果字节和哈希分别等于 `cleaned.md` 与 `current_sha256`。
+
+因此，对 `success` 文档，“manifest 中存在、该位置没有 Change”明确表示组件运行过但没有修改；manifest 中没有该位置才是
+组件缺失。`failed` 和 `unstable` 不能仅凭 manifest 推断全部组件已经运行，服务不为它们建立完整组件阶段链。
+
+共享重放模块直接使用 Python 码点范围，不进行跨语言应用。为了让 CodeMirror 跳转，Python 服务在已经验证的组件前快照上
+另外计算零起始、半开区间的 UTF-16 code unit `editor_range`。该范围只是 API 派生视图；前端不得用它重新应用修改，
+`result.json` 的 Python span 仍是审计权威。
+
+严格 UTF-8 输入不会包含无法重新编码的孤立代理项。仍需用包含中文、补充平面字符、组合字符、BOM、CRLF 和无末尾换行的
+合成测试证明服务返回的 UTF-16 范围能准确定位对应 `before`。
+
+任一步失败都把该文档标记为“产物无法可信重放”，不生成组件阶段数据，不用文本搜索、diff 猜测或跳过错误继续展示。
+`residual_proposals` 只显示为最终复查证据，绝不应用。
+
+## 11. 第一版界面行为
+
+第一版页面分为三个区域：
+
+1. 运行与文档列表：显示整体状态、文档状态、前后哈希和修改数量；
+2. 主双栏：只读展示完整原文与最终成功 Markdown，支持差异标记、行号和联动滚动；
+3. 组件侧栏：按实际流水线顺序显示组件标识、版本和修改数，选择后把主双栏切换为该组件执行前后视图。
+
+修改详情显示理由、修改前位置、`before` 和 `after`；点击后跳转到对应组件阶段的差异位置。同一个候选修改中的多条编辑应
+继续用 `proposal_ref` 关联，不能把一项多位置动作错误显示为互不相关的业务问题。
+
+页面必须清楚区分：
+
+- 总修改数量是实际 `Change` 条数，不是 unified diff hunk 数、问题数或修改字符数；
+- `success` 只表示选中组件运行稳定，不表示文档没有其他问题；
+- `failed` / `unstable` 没有正式清洗结果；
+- 零修改组件确实运行过，与组件缺失不是同一状态；
+- 原文路径失效、哈希变化和产物损坏属于不同错误。
+
+第一版以桌面浏览器评审为主，但键盘应能切换文档、组件和修改，状态不能只依赖颜色表达。页面不提供编辑控件、文件拖放、
+远程链接预览或任何会修改外部状态的按钮。
+
+## 12. 版本兼容策略
+
+第一版支持：
+
+- `manifest.json` schema `1`；
+- `result.json` schema `1`；
+- `review-locator.json` schema `1`；
+- 评审器内部 API `/api/v1/`。
+
+遇到未知 schema 时必须说明不支持的文件和版本并拒绝读取，不能忽略版本继续猜测。以后 mdpolish 产物升级时，在
+`reviewer/server/` 增加明确的 Python 版本适配器；前端仍只使用统一内部 API。只有无法保持原含义时才升级 API 版本。
+
+Python 核心和前端因此可以在同一仓库分别演进，但“任意核心变化都无需调整评审器”不是目标。真正保证的是：变化集中在
+文件契约适配器，并由兼容性测试暴露，不让内部类或目录变化直接扩散到页面。
+
+## 13. 隐私与数据安全
+
+- 定位文件、原文、成功 Markdown、diff 和审计继续按本地敏感数据处理；
+- 页面和本地 API 不包含遥测、错误上报、CDN、远程字体或自动更新请求；
+- 浏览器运行时只允许连接同源本地服务；
+- Markdown 只作为文本交给只读编辑器，不注入 `innerHTML`；
+- 服务不输出原文、diff、绝对源路径或 `before` / `after` 到终端日志；
+- 关闭页面或服务不删除缓存以外的任何文件，也不改变 30 日保留规则；
+- 定位文件不得解除 Git 忽略，不得进入测试 fixture；自动测试只使用虚构 Markdown 和临时目录。
+
+本设计没有因为增加页面而扩大真实数据授权。当前仍只允许对 `data/md/` 中现有 5 份论文副本保存实验产物；
+`/home/lihaoze/gov_test_data` 及其他外部真实材料继续只读且不得生成本项目产物。
+
+## 14. 测试与验收
+
+### 14.1 Python 实验层与 artifact store
+
+至少覆盖：
+
+- 定位文件记录实际最终运行目录、解析后的源路径、文档顺序和输入哈希；
+- 实验层生成定位内容，artifact store 不自行推断源路径；
+- 定位文件、manifest 和 result 的身份或哈希不一致时拒绝发布；
+- 定位文件使用批准的 JSON 编码和 `0600` 权限；
+- 任一定位文件写入、回读或校验失败时不发布最终运行目录；
+- 输入路径和文件内容在运行前后不变；
+- `failed` / `unstable` 仍不产生 `cleaned.md`；
+- 既有 manifest 和 result schema 不被静默改变。
+
+### 14.2 Python 重放、产物适配器与服务
+
+合成测试至少覆盖：
+
+- 合法 `success`、`failed` 和 `unstable` 产物；
+- 缺失、未知版本、非法 JSON、BOM、错误编码和路径穿越；
+- 源文件缺失、不是普通文件、哈希改变或身份不匹配；
+- cleaned 哈希不符、修改原文不符和中间快照链断裂；
+- 报告生成和评审服务对同一合成修改链得到完全相同的中间与最终文本；
+- 精确按 `(span.start, span.end, proposal_index, edit_index)` 降序应用，不把 artifact 记录顺序当作应用顺序；
+- 中文、补充平面字符、组合字符、CRLF、空文档和无末尾换行的快照重放及 UTF-16 编辑器范围；
+- 多组件、首个/中间/末尾零修改组件、空流水线、一个候选多编辑和后续组件基于新快照修改；
+- manifest 中缺失组件与合法零修改组件能被区分，倒序、非连续重复或身份不匹配的组件批次被拒绝；
+- 未知文档和组件位置返回明确错误；
+- 非 GET/HEAD 方法、非本机 Host、跨域和任意路径读取被拒绝；
+- API 不泄露绝对源路径，并包含禁止缓存和内容类型保护头。
+
+### 14.3 前端
+
+至少覆盖：
+
+- 运行和文档状态列表；
+- 原文与成功结果双栏；
+- 组件顺序、版本、零修改和修改数量；
+- 组件视图切换、修改详情和跳转；
+- `failed` / `unstable` 不显示正式结果；
+- 路径失效、哈希不符、产物损坏和未知 schema 的清楚错误；
+- 不把 Markdown 当 HTML 执行；
+- 键盘操作和不依赖颜色的状态表达。
+
+评审器检查至少包括 Python 的 Ruff、mypy 和 pytest，以及前端 TypeScript 类型检查、lint、单元/组件测试和生产构建。
+精确命令和依赖版本在实现后进入各自唯一权威；根目录 README 只记录当前真实可用的总体验收入口。
+
+### 14.4 本地 5 份论文验收
+
+实现和合成测试通过后，允许使用新的运行 ID 对 `data/md/` 中 5 份本地论文副本再次运行已批准的第一批流水线，并验证：
+
+1. 定位文件列出 5 份输入，路径和哈希正确，输入字节不变；
+2. 页面列出 8 个组件及其实际顺序和版本；
+3. 5 份文档都能同时打开原文和成功输出；
+4. 页面总修改数与 manifest、result 一致；
+5. 每个组件阶段都能重放到正确前后哈希，零修改组件显示为零而不是缺失；
+6. JAMA Abstract 前内容、Springer 合法 arXiv 引用和图片引用文字等既有反例仍保持不变；
+7. 浏览器和终端不发生外部网络请求，不输出真实文本或绝对源路径；
+8. 新运行仍只位于 Git 忽略的 `artifacts/`，权限和保留日期符合 `0005`。
+
+这一验收只证明当前 5 份论文和既有 8 个组件能够被本地评审，不表示通用数据集、GovDoc 或生产部署已经支持。
+
+## 15. 风险与代价
+
+- **评审服务依赖本仓库 Python 环境：** 它换来唯一的可信重放实现，但不能在只有静态产物和 Node.js 的机器上独立启动；
+- **共享 Python 模块仍是源码耦合点：** 依赖只限纯重放函数，并用报告与评审一致性测试控制，不能扩展到组件或流水线；
+- **绝对路径会泄露本机结构并可能失效：** 路径只进入私有定位文件，移动后明确报错，不把路径当可移植身份；
+- **新增 Node.js 工具链：** Node.js 只用于前端开发和构建，但仓库仍需要第二套受支持环境和锁文件；
+- **编辑器坐标仍有跨语言差异：** Python 服务派生并测试 UTF-16 范围；坐标错误只能影响跳转，不能改变已经在 Python 中完成并
+  验证哈希的阶段文本；
+- **完整文本会占用浏览器内存：** 第一版面向当前本地实验，不宣称支持任意极端长度；出现真实瓶颈后再设计流式读取或虚拟化；
+- **源码视图不能展示最终排版：** 它优先保证修改证据忠实；渲染预览另行处理安全、方言和资源边界；
+- **本地 HTTP 仍有攻击面：** 仅回环监听、同源、Host 校验、无写接口和严格路径白名单共同缩小范围；
+- **旧运行无法自动双栏：** 不回写历史或猜测路径，代价是完整查看需要重新产生带定位文件的新运行。
+
+## 16. 批准后的实施边界
+
+批准本文只授权：
+
+1. 由现有实验层生成 `review-locator.json` 内容，由 artifact store 校验、写入、回读并随运行目录原子发布；
+2. 从 `reporting.py` 提取第 10 节所需的纯 Python 重放逻辑，并由报告生成和评审服务共同调用；
+3. 创建第 6 节列出的 Python 服务、前端子项目、锁文件、合成测试和构建配置；
+4. 实现第 8 至 11 节的本地只读 API、产物适配、双栏源码比较和组件阶段视图；
+5. 在当前用户已有的 nvm 中安装和使用 Node.js 24，并新增 `reviewer/.nvmrc` 和 `package.json` 的版本限制；
+6. 在 `.gitignore` 中忽略评审器构建、依赖和覆盖率产物；
+7. 更新根目录 README 当前能力与实际检查入口，并新增对应 explanation 和经验证 guide；
+8. 在合成测试通过后，按第 14.4 节对本地 5 份论文副本产生一次新的私有运行并完成只读页面验收。
+
+批准不授权：
+
+- 改变清洗规则、组件顺序、核心模型或既有 JSON schema；
+- 修改、覆盖、移动或复制任何输入 Markdown；
+- 为 GovDoc 或其他仓库外数据生成产物；
+- 实现 Markdown/HTML 渲染、图片访问、编辑、审核、回写、远程服务、认证或数据库；
+- 修改系统级 Node.js 安装，提交、推送、创建 PR 或发布。

research-wiki/explanation/local-experiment-artifacts.md

@@ -12,21 +12,30 @@
 - 只有 `success` 文档才产生正式的清洗后 Markdown。
 
 已经实现的范围来自已批准的
-[`0005-local-experiment-runner-and-artifacts.md`](../design/0005-local-experiment-runner-and-artifacts.md)。
+[`0005-local-experiment-runner-and-artifacts.md`](../design/0005-local-experiment-runner-and-artifacts.md) 和
+[`0007-local-markdown-reviewer.md`](../design/0007-local-markdown-reviewer.md)。
 精确字段、校验和函数签名以 `src/mdpolish/` 中的代码与测试为准。
 
-## 2. 三层怎样解耦
+## 2. 保存与评审怎样解耦
 
 ```text
 experiment.py
 ├── pipeline.py          只负责内存清洗
 ├── reporting.py         只负责 JSON、行列和 unified diff
 └── artifact_store.py    只负责日期目录、权限和原子发布
+            │
+            ▼
+      已发布运行目录
+            │
+            ▼
+reviewer/                 只通过发布后的文件做本地只读评审
 ```
 
 - `experiment.py` 严格读取调用方显式列出的 UTF-8 Markdown，逐份调用同一个 `Pipeline`；
 - `reporting.py` 重放并校验 `Change` 的快照链，再生成机器可读审计和人可读 diff；
 - `artifact_store.py` 不理解清洗规则，只把已经生成的字节写入私有临时目录，校验后一次性发布。
+- 同仓库 `reviewer/server/` 只共用无文件 I/O 的 Python 快照重放模块，不导入组件或流水线；它读取 manifest、result、
+  成功输出和本机定位文件。
 
 因此，新增组件不会改变文件层；调整目录布局不会影响清洗和报告；修改 JSON 或 diff 时也不需要碰流水线。
 ClinDB 的 5 份论文、历史 arXiv 单组件组合和当前 first-batch 组合只存在于两个仓库内实验脚本，通用模块没有硬编码
@@ -71,6 +80,7 @@ artifacts/
     └── runs/
         └── <run_id>/
             ├── manifest.json
+            ├── review-locator.json
             └── documents/
                 └── <document_id>/
                     ├── result.json
@@ -95,6 +105,9 @@ artifacts/
 `changes.diff` 是原始输入到最终成功输出的 unified diff，只用于人工查看。它不包含绝对路径或时间戳，
 也不是修改重放的权威；机器审计仍以 `result.json` 为准。
 
+`review-locator.json` 只记录本次运行目录、每份输入的绝对解析路径和输入哈希，供本地评审器重新找到完整原文。它不复制
+原文，不替代 manifest 或 result，也不作为可移植运行身份。绝对路径可能泄露本机目录结构，因此该文件同样是本地敏感数据。
+
 ## 6. 为什么 reporter 要重放修改
 
 第二个组件看到的是第一个组件修改后的快照，因此后续 `Change.span` 不一定对应最初输入。为了生成准确行列，
@@ -137,6 +150,9 @@ artifact store 先在同一日期的 `runs/` 下建立本次专用临时目录
 
 当前只批准对 `data/md/` 中 5 份论文副本保存产物。仓库外 GovDoc 和其他真实数据没有因此获得输出授权。
 
+同仓库只读页面的路径验证、组件快照重放和使用边界见
+[`local-markdown-reviewer.md`](local-markdown-reviewer.md)。
+
 ## 9. 已完成的真实验证
 
 2026-08-22 使用 `paper.arxiv_submission_stamp` `1.0.0` 对 5 份本地论文副本完成一次保存型实验：
@@ -173,3 +189,7 @@ artifact store 先在同一日期的 `runs/` 下建立本次专用临时目录
 当前完整运行方法见
 [`run-local-clindb-first-batch-experiment.md`](../guides/run-local-clindb-first-batch-experiment.md)。实验层的文件、
 JSON、diff 和权限契约没有因组件增多而改变。
+
+2026-08-23 又产生运行 `clindb-first-batch-reviewer-v1`，用于验证新定位文件和本地页面：5/5 文档为 `success`，合计
+155 条修改，输入运行前后哈希不变。评审器 API 校验了 5 份原文、成功输出以及 8 个组件形成的 40 个阶段，所有文本哈希
+均与审计一致。实际页面启动步骤见 [`review-local-cleaning-run.md`](../guides/review-local-cleaning-run.md)。

research-wiki/explanation/local-markdown-reviewer.md

@@ -0,0 +1,109 @@
+# 本地 Markdown 清洗评审器如何保持只读和可追踪
+
+## 1. 它解决什么问题
+
+本地清洗实验已经保存最终 Markdown、逐条审计和 unified diff，但人工评审仍需要在多个文件之间切换，也看不到某个组件
+执行前后的完整文本。当前评审器把一次已发布运行变成只读页面：主视图比较原文和最终成功输出，组件时间线则比较每个
+组件实际收到的快照和它产生的新快照。
+
+实现范围来自已批准的
+[`0007-local-markdown-reviewer.md`](../design/0007-local-markdown-reviewer.md)。精确 API、字段和运行行为以
+[`reviewer/`](../../reviewer/) 中的代码、类型和测试为准。
+
+## 2. 同仓库怎样保持解耦
+
+```text
+mdpolish 本地实验层
+        │
+        ▼
+manifest / result / cleaned / review-locator
+        │
+        ▼
+Python 产物适配器与共享重放 ──► 本地只读 API ──► React 页面
+```
+
+- `src/mdpolish/` 不导入 `reviewer/`；
+- `reviewer/server/` 只从 `mdpolish` 导入无文件 I/O 的 `_artifact_replay.py`，不导入组件、流水线或实验入口；
+- 浏览器只读取 `/api/v1/`，不解析磁盘 JSON，也不知道绝对路径；
+- Python wheel 不包含前端代码或 Node.js 依赖；
+- 产物 schema 以后改变时，差异集中在服务端版本适配器，不扩散到页面组件。
+
+前端与核心位于同一 Git 仓库，方便开发和评审，但仍是独立的 Node.js package。依赖版本只在
+[`reviewer/package.json`](../../reviewer/package.json) 和锁文件维护。
+
+## 3. 运行定位文件保存什么
+
+新实验会在运行目录根部原子保存 `review-locator.json`。它记录：
+
+- 运行 ID 和发布时的绝对运行目录；
+- `manifest.json` 的固定相对位置；
+- 每份文档的 ID、实际读取的绝对源路径和输入 SHA-256。
+
+定位文件不复制原文，也不替代 manifest 或 result。评审器由用户显式指定当前运行目录；记录的旧运行目录只用于判断目录
+是否被移动。服务只根据定位文件读取对应原文，并在每次展示前重新计算哈希。源文件不存在或内容变化时，页面明确报告
+不可用，不按名称搜索替代文件。
+
+绝对路径会暴露本机目录结构，所以定位文件与其他 artifact 一样使用 `0600` 权限并按本地敏感数据处理。历史运行没有该
+文件时仍可查看清单和局部审计，但不能自动展示完整原文；评审器不会回写历史目录。
+
+## 4. 服务为什么只读取一次运行
+
+启动时必须传入一个具体运行目录。服务不会扫描 `artifacts/`，也没有让浏览器传入任意文件路径的 API。它先校验：
+
+1. manifest、result 和存在的 locator 都是支持的 schema、严格 UTF-8 JSON；
+2. 文档、组件、状态、路径和计数彼此一致；
+3. 所有 artifact 路径都留在所选运行目录；
+4. 原文和成功输出的字节哈希与审计一致；
+5. 成功文档确实同时具有 `cleaned.md` 和 `changes.diff`。
+
+HTTP 只监听 `127.0.0.1` 的随机空闲端口，只接受 `GET` 和 `HEAD`。服务拒绝非本机 Host、跨域 Origin、路径穿越和
+写请求，不提供删除、移动、重新清洗或 shell 执行能力。响应禁止缓存，不开放 CORS，也不向浏览器返回绝对源路径。
+
+## 5. 组件阶段怎样准确重放
+
+`Change.span` 使用 Python Unicode 码点位置，而 JavaScript 编辑器使用 UTF-16 code unit。共享 Python 重放模块直接按
+原生码点范围逐组件处理，不让浏览器应用修改：
+
+1. 当前完整文本哈希必须等于组件批次的 `before_sha256`；
+2. 每条范围内文本必须等于 `before`；
+3. 同一批次不得有冲突范围，并按位置从后向前应用；
+4. 应用后完整文本哈希必须等于 `after_sha256`；
+5. 全部组件结束后必须逐字等于 `cleaned.md`；
+6. 服务端另外从已验证的组件前快照派生 UTF-16 `editor_range`，只供 CodeMirror 跳转。
+
+组件没有修改时，阶段前后文本和哈希相同，但该组件仍显示在时间线中。包含中文、emoji、组合字符、BOM、CRLF 和无末尾
+换行的合成测试用于保护跨语言坐标。任一重放校验失败时，页面拒绝显示组件阶段，不通过搜索或 diff 猜测位置。
+
+中间快照只在服务内存中按需生成，不保存新的 Markdown 文件。`failed` 和 `unstable` 文档只显示错误、残留候选和已有的
+局部审计，不重建一份看似正式的部分输出。
+
+## 6. 页面当前能看什么
+
+页面当前提供：
+
+- 运行状态、文档状态、哈希和实际 `Change` 数量；
+- 完整原文与最终成功 Markdown 的只读双栏源码比较；
+- 8 个组件的实际顺序、版本和每份文档修改数量；
+- 任一组件执行前后的完整文本比较；
+- 修改理由、派生行列、`before` / `after` 和同候选修改关联；
+- `failed`、`unstable`、路径失效、哈希变化和未知 schema 的独立错误状态。
+
+Markdown 只作为文本交给 CodeMirror，不进入 `innerHTML`。第一版不渲染 Markdown、HTML 或图片，不加载 CDN、远程字体、
+遥测和其他外部资源，也不提供编辑、审核或回写。
+
+## 7. 当前验证结果和边界
+
+2026-08-23 使用 Python 3.13.11 和当前用户 nvm 中的 Node.js 24.19.0 完成：
+
+- Python Ruff、mypy 和 229 项 pytest 通过；
+- reviewer ESLint、TypeScript、6 项 Vitest 和生产构建通过；
+- 新运行 `clindb-first-batch-reviewer-v1` 的 5 份论文全部 `success`，共 155 条实际修改；
+- 5 份原文运行前后哈希不变；
+- 本地 API 成功校验 5 份文档、8 个组件和 40 个组件阶段；
+- 所有原文、成功输出和阶段前后文本的 SHA-256 与运行审计一致；
+- 生产页面和全部本地构建资源可以通过只读服务读取，响应没有 CORS 并包含禁止缓存和内容类型保护头。
+
+当前环境没有可用于自动视觉检查的本地浏览器，因此布局的真实浏览器视觉效果尚未验证。当前结果证明构建、服务、数据
+重放和主要 React 状态可以运行，不等于已经完成跨浏览器、极端长度、渲染预览或生产部署验证。
+
+实际启动与评审步骤见 [`review-local-cleaning-run.md`](../guides/review-local-cleaning-run.md)。

research-wiki/guides/review-local-cleaning-run.md

@@ -0,0 +1,127 @@
+# 使用本地页面评审一次 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` 管理；页面不会自动删除到期产物。

research-wiki/guides/run-local-clindb-first-batch-experiment.md

@@ -10,7 +10,7 @@
 - 输入只读，不覆盖原文件；
 - 不读取或复制图片，不处理 `/home/lihaoze/gov_test_data`。
 
-本指南于 2026-08-22 在 Python 3.13.11 环境实际验证。
+本指南于 2026-08-23 在 Python 3.13.11 环境实际验证。
 
 ## 2. 前置检查
 
@@ -24,7 +24,7 @@
 diff -u <(tail -n +2 AGENTS.md) <(tail -n +2 CLAUDE.md)
 ```
 
-当前已验证结果是 Ruff 通过、mypy 37 个文件无问题、pytest 204 项通过。再确认 5 份输入存在：
+当前检查结果只以根目录 [`README.md`](../../README.md#当前可用检查) 为准。检查通过后再确认 5 份输入存在：
 
 ```bash
 find data/md -maxdepth 1 -type f -name '*.md' -printf '%f\n' | sort
@@ -55,7 +55,8 @@ artifacts=/.../mdpolish/artifacts/<YYYY-MM-DD>/runs/clindb-first-batch-review
 
 ## 4. 先看哪些结果
 
-先打开运行目录的 `manifest.json`，确认：
+先确认运行目录根部同时存在 `manifest.json` 和 `review-locator.json`。定位文件只供本机评审器寻找原文，包含绝对路径，
+不得提交或分享。然后打开 `manifest.json`，确认：
 
 - `run.status` 是 `success`；
 - `summary.document_count` 和 `summary.success_count` 都是 5；
@@ -144,3 +145,6 @@ sha256sum data/md/*.md
 其他仓库、云存储或外部系统。
 
 `manifest.json` 中的 `retention_until` 是默认 30 天到期时间。当前不自动删除；到期后如需清理，必须先确认具体运行目录。
+
+需要在只读页面中查看完整前后文和各组件阶段时，继续按
+[`review-local-cleaning-run.md`](review-local-cleaning-run.md) 操作。

reviewer/.nvmrc

@@ -0,0 +1 @@
+24

reviewer/__init__.py

@@ -0,0 +1 @@
+"""Repository-local Markdown cleaning reviewer."""

reviewer/eslint.config.js

@@ -0,0 +1,40 @@
+import eslint from "@eslint/js";
+import reactHooks from "eslint-plugin-react-hooks";
+import reactRefresh from "eslint-plugin-react-refresh";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  { ignores: ["dist", "coverage", "node_modules"] },
+  eslint.configs.recommended,
+  ...tseslint.configs.strictTypeChecked,
+  ...tseslint.configs.stylisticTypeChecked,
+  {
+    files: ["**/*.{ts,tsx}"],
+    languageOptions: {
+      globals: { ...globals.browser, ...globals.node },
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    plugins: {
+      "react-hooks": reactHooks,
+      "react-refresh": reactRefresh,
+    },
+    rules: {
+      ...reactHooks.configs.flat.recommended.rules,
+      "react-refresh/only-export-components": ["warn", { allowConstantExport: true }],
+      "@typescript-eslint/consistent-type-definitions": ["error", "interface"],
+      "@typescript-eslint/no-confusing-void-expression": "off",
+      "@typescript-eslint/restrict-template-expressions": ["error", { allowNumber: true }],
+      "react-hooks/set-state-in-effect": "off",
+    },
+  },
+  {
+    files: ["tests/**/*.{ts,tsx}"],
+    rules: {
+      "@typescript-eslint/no-non-null-assertion": "off",
+    },
+  },
+);

reviewer/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="light" />
+    <title>mdpolish 评审器</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/client/main.tsx"></script>
+  </body>
+</html>

reviewer/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "mdpolish-reviewer",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": "^24.0.0"
+  },
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "build": "npm run typecheck && vite build",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "eslint src tests vite.config.ts",
+    "test": "vitest run",
+    "check": "npm run lint && npm run test && npm run build"
+  },
+  "dependencies": {
+    "@codemirror/lang-markdown": "6.5.2",
+    "@codemirror/merge": "6.12.2",
+    "@codemirror/state": "6.7.1",
+    "@codemirror/view": "6.43.9",
+    "react": "19.2.8",
+    "react-dom": "19.2.8"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@testing-library/jest-dom": "7.0.1",
+    "@testing-library/react": "16.3.2",
+    "@types/node": "24.13.3",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.4",
+    "@vitejs/plugin-react": "6.1.0",
+    "eslint": "10.9.0",
+    "eslint-plugin-react-hooks": "7.1.1",
+    "eslint-plugin-react-refresh": "0.5.4",
+    "globals": "17.11.0",
+    "jsdom": "30.0.1",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.67.0",
+    "vite": "8.2.2",
+    "vitest": "4.1.11"
+  }
+}

reviewer/server/__init__.py

@@ -0,0 +1,5 @@
+"""Read-only artifact adapter and local HTTP service."""
+
+from reviewer.server.artifacts import ReviewArtifactError, ReviewArtifacts
+
+__all__ = ["ReviewArtifactError", "ReviewArtifacts"]

reviewer/server/__main__.py

@@ -0,0 +1,233 @@
+"""Serve one local review run through a loopback-only read-only HTTP API."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import mimetypes
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any
+from urllib.parse import unquote, urlsplit
+
+from reviewer.server.artifacts import JsonObject, ReviewArtifactError, ReviewArtifacts
+
+_SECURITY_HEADERS = {
+    "Cache-Control": "no-store",
+    "Content-Security-Policy": (
+        "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'none'; "
+        "font-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'"
+    ),
+    "Referrer-Policy": "no-referrer",
+    "X-Content-Type-Options": "nosniff",
+    "X-Frame-Options": "DENY",
+}
+
+
+class ReviewerHttpServer(ThreadingHTTPServer):
+    """Threaded local server whose workers never keep process shutdown alive."""
+
+    daemon_threads = True
+
+
+def _valid_local_request(handler: BaseHTTPRequestHandler) -> bool:
+    host = handler.headers.get("Host")
+    if host is None:
+        return False
+    try:
+        parsed_host = urlsplit(f"//{host}")
+        if parsed_host.username is not None or parsed_host.password is not None:
+            return False
+        if parsed_host.hostname not in {"127.0.0.1", "localhost"}:
+            return False
+        if parsed_host.port is not None and not 0 < parsed_host.port < 65536:
+            return False
+    except ValueError:
+        return False
+
+    origin = handler.headers.get("Origin")
+    if origin is None:
+        return True
+    try:
+        parsed_origin = urlsplit(origin)
+        return parsed_origin.scheme == "http" and parsed_origin.netloc == host
+    except ValueError:
+        return False
+
+
+def _api_response(repository: ReviewArtifacts, path: str) -> JsonObject:
+    if path == "/api/v1/run":
+        return repository.run_summary()
+    parts = [part for part in path.split("/") if part]
+    try:
+        if len(parts) == 4 and parts[:3] == ["api", "v1", "documents"]:
+            return repository.document_comparison(unquote(parts[3], encoding="utf-8", errors="strict"))
+        if len(parts) == 6 and parts[:3] == ["api", "v1", "documents"] and parts[4] == "components":
+            document_id = unquote(parts[3], encoding="utf-8", errors="strict")
+            try:
+                component_position = int(parts[5])
+            except ValueError:
+                raise ReviewArtifactError("unknown_component", "组件位置不存在。", 404) from None
+            return repository.component_stage(document_id, component_position)
+    except UnicodeDecodeError:
+        raise ReviewArtifactError("not_found", "请求的资源不存在。", 404) from None
+    raise ReviewArtifactError("not_found", "请求的资源不存在。", 404)
+
+
+def _handler_factory(repository: ReviewArtifacts, static_root: Path) -> type[BaseHTTPRequestHandler]:
+    class ReviewRequestHandler(BaseHTTPRequestHandler):
+        server_version = "mdpolish-reviewer"
+        sys_version = ""
+
+        def log_message(self, format_: str, *args: Any) -> None:
+            del format_, args
+
+        def _headers(self, status: int, content_type: str, content_length: int) -> None:
+            self.send_response(status)
+            for name, value in _SECURITY_HEADERS.items():
+                self.send_header(name, value)
+            self.send_header("Content-Type", content_type)
+            self.send_header("Content-Length", str(content_length))
+            self.end_headers()
+
+        def _json(self, status: int, payload: JsonObject, *, head_only: bool) -> None:
+            content = (json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n").encode()
+            self._headers(status, "application/json; charset=utf-8", len(content))
+            if not head_only:
+                self.wfile.write(content)
+
+        def _error(self, error: Exception, *, head_only: bool) -> None:
+            if isinstance(error, ReviewArtifactError):
+                status = error.http_status
+                code = error.code
+                message = str(error)
+            else:
+                status = 500
+                code = "internal_error"
+                message = "评审器无法完成该请求。"
+            self._json(status, {"error": {"code": code, "message": message}}, head_only=head_only)
+
+        def _static(self, path: str, *, head_only: bool) -> None:
+            requested = "index.html" if path == "/" else unquote(path[1:], encoding="utf-8", errors="strict")
+            if "\0" in requested:
+                raise ReviewArtifactError("not_found", "请求的资源不存在。", 404)
+            candidate = static_root / requested
+            try:
+                if candidate.is_symlink():
+                    raise ReviewArtifactError("not_found", "请求的资源不存在。", 404)
+                resolved = candidate.resolve(strict=True)
+                if not resolved.is_relative_to(static_root) or not resolved.is_file():
+                    raise FileNotFoundError
+            except (FileNotFoundError, OSError):
+                if Path(requested).suffix:
+                    raise ReviewArtifactError("not_found", "请求的资源不存在。", 404) from None
+                resolved = (static_root / "index.html").resolve(strict=True)
+            content = resolved.read_bytes()
+            content_type = mimetypes.guess_type(resolved.name)[0] or "application/octet-stream"
+            if content_type.startswith("text/") or content_type in {"application/javascript", "application/json"}:
+                content_type += "; charset=utf-8"
+            self._headers(200, content_type, len(content))
+            if not head_only:
+                self.wfile.write(content)
+
+        def _handle(self, method: str) -> None:
+            head_only = method == "HEAD"
+            if method not in {"GET", "HEAD"}:
+                self.send_response(405)
+                for name, value in _SECURITY_HEADERS.items():
+                    self.send_header(name, value)
+                self.send_header("Allow", "GET, HEAD")
+                payload: JsonObject = {
+                    "error": {"code": "method_not_allowed", "message": "只允许 GET 和 HEAD。"}
+                }
+                content = (json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n").encode()
+                self.send_header("Content-Type", "application/json; charset=utf-8")
+                self.send_header("Content-Length", str(len(content)))
+                self.end_headers()
+                self.wfile.write(content)
+                return
+            try:
+                if not _valid_local_request(self):
+                    raise ReviewArtifactError("invalid_origin", "只接受本机同源请求。", 403)
+                request_path = urlsplit(self.path).path
+                if request_path.startswith("/api/"):
+                    self._json(200, _api_response(repository, request_path), head_only=head_only)
+                else:
+                    self._static(request_path, head_only=head_only)
+            except Exception as error:  # the response intentionally hides unexpected implementation details
+                self._error(error, head_only=head_only)
+
+        def do_GET(self) -> None:
+            self._handle("GET")
+
+        def do_HEAD(self) -> None:
+            self._handle("HEAD")
+
+        def do_POST(self) -> None:
+            self._handle("POST")
+
+        def do_PUT(self) -> None:
+            self._handle("PUT")
+
+        def do_PATCH(self) -> None:
+            self._handle("PATCH")
+
+        def do_DELETE(self) -> None:
+            self._handle("DELETE")
+
+        def do_OPTIONS(self) -> None:
+            self._handle("OPTIONS")
+
+    return ReviewRequestHandler
+
+
+def create_server(
+    repository: ReviewArtifacts,
+    static_root: Path,
+    *,
+    port: int = 0,
+) -> ReviewerHttpServer:
+    """Create, but do not start, the loopback reviewer server."""
+    index = static_root / "index.html"
+    if not index.is_file():
+        raise ReviewArtifactError("missing_build", "未找到前端构建结果，请先运行 npm run build。", 400)
+    return ReviewerHttpServer(("127.0.0.1", port), _handler_factory(repository, static_root.resolve()))
+
+
+def _arguments(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="只读查看一次 mdpolish 本地清洗运行。")
+    parser.add_argument("--run-dir", required=True, help="一次已发布运行目录的绝对或相对路径")
+    parser.add_argument("--port", type=int, default=0, help="本机端口；默认 0 表示自动选择")
+    arguments = parser.parse_args(argv)
+    if arguments.port < 0 or arguments.port > 65535:
+        parser.error("--port 必须在 0 到 65535 之间")
+    return arguments
+
+
+def main(argv: list[str] | None = None) -> None:
+    arguments = _arguments(argv)
+    repository = ReviewArtifacts(arguments.run_dir)
+    static_root = Path(__file__).resolve().parents[1] / "dist"
+    try:
+        server = create_server(repository, static_root, port=arguments.port)
+    except OSError as error:
+        raise ReviewArtifactError("server_error", "无法启动本地评审服务。", 500) from error
+    port = server.server_address[1]
+    print(
+        f"mdpolish 评审器已启动：http://127.0.0.1:{port}（{repository.run_id}，"
+        f"{len(repository.documents)} 份文档）",
+        flush=True,
+    )
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except ReviewArtifactError as error:
+        raise SystemExit(f"评审器启动失败：{error}") from None

reviewer/server/artifacts.py

@@ -0,0 +1,691 @@
+"""Strict adapters from published mdpolish artifacts to the reviewer API."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from hashlib import sha256
+from pathlib import Path
+from typing import NoReturn, TypeAlias, cast
+
+from mdpolish._artifact_replay import (
+    LocatedChange,
+    ReplayChange,
+    ReplayComponent,
+    ReplayError,
+    ReplayResult,
+    replay_change_chain,
+)
+
+JsonValue: TypeAlias = bool | int | float | str | list["JsonValue"] | dict[str, "JsonValue"] | None
+JsonObject: TypeAlias = dict[str, JsonValue]
+_STATUSES = {"success", "failed", "unstable"}
+_ERROR_STAGES = {"transform", "final_review"}
+
+
+class ReviewArtifactError(ValueError):
+    """Published artifacts cannot be exposed as a trustworthy review response."""
+
+    def __init__(self, code: str, message: str, http_status: int = 422) -> None:
+        super().__init__(message)
+        self.code = code
+        self.http_status = http_status
+
+
+@dataclass(frozen=True, slots=True)
+class ComponentRecord:
+    component_id: str
+    version: str
+    parameters: JsonValue
+    applicability: str
+
+
+@dataclass(frozen=True, slots=True)
+class ManifestDocument:
+    document_id: str
+    source_label: str
+    status: str
+    input_sha256: str
+    current_sha256: str
+    change_count: int
+    result_path: str
+    cleaned_path: str | None
+    diff_path: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class LocatorDocument:
+    document_id: str
+    source_path: Path
+    input_sha256: str
+
+
+@dataclass(frozen=True, slots=True)
+class ChangeRecord:
+    replay: ReplayChange
+    reason: str
+    recorded_line: int
+    recorded_column: int
+
+
+@dataclass(frozen=True, slots=True)
+class ResultRecord:
+    status: str
+    input_sha256: str
+    current_sha256: str
+    changes: tuple[ChangeRecord, ...]
+    errors: tuple[JsonObject, ...]
+    residual_proposals: tuple[JsonObject, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class DocumentRecord:
+    manifest: ManifestDocument
+    result: ResultRecord
+    locator: LocatorDocument | None
+
+
+def _fail(code: str, message: str, http_status: int = 422) -> NoReturn:
+    raise ReviewArtifactError(code, message, http_status)
+
+
+def _object(value: object, label: str) -> dict[str, object]:
+    if not isinstance(value, dict) or any(not isinstance(key, str) for key in value):
+        _fail("invalid_artifact", f"{label} 必须是 JSON 对象。")
+    return cast(dict[str, object], value)
+
+
+def _array(value: object, label: str) -> list[object]:
+    if not isinstance(value, list):
+        _fail("invalid_artifact", f"{label} 必须是数组。")
+    return cast(list[object], value)
+
+
+def _string(value: object, label: str, *, allow_empty: bool = False) -> str:
+    if not isinstance(value, str) or "\0" in value or (not allow_empty and not value):
+        _fail("invalid_artifact", f"{label} 必须是字符串。")
+    return value
+
+
+def _integer(value: object, label: str, *, minimum: int = 0) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value < minimum:
+        _fail("invalid_artifact", f"{label} 必须是不小于 {minimum} 的整数。")
+    return value
+
+
+def _hash(value: object, label: str) -> str:
+    digest = _string(value, label)
+    if len(digest) != 64 or any(character not in "0123456789abcdef" for character in digest):
+        _fail("invalid_artifact", f"{label} 必须是小写 SHA-256 摘要。")
+    return digest
+
+
+def _status(value: object, label: str) -> str:
+    status = _string(value, label)
+    if status not in _STATUSES:
+        _fail("invalid_artifact", f"{label} 不是已知状态。")
+    return status
+
+
+def _json_value(value: object, label: str) -> JsonValue:
+    if value is None or isinstance(value, str | int | float | bool):
+        return value
+    if isinstance(value, list):
+        return [_json_value(item, label) for item in value]
+    if isinstance(value, dict) and all(isinstance(key, str) for key in value):
+        return {cast(str, key): _json_value(item, label) for key, item in value.items()}
+    _fail("invalid_artifact", f"{label} 包含不支持的 JSON 值。")
+    raise AssertionError("unreachable")
+
+
+def _read_json(path: Path, label: str) -> dict[str, object]:
+    try:
+        content = path.read_bytes()
+    except OSError:
+        _fail("missing_artifact", f"无法读取{label}。")
+    if content.startswith(b"\xef\xbb\xbf"):
+        _fail("invalid_artifact", f"{label} 不能包含 UTF-8 BOM。")
+    if not content.endswith(b"\n"):
+        _fail("invalid_artifact", f"{label} 必须以换行结尾。")
+    try:
+        text = content.decode("utf-8", errors="strict")
+    except UnicodeDecodeError:
+        _fail("invalid_utf8", f"{label} 不是严格 UTF-8。")
+    try:
+        payload = cast(
+            object,
+            json.loads(
+                text,
+                parse_constant=lambda _value: _fail(
+                    "invalid_artifact", f"{label} 不能包含非有限数值。"
+                ),
+            ),
+        )
+    except json.JSONDecodeError:
+        _fail("invalid_artifact", f"{label} 不是合法 JSON。")
+    return _object(payload, label)
+
+
+def _read_markdown(path: Path, expected_hash: str, label: str, error_code: str) -> str:
+    try:
+        if path.is_symlink() or not path.is_file():
+            _fail(error_code, f"{label}不是普通文件。", 409)
+        content = path.read_bytes()
+    except OSError:
+        _fail(error_code, f"无法读取{label}。", 409)
+    if sha256(content).hexdigest() != expected_hash:
+        _fail("hash_mismatch", f"{label}的内容哈希已经变化。", 409)
+    try:
+        return content.decode("utf-8", errors="strict")
+    except UnicodeDecodeError:
+        _fail("invalid_utf8", f"{label}不是严格 UTF-8。", 409)
+    raise AssertionError("unreachable")
+
+
+def _run_path(run_directory: Path, relative_path: str, label: str) -> Path:
+    relative = Path(relative_path)
+    if relative.is_absolute() or "\0" in relative_path:
+        _fail("unsafe_path", f"{label}必须是运行目录内的相对路径。")
+    unresolved = run_directory / relative
+    try:
+        if unresolved.is_symlink() or not unresolved.is_file():
+            _fail("missing_artifact", f"无法读取{label}。")
+        resolved = unresolved.resolve(strict=True)
+    except OSError:
+        _fail("missing_artifact", f"无法读取{label}。")
+    if not resolved.is_relative_to(run_directory):
+        _fail("unsafe_path", f"{label}越过了运行目录边界。")
+    return resolved
+
+
+def _component(value: object, position: int) -> ComponentRecord:
+    item = _object(value, f"pipeline.components[{position}]")
+    return ComponentRecord(
+        component_id=_string(item.get("component_id"), "component_id"),
+        version=_string(item.get("version"), "component version"),
+        parameters=_json_value(item.get("parameters"), "component parameters"),
+        applicability=_string(item.get("applicability"), "component applicability"),
+    )
+
+
+def _manifest_document(value: object, position: int) -> ManifestDocument:
+    item = _object(value, f"manifest.documents[{position}]")
+    document_id = _string(item.get("document_id"), "document_id")
+    status = _status(item.get("status"), "document status")
+    result_path = _string(item.get("result_path"), "result_path")
+    cleaned_value = item.get("cleaned_path")
+    diff_value = item.get("diff_path")
+    cleaned_path = None if cleaned_value is None else _string(cleaned_value, "cleaned_path")
+    diff_path = None if diff_value is None else _string(diff_value, "diff_path")
+    base = f"documents/{document_id}"
+    if (
+        result_path != f"{base}/result.json"
+        or cleaned_path != (f"{base}/cleaned.md" if status == "success" else None)
+        or diff_path != (f"{base}/changes.diff" if status == "success" else None)
+    ):
+        _fail("invalid_artifact", "manifest 文档产物路径不符合 schema 1。")
+    return ManifestDocument(
+        document_id=document_id,
+        source_label=_string(item.get("source_label"), "source_label"),
+        status=status,
+        input_sha256=_hash(item.get("input_sha256"), "input_sha256"),
+        current_sha256=_hash(item.get("current_sha256"), "current_sha256"),
+        change_count=_integer(item.get("change_count"), "change_count"),
+        result_path=result_path,
+        cleaned_path=cleaned_path,
+        diff_path=diff_path,
+    )
+
+
+def _parse_change(value: object, position: int) -> ChangeRecord:
+    item = _object(value, f"changes[{position}]")
+    proposal = _object(item.get("proposal_ref"), "proposal_ref")
+    span = _object(item.get("span"), "span")
+    location = _object(item.get("location"), "location")
+    start = _integer(span.get("start"), "span.start")
+    end = _integer(span.get("end"), "span.end")
+    if end < start:
+        _fail("invalid_artifact", "change span 必须满足 start <= end。")
+    replay = ReplayChange(
+        component_id=_string(item.get("component_id"), "change component_id"),
+        component_version=_string(item.get("component_version"), "change component_version"),
+        component_position=_integer(item.get("component_position"), "change component_position"),
+        proposal_component_position=_integer(
+            proposal.get("component_position"), "proposal component_position"
+        ),
+        proposal_snapshot_sha256=_hash(proposal.get("snapshot_sha256"), "proposal snapshot_sha256"),
+        proposal_index=_integer(proposal.get("proposal_index"), "proposal_index"),
+        edit_index=_integer(item.get("edit_index"), "edit_index"),
+        start=start,
+        end=end,
+        before=_string(item.get("before"), "before", allow_empty=True),
+        after=_string(item.get("after"), "after", allow_empty=True),
+        before_sha256=_hash(item.get("before_sha256"), "before_sha256"),
+        after_sha256=_hash(item.get("after_sha256"), "after_sha256"),
+    )
+    return ChangeRecord(
+        replay=replay,
+        reason=_string(item.get("reason"), "change reason"),
+        recorded_line=_integer(location.get("line"), "location.line", minimum=1),
+        recorded_column=_integer(location.get("column"), "location.column", minimum=1),
+    )
+
+
+def _parse_error(value: object, position: int) -> JsonObject:
+    item = _object(value, f"errors[{position}]")
+    stage = _string(item.get("stage"), "error stage")
+    if stage not in _ERROR_STAGES:
+        _fail("invalid_artifact", "error stage 不是已知阶段。")
+    return {
+        "component_id": _string(item.get("component_id"), "error component_id"),
+        "component_version": _string(item.get("component_version"), "error component_version"),
+        "component_position": _integer(item.get("component_position"), "error component_position"),
+        "stage": stage,
+        "error_type": _string(item.get("error_type"), "error_type"),
+        "message": _string(item.get("message"), "error message"),
+    }
+
+
+def _parse_residual(value: object, position: int) -> JsonObject:
+    item = _object(value, f"residual_proposals[{position}]")
+    reference = _object(item.get("proposal_ref"), "residual proposal_ref")
+    proposal = _object(item.get("proposal"), "residual proposal")
+    component_position = _integer(item.get("component_position"), "residual component_position")
+    proposal_snapshot = _hash(proposal.get("snapshot_sha256"), "residual proposal snapshot_sha256")
+    if (
+        _integer(reference.get("component_position"), "residual reference component_position")
+        != component_position
+        or _hash(reference.get("snapshot_sha256"), "residual reference snapshot_sha256")
+        != proposal_snapshot
+    ):
+        _fail("invalid_artifact", "residual proposal_ref 与候选身份不一致。")
+    _integer(reference.get("proposal_index"), "residual proposal_index")
+    edits = _array(proposal.get("edits"), "residual proposal edits")
+    if not edits:
+        _fail("invalid_artifact", "residual proposal edits 不能为空。")
+    for edit_position, edit_value in enumerate(edits):
+        edit = _object(edit_value, f"residual edit[{edit_position}]")
+        span = _object(edit.get("span"), "residual edit span")
+        if _hash(edit.get("snapshot_sha256"), "residual edit snapshot_sha256") != proposal_snapshot:
+            _fail("invalid_artifact", "residual edit 与候选快照不一致。")
+        start = _integer(span.get("start"), "residual span.start")
+        end = _integer(span.get("end"), "residual span.end")
+        expected = _string(edit.get("expected_text"), "residual expected_text", allow_empty=True)
+        _string(edit.get("replacement"), "residual replacement", allow_empty=True)
+        if end < start or len(expected) != end - start:
+            _fail("invalid_artifact", "residual edit 范围与 expected_text 不一致。")
+    return {
+        "component_id": _string(item.get("component_id"), "residual component_id"),
+        "component_version": _string(item.get("component_version"), "residual component_version"),
+        "component_position": component_position,
+        "reason": _string(proposal.get("reason"), "residual reason"),
+        "edit_count": len(edits),
+    }
+
+
+def _component_json(component: ComponentRecord, position: int, change_count: int) -> JsonObject:
+    return {
+        "component_position": position,
+        "component_id": component.component_id,
+        "version": component.version,
+        "parameters": component.parameters,
+        "applicability": component.applicability,
+        "change_count": change_count,
+    }
+
+
+class ReviewArtifacts:
+    """Validated, read-only view over one explicitly selected run directory."""
+
+    def __init__(self, run_directory: str | Path) -> None:
+        requested = Path(run_directory)
+        try:
+            if requested.is_symlink() or not requested.is_dir():
+                _fail("missing_run", "指定的运行目录不存在或不是普通目录。", 400)
+            self.run_directory = requested.resolve(strict=True)
+        except OSError:
+            _fail("missing_run", "无法读取指定的运行目录。", 400)
+
+        manifest = _read_json(_run_path(self.run_directory, "manifest.json", "manifest.json"), "manifest.json")
+        if manifest.get("schema_version") != 1:
+            _fail("unsupported_schema", "只支持 manifest.json schema 1。", 409)
+        run = _object(manifest.get("run"), "manifest.run")
+        pipeline = _object(manifest.get("pipeline"), "manifest.pipeline")
+        summary = _object(manifest.get("summary"), "manifest.summary")
+        self.run_id = _string(run.get("run_id"), "run_id")
+        self.run_json: JsonObject = {
+            "run_id": self.run_id,
+            "run_date": _string(run.get("run_date"), "run_date"),
+            "status": _status(run.get("status"), "run status"),
+            "started_at_utc": _string(run.get("started_at_utc"), "started_at_utc"),
+            "completed_at_utc": _string(run.get("completed_at_utc"), "completed_at_utc"),
+            "retention_until": _string(run.get("retention_until"), "retention_until"),
+        }
+        self.components = tuple(
+            _component(value, position)
+            for position, value in enumerate(_array(pipeline.get("components"), "pipeline.components"))
+        )
+        manifest_documents = tuple(
+            _manifest_document(value, position)
+            for position, value in enumerate(_array(manifest.get("documents"), "manifest.documents"))
+        )
+        if len({item.document_id for item in manifest_documents}) != len(manifest_documents):
+            _fail("invalid_artifact", "manifest 中的 document_id 必须唯一。")
+        self.summary_json: JsonObject = {
+            "document_count": _integer(summary.get("document_count"), "summary.document_count"),
+            "success_count": _integer(summary.get("success_count"), "summary.success_count"),
+            "failed_count": _integer(summary.get("failed_count"), "summary.failed_count"),
+            "unstable_count": _integer(summary.get("unstable_count"), "summary.unstable_count"),
+            "change_count": _integer(summary.get("change_count"), "summary.change_count"),
+        }
+        expected_summary: JsonObject = {
+            "document_count": len(manifest_documents),
+            "success_count": sum(item.status == "success" for item in manifest_documents),
+            "failed_count": sum(item.status == "failed" for item in manifest_documents),
+            "unstable_count": sum(item.status == "unstable" for item in manifest_documents),
+            "change_count": sum(item.change_count for item in manifest_documents),
+        }
+        if self.summary_json != expected_summary:
+            _fail("invalid_artifact", "manifest 汇总与文档索引不一致。")
+        expected_status = (
+            "failed"
+            if expected_summary["failed_count"]
+            else "unstable"
+            if expected_summary["unstable_count"]
+            else "success"
+        )
+        if self.run_json["status"] != expected_status:
+            _fail("invalid_artifact", "manifest 运行状态与文档状态不一致。")
+
+        locator_path = self.run_directory / "review-locator.json"
+        locators: tuple[LocatorDocument, ...] | None = None
+        self.original_run_location_changed = False
+        if locator_path.exists():
+            locator = _read_json(
+                _run_path(self.run_directory, "review-locator.json", "review-locator.json"),
+                "review-locator.json",
+            )
+            if locator.get("schema_version") != 1:
+                _fail("unsupported_schema", "只支持 review-locator.json schema 1。", 409)
+            locator_run = _object(locator.get("run"), "review locator run")
+            if (
+                _string(locator_run.get("run_id"), "locator run_id") != self.run_id
+                or locator_run.get("manifest_path") != "manifest.json"
+            ):
+                _fail("invalid_artifact", "review locator 与 manifest 运行身份不一致。")
+            recorded_directory_text = _string(locator_run.get("run_directory"), "locator run_directory")
+            recorded_directory = Path(recorded_directory_text)
+            if not recorded_directory.is_absolute() or str(recorded_directory) != str(recorded_directory.resolve()):
+                _fail("invalid_artifact", "locator run_directory 必须是绝对解析路径。")
+            self.original_run_location_changed = recorded_directory != self.run_directory
+            parsed_locators: list[LocatorDocument] = []
+            for position, value in enumerate(_array(locator.get("documents"), "locator documents")):
+                item = _object(value, f"locator.documents[{position}]")
+                source_text = _string(item.get("source_path"), "source_path")
+                source_path = Path(source_text)
+                if not source_path.is_absolute() or str(source_path) != str(source_path.resolve()):
+                    _fail("invalid_artifact", "source_path 必须是绝对解析路径。")
+                parsed_locators.append(
+                    LocatorDocument(
+                        document_id=_string(item.get("document_id"), "locator document_id"),
+                        source_path=source_path,
+                        input_sha256=_hash(item.get("input_sha256"), "locator input_sha256"),
+                    )
+                )
+            locators = tuple(parsed_locators)
+            if len(locators) != len(manifest_documents):
+                _fail("invalid_artifact", "review locator 文档数量与 manifest 不一致。")
+            for indexed, located in zip(manifest_documents, locators, strict=True):
+                if indexed.document_id != located.document_id or indexed.input_sha256 != located.input_sha256:
+                    _fail("invalid_artifact", "review locator 文档身份与 manifest 不一致。")
+
+        records: list[DocumentRecord] = []
+        for position, manifest_document in enumerate(manifest_documents):
+            result = self._parse_result(manifest_document)
+            records.append(
+                DocumentRecord(
+                    manifest=manifest_document,
+                    result=result,
+                    locator=None if locators is None else locators[position],
+                )
+            )
+        self.documents = tuple(records)
+        self.documents_by_id = {item.manifest.document_id: item for item in self.documents}
+
+    def _parse_result(self, manifest: ManifestDocument) -> ResultRecord:
+        payload = _read_json(_run_path(self.run_directory, manifest.result_path, "result.json"), "result.json")
+        if payload.get("schema_version") != 1:
+            _fail("unsupported_schema", "只支持 result.json schema 1。", 409)
+        document = _object(payload.get("document"), "result.document")
+        if (
+            _string(document.get("document_id"), "result document_id") != manifest.document_id
+            or _string(document.get("source_label"), "result source_label") != manifest.source_label
+        ):
+            _fail("invalid_artifact", "result 与 manifest 文档身份不一致。")
+        status = _status(payload.get("status"), "result status")
+        input_hash = _hash(payload.get("input_sha256"), "result input_sha256")
+        current_hash = _hash(payload.get("current_sha256"), "result current_sha256")
+        changes = tuple(
+            _parse_change(value, position)
+            for position, value in enumerate(_array(payload.get("changes"), "result changes"))
+        )
+        errors = tuple(
+            _parse_error(value, position)
+            for position, value in enumerate(_array(payload.get("errors"), "result errors"))
+        )
+        residuals = tuple(
+            _parse_residual(value, position)
+            for position, value in enumerate(_array(payload.get("residual_proposals"), "result residual_proposals"))
+        )
+        output = _object(payload.get("output"), "result output")
+        cleaned = output.get("cleaned_path")
+        diff = output.get("diff_path")
+        expected_cleaned: object = "cleaned.md" if status == "success" else None
+        expected_diff: object = "changes.diff" if status == "success" else None
+        if cleaned != expected_cleaned or diff != expected_diff:
+            _fail("invalid_artifact", "result 状态与输出路径不一致。")
+        if (
+            status != manifest.status
+            or input_hash != manifest.input_sha256
+            or current_hash != manifest.current_sha256
+            or len(changes) != manifest.change_count
+        ):
+            _fail("invalid_artifact", "result 与 manifest 文档索引不一致。")
+        if status == "success" and (errors or residuals):
+            _fail("invalid_artifact", "success 文档不能包含错误或残留候选。")
+        if status == "failed" and (not errors or residuals):
+            _fail("invalid_artifact", "failed 文档的错误或残留状态不合法。")
+        if status == "unstable" and (errors or not residuals):
+            _fail("invalid_artifact", "unstable 文档的错误或残留状态不合法。")
+        for change in changes:
+            position = change.replay.component_position
+            if position >= len(self.components):
+                _fail("invalid_artifact", "change 没有对应的流水线组件。")
+            component = self.components[position]
+            if (
+                change.replay.component_id != component.component_id
+                or change.replay.component_version != component.version
+            ):
+                _fail("invalid_artifact", "change 身份与流水线组件不一致。")
+        for evidence in (*errors, *residuals):
+            position_value = evidence["component_position"]
+            component_id = evidence["component_id"]
+            component_version = evidence["component_version"]
+            if not isinstance(position_value, int) or position_value >= len(self.components):
+                _fail("invalid_artifact", "审计证据没有对应的流水线组件。")
+            component = self.components[position_value]
+            if component_id != component.component_id or component_version != component.version:
+                _fail("invalid_artifact", "审计证据身份与流水线组件不一致。")
+        if manifest.diff_path is not None:
+            _run_path(self.run_directory, manifest.diff_path, "changes.diff")
+        return ResultRecord(status, input_hash, current_hash, changes, errors, residuals)
+
+    def _source(self, record: DocumentRecord) -> tuple[str | None, str | None]:
+        if record.locator is None:
+            return None, "这次历史运行没有 review-locator.json，无法定位完整原文。"
+        try:
+            return (
+                _read_markdown(
+                    record.locator.source_path,
+                    record.manifest.input_sha256,
+                    "原文",
+                    "unavailable_source",
+                ),
+                None,
+            )
+        except ReviewArtifactError as error:
+            return None, str(error)
+
+    def _cleaned(self, record: DocumentRecord) -> tuple[str | None, str | None]:
+        if record.manifest.status != "success" or record.manifest.cleaned_path is None:
+            return None, None
+        try:
+            path = _run_path(self.run_directory, record.manifest.cleaned_path, "cleaned.md")
+            return (
+                _read_markdown(path, record.manifest.current_sha256, "清洗结果", "missing_artifact"),
+                None,
+            )
+        except ReviewArtifactError as error:
+            return None, str(error)
+
+    def _replay(self, record: DocumentRecord, original: str, cleaned: str | None) -> ReplayResult:
+        try:
+            replayed = replay_change_chain(
+                input_markdown=original,
+                input_sha256=record.result.input_sha256,
+                components=tuple(ReplayComponent(item.component_id, item.version) for item in self.components),
+                changes=tuple(item.replay for item in record.result.changes),
+                current_sha256=record.result.current_sha256,
+                current_markdown=cleaned,
+                include_zero_change_stages=record.result.status == "success",
+            )
+        except ReplayError as error:
+            raise ReviewArtifactError("untrusted_replay", f"产物无法可信重放：{error}", 409) from error
+        for recorded, located in zip(record.result.changes, replayed.changes, strict=True):
+            if recorded.recorded_line != located.line or recorded.recorded_column != located.column:
+                _fail("untrusted_replay", "产物记录的位置与重放快照不一致。", 409)
+        return replayed
+
+    @staticmethod
+    def _summary_json(
+        record: DocumentRecord,
+        original: str | None,
+        source_error: str | None,
+        cleaned: str | None,
+        output_error: str | None,
+    ) -> JsonObject:
+        return {
+            "document_id": record.manifest.document_id,
+            "source_label": record.manifest.source_label,
+            "status": record.manifest.status,
+            "input_sha256": record.manifest.input_sha256,
+            "current_sha256": record.manifest.current_sha256,
+            "change_count": record.manifest.change_count,
+            "source_available": original is not None,
+            "output_available": cleaned is not None,
+            "availability_error": source_error or output_error,
+        }
+
+    def _summary(self, record: DocumentRecord) -> JsonObject:
+        original, source_error = self._source(record)
+        cleaned, output_error = self._cleaned(record)
+        return self._summary_json(record, original, source_error, cleaned, output_error)
+
+    def _component_summaries(self, changes: tuple[ChangeRecord, ...]) -> list[JsonValue]:
+        counts = [0] * len(self.components)
+        for change in changes:
+            if 0 <= change.replay.component_position < len(counts):
+                counts[change.replay.component_position] += 1
+        return [_component_json(item, position, counts[position]) for position, item in enumerate(self.components)]
+
+    @staticmethod
+    def _change_json(recorded: ChangeRecord, located: LocatedChange | None) -> JsonObject:
+        change = recorded.replay
+        return {
+            "component_id": change.component_id,
+            "component_version": change.component_version,
+            "component_position": change.component_position,
+            "proposal_ref": {
+                "component_position": change.proposal_component_position,
+                "snapshot_sha256": change.proposal_snapshot_sha256,
+                "proposal_index": change.proposal_index,
+            },
+            "edit_index": change.edit_index,
+            "reason": recorded.reason,
+            "location": {
+                "line": recorded.recorded_line if located is None else located.line,
+                "column": recorded.recorded_column if located is None else located.column,
+            },
+            "editor_range": (
+                None if located is None else {"start": located.editor_start, "end": located.editor_end}
+            ),
+            "before": change.before,
+            "after": change.after,
+        }
+
+    def run_summary(self) -> JsonObject:
+        all_changes = tuple(change for document in self.documents for change in document.result.changes)
+        return {
+            "schema_version": 1,
+            "run": self.run_json,
+            "components": self._component_summaries(all_changes),
+            "documents": [self._summary(item) for item in self.documents],
+            "summary": self.summary_json,
+            "original_run_location_changed": self.original_run_location_changed,
+        }
+
+    def _document(self, document_id: str) -> DocumentRecord:
+        record = self.documents_by_id.get(document_id)
+        if record is None:
+            _fail("unknown_document", "文档不存在。", 404)
+        return record
+
+    def document_comparison(self, document_id: str) -> JsonObject:
+        record = self._document(document_id)
+        original, source_error = self._source(record)
+        cleaned, output_error = self._cleaned(record)
+        replayed = None if original is None else self._replay(record, original, cleaned)
+        located = () if replayed is None else replayed.changes
+        return {
+            "schema_version": 1,
+            "document": self._summary_json(record, original, source_error, cleaned, output_error),
+            "components": self._component_summaries(record.result.changes),
+            "original_markdown": original,
+            "cleaned_markdown": cleaned,
+            "changes": [
+                self._change_json(change, located[position] if position < len(located) else None)
+                for position, change in enumerate(record.result.changes)
+            ],
+            "errors": list(record.result.errors),
+            "residual_proposals": list(record.result.residual_proposals),
+        }
+
+    def component_stage(self, document_id: str, component_position: int) -> JsonObject:
+        record = self._document(document_id)
+        if record.manifest.status != "success":
+            _fail("stage_unavailable", "只有 success 文档具有完整组件阶段。", 409)
+        if component_position < 0 or component_position >= len(self.components):
+            _fail("unknown_component", "组件位置不存在。", 404)
+        original, source_error = self._source(record)
+        cleaned, output_error = self._cleaned(record)
+        if original is None or cleaned is None:
+            _fail("comparison_unavailable", source_error or output_error or "组件阶段不可用。", 409)
+        replayed = self._replay(record, original, cleaned)
+        stage = replayed.stages[component_position]
+        component = self.components[component_position]
+        recorded_changes = tuple(
+            item for item in record.result.changes if item.replay.component_position == component_position
+        )
+        return {
+            "schema_version": 1,
+            "document_id": record.manifest.document_id,
+            "component": _component_json(component, component_position, len(stage.changes)),
+            "before_sha256": stage.before_sha256,
+            "after_sha256": stage.after_sha256,
+            "before_markdown": stage.before_markdown,
+            "after_markdown": stage.after_markdown,
+            "changes": [
+                self._change_json(change, located)
+                for change, located in zip(recorded_changes, stage.changes, strict=True)
+            ],
+        }

reviewer/src/client/App.tsx

@@ -0,0 +1,378 @@
+import { lazy, Suspense, useEffect, useMemo, useState } from "react";
+
+import type {
+  ChangeDetail,
+  ComponentStageResponse,
+  DocumentComparisonResponse,
+  RunStatus,
+  RunSummaryResponse,
+} from "../shared/api.js";
+import { fetchComponentStage, fetchDocument, fetchRun } from "./api-client.js";
+
+const DiffView = lazy(async () => {
+  const module = await import("./DiffView.js");
+  return { default: module.DiffView };
+});
+
+interface AsyncState<T> {
+  loading: boolean;
+  value: T | null;
+  error: string | null;
+}
+
+const emptyState = <T,>(): AsyncState<T> => ({ loading: true, value: null, error: null });
+
+function statusLabel(status: RunStatus): string {
+  switch (status) {
+    case "success":
+      return "成功";
+    case "failed":
+      return "失败";
+    case "unstable":
+      return "不稳定";
+  }
+}
+
+function shortHash(hash: string): string {
+  return `${hash.slice(0, 8)}…${hash.slice(-6)}`;
+}
+
+function ErrorPanel({ message }: { message: string }) {
+  return (
+    <div className="state-panel state-panel--error" role="alert">
+      <span className="eyebrow">无法显示</span>
+      <p>{message}</p>
+    </div>
+  );
+}
+
+function LoadingPanel() {
+  return (
+    <div className="state-panel" role="status">
+      <span className="loading-dot" />
+      <p>正在校验本地运行产物…</p>
+    </div>
+  );
+}
+
+function ChangeList({
+  changes,
+  onSelect,
+  canJump,
+}: {
+  changes: ChangeDetail[];
+  onSelect: (change: ChangeDetail) => void;
+  canJump: boolean;
+}) {
+  if (changes.length === 0) {
+    return <p className="quiet-message">这个组件运行过，但没有修改当前文档。</p>;
+  }
+  return (
+    <ol className="change-list">
+      {changes.map((change) => (
+        <li key={`${change.proposal_ref.snapshot_sha256}-${change.proposal_ref.proposal_index}-${change.edit_index}`}>
+          <button type="button" onClick={() => onSelect(change)} disabled={!canJump}>
+            <span className="change-location">
+              第 {change.location.line} 行，第 {change.location.column} 列 · 候选
+              {change.proposal_ref.proposal_index + 1} / 编辑 {change.edit_index + 1}
+            </span>
+            <strong>{change.reason}</strong>
+            <span className="change-sample">
+              <del>{change.before || "∅"}</del>
+              <span aria-hidden="true">→</span>
+              <ins>{change.after || "∅"}</ins>
+            </span>
+          </button>
+        </li>
+      ))}
+    </ol>
+  );
+}
+
+export function App() {
+  const [runState, setRunState] = useState<AsyncState<RunSummaryResponse>>(emptyState);
+  const [selectedDocument, setSelectedDocument] = useState<string | null>(null);
+  const [documentState, setDocumentState] = useState<AsyncState<DocumentComparisonResponse>>({
+    loading: false,
+    value: null,
+    error: null,
+  });
+  const [selectedComponent, setSelectedComponent] = useState<number | null>(null);
+  const [stageState, setStageState] = useState<AsyncState<ComponentStageResponse>>({
+    loading: false,
+    value: null,
+    error: null,
+  });
+  const [focusRange, setFocusRange] = useState<{ start: number; end: number } | null>(null);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    fetchRun(controller.signal)
+      .then((run) => {
+        setRunState({ loading: false, value: run, error: null });
+        setSelectedDocument(run.documents[0]?.document_id ?? null);
+      })
+      .catch((error: unknown) => {
+        if (!controller.signal.aborted) {
+          setRunState({
+            loading: false,
+            value: null,
+            error: error instanceof Error ? error.message : "无法读取运行摘要。",
+          });
+        }
+      });
+    return () => controller.abort();
+  }, []);
+
+  useEffect(() => {
+    setSelectedComponent(null);
+    setFocusRange(null);
+    if (selectedDocument === null) {
+      setDocumentState({ loading: false, value: null, error: null });
+      return undefined;
+    }
+    const controller = new AbortController();
+    setDocumentState(emptyState());
+    fetchDocument(selectedDocument, controller.signal)
+      .then((document) => setDocumentState({ loading: false, value: document, error: null }))
+      .catch((error: unknown) => {
+        if (!controller.signal.aborted) {
+          setDocumentState({
+            loading: false,
+            value: null,
+            error: error instanceof Error ? error.message : "无法读取文档。",
+          });
+        }
+      });
+    return () => controller.abort();
+  }, [selectedDocument]);
+
+  useEffect(() => {
+    if (selectedDocument === null || selectedComponent === null) {
+      setStageState({ loading: false, value: null, error: null });
+      return undefined;
+    }
+    const controller = new AbortController();
+    setStageState(emptyState());
+    fetchComponentStage(selectedDocument, selectedComponent, controller.signal)
+      .then((stage) => setStageState({ loading: false, value: stage, error: null }))
+      .catch((error: unknown) => {
+        if (!controller.signal.aborted) {
+          setStageState({
+            loading: false,
+            value: null,
+            error: error instanceof Error ? error.message : "无法读取组件阶段。",
+          });
+        }
+      });
+    return () => controller.abort();
+  }, [selectedDocument, selectedComponent]);
+
+  const visibleChanges = useMemo(() => {
+    const document = documentState.value;
+    if (document === null) {
+      return [];
+    }
+    if (selectedComponent === null) {
+      return document.changes;
+    }
+    return document.changes.filter((change) => change.component_position === selectedComponent);
+  }, [documentState.value, selectedComponent]);
+
+  const selectChange = (change: ChangeDetail): void => {
+    setSelectedComponent(change.component_position);
+    setFocusRange(change.editor_range);
+  };
+
+  if (runState.loading) {
+    return <LoadingPanel />;
+  }
+  if (runState.error !== null || runState.value === null) {
+    return <ErrorPanel message={runState.error ?? "运行摘要为空。"} />;
+  }
+
+  const run = runState.value;
+  const document = documentState.value;
+  const selectedSummary = run.documents.find((item) => item.document_id === selectedDocument);
+  const selectedStage = stageState.value;
+  const canCompare =
+    document?.document.status === "success" &&
+    document.document.source_available &&
+    document.document.output_available &&
+    document.original_markdown !== null &&
+    document.cleaned_markdown !== null;
+  const beforeText = selectedStage?.before_markdown ?? document?.original_markdown ?? "";
+  const afterText = selectedStage?.after_markdown ?? document?.cleaned_markdown ?? "";
+  const beforeLabel = selectedStage === null ? "清洗前" : `组件 ${selectedStage.component.component_position + 1} 执行前`;
+  const afterLabel = selectedStage === null ? "清洗后" : `组件 ${selectedStage.component.component_position + 1} 执行后`;
+
+  return (
+    <div className="app-shell">
+      <header className="topbar">
+        <div>
+          <span className="brand-mark">md</span>
+          <div>
+            <p className="eyebrow">本地清洗评审器</p>
+            <h1>{run.run.run_id}</h1>
+          </div>
+        </div>
+        <div className="run-facts">
+          <span className={`status status--${run.run.status}`}>{statusLabel(run.run.status)}</span>
+          <span>{run.summary.document_count} 份文档</span>
+          <span>{run.summary.change_count} 条修改</span>
+        </div>
+      </header>
+
+      {run.original_run_location_changed ? (
+        <div className="notice" role="status">
+          这次运行目录已被移动；评审器使用你本次指定的目录读取产物。
+        </div>
+      ) : null}
+
+      <div className="layout">
+        <aside className="sidebar" aria-label="运行导航">
+          <section>
+            <div className="section-heading">
+              <h2>文档</h2>
+              <span>{run.documents.length}</span>
+            </div>
+            <nav className="document-list" aria-label="文档列表">
+              {run.documents.map((item) => (
+                <button
+                  type="button"
+                  key={item.document_id}
+                  className={item.document_id === selectedDocument ? "is-active" : ""}
+                  onClick={() => setSelectedDocument(item.document_id)}
+                  aria-current={item.document_id === selectedDocument ? "page" : undefined}
+                >
+                  <span className={`status-dot status-dot--${item.status}`} />
+                  <span>
+                    <strong>{item.source_label}</strong>
+                    <small>{item.change_count} 条修改</small>
+                  </span>
+                </button>
+              ))}
+            </nav>
+          </section>
+
+          <section className="component-section">
+            <div className="section-heading">
+              <h2>组件时间线</h2>
+              <button
+                type="button"
+                className="text-button"
+                onClick={() => {
+                  setSelectedComponent(null);
+                  setFocusRange(null);
+                }}
+                disabled={selectedComponent === null}
+              >
+                查看总结果
+              </button>
+            </div>
+            <ol className="component-list">
+              {(document?.components ?? run.components).map((component) => (
+                <li key={component.component_id}>
+                  <button
+                    type="button"
+                    className={component.component_position === selectedComponent ? "is-active" : ""}
+                    onClick={() => {
+                      setSelectedComponent(component.component_position);
+                      setFocusRange(null);
+                    }}
+                    disabled={!canCompare}
+                  >
+                    <span className="component-index">{component.component_position + 1}</span>
+                    <span>
+                      <strong>{component.component_id}</strong>
+                      <small>
+                        v{component.version} · {component.change_count} 条
+                      </small>
+                    </span>
+                  </button>
+                </li>
+              ))}
+            </ol>
+          </section>
+        </aside>
+
+        <main className="workspace">
+          <section className="document-header">
+            <div>
+              <p className="eyebrow">当前文档</p>
+              <h2>{selectedSummary?.source_label ?? "未选择"}</h2>
+            </div>
+            {selectedSummary === undefined ? null : (
+              <div className="document-meta">
+                <span className={`status status--${selectedSummary.status}`}>
+                  {statusLabel(selectedSummary.status)}
+                </span>
+                <span title={selectedSummary.input_sha256}>输入 {shortHash(selectedSummary.input_sha256)}</span>
+                <span title={selectedSummary.current_sha256}>当前 {shortHash(selectedSummary.current_sha256)}</span>
+              </div>
+            )}
+          </section>
+
+          {documentState.loading || stageState.loading ? <LoadingPanel /> : null}
+          {documentState.error !== null ? <ErrorPanel message={documentState.error} /> : null}
+          {stageState.error !== null ? <ErrorPanel message={stageState.error} /> : null}
+
+          {!documentState.loading && document !== null && document.document.status === "success" && !canCompare ? (
+            <ErrorPanel message={document.document.availability_error ?? "完整原文或清洗结果不可用。"} />
+          ) : null}
+
+          {!documentState.loading && document !== null && document.document.status !== "success" ? (
+            <div className="diagnostic-panel">
+              <p className="eyebrow">没有正式清洗结果</p>
+              <h3>{statusLabel(document.document.status)}文档只展示审计证据</h3>
+              <p>
+                该状态不会生成 <code>cleaned.md</code>，因此这里不构造完整部分输出。
+              </p>
+              {document.errors.map((error) => (
+                <article key={`${error.component_position}-${error.stage}-${error.error_type}`}>
+                  <strong>{error.error_type}</strong>
+                  <span>{error.message}</span>
+                </article>
+              ))}
+              {document.residual_proposals.map((proposal) => (
+                <article key={`${proposal.component_position}-${proposal.reason}`}>
+                  <strong>最终复查仍有 {proposal.edit_count} 项候选</strong>
+                  <span>{proposal.reason}</span>
+                </article>
+              ))}
+            </div>
+          ) : null}
+
+          {!documentState.loading && !stageState.loading && canCompare && stageState.error === null ? (
+            <Suspense fallback={<LoadingPanel />}>
+              <DiffView
+                before={beforeText}
+                after={afterText}
+                beforeLabel={beforeLabel}
+                afterLabel={afterLabel}
+                focusRange={focusRange}
+              />
+            </Suspense>
+          ) : null}
+
+          {document !== null ? (
+            <section className="changes-panel" aria-label="修改详情">
+              <div className="changes-heading">
+                <div>
+                  <p className="eyebrow">实际修改</p>
+                  <h3>
+                    {selectedComponent === null
+                      ? `全部组件 · ${visibleChanges.length} 条`
+                      : `${document.components[selectedComponent]?.component_id ?? "组件"} · ${visibleChanges.length} 条`}
+                  </h3>
+                </div>
+                {selectedStage === null ? null : <p>{selectedStage.component.applicability}</p>}
+              </div>
+              <ChangeList changes={visibleChanges} onSelect={selectChange} canJump={canCompare} />
+            </section>
+          ) : null}
+        </main>
+      </div>
+    </div>
+  );
+}

reviewer/src/client/DiffView.tsx

@@ -0,0 +1,99 @@
+import { markdown } from "@codemirror/lang-markdown";
+import { MergeView } from "@codemirror/merge";
+import { EditorState } from "@codemirror/state";
+import { EditorView, lineNumbers } from "@codemirror/view";
+import { useEffect, useRef } from "react";
+
+interface DiffViewProps {
+  before: string;
+  after: string;
+  beforeLabel: string;
+  afterLabel: string;
+  focusRange?: { start: number; end: number } | null;
+}
+
+const editorTheme = EditorView.theme({
+  "&": {
+    height: "100%",
+    backgroundColor: "#fbfaf7",
+    color: "#262822",
+    fontSize: "13px",
+  },
+  ".cm-scroller": {
+    fontFamily: '"SFMono-Regular", Consolas, "Liberation Mono", monospace',
+    lineHeight: "1.68",
+  },
+  ".cm-gutters": {
+    backgroundColor: "#f2f0ea",
+    color: "#8a877e",
+    border: "none",
+  },
+  ".cm-content": {
+    padding: "18px 0 36px",
+  },
+  ".cm-line": {
+    padding: "0 14px",
+  },
+  "&.cm-focused": {
+    outline: "2px solid #a7b9ac",
+    outlineOffset: "-2px",
+  },
+});
+
+const readOnlyExtensions = [
+  lineNumbers(),
+  markdown(),
+  EditorState.readOnly.of(true),
+  EditorView.editable.of(false),
+  EditorView.lineWrapping,
+  editorTheme,
+];
+
+export function DiffView({ before, after, beforeLabel, afterLabel, focusRange }: DiffViewProps) {
+  const host = useRef<HTMLDivElement>(null);
+  const merge = useRef<MergeView | null>(null);
+
+  useEffect(() => {
+    if (host.current === null) {
+      return undefined;
+    }
+    const view = new MergeView({
+      parent: host.current,
+      a: { doc: before, extensions: readOnlyExtensions },
+      b: { doc: after, extensions: readOnlyExtensions },
+      orientation: "a-b",
+      gutter: true,
+      highlightChanges: true,
+      collapseUnchanged: { margin: 4, minSize: 8 },
+    });
+    merge.current = view;
+    return () => {
+      view.destroy();
+      merge.current = null;
+    };
+  }, [before, after]);
+
+  useEffect(() => {
+    const view = merge.current;
+    if (view === null || focusRange === null || focusRange === undefined) {
+      return;
+    }
+    const anchor = Math.min(Math.max(focusRange.start, 0), view.a.state.doc.length);
+    const head = Math.min(Math.max(focusRange.end, anchor), view.a.state.doc.length);
+    view.a.dispatch({
+      selection: { anchor, head },
+      effects: EditorView.scrollIntoView(anchor, { y: "center" }),
+    });
+    view.a.focus();
+  }, [focusRange]);
+
+  return (
+    <section className="diff-shell" aria-label={`${beforeLabel}与${afterLabel}对比`}>
+      <div className="diff-labels" aria-hidden="true">
+        <span>{beforeLabel}</span>
+        <span>{afterLabel}</span>
+      </div>
+      <div className="diff-host" ref={host} />
+    </section>
+  );
+}

reviewer/src/client/api-client.ts

@@ -0,0 +1,288 @@
+import type {
+  ApiErrorResponse,
+  ComponentStageResponse,
+  DocumentComparisonResponse,
+  RunSummaryResponse,
+} from "../shared/api.js";
+
+export class ReviewerApiError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = "ReviewerApiError";
+    this.code = code;
+  }
+}
+
+type JsonRecord = Record<string, unknown>;
+
+function invalid(label: string): never {
+  throw new ReviewerApiError("invalid_response", `本地服务返回的 ${label} 格式不正确。`);
+}
+
+function record(value: unknown, label: string): JsonRecord {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return invalid(label);
+  }
+  return value as JsonRecord;
+}
+
+function array(value: unknown, label: string): unknown[] {
+  if (!Array.isArray(value)) {
+    return invalid(label);
+  }
+  return value;
+}
+
+function string(value: unknown, label: string): string {
+  if (typeof value !== "string") {
+    return invalid(label);
+  }
+  return value;
+}
+
+function integer(value: unknown, label: string, minimum = 0): number {
+  if (!Number.isSafeInteger(value) || (value as number) < minimum) {
+    return invalid(label);
+  }
+  return value as number;
+}
+
+function boolean(value: unknown, label: string): boolean {
+  if (typeof value !== "boolean") {
+    return invalid(label);
+  }
+  return value;
+}
+
+function nullableString(value: unknown, label: string): string | null {
+  return value === null ? null : string(value, label);
+}
+
+function hash(value: unknown, label: string): string {
+  const digest = string(value, label);
+  if (!/^[0-9a-f]{64}$/.test(digest)) {
+    return invalid(label);
+  }
+  return digest;
+}
+
+function status(value: unknown): "success" | "failed" | "unstable" {
+  if (value !== "success" && value !== "failed" && value !== "unstable") {
+    return invalid("status");
+  }
+  return value;
+}
+
+function component(value: unknown): RunSummaryResponse["components"][number] {
+  const item = record(value, "component");
+  return {
+    component_position: integer(item.component_position, "component_position"),
+    component_id: string(item.component_id, "component_id"),
+    version: string(item.version, "component version"),
+    parameters: item.parameters,
+    applicability: string(item.applicability, "component applicability"),
+    change_count: integer(item.change_count, "component change_count"),
+  };
+}
+
+function documentSummary(value: unknown): RunSummaryResponse["documents"][number] {
+  const item = record(value, "document summary");
+  return {
+    document_id: string(item.document_id, "document_id"),
+    source_label: string(item.source_label, "source_label"),
+    status: status(item.status),
+    input_sha256: hash(item.input_sha256, "input_sha256"),
+    current_sha256: hash(item.current_sha256, "current_sha256"),
+    change_count: integer(item.change_count, "document change_count"),
+    source_available: boolean(item.source_available, "source_available"),
+    output_available: boolean(item.output_available, "output_available"),
+    availability_error: nullableString(item.availability_error, "availability_error"),
+  };
+}
+
+function summary(value: unknown): RunSummaryResponse["summary"] {
+  const item = record(value, "summary");
+  return {
+    document_count: integer(item.document_count, "document_count"),
+    success_count: integer(item.success_count, "success_count"),
+    failed_count: integer(item.failed_count, "failed_count"),
+    unstable_count: integer(item.unstable_count, "unstable_count"),
+    change_count: integer(item.change_count, "change_count"),
+  };
+}
+
+function change(value: unknown): DocumentComparisonResponse["changes"][number] {
+  const item = record(value, "change");
+  const proposal = record(item.proposal_ref, "proposal_ref");
+  const location = record(item.location, "location");
+  const editorValue = item.editor_range;
+  const editorRange =
+    editorValue === null
+      ? null
+      : (() => {
+          const editor = record(editorValue, "editor_range");
+          const start = integer(editor.start, "editor_range.start");
+          const end = integer(editor.end, "editor_range.end");
+          if (end < start) {
+            return invalid("editor_range");
+          }
+          return { start, end };
+        })();
+  return {
+    component_id: string(item.component_id, "change component_id"),
+    component_version: string(item.component_version, "change component_version"),
+    component_position: integer(item.component_position, "change component_position"),
+    proposal_ref: {
+      component_position: integer(proposal.component_position, "proposal component_position"),
+      snapshot_sha256: hash(proposal.snapshot_sha256, "proposal snapshot_sha256"),
+      proposal_index: integer(proposal.proposal_index, "proposal_index"),
+    },
+    edit_index: integer(item.edit_index, "edit_index"),
+    reason: string(item.reason, "reason"),
+    location: {
+      line: integer(location.line, "location.line", 1),
+      column: integer(location.column, "location.column", 1),
+    },
+    editor_range: editorRange,
+    before: string(item.before, "before"),
+    after: string(item.after, "after"),
+  };
+}
+
+function runError(value: unknown): DocumentComparisonResponse["errors"][number] {
+  const item = record(value, "run error");
+  const stage = item.stage;
+  if (stage !== "transform" && stage !== "final_review") {
+    return invalid("error stage");
+  }
+  return {
+    component_id: string(item.component_id, "error component_id"),
+    component_version: string(item.component_version, "error component_version"),
+    component_position: integer(item.component_position, "error component_position"),
+    stage,
+    error_type: string(item.error_type, "error_type"),
+    message: string(item.message, "error message"),
+  };
+}
+
+function residual(value: unknown): DocumentComparisonResponse["residual_proposals"][number] {
+  const item = record(value, "residual proposal");
+  return {
+    component_id: string(item.component_id, "residual component_id"),
+    component_version: string(item.component_version, "residual component_version"),
+    component_position: integer(item.component_position, "residual component_position"),
+    reason: string(item.reason, "residual reason"),
+    edit_count: integer(item.edit_count, "residual edit_count", 1),
+  };
+}
+
+function parseRun(value: unknown): RunSummaryResponse {
+  const payload = record(value, "run response");
+  if (payload.schema_version !== 1) {
+    return invalid("run schema_version");
+  }
+  const run = record(payload.run, "run");
+  return {
+    schema_version: 1,
+    run: {
+      run_id: string(run.run_id, "run_id"),
+      run_date: string(run.run_date, "run_date"),
+      status: status(run.status),
+      started_at_utc: string(run.started_at_utc, "started_at_utc"),
+      completed_at_utc: string(run.completed_at_utc, "completed_at_utc"),
+      retention_until: string(run.retention_until, "retention_until"),
+    },
+    components: array(payload.components, "components").map(component),
+    documents: array(payload.documents, "documents").map(documentSummary),
+    summary: summary(payload.summary),
+    original_run_location_changed: boolean(
+      payload.original_run_location_changed,
+      "original_run_location_changed",
+    ),
+  };
+}
+
+function parseDocument(value: unknown): DocumentComparisonResponse {
+  const payload = record(value, "document response");
+  if (payload.schema_version !== 1) {
+    return invalid("document schema_version");
+  }
+  return {
+    schema_version: 1,
+    document: documentSummary(payload.document),
+    components: array(payload.components, "components").map(component),
+    original_markdown: nullableString(payload.original_markdown, "original_markdown"),
+    cleaned_markdown: nullableString(payload.cleaned_markdown, "cleaned_markdown"),
+    changes: array(payload.changes, "changes").map(change),
+    errors: array(payload.errors, "errors").map(runError),
+    residual_proposals: array(payload.residual_proposals, "residual_proposals").map(residual),
+  };
+}
+
+function parseStage(value: unknown): ComponentStageResponse {
+  const payload = record(value, "component stage response");
+  if (payload.schema_version !== 1) {
+    return invalid("component stage schema_version");
+  }
+  return {
+    schema_version: 1,
+    document_id: string(payload.document_id, "document_id"),
+    component: component(payload.component),
+    before_sha256: hash(payload.before_sha256, "before_sha256"),
+    after_sha256: hash(payload.after_sha256, "after_sha256"),
+    before_markdown: string(payload.before_markdown, "before_markdown"),
+    after_markdown: string(payload.after_markdown, "after_markdown"),
+    changes: array(payload.changes, "changes").map(change),
+  };
+}
+
+async function getJson<T>(
+  pathname: string,
+  parse: (payload: unknown) => T,
+  signal?: AbortSignal,
+): Promise<T> {
+  const response = await fetch(pathname, {
+    method: "GET",
+    cache: "no-store",
+    credentials: "same-origin",
+    signal,
+  });
+  const payload: unknown = await response.json();
+  if (!response.ok) {
+    const errorPayload = payload as Partial<ApiErrorResponse>;
+    throw new ReviewerApiError(
+      errorPayload.error?.code ?? "request_failed",
+      errorPayload.error?.message ?? `请求失败（HTTP ${response.status}）。`,
+    );
+  }
+  return parse(payload);
+}
+
+export function fetchRun(signal?: AbortSignal): Promise<RunSummaryResponse> {
+  return getJson("/api/v1/run", parseRun, signal);
+}
+
+export function fetchDocument(
+  documentId: string,
+  signal?: AbortSignal,
+): Promise<DocumentComparisonResponse> {
+  return getJson(
+    `/api/v1/documents/${encodeURIComponent(documentId)}`,
+    parseDocument,
+    signal,
+  );
+}
+
+export function fetchComponentStage(
+  documentId: string,
+  componentPosition: number,
+  signal?: AbortSignal,
+): Promise<ComponentStageResponse> {
+  return getJson(
+    `/api/v1/documents/${encodeURIComponent(documentId)}/components/${componentPosition}`,
+    parseStage,
+    signal,
+  );
+}

reviewer/src/client/main.tsx

@@ -0,0 +1,16 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+
+import { App } from "./App.js";
+import "./styles.css";
+
+const root = document.getElementById("root");
+if (root === null) {
+  throw new Error("missing #root element");
+}
+
+createRoot(root).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

reviewer/src/client/styles.css

@@ -0,0 +1,554 @@
+:root {
+  color: #252720;
+  background: #ecebe5;
+  font-family:
+    Inter, ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei",
+    sans-serif;
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body,
+#root {
+  min-width: 1180px;
+  min-height: 100%;
+  margin: 0;
+}
+
+button {
+  color: inherit;
+  font: inherit;
+}
+
+button:focus-visible {
+  outline: 2px solid #315f4b;
+  outline-offset: 2px;
+}
+
+.app-shell {
+  min-height: 100vh;
+  background:
+    radial-gradient(circle at 12% 0%, rgb(255 255 255 / 72%), transparent 34%),
+    #ecebe5;
+}
+
+.topbar {
+  position: sticky;
+  z-index: 20;
+  top: 0;
+  display: flex;
+  min-height: 76px;
+  align-items: center;
+  justify-content: space-between;
+  padding: 12px 24px;
+  border-bottom: 1px solid #d7d5cd;
+  background: rgb(248 247 242 / 94%);
+  backdrop-filter: blur(18px);
+}
+
+.topbar > div:first-child {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+
+.brand-mark {
+  display: grid;
+  width: 42px;
+  height: 42px;
+  place-items: center;
+  border-radius: 12px;
+  background: #284d3d;
+  color: #f3f4ed;
+  font-family: Georgia, serif;
+  font-size: 19px;
+  letter-spacing: -0.08em;
+}
+
+.eyebrow {
+  margin: 0 0 3px;
+  color: #78796f;
+  font-size: 11px;
+  font-weight: 700;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+}
+
+h1,
+h2,
+h3,
+p {
+  margin-top: 0;
+}
+
+.topbar h1 {
+  margin: 0;
+  font-family: Georgia, "Songti SC", serif;
+  font-size: 19px;
+  font-weight: 600;
+}
+
+.run-facts,
+.document-meta {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  color: #66685f;
+  font-size: 12px;
+}
+
+.run-facts > span:not(.status),
+.document-meta > span:not(.status) {
+  padding-left: 10px;
+  border-left: 1px solid #d5d2c9;
+}
+
+.status {
+  display: inline-flex;
+  align-items: center;
+  border: 1px solid currentColor;
+  border-radius: 999px;
+  padding: 3px 8px;
+  font-size: 11px;
+  font-weight: 700;
+}
+
+.status--success {
+  color: #277052;
+  background: #edf6ef;
+}
+
+.status--failed {
+  color: #a04338;
+  background: #fff0ed;
+}
+
+.status--unstable {
+  color: #986617;
+  background: #fff7df;
+}
+
+.notice {
+  padding: 9px 24px;
+  border-bottom: 1px solid #e6d09c;
+  background: #fff7de;
+  color: #77561d;
+  font-size: 12px;
+}
+
+.layout {
+  display: grid;
+  min-height: calc(100vh - 76px);
+  grid-template-columns: 300px minmax(0, 1fr);
+}
+
+.sidebar {
+  position: sticky;
+  top: 76px;
+  overflow-y: auto;
+  height: calc(100vh - 76px);
+  border-right: 1px solid #d7d5cd;
+  background: #f7f6f1;
+}
+
+.sidebar section {
+  padding: 20px 16px;
+}
+
+.sidebar section + section {
+  border-top: 1px solid #dfddd5;
+}
+
+.section-heading {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 10px;
+}
+
+.section-heading h2 {
+  margin: 0;
+  font-size: 12px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.section-heading > span {
+  color: #888980;
+  font-size: 11px;
+}
+
+.document-list,
+.component-list {
+  display: grid;
+  gap: 4px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.document-list button,
+.component-list button {
+  display: grid;
+  width: 100%;
+  align-items: center;
+  border: 0;
+  border-radius: 9px;
+  background: transparent;
+  cursor: pointer;
+  text-align: left;
+}
+
+.document-list button {
+  grid-template-columns: 9px 1fr;
+  gap: 10px;
+  padding: 9px 10px;
+}
+
+.document-list button:hover,
+.component-list button:hover:not(:disabled) {
+  background: #eceae2;
+}
+
+.document-list button.is-active,
+.component-list button.is-active {
+  background: #e0e8e0;
+  color: #234b39;
+}
+
+.document-list strong,
+.component-list strong {
+  display: block;
+  overflow: hidden;
+  font-size: 12px;
+  font-weight: 650;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.document-list small,
+.component-list small {
+  display: block;
+  margin-top: 3px;
+  color: #7d7e75;
+  font-size: 10px;
+}
+
+.status-dot {
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  background: #999;
+}
+
+.status-dot--success {
+  background: #348361;
+}
+
+.status-dot--failed {
+  background: #b64b3f;
+}
+
+.status-dot--unstable {
+  background: #bd831c;
+}
+
+.text-button {
+  border: 0;
+  background: transparent;
+  color: #315f4b;
+  cursor: pointer;
+  font-size: 11px;
+}
+
+.text-button:disabled {
+  color: #aaa99f;
+  cursor: default;
+}
+
+.component-list {
+  counter-reset: components;
+}
+
+.component-list button {
+  grid-template-columns: 26px minmax(0, 1fr);
+  gap: 8px;
+  padding: 8px;
+}
+
+.component-list button:disabled {
+  cursor: not-allowed;
+  opacity: 0.55;
+}
+
+.component-index {
+  display: grid;
+  width: 24px;
+  height: 24px;
+  place-items: center;
+  border: 1px solid #d3d1c8;
+  border-radius: 50%;
+  color: #74766e;
+  font-family: Georgia, serif;
+  font-size: 11px;
+}
+
+.workspace {
+  display: grid;
+  min-width: 0;
+  align-content: start;
+  gap: 14px;
+  padding: 18px 20px 30px;
+}
+
+.document-header {
+  display: flex;
+  align-items: end;
+  justify-content: space-between;
+  gap: 20px;
+}
+
+.document-header h2 {
+  margin: 0;
+  font-family: Georgia, "Songti SC", serif;
+  font-size: 21px;
+  font-weight: 600;
+}
+
+.diff-shell,
+.changes-panel,
+.diagnostic-panel,
+.state-panel {
+  overflow: hidden;
+  border: 1px solid #d5d3ca;
+  border-radius: 13px;
+  background: #fbfaf7;
+  box-shadow: 0 12px 36px rgb(55 57 48 / 7%);
+}
+
+.diff-shell {
+  min-height: 510px;
+}
+
+.diff-labels {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  border-bottom: 1px solid #dcdbd3;
+  background: #f4f2ec;
+  color: #6f7168;
+  font-size: 11px;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+}
+
+.diff-labels span {
+  padding: 9px 14px;
+}
+
+.diff-labels span + span {
+  border-left: 1px solid #dcdbd3;
+}
+
+.diff-host,
+.diff-host > .cm-mergeView {
+  height: 510px;
+}
+
+.diff-host .cm-mergeViewEditors {
+  height: 100%;
+}
+
+.diff-host .cm-editor {
+  min-width: 0;
+  height: 100%;
+}
+
+.changes-panel {
+  min-height: 120px;
+}
+
+.changes-heading {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 24px;
+  padding: 15px 18px;
+  border-bottom: 1px solid #e0ded6;
+}
+
+.changes-heading h3 {
+  margin: 0;
+  font-size: 14px;
+}
+
+.changes-heading > p {
+  max-width: 58%;
+  margin: 0;
+  color: #77786f;
+  font-size: 11px;
+  line-height: 1.5;
+}
+
+.change-list {
+  display: grid;
+  max-height: 310px;
+  gap: 1px;
+  overflow-y: auto;
+  margin: 0;
+  padding: 0;
+  background: #e4e2da;
+  list-style: none;
+}
+
+.change-list button {
+  display: grid;
+  width: 100%;
+  grid-template-columns: 145px minmax(240px, 1fr) minmax(260px, 0.9fr);
+  align-items: center;
+  gap: 16px;
+  border: 0;
+  padding: 11px 18px;
+  background: #fbfaf7;
+  cursor: pointer;
+  text-align: left;
+}
+
+.change-list button:hover {
+  background: #f4f5ef;
+}
+
+.change-list button:disabled {
+  cursor: default;
+}
+
+.change-location {
+  color: #73756c;
+  font-size: 11px;
+}
+
+.change-list strong {
+  font-size: 12px;
+  font-weight: 600;
+}
+
+.change-sample {
+  display: flex;
+  min-width: 0;
+  align-items: center;
+  gap: 8px;
+  font-family: "SFMono-Regular", Consolas, monospace;
+  font-size: 11px;
+}
+
+.change-sample del,
+.change-sample ins {
+  overflow: hidden;
+  max-width: 46%;
+  border-radius: 4px;
+  padding: 2px 5px;
+  text-decoration: none;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.change-sample del {
+  background: #f9ded9;
+  color: #913e34;
+}
+
+.change-sample ins {
+  background: #dcecdf;
+  color: #276348;
+}
+
+.quiet-message {
+  margin: 0;
+  padding: 22px 18px;
+  color: #77786f;
+  font-size: 12px;
+}
+
+.state-panel,
+.diagnostic-panel {
+  padding: 28px;
+}
+
+.state-panel {
+  display: grid;
+  min-height: 180px;
+  place-items: center;
+  align-content: center;
+  color: #66685f;
+}
+
+.state-panel p {
+  margin: 8px 0 0;
+}
+
+.state-panel--error {
+  border-color: #e2b6ae;
+  color: #8f3e34;
+}
+
+.loading-dot {
+  width: 11px;
+  height: 11px;
+  border-radius: 50%;
+  background: #3d735b;
+  box-shadow: 0 0 0 7px #dce9df;
+  animation: pulse 1.25s ease-in-out infinite;
+}
+
+.diagnostic-panel h3 {
+  margin-bottom: 8px;
+}
+
+.diagnostic-panel > p:not(.eyebrow) {
+  color: #686a61;
+  font-size: 13px;
+}
+
+.diagnostic-panel article {
+  display: grid;
+  grid-template-columns: 220px 1fr;
+  gap: 12px;
+  padding: 10px 0;
+  border-top: 1px solid #e0ded6;
+  font-size: 12px;
+}
+
+code {
+  border-radius: 4px;
+  padding: 1px 4px;
+  background: #eceae3;
+  font-family: "SFMono-Regular", Consolas, monospace;
+}
+
+@keyframes pulse {
+  0%,
+  100% {
+    opacity: 0.45;
+    transform: scale(0.82);
+  }
+
+  50% {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+@media (max-width: 1280px) {
+  .layout {
+    grid-template-columns: 270px minmax(0, 1fr);
+  }
+
+  .change-list button {
+    grid-template-columns: 125px minmax(180px, 1fr) minmax(220px, 0.8fr);
+  }
+}

reviewer/src/shared/api.ts

@@ -0,0 +1,113 @@
+export type RunStatus = "success" | "failed" | "unstable";
+
+export interface ComponentSummary {
+  component_position: number;
+  component_id: string;
+  version: string;
+  parameters: unknown;
+  applicability: string;
+  change_count: number;
+}
+
+export interface DocumentSummary {
+  document_id: string;
+  source_label: string;
+  status: RunStatus;
+  input_sha256: string;
+  current_sha256: string;
+  change_count: number;
+  source_available: boolean;
+  output_available: boolean;
+  availability_error: string | null;
+}
+
+export interface RunSummaryResponse {
+  schema_version: 1;
+  run: {
+    run_id: string;
+    run_date: string;
+    status: RunStatus;
+    started_at_utc: string;
+    completed_at_utc: string;
+    retention_until: string;
+  };
+  components: ComponentSummary[];
+  documents: DocumentSummary[];
+  summary: {
+    document_count: number;
+    success_count: number;
+    failed_count: number;
+    unstable_count: number;
+    change_count: number;
+  };
+  original_run_location_changed: boolean;
+}
+
+export interface ChangeDetail {
+  component_id: string;
+  component_version: string;
+  component_position: number;
+  proposal_ref: {
+    component_position: number;
+    snapshot_sha256: string;
+    proposal_index: number;
+  };
+  edit_index: number;
+  reason: string;
+  location: {
+    line: number;
+    column: number;
+  };
+  editor_range: {
+    start: number;
+    end: number;
+  } | null;
+  before: string;
+  after: string;
+}
+
+export interface RunErrorDetail {
+  component_id: string;
+  component_version: string;
+  component_position: number;
+  stage: "transform" | "final_review";
+  error_type: string;
+  message: string;
+}
+
+export interface ResidualProposalDetail {
+  component_id: string;
+  component_version: string;
+  component_position: number;
+  reason: string;
+  edit_count: number;
+}
+
+export interface DocumentComparisonResponse {
+  schema_version: 1;
+  document: DocumentSummary;
+  components: ComponentSummary[];
+  original_markdown: string | null;
+  cleaned_markdown: string | null;
+  changes: ChangeDetail[];
+  errors: RunErrorDetail[];
+  residual_proposals: ResidualProposalDetail[];
+}
+
+export interface ComponentStageResponse {
+  schema_version: 1;
+  document_id: string;
+  component: ComponentSummary;
+  before_sha256: string;
+  after_sha256: string;
+  before_markdown: string;
+  after_markdown: string;
+  changes: ChangeDetail[];
+}
+
+export interface ApiErrorResponse {
+  error: {
+    code: string;
+    message: string;
+  };
+}

reviewer/tests/App.test.tsx

@@ -0,0 +1,256 @@
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { App } from "../src/client/App.js";
+import type {
+  ComponentStageResponse,
+  DocumentComparisonResponse,
+  RunSummaryResponse,
+} from "../src/shared/api.js";
+
+vi.mock("../src/client/DiffView.js", () => ({
+  DiffView: ({ beforeLabel, afterLabel }: { beforeLabel: string; afterLabel: string }) => (
+    <div data-testid="diff-view">
+      {beforeLabel} / {afterLabel}
+    </div>
+  ),
+}));
+
+const components = [
+  {
+    component_position: 0,
+    component_id: "paper.rule",
+    version: "1.0.0",
+    parameters: [],
+    applicability: "替换测试单词。",
+    change_count: 1,
+  },
+  {
+    component_position: 1,
+    component_id: "paper.zero",
+    version: "1.0.0",
+    parameters: [],
+    applicability: "不修改当前测试文档。",
+    change_count: 0,
+  },
+];
+
+const documentSummary = {
+  document_id: "paper",
+  source_label: "inputs/paper.md",
+  status: "success" as const,
+  input_sha256: "1".repeat(64),
+  current_sha256: "2".repeat(64),
+  change_count: 1,
+  source_available: true,
+  output_available: true,
+  availability_error: null,
+};
+
+const runResponse: RunSummaryResponse = {
+  schema_version: 1,
+  run: {
+    run_id: "review-run",
+    run_date: "2026-08-23",
+    status: "success",
+    started_at_utc: "2026-08-23T01:00:00Z",
+    completed_at_utc: "2026-08-23T01:01:00Z",
+    retention_until: "2026-09-22T01:01:00Z",
+  },
+  components,
+  documents: [documentSummary],
+  summary: {
+    document_count: 1,
+    success_count: 1,
+    failed_count: 0,
+    unstable_count: 0,
+    change_count: 1,
+  },
+  original_run_location_changed: false,
+};
+
+const change = {
+  component_id: "paper.rule",
+  component_version: "1.0.0",
+  component_position: 0,
+  proposal_ref: {
+    component_position: 0,
+    snapshot_sha256: "1".repeat(64),
+    proposal_index: 0,
+  },
+  edit_index: 0,
+  reason: "替换测试单词",
+  location: { line: 1, column: 3 },
+  editor_range: { start: 0, end: 3 },
+  before: "old",
+  after: "new",
+};
+
+const documentResponse: DocumentComparisonResponse = {
+  schema_version: 1,
+  document: documentSummary,
+  components,
+  original_markdown: "old",
+  cleaned_markdown: "new",
+  changes: [change],
+  errors: [],
+  residual_proposals: [],
+};
+
+const stageResponse: ComponentStageResponse = {
+  schema_version: 1,
+  document_id: "paper",
+  component: components[0]!,
+  before_sha256: "1".repeat(64),
+  after_sha256: "2".repeat(64),
+  before_markdown: "old",
+  after_markdown: "new",
+  changes: [change],
+};
+
+function response(payload: unknown, status = 200): Response {
+  return new Response(JSON.stringify(payload), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+describe("App", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("shows the run, document comparison, component order and component stage", async () => {
+    const fetchMock = vi.fn((input: string | URL | Request) => {
+      const pathname =
+        typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+      if (pathname === "/api/v1/run") {
+        return Promise.resolve(response(runResponse));
+      }
+      if (pathname.endsWith("/components/0")) {
+        return Promise.resolve(response(stageResponse));
+      }
+      return Promise.resolve(response(documentResponse));
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    render(<App />);
+
+    expect(await screen.findByRole("heading", { name: "review-run" })).toBeInTheDocument();
+    expect(await screen.findByTestId("diff-view")).toHaveTextContent("清洗前 / 清洗后");
+    expect(screen.getByText("paper.rule")).toBeInTheDocument();
+    expect(screen.getByText("paper.zero")).toBeInTheDocument();
+    expect(screen.getByText("替换测试单词")).toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole("button", { name: /paper\.rule/ }));
+    await waitFor(() => {
+      expect(fetchMock).toHaveBeenCalledWith(expect.stringContaining("components/0"), expect.anything());
+    });
+    expect(await screen.findByTestId("diff-view")).toHaveTextContent("组件 1 执行前 / 组件 1 执行后");
+  });
+
+  it("shows API failures without rendering document text", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(() =>
+        Promise.resolve(
+          response({ error: { code: "unsupported_schema", message: "不支持这个产物版本。" } }, 409),
+        ),
+      ),
+    );
+
+    render(<App />);
+
+    expect(await screen.findByRole("alert")).toHaveTextContent("不支持这个产物版本");
+    expect(screen.queryByTestId("diff-view")).not.toBeInTheDocument();
+  });
+
+  it("shows failed audit evidence without inventing a cleaned result", async () => {
+    const failedSummary = {
+      ...documentSummary,
+      status: "failed" as const,
+      current_sha256: documentSummary.input_sha256,
+      change_count: 0,
+      output_available: false,
+    };
+    const failedRun: RunSummaryResponse = {
+      ...runResponse,
+      run: { ...runResponse.run, status: "failed" },
+      documents: [failedSummary],
+      summary: {
+        document_count: 1,
+        success_count: 0,
+        failed_count: 1,
+        unstable_count: 0,
+        change_count: 0,
+      },
+    };
+    const failedDocument: DocumentComparisonResponse = {
+      schema_version: 1,
+      document: failedSummary,
+      components: components.map((component) => ({ ...component, change_count: 0 })),
+      original_markdown: "原文",
+      cleaned_markdown: null,
+      changes: [],
+      errors: [
+        {
+          component_id: "paper.rule",
+          component_version: "1.0.0",
+          component_position: 0,
+          stage: "transform",
+          error_type: "SyntheticError",
+          message: "测试组件失败。",
+        },
+      ],
+      residual_proposals: [],
+    };
+    vi.stubGlobal(
+      "fetch",
+      vi.fn((input: string | URL | Request) => {
+        const pathname =
+          typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+        return Promise.resolve(response(pathname === "/api/v1/run" ? failedRun : failedDocument));
+      }),
+    );
+
+    render(<App />);
+
+    expect(await screen.findByRole("heading", { name: "失败文档只展示审计证据" })).toBeInTheDocument();
+    expect(screen.getByText("测试组件失败。")).toBeInTheDocument();
+    expect(screen.queryByTestId("diff-view")).not.toBeInTheDocument();
+  });
+
+  it("keeps audit details visible when a successful run has lost its original source", async () => {
+    const unavailableSummary = {
+      ...documentSummary,
+      source_available: false,
+      availability_error: "原文路径已经失效。",
+    };
+    const unavailableRun: RunSummaryResponse = {
+      ...runResponse,
+      documents: [unavailableSummary],
+    };
+    const unavailableDocument: DocumentComparisonResponse = {
+      ...documentResponse,
+      document: unavailableSummary,
+      original_markdown: null,
+      changes: [{ ...change, editor_range: null }],
+    };
+    vi.stubGlobal(
+      "fetch",
+      vi.fn((input: string | URL | Request) => {
+        const pathname =
+          typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+        return Promise.resolve(
+          response(pathname === "/api/v1/run" ? unavailableRun : unavailableDocument),
+        );
+      }),
+    );
+
+    render(<App />);
+
+    expect(await screen.findByRole("alert")).toHaveTextContent("原文路径已经失效");
+    expect(screen.getByText("替换测试单词")).toBeInTheDocument();
+    expect(screen.queryByTestId("diff-view")).not.toBeInTheDocument();
+  });
+});

reviewer/tests/DiffView.test.tsx

@@ -0,0 +1,21 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { DiffView } from "../src/client/DiffView.js";
+
+describe("DiffView", () => {
+  it("keeps Markdown and raw HTML as inert editor text", () => {
+    render(
+      <DiffView
+        before={'# title\n<img src="https://example.com/private.png" onerror="alert(1)">'}
+        after={'# title\n<script>alert("x")</script>'}
+        beforeLabel="清洗前"
+        afterLabel="清洗后"
+      />,
+    );
+
+    expect(screen.getByRole("region", { name: "清洗前与清洗后对比" })).toBeInTheDocument();
+    expect(document.querySelector("img")).toBeNull();
+    expect(document.querySelector("script")).toBeNull();
+  });
+});

reviewer/tests/api-client.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { fetchRun } from "../src/client/api-client.js";
+
+describe("API response validation", () => {
+  it("rejects a successful HTTP response with an unknown schema", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(() =>
+        Promise.resolve(
+          new Response(JSON.stringify({ schema_version: 2 }), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+          }),
+        ),
+      ),
+    );
+
+    await expect(fetchRun()).rejects.toMatchObject({
+      code: "invalid_response",
+    });
+  });
+});

reviewer/tests/setup.ts

@@ -0,0 +1,6 @@
+import "@testing-library/jest-dom/vitest";
+
+import { afterEach } from "vitest";
+import { cleanup } from "@testing-library/react";
+
+afterEach(() => cleanup());

reviewer/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "useDefineForClassFields": true,
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": false,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "types": ["node", "vite/client", "vitest/globals", "@testing-library/jest-dom/vitest"]
+  },
+  "include": ["src", "tests", "vite.config.ts"]
+}

reviewer/vite.config.ts

@@ -0,0 +1,29 @@
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    host: "127.0.0.1",
+    port: 5173,
+    strictPort: true,
+    proxy: {
+      "/api": {
+        target: "http://127.0.0.1:4174",
+        changeOrigin: true,
+        configure(proxy) {
+          proxy.on("proxyReq", (request) => request.removeHeader("origin"));
+        },
+      },
+    },
+  },
+  build: {
+    outDir: "dist",
+    emptyOutDir: true,
+  },
+  test: {
+    environment: "jsdom",
+    setupFiles: "./tests/setup.ts",
+    css: true,
+  },
+});

src/mdpolish/_artifact_replay.py

@@ -0,0 +1,217 @@
+"""Pure replay of recorded artifact changes against an exact Markdown snapshot."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mdpolish.models import markdown_sha256
+
+
+class ReplayError(ValueError):
+    """A recorded change chain cannot be replayed without losing trust."""
+
+
+@dataclass(frozen=True, slots=True)
+class ReplayComponent:
+    """The component identity needed to validate recorded changes."""
+
+    component_id: str
+    version: str
+
+
+@dataclass(frozen=True, slots=True)
+class ReplayChange:
+    """One artifact edit expressed with Python Unicode code-point indexes."""
+
+    component_id: str
+    component_version: str
+    component_position: int
+    proposal_component_position: int
+    proposal_snapshot_sha256: str
+    proposal_index: int
+    edit_index: int
+    start: int
+    end: int
+    before: str
+    after: str
+    before_sha256: str
+    after_sha256: str
+
+
+@dataclass(frozen=True, slots=True)
+class LocatedChange:
+    """A replayed edit with human and browser-editor coordinates."""
+
+    change: ReplayChange
+    line: int
+    column: int
+    editor_start: int
+    editor_end: int
+
+
+@dataclass(frozen=True, slots=True)
+class ReplayStage:
+    """The exact snapshots immediately before and after one component."""
+
+    component_position: int
+    before_sha256: str
+    after_sha256: str
+    before_markdown: str
+    after_markdown: str
+    changes: tuple[LocatedChange, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ReplayResult:
+    """The verified final snapshot, locations and optional component stages."""
+
+    current_markdown: str
+    changes: tuple[LocatedChange, ...]
+    stages: tuple[ReplayStage, ...]
+
+
+def _line_column(markdown: str, offset: int) -> tuple[int, int]:
+    if offset < 0 or offset > len(markdown):
+        raise ReplayError("a change offset is outside its recorded snapshot")
+
+    line = 1
+    column = 1
+    position = 0
+    while position < offset:
+        character = markdown[position]
+        if character == "\r":
+            line += 1
+            column = 1
+            if position + 1 < offset and markdown[position + 1] == "\n":
+                position += 2
+            else:
+                position += 1
+        elif character == "\n":
+            line += 1
+            column = 1
+            position += 1
+        else:
+            column += 1
+            position += 1
+    return line, column
+
+
+def _utf16_offset(markdown: str, offset: int) -> int:
+    return len(markdown[:offset].encode("utf-16-le")) // 2
+
+
+def _changes_conflict(left: ReplayChange, right: ReplayChange) -> bool:
+    if left.start == left.end and right.start == right.end:
+        return left.start == right.start
+    if left.start == left.end:
+        return right.start <= left.start <= right.end
+    if right.start == right.end:
+        return left.start <= right.start <= left.end
+    return max(left.start, right.start) < min(left.end, right.end)
+
+
+def replay_change_chain(
+    *,
+    input_markdown: str,
+    input_sha256: str,
+    components: tuple[ReplayComponent, ...],
+    changes: tuple[ReplayChange, ...],
+    current_sha256: str,
+    current_markdown: str | None,
+    include_zero_change_stages: bool,
+) -> ReplayResult:
+    """Verify and replay a complete recorded chain without file I/O."""
+    if markdown_sha256(input_markdown) != input_sha256:
+        raise ReplayError("input Markdown does not match the recorded input hash")
+
+    previous_position = -1
+    for change in changes:
+        if change.component_position < previous_position:
+            raise ReplayError("recorded changes are not in component order")
+        previous_position = change.component_position
+
+    current = input_markdown
+    located_changes: list[LocatedChange] = []
+    stages: list[ReplayStage] = []
+    cursor = 0
+
+    for component_position, component in enumerate(components):
+        before_markdown = current
+        batch: list[ReplayChange] = []
+        while cursor < len(changes) and changes[cursor].component_position == component_position:
+            batch.append(changes[cursor])
+            cursor += 1
+
+        batch_locations: list[LocatedChange] = []
+        if batch:
+            first = batch[0]
+            if markdown_sha256(current) != first.before_sha256:
+                raise ReplayError("a change batch does not follow the recorded snapshot chain")
+
+            for change in batch:
+                if change.component_id != component.component_id or change.component_version != component.version:
+                    raise ReplayError("a change identity does not match the recorded component")
+                if change.proposal_component_position != component_position:
+                    raise ReplayError("a change proposal reference has the wrong component position")
+                if change.proposal_snapshot_sha256 != change.before_sha256:
+                    raise ReplayError("a change proposal reference targets the wrong snapshot")
+                if change.before_sha256 != first.before_sha256 or change.after_sha256 != first.after_sha256:
+                    raise ReplayError("a change batch contains inconsistent snapshot hashes")
+                if change.start < 0 or change.end < change.start or change.end > len(current):
+                    raise ReplayError("a change span is outside its recorded snapshot")
+                if len(change.before) != change.end - change.start:
+                    raise ReplayError("a change before value does not match its span length")
+                if current[change.start : change.end] != change.before:
+                    raise ReplayError("a change before value does not match its recorded snapshot")
+                line, column = _line_column(current, change.start)
+                batch_locations.append(
+                    LocatedChange(
+                        change=change,
+                        line=line,
+                        column=column,
+                        editor_start=_utf16_offset(current, change.start),
+                        editor_end=_utf16_offset(current, change.end),
+                    )
+                )
+
+            for left_index, left in enumerate(batch):
+                for right in batch[left_index + 1 :]:
+                    if _changes_conflict(left, right):
+                        raise ReplayError("a change batch contains conflicting edit ranges")
+
+            application_order = sorted(
+                batch,
+                key=lambda change: (
+                    change.start,
+                    change.end,
+                    change.proposal_index,
+                    change.edit_index,
+                ),
+                reverse=True,
+            )
+            for change in application_order:
+                current = current[: change.start] + change.after + current[change.end :]
+            if markdown_sha256(current) != first.after_sha256:
+                raise ReplayError("replayed changes do not produce the recorded batch hash")
+
+        located_changes.extend(batch_locations)
+        if include_zero_change_stages or batch:
+            stages.append(
+                ReplayStage(
+                    component_position=component_position,
+                    before_sha256=markdown_sha256(before_markdown),
+                    after_sha256=markdown_sha256(current),
+                    before_markdown=before_markdown,
+                    after_markdown=current,
+                    changes=tuple(batch_locations),
+                )
+            )
+
+    if cursor != len(changes):
+        raise ReplayError("a change has no matching component position")
+    if markdown_sha256(current) != current_sha256:
+        raise ReplayError("replayed changes do not produce the recorded current hash")
+    if current_markdown is not None and current != current_markdown:
+        raise ReplayError("replayed changes do not produce the recorded current snapshot")
+
+    return ReplayResult(current_markdown=current, changes=tuple(located_changes), stages=tuple(stages))

src/mdpolish/artifact_store.py

@@ -131,7 +131,9 @@ def _validate_bundle(
     *,
     run_date: str,
     run_id: str,
+    run_directory: Path,
     manifest_json: bytes,
+    review_locator_json: bytes,
     documents: tuple[StoredDocument, ...],
 ) -> None:
     manifest = _json_object(manifest_json, "manifest")
@@ -216,6 +218,50 @@ def _validate_bundle(
     if run.get("status") != overall_status or manifest.get("summary") != expected_summary:
         raise ArtifactStoreError("manifest status or summary does not match its documents")
 
+    locator = _json_object(review_locator_json, "review locator")
+    if locator.get("schema_version") != 1:
+        raise ArtifactStoreError("review locator schema_version must be 1")
+    locator_run = _nested_object(locator, "run", "review locator")
+    expected_run = {
+        "run_id": run_id,
+        "run_directory": str(run_directory.resolve(strict=False)),
+        "manifest_path": "manifest.json",
+    }
+    if locator_run != expected_run:
+        raise ArtifactStoreError("review locator run identity does not match the target path")
+
+    locator_documents = locator.get("documents")
+    if not isinstance(locator_documents, list) or len(locator_documents) != len(documents):
+        raise ArtifactStoreError("review locator documents do not match the stored documents")
+    for position, document in enumerate(documents):
+        raw_locator_document = locator_documents[position]
+        if not isinstance(raw_locator_document, dict) or not all(
+            isinstance(key, str) for key in raw_locator_document
+        ):
+            raise ArtifactStoreError("review locator documents must be JSON objects")
+        locator_document = cast(dict[str, object], raw_locator_document)
+        source_path_value = locator_document.get("source_path")
+        if not isinstance(source_path_value, str) or "\0" in source_path_value:
+            raise ArtifactStoreError("review locator source_path must be an absolute path")
+        source_path = Path(source_path_value)
+        if not source_path.is_absolute() or source_path.resolve(strict=False) != source_path:
+            raise ArtifactStoreError("review locator source_path must be an absolute resolved path")
+
+        manifest_index = cast(dict[str, object], document_indexes[position])
+        expected_locator_document = {
+            "document_id": document.document_id,
+            "source_path": source_path_value,
+            "input_sha256": manifest_index.get("input_sha256"),
+        }
+        if locator_document != expected_locator_document:
+            raise ArtifactStoreError("review locator document identity does not match the manifest")
+        try:
+            source_bytes = source_path.read_bytes()
+        except OSError as error:
+            raise ArtifactStoreError("review locator source_path must identify a readable regular file") from error
+        if not source_path.is_file() or sha256(source_bytes).hexdigest() != manifest_index.get("input_sha256"):
+            raise ArtifactStoreError("review locator source file does not match its input hash")
+
 
 def _rename_no_replace(source: Path, target: Path) -> None:
     directory_fd = os.open(source.parent, os.O_RDONLY | os.O_DIRECTORY)
@@ -235,6 +281,7 @@ def publish_run(
     run_date: str,
     run_id: str,
     manifest_json: bytes,
+    review_locator_json: bytes,
     documents: tuple[StoredDocument, ...],
 ) -> Path:
     """Publish one complete run directory without replacing an existing run."""
@@ -256,7 +303,9 @@ def publish_run(
     _validate_bundle(
         run_date=run_date,
         run_id=run_id,
+        run_directory=artifacts_root / run_date / "runs" / run_id,
         manifest_json=manifest_json,
+        review_locator_json=review_locator_json,
         documents=documents,
     )
 
@@ -279,6 +328,7 @@ def publish_run(
                 _write_private_file(document_directory / "changes.diff", document.diff)
 
         _write_private_file(temporary_directory / "manifest.json", manifest_json)
+        _write_private_file(temporary_directory / "review-locator.json", review_locator_json)
         _rename_no_replace(temporary_directory, final_directory)
     except Exception:
         if temporary_directory.exists():

src/mdpolish/experiment.py

@@ -276,6 +276,31 @@ def _manifest_payload(
     }
 
 
+def _review_locator_payload(
+    *,
+    run_id: str,
+    run_directory: Path,
+    documents: tuple[_PreparedDocument, ...],
+) -> JsonObject:
+    document_values: list[JsonValue] = [
+        {
+            "document_id": document.input.document_id,
+            "source_path": str(document.resolved_path),
+            "input_sha256": document.input_sha256,
+        }
+        for document in documents
+    ]
+    return {
+        "schema_version": 1,
+        "run": {
+            "run_id": run_id,
+            "run_directory": str(run_directory.resolve(strict=False)),
+            "manifest_path": "manifest.json",
+        },
+        "documents": document_values,
+    }
+
+
 def run_experiment(
     *,
     pipeline: Pipeline,
@@ -365,6 +390,13 @@ def run_experiment(
         run_date=run_date,
         run_id=run_id,
         manifest_json=encode_json(manifest),
+        review_locator_json=encode_json(
+            _review_locator_payload(
+                run_id=run_id,
+                run_directory=final_directory,
+                documents=prepared,
+            )
+        ),
         documents=stored_documents,
     )
 

src/mdpolish/reporting.py

@@ -7,6 +7,12 @@ from dataclasses import dataclass
 from difflib import unified_diff
 from typing import TypeAlias
 
+from mdpolish._artifact_replay import (
+    ReplayChange,
+    ReplayComponent,
+    ReplayError,
+    replay_change_chain,
+)
 from mdpolish.models import (
     Change,
     ComponentInfo,
@@ -17,15 +23,13 @@ from mdpolish.models import (
     RunStatus,
     TextEdit,
     TransformResult,
-    markdown_sha256,
 )
 
 JsonValue: TypeAlias = bool | int | float | str | list["JsonValue"] | dict[str, "JsonValue"] | None
 JsonObject: TypeAlias = dict[str, JsonValue]
 
 
-class ReportingError(ValueError):
+ReportingError = ReplayError
-    """A core result cannot be represented without losing its audit contract."""
 
 
 @dataclass(frozen=True, slots=True)
@@ -115,99 +119,38 @@ def _run_error_json(error: RunError) -> JsonObject:
     }
 
 
-def _line_column(markdown: str, offset: int) -> tuple[int, int]:
-    if offset < 0 or offset > len(markdown):
-        raise ReportingError("a change offset is outside its recorded snapshot")
-
-    line = 1
-    column = 1
-    position = 0
-    while position < offset:
-        character = markdown[position]
-        if character == "\r":
-            line += 1
-            column = 1
-            if position + 1 < offset and markdown[position + 1] == "\n":
-                position += 2
-            else:
-                position += 1
-        elif character == "\n":
-            line += 1
-            column = 1
-            position += 1
-        else:
-            column += 1
-            position += 1
-    return line, column
-
-
-def _validate_change_identity(change: Change, components: tuple[ComponentInfo, ...]) -> None:
-    if change.component_position < 0 or change.component_position >= len(components):
-        raise ReportingError("a change has no matching component position")
-    component = components[change.component_position]
-    if change.component_id != component.component_id or change.component_version != component.version:
-        raise ReportingError("a change identity does not match the recorded component")
-    if change.proposal_ref.component_position != change.component_position:
-        raise ReportingError("a change proposal reference has the wrong component position")
-    if change.proposal_ref.snapshot_sha256 != change.before_sha256:
-        raise ReportingError("a change proposal reference targets the wrong snapshot")
-
-
 def _replay_changes(input_markdown: str, result: TransformResult) -> tuple[tuple[tuple[int, int], ...], str]:
-    if markdown_sha256(input_markdown) != result.input_sha256:
-        raise ReportingError("input Markdown does not match the transform result")
-
-    current = input_markdown
-    locations: list[tuple[int, int]] = []
-    cursor = 0
-    while cursor < len(result.changes):
-        first = result.changes[cursor]
-        batch_key = (first.component_position, first.before_sha256, first.after_sha256)
-        batch: list[Change] = []
-        while cursor < len(result.changes):
-            candidate = result.changes[cursor]
-            candidate_key = (candidate.component_position, candidate.before_sha256, candidate.after_sha256)
-            if candidate_key != batch_key:
-                break
-            batch.append(candidate)
-            cursor += 1
-
-        if markdown_sha256(current) != first.before_sha256:
-            raise ReportingError("a change batch does not follow the recorded snapshot chain")
-
-        for change in batch:
-            _validate_change_identity(change, result.components)
-            if change.before_sha256 != first.before_sha256 or change.after_sha256 != first.after_sha256:
-                raise ReportingError("a change batch contains inconsistent snapshot hashes")
-            if change.span.end > len(current):
-                raise ReportingError("a change span is outside its recorded snapshot")
-            if len(change.before) != change.span.end - change.span.start:
-                raise ReportingError("a change before value does not match its span length")
-            if current[change.span.start : change.span.end] != change.before:
-                raise ReportingError("a change before value does not match its recorded snapshot")
-            locations.append(_line_column(current, change.span.start))
-
-        application_order = sorted(
-            batch,
-            key=lambda change: (
-                change.span.start,
-                change.span.end,
-                change.proposal_ref.proposal_index,
-                change.edit_index,
-            ),
-            reverse=True,
-        )
-        for change in application_order:
-            current = current[: change.span.start] + change.after + current[change.span.end :]
-        if markdown_sha256(current) != first.after_sha256:
-            raise ReportingError("replayed changes do not produce the recorded batch hash")
-
     current_markdown = result.output_markdown if result.status is RunStatus.SUCCESS else result.partial_markdown
     if current_markdown is None:
         raise ReportingError("a transform result does not contain its status-specific Markdown")
-    if current != current_markdown or markdown_sha256(current) != result.current_sha256:
+    replayed = replay_change_chain(
-        raise ReportingError("replayed changes do not produce the transform result's current snapshot")
+        input_markdown=input_markdown,
-    return tuple(locations), current
+        input_sha256=result.input_sha256,
+        components=tuple(ReplayComponent(item.component_id, item.version) for item in result.components),
+        changes=tuple(
+            ReplayChange(
+                component_id=change.component_id,
+                component_version=change.component_version,
+                component_position=change.component_position,
+                proposal_component_position=change.proposal_ref.component_position,
+                proposal_snapshot_sha256=change.proposal_ref.snapshot_sha256,
+                proposal_index=change.proposal_ref.proposal_index,
+                edit_index=change.edit_index,
+                start=change.span.start,
+                end=change.span.end,
+                before=change.before,
+                after=change.after,
+                before_sha256=change.before_sha256,
+                after_sha256=change.after_sha256,
+            )
+            for change in result.changes
+        ),
+        current_sha256=result.current_sha256,
+        current_markdown=current_markdown,
+        include_zero_change_stages=False,
+    )
+    locations = tuple((item.line, item.column) for item in replayed.changes)
+    return locations, replayed.current_markdown
 
 
 def _change_json(change: Change, location: tuple[int, int]) -> JsonObject:

tests/__init__.py

@@ -0,0 +1 @@
+"""Test support package for repository-local integration fixtures."""

tests/reviewer_fixture.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import json
+from hashlib import sha256
+from pathlib import Path
+from typing import Any, TypedDict, cast
+
+
+class ReviewFixture(TypedDict):
+    run_directory: Path
+    source_path: Path
+    manifest_path: Path
+    locator_path: Path
+    result_path: Path
+    original: str
+    cleaned: str
+
+
+def digest(text: str) -> str:
+    return sha256(text.encode()).hexdigest()
+
+
+def write_json(path: Path, payload: object) -> None:
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+
+def read_json(path: Path) -> dict[str, Any]:
+    return cast(dict[str, Any], json.loads(path.read_text(encoding="utf-8")))
+
+
+def create_review_run(
+    root: Path,
+    *,
+    status: str = "success",
+    with_locator: bool = True,
+) -> ReviewFixture:
+    run_directory = root / "artifacts/2026-08-23/runs/review-run"
+    document_directory = run_directory / "documents/paper"
+    document_directory.mkdir(parents=True)
+    source_path = root / "paper.md"
+    original = "\ufeff😀 old\r\nCafe\u0301\n"
+    cleaned = "\ufeff😀 new\r\nCafe\u0301\n"
+    source_path.write_text(original, encoding="utf-8")
+    input_hash = digest(original)
+    current_hash = digest(cleaned) if status == "success" else input_hash
+    changes: list[dict[str, object]] = []
+    if status == "success":
+        changes.append(
+            {
+                "component_id": "paper.rule",
+                "component_version": "1.0.0",
+                "component_position": 0,
+                "proposal_ref": {
+                    "component_position": 0,
+                    "snapshot_sha256": input_hash,
+                    "proposal_index": 0,
+                },
+                "edit_index": 0,
+                "reason": "替换测试单词",
+                "span": {"start": 3, "end": 6},
+                "location": {"line": 1, "column": 4},
+                "before": "old",
+                "after": "new",
+                "before_sha256": input_hash,
+                "after_sha256": current_hash,
+            }
+        )
+    errors: list[dict[str, object]] = []
+    if status == "failed":
+        errors.append(
+            {
+                "component_id": "paper.rule",
+                "component_version": "1.0.0",
+                "component_position": 0,
+                "stage": "transform",
+                "error_type": "SyntheticError",
+                "message": "测试组件失败。",
+            }
+        )
+    residuals: list[dict[str, object]] = []
+    if status == "unstable":
+        residuals.append(
+            {
+                "component_id": "paper.rule",
+                "component_version": "1.0.0",
+                "component_position": 0,
+                "proposal_ref": {
+                    "component_position": 0,
+                    "snapshot_sha256": input_hash,
+                    "proposal_index": 0,
+                },
+                "proposal": {
+                    "snapshot_sha256": input_hash,
+                    "reason": "仍可替换测试单词",
+                    "edits": [
+                        {
+                            "snapshot_sha256": input_hash,
+                            "span": {"start": 3, "end": 6},
+                            "expected_text": "old",
+                            "replacement": "new",
+                        }
+                    ],
+                },
+            }
+        )
+    result = {
+        "schema_version": 1,
+        "document": {"document_id": "paper", "source_label": "inputs/paper.md"},
+        "status": status,
+        "input_sha256": input_hash,
+        "current_sha256": current_hash,
+        "changes": changes,
+        "errors": errors,
+        "residual_proposals": residuals,
+        "output": {
+            "cleaned_path": "cleaned.md" if status == "success" else None,
+            "diff_path": "changes.diff" if status == "success" else None,
+        },
+    }
+    result_path = document_directory / "result.json"
+    write_json(result_path, result)
+    if status == "success":
+        (document_directory / "cleaned.md").write_text(cleaned, encoding="utf-8")
+        (document_directory / "changes.diff").write_text("synthetic diff\n", encoding="utf-8")
+
+    manifest = {
+        "schema_version": 1,
+        "run": {
+            "run_id": "review-run",
+            "run_date": "2026-08-23",
+            "utc_offset": "+08:00",
+            "status": status,
+            "started_at_utc": "2026-08-23T01:00:00Z",
+            "completed_at_utc": "2026-08-23T01:01:00Z",
+            "retention_until": "2026-09-22T01:01:00Z",
+        },
+        "tool": {
+            "name": "mdpolish",
+            "package_version": "0.1.0",
+            "python_version": "3.13.11",
+            "platform": "linux-x86_64",
+            "git_commit": None,
+            "git_dirty": None,
+        },
+        "pipeline": {
+            "components": [
+                {
+                    "component_id": "paper.rule",
+                    "version": "1.0.0",
+                    "parameters": [],
+                    "applicability": "替换测试单词。",
+                },
+                {
+                    "component_id": "paper.zero",
+                    "version": "1.0.0",
+                    "parameters": [],
+                    "applicability": "不修改当前测试文档。",
+                },
+            ]
+        },
+        "documents": [
+            {
+                "document_id": "paper",
+                "source_label": "inputs/paper.md",
+                "status": status,
+                "input_sha256": input_hash,
+                "current_sha256": current_hash,
+                "change_count": len(changes),
+                "result_path": "documents/paper/result.json",
+                "cleaned_path": "documents/paper/cleaned.md" if status == "success" else None,
+                "diff_path": "documents/paper/changes.diff" if status == "success" else None,
+            }
+        ],
+        "summary": {
+            "document_count": 1,
+            "success_count": int(status == "success"),
+            "failed_count": int(status == "failed"),
+            "unstable_count": int(status == "unstable"),
+            "change_count": len(changes),
+        },
+    }
+    manifest_path = run_directory / "manifest.json"
+    write_json(manifest_path, manifest)
+    locator_path = run_directory / "review-locator.json"
+    if with_locator:
+        write_json(
+            locator_path,
+            {
+                "schema_version": 1,
+                "run": {
+                    "run_id": "review-run",
+                    "run_directory": str(run_directory.resolve()),
+                    "manifest_path": "manifest.json",
+                },
+                "documents": [
+                    {
+                        "document_id": "paper",
+                        "source_path": str(source_path.resolve()),
+                        "input_sha256": input_hash,
+                    }
+                ],
+            },
+        )
+    return {
+        "run_directory": run_directory,
+        "source_path": source_path,
+        "manifest_path": manifest_path,
+        "locator_path": locator_path,
+        "result_path": result_path,
+        "original": original,
+        "cleaned": cleaned,
+    }

tests/test_artifact_replay.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import replace
+
+import pytest
+
+from mdpolish._artifact_replay import (
+    ReplayChange,
+    ReplayComponent,
+    ReplayError,
+    replay_change_chain,
+)
+from mdpolish.models import markdown_sha256
+
+
+def change(
+    *,
+    component_position: int,
+    before_text: str,
+    after_text: str,
+    start: int,
+    end: int,
+    before_sha256: str,
+    after_sha256: str,
+    proposal_index: int = 0,
+    edit_index: int = 0,
+) -> ReplayChange:
+    return ReplayChange(
+        component_id=f"test.{component_position}",
+        component_version="1.0.0",
+        component_position=component_position,
+        proposal_component_position=component_position,
+        proposal_snapshot_sha256=before_sha256,
+        proposal_index=proposal_index,
+        edit_index=edit_index,
+        start=start,
+        end=end,
+        before=before_text,
+        after=after_text,
+        before_sha256=before_sha256,
+        after_sha256=after_sha256,
+    )
+
+
+def test_replay_builds_zero_change_stages_and_utf16_editor_ranges() -> None:
+    original = "\ufeff😀 old\r\nCafe\u0301"
+    final = "\ufeff😀 new\r\nCafe\u0301"
+    input_hash = markdown_sha256(original)
+    final_hash = markdown_sha256(final)
+    recorded = change(
+        component_position=0,
+        before_text="old",
+        after_text="new",
+        start=3,
+        end=6,
+        before_sha256=input_hash,
+        after_sha256=final_hash,
+    )
+
+    replayed = replay_change_chain(
+        input_markdown=original,
+        input_sha256=input_hash,
+        components=(ReplayComponent("test.0", "1.0.0"), ReplayComponent("test.1", "1.0.0")),
+        changes=(recorded,),
+        current_sha256=final_hash,
+        current_markdown=final,
+        include_zero_change_stages=True,
+    )
+
+    assert replayed.current_markdown == final
+    assert len(replayed.stages) == 2
+    assert replayed.stages[1].before_markdown == final
+    assert replayed.stages[1].after_markdown == final
+    assert replayed.stages[1].changes == ()
+    assert (replayed.changes[0].line, replayed.changes[0].column) == (1, 4)
+    assert (replayed.changes[0].editor_start, replayed.changes[0].editor_end) == (4, 7)
+
+
+def test_replay_uses_full_descending_application_key_not_record_order() -> None:
+    original = "abcd"
+    final = "aXXcYY"
+    input_hash = markdown_sha256(original)
+    final_hash = markdown_sha256(final)
+    right = change(
+        component_position=0,
+        before_text="d",
+        after_text="YY",
+        start=3,
+        end=4,
+        before_sha256=input_hash,
+        after_sha256=final_hash,
+        proposal_index=1,
+    )
+    left = change(
+        component_position=0,
+        before_text="b",
+        after_text="XX",
+        start=1,
+        end=2,
+        before_sha256=input_hash,
+        after_sha256=final_hash,
+    )
+
+    replayed = replay_change_chain(
+        input_markdown=original,
+        input_sha256=input_hash,
+        components=(ReplayComponent("test.0", "1.0.0"),),
+        changes=(right, left),
+        current_sha256=final_hash,
+        current_markdown=final,
+        include_zero_change_stages=True,
+    )
+
+    assert replayed.current_markdown == final
+
+
+@pytest.mark.parametrize(
+    ("mutate", "message"),
+    [
+        (lambda item: replace(item, component_position=2), "component position"),
+        (lambda item: replace(item, proposal_component_position=1), "proposal reference"),
+        (lambda item: replace(item, before="bad"), "recorded snapshot"),
+        (lambda item: replace(item, after_sha256="0" * 64), "batch hash"),
+    ],
+)
+def test_replay_rejects_untrusted_change_chains(
+    mutate: Callable[[ReplayChange], ReplayChange], message: str
+) -> None:
+    original = "old"
+    final = "new"
+    input_hash = markdown_sha256(original)
+    final_hash = markdown_sha256(final)
+    valid = change(
+        component_position=0,
+        before_text="old",
+        after_text="new",
+        start=0,
+        end=3,
+        before_sha256=input_hash,
+        after_sha256=final_hash,
+    )
+    tampered = mutate(valid)
+
+    with pytest.raises(ReplayError, match=message):
+        replay_change_chain(
+            input_markdown=original,
+            input_sha256=input_hash,
+            components=(ReplayComponent("test.0", "1.0.0"),),
+            changes=(tampered,),
+            current_sha256=final_hash,
+            current_markdown=final,
+            include_zero_change_stages=True,
+        )
+
+
+def test_replay_rejects_conflicting_ranges() -> None:
+    original = "abc"
+    input_hash = markdown_sha256(original)
+    first = change(
+        component_position=0,
+        before_text="ab",
+        after_text="x",
+        start=0,
+        end=2,
+        before_sha256=input_hash,
+        after_sha256="0" * 64,
+    )
+    second = change(
+        component_position=0,
+        before_text="bc",
+        after_text="y",
+        start=1,
+        end=3,
+        before_sha256=input_hash,
+        after_sha256="0" * 64,
+        proposal_index=1,
+    )
+
+    with pytest.raises(ReplayError, match="conflicting"):
+        replay_change_chain(
+            input_markdown=original,
+            input_sha256=input_hash,
+            components=(ReplayComponent("test.0", "1.0.0"),),
+            changes=(first, second),
+            current_sha256=input_hash,
+            current_markdown=None,
+            include_zero_change_stages=False,
+        )

tests/test_artifact_store.py

@@ -10,6 +10,8 @@ import pytest
 import mdpolish.artifact_store as artifact_store
 from mdpolish.artifact_store import ArtifactStoreError, StoredDocument, publish_run
 
+_SOURCE_BYTES = b"source\n"
+
 
 def stored_document(document_id: str = "paper", output: bytes | None = b"cleaned\n") -> StoredDocument:
     status = "success" if output is not None else "failed"
@@ -18,7 +20,7 @@ def stored_document(document_id: str = "paper", output: bytes | None = b"cleaned
         "schema_version": 1,
         "document": {"document_id": document_id, "source_label": f"inputs/{document_id}.md"},
         "status": status,
-        "input_sha256": "1" * 64,
+        "input_sha256": sha256(_SOURCE_BYTES).hexdigest(),
         "current_sha256": current_sha256,
         "changes": [],
         "errors": [] if status == "success" else [{"error_type": "SyntheticError"}],
@@ -82,15 +84,49 @@ def manifest_json(
     return (json.dumps(payload, indent=2) + "\n").encode()
 
 
+def review_locator_json(
+    artifacts_root: Path,
+    run_date: str,
+    run_id: str,
+    documents: tuple[StoredDocument, ...],
+) -> bytes:
+    source_root = artifacts_root.parent / f"{artifacts_root.name}-sources"
+    source_root.mkdir(exist_ok=True)
+    locator_documents: list[dict[str, object]] = []
+    for position, document in enumerate(documents):
+        source_path = source_root / f"{position}-{document.document_id}.md"
+        source_path.write_bytes(_SOURCE_BYTES)
+        report = json.loads(document.result_json)
+        locator_documents.append(
+            {
+                "document_id": document.document_id,
+                "source_path": str(source_path.resolve()),
+                "input_sha256": report["input_sha256"],
+            }
+        )
+    payload = {
+        "schema_version": 1,
+        "run": {
+            "run_id": run_id,
+            "run_directory": str((artifacts_root / run_date / "runs" / run_id).resolve()),
+            "manifest_path": "manifest.json",
+        },
+        "documents": locator_documents,
+    }
+    return (json.dumps(payload, indent=2) + "\n").encode()
+
+
 def test_publish_run_creates_private_date_layout_and_status_specific_files(tmp_path: Path) -> None:
     artifacts_root = tmp_path / "artifacts"
     documents = (stored_document("success"), stored_document("failed", None))
+    locator_json = review_locator_json(artifacts_root, "2026-08-22", "example-run", documents)
 
     run_directory = publish_run(
         artifacts_root=artifacts_root,
         run_date="2026-08-22",
         run_id="example-run",
         manifest_json=manifest_json("2026-08-22", "example-run", documents),
+        review_locator_json=locator_json,
         documents=documents,
     )
 
@@ -100,6 +136,7 @@ def test_publish_run_creates_private_date_layout_and_status_specific_files(tmp_p
     assert (run_directory / "documents/success/cleaned.md").read_bytes() == b"cleaned\n"
     assert (run_directory / "documents/success/changes.diff").read_bytes() == b""
     assert (run_directory / "documents/failed/result.json").is_file()
+    assert (run_directory / "review-locator.json").read_bytes() == locator_json
     assert not (run_directory / "documents/failed/cleaned.md").exists()
     assert not (run_directory / "documents/failed/changes.diff").exists()
 
@@ -121,11 +158,13 @@ def test_publish_run_rejects_existing_target_without_overwriting(tmp_path: Path)
     artifacts_root = tmp_path / "artifacts"
     documents = (stored_document(),)
     first_manifest = manifest_json("2026-08-22", "same-run", documents)
+    locator_json = review_locator_json(artifacts_root, "2026-08-22", "same-run", documents)
     run_directory = publish_run(
         artifacts_root=artifacts_root,
         run_date="2026-08-22",
         run_id="same-run",
         manifest_json=first_manifest,
+        review_locator_json=locator_json,
         documents=documents,
     )
 
@@ -135,6 +174,7 @@ def test_publish_run_rejects_existing_target_without_overwriting(tmp_path: Path)
             run_date="2026-08-22",
             run_id="same-run",
             manifest_json=first_manifest,
+            review_locator_json=locator_json,
             documents=documents,
         )
 
@@ -152,13 +192,15 @@ def test_publish_run_rejects_existing_target_without_overwriting(tmp_path: Path)
     ],
 )
 def test_publish_run_rejects_unsafe_date_and_run_id(tmp_path: Path, run_date: str, run_id: str) -> None:
+    artifacts_root = tmp_path / "artifacts"
     documents = (stored_document(),)
     with pytest.raises(ArtifactStoreError):
         publish_run(
-            artifacts_root=tmp_path / "artifacts",
+            artifacts_root=artifacts_root,
             run_date=run_date,
             run_id=run_id,
             manifest_json=manifest_json(run_date, run_id, documents),
+            review_locator_json=review_locator_json(artifacts_root, run_date, run_id, documents),
             documents=documents,
         )
 
@@ -166,22 +208,30 @@ def test_publish_run_rejects_unsafe_date_and_run_id(tmp_path: Path, run_date: st
 def test_publish_run_rejects_inconsistent_or_duplicate_document_artifacts(tmp_path: Path) -> None:
     valid = stored_document()
     bad_hash = StoredDocument("paper", valid.result_json, b"output", b"", "0" * 64)
+    first_artifacts_root = tmp_path / "artifacts-a"
     with pytest.raises(ArtifactStoreError, match="output hash"):
         publish_run(
-            artifacts_root=tmp_path / "artifacts-a",
+            artifacts_root=first_artifacts_root,
             run_date="2026-08-22",
             run_id="bad-hash",
             manifest_json=manifest_json("2026-08-22", "bad-hash", (bad_hash,)),
+            review_locator_json=review_locator_json(
+                first_artifacts_root, "2026-08-22", "bad-hash", (bad_hash,)
+            ),
             documents=(bad_hash,),
         )
 
     duplicates = (stored_document(), stored_document())
+    second_artifacts_root = tmp_path / "artifacts-b"
     with pytest.raises(ArtifactStoreError, match="unique"):
         publish_run(
-            artifacts_root=tmp_path / "artifacts-b",
+            artifacts_root=second_artifacts_root,
             run_date="2026-08-22",
             run_id="duplicate",
             manifest_json=manifest_json("2026-08-22", "duplicate", duplicates),
+            review_locator_json=review_locator_json(
+                second_artifacts_root, "2026-08-22", "duplicate", duplicates
+            ),
             documents=duplicates,
         )
 
@@ -189,32 +239,81 @@ def test_publish_run_rejects_inconsistent_or_duplicate_document_artifacts(tmp_pa
 def test_publish_run_rejects_manifest_path_or_document_mismatch(tmp_path: Path) -> None:
     documents = (stored_document(),)
     wrong_date = manifest_json("2026-08-21", "review", documents)
+    first_artifacts_root = tmp_path / "artifacts-a"
     with pytest.raises(ArtifactStoreError, match="identity"):
         publish_run(
-            artifacts_root=tmp_path / "artifacts-a",
+            artifacts_root=first_artifacts_root,
             run_date="2026-08-22",
             run_id="review",
             manifest_json=wrong_date,
+            review_locator_json=review_locator_json(
+                first_artifacts_root, "2026-08-22", "review", documents
+            ),
             documents=documents,
         )
 
     payload = json.loads(manifest_json("2026-08-22", "review", documents))
     payload["documents"][0]["change_count"] = 99
     mismatched_index = (json.dumps(payload, indent=2) + "\n").encode()
+    second_artifacts_root = tmp_path / "artifacts-b"
     with pytest.raises(ArtifactStoreError, match="index"):
         publish_run(
-            artifacts_root=tmp_path / "artifacts-b",
+            artifacts_root=second_artifacts_root,
             run_date="2026-08-22",
             run_id="review",
             manifest_json=mismatched_index,
+            review_locator_json=review_locator_json(
+                second_artifacts_root, "2026-08-22", "review", documents
+            ),
             documents=documents,
         )
 
 
+def test_publish_run_rejects_inconsistent_review_locator(tmp_path: Path) -> None:
+    artifacts_root = tmp_path / "artifacts"
+    documents = (stored_document(),)
+    locator = json.loads(review_locator_json(artifacts_root, "2026-08-22", "review", documents))
+    locator["documents"][0]["input_sha256"] = "0" * 64
+    inconsistent_locator = (json.dumps(locator, indent=2) + "\n").encode()
+
+    with pytest.raises(ArtifactStoreError, match="document identity"):
+        publish_run(
+            artifacts_root=artifacts_root,
+            run_date="2026-08-22",
+            run_id="review",
+            manifest_json=manifest_json("2026-08-22", "review", documents),
+            review_locator_json=inconsistent_locator,
+            documents=documents,
+        )
+
+    assert not artifacts_root.exists()
+
+
+def test_publish_run_rejects_source_changed_after_locator_creation(tmp_path: Path) -> None:
+    artifacts_root = tmp_path / "artifacts"
+    documents = (stored_document(),)
+    locator_json = review_locator_json(artifacts_root, "2026-08-22", "review", documents)
+    locator = json.loads(locator_json)
+    Path(locator["documents"][0]["source_path"]).write_bytes(b"changed\n")
+
+    with pytest.raises(ArtifactStoreError, match="input hash"):
+        publish_run(
+            artifacts_root=artifacts_root,
+            run_date="2026-08-22",
+            run_id="review",
+            manifest_json=manifest_json("2026-08-22", "review", documents),
+            review_locator_json=locator_json,
+            documents=documents,
+        )
+
+    assert not artifacts_root.exists()
+
+
 def test_publish_race_does_not_replace_a_new_target(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
+    artifacts_root = tmp_path / "artifacts"
     documents = (stored_document(),)
     original_rename = artifact_store._rename_no_replace
 
@@ -226,10 +325,11 @@ def test_publish_race_does_not_replace_a_new_target(
     monkeypatch.setattr(artifact_store, "_rename_no_replace", create_competing_target)
     with pytest.raises(ArtifactStoreError, match="already exists"):
         publish_run(
-            artifacts_root=tmp_path / "artifacts",
+            artifacts_root=artifacts_root,
             run_date="2026-08-22",
             run_id="raced",
             manifest_json=manifest_json("2026-08-22", "raced", documents),
+            review_locator_json=review_locator_json(artifacts_root, "2026-08-22", "raced", documents),
             documents=documents,
         )
 
@@ -253,14 +353,44 @@ def test_write_failure_cleans_temporary_directory_and_does_not_publish(
         original_write(path, content)
 
     monkeypatch.setattr(artifact_store, "_write_private_file", fail_second_write)
+    artifacts_root = tmp_path / "artifacts"
     documents = (stored_document(),)
 
     with pytest.raises(OSError, match="synthetic"):
         publish_run(
-            artifacts_root=tmp_path / "artifacts",
+            artifacts_root=artifacts_root,
             run_date="2026-08-22",
             run_id="broken",
             manifest_json=manifest_json("2026-08-22", "broken", documents),
+            review_locator_json=review_locator_json(artifacts_root, "2026-08-22", "broken", documents),
+            documents=documents,
+        )
+
+    runs_directory = tmp_path / "artifacts/2026-08-22/runs"
+    assert list(runs_directory.iterdir()) == []
+
+
+def test_locator_write_failure_does_not_publish(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    original_write = artifact_store._write_private_file
+
+    def fail_locator_write(path: Path, content: bytes) -> None:
+        if path.name == "review-locator.json":
+            raise OSError("synthetic locator write failure")
+        original_write(path, content)
+
+    monkeypatch.setattr(artifact_store, "_write_private_file", fail_locator_write)
+    artifacts_root = tmp_path / "artifacts"
+    documents = (stored_document(),)
+
+    with pytest.raises(OSError, match="locator"):
+        publish_run(
+            artifacts_root=artifacts_root,
+            run_date="2026-08-22",
+            run_id="locator-failure",
+            manifest_json=manifest_json("2026-08-22", "locator-failure", documents),
+            review_locator_json=review_locator_json(
+                artifacts_root, "2026-08-22", "locator-failure", documents
+            ),
             documents=documents,
         )
 

tests/test_experiment.py

@@ -109,6 +109,27 @@ def test_run_experiment_publishes_manifest_reports_diff_and_preserves_inputs(tmp
     assert (result.run_directory / "documents/second/changes.diff").read_bytes() == b""
 
     manifest = json.loads((result.run_directory / "manifest.json").read_bytes())
+    locator = json.loads((result.run_directory / "review-locator.json").read_bytes())
+    assert locator == {
+        "schema_version": 1,
+        "run": {
+            "run_id": "local-review",
+            "run_directory": str(result.run_directory.resolve()),
+            "manifest_path": "manifest.json",
+        },
+        "documents": [
+            {
+                "document_id": "first",
+                "source_path": str(first_path.resolve()),
+                "input_sha256": manifest["documents"][0]["input_sha256"],
+            },
+            {
+                "document_id": "second",
+                "source_path": str(second_path.resolve()),
+                "input_sha256": manifest["documents"][1]["input_sha256"],
+            },
+        ],
+    }
     assert manifest["run"]["run_date"] == "2026-08-22"
     assert manifest["run"]["utc_offset"] == "+08:00"
     assert manifest["run"]["started_at_utc"] == "2026-08-22T02:30:00Z"

tests/test_reviewer_artifacts.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, cast
+
+import pytest
+
+from reviewer.server import ReviewArtifactError, ReviewArtifacts
+from tests.reviewer_fixture import create_review_run, read_json, write_json
+
+
+def test_reviewer_returns_full_comparison_and_all_component_stages(tmp_path: Path) -> None:
+    fixture = create_review_run(tmp_path)
+    repository = ReviewArtifacts(fixture["run_directory"])
+
+    run = cast(dict[str, Any], repository.run_summary())
+    comparison = cast(dict[str, Any], repository.document_comparison("paper"))
+    changed = cast(dict[str, Any], repository.component_stage("paper", 0))
+    unchanged = cast(dict[str, Any], repository.component_stage("paper", 1))
+
+    assert run["summary"] == {
+        "document_count": 1,
+        "success_count": 1,
+        "failed_count": 0,
+        "unstable_count": 0,
+        "change_count": 1,
+    }
+    assert run["documents"][0]["source_available"] is True
+    assert comparison["original_markdown"] == fixture["original"]
+    assert comparison["cleaned_markdown"] == fixture["cleaned"]
+    assert comparison["changes"][0]["editor_range"] == {"start": 4, "end": 7}
+    assert changed["before_markdown"] == fixture["original"]
+    assert changed["after_markdown"] == fixture["cleaned"]
+    assert unchanged["before_markdown"] == fixture["cleaned"]
+    assert unchanged["after_markdown"] == fixture["cleaned"]
+    assert unchanged["changes"] == []
+
+
+@pytest.mark.parametrize("status", ["failed", "unstable"])
+def test_non_success_documents_expose_audit_but_no_formal_output(tmp_path: Path, status: str) -> None:
+    fixture = create_review_run(tmp_path, status=status)
+    repository = ReviewArtifacts(fixture["run_directory"])
+
+    comparison = cast(dict[str, Any], repository.document_comparison("paper"))
+
+    assert comparison["original_markdown"] == fixture["original"]
+    assert comparison["cleaned_markdown"] is None
+    if status == "failed":
+        assert comparison["errors"]
+        assert comparison["residual_proposals"] == []
+    else:
+        assert comparison["errors"] == []
+        assert comparison["residual_proposals"]
+    with pytest.raises(ReviewArtifactError, match="success"):
+        repository.component_stage("paper", 0)
+
+
+def test_historical_run_without_locator_reports_unavailable_source(tmp_path: Path) -> None:
+    fixture = create_review_run(tmp_path, with_locator=False)
+    repository = ReviewArtifacts(fixture["run_directory"])
+
+    summary = cast(dict[str, Any], repository.run_summary())
+
+    assert summary["documents"][0]["source_available"] is False
+    assert "review-locator.json" in summary["documents"][0]["availability_error"]
+    comparison = cast(dict[str, Any], repository.document_comparison("paper"))
+    assert comparison["original_markdown"] is None
+    assert comparison["cleaned_markdown"] == fixture["cleaned"]
+    assert comparison["changes"][0]["editor_range"] is None
+    with pytest.raises(ReviewArtifactError, match=r"review-locator\.json"):
+        repository.component_stage("paper", 0)
+
+
+def test_source_hash_change_is_not_silently_displayed(tmp_path: Path) -> None:
+    fixture = create_review_run(tmp_path)
+    repository = ReviewArtifacts(fixture["run_directory"])
+    source_path = fixture["source_path"]
+    assert isinstance(source_path, Path)
+    source_path.write_text("changed\n", encoding="utf-8")
+
+    summary = cast(dict[str, Any], repository.run_summary())
+
+    assert summary["documents"][0]["source_available"] is False
+    assert "哈希" in summary["documents"][0]["availability_error"]
+    comparison = cast(dict[str, Any], repository.document_comparison("paper"))
+    assert comparison["original_markdown"] is None
+    assert comparison["changes"][0]["editor_range"] is None
+    with pytest.raises(ReviewArtifactError, match="哈希"):
+        repository.component_stage("paper", 0)
+
+
+def test_reviewer_rejects_unknown_schema_and_artifact_path_escape(tmp_path: Path) -> None:
+    fixture = create_review_run(tmp_path)
+    manifest_path = fixture["manifest_path"]
+    assert isinstance(manifest_path, Path)
+    manifest = read_json(manifest_path)
+    manifest["schema_version"] = 2
+    write_json(manifest_path, manifest)
+
+    with pytest.raises(ReviewArtifactError) as unknown:
+        ReviewArtifacts(fixture["run_directory"])
+    assert unknown.value.code == "unsupported_schema"
+
+    second = create_review_run(tmp_path / "second")
+    second_manifest_path = second["manifest_path"]
+    assert isinstance(second_manifest_path, Path)
+    second_manifest = read_json(second_manifest_path)
+    second_manifest["documents"][0]["result_path"] = "../outside.json"
+    write_json(second_manifest_path, second_manifest)
+    with pytest.raises(ReviewArtifactError, match="路径"):
+        ReviewArtifacts(second["run_directory"])
+
+
+def test_reviewer_rejects_tampered_snapshot_chain_and_unknown_identity(tmp_path: Path) -> None:
+    fixture = create_review_run(tmp_path)
+    result_path = fixture["result_path"]
+    assert isinstance(result_path, Path)
+    result = read_json(result_path)
+    result["changes"][0]["after_sha256"] = "0" * 64
+    write_json(result_path, result)
+    repository = ReviewArtifacts(fixture["run_directory"])
+
+    with pytest.raises(ReviewArtifactError) as replay_error:
+        repository.document_comparison("paper")
+    assert replay_error.value.code == "untrusted_replay"
+
+    with pytest.raises(ReviewArtifactError) as document_error:
+        repository.document_comparison("missing")
+    assert document_error.value.http_status == 404
+    with pytest.raises(ReviewArtifactError) as component_error:
+        repository.component_stage("paper", 99)
+    assert component_error.value.http_status == 404

tests/test_reviewer_server.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import json
+import threading
+from collections.abc import Generator
+from http.client import HTTPConnection, HTTPResponse
+from pathlib import Path
+from typing import Any, cast
+
+import pytest
+
+from reviewer.server import ReviewArtifacts
+from reviewer.server.__main__ import create_server
+from tests.reviewer_fixture import ReviewFixture, create_review_run
+
+
+def request(
+    port: int,
+    method: str,
+    path: str,
+    *,
+    headers: dict[str, str] | None = None,
+) -> tuple[HTTPResponse, bytes]:
+    connection = HTTPConnection("127.0.0.1", port, timeout=3)
+    connection.request(method, path, headers=headers or {})
+    response = connection.getresponse()
+    content = response.read()
+    connection.close()
+    return response, content
+
+
+@pytest.fixture
+def running_server(tmp_path: Path) -> Generator[tuple[int, ReviewFixture], None, None]:
+    fixture = create_review_run(tmp_path)
+    static_root = tmp_path / "static"
+    (static_root / "assets").mkdir(parents=True)
+    (static_root / "index.html").write_text("<main>reviewer</main>\n", encoding="utf-8")
+    (static_root / "assets/app.js").write_text("export {};\n", encoding="utf-8")
+    repository = ReviewArtifacts(fixture["run_directory"])
+    server = create_server(repository, static_root)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        yield server.server_address[1], fixture
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=3)
+
+
+def test_server_exposes_same_origin_api_and_static_build(
+    running_server: tuple[int, ReviewFixture],
+) -> None:
+    port, fixture = running_server
+
+    api_response, api_content = request(port, "GET", "/api/v1/run")
+    page_response, page_content = request(port, "GET", "/")
+    asset_response, _ = request(port, "HEAD", "/assets/app.js")
+
+    payload = cast(dict[str, Any], json.loads(api_content))
+    assert api_response.status == 200
+    assert payload["run"]["run_id"] == "review-run"
+    assert str(fixture["source_path"]) not in api_content.decode()
+    assert api_response.getheader("Access-Control-Allow-Origin") is None
+    assert api_response.getheader("Cache-Control") == "no-store"
+    assert "default-src 'self'" in cast(str, api_response.getheader("Content-Security-Policy"))
+    assert page_response.status == 200
+    assert page_content == b"<main>reviewer</main>\n"
+    assert asset_response.status == 200
+    assert asset_response.getheader("Content-Type") == "text/javascript; charset=utf-8"
+
+
+@pytest.mark.parametrize(
+    ("method", "path", "headers", "status", "code"),
+    [
+        ("POST", "/api/v1/run", None, 405, "method_not_allowed"),
+        ("GET", "/api/v1/run", {"Host": "example.com"}, 403, "invalid_origin"),
+        (
+            "GET",
+            "/api/v1/run",
+            {"Origin": "http://example.com"},
+            403,
+            "invalid_origin",
+        ),
+        ("GET", "/api/v1/documents/missing", None, 404, "unknown_document"),
+        ("GET", "/api/v1/documents/paper/components/99", None, 404, "unknown_component"),
+        ("GET", "/assets/missing.js", None, 404, "not_found"),
+        ("GET", "/..%2Fsecret.txt", None, 404, "not_found"),
+    ],
+)
+def test_server_rejects_unsafe_or_unknown_requests(
+    running_server: tuple[int, ReviewFixture],
+    method: str,
+    path: str,
+    headers: dict[str, str] | None,
+    status: int,
+    code: str,
+) -> None:
+    port, _ = running_server
+
+    response, content = request(port, method, path, headers=headers)
+    payload = cast(dict[str, Any], json.loads(content))
+
+    assert response.status == status
+    assert payload["error"]["code"] == code