IronClaw 中 GitHub 仓库查询能力 `github.get_repo` 的调用规范与实现解析

IronClaw 中 GitHub 仓库查询能力github.get_repo的调用规范与实现解析【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw导读github.get_repo是 IronClaw GitHub 扩展extension id 为github中用于查询单个 GitHub 仓库元数据的核心只读能力也是该扩展 49 个工具中查询链路最简单、最典型的入口之一。本文以 get_repo.md 为主线围绕调用约定、参数规范、认证前提与 WASM 底层实现四个层面展开帮助你掌握在 IronClaw 中正确调用该能力的方式并理解它如何通过宿主 HTTP 出口host HTTP egress安全访问 GitHub API。一、能力概述与调用约定原文档给出了github.get_repo三条核心调用约定用途使用github.get_repo获取一个 GitHub 仓库的信息。参数规范必须使用该能力 schema 中精确的 JSON 字段名如果用户提供的是 GitHub URL则需要从中提取owner和repo字段并依据具体工具类型提取 schema 特定的数字、路径或 ref 键——例如 PR 工具用pr_numberIssue 工具用issue_number。运行前提该能力通过宿主 HTTP 出口读取 GitHub API需要已配置的 GitHub product-auth 账户。这三条约定在 manifest.toml 中均有对应声明[[tools]] origin_gate_matrix { loop_run gated_unless_granted, product forbidden, automation forbidden } id github.get_repo description Get a GitHub repository. effects [network, use_secret] default_permission allow visibility model input_schema_ref schemas/github/get_repo.input.v1.json prompt_doc_ref prompts/github/get_repo.md [[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从声明中可以解读出几个关键事实effects [network, use_secret]该工具被系统声明为“发起网络请求 使用密钥”两类副作用与文档所述“通过宿主 HTTP 出口读取 GitHub API、需要已配置的 product-auth 账户”完全对应。default_permission allow查询仓库是只读操作默认允许执行无需每次人工确认对比写操作如create_repo、create_issue均为ask。origin_gate_matrix表明该工具仅在loop_run上下文中被允许且默认 gated_unless_granted在 product 与 automation 上下文中为forbidden。凭据github_runtime_token由供应商github持有仅针对api.github.com注入以Authorization: token GH_TOKEN头方式注入——这正是 GitHub CLI 的标准做法manifest.toml 中保留了对应出处注释。二、输入参数规范精确的 JSON 字段名github.get_repo的输入 schema 位于 schemas/github/get_repo.input.v1.json其完整定义如下{ $schema: https://json-schema.org/draft/2020-12/schema, title: GitHub get_repo input, type: object, additionalProperties: false, properties: { owner: { type: string, minLength: 1, maxLength: 100, pattern: ^[^\\s/?#]$, not: { pattern: \\.\\. }, description: Repository owner or organization. }, repo: { type: string, minLength: 1, maxLength: 100, pattern: ^[^\\s/?#]$, not: { pattern: \\.\\. }, description: Repository name. } }, required: [owner, repo] }字段约束解读字段类型约束含义ownerstring必填1–100 字符^[^\s/?#]$禁止..仓库所有者或组织名repostring必填1–100 字符^[^\s/?#]$禁止..仓库名其余字段—additionalProperties: false不允许任何多余字段需要特别注意的是additionalProperties: false意味着参数必须“精确匹配”多余字段会直接导致解析失败。这一约束与 lib.rs 中的测试用例serde_rejects_unknown_fields_before_egress一致传入{query:...,extra:ignored?}这样的多余字段时工具会在发起任何网络请求之前就返回invalid_parameters。路径穿越防护owner/repo不允许包含空白、/、?、#也不允许包含..防止通过参数拼接出越界路径。从 URL 提取参数若用户直接给出形如https://github.com/owner/repo的 URL模型应当只提取owner与repo两个字段而不是把整个 URL 传给工具。调用示例{ owner: iro, repo: ironclaw }对于 PR 与 Issue 类工具URL 中还需提取各自的数字键例如https://github.com/iro/ironclaw/pull/4286应转换为github.get_pull_request的{owner:iro,repo:ironclaw,pr_number:4286}对应地在 types.rs 中get_pull_request的pr_number还接受number、pull_number两个别名。三、从 URL 到参数能力 schema 驱动的字段提取规则原文档强调“使用该能力 schema 中精确的 JSON 字段名”这一点在实现层面由两处机制保证schema 驱动的运行时校验所有 GitHub 工具的输入 schema 在编译期通过include_str!内嵌进 WASM 模块见 schema.rs运行时对外暴露为oneOf联合 schemagithub.get_repo对应的分支就是get_repo.input.v1.json。WIT 接口的schema()方法lib.rs 中GitHubTool::schema()返回整个联合 schema宿主侧借此对模型生成的参数做前置校验。字段提取规则的具体语义是模型把自然语言中的仓库 URL 拆解为ownerrepo并针对不同类型的工具附带不同的定位键pr_number/issue_number/path/ref等。这是该扩展所有 49 个工具共享的统一约定github.get_repo因其“仅需 ownerrepo”而成为最简单的一种。四、认证与安全模型product-auth 账户与凭证注入原文档指出该能力“requires a configured GitHub product-auth account”。这里的认证链路由宿主统一管理WASM 访客guest本身不接触任何令牌凭证声明在 manifest.toml 的[auth.github]段认证方式为api_key字段为github_runtime_tokenGitHub personal access token并声明了校验端点GET https://api.github.com/user成功状态 200注入头为Authorization: Bearer token。请求发出时宿主 HTTP 出口根据audience { scheme https, host api.github.com }匹配目标自动注入Authorization: token GH_TOKEN头prefix token 并在该目标上配置placeholder_env GH_TOKEN。WASM 模块在 lib.rs 的模块注释中明确声明“The host selects the operation via the invocation context capability id and mediates GitHub credentials through HTTP egress; this component never reads or constructs a GitHub token.”——即访客代码永远不会读取或构造令牌令牌仅由宿主注入。这一设计将“使用密钥”use_secret的副作用限制在宿主侧与 IronClaw 以隐私、安全、可扩展性为核心的 Agent OS 定位一致。五、源码级实现从调用到 GitHub API 的完整链路github.get_repo的底层实现是纯 Rust 编写、以 WASM 形式发布的访客工具源码位于 wasm-src/src其调用链如下1. 入口Guest::executeWIT 世界为sandboxed-tool定义在 lanes/ironclaw_wasm/wit/tool.wit。宿主通过capability_id即github.get_repo选择操作把参数 JSON 与调用上下文传入// lib.rs impl exports::near::agent::tool::Guest for GitHubTool { fn execute(req: Request) - Response { match dispatch::execute_inner(req.params, req.context.as_deref()) { Ok(result) Response::Success(result), Err(error) Response::Failure(GuestFailure { kind: guest_error_kind(error), code: Some(error), message: request::take_last_error_message(), }), } } }2. 分派dispatch::execute_innerdispatch.rs 根据上下文解析出 action 名称并分派GitHubAction::GetRepo { owner, repo } get_repo(owner, repo),其中action_from_context从{capability_id:github.get_repo}中解析出get_repodispatch.rsGitHubAction枚举的GetRepo变体在 types.rs 中以#[serde(rename get_repo)]声明且整个枚举带deny_unknown_fields再次印证“多余字段直接报invalid_parameters”。3. 参数校验与 URL 组装api::repos::get_reporepos.rs 中实现pub(crate) fn get_repo(owner: str, repo: str) - 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/{}/{}, encoded_owner, encoded_repo), None, ) }关键点双重校验除 JSON schema 外运行时还会调用validate_path_segmentvalidation.rs拒绝空串、/、..、?、#、控制字符与空白。URL 编码url_encode_path对路径段做百分号编码仅保留字母、数字、-、_、.保证特殊字符不会破坏路径结构。端点映射对应 GitHub REST APIGET /repos/{owner}/{repo}即仓库详情端点。4. HTTP 出口request::github_requestrequest.rs 负责实际请求const GITHUB_API_ROOT: str https://api.github.com; const GITHUB_API_VERSION: str 2026-03-10; const HTTP_TIMEOUT_MS: u32 10_000; let headers serde_json::json!({ Accept: application/vnd.githubjson, Content-Type: application/json, X-GitHub-Api-Version: GITHUB_API_VERSION, User-Agent: IronClaw-GitHub-Reborn-WASM }); let response crate::near::agent::host::http_request( method, url, headers.to_string(), body_bytes.as_deref(), Some(HTTP_TIMEOUT_MS), )?;该函数通过宿主提供的host::http_request发起请求即文档所说的“host HTTP egress”并固定携带 GitHub 官方要求的X-GitHub-Api-Version头。2xx 状态直接返回响应体401时会捕获 GitHub 返回的错误信息截断到 512 字符见 request.rs用于生成对模型可见的诊断信息其他状态码映射为github_api_error_status_{code}错误码。5. 错误分类guest_error_kindlib.rs 将错误码归类为 WIT 定义的ErrorKindinvalid_parameters、Invalid owner or repo name→ErrorKind::Inputgithub_api_error_status_401、AuthRequired→ErrorKind::AuthRequired宿主据此触发认证门控github_api_egress_denied→ErrorKind::NetworkDenied其余 →ErrorKind::OperationFailed这解释了原文档“requires a configured GitHub product-auth account”当令牌缺失或无效时调用方会收到AuthRequired类错误由宿主把认证请求带到认证门控流程而不是让访客直接暴露令牌问题。六、使用场景与相邻能力github.get_repo是只读查询工具适合作为工作流的第一步在创建 PR、Issue 或分支前先确认目标仓库存在且可见配合default_permission allow无需人工确认与其他只读工具组合成“仓库侦察”序列github.get_repo→github.list_branches→github.get_file_content与github.list_repos、github.search_repositories形成“枚举 → 精查”的查询范式。同类相邻能力同目录下 prompts/github包括list_repos列出当前账户可见仓库、search_repositories按关键字搜索、get_file_content读取仓库文件等写操作类如create_repo、fork_repo则默认需要ask授权体现了“读默认放行、写必须确认”的权限策略。七、验证与回归保障该能力的正确性由多层测试保障可以在仓库中自行验证schema 静态测试lib.rs 中validates_static_schema_json验证内嵌 schema 是合法 JSON 且oneOf分支不少于 30 个schema_exposes_bug1_parameters等测试逐条校验各工具 schema 的字段形态。分派与校验测试operation_comes_from_host_context_not_param_shape、serde_rejects_unknown_fields_before_egresslib.rs验证操作由上下文capability_id决定、多余参数在出口前被拒绝。产物新鲜度检查github扩展以预编译 WASM 形式交付wasm/github_tool.wasmREADME.md 提供了重建与校验命令./scripts/build-wasm-extensions.sh --first-party与python3 scripts/ci/check-wasm-artifact-freshness.py。manifest 投影测试cargo test -p ironclaw_extension_registry验证 manifest 声明与注册表投影的一致性。这些测试共同保证了字段名严格、参数在出口前校验、错误分类稳定是原文档“精确字段名”约定的落地保障。八、小结维度结论能力标识github.get_repoGitHub 扩展 49 个工具之一输入ownerrepo两个必填字符串严格按 schema 字段名认证需配置 GitHub product-auth 账户令牌由宿主注入Authorization: token权限只读default_permission alloweffects [network, use_secret]端点GET https://api.github.com/repos/{owner}/{repo}X-GitHub-Api-Version: 2026-03-10实现载体Rust → WASMwasm-src/src产物wasm/github_tool.wasm错误语义AuthRequired触发认证门控输入校验错误统一为ErrorKind::Input在 IronClaw 中github.get_repo是理解“能力 schema prompt 文档 manifest 声明 WASM 实现”四层协作机制的理想入口prompt 文档告诉模型如何调用schema 约束参数形态manifest 声明副作用与凭据WASM 实现真正完成出口请求。掌握这一条链路也就掌握了阅读 GitHub 扩展其余 48 个工具的方法论。【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考