IronClaw 扩展实战:使用 github.create_pull_request 能力安全创建 GitHub 拉取请求

原创2026-09-22 16:35:482,165 阅读
文章标签:人工智能AI Agent交互助手本地部署Agent 沙箱MCP ClientsAI 技能AI 插件后端认证鉴权CLI前端

IronClaw 扩展实战:使用 github.create_pull_request 能力安全创建 GitHub 拉取请求

本篇技术指南围绕 IronClaw Agent OS 中 GitHub 扩展的 github.create_pull_request 能力展开,讲解该能力在 GitHub 扩展包 中的定位、完整输入参数语义、三种典型调用方式(普通 PR、Issue 转 PR、同组织跨仓库 PR)以及其背后的 WASM 实现与安全审批模型。读完本文,你将掌握如何让 IronClaw 中的 Agent 通过 github.create_pull_request 在 GitHub 上安全地执行外部写操作,并能准确理解其参数校验、凭证注入与错误处理机制。

能力定位:IronClaw 中的 GitHub 扩展工具

在 IronClaw 的扩展目录(extension catalog)中,GitHub 是覆盖面最大的工具面,共提供 49 个工具(github.get_repo 到 github.handle_webhook),扩展 ID 为 github。该扩展是一个 data-only 包:它不包含 Rust crate,行为以 WASM 访客(guest)模块交付,运行时为 wasm,产物提交在 wasm/github_tool.wasm,访客源码位于 wasm-src/(该目录被排除在工作区构建图之外)。完整的包规则见 crates/extensions/AGENTS.md。

github.create_pull_request 就是这 49 个工具之一,它在 manifest.toml 中的声明如下:

[[tools]]
origin_gate_matrix = { loop_run = "gated_unless_granted", product = "forbidden", automation = "forbidden" }
id = "github.create_pull_request"
description = "Create a pull request."
effects = ["network", "use_secret", "external_write"]
default_permission = "ask"
visibility = "model"
input_schema_ref = "schemas/github/create_pull_request.input.v1.json"
prompt_doc_ref = "prompts/github/create_pull_request.md"

从这份声明可以读出三个关键事实:

  • 这是一个外部写操作:effects 明确标注了 external_write,与只读的 github.get_pull_request(effects = ["network", "use_secret"]、default_permission = "allow")形成鲜明对比;
  • 默认需要审批:default_permission = "ask",模型调用前需要用户批准,同时 origin_gate_matrix 规定在 loop_run 场景下为 gated_unless_granted,在 product 与 automation 场景下直接 forbidden;
  • 必须配置 GitHub 产品认证账户:工具通过 github_runtime_token 凭证句柄访问 api.github.com,凭证以 Authorization 请求头注入,前缀为 token ,占位环境变量为 GH_TOKEN。

对应的提示词文档正是本文的起点 —— create_pull_request.md。它会在工具注册时与输入 JSON Schema 一起作为资源(asset)嵌入 ironclaw_extension_support 包中,具体嵌入逻辑见 packages/github.rs 的 github_prompt_asset! 宏。

输入参数完整参考(基于 JSON Schema)

github.create_pull_request 的输入 Schema 位于 schemas/github/create_pull_request.input.v1.json,采用 JSON Schema 2020-12 草案,并设置 additionalProperties: false,即必须使用精确的 JSON 字段名,任何多余字段都会被拒绝。

