跳到主要内容

一三一法则

技术方案与权衡分析的结构化决策框架。当用户在多个方法之间做选择时（架构决策、工具选型、重构策略、迁移路径），此技能会生成一个 1-3-1 格式的回复：一个清晰的问题陈述、三个各有优劣的选项、以及一个包含完成标准和实施计划的具体建议。当用户要求“1-3-1”、说“给我一些选项”、或需要在不同方法之间做选择时使用。

技能元数据​

来源可选 — 使用 hermes skills install official/communication/one-three-one-rule 安装
路径optional-skills/communication/one-three-one-rule
版本1.0.0
作者Willard Moore
许可证MIT
标签communication, decision-making, proposals, trade-offs

参考：完整 SKILL.md​

信息

以下是 Hermes 在触发此技能时加载的完整技能定义。这是技能激活时 Agent 看到的指令。

1-3-1 沟通法则

当任务有多个可行方法且用户需要明确建议时使用的结构化决策格式。生成简洁的问题描述、三个带有权衡的选项、以及推荐路径的可执行计划。

何时使用​

  • 用户明确要求“1-3-1”格式的回复。
  • 用户说“给我一些选项”或“我有哪些选择”来询问技术决策。
  • 任务有多个可行方法且存在有意义的权衡（架构、工具、迁移策略）。
  • 用户需要一个可以转发给团队或利益相关者的方案。

不要用于有唯一明显答案的简单问题、调试场景、或用户已经决定采用某个方法的情况。

流程​

  1. 问题（一句话）

    • 用一句简洁的话陈述核心决策或期望结果。
    • 聚焦于“做什么”，而不是“怎么做”——不涉及实现细节、工具名称或具体技术。
    • 保持紧凑。如果你需要用到“和”字，说明你在描述两个问题。

  2. 选项（恰好三个）

    • 提供三个不同且可行的方案，分别标记为 A、B、C。
    • 每个选项包含简要描述、优点和缺点。
    • 选项应代表真正不同的策略，而不是同一方法的微小变体。

  3. 建议（一个选项）

    • 根据用户的背景和优先级，说明你推荐哪个选项及其原因。
    • 直接了当——这是你的专业判断，不是模棱两可的措辞。

  4. 完成标准

    • 列出推荐选项的具体成功标准。
    • 这些是具体、可验证的结果——不是模糊的期望。
    • 如果用户选择了其他选项，请修改此部分以匹配。

  5. 实施计划

    • 执行推荐选项的具体步骤。
    • 在适用的情况下包含具体命令、工具或操作。
    • 如果用户选择了其他选项，请修改此部分以匹配。

验证​

  • 回复中恰好包含一个 Problem 句子。
  • 回复中恰好包含三个选项（A、B、C），每个选项都有优缺点。
  • 回复中有一个 Recommendation，选择其中一个选项并给出理由。
  • DoD（完成定义）和 Implementation Plan（实施计划）与推荐的选项一致。
  • 如果用户选择了不同的选项，Recommendation、DoD 和 Implementation Plan 会相应更新。

示例​

用户：“给我一个 1-3-1，关于为我们的 API 客户端添加重试逻辑。”

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) 添加抖动，防止惊群效应。
  3. 使用重试工具类包装 api_client.py 中现有的 API 调用。
  4. 添加单元测试，模拟每个重试场景的 HTTP 响应。
  5. 通过对一个不稳定的端点模拟进行简单的压力测试，验证负载下的表现。