1-3-1 沟通规则

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

适用场景

• 用户明确要求以“1-3-1”格式响应。
• 用户提出“给我几个选项”或“我有哪些选择”等表述，针对某项技术决策。
• 某项任务存在多个真正可行、且具有实质性权衡差异的实现路径（例如架构设计、工具选型、迁移策略）。
• 用户需要一份可直接转发给团队或相关干系人的正式提案。

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

执行流程

1. 问题（一句话）

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

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

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

3. 推荐（仅一个选项）

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

4. 完成定义（Definition of Done, DoD）

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

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 调用统一包裹进重试工具。
4. 编写单元测试，模拟各类 HTTP 响应以覆盖全部重试场景。
5. 通过简易压力测试，在模拟的不稳定端点上验证重试行为在高负载下的有效性。