IronClaw GitHub Webhook 归一化github.handle_webhook能力源码级深度解析【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw在 IronClaw一个聚焦隐私、安全与可扩展性的 Agent OS的扩展体系中GitHub 扩展包crates/extensions/packages/github以 WASM 工具的形式向 Agent 提供仓库、Issue、PR、搜索、文件、Release、Workflow 等数十项能力。其中github.handle_webhook是一类特殊的被动型能力它不发起任何 GitHub API 调用而是把宿主已经验签并投递进来的 webhook 负载归一化为系统统一的事件意图System Event Intent供 Agent 的循环与触发器消费。本文以 handle_webhook.md 为主线结合 webhook.rs、handle_webhook.input.v1.json 与 manifest.toml 等源码逐层拆解该能力的输入协议、归一化映射、字段约定与安全边界读完即可在 IronClaw 中正确编排与调用它。能力定位归一化而非请求原文档的开篇即点明了该能力的核心语义Usegithub.handle_webhookto normalize a GitHub webhook payload into system event intents. This capability does not call GitHub; it normalizes a webhook payload already verified and supplied by the host.这句话包含三个关键约束也是理解整个能力的前提输入是宿主已验签的 webhookGitHub 通过X-Hub-Signature-256对 webhook 做 HMAC 签名签名校验由宿主host在把负载交给扩展之前完成。该能力不负责、也不应该重复验签它只消费已经可信的 payload。它不调用 GitHub这一点在 manifest.toml 中体现得极为直接——github.handle_webhook的effects []既不声明network也不声明use_secret更没有像其他工具那样挂载[[tools.credentials]]GitHub Token 的注入只存在于api.github.com的 HTTP 出站路径上。也就是说即使被调用它也拿不到也不需要任何凭据。它的输出是事件意图而非 REST 响应返回结构是一个ToolWebhookResponse里面携带emit_events数组每个元素是一个SystemEventIntent——这才是 IronClaw 内部统一的事件载体。从工程结构看manifest.toml 为该工具声明了input_schema_ref schemas/github/handle_webhook.input.v1.json与prompt_doc_ref prompts/github/handle_webhook.md而 schema.rs 通过include_str!把该 schema 与其余 40 多个 GitHub schema 一起打包进 WASM构成oneOf联合校验。调用时宿主通过 invocation context 中的capability_id即github.handle_webhook决定执行哪个操作见 dispatch.rs 与 types.rs 中的GitHubAction::HandleWebhook分支。输入协议schema 详解该能力的输入 schema 位于 handle_webhook.input.v1.json结构非常精简只有两层{ $schema: https://json-schema.org/draft/2020-12/schema, title: GitHub handle_webhook input, type: object, additionalProperties: false, properties: { webhook: { type: object, additionalProperties: false, properties: { headers: { type: object, additionalProperties: { type: string } }, body_json: { type: object, additionalProperties: true } }, required: [headers, body_json] } }, required: [webhook] }对应到 types.rs 中的 Rust 结构体#[derive(Debug, Deserialize)] pub(crate) struct GitHubWebhookRequest { #[serde(default)] pub(crate) headers: HashMapString, String, #[serde(default)] pub(crate) body_json: Optionserde_json::Value, }各字段说明字段类型是否必填含义与取值约定webhook.headersobject值为 string 的 map必填webhook 的 HTTP 请求头集合至少应包含X-GitHub-Event事件名、X-GitHub-Delivery投递 ID头名匹配是大小写不敏感的见下文header_value实现webhook.body_jsonobject任意 JSON必填GitHub webhook 的 JSON 请求体即事件专属的负载对象值得注意的两点顶层与webhook层都开启了additionalProperties: false多传任何无关字段都会被拒绝对应 serde 层面的严格反序列化但body_json内部是additionalProperties: true的透传对象——因为 GitHub 各事件的负载结构千差万别归一化器只做提取关键字段并追加从不丢弃原始字段。事件类型归一化从 GitHub 事件名到系统事件类型归一化的第一件事是把 GitHub 的原始事件头X-GitHub-Event映射为 IronClaw 系统内部统一的event_type命名空间。核心逻辑在 webhook.rs 的github_event_type函数let base match event { issues issue, pull_request pr, issue_comment { if payload.pointer(/issue/pull_request).is_some() { pr.comment } else { issue.comment } } pull_request_review pr.review, pull_request_review_comment pr.review_comment, pull_request_review_thread pr.review_thread, check_suite ci.check_suite, check_run ci.check_run, status ci.status, other other, };完整映射关系如下GitHubX-GitHub-Event归一化基名base附 action 后的示例issuesissueissue.opened、issue.closedpull_requestprpr.opened、pr.closed、pr.mergedissue_comment普通 Issue 评论issue.commentissue.comment.createdissue_commentPR 上的评论负载含/issue/pull_requestpr.commentpr.comment.createdpull_request_reviewpr.reviewpr.review.submittedpull_request_review_commentpr.review_commentpr.review_comment.createdpull_request_review_threadpr.review_threadpr.review_thread.resolvedcheck_suiteci.check_suiteci.check_suite.completedcheck_runci.check_runci.check_run.completedstatusci.statusci.status.pending其他未知事件原样透传保持原名归一化后若负载中存在非空的action字段则拼接为base.action例如pr.opened、ci.check_run.completed。这套命名把 Issue 与 PR 评论两者在 GitHub 侧共用issue_comment事件做了关键区分——判断依据是负载中是否存在/issue/pull_request指针这正好与后文pr_number的回退逻辑相呼应。Payload 增强追加统一语义字段归一化的第二件事是在原始负载基础上锦上添花地追加一组跨事件统一的语义字段见 webhook.rs 的github_enriched_payload。其核心策略是put_if_missing只有当目标字段在原始负载中不存在时才写入绝不覆盖 GitHub 原生的同名字段从而保证原始数据优先、增强字段兜底。追加的字段及其取值来源JSON Pointer如下追加字段取值来源说明event头部X-GitHub-Event原始事件名如pull_requestevent_type归一化结果如pr.openeddelivery_id头部X-GitHub-DeliveryGitHub 每次投递的全局唯一 ID便于溯源与去重action负载/action事件动作如openedrepository_name负载/repository/full_name如nearai/ironclawrepository_owner负载/repository/owner/login仓库属主sender_login负载/sender/login触发事件的用户issue_number负载/issue/numberIssue 编号pr_number负载/pull_request/number回退/issue/number当/issue/pull_request存在时PR 编号comment_author负载/comment/user/login评论作者comment_body负载/comment/body评论正文review_state负载/review/state如approvedpr_state负载/pull_request/state如open、closedpr_merged负载/pull_request/merged是否已合并pr_draft负载/pull_request/draft是否为草稿 PRbase_branch负载/pull_request/base/ref目标分支head_branch负载/pull_request/head/ref源分支ci_status负载/check_run/status→/check_suite/status→/statusCI 状态三级回退ci_conclusion负载/check_run/conclusion→/check_suite/conclusion→/stateCI 结论三级回退其中两处聪明的回退值得单独说明pr_number回退GitHub 对 PR 的issue_comment事件负载中没有/pull_request/number但存在/issue/number且/issue/pull_request非空。源码注释webhook.rs明确记录了这一行为此时回退到/issue/number从而保证 PR 评论事件同样携带pr_number下游触发器可以统一按 PR 维度处理。CI 字段回退check_run、check_suite、status三种事件在 GitHub 侧的负载结构完全不同归一化器按优先级依次探测把三者统一收敛到ci_status/ci_conclusion两个字段屏蔽了底层差异。输出协议系统事件意图归一化完成后函数返回序列化后的ToolWebhookResponsetypes.rs#[derive(Debug, Serialize)] pub(crate) struct ToolWebhookResponse { pub(crate) accepted: bool, pub(crate) emit_events: VecSystemEventIntent, } #[derive(Debug, Serialize)] pub(crate) struct SystemEventIntent { pub(crate) source: String, pub(crate) event_type: String, pub(crate) payload: serde_json::Value, }一个典型的输出如下对应 lib.rs 中handle_webhook_normalizes_pull_request_opened_event测试的语义{ accepted: true, emit_events: [ { source: github, event_type: pr.opened, payload: { action: opened, event: pull_request, event_type: pr.opened, repository_name: nearai/ironclaw, repository_owner: nearai, sender_login: reviewer, pr_number: 4280, pr_state: open, pr_merged: false, pr_draft: true, base_branch: reborn-integration, head_branch: codex/reborn-github-capabilities, repository: { ……: 原始负载字段原样保留 }, pull_request: { ……: 原始负载字段原样保留 } } } ] }accepted: true表示负载被成功接收并归一化在实现中只要头部与 body 齐备即返回 trueemit_events数组中的每个SystemEventIntent携带source恒为github、event_type归一化事件类型与payload增强后的完整负载。后续 IronClaw 的触发器triggers与 Agent 循环可以直接按event_type匹配并消费这些意图。字段命名约定URL 提取与 pr_number / issue_number原文档第二条给出了给模型LLM的硬性约定Use the exact JSON field names from this capability schema. If the user provides a GitHub URL, extract the owner and repo fields plus the schema-specific number, path, or ref key; for pull-request tools, usepr_number; for issue tools, useissue_number.这条约定贯穿整个 GitHub 扩展包具体落地为参数必须使用 schema 中的精确 JSON 字段名owner、repo、pr_number、issue_number、path、ref等禁止自创别名当用户只给了一个 GitHub URL 时模型应先从 URL 中提取owner和repo再按目标工具的 schema 提取对应的标识键例如https://github.com/nearai/ironclaw/pull/4280→owner: nearai、repo: ironclaw、pr_number: 4280.../issues/123→issue_number: 123PR 系工具一律用pr_numberIssue 系工具一律用issue_number——这与 webhook.rs 中归一化输出的字段命名完全一致保证webhook 归一化出来的字段能直接被查询/操作工具复用形成闭环。作为兼容性佐证Rust 侧对若干 PR 工具同时接受number/pull_number别名见 types.rs 中#[serde(alias number, alias pull_number)]并有专门测试serde_accepts_common_pr_number_aliaseslib.rs验证但在对外文档与模型约定层面规范字段就是pr_number。源码调用链与错误语义完整调用链为宿主已验签的 webhook 负载 → WASM Guest::execute(req.params, req.context) [lib.rs] → dispatch::execute_inner [dispatch.rs] → GitHubAction::HandleWebhook { webhook } webhook::handle_webhook → github_event_type github_enriched_payload [webhook.rs] → serde_json::to_string(ToolWebhookResponse{..})错误语义源码与测试共同印证见 lib.rs触发条件返回错误headers中缺少X-GitHub-Event或该值为空/全空白Missing X-GitHub-Event headerbody_json为NoneMissing webhook.body_json头部查找采用大小写不敏感匹配webhook.rs 的header_value会把键统一转小写后比对因此X-GitHub-Event与x-github-event等价不产生额外错误此外参数校验是入口即拦截的任何多余字段或非法结构都会在进入handle_webhook之前被 serde 严格反序列化拒绝invalid_parameters符合该扩展包验证先于出站的一贯风格可参考 lib.rs 的serde_rejects_unknown_fields_before_egress测试。测试验证三类典型事件的归一化lib.rs 内置了三组针对 webhook 的单元测试是理解行为的最快途径handle_webhook_rejects_missing_event_or_body验证缺头、缺 body 两种失败路径的错误文案。handle_webhook_normalizes_pull_request_opened_event输入X-GitHub-Event: pull_requestaction: opened断言event_type pr.opened且pr_number、pr_state、pr_merged、pr_draft、base_branch、head_branch全部按预期从负载提取。handle_webhook_normalizes_check_run_event输入check_run事件断言event_type ci.check_run.completed、ci_status completed、ci_conclusion success。handle_webhook_normalizes_pr_comment_event输入带X-GitHub-Delivery头的issue_comment事件负载含/issue/pull_request断言accepted true、source github、event_type pr.comment.created并验证delivery_id、repository_name、pr_number三个增强字段——其中pr_number正是通过/issue/number回退逻辑得到的。实战编排建议在实际使用 IronClaw 编排 GitHub 事件驱动工作流时推荐按以下模式接入宿主层配置 GitHub 仓库 webhook指向 IronClaw 的入口端点宿主完成X-Hub-Signature-256验签后把请求头与 body 原样封装为{webhook: {headers: {...}, body_json: {...}}}并以capability_id github.handle_webhook调用该能力。能力层handle_webhook归一化出SystemEventIntent触发 IronClaw 的触发器系统按event_type如pr.opened、issue.comment.created、ci.check_run.completed路由。Agent 层在收到事件意图后如需进一步操作例如评论 PR、关闭 Issue、查询 CI 日志按前文约定把pr_number/issue_number/repository_name拆解为owner/repo与对应编号字段调用 manifest.toml 中注册的其他 GitHub 能力如github.create_issue_comment、github.merge_pull_request、github.get_workflow_run_jobs形成事件归一化 → 意图路由 → 主动操作的完整闭环。安全边界小结零凭据github.handle_webhook不声明任何effects与credentials归一化过程纯内存计算不产生网络出站天然无 Token 泄露面验签前置签名验证是宿主的职责该能力接收的是已验证的负载切勿在模型提示中引导该能力自行验签字段覆盖保护增强字段采用put_if_missing策略永远不会篡改 GitHub 原始负载中的既有字段下游消费方既可信任原始数据也可依赖统一语义字段。从 manifest.toml 可以看到该工具default_permission ask——即默认情况下调用需要用户授权确认这与它读取并翻译外部事件的敏感属性相匹配。理解这一层权限语义有助于在配置 IronClaw 运行策略参考 profiles 下的 TOML 配置时为事件驱动场景提前授予相应权限。【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
