首版文档导航
本目录描述 rpkiparrot 首版 Python 库及配套 CLI、可选持久化和 HTTP 服务的实施契约。文档基线为 2026-10-03；仓库处于未发布实现阶段。已实现入口由源码生成参考及可执行示例列出，包括离线验证、RTR 客户端、运行中配置、两种数据库和 HTTP/SDK。首版验收仍以关联 Issues 和实际报告为准，不能把设计或配置的矩阵当成通过证据；扩展阶段能力保留明确的计划标签。
总体设计规定范围、协议版本和阶段。下面的专题文档细化调用方式、行为和验收依据；有冲突时先核对固定规范并同步修正文档，不让实现自行选择一套语义。协议镜像和参考实现只作为资料，不自动改变基线或增加运行时依赖。
阅读顺序
完整 API 参考见文档站。docs/api.md
是生成源文件，GitHub 和普通 Markdown 阅读器只显示 ::: 指令，不会展开接口。
本地查看可按API 参考查看说明运行
uv run --locked nox -s docs，再打开生成的 site/docs/api/index.html。
CI 将站点归档为制品，线上使用显式 Cloudflare 部署。
直接在 GitHub 阅读时，可先看下面的使用流程、公共 API 契约和数据与错误。
| 文档 | 回答的问题 |
|---|---|
| 版本说明 | 未发布首版提供哪些能力、协议基线与使用限制 |
| 使用流程 | 第三方如何仅使用库完成离线验证、嵌入 RTR 和事件订阅 |
| API 参考查看说明 | 如何构建和查看从源码生成的完整签名、字段与 docstring |
| 公共 API | 公开入口、签名、模块依赖及扩展接口是什么 |
| 数据与错误 | 输入、模型、可用性、结果、时间和异常如何表达 |
| 生命周期与一致性 | 谁启动和关闭任务，如何发布快照、切换来源和恢复订阅 |
| 输入与验证 | 接受哪些 JSON 和 AS_PATH，上游数据如何成为可查询快照 |
| RTR 状态机 | 各版本 PDU、状态、定时器、错误和事务怎样处理 |
| 配置 | Python 配置对象、默认行为、资源限制和 CLI 配置怎样对应 |
| 运行中配置变更 | 增删来源、修改配置怎样原子生效，哪些字段需要重建 Client |
| 规模与资源基线 | 真实数据、多来源、内存与磁盘预算怎样测量和确定 |
| 持久化 | SQLite、DuckDB 如何提交、恢复和共享完整状态 |
| 交换格式与诊断 | 导出、录制、状态、指标和错误使用什么结构 |
| CLI | 命令参数、输入输出、退出码与库 API 怎样对应 |
| HTTP 与远程 SDK | 可选服务的请求、分页、长轮询和远程调用怎样工作 |
| 验收 | 每项约定由哪些正常、边界和故障场景证明 |
| 兼容与分发 | 公共接口、实验性协议、包制品和版本怎样维护 |
| Decision / Decline | 哪些功能不属于本库、首版不做哪些扩展，以及代码生成不能采用哪些捷径 |
已有依据
- 规范镜像：固定 RFC、草案、勘误和已知冲突。
- 互操作资料与样本索引：生产者格式、独立实现向量、来源与限制。
- 实现参考库：按模块参考 Python 库的接口、源码和测试。
- CI/CD 落地参考：工具、运行矩阵和发布检查；尚未落地的方案继续保留计划状态。
- PyPI 手工准备：账户、发布身份和发布前资料准备；与包构建和行为验收分开进行。
- 开发约定：整个仓库长期遵守的规则和实际可执行命令入口。
开始实现和交付
验收文档按 M0–M4 组织工程、离线核心、在线同步、持久化及完整首版。各阶段同时交付库、对应 CLI、API 参考、可执行示例和行为检查；阶段实现与完整首版验收分别记录。开发进展与遗留问题在 Issue #5 维护。
本文档集已给出首版各模块的设计入口。性能阈值、依赖版本范围、平台支持和协议互操作结果仍须通过实施验证取得，不用文档推断通过。各阶段的证据要求和发布阻断项见验收文档。
公开签名、字段和 docstring 由源码生成参考维护，手写文档说明行为、流程和规范依据。使用流程链接到仓库的可执行示例，安装验收从仓库外运行适用示例。尚未实现的扩展示例必须明确标为设计示例，不能当作当前可运行接口。