企业官网建设流程全解析

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

本篇技术指南围绕 IronClaw 开源仓库中 GitHub 扩展包的github.list_pull_request_comments能力展开，讲解如何在 Agent 会话中按仓库与 PR 编号列出 pull request review comments（评审评论），并利用sort、direction、since参数实现有序或增量拉取。阅读完本文，你将掌握该能力的完整输入参数、默认值与校验规则、底层 REST 请求的构造方式，以及认证、权限与错误处理的实现细节，可直接在 IronClaw 的 Agent 编排或扩展开发中落地使用。

能力定位：github.list_pull_request_comments是什么

github.list_pull_request_comments是 IronClaw GitHub 扩展中用于列出 Pull Request 评审评论的工具。在 GitHub 的语义里，评审评论（review comments）与时间线评论（issue comments）是两类不同的对象：前者是评审者在 PR 的 diff 行内留下的批注，后者是 PR 页面上普通对话流中的评论。本能力面向前者，对应 GitHub REST API 的GET /repos/{owner}/{repo}/pulls/{pull_number}/comments端点。

官方 prompt 文档（prompts/github/list_pull_request_comments.md）给出了使用该能力的四条核心指引：

• 用github.list_pull_request_comments列出 pull request review comments；
• 当用户要求有序或最近更新的评审评论时，使用sort、direction和since参数；
• 必须使用该能力 schema 中的精确 JSON 字段名；如果用户提供 GitHub URL，要提取出owner和repo字段，以及 schema 指定的编号、路径或 ref 键——对 PR 类工具用pr_number，对 issue 类工具用issue_number；
• 该能力通过 host HTTP egress 读取 GitHub API，并且需要一个已配置的 GitHub product-auth 账户。

从扩展包结构看，该能力属于 GitHub 扩展（扩展 id 为github），它是 IronClaw 工具目录中覆盖面最大的扩展之一（仓库 README.md 显示共 49 个工具），且是纯数据包（data-only package）：没有独立 crate，行为以 WASM 访客（guest）形式交付，源码位于 wasm-src/，编译产物为wasm/github_tool.wasm。

输入参数详解：从 JSON Schema 到字段语义

该能力的输入严格由 schemas/github/list_pull_request_comments.input.v1.json 约束。这是一个additionalProperties: false的对象 schema，即传入 schema 之外的多余字段会被直接拒绝。各字段说明如下：

值得注意的字段细节：

• owner/repo的严格校验：schema 层禁止空白、/、?、#等字符和..路径穿越片段，这与源码中validate_path_segment的防护逻辑一致（见 wasm-src/src/validation.rs），目的是防止构造出越权或畸形的请求路径。
• pr_number的命名：schema 明确规定 PR 类工具使用pr_number（issue 类工具则是issue_number）。同时，在 Rust 反序列化层（wasm-src/src/types.rs）为pr_number声明了number、pull_number两个别名（#[serde(alias = "number", alias = "pull_number")]），提升了容错性。
• since的时间格式：要求 ISO 8601 的date-time格式，例如2026-06-23T00:00:00Z，用于实现"只看最近更新"的增量场景。
• 分页上限：limit最大 100，超出即校验失败；默认 30，与 GitHub API 的常规分页习惯对齐。

从 URL 到参数：owner / repo / pr_number 的提取规则

官方 prompt 文档要求：当用户给出的是 GitHub URL 而不是结构化参数时，模型需要先做字段提取。规则可以概括为：

• 从形如https://github.com/{owner}/{repo}/pull/{pr_number}的 URL 中提取owner、repo，PR 场景的编号键是pr_number；
• 若是 issue 场景（/issues/{issue_number}），编号键则必须是issue_number；
• 所有字段名必须与能力 schema 中的精确 JSON 字段名一致，不能自造别名。

这条规则的统一性很重要：GitHub 扩展的 49 个工具共享同一套"从 capability id 到 action、从 URL 到参数"的解析约定，便于模型在多工具间保持一致行为。实现层面，schema.rs中的action_name_from_capability_id会把github.list_pull_request_comments这类 capability id 去掉github.前缀映射为 action 名（wasm-src/src/schema.rs），而 wasm-src/src/dispatch.rs 负责把解析出的参数 JSON 与 action 名合并后分发到具体的 API 实现。

