IronClaw 扩展实战:使用 github.create_pull_request 能力安全创建 GitHub 拉取请求
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 扩展中安全模型最完整的工具之一,主要体现在三个层面:
- 权限门:
default_permission = "ask"+origin_gate_matrix中的gated_unless_granted,意味着模型发起 PR 创建前必须经过用户审批;product、automation场景则完全禁止,避免未经用户在场的外部写操作。 - 凭证注入:工具声明了
[[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 头,防止令牌泄漏到第三方存储。 - 写操作显式声明:
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 扩展中"创建拉取请求"的唯一入口,也是外部写操作安全模型的典型样本。使用时要记住四条核心规则:
- 字段必须精确匹配 Schema:
additionalProperties: false意味着任何拼写错误的字段都会被拒绝; title与issue二选一:新建 PR 用title,Issue 转 PR 用issue;- 跨仓库 PR 用
head_repo,维护者推送权限用maintainer_can_modify; - 该操作需要审批:
default_permission = "ask"且需要已配置的 GitHub personal access token,请求通过宿主 HTTP egress 以Authorization: token <TOKEN>头发出。
掌握这些约定,你就可以让 IronClaw 中的 Agent 可靠、安全地完成"从分支到 PR"的完整提交流程。