ZeroClaw Git 事件驱动的 SOP Fan-In：从 Git Forge 事件到 SOP 运行的全链路触发指南

ZeroClaw Git 事件驱动的 SOP Fan-In从 Git Forge 事件到 SOP 运行的全链路触发指南【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw导读本文讲解 ZeroClaw 的Git SOP Fan-In如何让 GitHub、Gitea、Forgejo 等 Git 平台的仓库事件PR 打开、Issue 创建、评论、CI 失败、版本发布等自动启动一条 Standard Operating Procedure标准操作规程简称 SOP运行。你将掌握事件如何从 Forge 路由到 SOP 入口ingress、channel触发器如何匹配事件、condition如何精确筛选事件以及如何配置、触发、排查和审批这类自动化流程。读完本文你可以直接落地“PR 自动分诊”“CI 失败自动处理”“Issue 自动归类”等事件驱动的自动化运维管线。本文是 SOP Fan-In 系列中 Git 源头的专门指南。传输层provider、Forge 认证、轮询、仓库范围、事件路由表在 Git 通道文档 中配置本文聚焦于触发器这一侧——哪些事件类型能进入 SOP 入口完全由通道的逐事件events路由表决定。一、核心机制Forge 事件如何变成 SOP 运行Git Forge 事件可以启动 SOP 运行。当一个事件类型在通道的事件表eventstable中被路由到sop时Git 通道会把标准化后的 Forge 事件提升lift为一个 SOP 事件并派发给 SOP 引擎事件主题topicgit.alias:event_type例如git.main:pull_request.opened结构化 JSON 载荷携带仓库repo、Issue/PR 编号、作者、标题、正文等字段分发目标SOP 引擎engine的dispatch_sop_event入口。从源码看这条链路在 crates/zeroclaw-channels/src/git/events.rs 的event_to_sop_message中完成Git 通道把标准化事件包进一个ChannelMessage信封主题通过ChannelSopTopic::build(channel_key, alias, event_type)生成载荷由event_payload序列化为结构化 JSON并设置内部标记internal_sop_event由编排器orchestrator识别并送入 SOP 入口而不是作为聊天消息进入 LLM 循环。值得注意的是该内部标记只有 Git 生产者会设置因此外部用户无法通过伪造消息subject来冒充 SOP 事件。在 crates/zeroclaw-channels/src/git/channel.rs 的dispatch_event中路由决策由router::resolve_route(event.event_type(), self.cfg.events)完成三种结果分别是Ignore静默丢弃、Message按对话消息投递、Sop { sop }投递到指定 SOP 入口。触发与匹配概览环节机制说明事件来源Forge REST API 轮询通道按since游标轮询无需公网 URL 或 Webhook 暴露可运行在 NAT 之后事件标准化GitEvent枚举跨 Forge 统一为 9 种事件类型见下文与 provider 无关路由决策events路由表逐事件类型指定message或sop nameSOP 入口dispatch_sop_event单一匹配器评估所有已加载 SOP 的触发器命中即启动运行主题git.alias:event_type通道生成的 SOP 事件主题不是触发器字段触发器channel触发器匹配通道种类git与可选alias二、Mention Gate 与作者检查哪些事件被放行SOP 路由在闸门上与对话路径有明确差异Mention 门槛仅对sop路由的生存周期事件放宽例如一个pull_request.opened被路由到分诊 SOP 后无论作者是否在评论中提及应用都会触发 SOP。这由源码中的gate_mentions参数控制——对话路径传trueSOP 路径传false见 crates/zeroclaw-channels/src/git/events.rs 与 crates/zeroclaw-channels/src/git/channel.rs。作者检查仍然适用于每一次投递无论 SOP 还是对话来自应用自身账户的事件一律丢弃admit_author中对bot_login的大小写不敏感比较来自其他 Bot 的事件按listen_to_bots决定是否放行对 actor 的 login 强制实施 peer-group 允许名单allowlist。无作者的事件例如没有 actor 的 workflow run直接丢弃避免绕过作者过滤器。一句话概括sop路由绕过mention_only但不绕过自我/Bot 过滤也不绕过作者允许名单。相关测试见 crates/zeroclaw-channels/src/git/events.rsunmentioned_comment_dropped_only_on_the_gated_path未提及的评论只在门控路径被丢弃SOP 路径放行、own_bot_events_always_dropped_even_ungated自身 Bot 事件即使未门控也始终丢弃、foreign_bot_respects_listen_to_bots外部 Bot 遵守listen_to_bots。三、触发器与匹配规则Trigger Matching一个channel触发器匹配channel通道种类固定为git可选alias配置的实例名例如default或main没有topic字段哪些事件类型能进入 SOP 入口完全由通道的逐事件events路由表决定。因此触发器选择来源source路由表选择事件event。日志中看到的git.alias:event_type字符串是通道生成的事件主题不是触发器字段。如果想把触发器限定到单个事件类型用condition对载荷做测试例如$.event_type pull_request.opened。事件的结构化 JSON 载荷会被转发进 SOP 事件可用于可选的触发器condition步骤上下文step context接收的是**截断、净化、加框capped, sanitized, framed**后的形式——未受信任的外部文本不会直接拼入模型上下文。一个 JSON-path 形式的condition如$.repo octo/repo可以把 SOP 收窄到单个仓库。已知事件类型以下 9 种是已知事件类型与 crates/zeroclaw-channels/src/git/types.rs 中GitEvent枚举的变体一一对应事件类型说明载荷关键字段issue_comment.createdIssue/PR 上的新评论repo,number,comment_id,author,bodyissues.opened新 Issue 的开帖repo,number,issue_id,author,title,bodypull_request.opened新 PR 的开帖repo,number,author,title,bodypull_request.closedPR 未合并关闭repo,number,author,title,html_urlpull_request.mergedPR 已合并repo,number,author,title,html_urlpull_request_review_comment.created行内评审评论repo,number,comment_id,author,bodyworkflow_run.completedCI 工作流运行成功完成repo,run_id,attempt,name,branch,run_number,pr_number,actor,html_urlworkflow_run.failedCI 工作流运行失败同上verdict 为 failedrelease.published发布新版本repo,release_id,tag,name,author,body,html_url此外所有 SOP 事件载荷都包含公共字段source恒为channel、channelgit、channel_alias、provider如github、sop目标 SOP 名、topicgit.alias:event_type、event_type、dedup_id、created_at、target。这一形状由 crates/zeroclaw-channels/src/git/events.rs 的common_payload构造并有测试sop_message_carries_reserved_subject_and_structured_payload逐一断言这些字段见 crates/zeroclaw-channels/src/git/events.rs。四、配置实战把事件路由到 SOP完整的触发链路由两部分配置组成通道侧的事件路由SOP 定义侧的触发器。4.1 通道侧events路由表在 Git 通道配置中为每个事件类型设置路由。GitEventRoute结构定义于 crates/zeroclaw-config/src/schema.rs只有两个字段message: bool把事件作为普通通道消息投递到 agent 循环sop: OptionString把事件路由到指定名称的 SOP 入口。一个事件条目sop与message都没设置时显式禁用该事件类型。配置示例[channels.git.main] enabled true provider github # ... 认证相关配置 ... [channels.git.main.events.pull_request.opened] sop pr-triage # PR 打开 → 分诊 SOP [channels.git.main.events.issues.opened] sop issue-triage # Issue 打开 → 归类 SOP [channels.git.main.events.issue_comment.created] message true # 普通评论仍走对话路径 [channels.git.main.events.workflow_run.failed] sop ci-failure # CI 失败 → 自动处理 SOP [channels.git.main.events.release.published] message true # 版本发布通知 agent路由决策逻辑在 crates/zeroclaw-channels/src/git/router.rs 的resolve_route中sop非空时优先即使同时写了message true其次message否则Ignore。关键设计路由即订阅。通道从路由表推导要轮询哪些 API 端点TransportPlan::from_routes见 crates/zeroclaw-channels/src/git/router.rs评审评论、Releases、Actions 运行等端点只有在其事件类型被路由后才会被轮询。因此未配置的通道成本与之前完全一样列表workflow_run.failed不会关闭对话未在非空表中列出的事件类型沿用默认行为issue_comment.created、issues.opened、pull_request.opened按对话投递其余忽略只有被路由的事件类型才被轮询poll。启动时validate_routescrates/zeroclaw-channels/src/git/router.rs会对未知事件类型拼写错误和空的sop 条目给出启动警告。4.2 SOP 侧channel触发器加载一个 SOP其channel触发器声明通道channel git可选alias。SOP.toml放在sops_dir默认未设置需在配置中显式开启默认文档值为shared/sops下的子目录中# sops_dir/pr-triage/SOP.toml [sop] name pr-triage description Triage newly opened pull requests version 1.0.0 [[triggers]] type channel channel git alias main condition $.event_type pull_request.opened关于sops_dir默认未设置运行时 SOP 执行默认关闭直到运维显式开启相对值基于安装根目录解析文档化值shared/sops解析为install/shared/sops。用zeroclaw sop validate name校验 SOP。4.3condition表达式精确筛选事件触发器condition与步骤when:守卫共用同一套表达式语法完整语法见 SOP 语法参考。触发器条件针对事件载荷求值fail-closed条件无效、载荷缺失、JSON path 无法解析、数值比较双方非数字时都视为不匹配空条件无条件匹配。常用 Git 事件筛选示例表达式效果$.event_type pull_request.opened只匹配 PR 打开事件$.repo octo/repo只匹配octo/repo仓库$.repo octo/repo ...不支持单个条件只允许一次比较无AND/OR/NOT$.number 100按编号数值筛选数值比较$.author.login dependabot[bot]按作者 login 筛选语法要点以$开头的 JSON path 形式$.path.to.field op value点分路径数组元素用数字段$.readings.1不支持括号语法比较运算符、!、、、、单一运算符解析器最长优先匹配 token字符串字面量要加双引号$.status criticalJSON 布尔值会被转换为字符串true/false因此写$.active true数值比较两侧都能解析为数字时按数值比较否则按字符串比较。五、触发一次运行Fire it按以下三步即可触发一次 SOP 运行路由事件类型到 SOP在通道配置的events表中写一个带sop name的条目加载匹配的 SOPSOP 的channel触发器声明channel git可选alias制造 Forge 事件打开或评论一个 Issue/PR、发布一个 Release、或让一次 workflow run 结束。通道随后会标准化事件 → 筛选载荷安全性作者检查 peer-group 允许名单→ 分发给每个已加载且channel触发器匹配、condition如有成立的 SOP。路由一个事件类型同时也订阅了对应的 Forge 端点所以只有被路由的事件类型会被轮询。排查如果什么都没启动症状检查点事件被当作对话消息而不是 SOP确认事件类型被路由到sop而不是留在对话默认值SOP 触发器不匹配确认 SOP 的channel触发器写了channel git及正确的alias条件不成立对照载荷核对condition表达式事件从未到达确认事件类型已在路由表中订阅路由即订阅且通道在运行轮询更多症状与对策参见 Fan-In 总览的排查表。特别地sop路由仍然受作者允许名单约束——空/错误配置的 allowlist 会吞掉所有事件包括sop路由的 PR 生命周期事件首次丢弃会以 WARN 日志提示“dropping events from sender outside the peer allowlist”见 crates/zeroclaw-channels/src/git/channel.rs。六、审批与观察Approve and observeSOP 运行到达检查点checkpoint时会暂停为WaitingApproval。两类方式处理CLI 方式zeroclaw sop list # 列出运行状态找出 WaitingApproval zeroclaw sop approve # 批准暂停的运行 zeroclaw sop pending # 查看所有暂停待审的运行带外out-of-bandGateway API 方式通过 Gateway API 的审批端点GET /admin/sop/pending列出暂停待人工审批的运行WaitingApprovalPOST /admin/sop/approve批准POST /admin/sop/deny拒绝取消。这些路由在 crates/zeroclaw-gateway/src/lib.rs 中注册处理实现位于 crates/zeroclaw-gateway/src/api_sop.rs。审批端点需要 gateway 配对认证paired-token bearer 认证与 Webhook 路由共享限流器。七、深入原理从 Forge 事件到引擎分发的完整调用链把上文各环节串起来一条pull_request.opened事件的完整路径是轮询Git 通道按TransportPlan由路由表推导轮询 Forge REST API命中issues端点族因为pull_request.opened被路由标准化provider 把原生载荷映射为统一的GitEvent::PullRequestOpenedcrates/zeroclaw-channels/src/git/events.rs事件类型为pull_request.opened去重 ID 为ghpr_octo/repo#12PR 没有传输稳定的对象 ID以owner/repo#number作为身份键路由决策dispatch_event调用resolve_route得到RouteAction::Sop { sop: pr-triage }crates/zeroclaw-channels/src/git/channel.rsSOP 事件构造event_to_sop_message生成主题git.main:pull_request.opened、结构化 JSON 载荷与internal_sop_event标记经通道监听总线送达编排器引擎分发编排器把事件交给 SOP 引擎的dispatch_sop_eventcrates/zeroclaw-runtime/src/sop/dispatch.rs单一匹配器对每个已加载 SOP 的触发器求值运行启动匹配成功则启动运行通过SopAuditLogger持久化运行启动审计在非 agent 循环上下文中ExecuteStep动作记录为 pending 而非静默执行headless 安全见 Fan-In 总览。引擎侧测试dispatch_to_named_sop_filters_matching_channel_triggerscrates/zeroclaw-runtime/src/sop/dispatch.rs验证了channel git、alias main的触发器精确匹配行为。八、实操示例一个完整的 PR 分诊 SOP以下是一个可直接落地的完整示例收到octo/repo仓库的新 PR 后自动生成评审摘要并请求人工审批。1. 通道配置config.toml[channels.git.main] enabled true provider github # App ID / private key 等认证配置见 Git 通道文档 [channels.git.main.events.pull_request.opened] sop pr-triage2. SOP 清单sops_dir/pr-triage/SOP.toml[sop] name pr-triage description Triage newly opened pull requests in octo/repo version 1.0.0 [[triggers]] type channel channel git alias main condition $.repo octo/repo $.event_type pull_request.opened注意condition只允许单次比较不支持。上面的写法会产生无效条件fail-closed 不匹配。正确做法是只保留一个条件或在 SOP 内用步骤when:做多级判断。例如用$.event_type pull_request.opened触发再在SOP.md步骤中用when:守卫$.steps.1.repo octo/repo过滤。3. SOP 步骤sops_dir/pr-triage/SOP.md# PR triage Classify a newly opened PR and prepare an operator-facing summary. ## Steps 1. **Classify** - Inspect the PR payload and extract severity and area. - output: {type:object,required:[repo,number,severity],properties:{repo:{type:string},number:{type:integer},severity:{type:string}}} - next: 2 2. **Approval gate** - Require explicit approval before any action. - kind: checkpoint - requires_confirmation: true - next: 3 3. **Post summary** - Comment the triage summary back to the PR thread. - kind: capability - capability: forge.comment - with: { repo $.steps.1.repo, number $.steps.1.number, body Triage summary... }forge.comment能力步骤通过 Git 通道的出站路径把评论发回 Issue/PRprovider 无关GitHub / Gitea / Forgejo与检查点组合可构成无头headless评审管线详见 SOP 语法参考。这些注入式适配器只在daemon / channel-start路径注入独立 agent 运行与 CLI 校验会 fail-closed。4. 校验与运行zeroclaw sop validate pr-triage # 校验 SOP zeroclaw daemon # 或 zeroclaw channel start驱动轮询与 SOP 维护在仓库打开一个 PR 后SOP 运行即被触发到达检查点时用zeroclaw sop list/zeroclaw sop approve或 Gateway API 审批。九、安全基线公共仓库的 Issue/PR 评论是不可信输入保持mention_only true对话路径、用 peer group 门控发送者空 peer 集合拒绝所有人[*]接受任何人公开仓库把 autonomy 保持在Supervised或更低。SOP 入口对不可信输入有多层防护见 Fan-In 总览的安全默认值主题与载荷文本被截断、归一化、prompt-guard 筛查、加框后才进入模型上下文untrusted_input_guard block可拒绝不安全的不可信事件BlockedUnsafe默认warn审计放行无头分发只记录运行进度而不自动执行ExecuteStep。作者闸门永远生效sop路由跳过的是mention_only自我/Bot 过滤与作者 allowlist 对每次投递仍然适用。相关文档Git 通道provider、Forge 认证、轮询、事件路由Fan-In 总览SOP 语法参考SOP.toml/SOP.md格式与condition语法SOP 如何运行Gateway API审批端点【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考