IronClaw 中的 GitHubadd_issue_labels能力为 Issue 与 Pull Request 批量添加标签的完整实践指南【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclawIronClaw 作为一款以隐私、安全与可扩展性为核心的 Agent OS将 GitHub 能力封装为独立扩展包github扩展 IDgithub其中github.add_issue_labels专门用于为 Issue 或 Pull Request 添加标签Labels。本文基于该能力的提示文档与仓库源码完整讲解其调用契约、JSON 参数格式、URL 提取规则、底层 WASM 实现链路、审批与凭据要求以及可复现的测试验证帮助你安全、准确地使用这一能力完成 Issue/PR 的自动化标签管理。能力定位一次外部写入操作在 IronClaw 的 GitHub 扩展工具面Tool Surface中github.add_issue_labels是 49 个工具之一见 扩展 README其语义在提示文档中定义得非常明确Usegithub.add_issue_labelsto add labels to an issue or pull request.该能力通过 GitHub API 执行外部写入external write使用宿主 HTTP 出站host HTTP egress将请求发往api.github.com因此它必须经过审批approval并且要求环境中已配置 GitHub 产品认证product-auth账号。这一点与只读类工具如github.list_issues、github.get_issue有本质区别——写操作默认不会自动放行。调用契约必需的四个参数根据 add_issue_labels.input.v1.json 中定义的 JSON Schema调用时必须提供四个字段缺一不可required字段类型约束说明ownerstring1–100 字符^[^\s/?#]$不允许..仓库所有者用户或组织repostring1–100 字符^[^\s/?#]$不允许..仓库名称issue_numberinteger≥ 1Issue 或 Pull Request 的编号labelsarraystring至少 1 个、至多 100 个元素每个元素 1–100 字符要添加的标签名列表Schema 顶层还声明了additionalProperties: false意味着不接受任何未在 Schema 中定义的额外字段同时所有字段名必须严格使用上述精确 JSON 字段名exact JSON field names不要使用number、pull_number等别名。最小可用的参数示例{ owner: nearai, repo: ironclaw, issue_number: 42, labels: [bug, priority/high] }从 URL 中提取参数issue 用issue_numberPR 用pr_number提示文档给出了一个重要的通用规则如果用户直接提供 GitHub URL应从中提取owner、repo以及 Schema 专属的编号/路径/引用键。对于 Issue 类工具使用issue_number对于 Pull Request 类工具使用pr_number。例如用户给出https://github.com/nearai/ironclaw/issues/4286owner→nearairepo→ironclawissue_number→4286由于 GitHub 中 Pull Request 与 Issue 共享同一套编号空间add_issue_labels既能用于 Issue 也能用于 PR统一使用issue_number字段。需要提醒的是仓库实现为 PR 类工具提供过number、pull_number等 serde 反序列化别名见 lib.rs 测试但能力 Schema 与提示文档要求的是issue_number应始终以 Schema 为准。底层实现链路从 Schema 到 GitHub API该能力不是直接在宿主中实现的而是作为一个WASM guest运行github包是纯数据包data-only package无 crate其行为以编译好的wasm/github_tool.wasm交付guest 源码位于wasm-src/。调用链如下Schema 内嵌wasm-src/src/schema.rs通过include_str!(../../schemas/github/add_issue_labels.input.v1.json)将输入 Schema 编译进 WASM并在运行时以oneOf联合 Schema 的形式暴露给模型schema.rs。操作分发宿主根据调用上下文中的capability_id如github.add_issue_labels选择操作。dispatch.rs将GitHubAction::AddIssueLabels分支映射到add_issue_labels函数dispatch.rs。参数反序列化types.rs定义AddIssueLabels { owner, repo, issue_number, labels }枚举变体types.rsserde 解析失败返回invalid_parameters。请求构造api/issues.rs中的add_issue_labels委托给通用的issue_name_list_request辅助函数issues.rs最终构造POST /repos/{owner}/{repo}/issues/{issue_number}/labels Content-Type: application/json {labels: [bug, priority/high]}HTTP 出站request.rs中的github_request将请求发往https://api.github.com携带Accept: application/vnd.githubjson、X-GitHub-Api-Version、User-Agent: IronClaw-GitHub-Reborn-WASM等请求头并设置 10 秒超时request.rs。从源码结构看issue_name_list_request是 Issue 名称列表类写操作的统一入口add_issue_assignees、remove_issue_assignees也复用了同一套构造逻辑仅端点与请求体字段不同。权限模型为什么必须审批在 manifest.toml 中github.add_issue_labels的声明如下[[tools]] origin_gate_matrix { loop_run gated_unless_granted, product forbidden, automation forbidden } id github.add_issue_labels description Add labels to an issue or pull request. effects [network, use_secret, external_write] default_permission ask visibility model input_schema_ref schemas/github/add_issue_labels.input.v1.json prompt_doc_ref prompts/github/add_issue_labels.md三个要点值得展开effects [network, use_secret, external_write]同时声明了网络访问、使用密钥和对外写入三种效果是能力被判定为高风险写操作的核心依据。default_permission ask默认权限为“询问”即模型在 loop 运行中调用此工具时默认会进入审批流程结合origin_gate_matrix的gated_unless_granted与github.get_repo等读操作的default_permission allow形成对照。凭据注入工具绑定github_runtime_token凭据句柄audience限定为https://api.github.com以Authorization: token GH_TOKEN请求头形式由宿主在出站时注入对应环境变量占位符GH_TOKEN。[auth.github]一节还定义了 product-auth 校验方式对GET https://api.github.com/user返回 200 即视为有效manifest.toml。这意味着即使模型“想”给某个 Issue 打标签也必须经过用户审批且必须存在已配置的 GitHub 个人访问令牌personal access token令牌的权限范围如issues: write需要覆盖目标仓库的标签写入操作。输入校验与错误处理在出站前拦截非法参数issue_name_list_request在真正发起 HTTP 请求之前会做多层校验issues.rsowner、repo必须通过validate_path_segment非空、不含/、..、?、#、空白与控制字符labels列表至多 100 个值且每个值非空、不超过 100 字符空列表直接报错Invalid labels: values cannot be empty。这些校验保证了非法输入在出站前即被拦截。错误码会被映射为结构化的ErrorKind校验类错误映射为Inputgithub_api_error_status_401映射为AuthRequired并携带 GitHub 返回的受限错误消息403/429 映射为Client422 且在响应体中包含Validation Failed与errors数组时映射为Inputlib.rs、request.rs。401 时捕获的 provider 消息会被截断到 512 字符并经过宿主清洗后才暴露给模型。测试验证行为有据可查仓库在 lib.rs 中提供了issue_mutation_tools_use_native_endpoints测试用 mock 响应验证了add_issue_labels的完整行为( github.add_issue_labels, r#{owner:nearai,repo:ironclaw,issue_number:42,labels:[api,reborn]}#, POST, /repos/nearai/ironclaw/issues/42/labels, json!({labels:[api,reborn]}), ),测试断言了三个事实请求方法为POST、请求路径为/repos/{owner}/{repo}/issues/{issue_number}/labels、请求体为{labels:[api,reborn]}——与 Schema 和提示文档完全一致可直接作为集成联调时的对照基准。配套能力与典型工作流在实战中add_issue_labels通常与以下工具组合使用github.list_issues先按state、labels、assignee、milestone等过滤出目标 Issuegithub.remove_issue_label移除单个标签实现“替换标签”效果先删后加github.create_issue建 Issue 时直接带labels字段适合创建即打标github.update_issuePATCH整个 Issuelabels为覆盖式语义传入空数组可清空标签。一个典型的自动化工作流是模型先list_issues定位待处理的 Issue → 用户确认后调用add_issue_labels打上bug/priority/high标签 → 处理完成后用remove_issue_label或update_issue清理。由于全部写操作都需要审批模型可以在一次审批会话中按顺序完成标签的增删兼顾效率与可控性。小结github.add_issue_labels是 IronClaw 扩展体系中的一个典型“受控写操作”参数契约由 输入 Schema 严格约束实现以 WASM guest 形式运行并复用统一的名称列表写入辅助函数权限上同时声明网络、密钥与外部写入三种效果并要求审批与 product-auth 账号最终通过宿主 HTTP egress 将POST /repos/{owner}/{repo}/issues/{issue_number}/labels请求发出。掌握其参数格式、URL 提取规则与权限模型即可在 IronClaw 中安全可靠地完成 Issue/PR 的自动化标签管理。【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址: https://gitcode.com/gh_mirrors/iro/ironclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考