# 运行本地 ClinDB 第一批完整清洗实验

## 1. 适用范围

本指南只运行仓库内已经批准的 first-batch 实验脚本：

- 输入：`data/md/` 中的 `dmp.md`、`ejhf.md`、`jama.md`、`sim.md` 和 `springer.md`；
- 流水线：`design/0006` 固定的 8 个组件和顺序；
- 输出：`artifacts/<YYYY-MM-DD>/runs/<run_id>/`；
- 输入只读，不覆盖原文件；
- 不读取或复制图片，不处理 `/home/lihaoze/gov_test_data`。

本指南于 2026-08-23 在 Python 3.13.11 环境实际验证。

## 2. 前置检查

在仓库根目录执行：

```bash
.venv/bin/python --version
.venv/bin/ruff check .
.venv/bin/mypy src tests scripts/run_clindb_arxiv_experiment.py scripts/run_clindb_first_batch_experiment.py
.venv/bin/pytest
diff -u <(tail -n +2 AGENTS.md) <(tail -n +2 CLAUDE.md)
```

当前检查结果只以根目录 [`README.md`](../../README.md#当前可用检查) 为准。检查通过后再确认 5 份输入存在：

```bash
find data/md -maxdepth 1 -type f -name '*.md' -printf '%f\n' | sort
```

必须看到 `dmp.md`、`ejhf.md`、`jama.md`、`sim.md` 和 `springer.md`。不要把真实论文复制进测试 fixture。

## 3. 运行实验

人工选择一个当天未使用的安全运行 ID：

```bash
.venv/bin/python scripts/run_clindb_first_batch_experiment.py \
  --run-id clindb-first-batch-review
```

成功时终端只显示运行身份和汇总，不打印原文：

```text
run_id=clindb-first-batch-review
status=success
documents=5
changes=155
artifacts=/.../mdpolish/artifacts/<YYYY-MM-DD>/runs/clindb-first-batch-review
```

同一天同名目录已存在时脚本会拒绝覆盖。需要重跑时使用新 ID，不要删除旧目录来绕过检查。

## 4. 先看哪些结果

先确认运行目录根部同时存在 `manifest.json` 和 `review-locator.json`。定位文件只供本机评审器寻找原文，包含绝对路径，
不得提交或分享。然后打开 `manifest.json`，确认：

- `run.status` 是 `success`；
- `summary.document_count` 和 `summary.success_count` 都是 5；
- `summary.failed_count`、`summary.unstable_count` 都是 0；
- `summary.change_count` 是 155；
- `pipeline.components` 的顺序与 `design/0006` 一致。

然后查看每份文档目录：

```text
documents/<document_id>/
├── result.json
├── cleaned.md
└── changes.diff
```

- `changes.diff` 用于人工查看输入到最终输出的总变化；
- `result.json` 用于按组件、理由、位置和哈希追踪每条修改；
- `cleaned.md` 是成功输出全文。

当前 5 份输入的预期计数是：

| 文档 | `Change` 数 |
| --- | ---: |
| dmp | 47 |
| ejhf | 9 |
| jama | 79 |
| sim | 3 |
| springer | 17 |
| **合计** | **155** |

按组件应为：Word 批注 2、手稿行号 75、arXiv 戳 2、重复页眉 2、映射断词 6、HTML 实体 31、
HTML 表格布局 9、参考文献空行 28。

## 5. 人工复核重点

除了逐份查看 diff，至少确认：

- JAMA 的 Abstract 前作者和单位编号仍在，只删除 Abstract 后的 75 个手稿行号；
- Springer 两条 `arXiv preprint arXiv:` 合法参考文献仍在；
- Springer 正文中的编号方法列表没有被参考文献规则整理；
- dmp 的重复页眉删除后，正文句子接回，参考文献第 18、19 条之间仍有一个空行；
- 9 张表仍是 HTML，属性和单元格内容未被布局组件改写；
- 双重实体变成单层 `&lt;`、`&gt;` 或 `&amp;`，没有直接生成标签边界；
- 图片引用文字保持不变。

清洗目录没有复制图片资产，所以直接打开 `cleaned.md` 时图片仍可能无法显示。这不表示图片引用被清洗组件删除；
资产打包和路径改写需要单独设计。

## 6. 验证幂等和输入不变

流水线会在每份文档结束时做最终稳定性复查。需要额外复核整个保存结果时，可以把 `cleaned.md` 作为内存输入再次运行
同一 `build_pipeline()`；5 份都应为 `success` 且合计零 `Change`。

实验层已经在发布前后复读输入并比较字节哈希。需要人工记录运行前后的摘要时，可在运行前后分别执行：

```bash
sha256sum data/md/*.md
```

两次输出必须逐项一致。每个 `cleaned.md` 的 SHA-256 还必须等于对应 `result.json.current_sha256`。

## 7. 常见失败

### 状态不是 `success`

查看对应 `result.json` 的 `errors` 或 `residual_proposals`。`failed` / `unstable` 文档不会有正式 `cleaned.md`，
不能把其他文档的部分成功当成整批成功。

### 修改数不是 155

先按组件和文档分组定位差异。输入变化、组件参数变化或识别边界变化都必须回到 design/reference 核对；不要放宽断言、
补跑第二轮或手工改产物。

### 图片不显示

当前运行只保存 Markdown、审计和 diff，不复制图片。不要为了显示图片而修改输入路径或把真实资产强制加入 Git。

### 私有目录无法被 Snap 工具读取

运行目录权限是 `0700`，文件是 `0600`。使用普通编辑器或当前虚拟环境中的 Python 读取，不要放宽权限。

## 8. 数据边界

产物包含完整论文和原文片段，只能保存在本机 Git 忽略的 `artifacts/`。不得执行 `git add -f`，不得复制到 Wiki、
其他仓库、云存储或外部系统。

`manifest.json` 中的 `retention_until` 是默认 30 天到期时间。当前不自动删除；到期后如需清理，必须先确认具体运行目录。

需要在只读页面中查看完整前后文和各组件阶段时，继续按
[`review-local-cleaning-run.md`](review-local-cleaning-run.md) 操作。