IronClaw GitHub 扩展深度解析：用 github.get_pull_request 能力获取单个 Pull Request

IronClaw GitHub 扩展深度解析用 github.get_pull_request 能力获取单个 Pull Request【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw本篇技术指南聚焦 IronClaw面向隐私、安全与可扩展性的 Agent OS中 GitHub 扩展包内的github.get_pull_request能力它如何通过宿主 HTTP egress 读取 GitHub API、需要怎样的认证账号、输入参数契约长什么样以及调用底层经过了哪些校验、调度与错误处理链路。读完本文你将掌握该能力从「用户给出一段 GitHub URL」到「返回 PR 原始 JSON」的完整调用姿势并能在 crates/extensions/packages/github 包内自行追溯每一处实现细节。一、能力定位GitHub 扩展中的单 PR 详情工具在 IronClaw 的 GitHub 扩展包扩展 ID 为github见 README.md中github.get_pull_request是 49 个工具github.get_repo…github.handle_webhook之一职责非常单一按仓库与编号抓取一个 Pull Request 的完整数据。它对应的能力说明文档位于 prompts/github/get_pull_request.md原文明确给出三条使用准则用github.get_pull_request抓取一个Pull Request必须使用该能力 schema 中精确的 JSON 字段名若用户提供的是 GitHub URL则从中提取owner、repo以及 schema 特定的数字/路径/引用键——对 PR 类工具用pr_number对 Issue 类工具用issue_number该能力经由宿主 HTTP egress读取 GitHub API且要求配置了 GitHub 产品认证账号。在 manifest.toml 中该工具被声明为[[tools]] origin_gate_matrix { loop_run gated_unless_granted, product forbidden, automation forbidden } id github.get_pull_request description Fetch one pull request. effects [network, use_secret] default_permission allow visibility model input_schema_ref schemas/github/get_pull_request.input.v1.json prompt_doc_ref prompts/github/get_pull_request.md值得注意的声明要点只读且默认放行effects只有network与use_secret没有external_writedefault_permission allow说明它是读取即允许的只读能力与create_pull_request、merge_pull_request等写操作default_permission ask形成鲜明对比来源门控origin_gate_matrix规定仅在loop_runAgent 主循环内可用且默认 gated未授权则拦截在product与automation来源下被禁止运行时形态整个 GitHub 扩展是一个data-only 包行为以 WASM guest 形式交付编译产物为wasm/github_tool.wasm源码在wasm-src/不参与工作区构建图。二、输入参数契约owner、repo、pr_number 的完整约束调用github.get_pull_request必须严格遵循其输入 JSON Schema位于 schemas/github/get_pull_request.input.v1.json。该 schema 采用 JSON Schema 2020-12 草案additionalProperties设为false意味着传入 schema 之外的任何字段都会被拒绝源码中亦有测试印证serde_rejects_unknown_fields_before_egress测试断言多余字段会返回invalid_parameters。三个必填字段及约束如下字段类型约束说明ownerstring长度 1–100模式^[^\s/?#]$禁止包含..仓库所有者或组织名repostring长度 1–100模式^[^\s/?#]$禁止包含..仓库名pr_numberinteger最小值为 1Pull Request 编号一个合法的最小调用参数示例{ owner: nearai, repo: ironclaw, pr_number: 4286 }owner/repo的正则^[^\s/?#]$从源头排除了空格、斜杠、问号、井号等会破坏 URL 路径结构的字符not: \.\.则挡住了路径穿越尝试。这些约束与 WASM 端代码里的validate_path_segment见下文第六节构成双重防线。兼容别名虽然 schema 规定字段名为pr_number但从源码测试 lib.rs 的serde_accepts_common_pr_number_aliases可以确认反序列化层额外接受了number作为pr_number的别名Issue 类工具则接受issue_number例如let action: GitHubAction serde_json::from_value(json!({ action: get_pull_request, owner: nearai, repo: ironclaw, number: 4286 })) .expect(number should be accepted as a pull request number alias);但注意additionalProperties: false的 schema 层面约束依然存在因此官方推荐始终使用精确字段名pr_number别名只是历史兼容层。三、从 GitHub URL 提取参数的实操指引能力文档的核心指导之一是当用户直接粘贴 GitHub URL 而非结构化参数时模型需要自行完成URL → 参数的提取。以典型 PR 地址为例https://github.com/nearai/ironclaw/pull/4286应提取为{ owner: nearai, repo: ironclaw, pr_number: 4286 }提取规则在 prompts/github/get_pull_request.md 及同目录其他能力文档中被统一为一条约定从 URL 的github.com/{owner}/{repo}/...段提取owner与repo再按工具类型选择数字键PR 类工具用pr_number如get_pull_request、get_pull_request_files、get_pull_request_reviews、merge_pull_request等Issue 类工具用issue_number如get_issue、create_issue_comment等涉及文件、分支或引用的工具如get_file_content则使用 schema 规定的path或ref键。这条约定同时出现在同目录的 get_pull_request_files.md、get_issue.md 等文档中是整个 GitHub 扩展统一的参数提取协议模型侧保持精确字段名习惯即可避免误用issue_number调 PR 工具。四、前置条件GitHub 产品认证账号与宿主 egress能力文档最后一句强调该能力reads from the GitHub API through host HTTP egress and requires a configured GitHub product-auth account。这句话背后有两层机制都能在包内配置中找到证据。第一层凭证声明。每个工具的[[tools.credentials]]段见 manifest.toml声明了统一的运行时凭证句柄[[tools.credentials]] handle github_runtime_token vendor github audience { scheme https, host api.github.com } injection { type header, name authorization, prefix token } placeholder_env GH_TOKEN凭证受众audience被限定为https://api.github.com只有对该主机的请求才会注入Authorization头注入方式为请求头注入prefix token 与 GitHub CLI 的Authorization: token GH_TOKEN行为一致manifest 中亦以注释引用说明placeholder_env GH_TOKEN表明该句柄对应的环境占位变量。第二层账号验证。manifest 末尾的[auth.github]段定义了产品认证product-auth的校验方式[auth.github] method api_key display_name GitHub personal access token fields [ { handle github_runtime_token, label Personal access token, secret true } ] validation { method GET, url https://api.github.com/user, success_status [200], inject { handle github_runtime_token, type header, name authorization, prefix Bearer } }即配置的 GitHub Personal Access Token 在认证校验时会被以Bearer前缀注入到GET https://api.github.com/user返回 200 才视为账号可用。因此使用github.get_pull_request前必须先配置并验证 GitHub 产品认证账号可用github.get_authenticated_user直接查询当前 token 对应的用户。同时从 WASM 源码 lib.rs 的模块注释可以确认一个重要的安全设计guest 本身从不读取或构造 GitHub token凭证完全由宿主 HTTP egress 层注入。五、底层实现链路从 capability_id 到 GitHub REST 请求github.get_pull_request的执行路径可以完整追溯到 WASM 源码。整个调用链如下入口宿主通过 WIT 接口调用GitHubTool::executelib.rs传入params与context动作识别dispatch.rs 的action_from_context从调用上下文context.capability_id形如github.get_pull_request解析出动作名action_name_from_capability_id还会把github.comment_issue等兼容别名归一化search_issues→search_issues_pull_requests参数注入params_with_action把动作名以action字段注入参数对象防止调用方伪造 action 字段若参数中已含action直接返回invalid_parameters分发execute_inner的 match 分支GitHubAction::GetPullRequest { owner, repo, pr_number } get_pull_request(owner, repo, pr_number)调用 API 层API 层pulls.rs 中的get_pull_request完成路径段校验后构造GET /repos/{owner}/{repo}/pulls/{pr_number}并委托github_request请求执行request.rs 的github_request拼出完整 URLhttps://api.github.com/repos/...设置请求头后通过crate::near::agent::host::http_request宿主 egress 能力发出请求超时上限 10 秒。get_pull_request的具体实现pulls.rspub(crate) fn get_pull_request(owner: str, repo: str, pr_number: u32) - ResultString, String { if !validate_path_segment(owner) || !validate_path_segment(repo) { return Err(Invalid owner or repo name.into()); } let encoded_owner url_encode_path(owner); let encoded_repo url_encode_path(repo); github_request( GET, format!( /repos/{}/{}/pulls/{}, encoded_owner, encoded_repo, pr_number ), None, ) }对应的 HTTP 请求request.rs 中构造为GET https://api.github.com/repos/{owner}/{repo}/pulls/{pr_number} Accept: application/vnd.githubjson Content-Type: application/json X-GitHub-Api-Version: 2026-03-10 User-Agent: IronClaw-GitHub-Reborn-WASM Authorization: token GH_TOKEN ← 由宿主 egress 按 credentials 声明注入六、egress 前的输入校验安全第一道防线在发起任何网络请求之前get_pull_request会对owner与repo执行validate_path_segmentvalidation.rs校验规则为非空不含/、..、?、#不含控制字符与空白字符。随后url_encode_path对路径段做百分号编码除字母、数字、-、_、.外全部编码从实现层面杜绝了 URL 注入与路径穿越。pr_number为u32类型且 schema 要求minimum: 1天然排除了 0 与负数。这套schema 层 WASM 层双重校验的策略在源码测试中被反复验证如list_pull_requests_rejects_invalid_sort_direction_and_pagination测试断言校验失败发生在 egress 之前requests().is_empty()。其收益是无效参数不会浪费网络请求也不会把恶意构造的路径传给宿主 egress。七、响应与错误处理原始 JSON 契约与错误码分类响应形态github.get_pull_request属于 manifest 注释中所说的detail tool——GitHub REST 端点返回异构的供应商自有响应结构详情类工具保留其原始 JSON 契约见 manifest.toml 的注释说明。因此该工具返回的是 GitHub Pull Request 对象的原始 JSON而不是被压缩过的摘要压缩摘要只发生在list_pull_requests、search_issues_pull_requests等高基数列表工具上这些工具的 prompt 文档会专门指向详情工具取全量数据。从列表压缩测试的 fixture 可以观察到 PR 对象中常见的字段维度如number、title、state、body、user.login、labels、assignees、requested_reviewers、milestone、draft、created_at/updated_at/closed_at/merged_at、head.ref/head.sha、base.ref/base.sha、html_url、author_association等——get_pull_request会原样带回这些完整细节。错误处理github_requestrequest.rs对非 2xx 响应做如下处理422且响应体是 GitHub 风格的 Validation Failed含非空errors数组→ 返回github_api_error_status_422_validation401→ 记录供应商错误消息从响应体message字段提取截断至 512 字符见provider_error_message与测试provider_error_message_bounds_the_message_to_512_chars返回github_api_error_status_401其余非 2xx → 返回github_api_error_status_{status}宿主 egress 失败 → 映射为AuthRequired、invalid_parameters、github_api_body_limit、github_api_egress_denied、github_api_request_failed等稳定错误码host_failure_code。随后 lib.rs 的guest_error_kind会把错误码归类为 WIT 层的ErrorKind401/AuthRequired→AuthRequired各类参数校验错误 →Inputgithub_api_body_limit→OutputTooLargegithub_api_egress_denied→NetworkDenied403/429 →Client其余 →OperationFailed。401 时捕获的供应商消息会随guest-failure.message一并返回由宿主转交给认证门auth gate用于诊断且宿主在展示给模型前会做清理与限长。八、与相邻 PR 能力的协同使用github.get_pull_request在 GitHub 扩展的 PR 工具族中处于详情查询位置与之配套的同类能力prompt 文档均位于 prompts/github 目录包括能力职责与本工具的关系github.list_pull_requests列出仓库内 PR 的压缩摘要先列表、后取详情列表省略大字段详情只能通过get_pull_request获取github.get_pull_request_files列出 PR 变更文件需pr_number支持page/limit分页大 PR 必须翻页否则只返回第一页github.get_pull_request_reviews列出 PR 评审同为只读详情工具github.create_pull_request/github.update_pull_request创建/更新 PR写操作default_permission askgithub.merge_pull_request合并 PR写操作default_permission ask从 lib.rs 的list_pull_requests_compacts_realistic_large_provider_response测试可以印证协作模式列表工具会把动辄数 MB 的供应商响应压缩到 100KB 以内的模型可用摘要并刻意丢弃body、head.repo、_links等大字段——测试断言large detail must remain available only through github.get_pull_request。也就是说Agent 的标准工作流是list 定位 → get_pull_request 取全量详情get_pull_request是补齐列表摘要所缺细节的唯一入口。九、质量保障测试如何锁定该能力的行为GitHub 扩展的 WASM 源码内置了大量单元测试随cargo test -p执行其中与本能力直接相关的有schema 完整性schema_exposes_bug1_parameters断言聚合 schema 中能找到GitHub get_pull_request_files input等所有工具的输入 schema且数量 ≥ 30字段名严格性serde_rejects_unknown_fields_before_egress断言多余字段导致invalid_parameters别名兼容serde_accepts_common_pr_number_aliases验证number/pull_number别名错误码分类guest_error_kind_classifies_string_validation_errors_as_input、guest_error_kind_does_not_classify_generic_422_as_input等锁定错误分类边界请求构造get_pull_request_files_uses_page_and_limit断言请求路径为/repos/nearai/ironclaw/pulls/42/files?per_page50page3可用于类比验证get_pull_request的路径构造/repos/{owner}/{repo}/pulls/{pr_number}。此外包的 manifest 投影由cargo test -p ironclaw_extension_registry校验WASM 产物新鲜度由python3 scripts/ci/check-wasm-artifact-freshness.py把关重新构建见scripts/ci/目录下的构建脚本说明确保wasm/github_tool.wasm与wasm-src/源码始终同步。十、使用注意事项小结结合能力文档与源码实现使用github.get_pull_request时建议遵循以下要点字段名必须精确传owner、repo、pr_number不要随意增删字段additionalProperties: false会拒绝未知字段优先结构化参数用户给 URL 时按owner repo pr_number提取PR 工具绝不用issue_number先认证再调用确保配置了已通过校验的 GitHub 产品认证账号校验方式见 manifest.toml 的[auth.github]段否则 egress 会返回AuthRequired/github_api_error_status_401把它当作详情入口列表类工具只给压缩摘要需要完整 PR 数据正文、head/base 仓库信息、链接等时必须调用本工具理解门控模型该工具仅在loop_run来源可用默认 gatedproduct与automation来源被禁止这是 IronClaw 权限模型的一部分详见 crates/extensions/AGENTS.md 的扩展包规则按需配合相邻能力变更文件多时配合github.get_pull_request_files的page/limit分页评审场景配合github.get_pull_request_reviews。如需在仓库中继续深入建议按以下路径阅读能力文档 prompts/github/get_pull_request.md → 输入 schema schemas/github/get_pull_request.input.v1.json → 调度 wasm-src/src/dispatch.rs → API 实现 wasm-src/src/api/pulls.rs → egress 与错误处理 wasm-src/src/request.rs。【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考