Skip to main content
Schedules

Schedule 数据结构

Forward Schedule API 复用的 Schedule 和 Schedule Run 响应结构。

Schedule 对象

创建、查询、列表、更新、归档、暂停和恢复接口返回该结构。
字段类型说明
idstringSchedule ID，前缀为 sched_。
sourcestring权威创建方式，当前为 api 或 tool。详见创建来源。
source_session_idstring | null创建来源 Session。api 来源为 null，tool 来源为非空 sess_*。
identity_idstringSchedule 所属 Forward Identity ID。
template_idstringSchedule 执行使用的 Forward Template ID。
namestringSchedule 名称。
descriptionstringSchedule 描述；未设置时为空字符串。
statusstringactive 或 paused；归档状态通过 archived_at 表达。
paused_reasonobject | null暂停原因；未暂停时为 null。
initial_eventsarray每次执行时注入的初始事件。
initial_events_versioninteger只读输入内容版本，从 1 开始；递增规则见输入版本。
resourcesarraySchedule 专属文件配置，按 file_id 排序；未配置时为 []。结构和生效规则见文件资源。
executionobject执行策略，字段见执行策略。
trigger_policyobject触发策略，字段见触发策略。
environment_idstring执行环境 ID。
sinksarray结果推送目标；未配置时为 []。
metadataobject调用方业务元数据。
archived_atstring | null归档时间，RFC 3339；未归档时为 null。
created_atstring创建时间，RFC 3339。
updated_atstring最后更新时间，RFC 3339。

执行策略

字段类型说明
session_modestringnew_session 或 reuse_session。
max_concurrent_runsinteger同一 Schedule 最大并发 Run 数。
max_attemptsinteger单个 Run 的最大尝试次数，当前为 1 或 2。
timeout_msinteger单次尝试超时时间，单位毫秒。

触发策略

字段类型说明
typestringcron、once、interval 或 manual。
expressionstring触发表达式；manual 时为空字符串或省略。
timezonestringIANA timezone；不适用时为空字符串或省略。
start_atstring可选执行窗口开始时间，RFC 3339。
stop_atstring可选执行窗口结束时间，RFC 3339。
upcoming_runs_atarray后续触发时间，UTC ISO 8601；当前返回 [] 或最多一个时间。
last_run_atstring | null最近一次触发时间。
sinks 的公开格式和约束见创建 Schedule。

文件资源

创建和更新 Schedule 时，通过顶层 resources 数组指定文件，格式与 Session、Batch 的文件资源一致。先通过上传 File获得 file_id，再引用当前调用方在该 Schedule 的 Identity 下有权访问的 Forward File。 
{
  "resources": [
    {
      "type": "file",
      "file_id": "file_news_sources",
      "mount_path": "/data/news-sources.csv"
    }
  ]
}
字段类型是否必填说明
typestring是当前只支持 file。
file_idstring是Files API 返回的文件 ID，按不透明字符串处理，不要求固定前缀；不能为空或包含控制字符。
mount_pathstring否Agent 容器内的文件路径。显式指定时必须是规范绝对路径，不能为 /，不能包含控制字符，最长 1024 字节。
每个元素只能包含上述字段，不接受 enabled 等额外字段。最多指定 100 个文件；同一数组不能重复 file_id，也不能为不同文件显式指定相同挂载路径。接口不接受顶层 files 参数。 省略或传空字符串的 mount_path 使用 /data/workspace/<filename>；同名文件应显式指定不同路径。若同一文件已由 Template / Identity Config 配置，省略 Schedule 路径时沿用继承路径。

创建与更新

请求中的 resources创建 Schedule更新 Schedule
省略不配置专属文件。保留原配置。
null 或 []不配置专属文件。清空全部专属文件配置。
非空数组配置数组中的文件。整组替换专属文件配置，不按元素合并。
完整 Schedule 响应始终返回 resources 数组，包括旧 Schedule 的 []。它只表示 Schedule 自身配置，不包含 Template / Identity Config 的继承文件；省略的挂载路径不会在此补全为运行时路径。修改 resources 不递增 initial_events_version，该版本仅描述 initial_events。

继承与生效时点

执行时将 Schedule 文件与当前 Template / Identity Config 的文件合并。同一 file_id 去重：Schedule 省略路径或显式路径与继承路径相同时可复用，显式指定不同路径会冲突；不同文件不能占用同一路径。与继承配置合并后才能发现的冲突，会在执行时、发送任务消息前报错。 new_session 和 reuse_session 均支持文件配置。每个执行尝试在创建 Session 或发送任务前选定本次 Schedule 专属 resources；同一 attempt 的发送重试和恢复沿用已选的专属文件配置，新的 attempt 可以选用更新后的配置。更新不打断当前执行；后续执行会应用选定的新增、移除和路径变更，复用 Session 时也会同步。Template / Identity Config 的继承文件不属于该快照，仍按当前配置刷新。 清空 Schedule 文件不会移除继承文件，也不会修改 Template / Identity Config。文件挂载不会将内容自动插入 initial_events；任务可在消息中按挂载路径读取文件，例如 Read /data/news-sources.csv and summarize its contents。

文件删除限制

