github-ops

1实现原理 · 为什么它能做到

全篇第一原则：交付被请求的 GitHub 状态，而不是一条看起来成功的命令——2xx 只证明 GitHub 接受了请求，不证明字段真的改了、邀请被接受、异步任务完成或业务结果达成。

SKILL.md 本体只是「硬契约 + 路由表」：按操作域把任务分派到 8 个 reference，并要求只读当前任务需要的那一份，避免一次性加载全部约 95KB 知识。

第 1 步先给请求分类（读-only / 具名状态变更 / 破坏性·公开·涉凭证·触发生产·对外沟通），分类决定授权范围与是否可以在写之前停下。

第 2 步在第一次写之前绑定身份、主机与目标：先验证活跃账号（--hostname HOST）再解析全限定目标，并对多 GitHub 实例强制显式 HOST。

第 3 步要求读 GitHub 托管态（而非过期的本地 ref 或记忆），并在有后果的写之前显式写出一份六行影响预览：Target / Current / Requested / Blast radius / Recovery / Readback。

第 4 步要求选「输入契约真的支持该变更」的接口，优先级固定为 gh 专用子命令 → 文档化 REST → GraphQL（仅 GraphQL 专用或需合并关联数据）→ 只有 UI 才有的设置；核心陷阱是「响应字段不等于可写字段」。

第 5 步是幂等纪律：能 pin 的都 pin（仓库/编号/分支/run ID/用户名/预期 SHA），非幂等写在超时或 5xx 后先读回再决定是否重发。

第 6 步用「不信任变更响应、也不信任缓存 ref」的新读取做验收，并给出按变更类型分行的验收证据表（PR 合并/分支删除/issue-评论-审查/仓库创建编辑可见性/协作者与团队权限/组织设置/2FA/workflow/secret）。

第 7 步收口为四种诚实状态之一：changed and verified / already satisfied / pending / failed-no-op or partial，并要求失败态附恢复与未决风险。

高危边界被单列成节：仓库创建必须显式 OWNER/REPO 与可见性、可见性变更需后果承认旗标、删除/转移/组织级权限/2FA/密钥轮换各走专属 reference。

与相邻 skill 划清边界：本地 Git 修复（脏工作区、bundle、丢失提交）归 git-safety-net，本 skill 只拥有 GitHub 托管状态。

高危操作按 reference 拆成专用流程：仓库转移的 REST 是异步操作，202 只是 pending，必须轮询新全限定名并重审协作者/团队/保护/Pages/secrets；删除保留交互式精确名称确认且明令不加 --yes。

组织级变更同样是专用流程：先区分 effective permission 的来源（仓库/团队/base permission/组织所有权/企业策略），再判 UI-only 字段，最后才谈写；2FA 强制被当作组织级访问变更而非勾选框。

issue 的创建/评论/转仓/关闭被显式定义为「外部动作」，执行前必须绑定确切仓库与内容；批量 issue 治理走冻结清单 + 逐条读回。

2核心能力

3外部依赖

4管控建议与判定依据

5第二遍独立确认

