mdpolish/research-wiki/guides/run-local-clindb-arxiv-experiment.md

运行本地 ClinDB arXiv 清洗实验

1. 适用范围

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

• 输入：data/md/ 中的 dmp.md、ejhf.md、jama.md、sim.md 和 springer.md；
• 流水线：只包含 paper.arxiv_submission_stamp 1.0.0；
• 输出：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

确认 5 份本地输入存在：

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

预期看到：

dmp.md
ejhf.md
jama.md
sim.md
springer.md

3. 运行实验

为本次实验人工选择一个小写运行 ID。同一天已经使用过的 ID 不能覆盖；需要重跑时换一个新 ID。

.venv/bin/python scripts/run_clindb_arxiv_experiment.py \
  --run-id clindb-arxiv-stamp-review

成功时终端只显示运行 ID、状态、文档数、修改数和产物目录，例如：

run_id=clindb-arxiv-stamp-review
status=success
documents=5
changes=2
artifacts=/.../mdpolish/artifacts/<YYYY-MM-DD>/runs/clindb-arxiv-stamp-review

终端不会打印论文原文或 diff。

4. 查看结果

进入终端输出的运行目录。目录结构为：

manifest.json
documents/
├── dmp/
│   ├── result.json
│   ├── cleaned.md
│   └── changes.diff
├── ejhf/
├── jama/
├── sim/
└── springer/

先看 manifest.json 的整批状态和汇总，再查看各文档：

• cleaned.md：成功清洗后的完整 Markdown；
• changes.diff：输入到成功输出的人工对比；
• result.json：组件、理由、位置、before、after 和哈希等机器审计。

dmp、ejhf 和 jama 当前应为零修改，diff 是空文件；sim 和 springer 当前各有一条删除。

5. 判断成功

本轮验收口径是：

• manifest 整体状态为 success；
• 5 份文档全部为 success；
• 合计 2 条修改；
• sim 修改位置为 1:1；
• springer 修改位置为 18:1；
• Springer 两条合法 arXiv preprint arXiv: 参考文献保留；
• 每份 cleaned.md 的 SHA-256 等于对应 result.json.current_sha256；
• 输入文件运行前后不变。

只看到运行目录存在不等于成功，必须先检查 manifest 和文档状态。

6. 常见失败

运行目录已经存在

脚本拒绝覆盖同一日期下的同名运行目录。选择新的 --run-id，不要删除或覆盖旧目录来绕过检查。

输入缺失或不是 UTF-8

整批预检会失败，不运行任何组件，也不发布最终目录。先确认 data/md/ 中 5 份文件存在且未被修改。

状态为 failed 或 unstable

对应文档只会生成 result.json，不会生成 cleaned.md 或 diff。查看错误或残留候选，不要把其他文档的部分成功 当成整批成功。

Snap 版本的 jq 报权限错误

产物目录权限是 0700。某些 Snap 沙箱工具不能进入私有目录，即使当前用户拥有权限。可直接用编辑器查看 JSON， 或使用当前虚拟环境中的 Python 读取；不要为了兼容受限工具放宽产物权限。

7. 数据边界

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

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