Windmill Triggers 是 Windmill 中用于让外部事件调用脚本（script）与流程（flow）的机制。
一、用途 触发器把外部事件（HTTP 请求、WebSocket 消息、Kafka 消息、邮件等）与 Windmill 中的可运行对象（脚本或流程）连接起来，事件到达时自动执行对应的脚本或流程。
二、文件命名 触发器配置文件使用模式：{path}.{trigger_type}_trigger.yaml。示例：
- u/user/webhook.http_trigger.yaml
- f/data/kafka_consumer.kafka_trigger.yaml
- f/sync/postgres_cdc.postgres_trigger.yaml
- f/inbound/orders.email_trigger.yaml
三、邮件触发器（Email Triggers） 邮件触发器将收到的邮件路由到脚本或流程。每个触发器保留一个 local-part：发送到 <local_part>@<windmill_email_domain> 的邮件会投递到配置的可运行对象。设置 workspaced_local_part: true 可按工作区命名空间化（实际收件人变为 <workspace_id>-<local_part>@…）；在 Windmill Cloud 上这是必需的。发件人可以用 + 在 local-part 后追加 URL 风格附加参数：mytrigger+foo=bar+baz=qux@…，这些参数会作为 email_extra_args 传入脚本。
载荷（Payload）：可运行对象会收到：
- parsed_email — { headers, text_body, html_body, attachments[] }，每个附件包含 { headers, body }。
- raw_email — 原始 RFC 822 消息字符串；若消息超过 1 MiB，则为 S3 对象（{ s3: "windmill_emails/<job_id>/raw.eml" }）。
- email_extra_args（可选，仅当发件人追加了 +key=value 附加参数时）— 解析后的附加参数扁平对象。 若使用预处理器（preprocessor），以上内容会嵌套在 event 下，并带有 event.kind = "email" 与 event.trigger_path（触发器路径）。不使用预处理器时不会暴露 trigger_path，如需该字段请添加预处理器。
附件为 S3 对象：二进制附件上传到工作区 S3 桶，出现在 parsed_email.attachments[i].body 中，形如 { "s3": "windmill_emails/<job_id>/attachments/<filename>" }。在脚本中读取字节可使用 wmill SDK： TypeScript： import * as wmill from "windmill-client" const file = await wmill.loadS3File(parsed_email.attachments[0].body) Python： import wmill data = wmill.load_s3_file(parsed_email["attachments"][0]["body"]) 若工作区未配置 S3 资源（Workspace Settings → Object storage），body 会回退为字符串 "configure s3 in the workspace settings to handle attachments"；大型 raw_email 正文同理。邮件附件存储要求服务器以 parquet feature 构建。文本/HTML/内联部分以字符串形式内联在 body 中。
四、CLI 命令 将本地更改部署到工作区可能破坏远程状态——仅在用户明确要求部署/发布/推送时才建议或运行部署，不要在用户说“run”“try”“test”时执行。根据仓库接线方式，通过 git push 或 wmill sync push 部署（参见 AGENTS.wmill.md 的 Deploying 部分）。sync pull 可自行安全运行——它从不修改远程状态，但会用远程内容覆盖本地文件（可用 sync pull --dry-run 仅预览）。
推送触发器配置——仅在用户明确要求部署时
wmill sync push
从 Windmill 拉取触发器
wmill sync pull
五、HttpTrigger（.http_trigger.yaml） 必须是符合给定 schema 的 YAML 文件。字段包括：script_path（触发时执行的脚本或流程路径）、is_flow（script_path 指向流程则为 true，指向脚本则为 false）、labels、draft_only、is_draft、route_path（触发此端点的 URL 路由路径，如 'api/myendpoint'，不得以 / 开头）、static_asset_config（含 s3、storage、filename，用于提供静态资源）、http_method（get/post/put/delete/patch）、authentication_resource_path（包含认证配置的资源路径，用于 api_key、basic_http、custom_script、signature 方法）、summary、description、request_type（sync/async/sync_sse）、authentication_method（none/windmill/api_key/basic_http/custom_script/signature）、is_static_website（为 true 时从 S3/storage 提供静态文件而非运行脚本）、workspaced_route（为 true 时路由包含工作区 ID）、wrap_body（为 true 时将请求体包裹在 'body' 参数中）、raw_string（为 true 时将请求体作为原始字符串传递而非按 JSON 解析）、allowed_origins（允许跨源调用此路由的来源列表，按请求 Origin 头匹配并回显；设为 [''] 可取消限制；空列表等同于 null；静态网站会忽略此项）、error_handler_path（触发作业失败时运行的脚本路径，为裸路径，不能是流程）、error_handler_args、retry（含 constant、exponential、retry_if）。必填字段：script_path、is_flow、route_path、request_type、authentication_method、http_method、is_static_website、workspaced_route、wrap_body、raw_string。
六、WebsocketTrigger（*.websocket_trigger.yaml） 必须是符合给定 schema 的 YAML 文件。字段包括：script_path、is_flow、labels、draft_only、is_draft、url（要连接的 WebSocket URL，可为静态 URL 或由可运行对象计算）、filters（匹配传入消息的过滤器，每条为叶子 {key, value} 或 {path, value}，或分组 {any_of: [...]}/{all_of: [...]}/{none_of: [...]}；顶层条目由 filter_logic 组合）、filter_logic（and/or）、initial_messages（连接后立即发送的消息，可为原始字符串或由可运行对象计算）、url_runnable_args、can_return_message（为 true 时脚本可返回消息通过 WebSocket 发回）、can_return_error_result（为 true 时错误结果通过 WebSocket 发回）、heartbeat（含 interval_secs、message、state_field）、error_handler_path、error_handler_args、retry。必填字段：script_path、is_flow、url、filters、can_return_message、can_return_error_result。
七、KafkaTrigger（*.kafka_trigger.yaml） 必须是符合给定 schema 的 YAML 文件。字段包括：script_path、is_flow、labels、draft_only、is_draft、kafka_resource_path（包含连接配置的 Kafka 资源路径）、group_id（此触发器的 Kafka 消费者组 ID）、topics（要订阅的 Kafka 主题名数组）、filters（匹配传入消息的过滤器，结构同 WebSocket 触发器）。资料在此处截断，KafkaTrigger 的其余字段与必填项暂未提供。
八、适用场景与限制 适用于需要由外部事件驱动脚本/流程执行的场景，如 Webhook 端点、WebSocket 消息、Kafka 消费、邮件路由等。限制与注意事项：部署（sync push）可能破坏远程状态，仅在用户明确要求部署时执行；sync pull 会覆盖本地文件；邮件附件与大型 raw_email 依赖工作区 S3 配置，且附件存储要求服务器以 parquet feature 构建；Windmill Cloud 上邮件触发器必须设置 workspaced_local_part。