IronClaw 中的 GitHub `add_issue_labels` 能力：为 Issue 与 Pull Request 批量添加标签的完整实践指南

IronClaw 中的 GitHubadd_issue_labels能力：为 Issue 与 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（扩展 ID：github），其中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）：

字段	类型	约束	说明
owner	string	1–100 字符；^[^\s/?#]+$；不允许..	仓库所有者（用户或组织）
repo	string	1–100 字符；^[^\s/?#]+$；不允许..	仓库名称
issue_number	integer	≥ 1	Issue 或 Pull Request 的编号
labels	array<string>	至少 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_number，PR 用pr_number

提示文档给出了一个重要的通用规则：如果用户直接提供 GitHub URL，应从中提取owner、repo以及 Schema 专属的编号/路径/引用键。对于 Issue 类工具使用issue_number，对于 Pull Request 类工具使用pr_number。

例如用户给出https://github.com/nearai/ironclaw/issues/4286：

• owner→nearai
• repo→ironclaw
• issue_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/。调用链如下：

1. Schema 内嵌：wasm-src/src/schema.rs通过include_str!("../../schemas/github/add_issue_labels.input.v1.json")将输入 Schema 编译进 WASM，并在运行时以oneOf联合 Schema 的形式暴露给模型（schema.rs）。
2. 操作分发：宿主根据调用上下文中的capability_id（如github.add_issue_labels）选择操作。dispatch.rs将GitHubAction::AddIssueLabels分支映射到add_issue_labels函数（dispatch.rs）。
3. 参数反序列化：types.rs定义AddIssueLabels { owner, repo, issue_number, labels }枚举变体（types.rs），serde 解析失败返回invalid_parameters。
4. 请求构造：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"]}

5. HTTP 出站：request.rs中的github_request将请求发往https://api.github.com，携带Accept: application/vnd.github+json、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.rs）：

• owner、repo必须通过validate_path_segment（非空、不含/、..、?、#、空白与控制字符）；
• labels列表至多 100 个值，且每个值非空、不超过 100 字符；
• 空列表直接报错Invalid labels: values cannot be empty。

这些校验保证了非法输入在出站前即被拦截。错误码会被映射为结构化的ErrorKind：校验类错误映射为Input，github_api_error_status_401映射为AuthRequired（并携带 GitHub 返回的受限错误消息），403/429 映射为Client，422 且在响应体中包含Validation Failed与errors数组时映射为Input（lib.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等过滤出目标 Issue；
• github.remove_issue_label：移除单个标签，实现“替换标签”效果（先删后加）；
• github.create_issue：建 Issue 时直接带labels字段，适合创建即打标；
• github.update_issue：PATCH整个 Issue，labels为覆盖式语义（传入空数组可清空标签）。

一个典型的自动化工作流是：模型先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