企业官网建设流程全解析

• 人工智能
• AI 应用
• 交互助手
• AI Agent

IronClaw 是一款以隐私、安全与可扩展性为核心的 Agent OS（其扩展包位于crates/extensions/packages/github），通过 WASM 访客（guest）扩展把 GitHub REST API 封装成一组可供 Agent 调用的工具（capability）。github.list_repos是其中用于枚举"已认证 GitHub 用户可见仓库"的核心只读工具。本文以扩展包内的能力提示文档 list_repos.md 为主干，结合输入 Schema、WASM 源码与 Manifest 配置，讲解该工具的参数语义、身份边界、调用方式与底层实现，帮助你在开发 Agent 技能或调试扩展行为时正确使用它。

能力定位：列出认证用户可见的仓库

github.list_repos的作用是列出当前 GitHub 认证账号可以访问的仓库。它的底层对应 GitHub REST 的/user/repos端点——注意这个端点返回的并不是"我拥有的仓库"，而是"我能访问的仓库"，范围包括：

• 认证用户自己拥有的仓库；
• 认证用户所属组织（organization）名下的仓库；
• 认证用户被授予访问权限的协作仓库（collaborator repositories）。

正如 list_repos.md 明确指出的，由于/user/repos会返回组织拥有的仓库，结果中的owner.login不能作为认证账号身份的证据。这一点是该工具最容易被误用的地方，详见下文"身份判定"小节。

参数说明：type过滤与分页

该工具的参数约束定义在输入 Schema list_repos.input.v1.json 中，共三个字段：

Schema 中additionalProperties为false，即不接受的额外字段会导致参数校验失败；同时所有字段都是可选的（required: []），因此可以不带任何参数直接调用，此时使用默认值拉取第一页、每页 30 条。

type各取值的语义

根据 list_repos.md 的说明，type控制 GitHub 的仓库隶属过滤，五个取值在认证的/user/repos端点上均合法：

• all：返回所有可见仓库（包含自己拥有的、组织内的、以及协作的）；
• owner：仅返回认证用户本人拥有的仓库；
• public：仅返回公开可见的仓库；
• private：仅返回私有可见的仓库；
• member：返回认证用户作为成员可以访问的仓库——当用户需要组织仓库或协作者仓库时，应使用member。

在 WASM 源码 types.rs 中，这五个取值被建模为RepoListType枚举，并通过as_str()原样序列化为查询参数；对应实现位于 repos.rs：

