实现 ClinDB 第一批清洗组件

2026-08-23 20:56:36 +08:00
parent 6fcc7d5736
commit 80001a8ab9
28 changed files with 2538 additions and 67 deletions
@@ -19,7 +19,7 @@
 ```bash
 .venv/bin/python --version
 .venv/bin/ruff check .
-.venv/bin/mypy src tests scripts/run_clindb_arxiv_experiment.py
+.venv/bin/mypy src tests scripts/run_clindb_arxiv_experiment.py scripts/run_clindb_first_batch_experiment.py
 .venv/bin/pytest
 ```

@@ -0,0 +1,146 @@
+# 运行本地 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-22 在 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)
+```
+
+当前已验证结果是 Ruff 通过、mypy 37 个文件无问题、pytest 204 项通过。再确认 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`，确认：
+
+- `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 天到期时间。当前不自动删除；到期后如需清理，必须先确认具体运行目录。