5.2 KiB
运行本地 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. 前置检查
在仓库根目录执行：
.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 份输入存在：
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：
.venv/bin/python scripts/run_clindb_first_batch_experiment.py \
--run-id clindb-first-batch-review
成功时终端只显示运行身份和汇总，不打印原文：
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一致。
然后查看每份文档目录：
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。
实验层已经在发布前后复读输入并比较字节哈希。需要人工记录运行前后的摘要时，可在运行前后分别执行：
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 天到期时间。当前不自动删除；到期后如需清理，必须先确认具体运行目录。