151 lines
5.5 KiB
Markdown
151 lines
5.5 KiB
Markdown
# 运行本地 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，属性和单元格内容未被布局组件改写；
|
||
- 双重实体变成单层 `<`、`>` 或 `&`，没有直接生成标签边界；
|
||
- 图片引用文字保持不变。
|
||
|
||
清洗目录没有复制图片资产，所以直接打开 `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) 操作。
|