[Product Designer] plan(issue-110): scheduled-workflow-jitter-throttling

plans/110-scheduled-workflow-jitter-throttling.md

@@ -0,0 +1,62 @@
+---
+status: TODO
+---
+
+# 需求分析：Issue #110 [Backlog Discovery] feat(backlog): scheduled-workflow-jitter-throttling
+
+## 1. 背景与目标
+- self 依赖 GitHub 定时工作流驱动自迭代，整点触发容易出现排队与延迟，影响稳定性与可预期性。
+- 通过错峰调度与节流策略降低高峰拥塞与无效运行成本，提升定时任务可靠性与资源效率。
+
+## 2. 需求摘要
+- 为定时工作流引入统一的错峰调度策略（jitter），避免整点集中触发。
+- 引入节流/跳过策略（throttling），在无变化或低价值场景减少无效运行。
+- 提供可配置与可观测能力，支持统计延迟、跳过率与节省成本。
+
+## 3. 范围定义（In Scope / Out of Scope）
+In Scope:
+- 设计错峰调度策略：基于定时触发时间添加抖动窗口与分布规则。
+- 定义节流条件与兜底规则：例如无变更、重复任务、未达到最小间隔时的处理策略。
+- 增加配置入口与默认值建议，支持不同工作流按需覆盖。
+- 增加观测指标与日志字段：延迟、跳过原因、节省运行时长/次数。
+
+Out of Scope:
+- 重构现有业务逻辑或工作流业务步骤。
+- 引入全新的外部调度系统或迁移到非 GitHub Actions 调度方案。
+
+## 4. 需求拆解
+1. 错峰调度策略设计
+   - 定义抖动窗口大小（如 0-10 分钟）与分布算法，避免同一批任务集中。
+2. 节流判定与兜底执行
+   - 明确触发判定条件（无变更、重复运行间隔、低价值任务）。
+   - 设定兜底规则（例如每日/每周最小执行次数保证）。
+3. 配置与参数落地
+   - 在仓库或 workflow 层提供默认配置与覆盖机制。
+4. 观测与度量
+   - 增加延迟率、平均排队时间、跳过率、节省运行成本统计。
+5. 文档与示例
+   - 提供使用指南与示例配置，方便维护者理解与调整。
+
+## 5. 技术方案建议
+- 采用 deterministic jitter：基于 workflow 名称、仓库、日期等生成稳定抖动，确保可预期与可重放。
+- 节流策略以“无变更 + 最小间隔 + 最小执行次数”组合判定，避免误跳过。
+- 通过 workflow 输入参数或仓库级配置文件提供默认值，并在日志中输出决策与原因。
+
+## 6. 风险与依赖
+- 依赖近 30 天的延迟与运行时长统计作为收益评估依据。
+- 节流误判导致关键任务未执行，影响自驱迭代节奏。
+- 错峰参数不当可能引发执行时间漂移或跨日执行风险。
+
+## 7. 验收标准
+- 定时工作流支持配置抖动窗口，且同一批任务触发时间分散。
+- 节流判定条件可配置，且日志中记录跳过原因与兜底执行结果。
+- 提供统计输出或报表，能够量化延迟率下降与运行次数减少情况。
+
+## 8. 待确认问题
+- 近 30 天定时工作流的排队延迟、运行时长与成本基线数据是多少？
+- 节流策略的“兜底执行频率”应如何定义（例如每天至少一次或每周至少一次）？
+- 是否需要对不同类型工作流设定差异化默认策略？
+
+## 9. 更新记录
+- <YYYY-MM-DD HH:mm:ss +08:00> 初始化需求分析文档。
+- 2026-02-21 16:10:25 +08:00 更新需求分析内容，补充错峰与节流策略细化、风险与验收标准。