• [ok] external_deps 逐条反查调用点是否真实存在 — 10 条依赖全部在文件内定位到调用点：gh（SKILL.md 步骤 2 命令块与全篇）、git（pr_operations.md 的 'git rev-parse '<candidate>^{tree}'' 与远端分支退役小节的 '--force-with-lease="refs/heads/{branch/path}:$expected_sha"'）、jq（best_practices.md 的 'gh api rate_limit --jq ...' 与多处 '| jq'）、curl（workflow_operations.md 匿名回读两行）、unzip（'unzip -tq RUN_ID.zip'）、REST（api_reference.md 全篇 gh api repos/...）、GraphQL（'gh api graphql -f query='）、企业主机（best_practices.md 的 'gh api --hostname github.example.com user --jq '.login''）、webhook 目标（api_reference.md 的 config[url]=https://example.com/webhook）、文档链接（api_reference.md 末尾三条 https 链接）。无虚构条目；也未漏登记第三方包——全目录不存在 package.json / requirements.txt / go.mod / Gemfile 等依赖清单。
• [ok] 文件清单 glob + git ls-files 全量核对 — github-ops/ 下恰好 9 个文件：SKILL.md + references/{api_reference,best_practices,branch_protection,issue_operations,organization_access_and_settings,pr_operations,repository_operations,workflow_operations}.md；无 scripts/、无模板/数据文件、无隐藏文件、无 symlink；find 与 git ls-files 结果一致；目录内无 LICENSE（LICENSE 在仓库根，MIT，Copyright (c) 2025 daymade，与固定取值相符）。工作副本 HEAD = d5c4678cb5d4fd6acc9c922690df035dbd33d247，与 pin 一致。
• [ok] 指令中记载的 gh 子命令与 flag 真实性核验（本机 gh 2.100.0） — 对 41 组子命令/flag 跑 gh <cmd> --help 校验，缺失 0：含 --accept-visibility-change-consequences、--match-head-commit、--auto/--squash/--rebase、--paginate/--slurp/--input/-X/-f/-F/-i、--hostname、--show-token、repo create --source/--remote/--internal、secret/variable/run/workflow 全族、issue pin/unpin/transfer、pr ready --undo、pr edit --add-project、run rerun --failed/--debug、run download --name/--dir、config set、repo set-default。--json 字段名另用负控验证（'--json bogusfieldxyz' 报 'Unknown JSON field'），说明 gh 会先做客户端校验，本 skill 用到的 issue/pr/run/repo/workflow --json 字段集全部通过校验。
• [discrepancy] 安全结论反例①：是否有未登记的网络外发 — 发现两条第一遍未单独点名的外发路径，本稿已补登记：(a) curl 直连 api.github.com 的匿名回读（不是走 gh 的通道，用于运行历史清除验收）；(b) 创建 webhook 后仓库事件会持续外发到 config[url] 指定地址（示例为 example.com 占位，替换为真实 URL 后即形成长期数据出口）。其余外发（gh/git/文档链接）与第一遍一致。混淆载荷反查：base64/eval/xxd/加密串在目录内零命中。
• [ok] 安全结论反例②：凭证读取/泄露面 — grep 'token|TOKEN|secret|SECRET|show-token|GH_TOKEN|env|api_key' 的全部命中均为纪律条款或 API 字段名，无一处读取、打印、写盘或作为参数内联：'Never use `gh auth status --show-token`'、'never inline or echo the value'、'keep secrets out of command arguments.'、'token literal in a command, document, process argument, log, or committed environment file.'、'Never copy another environment's credential as a fallback.'、'Use only that host's existing authorized login; do not copy tokens,'。gh secret set 走隐藏交互提示或 stdin 重定向，并明确 'GitHub intentionally does not return the secret value.'。
• [discrepancy] 安全结论反例③：是否有未声明的破坏性/绕过行为 — 两处需在展示层点名的能力（非漏洞）：(a) workflow_operations.md 的 '## Purging Public Run History' 提供真实 DELETE（gh api -X DELETE 'repos/OWNER/REPO/actions/runs/RUN_ID' 与 deployment 删除），runs 不可恢复，文档要求先全量备份并匿名回读验收；(b) 同文件含 'gh secret delete SECRET_NAME'、gh variable delete、gh workflow disable 等可令生产流程停摆的操作。SKILL.md 的高危边界清单只列 '- Merges, branch deletions, repository creation/deletion/transfer/visibility changes,' 一行覆盖范围，未把「运行历史清除」纳入该清单（仅路由表以 purge 覆盖），属边界清单与 reference 能力的轻微不同步——用户需知晓删除历史同样不可逆。
• [ok] 实现原理是否夸大：description 声明 vs 实际文档能力 — description 列出的各域逐一有承载：PR（pr_operations.md）、issues（issue_operations.md）、Actions（workflow_operations.md）、repositories（repository_operations.md）、collaborators/teams/base permissions/2FA（organization_access_and_settings.md）、branch protection（branch_protection.md）、API automation 与 public/enterprise GitHub（api_reference.md + best_practices.md）、parallel or superseded PR convergence（pr_operations.md 收敛五步）、「write 返回成功但状态没变」（SKILL.md 第 4/6 步 + 组织设置的静默 no-op 节）、「某设置只能 CLI/REST/GraphQL/UI 哪种能改」（SKILL.md 第 4 步 + UI-only 小节）。七步契约标题在正文以 '### 1.'…'### 7.' 实际存在。反面检查：全文没有自动完成/保证成功式措辞，反而反复要求报 pending/failed/no-op，未夸大。
• [discrepancy] 内部一致性：小标题与内容、示例与边界清单是否自洽 — 一处小标题窄于内容：workflow_operations.md 的小节标题为 '### Managing Secrets (via API)'，其下同时给出 gh api repos/{owner}/{repo}/actions/secrets（API）与 gh secret set/list/delete（gh CLI 子命令）——命令本身可执行，仅标题措辞与命令族不完全对应。另一处见上一条（路由表 purge vs 高危边界清单）。其余抽检一致：可见性变更在 SKILL.md 与 repository_operations.md 用同一旗标与读回要求；2FA 在 SKILL.md 验收表与 organization_access_and_settings.md 的流程互相对应。

6结论