实现本地清洗实验与产物保存

2026-08-22 17:25:44 +08:00
parent eed2119016
commit 6fcc7d5736
13 changed files with 2701 additions and 20 deletions
@@ -0,0 +1,129 @@
+# 运行本地 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. 前置条件
+
+在仓库根目录执行，并确认隔离环境和基础检查可用：
+
+```bash
+.venv/bin/python --version
+.venv/bin/ruff check .
+.venv/bin/mypy src tests scripts/run_clindb_arxiv_experiment.py
+.venv/bin/pytest
+```
+
+确认 5 份本地输入存在：
+
+```bash
+find data/md -maxdepth 1 -type f -name '*.md' -printf '%f\n' | sort
+```
+
+预期看到：
+
+```text
+dmp.md
+ejhf.md
+jama.md
+sim.md
+springer.md
+```
+
+## 3. 运行实验
+
+为本次实验人工选择一个小写运行 ID。同一天已经使用过的 ID 不能覆盖；需要重跑时换一个新 ID。
+
+```bash
+.venv/bin/python scripts/run_clindb_arxiv_experiment.py \
+  --run-id clindb-arxiv-stamp-review
+```
+
+成功时终端只显示运行 ID、状态、文档数、修改数和产物目录，例如：
+
+```text
+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. 查看结果
+
+进入终端输出的运行目录。目录结构为：
+
+```text
+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 天到期时间。第一版不会自动删除；到期后如需清理，必须先确认
+具体运行目录。