底层调用链与请求构造

调用github.list_pull_request_comments时，请求会经历如下链路：

1. 分发：dispatch.rs的execute_inner根据 capability id 反序列化出GitHubAction::ListPullRequestComments枚举，并调用list_pull_request_comments（wasm-src/src/dispatch.rs）。
2. 校验：进入 wasm-src/src/api/pulls.rs 中的同名函数，先做validate_path_segment（owner/repo）、validate_page（page 不能为 0）、validate_limit（1–100）三组校验；since若提供还需通过validate_input_length的长度检查。
3. 构造 URL：核心实现构造出如下 REST 路径：

GET /repos/{owner}/{repo}/pulls/{pr_number}/comments?per_page={limit}

之后按需追加查询参数：&sort={sort}、&direction={direction}、&since={since}（since 值经url_encode_query百分号编码）、&page={page}。从 wasm-src/src/api/pulls.rs 的源码可以看出，limit会先取默认值 30 再与 100 取最小值，即limit.unwrap_or(30).min(100)，与 schema 的约束保持一致。

4. 发起请求：最终交给github_request("GET", &path, None)（wasm-src/src/request.rs）。请求固定携带以下请求头：

   • Accept: application/vnd.github+json
   • Content-Type: application/json
   • X-GitHub-Api-Version: 2026-03-10
   • User-Agent: IronClaw-GitHub-Reborn-WASM

   请求基址为https://api.github.com，超时时间为 10 秒。值得注意的是，GitHub 扩展是 WASM guest，其 HTTP 出口是通过 host 侧的http_request能力完成的——这正是 prompt 文档所说"reads from the GitHub API through host HTTP egress"的底层含义。

排序与增量查询：sort / direction / since 的实战用法

prompt 文档特别强调：当用户要求有序或最近更新的评审评论时，应使用sort、direction和since。结合 schema 与源码，它们的组合语义如下：

• sort=created：按评论创建时间排序；sort=updated：按评论最后更新时间排序。枚举值定义在 wasm-src/src/types.rs 的PullRequestCommentSort。
• direction=asc/desc：配合sort指定升序或降序。注意 schema 注释写明"Sort direction when sort is supplied"，即 direction 依赖 sort 而存在。
• since=<ISO 8601 时间戳>：只返回该时间点之后更新过的评论，适合"上次检查之后有哪些新批注"的增量同步场景。

三个参数可组合使用。以"查看某个 PR 最近更新、按更新时间倒序、只看 2026-06-23 之后的评论"为例，一个合法的调用参数如下：

{ "owner": "nearai", "repo": "ironclaw", "pr_number": 12, "sort": "updated", "direction": "desc", "since": "2026-06-23T00:00:00Z", "page": 1, "limit": 30 }

这条调用在仓库的单元测试中有精确断言（见 wasm-src/src/lib.rs 的list_pull_request_comments相关测试）：它验证了上述参数组合最终生成的请求路径为

/repos/nearai/ironclaw/pulls/12/comments?per_page=2&sort=updated&direction=desc&since=2026-06-23T00%3A00%3A00Z&page=3

注意since中的冒号被编码成了%3A，这正是url_encode_query生效的结果，也再次印证了 prompt 文档要求"使用 schema 精确字段名、按字段语义传参"的必要性。

认证与网络出口：需要怎样的 GitHub 账户配置

prompt 文档明确指出：该能力需要一个已配置的 GitHub product-auth 账户。从 manifest.toml 可以看到该工具完整的认证与权限声明：

• 凭据句柄：github_runtime_token，供应商（vendor）为github；
• 受众：audience = { scheme = "https", host = "api.github.com" }，即凭据只对 api.github.com 生效；
• 注入方式：injection = { type = "header", name = "authorization", prefix = "token " }，即运行时把 token 以Authorization: token <TOKEN>的形式注入请求头；
• 占位环境变量：placeholder_env = "GH_TOKEN"，方便本地以GH_TOKEN环境变量提供占位值。

