Hatchet CLI 触发工作流并轮询完成trigger-and-watch 实战指南【免费下载链接】hatchet An orchestration engine for background tasks, AI agents, and durable workflows项目地址: https://gitcode.com/GitHub_Trending/ha/hatchet本篇指南围绕 Hatchet CLI 的trigger与runs命令完整讲解如何在命令行中手动触发一个工作流、捕获 run ID、轮询其运行状态直至终态并在失败时通过日志与事件进行诊断。该流程面向自动化场景尤其适合 AI Agent 与脚本化集成读完即可掌握一套可复制的触发—轮询—诊断—清理闭环并理解命令背后的源码实现。前置条件在开始触发工作流之前需要确认以下三点必须有一个正在运行的 Hatchet worker。worker 通过hatchet worker dev -p HATCHET_PROFILE启动HATCHET_PROFILE为你要使用的 profile 名称。如果没有任何 worker 在运行任务会永远停留在QUEUED状态永远不会被执行。worker 启动的完整配置hatchet.yaml、自动重载、pre-commands参见 start-worker.md。必须知道工作流名称并准备好对应的输入 JSON。这些命令需要一个 profile通过-p HATCHET_PROFILE指定。如果你的本地开发场景希望免去 token 和服务器可以使用嵌入式模式embedded mode——在该模式下引擎在 worker 进程内启动由代码直接触发任务而不是走 CLI详见 local-dev-embedded.md。关于 profile 的创建与选择可参考 setup-cli.md。CLI 的trigger命令同时支持交互式选择器与非交互模式本文档给出的非交互流程专为自动化场景设计。步骤一将输入写入临时文件为避免多个会话之间互相冲突请将工作流输入 JSON 写入一个唯一命名的临时文件。使用时间戳与进程 ID 组合命名可以保证唯一性HATCHET_INPUT_FILE/tmp/hatchet-input-$(date %s)-$$.json cat $HATCHET_INPUT_FILE ENDJSON INPUT_JSON ENDJSON将INPUT_JSON替换为工作流实际需要的 JSON payload。使用 heredoc 的ENDJSON带引号可以防止 shell 对$、反引号等字符做变量展开确保 JSON 内容原样写入。这一步的意义在于后续的hatchet trigger通过-j参数接收文件路径而非内联字符串避免长 JSON 在命令行中转义出错。从源码看CLI 对输入 JSON 的校验发生在读取文件之后——runManualNonInteractive先调用os.ReadFile(jsonPath)读取文件内容再通过json.Unmarshal校验其合法性validateJSON任何非法 JSON 都会直接报错退出见 trigger.go。因此写入后如果立即触发失败并提示 invalid JSON in file通常是文件内容本身有问题。步骤二触发工作流并捕获 run ID使用hatchet trigger manual子命令进行非交互式手动触发并开启-o json输出RUN_ID$(hatchet trigger manual -w WORKFLOW_NAME -j $HATCHET_INPUT_FILE -p HATCHET_PROFILE -o json | jq -r .runId)各参数含义如下参数简写说明manual—trigger的保留子命令名表示通过 API 手动触发工作流-w WORKFLOW_NAME--workflow要触发的工作流名称非交互模式必须与-j同时提供-j $HATCHET_INPUT_FILE--json输入 JSON 文件的路径-p HATCHET_PROFILE--profile连接 Hatchet 时使用的 profile-o json--output以 JSON 格式输出跳过交互提示-o json会让命令向 stdout 输出{runId: ..., workflow: ...}这样的 JSON 结构上面的命令通过jq -r .runId直接把 run ID 捕获到$RUN_ID变量中供后续轮询步骤使用。源码视角trigger manual内部发生了什么在 trigger.go 中trigger命令的入口逻辑如下当提供了--workflow或--json标志时自动进入非交互手动模式runManualNonInteractive此时manual以外的触发器名称会被拒绝--workflowand--jsonflags can only be used with manual triggering且两个标志缺一不可。在非交互模式下CLI 通过 REST API 拉取工作流列表按名称精确匹配目标工作流如果未找到直接报错workflow name not found。随后调用hatchetClient.Admin().RunWorkflow(workflowName, inputData)发起触发整个过程有30 秒超时保护如果超时未返回会提示 workflow trigger timed out after 30 seconds通常表示与 Hatchet 服务器的连接有问题见 trigger.go。JSON 输出结构由printJSON生成字段为runId与workflow见 trigger.go。值得一提的还有trigger命令的多面性不加manual时它会加载项目根目录的hatchet.yaml展示triggers配置段定义的触发器列表供交互选择hatchet trigger显示选择器、hatchet trigger name直接运行对应触发器manual是保留关键字hatchet.yaml中的触发器不允许命名为manualvalidateTriggerNames强制校验。步骤三轮询直至运行结束触发完成后运行可能不会立即结束。需要每 5 秒执行一次以下命令直到运行进入终态hatchet runs get RUN_ID -o json -p HATCHET_PROFILE解析返回的 JSON 并检查状态查看.run.status获取整个运行的总体状态查看.tasks[].status获取每个任务的独立状态。终态terminal statusesCOMPLETED、FAILED、CANCELLED。看到这些状态即可停止轮询。非终态non-terminal statusesQUEUED、RUNNING。看到这些状态需要继续轮询。之所以用 JSON 输出而非默认模式是因为runs get在不带-o json时会直接启动交互式 TUI终端界面这不适合脚本化的轮询循环。从 runs.go 的源码看runs get接受唯一一个 run ID 参数JSON 模式下它调用V1WorkflowRunGetWithResponse获取完整运行详情后原样打印。返回的结构中不仅包含状态还包含displayName、输入、各任务的输出/错误信息与时间戳这些在后续诊断中非常有用详见 debug-run.md。步骤四失败处理如果轮询发现运行状态为FAILED按下面的顺序收集诊断信息。获取日志logshatchet runs logs RUN_ID -p HATCHET_PROFILE该命令打印任务代码产生的应用级日志输出如 print 语句、logger 调用。重点寻找错误信息、堆栈跟踪或非预期输出。日志按时间戳排序输出对于多任务DAG运行所有任务的日志会合并后按时间排序并带有任务名前缀方便区分来源。从源码看runs logs首先尝试把 run ID 当作工作流运行DAG来解析逐个任务拉取日志后合并排序若失败则回退为把 run ID 当作单个任务 ID 处理见 runs.go。此外它还支持几个实用的扩展参数参数说明--tail N只显示最近 N 行日志--since 5m只显示最近 5 分钟内的日志支持1h、24h、7d等格式-f/--follow持续轮询新日志并实时打印CtrlC 停止每 2 秒轮询一次获取事件eventshatchet runs events RUN_ID -o json -p HATCHET_PROFILE该命令返回生命周期事件日志展示任务是如何被派发dispatch、开始start和失败fail的完整序列。重点关注eventType和message字段理解失败的先后顺序。事件类型通常包括QUEUED、STARTED、FINISHED、FAILED、CANCELLED等非 JSON 模式下每条事件会按时间 事件类型 任务名 消息的格式打印便于人工阅读见 runs.go。步骤五清理临时文件轮询结束、诊断完成后删除之前创建的输入临时文件避免在/tmp堆积垃圾文件rm -f $HATCHET_INPUT_FILE常见问题排查现象可能原因处理方式任务一直停留在 QUEUEDworker 没有运行或工作流/任务名称与 worker 注册的不一致启动或重启 workerhatchet worker dev -p HATCHET_PROFILE并核对任务名称任务立即 FAILED任务代码抛出了异常检查日志步骤四中的堆栈跟踪任务被 CANCELLED运行被外部取消检查事件日志定位取消来源结合 debug-run.md 的排查经验针对上述问题还可以进一步细化QUEUED 但无 STARTED 事件说明任务从未被任何 worker 拾取。除 worker 未启动外还要检查 worker 是否注册了该任务类型、以及 worker 与触发命令是否使用了相同的-pprofile不同 profile 指向不同租户任务无法互通。FAILED先看日志中的堆栈再看事件中的FAILED事件消息。常见原因包括任务代码未处理异常、超时、或依赖数据库、外部 API不可达。运行 COMPLETED 但输出不符合预期检查.tasks[].output看各任务实际返回了什么核对.run.input确认输入是否正确。执行缓慢对比每个任务的startedAt与finishedAt时间戳找出瓶颈任务若触发与首个任务启动之间有明显间隔通常意味着排队延迟worker 容量不足。补充与其它 CLI 技能的配合本文档是 Hatchet CLI Agent Skills 体系中的一环见 SKILL.md。按场景选择配套文档可形成完整闭环启动 worker→ start-worker.md本地免 token 开发嵌入式模式→ local-dev-embedded.md深入诊断失败/卡住的运行→ debug-run.md使用相同或新的输入重放运行→ replay-run.mdCLI 与 profile 配置→ setup-cli.md关键 CLI 惯例贯穿始终本地开发优先嵌入式模式无需 token/profile指定 profile 用-p机器可读输出统一用-o json输入写入唯一命名的临时文件使用完毕后清理临时文件。遵循这些惯例触发—轮询—诊断的自动化流程就能稳定、可重复地运行。【免费下载链接】hatchet An orchestration engine for background tasks, AI agents, and durable workflows项目地址: https://gitcode.com/GitHub_Trending/ha/hatchet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