字段 类型 必填 约束 说明
owner string ✅ 长度 1–100;正则 ^[^\s/?#]+$;禁止 .. 仓库所有者或组织
repo string ✅ 长度 1–100;正则 ^[^\s/?#]+$;禁止 .. 仓库名
head string ✅ 长度 1–255 源分支或 ref
base string ✅ 长度 1–255 目标分支
title string 条件必填 长度 1–65536 PR 标题;除非提供 issue 将已有 Issue 转为 PR,否则必填
body string 否 最大 65536 PR 正文
issue integer 条件必填 最小值 1 要转换为 PR 的已有 Issue 编号
head_repo string 否 长度 1–100;正则 ^[^\s/?#]+$;禁止 .. 同组织跨仓库 PR 时,head 分支所在的仓库
maintainer_can_modify boolean 否 — 维护者是否可推送 head 分支
draft boolean 否 默认 false 是否以草稿(draft)形式创建

Schema 的约束组合表达了两个互斥的必填分支(anyOf):

"required": ["owner", "repo", "head", "base"],
"anyOf": [
  { "required": ["title"] },
  { "required": ["issue"] }
]

也就是说:owner、repo、head、base 四项恒为必填;在此基础上,title 与 issue 必须二选一 —— 要么提供标题新建 PR,要么提供 Issue 编号将已有 Issue 转化为 PR。

三种典型调用方式

提示词文档 create_pull_request.md 明确了该能力的核心使用约定:使用 github.create_pull_request 创建拉取请求;当用户询问维护者能否推送到 head 分支时,使用 maintainer_can_modify。结合 Schema 与源码,可以归纳出三种典型场景。

场景一:普通 PR(title 分支)

{
  "owner": "octocat",
  "repo": "hello-world",
  "head": "feature/add-readme",
  "base": "main",
  "title": "Add project readme",
  "body": "This PR adds the project readme and improves onboarding docs.",
  "draft": false
}

这是最常见的形式:指定源分支 head、目标分支 base 与标题 title,创建一个常规 PR。draft 不传时默认取 false(由 WASM 侧的 draft.unwrap_or(false) 兜底,见 dispatch.rs)。

场景二:将已有 Issue 转换为 PR(issue 分支)

{
  "owner": "octocat",
  "repo": "hello-world",
  "head": "feature/fix-typo",
  "base": "main",
  "issue": 42
}

当 Issue 已经包含了完整的描述与讨论,直接提供 issue 编号即可让 GitHub 把该 Issue 转换为 PR,PR 会自动继承 Issue 的标题与正文。此时 title 不可再传(anyOf 语义下两个分支互斥,同时传两个字段虽不违反 anyOf,但更规范的做法是二选一)。

场景三:同组织跨仓库 PR(head_repo)

{
  "owner": "acme",
  "repo": "backend",
  "head": "feature/refactor",
  "base": "main",
  "title": "Refactor service layer",
  "head_repo": "acme/backend-sandbox"
}

当 head 分支位于同组织内的另一个仓库时,使用 head_repo 指明该仓库。注意 head_repo 的 Schema 约束与 owner/repo 完全一致(长度 1–100、^[^\s/?#]+$、禁止 ..),并在 WASM 侧通过 validate_path_segment 再次校验(见下文)。

关于 maintainer_can_modify

提示词文档特别指出:maintainer_can_modify 用于用户询问维护者是否可以推送到 head 分支的场景。该字段为布尔值,置 true 表示允许仓库维护者向 PR 的源分支推送提交。

从 GitHub URL 提取字段的规则

提示词文档还约定了一套 URL 解析规则:如果用户提供 GitHub URL,应提取 owner 和 repo 字段,再加上 Schema 中与工具类型对应的编号/路径/ref 键。具体到拉取请求与 Issue 相关工具:

  • 拉取请求工具使用 pr_number;
  • Issue 工具使用 issue_number。

例如用户给出 https://github.com/octocat/hello-world/issues/42 并要求"把这个 Issue 转成 PR",则应解析出:

{
  "owner": "octocat",
  "repo": "hello-world",
  "issue": 42
}

而如果用户给出的是某个 PR 的 URL 并希望更新或合并它,则对应工具(如 github.update_pull_request、github.merge_pull_request)应使用 pr_number。这条规则保证模型在不同 GitHub 工具之间使用一致的字段语义,避免把 Issue 编号误当作 PR 编号使用。

底层实现:从调用链到 HTTP 请求构造

调用链概览

github.create_pull_request 的完整调用链为:

模型/用户 → manifest 注册的 capability (github.create_pull_request)
  → dispatch.rs::execute_inner 反序列化 GitHubAction::CreatePullRequest
  → api/pulls.rs::create_pull_request 构造请求体
  → request.rs::github_request 通过 host HTTP egress 发送 POST

dispatch.rs 负责把 capability ID 映射到对应的 action:action_name_from_capability_id 将 github.create_pull_request 解析为 action 名 create_pull_request,随后按 GitHubAction::CreatePullRequest 的字段解构参数,并调用 create_pull_request(&owner, &repo, title.as_deref(), &head, &base, body.as_deref(), issue, head_repo.as_deref(), maintainer_can_modify, draft.unwrap_or(false))。

WASM 侧参数校验

在 api/pulls.rs 中,create_pull_request 首先做本地校验:

if !validate_path_segment(owner) || !validate_path_segment(repo) {
    return Err("Invalid owner or repo name".into());
}
if issue.is_none() && title.is_none_or(|value| value.is_empty()) {
    return Err("invalid_parameters".to_string());
}
validate_input_length(title, "title")?;
validate_input_length(head, "head")?;
validate_input_length(base, "base")?;
validate_input_length(body, "body")?;
if let Some(head_repo) = head_repo {
    if !validate_path_segment(head_repo) {
        return Err("Invalid repository name".into());
    }
}

这里的 validate_path_segment(见 validation.rs)拒绝空串、/、..、?、# 以及所有控制字符和空白字符;validate_input_length 以 MAX_TEXT_LENGTH = 65536 为上限。这些校验与 JSON Schema 层面的约束相互呼应:Schema 负责在工具调用入口拦截非法字段,WASM 侧负责在发送 HTTP 请求前再次把关,形成双层防线。

校验通过后,构造请求体并发送:

let path = format!("/repos/{}/{}/pulls", encoded_owner, encoded_repo);
let mut req_body = serde_json::json!({
    "head": head,
    "base": base,
    "draft": draft,
});
// 可选字段按需追加:title / body / issue / head_repo / maintainer_can_modify
github_request("POST", &path, Some(req_body.to_string()))

注意 owner 与 repo 在拼入 URL 前会经过 url_encode_path 百分号编码,仅保留字母数字、-、_、.。

HTTP 请求与错误映射

最终请求由 request.rs 中的 github_request 完成:

  • 目标:https://api.github.com/repos/{owner}/{repo}/pulls,方法 POST;
  • 固定请求头:Accept: application/vnd.github+json、Content-Type: application/json、X-GitHub-Api-Version: 2026-03-10、User-Agent: IronClaw-GitHub-Reborn-WASM;
  • 超时:10 秒(HTTP_TIMEOUT_MS: u32 = 10_000);
  • 发送方式:通过 host 提供的 http_request 宿主函数走主机 HTTP egress(host-mediated egress),WASM 访客本身不直接建立网络连接。

错误处理也值得注意:HTTP 422 且响应体满足 GitHub "Validation Failed" 特征时返回 github_api_error_status_422_validation;HTTP 401 时会把响应体中的 message 字段(截断到 512 字符)暂存,供宿主在认证门(auth gate)上向用户展示"凭证无效"之类的可读诊断;其余非 2xx 状态统一映射为 github_api_error_status_{status}。宿主侧的 egress 拒绝、认证缺失等失败则映射为 github_api_egress_denied、AuthRequired 等稳定错误码。

安全模型:审批、凭证与写操作边界

github.create_pull_request 是整个 GitHub 扩展中安全模型最完整的工具之一,主要体现在三个层面:

  1. 权限门:default_permission = "ask" + origin_gate_matrix 中的 gated_unless_granted,意味着模型发起 PR 创建前必须经过用户审批;product、automation 场景则完全禁止,避免未经用户在场的外部写操作。
  2. 凭证注入:工具声明了 [[tools.credentials]],凭证句柄 github_runtime_token 由 [auth.github] 认证方式(api_key,GitHub personal access token)提供。宿主只向 api.github.com 注入 Authorization: token <TOKEN> 请求头,凭证不会暴露给 WASM 访客代码。类似地,扩展包内的 github.get_job_logs 在跟随 302 跳转到 Azure Blob 时会剥离 Authorization 头,防止令牌泄漏到第三方存储。
  3. 写操作显式声明:effects = ["external_write"] 让宿主在审批界面明示"这是一次外部写入",用户可以在批准前看到操作的完整参数。

此外,trust = "first_party_requested"(见 manifest.toml 头部)表明该包属于第一方扩展,其信任来源于扩展注册表(extension registry)而非管理员的本地 manifest 效果授权,相关说明见 packages/github.rs 的注释。

与周边工具的组合使用

创建 PR 只是 PR 生命周期的一环。GitHub 扩展包围绕 PR 提供了一整套工具(全部声明于 manifest.toml,实现于 api/pulls.rs):

  • github.list_pull_requests:列出仓库中的 PR 摘要(默认 state=open,limit 默认 30、上限 100);
  • github.get_pull_request:按 pr_number 获取单个 PR 详情;
  • github.update_pull_request:PATCH /repos/{owner}/{repo}/pulls/{pr_number},可更新标题、正文、状态、base 分支与 maintainer_can_modify;
  • github.get_pull_request_files:列出 PR 变更的文件;
  • github.create_pr_review:为 PR 创建评审(支持 COMMENT/APPROVE/REQUEST_CHANGES 等事件);
  • github.merge_pull_request:PUT /repos/{owner}/{repo}/pulls/{pr_number}/merge 合并 PR(默认 merge_method = "merge")。

典型工作流可以是:Agent 用 github.create_branch 创建分支 → github.create_or_update_file 提交变更 → github.create_pull_request 发起 PR → 用 github.get_pull_request 轮询状态 → github.merge_pull_request 合并。其中创建 PR 之前的每一步写操作(分支、文件)同样需要审批。

测试与产物一致性校验

GitHub 扩展作为 data-only 的 WASM 包,其一致性由两类检查保障(见 README.md):

  • manifest 投影测试:cargo test -p ironclaw_extension_registry,验证 manifest 中声明的工具、Schema、提示词资源能被正确解析与投影;
  • WASM 产物新鲜度检查:python3 scripts/ci/check-wasm-artifact-freshness.py,确认 wasm/github_tool.wasm 与 wasm-src/ 源码保持一致(重建方式为 ./scripts/build-wasm-extensions.sh --first-party 后再 --update)。

github.create_pull_request 的提示词文档与输入 Schema 会通过 include_str!/include_bytes! 宏直接编译进 ironclaw_extension_support 的 GitHub 包资源列表(见 packages/github.rs),因此提示词与 Schema 的任何修改都会影响二进制产物的一致性校验结果。

小结

github.create_pull_request 是 IronClaw GitHub 扩展中"创建拉取请求"的唯一入口,也是外部写操作安全模型的典型样本。使用时要记住四条核心规则:

  1. 字段必须精确匹配 Schema:additionalProperties: false 意味着任何拼写错误的字段都会被拒绝;
  2. title 与 issue 二选一:新建 PR 用 title,Issue 转 PR 用 issue;
  3. 跨仓库 PR 用 head_repo,维护者推送权限用 maintainer_can_modify;
  4. 该操作需要审批:default_permission = "ask" 且需要已配置的 GitHub personal access token,请求通过宿主 HTTP egress 以 Authorization: token <TOKEN> 头发出。

掌握这些约定,你就可以让 IronClaw 中的 Agent 可靠、安全地完成"从分支到 PR"的完整提交流程。

登录后查看全文
ironclaw