Pake 的 GitHub 运维技能：用 gh CLI 安全、可验证地处理 Issue、PR 与 Release

本文围绕 Pake 仓库内置的 GitHub 运维技能 SKILL.md 展开，完整解析这套面向 AI Agent 的运维规范：何时使用 gh CLI、哪些"项目事实"可以避免 Agent 误判仓库状态、CI/npm/Release 三类状态各该用哪条命令核验，以及五条安全规则如何约束 Agent 的写操作。读完本文，你既能直接沿用这套 gh 运维流程管理任意 GitHub 仓库，也能理解 Pake 自身的发布流水线（release.yml、npm-publish.yml、quality-and-test.yml 等）为何按此设计。

一、技能定位：GitHub 运维，而非代码评审或打包

该技能位于 plugins 技能目录体系 同级的 Agent 技能体系中，frontmatter 明确声明了边界：

name: github-ops
description: GitHub issue, PR, and release operations via gh CLI. Not for code review or release builds.
version: 2.1.0
allowed-tools:
  - Bash
  - Read

两个关键约束值得注意：

• 能力边界：技能只覆盖 issue、PR、release 的"操作面"（查询、评论、合并、关闭、发版），明确排除代码评审和 release 构建本身——后者由 release.yml 与 single-app.yaml 等 workflow 承担；
• 工具白名单：allowed-tools 只允许 Bash 与 Read，即 Agent 只能"执行命令 + 读文件"，不能越权写仓库内容。这意味着所有 GitHub 状态交互都必须走 gh CLI，而不是直接改本地文件去"模拟"发布。

二、Golden Rule：先查活状态，再动手

技能开篇即给出最高优先级规则：

Always use gh CLI and query live state before acting. Never assume state from memory or a previous turn.

这条规则针对的是 Agent 的典型失败模式：在上一轮对话中读到过某个 PR 是 open 状态，就默认它现在仍是 open。正确做法是在每个写操作前重新查询。对应的实操命令模式包括：

# 查询某个 issue 当前状态，而不是凭记忆回答
gh issue view <id> --json number,title,state,author,url

# 查询 release 的真实产物（资产数量与状态）
gh release view <tag> --json assets

# 查询某条 workflow run 的终态
gh run view <run-id> --json status,conclusion

后文所有"核验命令"都服务于这条规则：任何结论必须先有活查询证据。

三、项目事实（Project Facts）：五条避免误判的仓库特定知识

技能的核心价值浓缩在 5 条"项目事实"中。以下逐条结合仓库内 workflow 源码佐证。

3.1 仓库与 workflow 版图

技能声明仓库为 tw93/Pake（package.json 中 repository.url 也指向该仓库），并列出 5 个关键 workflow 及其触发方式：

Workflow 文件	触发方式	职责
release.yml	V* tag 推送	构建应用资产、创建 Release、发布 Docker 镜像
npm-publish.yml	V* tag 或 main 分支手动 workflow_dispatch	npm Trusted Publishing；支持仅发 npm 的热修复
quality-and-test.yml	push（main/dev）与 PR	日常 CI：格式化、Rust 质量、CLI 快速验证、完整 Tauri 构建
pake-cli.yaml	外部用户从 fork 手动触发	公共构建入口，把任意网页打包成桌面应用
single-app.yaml	外部用户从 fork 手动触发	单应用公共构建

源码层面的印证：

• release.yml 第 3-6 行确实以 on: push: tags: ["V*"] 触发，create-release job 通过 ncipollo/release-action 创建占位 Release，build-popular-apps job 以 default_app_list.json 为矩阵复用 single-app.yaml；
• npm-publish.yml 声明 permissions: id-token: write（第 25 行），这是 npm Trusted Publishing 所必需的 OIDC 权限，与技能描述完全吻合；其 workflow_dispatch 入口（第 11-20 行）要求传入精确的 expected_sha 和对应成功的 quality_run_id，即"npm-only 热修复必须绑定到 main 上某个通过质检的 commit"；
• quality-and-test.yml 的 on: push: branches: [main, dev] + pull_request 印证其 push CI 定位；
• pake-cli.yaml 只有 workflow_dispatch 输入（platform、url、name、icon、宽高等），构建后按平台上传 DMG/DEB/AppImage/RPM/ZST/MSI artifact，正是外部用户在 fork 中自助触发构建的入口。

