cron

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cron

Cron

Overview

概述

Use this skill to manage Codex automations through the native Zig
cron
CLI. Runtime paths are Zig-only (no Python fallback, no shell launchd wrappers).
使用此技能通过原生Zig
cron
CLI管理Codex自动化任务。运行时路径仅支持Zig(无Python回退,无Shell launchd包装器)。

Zig CLI Iteration Repos

Zig CLI迭代仓库

When iterating on
cron
, use these two repos:
  • skills-zig
    (
    /Users/tk/workspace/tk/skills-zig
    ): source for the
    cron
    binary, build/test wiring, release tags.
  • homebrew-tap
    (
    /Users/tk/workspace/tk/homebrew-tap
    ): formula/checksum updates for released binaries.
在迭代
cron
时,请使用以下两个仓库:
  • skills-zig
    (/Users/tk/workspace/tk/skills-zig):
    cron
    二进制文件的源码、构建/测试配置、发布标签。
  • homebrew-tap
    (/Users/tk/workspace/tk/homebrew-tap):已发布二进制文件的公式/校验和更新。

Quick Start

快速开始

bash
run_cron_tool() {
  install_cron_direct() {
    local repo="${SKILLS_ZIG_REPO:-$HOME/workspace/tk/skills-zig}"
    if ! command -v zig >/dev/null 2>&1; then
      echo "zig not found. Install Zig from https://ziglang.org/download/ and retry." >&2
      return 1
    fi
    if [ ! -d "$repo" ]; then
      echo "skills-zig repo not found at $repo." >&2
      echo "clone it with: git clone https://github.com/tkersey/skills-zig \"$repo\"" >&2
      return 1
    fi
    if ! (cd "$repo" && zig build build-cron -Doptimize=ReleaseFast); then
      echo "direct Zig build failed in $repo." >&2
      return 1
    fi
    if [ ! -x "$repo/zig-out/bin/cron" ]; then
      echo "direct Zig build did not produce $repo/zig-out/bin/cron." >&2
      return 1
    fi
    mkdir -p "$HOME/.local/bin"
    install -m 0755 "$repo/zig-out/bin/cron" "$HOME/.local/bin/cron"
  }

  local os="$(uname -s)"
  if command -v cron >/dev/null 2>&1 && cron --help 2>&1 | grep -q "cron.zig"; then
    cron "$@"
    return
  fi

  if [ "$os" = "Darwin" ]; then
    if ! command -v brew >/dev/null 2>&1; then
      echo "homebrew is required on macOS: https://brew.sh/" >&2
      return 1
    fi
    if ! brew install tkersey/tap/cron; then
      echo "brew install tkersey/tap/cron failed." >&2
      return 1
    fi
  elif ! (command -v cron >/dev/null 2>&1 && cron --help 2>&1 | grep -q "cron.zig"); then
    if ! install_cron_direct; then
      return 1
    fi
  fi

  if command -v cron >/dev/null 2>&1 && cron --help 2>&1 | grep -q "cron.zig"; then
    cron "$@"
    return
  fi
  echo "cron binary missing or incompatible after install attempt." >&2
  if [ "$os" = "Darwin" ]; then
    echo "expected install path: brew install tkersey/tap/cron" >&2
  else
    echo "expected direct path: SKILLS_ZIG_REPO=<skills-zig-path> zig build build-cron -Doptimize=ReleaseFast" >&2
  fi
  return 1
}
  • List automations:
    run_cron_tool list
  • Show one automation:
    run_cron_tool show --id <id>
  • Create an automation:
    run_cron_tool create --name "Weekly release notes" --prompt-file /path/to/prompt.md --rrule "RRULE:FREQ=WEEKLY;BYDAY=FR;BYHOUR=9;BYMINUTE=0"
  • Update an automation:
    run_cron_tool update --id <id> --rrule "RRULE:FREQ=DAILY;BYHOUR=9;BYMINUTE=0"
  • Enable or disable:
    run_cron_tool enable --id <id>
    or
    run_cron_tool disable --id <id>
  • Run immediately:
    run_cron_tool run-now --id <id>
  • Delete:
    run_cron_tool delete --id <id>
  • Run due automations once:
    run_cron_tool run-due
  • Run due automations dry-run:
    run_cron_tool run-due --dry-run
  • Install/start launchd scheduler (macOS):
    run_cron_tool scheduler install
  • Stop/remove launchd scheduler (macOS):
    run_cron_tool scheduler uninstall
  • Show scheduler status (macOS):
    run_cron_tool scheduler status