pub(crate) fn list_repos( repo_type: Option<RepoListType>, page: Option<u32>, limit: Option<u32>, ) -> Result<String, String> { validate_page(page)?; validate_limit(limit)?; let limit = limit.unwrap_or(30).min(100); // Cap at 100 let mut path = format!("/user/repos?per_page={}", limit); if let Some(repo_type) = repo_type { path.push_str("&type="); path.push_str(repo_type.as_str()); } if let Some(p) = page { path.push_str(&format!("&page={}", p)); } github_request("GET", &path, None) }

可见其请求路径固定为GET /user/repos，limit映射为per_page（默认 30、上限 100），page与type直接拼入查询串。参数校验函数validate_page与validate_limit定义在 validation.rs，其中page = 0会被判为invalid_page，limit超出1..=100会被判为invalid_limit——这解释了 Schema 中的最小/最大值约束来自何处。

身份判定：不要用list_repos回答 "who am I on GitHub?"

能力提示文档用一整段强调了该工具最关键的边界：github.list_repos不能用来回答"我在 GitHub 上是谁"。

原因在于/user/repos返回的是"认证用户可以访问的仓库"，其中包含组织拥有的仓库，因此列表里某个仓库的owner.login很可能是组织名（例如acme-inc/website），而不是认证用户的登录名。若 Agent 据此宣称"我就是 acme-inc"，就会产生身份误判。

正确的做法是调用专门的github.get_authenticated_user工具（对应GET /user端点）。配套提示文档 get_authenticated_user.md 给出了明确的调用时机：

• 用户提出"who am I on GitHub?"、"which GitHub account is connected?" 这类身份类问题；
• 在做出任何关于"已认证 GitHub 登录名"的断言之前；
• 在github.list_repos返回组织仓库、需要确认真实登录身份时。

从源码看，get_authenticated_user在 repos.rs 中实现为github_request("GET", "/user", None)，两者互不替代：一个回答"我能访问什么"，一个回答"我是谁"。

字段命名纪律与 GitHub URL 解析

能力提示文档要求严格使用该能力 Schema 中的精确 JSON 字段名调用工具。对github.list_repos而言，合法的顶层字段只有page、limit、type三个（见 list_repos.input.v1.json），传入其他字段会被additionalProperties: false拒绝。

当用户给出一个 GitHub URL 时，应从中提取结构化的字段值：

• 提取owner与repo（仓库类工具）；
• 数字型标识字段按工具类型命名：pull request 工具用pr_number，issue 工具用issue_number；
• 涉及文件路径或分支时提取对应的path或ref键。

这条规则在 WASM 侧有对应的严格校验：调度层 dispatch.rs 会把参数 JSON 反序列化为GitHubAction枚举，解析失败统一返回invalid_parameters；GitHubAction::ListRepos变体（types.rs）仅接受type、page、limit三个可选字段，其中type通过#[serde(rename = "type")]与 Rust 关键字repo_type映射——这再次印证了字段名必须与 Schema 完全一致。

底层链路：WASM 访客、HTTP 出口与认证

github.list_repos不是直接跑在宿主机上的函数，而是随扩展包分发的 WASM 模块中的能力。整个包的结构如下：

• manifest.toml：工具注册清单，id = "github"、version = "0.2.8"、runtime.kind = "wasm"、module = "wasm/github_tool.wasm"；
• prompts/github/list_repos.md：模型可见的能力使用提示（即本文主文档）；
• schemas/github/list_repos.input.v1.json：输入参数 Schema；
• wasm-src/：WASM 访客的 Rust 源码（不参与工作区构建图，仅作为可审计源码随包存放）。

请求如何发出

请求链路为：Agent 以github.list_repos为 capability id 发起调用 → 调度层通过action_name_from_capability_id（schema.rs）把"github.list_repos"映射为 action"list_repos"→ 反序列化参数 → 分发到list_repos实现 → 调用github_request。

github_request（request.rs）通过宿主的host::http_request走**主机 HTTP 出口（host HTTP egress）**发起请求，这与提示文档最后一句"reads from the GitHub API through host HTTP egress"完全对应。请求会带上：

• Accept: application/vnd.github+json；
• X-GitHub-Api-Version（当前仓库固定为2026-03-10）；
• 由宿主注入的认证头（详见下节）；
• 10 秒超时（HTTP_TIMEOUT_MS = 10_000）。

非 2xx 响应会被映射为稳定的错误码，如github_api_error_status_401、github_api_error_status_422_validation；401时的 GitHub 错误消息会被截断到 512 字符后交给宿主转递给鉴权门（见 request.rs），这体现了 IronClaw 对"访客错误消息暴露面"的收敛设计。

认证与权限

github.list_repos的凭证配置在 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"

即：使用 GitHub 个人访问令牌，以Authorization: token <GH_TOKEN>的形式注入到api.github.com的请求头中；同时[auth.github]段声明该产品账号通过GET /api.github.com/user（成功状态 200）完成有效性校验。因此调用该能力必须配置 GitHub product-auth 账号，这也是提示文档最后一句话的前提条件。

工具的权限模型在 Manifest 中也有体现：github.list_repos声明effects = ["network", "use_secret"]、default_permission = "allow"（只读、默认放行），而github.create_repo这类写操作则声明了external_write且默认ask。这意味着列出仓库是 Agent 可默认执行的低风险只读操作。

典型使用场景与最佳实践

综合提示文档与实现，github.list_repos的推荐用法如下：

1. 枚举可见仓库：直接调用github.list_repos（不带参数）即可获得第一页 30 条可见仓库；需要更多结果时用page/limit分页遍历（limit上限 100）。
2. 按隶属关系过滤：
   • 只要自己的仓库 →type: "owner"；
   • 需要组织/协作者仓库 →type: "member"；
   • 只关心公开或私有仓库 →type: "public"/type: "private"。
3. 定位后续操作目标：把列表结果中的full_name（owner/repo形式）提取出来，作为github.get_repo、github.list_issues、github.list_pull_requests等工具的owner+repo参数——提取后务必使用各工具 Schema 规定的精确字段名。
4. 不要用它做身份断言：涉及"当前登录用户是谁"的问题一律改用github.get_authenticated_user，避免被组织仓库的owner.login误导。

总结

github.list_repos是 IronClaw GitHub 扩展中语义最容易被误解的只读能力之一：它回答的是"认证账号能访问哪些仓库"，而不是"认证账号是谁"。使用时要记住三个要点：用type控制隶属过滤（all/owner/public/private/member）、用page/limit控制分页（上限 100）、把身份问题交给github.get_authenticated_user。在实现层面，它由 manifest.toml 注册、经 dispatch.rs 分发、由 repos.rs 组装GET /user/repos请求，并通过宿主 HTTP 出口与github_runtime_token凭证完成认证——理解这条链路，能帮助你在排查 Agent 仓库枚举类任务时快速定位问题所在。

• 人工智能
• AI 应用
• 交互助手
• AI Agent