bifangknt gh-cli
Overview
以可复现、可审计的方式调用 gh。默认输出结构化数据，优先使用非交互命令，避免依赖浏览器或 TUI。
Workflow
- 确认认证与仓库上下文。
- 如果命令参数不确定，先运行
gh <subcommand> --help或gh help <topic>。 - 先生成“只读探测命令”，再生成“变更命令”。
- 变更命令明确影响范围（仓库、PR/Issue 编号、merge 策略、是否删除分支）。
- 执行后返回关键输出与下一步建议。
Operation Decision
- 用户只问“现状/列表/状态”：只执行只读命令（
list/view/status/api GET）。 - 用户要求“评论/审查/合并/触发工作流”：先只读确认对象存在与状态，再执行变更命令。
- 用户同时要“查询+修改”：拆成两段，先回显查询结果，再给修改命令并执行。
- 用户目标不完整（缺编号、缺仓库、缺 merge 方法）：先补齐参数，不直接变更。
- 用户要求“整体审查结论”（
approve/request-changes/comment）：使用gh pr review。 - 用户要求“按文件/按行评论”：使用
gh api repos/{owner}/{repo}/pulls/{num}/reviews或gh api repos/{owner}/{repo}/pulls/{num}/comments，不要把gh pr review当作行内评论接口。
Command Rules
- 默认使用非交互模式；不要依赖手动输入。
- 优先输出 JSON：使用
--json+--jq/-q精简结果。 - 需要批量查询时，优先
gh api --paginate。 - 需要复杂参数时，优先
gh api -f/-F或--input传文件。 gh pr diff不支持按文件路径直接过滤；按文件获取 patch 使用gh api repos/{owner}/{repo}/pulls/{num}/files --paginate再筛选。- 提交行内评论前，必须先查询
headRefOid，并保证请求里的commit_id与其一致；否则常见422。 - 构造复杂 JSON 时，优先内存对象后通过标准输入喂给
gh api --input -，避免在工作区落地临时文件。
Failure Handling
- 认证失败：先执行
gh auth status，返回失败原因并给出最小修复命令。 - 权限不足（repo/org/token scope）：明确缺失权限，不尝试重复写操作。
- 资源不存在（PR/Issue 编号错误）：先回显查询命令与空结果，再请求更正目标。
- 分支保护或检查未通过导致无法 merge：返回阻塞项（review/check/protection），并给出可执行下一步。
- 二次执行冲突（已 merge、已关闭、已评论）：识别幂等场景并停止重复变更。
Safety Checklist
执行任何写操作前，先确认：
- 目标仓库（
owner/repo）。 - 目标对象（PR/Issue 编号或 workflow 名称）。
- 操作类型（comment/review/merge/run 等）。
- 关键策略（merge 方法、是否
--delete-branch、是否--auto）。 - 若为行内评论：
headRefOid与commit_id一致。 - 预期结果（状态变化、评论内容、触发记录）。
缺任一关键项时，先补信息，再执行。
Output Format
统一按以下结构输出：
Plan: 本次要做的动作（1-2 行）。Commands: 实际执行的命令（先只读，后变更）。Result: 关键字段（如number、state、url、reviewDecision）。Next: 若失败或受阻，给最短可执行下一步。
Reference
按需读取参考文档，避免一次加载全部命令：
- 入口索引：
references/commands.md - 认证：
references/auth.md - 仓库上下文：
references/repo.md - PR：
references/pr.md - Issue：
references/issue.md - Workflow：
references/workflow.md - Run：
references/run.md - API：
references/api.md - 细粒度子命令：
references/commands.md列出的*-*.md文件（如pr-diff.md、run-watch.md）