Runtime bootstrap policy mirrors
seq
/
cas
/
lift
: require the Zig binary, default to Homebrew install on macOS, and fallback to direct Zig install from
skills-zig
on non-macOS.
Subcommand
--help
prints top-level usage. For detailed options, use the matrix below.
bash
run_cron_tool() {
  install_cron_direct() {
    local repo="${SKILLS_ZIG_REPO:-$HOME/workspace/tk/skills-zig}"
    if ! command -v zig >/dev/null 2>&1; then
      echo "zig not found. Install Zig from https://ziglang.org/download/ and retry." >&2
      return 1
    fi
    if [ ! -d "$repo" ]; then
      echo "skills-zig repo not found at $repo." >&2
      echo "clone it with: git clone https://github.com/tkersey/skills-zig \"$repo\"" >&2
      return 1
    fi
    if ! (cd "$repo" && zig build build-cron -Doptimize=ReleaseFast); then
      echo "direct Zig build failed in $repo." >&2
      return 1
    fi
    if [ ! -x "$repo/zig-out/bin/cron" ]; then
      echo "direct Zig build did not produce $repo/zig-out/bin/cron." >&2
      return 1
    fi
    mkdir -p "$HOME/.local/bin"
    install -m 0755 "$repo/zig-out/bin/cron" "$HOME/.local/bin/cron"
  }

  local os="$(uname -s)"
  if command -v cron >/dev/null 2>&1 && cron --help 2>&1 | grep -q "cron.zig"; then
    cron "$@"
    return
  fi

  if [ "$os" = "Darwin" ]; then
    if ! command -v brew >/dev/null 2>&1; then
      echo "homebrew is required on macOS: https://brew.sh/" >&2
      return 1
    fi
    if ! brew install tkersey/tap/cron; then
      echo "brew install tkersey/tap/cron failed." >&2
      return 1
    fi
  elif ! (command -v cron >/dev/null 2>&1 && cron --help 2>&1 | grep -q "cron.zig"); then
    if ! install_cron_direct; then
      return 1
    fi
  fi

  if command -v cron >/dev/null 2>&1 && cron --help 2>&1 | grep -q "cron.zig"; then
    cron "$@"
    return
  fi
  echo "cron binary missing or incompatible after install attempt." >&2
  if [ "$os" = "Darwin" ]; then
    echo "expected install path: brew install tkersey/tap/cron" >&2
  else
    echo "expected direct path: SKILLS_ZIG_REPO=<skills-zig-path> zig build build-cron -Doptimize=ReleaseFast" >&2
  fi
  return 1
}
  • 列出自动化任务:
    run_cron_tool list
  • 查看单个自动化任务:
    run_cron_tool show --id <id>
  • 创建自动化任务:
    run_cron_tool create --name "Weekly release notes" --prompt-file /path/to/prompt.md --rrule "RRULE:FREQ=WEEKLY;BYDAY=FR;BYHOUR=9;BYMINUTE=0"
  • 更新自动化任务:
    run_cron_tool update --id <id> --rrule "RRULE:FREQ=DAILY;BYHOUR=9;BYMINUTE=0"
  • 启用或禁用:
    run_cron_tool enable --id <id>
    run_cron_tool disable --id <id>
  • 立即运行:
    run_cron_tool run-now --id <id>
  • 删除:
    run_cron_tool delete --id <id>
  • 运行一次到期的自动化任务:
    run_cron_tool run-due
  • 模拟运行到期的自动化任务:
    run_cron_tool run-due --dry-run
  • 安装/启动launchd调度器(macOS):
    run_cron_tool scheduler install
  • 停止/移除launchd调度器(macOS):
    run_cron_tool scheduler uninstall
  • 查看调度器状态(macOS):
    run_cron_tool scheduler status