在扩展包的[auth.github]配置段中，认证方式为api_key（"GitHub personal access token"），字段 handle 同样是github_runtime_token，校验方式是向https://api.github.com/user发GET请求并期望200，注入前缀为Bearer。这意味着：一个有效的 GitHub Personal Access Token 即满足 product-auth 的配置前提；配置完成后，github.list_pull_request_comments这类只读工具在default_permission = "allow"下可直接执行，无需每次询问。

权限模型：何时允许、何时需要门禁

该工具在 manifest 中的声明如下（manifest.toml）：

• origin_gate_matrix = { loop_run = "gated_unless_granted", product = "forbidden", automation = "forbidden" }：loop（Agent 主循环）场景下默认受门禁控制，除非已授予权限；product 与 automation 场景直接禁止。
• effects = ["network", "use_secret"]：声明副作用为网络访问与使用机密（token），不包含external_write——它是只读能力，不会对外产生写入。
• default_permission = "allow"：默认放行，即只读查询通常可直接执行。
• visibility = "model"：对模型可见。

因此在实际使用中，读评论属于低风险操作，默认即放行；而像github.create_pr_review、github.reply_pull_request_comment等写操作则声明了external_write且default_permission = "ask"，需要显式确认。这与 IronClaw 面向隐私与安全的权限分层设计是一致的。

错误处理与边界行为

请求失败时的错误码映射同样值得了解（wasm-src/src/request.rs）：

• 非 2xx 状态码统一映射为github_api_error_status_{status}，例如 404 对应github_api_error_status_404；
• 422 且响应体符合 GitHub "Validation Failed" 结构时，映射为github_api_error_status_422_validation（有errors数组才算校验失败，普通的 "abuse detection" 消息不会被误判）；
• 401 时会把 GitHub 返回的message字段截取前 512 字符暂存，供上层在认证门禁处向模型呈现可读诊断；
• host 层网络失败按类型映射：AuthRequired、invalid_parameters、github_api_body_limit（输出过大）、github_api_egress_denied（出口被拒）、github_api_request_failed等。

此外，WASM 入口层若能力 id 不合法会返回unsupported_github_capability，参数不是合法 JSON 则返回invalid_parameters，且参数对象中不允许自带action字段（见 wasm-src/src/dispatch.rs）。

与相邻能力的配合

github.list_pull_request_comments不是孤立存在的，它属于 PR 评审工作流工具组（prompts 目录见 prompts/github/）。完整的评审闭环通常还需要：

• reply_pull_request_comment.md：回复某条评审评论（POST /pulls/{pr_number}/comments/{comment_id}/replies）；
• get_pull_request_reviews.md：列出 PR 的 review 汇总（GET /pulls/{pr_number}/reviews）；
• list_pull_request_review_threads.md：列出内联评审线程（走 GraphQL/graphql端点，且刻意不加载每线程评论详情，见 wasm-src/src/lib.rs 中的review_threads_use_graphql_endpoint测试）；
• create_pr_review.md：提交评审。

典型的使用姿势是：先用list_pull_request_comments拿到某 PR 的既有批注（可配合since只取增量），再决定是否回复、解析线程或提交新的评审，从而在 IronClaw 的 Agent 工作流里完整承担 PR 评审的读写职责。

验证与扩展开发参考

如果你想进一步验证或二次开发该能力，仓库中值得关注的落点包括：

• 能力注册与声明：manifest.toml 中id = "github.list_pull_request_comments"的工具条目；
• 输入约束：list_pull_request_comments.input.v1.json；
• 请求构造与校验：api/pulls.rs 的list_pull_request_comments函数；
• 参数反序列化：types.rs 的PullRequestCommentSort、Direction枚举与ListPullRequestCommentsaction；
• 端到端测试断言：lib.rs 中验证完整查询串的单元测试。

整体来看，github.list_pull_request_comments是 IronClaw GitHub 扩展中一个典型的"小而严谨"的只读能力：参数 schema 严格、校验前置、请求构造透明、认证与权限模型清晰，可以作为理解整个 GitHub 扩展包（乃至 IronClaw 扩展机制）的入门样例。

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