未归档的 Schedule（包括已暂停的 Schedule）引用文件时，删除 File返回 HTTP 409。更新或清空文件配置、归档 Schedule 会释放该配置引用；尚未进入终态的 Run 已选定的文件仍受保护，直到 Run 结束。其他 Template / Identity Config 或 Session 的引用也可能继续阻止删除。

Schedule Run 对象

手动运行、查询 Run 和列出 Runs 接口返回该结构。
字段类型说明
idstringSchedule Run ID，前缀为 srun_。
sourcestring父 Schedule 的权威创建方式，当前为 api 或 tool。详见创建来源。
source_session_idstring | null父 Schedule 的创建来源 Session。
schedule_idstring所属 Schedule ID。
identity_idstringForward Identity ID。
template_idstringForward Template ID。
session_idstring | null本次执行创建或使用的 Session。
statusstringpending、running、completed、failed 或 skipped。
trigger_contextobject本次 Run 的触发方式，详见 Trigger Context。
errorobject | null失败或跳过时的结构化错误。
result_payloadstring | null主流程文本结果。
error_messagestring | null便于展示的错误信息；结构化信息保留在 error。
push_sinkstring | null本次 IM 投递使用的 Sink 类型；未配置时为 null。
push_statusstringIM 投递状态：pending、succeeded、failed 或 skipped。
push_finished_atstring | nullIM 投递结束时间。
attemptinteger当前或最终实际执行到第几次，从 1 开始。
initial_events_versioninteger（可选）当前执行尝试所选输入的版本；尚未选择或无法确认时省略，见输入版本。
initial_eventsarray（可选）仅在获取单条 Run 且传 include_initial_events=true 时，返回当前尝试已绑定的输入快照；未知时省略，详见查询输入快照。
triggered_atstring触发时间，RFC 3339。
started_atstring | null开始执行时间，RFC 3339。
completed_atstring | null结束时间，RFC 3339。
duration_msinteger | null执行耗时，单位毫秒。
created_atstring记录创建时间，RFC 3339。
主流程 status 与 IM 投递 push_status 相互独立。Schedule 配置 execution.max_attempts=2 时，同一个 Run 最终可能返回 attempt=2。

Identity 启停与排期

Identity 停用期间不启动新的 Schedule 执行，尚未开始的 Run 可能被记录为 skipped；已接受的执行及结果投递会自然完成。重新启用后，周期任务从未来的触发点继续，不补跑停用期间错过的触发；已经过期的一次性触发保留 skipped Run 并按正常规则归档。手动暂停、已归档或已删除的 Schedule 不会因 Identity 启用而恢复，详见启用 Identity。

输入版本

initial_events_version 由服务端维护，无需在创建或更新请求中传入。新建 Schedule 为 1；只有规范化后的 initial_events 实际改变时才递增。相同内容更新、修改 resources、名称或执行/触发策略不递增；改回曾经使用的内容仍会生成新的版本。存量 Schedule 的当前输入以 1 为基线，不追溯历史版本。 Run 创建时尚未绑定输入；在本次 attempt 首次发送输入前，执行器将匹配的内容和版本绑定到 Run。同一 attempt 的发送重试和恢复沿用该绑定，新的 attempt 可以选用更新后的输入。因此应结合 attempt 理解 Run 的版本，版本存在仅表示已选择输入，不代表运行时已经接收或执行成功。 尚未选择输入的 pending、skipped Run，以及无法确认执行输入的历史 Run，会省略该字段；未知版本不返回 0，也不能用当前 Schedule 的版本补齐。接入方应兼容新增字段，并将缺失版本视为未知。 接入方可在创建或更新 Schedule 后保存 schedule_id、initial_events_version 与输入内容的对应关系，再按 Run 或 Webhook 回调中的版本关联执行输入。当前 Schedule 返回的是最新配置，可能与已经开始执行的 Run 不同。 可通过获取 Schedule Run并传 include_initial_events=true 回查该次所选输入，无需依赖当前 Schedule 的配置。

创建来源

source 和 source_session_id 是只读字段，在 v1/v2 的完整 Schedule 和 Schedule Run 响应中始终存在。
sourcesource_session_id含义
apinull通过公开 Schedule API 创建。
tool非空 sess_*通过 Forward 托管工具创建，关联发起创建工具调用的交互 Session。
来源由服务端记录，不能通过创建或更新请求设置，也不支持按来源筛选。metadata.source 只是可修改的业务元数据，不代表权威来源。 Schedule Run 继承父 Schedule 的来源，与本次手动或自动触发、是否配置 sinks 无关；历史 Run 和已归档 Schedule 的 Run 同样适用。Run 的 session_id 表示本次执行 Session，trigger_context.type 表示本次触发方式。来源 Session 不表示 reuse_session 的执行绑定，内部来源结果投递目标也不作为公开来源。 来源字段是兼容新增的 JSON 字段，客户端应容忍未知字段。服务部署后，历史 Schedule 和 Run 的查询响应也返回来源字段，不需要数据回填。

Trigger Context

type说明
schedule系统根据 Schedule 触发策略自动触发；包含 scheduled_at。
manual调用运行 Schedule 接口手动触发。

Run Error

status=failed 或 status=skipped 时可能返回 error；status=completed 时为 null。
error.type说明
concurrency_limit_reached同一个 Schedule 已达到最大并发 Run 数，本次触发已记录但不会执行。
session_creation_failed创建或绑定 Forward Session 失败。
execution_failedTemplate 执行失败。