name: one-three-one-rule description: “1-3-1 decision briefs: problem, three options, one pick.” platforms: [linux, macos, windows] version: 1.0.0 author: Willard Moore license: MIT category: communication metadata: hermes: tags: [communication, decision-making, proposals, trade-offs]
1-3-1 沟通规则
当一项任务存在多种可行的解决方案，且用户需要明确的建议时，可采用此结构化的决策格式。它能够清晰地阐述问题核心，列出三种带有利弊权衡的选项，并为推荐的方案提供具体的执行计划。
适用场景
- 用户明确要求获得“1-3-1”格式的回复。
- 用户在面对技术决策时询问“给我一些选项”或“我有哪些选择”。
- 某项任务存在多种可行的解决方案，且这些方案在架构、工具选型、迁移策略等方面存在明显的利弊差异。
- 用户需要一份可转交给团队或利益相关方的建议方案。
不适用于答案显而易见的简单问题、调试过程，以及用户已确定解决方案的任务。
操作步骤
-
问题描述（一句话）
- 用一句简洁的话明确核心决策或期望达成的结果。
- 需聚焦于“做什么”，而非“如何做”——不得提及实现细节、工具名称或具体技术。
- 表述要简明扼要，若需使用“和”字，则说明存在两个不同问题。
-
可选方案（恰好三个）
- 列出三种不同的可行方案，分别标记为A、B、C。
- 每个方案都需附上简要描述、优点及缺点。
- 这些方案必须是真正不同的策略，而非同一方法的细微变体。
-
推荐方案（一个方案）
- 根据用户的实际情况与优先级，明确指出推荐的方案及其理由。
- 表述要直接清晰——这代表您的专业判断，而非模棱两可的意见。
-
完成标准
- 列出所推荐方案的具体成功标准。
- 这些应是具体且可验证的结果，而非模糊的期望。
- 若用户选择其他方案，则需相应调整此部分内容。
-
实施计划
- 执行所推荐方案的具体步骤。
- 在适用情况下，需包含具体的命令、工具或操作内容。
- 若用户选择其他方案，则需相应调整此部分内容。
- 响应中仅包含一个问题描述句。
- 响应中恰好包含三个选项（A、B、C），每个选项均需列出其优缺点。
- 响应中需给出一项推荐意见，明确选定其中一个选项并说明理由。
- “完成标准”与“实施计划”需与所推荐的选项保持一致。
- 若用户选择其他选项，则推荐意见、“完成标准”及“实施计划”均需相应调整。
示例
用户：“请为我提供一种为 API 客户端添加重试逻辑的 1-3-1 方案。”
智能体回复：
问题： 在高负载情况下，对外部服务的 API 调用会间歇性失败，需要实现优雅的重试机制。
选项：
-
选项 A：在共享工具中采用带抖动机制的指数退避策略。
优点：方案简单且易于理解；只需实现一次，所有调用方均可复用。
缺点：不支持断路保护；调用方在重试过程中仍会阻塞。 -
选项 B：在每个接口调用上使用重试库（如 tenacity）作为装饰器。
优点：可针对每个接口单独配置；内置断路保护和速率限制功能。
缺点：会增加依赖项；装饰器模式可能会使控制流程变得复杂。 -
选项 C：基于队列的异步重试机制，并配有死信处理功能。
优点：非阻塞式处理；可追踪失败调用并重新执行；具备良好的扩展性。
缺点：复杂度显著提升；需要队列后端支持；对于调用量较低的服务而言属于过度设计。
推荐意见： 选择选项 A。当前的调用量无需引入队列架构，而通过共享工具结合指数退避与抖动机制即可有效处理故障，且不会增加新的依赖项。
完成标准：
api_retry()工具用于处理短暂的 HTTP 错误（如 429、502、503、504 状态码）。- 它会以指数退避策略并加入随机抖动，最多尝试重试 3 次。
- 所有的外部 API 调用都会通过该重试工具进行处理。
- 每次重试尝试都会被记录下来，包括对应的接口地址及尝试次数。
- 测试案例涵盖了重试次数耗尽、立即成功以及先出现短暂错误后再成功的各种场景。
实施计划：
- 创建
utils/api_retry.py文件，其中可配置最大重试次数、基础延迟时间以及支持重试的状态码列表。 - 通过使用
random.uniform(0, base_delay)实现随机抖动，以避免大量请求同时发起造成的冲击。 - 在
api_client.py中将现有的 API 调用用该重试工具封装起来。 - 为每种重试场景编写单元测试，使用模拟对象来模拟 HTTP 响应。
- 通过针对不稳定接口的简单压力测试，验证系统在高负载下的表现。