cron-schedule-planner

Cron 计划规划器

收集各个仓库中 GitHub Actions 的 on.schedule cron 表达式，判断每个工作流的资源消耗强度，将 UTC cron 时间转换为本地时区，并生成 Markdown 报告，其中包含每小时直方图、冲突情况和具体的任务分配调整建议。

只读：脚本不会编辑工作流。只有在用户确认后才会应用建议。

使用说明

步骤 1：确定仓库范围

• 默认：已通过身份验证的 gh 用户的所有仓库（无需本地检出）。
• 使用 --owner <owner> 扫描其他所有者。
• 使用 --repo <owner/repo> 指定仓库列表（可重复使用）。
• 使用 --local <dir> 扫描本地检出，而不是调用 GitHub API。

步骤 2：运行脚本

bash scripts/cron-schedule-planner.sh

常见变体：

# Specific owner, Swiss local time, report in target/
bash scripts/cron-schedule-planner.sh --owner dboeckli --tz Europe/Zurich

# Local checkouts (no GitHub API)
bash scripts/cron-schedule-planner.sh --local ~/projects/referenzen

# A few explicit repos
bash scripts/cron-schedule-planner.sh --repo dboeckli/ai-agent-skills --repo dboeckli/camel-first

步骤 3：查看结果

脚本会输出每小时直方图、冲突情况和建议，并写入 target/cron-schedule-overview.md。请总结：

• 找到了多少个仓库 / 定时任务条目；
• UTC 时间中最拥挤的时段（冲突）；
• 哪些高强度任务位于拥挤时段。

步骤 4：仅在确认后应用建议

重新分配建议基于启发式规则（将高强度任务从拥挤时段移到空闲时段，同时保留分钟和日期字段）。请以差异形式展示这些建议，并且只有在明确确认后才修改工作流文件。切勿自动编辑。

选项

选项	含义
--owner <owner>	要扫描的 GitHub 所有者（默认为已通过身份验证的用户）
--repo <owner/repo>	指定仓库（可重复使用）；禁用所有者扫描
--local <dir>	扫描 <dir> 下的本地检出，而不是扫描 GitHub
--tz <zone>	Local 列使用的本地时区（默认 Europe/Zurich）
--limit <n>	所有者扫描的仓库数量上限（默认 200）
--out <file>	Markdown 报告（默认 target/cron-schedule-overview.md）
--no-report	仅输出到控制台，不生成报告文件
--top <n>	重新分配建议的数量上限（默认 5）
--queue-stats	添加按 UTC 小时统计的实际排队时间（通过 gh run list 获取）
--runs <n>	每个仓库用于队列统计的运行次数上限（默认 50）

输出

target/cron-schedule-overview.md：

• 定时工作流表格：仓库、工作流、cron（UTC）、UTC 时间、本地时间、频率、强度、依据。
• 每 UTC 小时的运行次数直方图（条形图）。
• 按频率 / 星期几统计的运行次数。
• 冲突——包含两个或更多定时运行的 UTC 小时。
• 按 UTC 小时统计的实际排队时间（使用 --queue-stats）——根据近期运行中 createdAt 与 startedAt 之间的等待时间计算平均值和最大值，作为实际竞争程度的信号。
• 重新分配建议——将拥挤时段中的高强度任务移至空闲时段；使用 --queue-stats 时，优先选择实际排队时间最低的空闲时段。

分类

强度根据工作流内容通过启发式规则判断。具体模式以及 UTC / 时区规则请参见 references/classification-and-timezones.md。

• high — Docker Compose、Testcontainers、服务容器（services:）、Kind/k3s 集群、矩阵构建。
• medium — Maven/Gradle 完整构建、Docker 镜像构建。
• low — lint/format/validate 及其他元工作流。

示例

示例 1：我安排的构建是否发生冲突？

用户说：“我安排的 GitHub Actions 构建会发生冲突吗？”

操作：

1. 运行 bash scripts/cron-schedule-planner.sh --owner <owner>
2. 报告拥挤的 UTC 时段，以及这些时段中的高强度作业
3. 指向 target/cron-schedule-overview.md

结果：提供所有仓库的冲突概览，并附上具体依据。

示例 2：Testcontainers 构建应该安排在什么时候运行？

用户说：“我应该把 Testcontainers 构建安排在什么时候运行？”

操作：

1. 运行规划工具并找出拥挤的时段（冲突）
2. 从建议中推荐一个空闲时段
3. 提供具体的 cron 差异；仅在确认后应用

结果：给出一个竞争较少的时段，以及可直接应用的 cron 更改。

故障排除

gh: not found 或身份验证错误

脚本需要已完成身份验证的 gh。运行 gh auth status；如果失败，用户必须进行身份验证。也可以使用 --local <dir> 搭配本地检出。

报告为空

范围内没有工作流包含 on.schedule 条目。请检查仓库范围（--owner、--repo、--local），并确认工作流确实定义了 schedule: cron。

时间看起来相差一小时

Cron 始终使用 UTC。当地时间根据当前日期计算，因此夏令时转换可能会导致时间相差一小时。夏令时变更后重新运行，或手动调整。

--queue-stats 显示的数据很少或没有数据

GitHub 对大多数运行报告的 startedAt 与 createdAt 相同（没有记录排队时间），因此可用信号较少。增大 --runs 以包含更早的运行记录。请谨慎看待较大的时间差：它们可能是由审批关卡、并发限制或手动运行导致的，不一定是运行器竞争。