paper-atlas/docs/usage.md

# 使用指南

先在已确认的远程环境安装项目，使用 `paper-atlas`。从源码运行时，将命令前缀替换为 `python3 -B -m paper_atlas`，其余参数相同。数据目录位于仓库外。

## 按证据补充稳定标识

`paper-atlas curate identifiers --plan /data/review/plan.json --output /data/review/prepared`
只生成新的 JSONL、manifest、证据副本及 `curation-report.json`，不会连接数据库。
输出目录必须不存在，父目录必须已存在；任何输入或断言失败，都不发布本批输出。
原始文件不变，未选中的记录逐字节保留。题名、作者、年份、页码、投稿决定、标签和既有 metadata
均不重写，仅补充 `identifiers` 并追加 `metadata.identifier_curation` 证据链。

计划格式如下（哈希占位符须替换为真实 SHA256，所有路径按命令当前目录解析）：

```json
{
  "format_version": 1,
  "inputs": [{
    "file": "/data/review/uai2001.jsonl",
    "sha256": "<JSONL 文件 SHA256>",
    "manifest_sha256": "<同名 .manifest.json 文件 SHA256>"
  }],
  "assertions": [{
    "source": "dblp",
    "external_id": "conf/uai/example",
    "record_sha256": "<原始物理行字节 SHA256，包含该行原有换行符>",
    "identifiers": {"arxiv": "1408.1485"},
    "evidence": [{
      "file": "/data/review/primary-metadata.json",
      "sha256": "<证据 JSON 文件 SHA256>",
      "url": "https://example.org/primary-record",
      "checked_at": "2026-11-08T08:00:00Z",
      "note": "说明人工核对的题名、作者、出版版本和稳定标识证据"
    }]
  }]
}
```

输入 manifest 必须包含 `source/venue/year/track/count/list_url/file_sha256`，且与逐条记录一致。
断言必须唯一、准确命中一条记录。仅支持无版本后缀的 arXiv 编号与小写规范 DOI；
已有同类标识不允许覆盖，相同值可以补记证据。证据只接受不超过 16 MiB 的 JSON 元数据文件，
来源 URL 要求 HTTPS 且不含凭据，核查时间必须带时区；不下载论文 PDF。

`verification_scope=input_and_evidence_integrity_only` 和 `semantic_identity_verified=false`
明确表示哈希校验不能证明两条记录属于同一作品。请先独立核对版本关系；仅年份、页码或相同题名
不能作为合并依据。存在来源冲突的行应继续暂缓。新 manifest 保留原来的 partial 状态及摘要缺失数，
不会把补充编号伪装成来源覆盖或摘要补全。证据副本按 SHA256 保存在输出目录 `evidence/`，
原计划也保存在 `plan.json`，供之后复查。

文件生成后仍需另做当前 PostgreSQL 身份、投稿和决定冲突预检；导入运行时必须包含
“稳定标识优先、多个标题候选则整文件回滚”的身份保护，再以 `import records` 独立导入并验收。
该命令不会自动导入或合并实体，也不代表最终全库去重通过。

## PostgreSQL 查询

在远程环境安装 `.[postgres]`，通过权限为 `0600` 的 libpq service 文件连接，不把密码放入 URL、命令行或仓库。

```sh
export PGSERVICEFILE=/etc/paper-atlas/pg_service.conf
paper-atlas query --pg-service foundry-research --stats
paper-atlas query --pg-service foundry-research --query '"language model"' --tag arxiv:category=cs.CL
paper-atlas query --pg-service foundry-research --status rejected --outcome accepted --limit 20
paper-atlas query --pg-service foundry-research --paper 123
```

使用只读一致性事务，支持论文 ID、会议别名、年份、轨道、标签、最新决定和跨会议录用筛选。全文检索使用 PostgreSQL `websearch_to_tsquery('english', ...)`，支持引号短语、`OR` 和减号排除；与 SQLite FTS5 的语法及分词结果不完全相同。JSON 来源列保留原始文本；转成 `jsonb` 前须确认原始值符合该类型的限制。

