paper-atlas/docs/operations.md

运行维护与数据核验

代码以固定 commit 部署，已经启动的任务继续使用其原版本。目录重构不要求迁移数据库，也不更改已有 JSONL 和 manifest 格式。

arXiv 原始编号与类别证据

原始行数、唯一 arXiv 编号数和合并后的论文实体数分别核验。以下只读原始压缩包，流式处理到 ZIP EOF/CRC 检查完成；输出审计 JSON 与编号 SQLite 索引，不修改论文主库：

paper-atlas audit arxiv --archive /data/paper-index/raw/arxiv-metadata.zip \
  --out /data/paper-index/collected/arxiv-source-audit.json

同编号的重复行会记录出现位置、次数和内容哈希版本，不直接视作不同论文；同篇论文的多个 arXiv 编号则保留各自来源及类别证据。旧导入器使用共享类别证据键，可能在论文实体合并时丢失某个编号的相同类别出处。新导入使用逐记录证据键；已有数据须在没有其他主库写入任务时按保留的来源 metadata 修复：

paper-atlas maintain arxiv-tags --db /data/paper-index/papers.sqlite \
  --out /data/paper-index/collected/arxiv-tag-repair.json

修复使用同一维护锁，分批提交并保存断点，保留 custom:* 和其他来源证据；失败后确认原因已解决，再增加 --resume 从上次提交位置继续。完成报告不能作为重新扫描的断点，重新核验应指定新报告。源审计和标签修复均保留 8 GiB 空闲空间，不能代替所有来源入库后的实体、投稿去重与完整性检查。

修复结束后还须核对每条 arXiv 来源记录的类别集合，不能只看旧证据键是否清零。下面的只读审计比较来源 metadata 中的类别、所属论文实体和逐记录证据键，同时检查没有合法 arXiv 来源的类别行：

paper-atlas audit arxiv-tags --db /data/paper-index/papers.sqlite \
  --repair-report /data/paper-index/collected/arxiv-tag-repair.json \
  --out /data/paper-index/collected/arxiv-tag-coverage-audit.json

审计持有共享维护锁；修复或其他协调写入尚未结束时会拒绝运行。提供修复报告时，还会核对其已完成状态、数据库路径和固定来源范围。审计以一致的只读快照分批读取，记录完整扫描数量、缺失/多余证据、错误论文归属、残留旧键及少量异常样例，不修改主库。

只有全量记录核对完毕且无差异时才标记 passed；存在差异为 failed 并返回非零退出码，解析或执行中断为 error。运行中的报告不能作为完成证明。重新核验须使用新输出路径，不能覆盖已有报告；该检查不替代最后的实体去重、外键、SQLite 与全文索引核验。

长期维护与更新

1. 每次采集先核对来源、许可、可访问性、空闲空间和现有运行批次。保持低并发，遵守来源限流、重试与人机验证要求。
2. 下载先写 .part，确认完整 HTTP 响应和 ZIP 目录，再记录 SHA-256 与时间后切换为正式文件。正式导入会读至 EOF，从而验证成员 CRC。
3. 每次导入保留来源证据和批次，按会议/年份/track 报告覆盖状态。缺失摘要留空，不编造文本；缺失决定保留未知。
4. 核验行数、唯一标识、外键、全文查询和 SQLite 完整性后，再将批次视为交付。样本通过不能证明全量正确。
5. 数据库备份使用 SQLite backup API 或一致性快照，不能在写入过程中只复制 .sqlite 主文件而遗漏 WAL。按明确保留策略轮换备份，避免无上限积累。
6. 不为每次数据更新生成新 Docker 镜像；不常驻下载器；不自动创建定时任务。本项目的更新任务应按需或经用户授权调度。
7. 代码通过工作分支和 PR 交付；构建或 CI 只能使用用户确认的远程 runner，不在本机触发构建。

当前访问限制

2026-11-06 从目标服务器测试：Kaggle 元数据 GET 可下载；OpenReview 会议 group 接口可读，但 notes 接口返回 ChallengeRequiredError。这限制了直接补全；已使用来源可追溯的公开历史快照补充近期投稿与明确决定。仍不能用录用名单替代全部投稿，也不能声称覆盖了全部拒稿。

查询批次与入库状态

采集文件、已入库的来源记录和去重论文实体是不同的计数。来源可能覆盖同一篇论文，同一篇论文也可能有多次投稿；不能把各批文件数量相加作为独立论文总数。实时统计与覆盖报告使用：

paper-atlas query --db /data/paper-index/papers.sqlite --stats
paper-atlas coverage --db /data/paper-index/papers.sqlite \
  --out /data/paper-index/collected/venue-coverage-current.json

manifest 和采集器状态清单用于确认文件是否齐全及是否缺摘要；ingest_runs 和协调器日志用于确认主库导入是否成功。官方程序、书目目录和公开投稿快照分别保留，未出现在某份清单不等于被拒稿；第三方快照也不能代表平台当前全量状态。代码测试成功不能代替最终全库去重、完整性和逐届覆盖核验。

当前代码与合并状态以 Pull Requests 为准；CI 结果以对应提交的 Actions 检查为准。工作分支交付后等待用户手动合并。合并代码不自动部署、不自动启动采集，也不代表数据批次已完成。