# 运行本地 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 scripts/run_clindb_first_batch_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 天到期时间。第一版不会自动删除；到期后如需清理，必须先确认
具体运行目录。