运行时引导策略与
seq
/
cas
/
lift
一致:要求Zig二进制文件,macOS默认使用Homebrew安装,非macOS环境回退到从
skills-zig
直接构建Zig版本。
子命令
--help
会显示顶级使用说明。如需详细选项,请参考下方的命令选项矩阵。

Workflow

工作流程

  1. Choose working directories (
    cwds
    ). Default is current repo if omitted on
    create
    .
  2. Write the automation prompt (use
    --prompt-file
    for multi-line prompts).
  3. Provide an RFC5545 RRULE string.
  4. Create or update with
    cron
    .
  5. For unattended execution, install scheduler via
    cron scheduler install
    .
  1. 选择工作目录(
    cwds
    )。如果在
    create
    时省略,默认使用当前仓库。
  2. 编写自动化任务提示词(多行提示词请使用
    --prompt-file
    )。
  3. 提供RFC5545 RRULE格式的字符串。
  4. 使用
    cron
    创建或更新自动化任务。
  5. 如需无人值守执行,通过
    cron scheduler install
    安装调度器。

Headless Runner

无头运行器

  • cron run-due
    executes due automations by calling
    codex exec
    and updates:
    • automations.last_run_at
    • automations.next_run_at
    • automation_runs
      rows
  • cron run-due --dry-run
    is read-only:
    • no
      automation_runs
      rows are inserted/updated
    • no
      automations.last_run_at
      /
      next_run_at
      updates
    • no automation files or
      memory.md
      writes
  • --codex-bin
    accepts executable name or absolute path (default resolves
    $CODEX_BIN
    or
    codex
    in
    PATH
    ).
  • Locking is label-scoped and fail-closed (
    --lock-label
    , or env
    CRON_LAUNCHD_LABEL
    ).
  • --lock-label
    uses strict label validation: only
    [A-Za-z0-9._-]
    (no slashes/spaces).
  • run-due
    default batch limit is
    10
    automations per invocation (
    --limit
    overrides).
  • Scheduler commands are macOS-only and manage
    ~/Library/LaunchAgents/<label>.plist
    directly from Zig.
  • Launchd scheduler runs
    run-due
    with default DB path and default limit unless you invoke
    cron
    manually with overrides.
  • Logs:
    ~/Library/Logs/codex-automation-runner/out.log
    and
    ~/Library/Logs/codex-automation-runner/err.log
    .
  • cron run-due
    通过调用
    codex exec
    执行到期的自动化任务,并更新以下内容:
    • automations.last_run_at
    • automations.next_run_at
    • automation_runs
      行记录
  • cron run-due --dry-run
    为只读模式:
    • 不会插入/更新
      automation_runs
      行记录
    • 不会更新
      automations.last_run_at
      /
      next_run_at
    • 不会写入自动化任务文件或
      memory.md
  • --codex-bin
    接受可执行文件名或绝对路径(默认解析
    $CODEX_BIN
    PATH
    中的
    codex
    )。
  • 锁定基于标签范围且为失败关闭模式(
    --lock-label
    ,或环境变量
    CRON_LAUNCHD_LABEL
    )。
  • --lock-label
    使用严格的标签验证:仅允许
    [A-Za-z0-9._-]
    (无斜杠/空格)。
  • run-due
    默认每次调用最多处理10个自动化任务(可通过
    --limit
    覆盖)。
  • 调度器命令仅支持macOS,直接通过Zig管理
    ~/Library/LaunchAgents/<label>.plist
  • Launchd调度器会使用默认数据库路径和默认限制运行
    run-due
    ,除非手动调用
    cron
    并指定覆盖参数。
  • 日志位置:
    ~/Library/Logs/codex-automation-runner/out.log
    ~/Library/Logs/codex-automation-runner/err.log

