从搜索到可复现阅读¶
先找到论文，再确认身份，最后选择派生阅读视图或固定原始资产。
本页对应新的不可变内容 API；客户端须与服务端的 major.minor 对齐，
RC 使用部署方确认的完整版本，不能假定旧客户端已支持新接口。
安装、登录及既有配置保留见 命令行（qatlas CLI）。
身份与版本不是同一件事¶
qa_…是作品身份，不固定 PDF 字节或解析。source_id固定 PDF 的确切字节与 SHA-256；同一作品相同 SHA 可复用 source。arXiv
vN是上游语义版本，来源标签可能为arxiv:vN或arxiv:IDvN；相同字节的两个语义版本可以共享 source。revision_id固定一次完整解析发布；重解析/重上传产生新 revision， current 只是可变指针，旧评论不迁移。S3VersionId是对象存储物理版本，不是上述任何公开 pin，不能用它替代 source、arXiv 版本或解析修订。存储版本恢复也不得覆盖固定身份的字节。
查找与确认身份¶
qatlas search / qatlas match 需要各自插件，也可从 Web 搜索或 API 参考
取得作品 ID。match 只检查已有 registry；搜索渠道错误不能解释为论文不存在。
qatlas search 'quantum linear systems' --json
qatlas match 1010.4458 --json
qatlas paper get metadata qa_…
可定位、可接续的 JSON 阅读¶
qatlas paper read qa_… --limit 30000 --json
qatlas paper read qa_… --source-id SOURCE_ID --revision REVISION_ID --page 5 --block 12 --json
qatlas paper read qa_… --cursor 'next_request.cursor 的原字符串' --json
qatlas paper read qa_… --no-wait --json
stdout 是完整的 Middle 派生阅读信封，不是原始 Middle/ContentList JSON。
响应保留 source/revision/PDF与artifact摘要、renderer、content、request_scope、
content_ranges、truncated、next_request 和 warnings。page 与 block 为
1-based 的原生产者编号，block 必须带 page，非连续 index 不重编号；预算为
Unicode 正文字符，默认 30000、上限 100000。
truncated=true 时将 next_request.cursor 原样传回；游标固定来源、修订、
摘要、renderer 和选择范围。cursor-only 会先解 pin 再加载，不会误选最新 current。
显式 pin/选择冲突为 409，格式错误为 400，缺件为 404，完整性失败为 422，
存储/registry 不可用为 503；不能用重新解析或回退其他版本掩盖固定原件故障。
未就绪的无 pin 正文请求可触发懒解析并返回 202、Operation-Location、Retry-After。
CLI 有界轮询 read/status，只有完整包与来源核验 ready 后重取原请求。
状态请求不下载、不创建解析任务；进程 Done 或历史 Middle 文件存在不代表 ready。
--no-wait 仅返回异步状态和轮询位置，进度始终在 stderr。
固定 PDF 与原始解析包¶
qatlas paper pdf qa_… --source-id SOURCE_ID -o paper.pdf
qatlas paper pdf 0811.3171v2 --version v2 --no-cache -o paper-v2.pdf
qatlas paper source-list qa_… --json
qatlas paper parse-list qa_… --json
qatlas paper parse-json qa_… REVISION_ID -o middle-original.json
paper pdf 直接访问鉴权 /api/papers/{id}/pdf；不先枚举 source，所以旧 PDF
尚未登记 source 不会阻断获取。source/version 互斥，显式 pin 无匹配不换版本。
规范 ID 和别名均校验完整 SHA 后才输出；缓存命中也先确认当前服务端授权/开关，
禁用/401/403 不可用旧缓存伪装成功。已存 PDF 不需要 MinerU token 或推理。
完整包的 /parses/{revision}/manifest 返回各成员原始相对路径/大小/SHA；
/parses/{revision}/files/{original_relative_path} 返回其原字节，含所有 JSON、
Markdown、图片和未知合法成员。生产者原名不被改写。/json 和 paper parse-json
仍只返回固定 revision 的原始 Middle artifact，不是阅读视图；历史评论依然固定
原 source/revision，不拿新的解析替换旧锚点。
开关、懒迁移与上传¶
所有内容/PDF/raw JSON/block 原件/图片/figures 均要求
paper_access.enabled 和当前身份 papers:read；关闭 404，无存储或解析副作用。
元数据列表和评论不能变成绕过开关的原件入口。
新内容在独立 qatlas-content 桶的 content/ 命名空间中不可变发布。
数据库迁移不做 bulk backfill；首次内容/PDF访问仅按需冻结旧 PDF，不复制旧 MD、
JSON 或图片，不删除旧桶。正文需要时才对冻结 source 解析，不能把旧派生资产当 ready。
PDF 导入别名永久绑定首次成功的确切 PDF；同别名不同字节即使 overwrite=true
也返回 409。完整解析上传须支持的 Middle + Markdown，MD-only/缺件拒收；所有
原成员名/字节保留，核验成员、manifest 和 PG 发布后才切 current。重上传是新
revision，overwrite 不修改旧 revision。
完整 API、清单和错误契约见 论文内容：固定 PDF、完整解析包与可续读视图，上传入口见 Upload API：冻结 PDF 与完整解析发布；历史存储记录不代表当前覆盖写规则。