用途
Automated Orchestration 用于协调端到端的分析流水线，使其具备检查点与断点续跑能力，并能根据实际遇到的数据量自适应调整分析深度。其核心原则是：每一个可能失败的阶段都必须可恢复，每一条流水线都必须根据数据规模调整深度。
何时使用
- 流水线按顺序处理多个阶段，一旦失败会损失数小时的工作成果。
- 大型数据语料需要分块处理，并需感知速率限制。
- 分析深度应随数据量伸缩（浅层扫描与深度分析）。
- 长时间运行的任务需要优雅中断与重启。
- 多个数据源需要跨阶段组合，并容忍部分失败。
何时不使用
- 5 分钟以内、没有中间状态的单次脚本。
- 全量重新执行成本低廉且可接受的流水线。
- 实时流式处理（应改用事件驱动模式）。
核心模式
无编排时，fetch_all_data、process_everything、analyze_all、generate_report 依次执行，若在 analyze 阶段失败则需从头开始。有编排时，各阶段分别写入检查点，若在 enrich 阶段失败，可从 Stage 3 检查点恢复。
快速参考
- 检查点：每阶段使用 JSON/pickle，原子写入；反模式是超过 5 分钟的任务不设检查点。
- 幂等性：先删除再写入，按 key upsert；反模式是只追加不去重。
- 深度调整：按条目数量缩放分析层级；反模式是对所有输入硬编码深度。
- 速率限制：指数退避加抖动；反模式是无延迟的重试循环。
- 进度：每阶段结构化日志并记录计数；反模式是静默处理、无可见性。
- 失败处理：隔离阶段，部分失败时继续；反模式是因单个错误中止整条流水线。
流水线架构
1. 将阶段定义为幂等单元
每个阶段读取输入产物、产出输出产物，并在成功时写入检查点。重新运行已完成的阶段是空操作。示例代码定义了 PipelineStage 基类，包含 checkpoint_path、is_complete、load_checkpoint、save_checkpoint（先写 .tmp 再重命名，在 POSIX 上为原子操作）、run（带检查点/续跑逻辑）、process_item、_item_key（用于去重的唯一键）、_load_output，以及 checkpoint_interval（默认每 50 个条目保存一次检查点）。
2. 使用流水线运行器编排阶段
Pipeline 类按顺序运行各阶段并感知检查点，记录每个阶段的名称、状态、耗时、条目数与错误数。遇到 KeyboardInterrupt 时记录 interrupted 并提示重新运行可从该阶段恢复；遇到其他异常时记录 failed 并中止。write_report 将状态报告写入 docs/analysis/03-automated-orchestration.md，包含流水线状态表格，以及中断与失败章节或全部成功的结果说明。
3. 基于活动量的深度调整
choose_depth 函数根据条目数量选择分析深度层级，返回下游阶段消费的参数。默认阈值：shallow（0–100，仅快速摘要）、standard（101–5000，逐项完整分析）、deep（5001–50000，抽样深度加完整摘要）、archival（50001 及以上，统计抽样加关键条目）。调用方不应硬编码深度，而应始终从数据推导。
4. 感知速率限制的抓取
fetch_with_backoff 函数使用指数退避加抖动进行重试，尊重速率限制。遇到 RateLimitError 时等待 base_delay * (2 ** attempt) 加随机抖动；其他异常在最后一次尝试时抛出，否则等待 base_delay。超过最大重试次数后抛出 RuntimeError。
处理数据不足
- 流水线无内容可处理：记录“no input data”，写入报告说明输入为空，以 no_data 状态干净退出。
- 某阶段产出为空：记录警告，将空集合传给下一阶段，不跳过也不报错，让下游阶段优雅处理空输入。
- 外部 API 不可用：带退避重试；达到最大重试后将该阶段标记为 degraded，若有缓存或部分数据则继续，并记录跳过了什么。
- 检查点文件损坏：删除检查点，从头重跑该阶段，并记录损坏事件。
常见错误
- 超过 5 分钟的任务不设检查点：应每 N 个条目及阶段完成时写入检查点。
- 单体单函数流水线：应拆分为具有清晰输入/输出契约的离散阶段。
- 静默跳过失败条目：应记录每个失败的条目 ID、错误与时间戳。
- 硬编码分析深度：应使用 choose_depth() 或等价方法基于实际条目数。
- 无退避的重试：对外部调用始终使用指数退避加抖动。
- 非原子检查点写入：应先写 .tmp 再重命名（POSIX 上原子）。
- 忽略部分失败：应收集错误、继续处理，并在报告中汇总。
- 无进度可见性：应记录阶段进入/退出、条目数与耗时。
边界
应当做：管理流水线阶段的顺序与依赖；优雅处理中断（Ctrl+C 保存检查点）；自动按数据规模缩放深度；以结构化、可解析的输出记录进度；在 docs/analysis/03-automated-orchestration.md 生成状态报告。
不应做：做出分析结论（这属于领域特定的下游技能）；静默跳过失败阶段而不记录；无退避地无限重试；决定数据含义——只负责可靠地让数据流经各阶段。
报告输出
流水线必须以写入 docs/analysis/03-automated-orchestration.md 结束，内容包含：流水线运行时间戳；阶段表格（名称、状态 complete/failed/interrupted/skipped、条目数、错误数、耗时）；列出任何中断或跳过步骤及原因的章节；所选深度层级及其原因的摘要。