设计文档

pplx-cli（pplx-export / pplx-ask）的设计参考——机制层文档：管线、状态机、 数据契约，以及工具所依赖的 Perplexity Web API。面向任务的使用说明请从 使用指南开始。

文档定位：pplx_export/（Perplexity 对话归档工具）的系统设计参考。 读者：接手维护的 agent / 工程师。目标是读完本区文档即可定位任何一个机制的 实现位置（模块/函数/行号），理解它为什么这样设计，然后安全地修改。

与既有文档的分工（本区文档是它们的超集细化版，不替代）：

• 下文 API 参考各页：Perplexity REST/GraphQL API 实测参考（端点/响应/错误语义）；
• pplx_export/README.md：工具概览与用法（管线全图、ask 时序的概念版）；
• 下文系统设计各页：落到模块/函数/行号级的架构、依赖、管线、状态机、 数据模型、限频与错误分流。

行号引用格式 file.py:NN，均相对 pplx_export/。各页机制描述均对照源码 核实（2026-07-23，__version__ = "0.1.0"，pplx_export/__init__.py:31）。

系统设计

• 架构总览——分层模块图与真实 import 依赖图：CLI、命令层、 站点层与 core 基础层如何组合。
• 导出管线——端到端导出流程：抓取、原始响应先行落盘、 模式识别与 Markdown 渲染。
• 子代理与中断——后台子代理产物的确定性归属， 以及导出运行的中断 / 续跑状态语义。
• ask 时序与多账户——流式 ask 的完整时序，以及多账户 cookie 自动切换流程。
• 数据模型与目录契约——核心数据模型、写入边界，以及所有 写入方必须遵守的磁盘归档目录契约。
• 限频与错误处理——限频纪律、退避行为，以及错误 在各层之间的路由方式。
• 离线运维机制——零网络机制：离线重渲、关系图重建 及其他本地维护管线。
• 测试体系（架构）——全离线快照测试体系：fixture、 回归策略与覆盖布局。

API 参考

• API·认证模型——Perplexity Web API 的认证方式： 会话 cookie、令牌与账户身份。
• API·GraphQL——持久化查询（persisted queries / APQ）及 在用的 GraphQL 操作。
• API·REST 端点——实测过的 REST 端点，按用途分组。
• API·响应与错误语义——响应结构要点、解析纪律， 以及错误 / 风控语义。
• API·发现方法与路线——基于前端 bundle 静态分析 的端点发现方法，以及端点改进路线。