3.2 轮询 CI 的正确姿势：禁止管道吞掉退出码

技能要求：

Poll CI with gh run view <run-id> --json status,conclusion. Never pipe gh run watch or build output through tail/head; pipes swallow the real exit code and misreport failures as green.

背后的 shell 机制：cmd | tail 的退出码默认取自 tail 而非 cmd（除非开启 pipefail）。把 gh run watch 或构建输出接到 tail/head 上，即使构建失败，管道整体仍可能返回 0，导致 Agent 把红色 run 误报为绿色。因此规范要求改用无管道的 JSON 轮询：

gh run view 1234567890 --json status,conclusion
# 期望最终得到 {"conclusion":"success","status":"completed"}

这与 npm-publish.yml 中"Verify published version" 步骤的风格一致——用显式 for 循环轮询 npm view 并比较字符串，而不是依赖任何管道输出。

3.3 用 gitHead 把 npm 包钉到具体 commit

技能要求验证 npm 状态时用：

npm view pake-cli@<version> version gitHead dist.tarball --json

要点有二：

1. gitHead 是"发布包 ↔ commit"的锚点。Pake 的 CLI 以 npm 包 pake-cli 发布（package.json 中 name 为 pake-cli，bin.pake 指向 dist/cli.js），gitHead 记录了打包时所在的 commit SHA，能直接回答"这个版本是否包含我正在审查的那个修复"；
2. latest 指针必须单独查。npm view pake-cli version（不带版本号）返回的是 latest dist-tag 指向的版本，它可能指向另一个 commit——也就是说，"某个版本已发布"与"latest 已切到该版本"是两个独立事实。

这条事实与仓库的发布脚本呼应：npm-publish.yml 在 npm publish 之后专门有一个轮询步骤（第 109-122 行），最多 12 次、每次 10 秒地执行 npm view pake-cli@${VERSION} version，直到 registry 真正可见该版本才宣布成功——正是"用 npm view 验证发布终态"这一规范的流水线内建实现。

3.4 PR 行内评论的查询位置

Inline PR review comments live at gh api repos/tw93/Pake/pulls/<n>/comments; gh pr view does not show them.

gh pr view 只展示 PR 主体与元数据，行内评审意见（review comments）不会出现在其中。要读取逐行评论，需要直接打 REST API：

gh api repos/tw93/Pake/pulls/123/comments

这条事实的意义在于：Agent 若基于 gh pr view 的输出判断"这个 PR 没有讨论"，会漏掉全部行内评审，从而给出错误的合并/回复决策。

3.5 App Release 的真相来源是 release assets，不是 workflow 名

App-release truth is gh release view <tag> --json assets (asset count/state), not workflow names or source state.

Pake 的应用发布产物（各平台安装包）最终挂在 GitHub Release 的 assets 上（release.yml 的 create-release job 负责建 Release，build-popular-apps 负责产出资产）。因此判断"V3.15.7 发布完成没有"的唯一可靠方式是：

gh release view V3.15.7 --json assets

检查资产的数量与上传状态，而不是看某条名为 "Release" 的 workflow 是否绿、或源码里版本号是否已改。workflow 绿了只说明构建步骤执行完，资产可能还在上传中甚至缺失。

四、Safety Rules：五条写操作约束

技能的安全规则是整个文档的操作纪律核心，逐条解读如下。

4.1 先出草稿，获批后才可写；批准不可续期

ALWAYS 在调用任何写操作（gh issue comment、gh pr comment、gh pr merge、gh issue close、gh release create 等）之前，先起草回复内容并展示给用户审批。一次批准不延伸到后续任何评论——第 2 条批过不代表第 3 条可以自动发送。这条规则把 Agent 的每个写动作都变成"人签一次、Agent 执行一次"的模式，防止批量误操作。

4.2 无明确请求，绝不合并/关闭/修改

NEVER merge、close 或 modify without explicit user request。即使用户的长期意图看起来是"清理 issue"，也不能把推断当指令。

4.3 回复语言跟随 issue/PR 作者

