1-3-1 沟通规则

当一项任务存在多种可行方案、且用户需要明确建议时，采用的结构化决策格式。该格式产出简洁的问题界定、三个含权衡分析的选项，以及针对推荐路径的可执行计划。

适用场景

• 用户明确要求“1-3-1”格式的回复。
• 用户提出“给我几个选项”或“我有哪些选择”等涉及技术决策的请求。
• 某项任务存在多个具备实际意义权衡取舍的可行路径（例如架构设计、工具选型、迁移策略等）。
• 用户需要一份可直接转发给团队或相关干系人的正式提案。

请勿将本规则用于以下情况：答案唯一且显而易见的简单问题、调试会话，或用户已明确选定具体实施方式的任务。

执行流程

1. 问题（一句话）

   • 用一句简洁语句阐明核心决策点或期望达成的结果。
   • 聚焦于“做什么”，而非“怎么做”——不包含实现细节、工具名称或具体技术栈。
   • 力求精炼。若需使用“且（and）”，说明你实际上在描述两个独立问题。

2. 选项（严格限定为三个）

   • 列出三种彼此独立、切实可行的方案，并依次标记为 A、B、C。
   • 每种方案需附简要说明、优势与劣势。
   • 各选项应代表本质不同的策略，而非同一思路下的细微变体。

3. 推荐方案（仅一个）

   • 明确指出你推荐的选项，并基于用户的上下文与优先级说明理由。
   • 表述须直接果断——这是你的专业判断，而非模棱两可的规避性表达。

4. 完成定义（Definition of Done）

   • 列出所推荐方案对应的具体成功标准。
   • 这些标准必须是可验证、可衡量的结果，而非模糊的愿景或目标。
   • 若用户最终选择其他选项，需同步更新本节内容以匹配其选择。

5. 实施计划

   • 为执行所推荐方案而制定的具体步骤。
   • 在适用情况下，应包含具体命令、工具或操作动作。
   • 若用户最终选择其他选项，需同步更新本节内容以匹配其选择。

校验要点

• 回复中仅含一句“问题”陈述。
• 回复中严格包含三项选项（A、B、C），且每项均附有优势与劣势分析。
• 回复中仅含一项“推荐方案”，并明确指定选项及相应推理依据。
• “完成定义”与“实施计划”须与所推荐的选项完全一致。
• 若用户另行选定其他选项，则“推荐方案”、“完成定义”与“实施计划”三部分均须相应更新。

示例

用户：“请为我们的 API 客户端添加重试逻辑提供一份 1-3-1 分析。”

Agent：

问题：调用外部服务的 API 请求在高负载下偶发失败，需实现优雅的重试处理机制。

选项：

• 选项 A：在共享工具模块中实现带抖动的指数退避重试。
  优势：模式简洁、业界成熟；所有调用方共用同一实现。
  劣势：无熔断机制；重试期间调用方仍处于阻塞状态。

• 选项 B：使用重试库（tenacity）作为各端点调用的装饰器。
  优势：支持按端点粒度配置；内置熔断器与速率限制能力。
  劣势：引入新依赖；装饰器模式可能掩盖控制流逻辑。

• 选项 C：基于队列的异步重试，配合死信队列处理。
  优势：非阻塞；失败调用可被追踪与重放；具备良好扩展性。
  劣势：系统复杂度显著提升；需引入队列后端；对低流量服务属于过度设计。

推荐方案：选项 A。当前调用量尚不足以支撑队列基础设施投入，而共享工具模块中实现的带抖动指数退避机制，既能干净覆盖目标故障场景，又无需引入额外依赖。

完成定义：

• api_retry() 工具函数可处理瞬态 HTTP 错误（429、502、503、504）。
• 最多重试 3 次，采用指数退避策略并加入抖动。
• 所有对外部 API 的调用均通过该重试工具路由。
• 每次重试尝试均记录日志，包含端点地址与重试序号。
• 单元测试覆盖重试耗尽、立即成功、瞬态失败后成功等全部典型场景。

实施计划：

1. 创建 utils/api_retry.py，支持配置最大重试次数、基础延迟时间及可重试状态码列表。
2. 使用 random.uniform(0, base_delay) 添加抖动，避免“惊群效应（thundering herd）”。
3. 在 api_client.py 中对现有 API 调用统一封装 retry 工具。
4. 编写单元测试，模拟各类 HTTP 响应以覆盖全部重试场景。
5. 借助简易压力测试，在模拟的不稳定端点上验证重试行为在负载下的有效性。