CLI 自动还原迁移中的 NUL/SOH 文本转义，详情中的来源摘要和筛选参数保留原字符。直接 SQL 读取可能看到 `U+0001` 转义序列；跨项目 ETL 应按迁移元数据中的 `text_codec` 使用 `paper_atlas.postgres.text.encode/decode`。存储格式和无损哈希验收见[运行维护](operations.md#postgresql-迁移)。

迁移与切换见[运行维护](operations.md#postgresql-迁移)。`import records`、`import arxiv` 和 `maintain backfill` 均支持 `--pg-service` 和可选 `--pg-schema`；与 `--db` 二选一。SQLite 导入仅用于未切换的索引或独立样本。尚未适配 PostgreSQL 的维护、覆盖审计命令仍可只读检查冻结备份，不能当作主库的当前状态。

## 1. 下载固定快照

`paper-atlas download --help` 说明大小、校验和与续传参数。各来源的固定版本与具体命令见[数据源说明](data-sources.md)。下载成功只表示原始文件已核验。

## 2. 采集并核对清单

```sh
paper-atlas collect pmlr --cache /data/paper-index/raw/http-cache --out /data/paper-index/collected
paper-atlas collect cvf --cache /data/paper-index/raw/http-cache --out /data/paper-index/collected
paper-atlas collect ecva --cache /data/paper-index/raw/http-cache --out /data/paper-index/collected
paper-atlas catalogue dblp --help
paper-atlas audit iclr --help
paper-atlas collect public-openreview --help
paper-atlas collect icml-public-archive --help
paper-atlas audit public-openreview --help
```

采集输出 JSONL、manifest 和逐卷或逐年 catalogue。逐项检查 blocked、partial、缺失摘要及目标会议归属。DBLP 候选目录还需核验届次和 track，不能直接当作主会录用名单。

其他会议的公开拒稿使用 `collect public-openreview`，再以 `audit public-openreview` 核对既有投稿身份和决定冲突。来源版本、逐文件状态盘点和未解决记录分别保存在 inventory 与 held 清单中，具体命令见[数据源说明](data-sources.md#其他会议的公开拒稿)。这类公开子集不能当作会议完整投稿名单。

主库切换后，预检须直接连接当前 PostgreSQL，不能用冻结的 SQLite 备份推断当前决定：

```sh
paper-atlas audit public-openreview --pg-service foundry-research \
  --inventory /data/paper-index/collected/public-openreview-v1/public-openreview-inventory.json \
  --out /data/paper-index/collected/public-negative-pg-preflight.json
```

预检使用只读一致性快照，报告会记录实际数据库、schema、文件哈希和同届次/轨道的决定冲突；其他会议的录用保留为独立历史。预检不预留写锁，实际导入这两类公开负面决定时会在写事务中再次复核同一次投稿的最新状态；过期预检报告不能覆盖已经变化的决定。

## 3. 串行导入

PostgreSQL 主库逐文件导入已经核验的资料：

```sh
paper-atlas import records --pg-service foundry-research \
  /data/paper-index/collected/selected-file.jsonl
paper-atlas maintain backfill --pg-service foundry-research \
  --queue /data/paper-index/collected/audited-identity-queue.json
```

文件和 queue 须替换为实际核验通过的路径。会议导入按文件提交，失败时该文件的论文、标签和决定更改全部回滚，失败批次日志保留；重跑会按来源标识与决定证据去重。回填使用已有源记录，只合并经独立身份佐证的投稿，不重新导入文本。所有写入者须遵守同一数据库/schema 的会话锁；其他项目也应通过相同的写入接口更新共享论文和投稿。

未来需要导入新的 arXiv 元数据包时使用 `paper-atlas import arxiv --pg-service foundry-research --archive ... --storage-path ...`。每 500 行提交断点，恢复同一文件时保留已提交 ID 和标签证据；`--storage-path` 指定运行主机上要监测的文件系统，在数据库主机执行时应指向数据库卷。已完成的历史压缩包不需要重复导入。

SQLite 独立样本的首次 arXiv 导入使用 `paper-atlas import arxiv --db ... --archive ...`。SQLite 协调器仍适用于未切换的索引：

```sh
paper-atlas maintain merge --db /data/paper-index/samples/example.sqlite \
  --archive /data/paper-index/raw/arxiv-metadata.zip \
  /data/paper-index/collected/selected-file.jsonl
```

上例的 selected-file 须换成实际通过核验的文件。协调器会维护本项目的 arXiv 断点、序列化写入并检查外键；已完成的 arXiv 批次不会重启。持久批次应作为一次性 systemd 任务运行，详见[运行维护](operations.md)。

## 4. 查询与分析前检查

```sh
paper-atlas query --pg-service foundry-research --query '"language model"' --limit 20
paper-atlas query --pg-service foundry-research --tag arxiv:category=cs.AI
paper-atlas query --pg-service foundry-research --venue ICLR --year 2025 --status rejected
paper-atlas query --pg-service foundry-research --paper 123
PGSERVICEFILE=/etc/paper-atlas/pg_service.conf paper-atlas coverage \
  --pg-service foundry-research --pg-schema research --out /data/paper-index/collected/coverage.json
```

`--status rejected` 筛选某次投稿的最新已知决定。它并不表示论文在所有会议均未录用；分析转投情况时查看该论文的完整投稿历史。年份表示会议届次，观察时间和决定日期分别保留。

覆盖报告使用只读一致性快照，标明实际数据库和 schema，并列出零入库目标与注册表外的已入库会议。逐届、逐 track 分别列出最新观察状态的投稿数、全部决定观察数、各来源记录数，以及来源摘要和论文实体摘要的缺失数。摘要缺失指 NULL 或空字符串；有文字不代表内容已经完整核验。同一来源的多个清单 URL 可以重叠，不能把清单计数相加当作来源总量；零条拒稿也不证明该会议没有公开拒稿。SQLite 样本仍可显式使用 `--db`，生产报告应查询当前 PostgreSQL。

例如，查找在 ICLR 有拒稿记录、但在其他已知投稿中已有录用的论文：

```sh
paper-atlas query --pg-service foundry-research \
  --venue ICLR --status rejected --outcome accepted
```

`known_acceptances` 列出目前仍为录用状态的各次投稿及会议、年份、track 和决定证据，`publication_outcome` 汇总为 accepted 或 no_known_acceptance。汇总会检查所有会议和 track，不把某次拒稿覆盖到整篇论文；同一次投稿的后续撤稿也会更新该次状态并保留原决定。no_known_acceptance 只表示现有来源中没有查到录用，不能称为“从未录用”。

`--stats` 中 papers 是当前规则下的论文实体数；source_records 是来源记录数；decisions 是决定观察数。一个投稿可能有多个来源和多条观察，不能相加当作论文数。

已有稳定标识或原来源记录匹配时，该身份优先；同标题、同作者的另一 arXiv 存档或扩展稿不会仅因相似标题被并入。没有身份锚点时，作者佐证的精确标题只有一个候选才可匹配；多个候选会报 `Ambiguous paper identity`，整个采集文件回滚并记录失败运行。应补有证据的标识或先核查版本关系，不删除重复候选或任取第一个。一个新来源明确同时携带两个既有稳定标识时，仍可按既有规则归并并保留投稿、标签和合并日志；未归并的同标题关系继续保留为待核查候选。这些规则不证明全库去重完成。

## 5. 投稿历史关系审计

```sh
PGSERVICEFILE=/etc/paper-atlas/pg_service.conf paper-atlas audit histories \
  --pg-service foundry-research --pg-schema research --examples 20 \
  --out /data/paper-index/collected/history-audit.json
```

使用一个只读一致性快照，区分论文实体、投稿和决定观察；分别统计同次投稿曾出现负面与录用观察、不同投稿共存负面与当前已知录用、不同会议之间的共存。workshop/main 是不同 track，属于同一会议时不算跨会议；会议别名也不会增加一个会议。当前已知录用使用与 `query --outcome` 相同的“每次投稿最新观察”规则，后续撤稿的该次投稿不再算当前录用，但旧录用决定仍保留。

报告不凭观察时间、届次年份或行顺序断言“拒稿发生在录用之前”。样例保留真实 `decision_date`、`observed_at`、原始标签、证据 URL 和决定来源，供进一步核查；日期缺失仍保持未知。`negative` 统计包含 rejected、desk_rejected 和 withdrawn，其原始状态不互相替换。

总数覆盖快照内全部投稿，样例由 `--examples` 限定为 0–100 篇；每篇最多展示 20 次投稿、每次最多 50 条决定、每条决定最多 100 个来源，并明确标记截断。样例优先保留负面/录用的不同投稿对。四项来源关系检查报告缺失关联和来源论文归属不一致，不自动修复。

这些统计依赖现有论文身份关联，不证明实体合并正确，也不证明原始决定签名、公开拒稿全集、标签类型或最终全库去重已完成。SQLite 独立样本可使用 `--db`；冻结备份不能代表当前 PostgreSQL 的历史情况。