回复 issue 或 PR 之前，先读正文确认作者使用的语言，回复时与之保持一致。技能特别强调"这针对作者，不是针对线程里的任意评论者"——避免被无关评论者的语言带偏。

4.4 宣布"修复已发布"前，先核验产物

在回复"CLI 修复已发布"之前，必须用 npm view pake-cli@<version> version gitHead dist.tarball --json 确认该版本的 gitHead 确实包含这个修复，并单独用 npm view pake-cli version 检查 latest 指针。应用类发布则用 gh release view <tag> --json assets 核对资产。这条规则与第 3.3 节的 gitHead 机制是同一套证据链的两面：先证明 commit 对了，再证明版本可见了。

与之配套的还有仓库内置的发布前自检脚本 check-release-version.mjs：它在 CI 中核对 tag（Vx.y.z）与 package.json、src-tauri/Cargo.toml、src-tauri/Cargo.lock、src-tauri/tauri.conf.json 以及 dist/cli.js 内置版本号五处是否一致，并校验 repository.url 与 npm files 白名单。发布链路中"版本号五处一致"是前置门禁，而 npm view gitHead 是发布后的独立复核，两者共同构成完整的版本证据链。

4.5 发布后关 issue，先确认目标、再带升级命令

在 release 后关闭 issue 前，先用：

gh issue view <id> --json number,title,state,author,url

确认要关的确实是那个 issue，且关闭评论里必须包含具体版本号或升级命令（例如 npm i -g pake-cli@3.15.7），让报告者可以立即验证。

五、完整工作流串讲：一次"修复验证 + 发布关闭"的端到端操作

把上述规则组合起来，Pake 场景下一次典型的 Agent 运维操作如下：

# 1. 查活状态：PR 是否已合并、质检 run 是否成功
gh run view <run-id> --json status,conclusion

# 2. 核验 npm 侧：版本可见、gitHead 含修复、latest 指针
npm view pake-cli@3.15.7 version gitHead dist.tarball --json
npm view pake-cli version

# 3. 核验 App Release 资产（若涉及应用发布）
gh release view V3.15.7 --json assets

# 4. 读取行内评审评论（如需回应评审）
gh api repos/tw93/Pake/pulls/456/comments

# 5. 起草回复（先展示给用户，含具体版本/升级命令），获批后执行
gh issue comment <id> --body "<draft>"
gh issue close <id> --comment "Fixed in pake-cli@3.15.7, upgrade: npm i -g pake-cli@3.15.7"

每一步都对应技能中的一条事实或安全规则：查询走 --json 轮询（3.2）、npm 侧双查（3.3/4.4）、资产为准（3.5）、行内评论走 API（3.4）、写操作先获批且评论带版本（4.1/4.5）。

六、适用前提与限制

• 本技能假设操作者已安装并登录 gh CLI（gh auth login），具备对目标仓库的读权限，写操作还依赖对应的 push/triage 权限；
• 仓库名为 tw93/Pake，所有 gh api repos/tw93/Pake/... 形式的命令在该前提下成立；fork 场景需替换为自己的 owner/repo；
• 版本号以当前仓库 package.json 中的 3.15.7 为准，文中出现的版本仅为示例；
• 技能明确不覆盖代码评审与 release 构建本身的实现细节——构建逻辑应直接阅读 release.yml、single-app.yaml 等 workflow 源码；
• npm view 相关命令依赖 npm registry 的元数据，gitHead 字段对通过 Trusted Publishing（无 token、OIDC 鉴权）发布的包同样存在，因为 npm 在服务端从发布元数据中捕获该字段。

七、小结

github-ops 技能 用不到 40 行文本，把"Agent 如何安全操作 GitHub"收敛为三层：一条 Golden Rule（先查活状态）、五条项目事实（workflow 版图、CI 轮询方式、gitHead 锚定、行内评论位置、release 资产真相）、五条安全规则（先批后写、无请求不修改、跟随作者语言、发布前核验、关闭前确认目标）。它与 npm-publish.yml 的发布后轮询、check-release-version.mjs 的五处版本一致性门禁互为表里，共同保证 Pake 的每次 issue 回复、PR 交互和版本发布都有可复核的命令级证据。这套模式——状态必活查、发布必验锚、写操作必审批——可以直接移植到其他项目的 Agent 运维技能中。