StepAmoo 的定时任务只负责“到点把任务叫起来”，任务该不该真正执行，取决于触发条件怎么写。把触发条件拆成时间、条件、依赖三层逐项确认：时间层决定何时唤醒，条件层决定动作是否成立，依赖层决定前置数据是否就绪。任何一层写模糊，都会出现两种结果：该跑的时候任务被判为不满足而跳过，不该跑的时候任务因为默认值或空值恰好为真而执行。建议先判断任务属于时间触发还是条件触发，再把条件改写成能被求值出 true/false 的表达式，最后用手动触发验证一次，然后再交给调度器等待。

StepAmoo 定时任务漏跑、误跑，多数不是调度器失灵，而是触发条件写得无法判断或触发类型用错。适用场景：任务需要在特定时间点或特定状态达成后执行。操作动作：先区分时间触发与条件触发，把条件写成带字段名、比较符、阈值、时区的布尔表达式，再手动触发一次。验证方式：看任务状态流转和日志里的条件求值结果。风险边界：条件里含“尽快、空闲时、准备好”这类描述，任何验证都无法给出确定判断。

先确认这个任务属于定时还是条件触发

判断依据很直接：如果执行与否只由时钟决定，前置数据没有到位也照样该跑，就属于时间触发；如果执行与否取决于某个状态、某个文件、某条记录的当前取值，就属于条件触发。用错类型的典型症状是把条件触发写成定时触发，任务每天到点都跑，但数据没到位，跑出来的结果是空或旧值；反过来把时间触发写成条件触发，条件一直不成立，任务就一直挂在等待中。

典型使用场景可以这样区分：日报汇总、日志滚动清理、缓存过期回收这类“到点就该做，做的时候数据齐不齐都要做”的任务，用时间触发；上游任务成功后才开始下游加工、订单状态变为已支付才发通知、某个入参文件落地后才导入，用条件触发。两者也可以叠加，但叠加时要明确先后：通常是时间触发负责唤醒，条件触发负责在唤醒后决定是否继续。

把触发条件写成可判断的句子

条件是否可判断，标准是能否在任意时刻对条件求出一个确定的 true 或 false。写条件时至少补齐四个要素：字段从哪里取、用什么比较、阈值是多少、在哪个时间窗口内有效。下面是一段通用配置骨架，字段名需要按实际环境替换，结构可以照此组织：

trigger:
  type: condition            # 或 schedule
  when:
    - source: upstream_task   # 取值的来源
      field: status           # 具体字段
      op: equals              # 比较符
      value: success          # 阈值
    - source: storage
      field: input_file_exists
      op: equals
      value: true
  window:
    start: "2025-01-01 00:00"
    end:   "2025-01-01 06:00"
    timezone: Asia/Shanghai   # 显式写时区，不依赖宿主默认值
  repeat: false               # 窗口内是否允许重复执行

会导致无法判断的表述需要单独标注出来，看到就应当改写：“数据准备好之后”——准备好没有判定字段；“业务空闲时”——空闲没有阈值；“上游完成后尽快”——尽快没有上下界；“每天跑一次就行”——没写具体时间点和时区；“有数据就跑”——空集合、全零、状态为 null 时是否算有数据没有约定。把这些句子改写成“字段 X 取值等于 Y”“集合元素数量大于 0”“任务状态为 success”这类形式，条件才具备可验证性。

用一次手动触发验证条件成立与否

不要直接等到预定时间看结果，先手动跑一次。手动触发的位置通常在任务详情页的“立即运行”或“手动触发”入口，也可以通过命令行执行，命令名以实际环境为准，常见形式如下：

# 先做一次不产生副作用的求值检查
stepamoo task run `--id` <task_id> `--dry-run`

# 正式触发并跟踪日志
stepamoo task run `--id` <task_id>
stepamoo task logs `--id` <task_id> `--follow`

需要观察三类返回：一是任务状态流转，是否从等待变为运行再变为成功或失败，卡在等待通常说明依赖层没有满足；二是日志里的条件求值行，逐条看每个字段被读到的实际值和求值结果，这一步能直接暴露字段取不到值、取到字符串“false”被当成真值这类问题；三是副作用是否发生，输出文件是否生成、目标表写入行数是否合理。手动触发前建议确认任务具备幂等性，或者在测试数据上执行，避免重复写入。

记录未触发的三种常见原因

把未触发的情况归到三类，排查时可以直接对号入座。第一类是依赖未完成：任务处于等待态，日志里有上游任务未就绪或前置文件不存在的记录，调度器侧通常能看到本次唤醒被标记为因依赖跳过；这类问题要先确认上游是否真的运行成功，而不是调下游的超时时间。第二类是条件不满足：任务被唤醒但很快结束，日志里能看到条件求值那几行打印出的实际值与期望值不一致，常见原因是字段名写错读成空值、状态值大小写不匹配、数值被当作字符串比较。第三类是时间窗口错开：任务确实运行了，但运行时间落在预期窗口之外，日志里的调度时间与窗口起止对不上，最容易被忽略的是时区——宿主默认时区与窗口声明的时区不一致时，实际运行时间可能整体偏移若干小时，表现为“今天该跑的跑到了昨天或明天”。

这三类原因对应的处理动作不同：依赖问题改上游或改依赖声明，条件问题改字段和比较符，时间窗口问题改时区或改窗口起止。建议每次排查后把当次的现象和日志特征记录在任务备注里，下次同类任务上线前对照检查一遍，比反复重跑更容易定位。