catalyst-job-scheduling

Catalyst 作业调度

作业调度分为三个部分，用于运行后台任务：作业池（容量容器）、作业（每个作业执行一次，通过 API/SDK/MCP 立即提交）和 Cron（按时间表提交作业的调度器）。除非另有标注，本技能及其参考资料中的所有信息均已在真实的 Catalyst 项目中经过运行时验证（2026 年 8 月）。

前提条件

执行任何操作前，先加载 references/job-scheduling-basics.md——其中介绍了最容易导致失败的五条设置规则：必须先创建作业池（没有默认池）、目标必须是 JOB 类型函数、所有时间值都以秒为单位、job_name 的限制，以及函数与作业池之间的内存限制。

工作原理

1. 确定目标类型：作业函数（最常见）、Webhook（任意 HTTP URL）、Circuit 或 AppSail。创建或确认有与之类型匹配的作业池（Function 池按 memory MB 定容量；其他类型按并发 number 定容量，范围为 1–10）。
2. 一次性任务 → 提交即时作业（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，查看这两种路径的精确载荷。
3. 编写 Job 函数处理程序 (jobRequest, context)：使用 catalyst.initialize(context, { scope: 'admin' }) 初始化 SDK，通过 jobRequest.getAllJobParams() 读取输入（所有值都会以字符串形式传入），并且务必以 context.closeWithSuccess() 或 closeWithFailure() 结束——失败会触发重试链。
4. 处理重试、动态调度、Webhook 目标或监控时，加载 references/job-scheduling-advanced.md——其中介绍了重试语义（通过 parent_job_id 关联的新作业记录）、触发行为（Periodic Cron 在创建和更新时都会立即触发；日期已过的 OneTime 会立即触发；OneTime 触发后会自动禁用），以及可观测性陷阱（成功/失败计数始终为 0；动态 Cron 不会显示在列表 API 中）。
5. 根据作业记录验证，而非计数器：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() 的内容——运行时，它们的 headers 包含有效凭据（X-ZC-PROJECT-SECRET-KEY、X-ZC-Admin-Cred-Token）。只提取所需字段。
• 面向自有项目函数 URL 的 Webhook 目标作业也会携带相同的凭据标头；请将 Webhook 接收端日志视为敏感信息。
• 作业函数以管理员权限运行——使用 params 执行查询前，验证/设定允许列表，限制所接受的内容。
• 切勿将密钥存入作业的 headers/params——Get_Job_By_Id / Get_Cron_Job_By_Id / List_All_Crons 会以明文返回这些内容。切勿将原始 Cron/作业数据转贴到聊天、问题跟踪或日志中。

防幻觉提示

• SDK 枚举 CRON_TYPE.CALENDER（“Calender”）拼写有误，且会被服务器拒绝。请使用字符串 'Calendar'。
• retry_interval 的单位不是毫秒，而是秒，范围为 60–86400。15 * 60 * 1000 会被拒绝。
• 即时作业和计划作业共用 15 分钟超时；context.getMaxExecutionTimeMs() 返回字符串 "900000"（进行运算前先用 parseInt 转换），而 getRemainingExecutionTimeMs() 返回数字。

触发词

• “任务调度”、“任务池”、“jobpool”、jobpool_id、“创建任务池”
• “提交任务”、“立即执行的任务”、“后台任务”、“将此函数作为任务运行”、submitJob、Create_Immediate_Job
• “cron”、“cron 任务”、“定时函数”、“安排函数定时执行”、“周期性任务”、createCron、Create_Cron_Job、cron_expression、time_of_execution、“周期性”、“一次性 cron”、“日历 cron”
• “重试任务”、number_of_retries、retry_interval、parent_job_id、“催款”、“账单计划”、“试用期到期任务”
• pauseCron、resumeCron、runCron、deleteCron、“暂停 cron”、“手动触发 cron”、Submit_Cron_Job
• 错误：“给定的函数不是任务函数”、“job_name 只能包含字母数字和下划线”、“job_name 长度应为 1–20 个字符”、“重试间隔应在 60 秒以内”、“删除任务池前，请先删除所有关联的预定义 Cron”、“为任务函数分配的内存过高”
• “webhook 任务”、“按计划调用 URL”、notify_url

参考资料

文件	在查询涉及以下内容时加载……
references/job-scheduling-basics.md	核心概念、任务池、立即执行的任务、全部 4 种 cron 类型、MCP 工具工作流、Node SDK 调用、任务函数处理程序模板、CLI 设置
references/job-scheduling-advanced.md	重试语义、动态（代码内）创建 cron、触发和计时行为、以 webhook 为目标的任务、notify_url、监控/可观测性、安全防护措施、任务池容量规则