Command Options (High Signal)

命令选项(关键)

  • list
    :
    --status <ACTIVE|PAUSED>
    ,
    --json
  • show
    :
    --id <id>
    or
    --name <name>
    , optional
    --json
  • create
    :
    --name
    ,
    --prompt|--prompt-file
    ,
    --rrule
    , optional
    --status
    ,
    --cwd
    (repeatable),
    --cwds-json
    ,
    --clear-cwds
    ,
    --next-run-at
  • update
    :
    --id|--name
    , optional
    --new-name
    ,
    --prompt|--prompt-file
    ,
    --rrule
    ,
    --status
    ,
    --cwd
    (repeatable),
    --cwds-json
    ,
    --clear-cwds
    ,
    --next-run-at
    ,
    --clear-next-run-at
  • enable|disable|run-now|delete
    :
    --id
    or
    --name
  • run-due
    : optional
    --id
    ,
    --limit
    ,
    --dry-run
    ,
    --codex-bin
    ,
    --lock-label
    (
    [A-Za-z0-9._-]
    only)
  • scheduler install
    : optional
    --label
    ,
    --interval-seconds
    ,
    --path
    ,
    --codex-bin
  • scheduler uninstall|status
    : optional
    --label
  • Scheduler
    --label
    is strict: only
    [A-Za-z0-9._-]
    (no slashes/spaces).
  • list
    --status <ACTIVE|PAUSED>
    --json
  • show
    --id <id>
    --name <name>
    ,可选
    --json
  • create
    --name
    --prompt|--prompt-file
    --rrule
    ,可选
    --status
    --cwd
    (可重复),
    --cwds-json
    --clear-cwds
    --next-run-at
  • update
    --id|--name
    ,可选
    --new-name
    --prompt|--prompt-file
    --rrule
    --status
    --cwd
    (可重复),
    --cwds-json
    --clear-cwds
    --next-run-at
    --clear-next-run-at
  • enable|disable|run-now|delete
    --id
    --name
  • run-due
    :可选
    --id
    --limit
    --dry-run
    --codex-bin
    --lock-label
    (仅允许
    [A-Za-z0-9._-]
  • scheduler install
    :可选
    --label
    --interval-seconds
    --path
    --codex-bin
  • scheduler uninstall|status
    :可选
    --label
  • 调度器
    --label
    有严格限制:仅允许
    [A-Za-z0-9._-]
    (无斜杠/空格)。

Clarify When Ambiguous

模糊场景处理

Ask questions only when the request is ambiguous or when the user explicitly asks for guidance. Do not block otherwise.
Essential elements to confirm or infer:
  1. Automation name.
  2. Prompt content (single line or file path).
  3. Schedule as an RFC5545 RRULE string (include
    RRULE:
    prefix).
  4. Working directories (
    cwds
    ), default to current repo if not specified.
  5. Status if explicitly requested; otherwise default to
    ACTIVE
    .
When ambiguous, ask for missing details. Examples:
  • If user says “daily”/“weekly” without time, ask for required time/day fields.
  • If user says “run it for this repo” without paths, confirm repo root as
    cwd
    .
仅当请求模糊或用户明确寻求指导时才提问。否则无需阻塞流程。
需要确认或推断的关键要素:
  1. 自动化任务名称。
  2. 提示词内容(单行或文件路径)。
  3. 以RFC5545 RRULE字符串形式提供的调度规则(需包含
    RRULE:
    前缀)。
  4. 工作目录(
    cwds
    ),未指定时默认使用当前仓库。
  5. 状态(仅当明确请求时确认;否则默认为
    ACTIVE
    )。
当信息模糊时,询问缺失的细节。示例:
  • 如果用户仅说“每天”/“每周”但未指定时间,询问所需的时间/日期字段。
  • 如果用户说“为这个仓库运行”但未提供路径,确认仓库根目录为工作目录。

Schedule (RRULE)

调度规则(RRULE)

  • Accept only RFC5545 RRULE strings. Cron expressions are unsupported.
  • Rules are canonicalized to
    RRULE:
    -prefixed form.
  • Legacy non-prefixed stored values (
    FREQ=...
    ) are still accepted at run time for compatibility.
  • Validation is fail-closed.
  • BYHOUR
    /
    BYMINUTE
    are interpreted in UTC.
  • Supported frequencies:
    • HOURLY
      requires
      BYMINUTE
    • DAILY
      requires
      BYHOUR
      and
      BYMINUTE
    • WEEKLY
      requires
      BYDAY
      ,
      BYHOUR
      , and
      BYMINUTE
Example rules:
  • Daily at 09:00:
    RRULE:FREQ=DAILY;BYHOUR=9;BYMINUTE=0
  • Weekly on Friday at 09:00:
    RRULE:FREQ=WEEKLY;BYDAY=FR;BYHOUR=9;BYMINUTE=0
  • Every 24 hours:
    RRULE:FREQ=HOURLY;INTERVAL=24;BYMINUTE=0
  • 仅接受RFC5545 RRULE字符串。不支持Cron表达式。
  • 规则会被规范化为带
    RRULE:
    前缀的格式。
  • 为兼容旧版本,运行时仍接受未带前缀的存储值(如
    FREQ=...
    )。
  • 验证为失败关闭模式。
  • BYHOUR
    /
    BYMINUTE
    以UTC时间解析。
  • 支持的频率:
    • HOURLY
      需要
      BYMINUTE
    • DAILY
      需要
      BYHOUR
      BYMINUTE
    • WEEKLY
      需要
      BYDAY
      BYHOUR
      BYMINUTE
规则示例:
  • 每天09:00运行:
    RRULE:FREQ=DAILY;BYHOUR=9;BYMINUTE=0
  • 每周五09:00运行:
    RRULE:FREQ=WEEKLY;BYDAY=FR;BYHOUR=9;BYMINUTE=0
  • 每24小时运行一次:
    RRULE:FREQ=HOURLY;INTERVAL=24;BYMINUTE=0

Task Examples

任务示例

Daily standup summary

每日站会总结

Name:
Summarize yesterday's git activity
Prompt: Summarize yesterday's git activity for standup. Include notable commits, files touched, and any risks or follow-ups. Schedule:
RRULE:FREQ=DAILY;BYHOUR=9;BYMINUTE=0
名称:
Summarize yesterday's git activity
提示词:总结昨天的Git活动用于站会。包括重要提交、涉及的文件,以及任何风险或后续事项。 调度规则:
RRULE:FREQ=DAILY;BYHOUR=9;BYMINUTE=0

Weekly release notes

每周发布说明

Name:
Draft weekly release notes
Prompt: Draft weekly release notes from merged PRs. Include links when available and group by area. Schedule:
RRULE:FREQ=WEEKLY;BYDAY=FR;BYHOUR=9;BYMINUTE=0
名称:
Draft weekly release notes
提示词:从合并的PR中草拟每周发布说明。包含可用的链接并按领域分组。 调度规则:
RRULE:FREQ=WEEKLY;BYDAY=FR;BYHOUR=9;BYMINUTE=0

CI failure triage

CI失败排查

Name:
Summarize CI failures
Prompt: Summarize CI failures and flaky tests from the last CI window, group by root cause, and suggest minimal fixes. Schedule:
RRULE:FREQ=DAILY;BYHOUR=8;BYMINUTE=30
名称:
Summarize CI failures
提示词:总结最近CI周期中的失败和不稳定测试,按根本原因分组,并建议最小修复方案。 调度规则:
RRULE:FREQ=DAILY;BYHOUR=8;BYMINUTE=30

Data Model Reference

数据模型参考

See
references/db.md
for schema and field notes.
请查看
references/db.md
获取表结构和字段说明。