review-bot

审核机器人

发布技能可以通过 GitHub App 发布审核意见，这样拉取请求的作者就不会审核自己的工作。此技能正是实现这一点的机制：它包含用于生成 App 短期安装令牌并报告 App 身份的脚本。App 在每个仓库中单独声明，其私钥按机器分别保存；此处不会读取配置文件，也不会根据远程仓库推断仓库。

Reviewing identity 区块

仓库会在 docs/agents/issue-tracker.md 中通过以下固定区块声明其审核 App，每个发布技能都会读取此区块：

## Reviewing identity

- **Reviewing app**: <app name>
- **Client id**: <client id>

可选的第三个字段 Review-token command 用于存放字面意义上的 shell 命令，适用于令牌来自其他来源的仓库（例如来自密钥存储的机器人账户 PAT）。如果存在该字段，发布器会原样使用其中的命令，而不会查询此技能。

密钥所在位置

私钥是唯一按机器保存的项目。scripts/review_token.py 按以下顺序解析密钥：--key、REVIEW_BOT_KEY、~/.config/review-bot/<client id>.pem、~/.config/review-bot/key.pem；文件权限为 600。按客户端 ID 区分密钥，就能让一台机器保存两个仓库各自的 App 密钥。密钥绝不会存放在仓库中，也不会存放在已同步的技能目录下；持有密钥的任何人都能以该 App 的身份发布内容。

解析

依赖方调用的内容。输入：追踪文档中的客户端 ID 和 <owner>/<repo>，即拉取请求的目标仓库，绝不能使用检出目录的远程仓库（检出的是分叉仓库时，其远程仓库指向的就是分叉）。

1. 如果此技能不在已安装的技能中，或追踪文档没有提供客户端 ID，则返回下方对应的 unavailable 行。
2. 从此技能的根目录运行 python3 scripts/review_token.py whoami --client-id <id> <owner>/<repo>。其标准输出包含身份信息；所有失败原因都会写入标准错误，并以状态码 1 或 2 退出。
3. 如果退出状态码为 0，则返回两行：
   • reviewer: <slug>，即 app: 行中括号内的 slug。这是 GraphQL 格式，即不带 [bot] 的纯登录名，也是使用方读取的内容以及 finish-it 存入其数据包的内容。不要从 graphql login: 行获取，该行可能带有后缀。
   • review-token command: <the whoami "review-token command:" line, verbatim>。内容为 python3 <absolute path to scripts/review_token.py> token --client-id <id> <owner>/<repo>，路径经 shlex.quote 处理后再用 shell 引号括起，因此能够通过使用方执行的 sh -c "$tok" 再次解析。使用方在单引号包围的 sh -c '…' 中嵌入此命令时，会按常规方式转义其中包含的任何单引号；正如其发布参考所述，脚本路径中包含空格或其他元字符时，只有经过这一步才能在两种形式下都安全。绝对路径指向已安装技能自身，因此无需配置 PATH。
4. 如果退出状态码非零，则返回 review-bot: unavailable (<reason>)，其中原因取自标准错误，并表述为以下其中一种：
   • 不在已安装的技能中
   • 追踪文档中没有客户端 ID
   • 未在 <path> 找到密钥
   • 无法读取密钥
   • 签名失败（不是 App 私钥）
   • <owner>/<repo> 上未安装 App
   • 代码托管平台拒绝请求（HTTP <status>: <message>）
   • 网络或 TLS 故障

依赖方随后会回退到已认证用户，记录原因，并暂停门控。解析过程绝不会中止运行。

示例：某仓库声明的客户端 ID 为 Iv1.example，技能安装在 ~/.agents/skills/review-bot：

reviewer: reviewer
review-token command: python3 /home/me/.agents/skills/review-bot/scripts/review_token.py token --client-id Iv1.example acme/widgets

设置和检查

用户调用的形式为 /review-bot。陪同他们阅读 references/setup.md：按文档所列权限创建应用，将其安装到所有需要审核的仓库，生成并下载密钥，然后将其放在对应客户端 ID 的路径下。接着，针对他们指定的仓库运行 python3 scripts/review_token.py whoami --client-id <id> <owner>/<repo>，并展示输出：应用、两个登录名、安装信息及其权限，以及审核令牌命令。如果退出码非零，则报告 stderr 内容及其指向的 references/setup.md 步骤（404 表示安装未覆盖该仓库；openssl 拒绝则表示该文件不是应用的私钥）。

最后，打印要粘贴到该仓库的 docs/agents/issue-tracker.md 中的确切代码块，并根据 app: 行和客户端 ID 填写：

## Reviewing identity

- **Reviewing app**: <app name>
- **Client id**: <client id>

脚本

scripts/review_token.py 有两个子命令，没有其他子命令；GH_TOKEN=$(python3 scripts/review_token.py token …) gh … 是以应用身份运行临时调用的方式。

• token --client-id <id> <owner>/<repo> 会在 stdout 中打印仅限该仓库的安装令牌，不输出其他内容。令牌缓存位于 ~/.cache/review-bot/<client id>/<owner>/<repo>.json（REVIEW_BOT_CACHE_DIR 可覆盖根目录）；目录权限为 700，文件权限为 600，通过重命名 .part 文件写入；令牌剩余有效期超过五分钟时会复用；REVIEW_BOT_NO_CACHE=1 则始终重新签发。如果无法写入缓存，会在 stderr 中发出警告，但仍会打印签发的令牌。
• whoami --client-id <id> <owner>/<repo> 会打印 app: <name> (<slug>)、rest login: <slug>[bot]、通过 GraphQL viewer 查询并使用签发令牌读取的 graphql login: <login>、installation: <id> on <owner>/<repo>、permissions: …，以及 review-token command: …。如果探测时拒绝已缓存的令牌，会将其丢弃，在 stderr 中发出警告，然后重新签发一次。

两个子命令都接受 --key <path>（或 REVIEW_BOT_KEY）和 --api <url>（或 REVIEW_BOT_API，默认值为 https://api.github.com；GitHub Enterprise 使用 https://<host>/api/v3，并据此派生 GraphQL 端点 <host>/api/graphql）。如果密钥可被组用户或其他用户读取，脚本会在 stderr 中发出警告。

退出码：0 表示成功；1 表示代码托管服务已响应但拒绝请求（未安装、HTTP 401/403/404，或签发的令牌未通过探测）；2 表示没有响应或缺少本地输入（密钥缺失或无法读取、缺少 openssl 或其拒绝该密钥、网络或 TLS 故障），并会在 stderr 中指出失败的命令。TLS 验证失败时会指出 Install Certificates.command 和 SSL_CERT_FILE。调用方只检查是否非零，并将 stdout 捕获为令牌；令牌绝不会出现在脚本所运行的任何命令的 argv 中。

python3 scripts/test_review_token.py 会使用一次性密钥和本地伪造代码托管服务对脚本进行测试。