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