110 lines
6.2 KiB
Markdown
110 lines
6.2 KiB
Markdown
# 本地 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)。
|