IronClaw 的 GitHub Issue 只读搜索能力github.search_issues 工具全解析【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclawgithub.search_issues是 IronClaw GitHub 扩展包中用于只读发现 GitHub issues 与 pull requests的核心工具它以github.search_issues_pull_requests兼容别名的形式存在面向 Agent 提供聚焦的搜索查询、紧凑的响应结构与标准分页能力。读完本文你将掌握该工具的完整输入参数语义、GitHub 搜索 qualifier 组合技巧、紧凑输出结构以及从 capability 映射到 WASM 访客执行再到 GitHub REST API 的完整底层调用链可直接在 IronClaw 的 Agent 会话与自定义扩展中落地使用。一、工具定位只读搜索的兼容别名在 IronClaw 的 GitHub 扩展包crates/extensions/packages/github/manifest.toml中github.search_issues被显式声明为id github.search_issues description Compatibility alias for compact github.search_issues_pull_requests results.它是一个兼容别名——底层与github.search_issues_pull_requests共享同一实现search_issues_pull_requests函数两者效果完全一致。因此本文介绍的所有行为对两个工具名同时成立。该工具具备以下特性只读语义仅发起GET请求不产生任何写入副作用effects[network, use_secret]即通过网络访问 GitHub API 并使用配置的密钥default_permission allow作为只读发现能力默认放行无需每次询问visibility model对模型可见、可调用origin_gate_matrixloop_run gated_unless_granted、product forbidden、automation forbidden即在 Agent 循环中受门控管理在产品与自动化来源中不可用。相比github.list_issues仅限单个仓库内按固定过滤条件列举github.search_issues走的是 GitHub 官方Search API/search/issues可以跨仓库、跨组织自由组合搜索条件是 Agent 进行问题发现、triage 与信息收集的首选入口。二、输入参数详解从 query 到结构化字段github.search_issues的输入由 crates/extensions/packages/github/schemas/github/search_issues.input.v1.json 定义核心参数如下参数类型约束说明querystring长度 1–512GitHub issue 搜索查询串支持repo:、org:、is:issue、is:pr、label:、state:、author:、assignee:、involves:等 qualifierrepositorystring长度 3–201格式owner/repo仓库简写用于在未提供 query 时构建repo:qualifierownerstring长度 1–100仓库所有者必须与repo成对出现repostring长度 1–201与owner配对时为仓库名单独提供时必须是owner/repo简写authorstring长度 1–100作者登录名构建author:qualifierassigneestring长度 1–100被指派者登录名构建assignee:qualifierinvolvesstring长度 1–100参与者登录名构建involves:qualifierstateenumopen/closedissue 状态 qualifiertypeenumissue/pr结果类型 qualifierpageinteger≥ 1默认 11 起始的结果页码limitinteger1–100默认 30单页最大返回条数sortenum见下方列表GitHub issue 搜索排序字段orderenumasc/desc默认desc配合 sort 的排序方向必须满足的输入约束Schema 中的anyOf规定query、repository、ownerrepo、单独repo、author、assignee、involves这七种情况至少提供一种否则校验失败。也就是说你既可以只给一个自由文本query也可以完全不写 query 而用结构化字段拼出限定条件。sort 可选值与 GitHub issue 搜索排序一致comments、created、updated、reactions、reactions-1、reactions--1、reactions-smile、reactions-thinking_face、reactions-heart、reactions-tada、interactions2.1 query 中的 GitHub 搜索 qualifier 实战关联文档强调当用户要求窄范围结果集时应在query中给出聚焦的 qualifier。常用组合包括repo:octocat/Hello-World is:issue state:open # 单仓库内开放 issue org:ironclaw is:pr state:open label:bug # 组织内带 bug 标签的开放 PR involves:me is:issue state:open # 与我相关的开放 issue author:octocat is:pr created:2026-01-01 # 某作者近期创建的 PR assignee:octocat is:issue label:good first issue # 指派给某人的新手友好 issue repo:octocat/Hello-World is:issue is:open in:title search # 标题中含关键词2.2 结构化字段如何拼接成 query当使用repository、owner/repo、author、assignee、involves、state、type等结构化字段时WASM 访客端会在内部把它们翻译成等价 qualifier 并与自由文本合并。其规则在 crates/extensions/packages/github/wasm-src/src/validation.rs 的build_issue_search_query第 169–227 行中实现repository与owner/repo互斥同时提供会返回invalid_repository错误repository必须包含/且两侧各不超过 100 字符validate_repository_segmentquery会先trim空串视为未提供author/assignee/involves值不允许空白、控制字符以及:、、(、)等特殊字符validate_search_qualifier_valuestate仅接受open/closedtype仅接受issue/prvalidate_search_state、validate_search_type最终合并的完整 query 同样受512 字符上限约束MAX_SEARCH_QUERY_LENGTH超出返回invalid_query_too_large若所有部分都为空返回invalid_query_empty。三、输出结构紧凑的搜索结果信封github.search_issues的响应由 crates/extensions/packages/github/schemas/github/search_issues.output.v1.json 定义保留了 GitHub 搜索 API 的经典信封结构{ total_count: 128, incomplete_results: false, items: [ { number: 42, title: Fix flaky egress test, state: open, state_reason: null, draft: false, locked: false, html_url: https://api.github.com/repos/ironclaw/ironclaw/issues/42, repository_url: https://api.github.com/repos/ironclaw/ironclaw, comments: 3, created_at: 2026-08-01T10:00:00Z, updated_at: 2026-08-10T10:00:00Z, closed_at: null, author_association: CONTRIBUTOR, score: 1.0, user: { login: octocat }, labels: [{ name: bug }], assignees: [{ login: octocat }], milestone: { title: v0.3 }, pull_request: null } ] }三个顶层字段的含义total_countGitHub 报告的匹配结果总数≥ 0incomplete_resultsGitHub 是否返回了不完整的结果集布尔值items当前页的条目数组必填字段additionalProperties开放以便透传其他字段。3.1 响应压缩只保留模型所需字段WASM 访客端通过 crates/extensions/packages/github/wasm-src/src/response.rs 的compact_issue_search第 16–36 行对 GitHub 原始响应做紧凑化投影每个条目compact_search_item第 67–99 行保留基础字段number、title、state、state_reason、draft、locked、html_url、repository_url、comments、created_at、updated_at、closed_at、author_association、score嵌套对象投影user.login、labels[].name、assignees[].login、milestone.titlePR 标记pull_request若为 PR 条目投影url、html_url、merged_at三个字段issue 条目中该字段为null。同时validate_page_size第 167–172 行会校验单页条目数不超过 100MAX_PAGE_ITEMS防止异常响应撑爆上下文。这一设计让模型拿到的每个条目都足够做出下一步决策如是否进入详情读取又不会因超大响应浪费 token。四、从搜索到详情的组合工作流关联文档明确给出了该工具的使用策略先用 search 做窄范围发现再用 detail 工具取全文。搜索阶段用github.search_issues或github.search_issues_pull_requests拿回紧凑摘要通过page/limit翻页详情阶段对感兴趣的单个结果调用github.get_issue按 issue number 取单个 issue/PR见 prompts/github/get_issue.md或github.get_pull_request取单个 PR见 prompts/github/get_pull_request.md获取 body 等完整细节。两个 detail 工具的提示词都强调严格使用 schema 中的精确 JSON 字段名当用户直接给出 GitHub URL 时从中提取owner、repo以及 schema 特定的编号字段——PR 类工具用pr_numberissue 类工具用issue_number。与同为列表型能力的github.list_issues单仓库、固定过滤条件相比github.search_issues的优势在于跨仓库/组织自由组合 qualifier适合找所有仓库里带某标签的开放 issue某作者近期提交的所有 PR这类聚合型问题。五、底层调用链从 capability 到 GitHub REST APIgithub.search_issues的完整执行路径可以拆解为五层所有实现均位于扩展包的 WASM 访客源码 crates/extensions/packages/github/wasm-src 中Capability 映射IronClaw host 将 capability idgithub.search_issues传给 WASM 访客schema.rs第 18 行将其映射为内部 action 名search_issues_pull_requeststypes.rs第 273 行以#[serde(rename search_issues_pull_requests)]声明对应的GitHubAction变体。参数分发dispatch.rs第 304–332 行解析 JSON 参数并调用search_issues_pull_requests(...)把query、repository、owner、repo、author、assignee、involves、state、issue_type、page、limit、sort、order全部透传。查询构造与校验api/search.rs第 47–75 行先经build_issue_search_query拼接 query见上文 2.2 节再校验page、limit、sort随后构造请求路径GET /search/issues?q{url_encode_query(query)}per_page{limit}[page{p}sort{s}order{o}]append_search_paramsvalidation.rs 第 144–166 行追加分页与排序参数其中order仅接受asc/desc。HTTP 执行request.rs第 36–77 行的github_request通过 host 提供的 HTTP egresscrate::near::agent::host::http_request向https://api.github.com发起请求带 10 秒超时HTTP_TIMEOUT_MS并附加请求头Accept: application/vnd.githubjson Content-Type: application/json X-GitHub-Api-Version: 2026-03-10 User-Agent: IronClaw-GitHub-Reborn-WASM响应压缩github_request成功后compact_issue_search按第三节的投影规则压缩响应返回给模型。5.1 认证与网络出口凭证注入manifest.toml 中每个工具都声明[[tools.credentials]]handle github_runtime_token、vendor github、audience { scheme https, host api.github.com }、injection { type header, name authorization, prefix token }。即运行时以Authorization: token GH_TOKEN头注入 GitHub token占位环境变量为GH_TOKEN。产品级认证[auth.github] 配置采用api_key方法字段为 GitHub personal access token并通过GET https://api.github.com/user期望 200做配置校验。这正是关联文档所说需要配置 GitHub product-auth 账户的含义。网络出口请求经由 host HTTP egress 代发request.rs把HttpFailure映射为语义化错误码例如AuthRequired需要认证、github_api_egress_denied网络出口被拒绝、github_api_body_limit响应体过大、github_api_executor_failed等方便 host 与模型理解失败原因。六、错误处理与边界行为GitHub 非 2xx 状态统一返回github_api_error_status_{status}错误码401 会额外捕获并截断上限 512 字符GitHub 返回的message文本供 host 带到认证门控做诊断request.rs第 72–74、84–95 行。422 校验失败仅当响应体同时含message: Validation Failed且errors数组非空时才归类为github_api_error_status_422_validationis_github_validation_error_body避免把abuse detection等其他 422 误判相关单测见 request.rs 第 236–248 行。参数校验错误集中在 validation.rs包括invalid_repository、invalid_query_empty、invalid_query_too_large、invalid_state、invalid_type、invalid_sort、invalid_page、invalid_limit、invalid_author、invalid_assignee、invalid_involves等全部在发起网络请求前拦截。响应结构异常compact_issue_search解析失败或items缺失时返回github_api_invalid_response。七、测试验证与源码索引扩展包的 WASM 访客单元测试位于 crates/extensions/packages/github/wasm-src/src/lib.rs与本主题直接相关search_issues_pull_requests_accepts_wider_sort第 1612 行验证 issue 搜索接受 GitHub 全量排序字段含 reaction 类排序search_issues_pull_requests_compacts_items_and_preserves_envelope_and_errors第 1629 行验证响应被压缩为紧凑 items 且保留total_count/incomplete_results信封并正确传递错误search_issues_pull_requests_rejects_commit_search_sort第 1724 行验证拒绝非 issue 搜索的排序值如 commit 类 sort。值得关注的是测试中直接以capability_idgithub.search_issues驱动执行lib.rs 第 153 行附近印证了该兼容别名与search_issues_pull_requests同源同测的事实。相关文件索引工具提示词crates/extensions/packages/github/prompts/github/search_issues.md、search_issues_pull_requests.md输入/输出 Schemasearch_issues.input.v1.json、search_issues.output.v1.json实现源码api/search.rs、validation.rs、response.rs、request.rs、dispatch.rs、schema.rs工具注册与认证配置crates/extensions/packages/github/manifest.toml扩展包总览crates/extensions/packages/github/README.md八、使用建议小结优先窄查询任何涉及找出具体一批 issue/PR的需求先想清楚repo:、org:、is:issue/is:pr、state:、label:、author:、assignee:、involves:这些 qualifier 的组合缩小到目标结果集再配合page/limit翻页区分搜索与列举跨仓库/跨组织聚合搜索用github.search_issues单仓库内按固定条件列举用github.list_issues搜索之后接详情紧凑结果只适合做筛选决策需要正文、评论、review 等完整信息时按条目类型选择github.get_issueissue_number或github.get_pull_requestpr_number注意只读边界该工具是纯只读发现能力默认允许执行任何写入动作应改用github.create_issue、github.update_issue、github.comment_issue等写操作工具它们默认default_permission ask需要显式授权。【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考