Catalyst Job Scheduling 用于在 Catalyst 平台上运行后台工作，整体由三部分组成：作业池（job pools，作为容量容器）、作业（jobs，每次执行一个，可通过 API/SDK/MCP 立即提交）以及定时任务（crons，按时间表提交作业的调度器）。据资料说明，该技能及其参考中的每项事实均针对一个实时 Catalyst 项目做过运行时验证（2026 年 8 月），除非另有标注。
用途与前置条件
在执行任何操作前，需要先加载 references/job-scheduling-basics.md，其中覆盖了导致大多数失败的五条设置规则：作业池必须首先存在（没有默认池）、目标必须是 JOB 类型的函数、所有时间值以秒为单位、job_name 有长度与字符限制、以及函数与作业池之间的内存约束。
主要能力与工作方式
首先识别目标类型：Job 函数（最常见）、Webhook（任意 HTTP URL）、Circuit 或 AppSail。然后创建或验证匹配类型的作业池（Function 池按内存 MB 设定大小；其他类型按并发数 1–10 设定）。
一次性工作可提交即时作业（MCP 工具 CatalystbyZoho_Create_Immediate_Job，或 SDK 的 jobScheduling().job().submitJob()）。重复或延迟工作则创建 cron（CatalystbyZoho_Create_Cron_Job，或 SDK 的 cron().createCron()），并选择 Periodic、OneTime、Calendar 或 CronExpression 类型。两种路径的精确载荷可参考 references/job-scheduling-basics.md。
Job 函数处理器写法为 (jobRequest, context)：使用 catalyst.initialize(context, { scope: 'admin' }) 初始化 SDK，通过 jobRequest.getAllJobParams() 读取输入（所有值都以字符串形式到达），并且必须以 context.closeWithSuccess() 或 closeWithFailure() 结束——失败正是触发重试链的条件。
重试、动态调度、Webhook 目标与监控
如需重试、动态调度、Webhook 目标或监控，可加载 references/job-scheduling-advanced.md，其中涵盖重试语义（新作业记录通过 parent_job_id 关联）、触发行为（Periodic cron 在创建和更新时都会立即触发；日期已过的 OneTime 会立即触发；OneTime 触发后自动禁用）以及可观测性陷阱（成功/失败计数器保持为 0；动态 cron 在列表 API 中不可见）。
验证应依据作业记录而非计数器：CatalystbyZoho_Get_Job_By_Id 会显示 job_status（PENDING → RUNNING → SUCCESS | FAILURE）、execution_time、dispatch_delay、response_code。不要信任 cron 的 success_count/failure_count——它们会一直保持为 0。
安全清单
切勿整体记录 jobRequest.getJobDetails() 或 getJobMetaDetails()——运行时其头部包含实时凭据（X-ZC-PROJECT-SECRET-KEY、X-ZC-Admin-Cred-Token），只提取所需字段。指向自身项目函数 URL 的 Webhook 目标作业会携带同样的凭据头，应将 Webhook 接收方日志视为敏感信息。Job 函数以管理员权限运行，因此在使用通过参数接收的任何内容进行查询前，必须验证或白名单化。切勿在作业头部/参数中存储机密——Get_Job_By_Id、Get_Cron_Job_By_Id、List_All_Crons 会以明文返回它们。切勿将原始 cron/作业转储粘贴到聊天、issue 或日志中。
常见错误与防幻觉提示
SDK 枚举 CRON_TYPE.CALENDER（拼写为 "Calender"）拼写错误且会被服务器拒绝，应使用字符串 'Calendar'。retry_interval 不是毫秒，而是秒，范围 60–86400，15 * 60 * 1000 会被拒绝。即时作业与计划作业共享相同的 15 分钟超时；context.getMaxExecutionTimeMs() 返回字符串 "900000"（做数学运算前需 parseInt），而 getRemainingExecutionTimeMs() 返回数字。
触发词与错误信息
触发词包括："job scheduling"、"job pool"、jobpool、jobpool_id、"create a job pool"、"submit a job"、"immediate job"、"background job"、"run this function as a job"、submitJob、Create_Immediate_Job、"cron"、"cron job"、"scheduled function"、"schedule a function"、"recurring job"、createCron、Create_Cron_Job、cron_expression、time_of_execution、"Periodic"、"OneTime cron"、"Calendar cron"、"retry a job"、number_of_retries、retry_interval、parent_job_id、"dunning"、"billing schedule"、"trial expiry job"、pauseCron、resumeCron、runCron、deleteCron、"pause a cron"、"trigger a cron manually"、Submit_Cron_Job、"webhook job"、"call a URL on schedule"、notify_url。
常见错误信息包括："The given function is not a job function"、"job_name must contain only alphanumeric and underscore"、"job_name should be within 1-20 char length"、"retry interval should be within 60s"、"Delete all associated Pre-defined Crons before deleting Job Pool"、"memory allocated for the Job Function is higher"。
参考资料
references/job-scheduling-basics.md：适用于核心概念、作业池、即时作业、全部 4 种 cron 类型、MCP 工具工作流、Node SDK 调用、Job 函数处理器模板、CLI 设置。references/job-scheduling-advanced.md：适用于重试语义、动态（代码内）cron 创建、触发/时序行为、Webhook 目标作业、notify_url、监控/可观测性、安全护栏、池容量规则。
适用场景与限制
该技能适用于在 Catalyst 平台上安排后台作业、定时任务、重试与 Webhook 调度等场景。限制方面：作业池无默认值，必须先创建；目标必须为 JOB 类型函数；时间值统一以秒为单位；job_name 仅允许字母数字与下划线且长度 1–20；retry_interval 为 60–86400 秒；即时与计划作业共享 15 分钟超时；cron 成功/失败计数器不可信；动态 cron 在列表 API 中不可见；凭据可能出现在作业头部与记录中，需谨慎处理。