pikasTech-unidesk/.agents/skills/unidesk-gh/SKILL.md

name, description

name	description
unidesk-gh	UniDesk GitHub CLI - 通过 `bun scripts/cli.ts gh ...` 管理 GitHub issue/PR，不依赖原生 `gh` binary。用户提到 gh、GitHub issue、GitHub PR、创建 issue、评论 issue、合并 PR、preflight、看板操作时使用。

UniDesk GitHub CLI

GitHub issue/PR 正式读写必须走 bun scripts/cli.ts gh ... 或 trans gh:/... apply-patch，不依赖原生 gh binary，不手写 GitHub API。

高频规则

• Issue/PR 正文、评论、关闭/重开、PR 描述和 merge closeout 默认中文。
• 需要理解、拆解、执行或关闭 GitHub issue 时，必须阅读正文全文：
  • 人工完整正文首选 trans gh:/owner/repo/issue/<number> cat；定点检索使用同一路由的 rg <pattern>。
  • PR 人工完整正文对应使用 trans gh:/owner/repo/pr/<number> cat 或 rg <pattern>。
  • 默认 gh issue/pr view 只承担有界元数据摘要和 Next 引导，不创建或要求展开 dump。
  • 不能只凭 compact summary、body preview、body SHA 或截断摘要下结论。
• 新 issue 正文必须包含 目标合并分支: <repo branch/lane>；不需要合并时写 目标合并分支: 不适用。
• 大计划、后续阶段和独立改进方向创建新 issue；已有 issue 评论只写短进展、证据、阻塞和链接。
• 规划型、多阶段、架构/API/平台运维类 issue 第一阶段必须 P0 SPEC 先行；细则见 references/issues.md。
• P0 SPEC 先行 段不得写入硬编码阈值、采样周期、重试次数、并发数等可调参数；必须写明这些参数由指定 YAML/source-of-truth 控制，issue 只列配置路径、字段族和验收读取方式。
• gh 默认输出是 k8s 风格 text/table/summary/Next/Disclosure；脚本消费或全量排障必须显式用 --json、--full 或 --raw。
• gh auth status --repo owner/name 分别披露仓库 read、基于 git push --dry-run 的非变更 write 能力和 PR merge eligibility，保持 writesRemote=false、mutation=false 与 valuesPrinted=false；merge eligibility 只覆盖 token 与仓权限，分支保护、检查和 PR 状态仍由 guarded merge 判定。
• gh issue view / gh pr view 的 --json body,...、--full 和 --raw 只用于显式机器结构化披露；请求正文时只在 .data.issue.body / .data.pullRequest.body 出现一次。
• 多行正文使用 quoted heredoc：
  • 正文使用 --body-stdin <<'EOF'；issue close/reopen 生命周期评论只用 --comment-stdin <<'EOF'。
  • 单次正文或 patch 必须直接从 heredoc 进入 stdin，禁止先写 /tmp 或工作区临时文件再用 < file 转交。
  • 只有需要复用或正式保留的文件才使用 --body-file。
  • 不要把 Markdown 塞进 shell 参数。
• gh pr create 默认 Next 只给有界 pr view、pr review-plan、pr preflight 和 closeout status 下钻；不得默认提示 preflight --full|--raw、手工 CI/CD、mirror sync、PipelineRun 或 Argo refresh。
• PR review 先用 review-plan 建立文件索引，只对需要审查的文件执行 pr diff --file，不得机械下钻每个文件。
• 发现整个 PR 的授权目标、架构方向、data flow 或 source of truth 错误时，禁止在错误 PR 上继续补丁：
  • 未合并 PR 通过受控入口关闭，停止旧 writer，并从最新目标分支新建 PR；
  • 已合并 PR 先用独立 PR 精确 revert 原 PR，回滚合并后再开始正确实现；
  • 回滚 PR 与正确实现 PR 必须分离，完整流程见 references/pull-requests.md。
• PR merge 只走 guarded gh pr merge；它内建 readiness/preflight，普通已审 PR 不先机械执行独立 pr preflight。主代理按 $unidesk-subagent 完成 review 和 merge 授权判断后执行；只有确认 ancestry 可丢弃时才显式 --squash。
• gh pr merge 的远端 head branch 生命周期：
  • 默认保留远端和本地 head branch 状态；
  • 只有确认 head 是可删除的临时分支时才显式传 --delete-branch；
  • 显式删除同时清理 Git 已登记、分支精确匹配、非主 worktree 且状态干净的本地 worktree；
  • --keep-branch 仅作为兼容的显式声明。
• 功能和 skill 在 merge 前进入同一个 PR；TaskTree ExecutionReport 不作为仓库文件提交。遗留 MDTODO 按 $unidesk-tasktree 迁移，禁止仅为补写 merge 事实再开文档 PR。
• 成功 merge 后默认摘要已披露 mergeCommit 和 mergedAt，不再机械执行 pr view。只有输出缺字段、merge 后出现新运行证据，或需要定点排障时才继续查询；只有用户明确要求把 merge 后新证据写回 Git 时，才创建第二个 closeout PR。

常用入口

bun scripts/cli.ts gh auth status --repo pikasTech/unidesk
bun scripts/cli.ts gh issue list --repo pikasTech/unidesk --state open --limit 30
bun scripts/cli.ts gh issue view <number> --repo pikasTech/unidesk
trans gh:/pikasTech/unidesk/issue/<number> cat
trans gh:/pikasTech/unidesk/issue/<number> rg <pattern>
bun scripts/cli.ts gh issue comments <number> --repo pikasTech/unidesk --limit 8
bun scripts/cli.ts gh issue create --repo pikasTech/unidesk --title "标题" --body-stdin
bun scripts/cli.ts gh issue comment create <number> --repo pikasTech/unidesk --body-stdin
bun scripts/cli.ts gh pr list --repo pikasTech/unidesk --state all --limit 10
bun scripts/cli.ts gh run list --repo owner/name --limit 10
bun scripts/cli.ts gh run view <run-id> --repo owner/name
bun scripts/cli.ts gh run logs <run-id> --job <job-id> --repo owner/name
bun scripts/cli.ts gh run benchmark --repo owner/name --url https://owner.github.io/repo/dev/bench/ --limit 10
trans gh:/pikasTech/unidesk/pr/<number> cat
trans gh:/pikasTech/unidesk/pr/<number> rg <pattern>
bun scripts/cli.ts gh pr review-plan <number> --repo pikasTech/unidesk
bun scripts/cli.ts gh pr diff <number> --repo pikasTech/unidesk --file path/to/file [--hunk 1]
bun scripts/cli.ts gh pr create --repo pikasTech/unidesk --title "标题" --body-stdin --base master --head <branch>
bun scripts/cli.ts gh pr ready <number> --repo pikasTech/unidesk [--dry-run]
bun scripts/cli.ts gh pr preflight <number> --repo pikasTech/unidesk
bun scripts/cli.ts gh pr merge <number> --repo pikasTech/unidesk --merge --delete-branch

• gh run benchmark 读取 github-action-benchmark 发布到 GitHub Pages 的 data.js：
  • --url 可以传页面目录或 data.js；
  • 默认输出有界历史和最新测量；
  • --commit <sha-prefix> --raw 返回筛选后的结构化 entries 与 measurements；
  • 不解析 job log，也不默认输出完整导出文件。

机器结构化入口必须显式请求：

bun scripts/cli.ts gh issue view <number> --repo pikasTech/unidesk --json body,title,state
bun scripts/cli.ts gh pr view <number> --repo pikasTech/unidesk --json body,title,state,head,base

Issue CRUD/comment/patch/stale-close/scan-escape 和看板命令见 references/issues.md；PR files/review-plan/diff/preflight/merge 见 references/pull-requests.md；trans gh: 虚拟文件系统见 references/trans-gh.md。

何时读取 reference

• 需要具体 issue/comment 命令参数、--json 字段、body guard 或看板命令：读 references/issues.md。
• 需要 PR bounded patch/index/drill-down、closeout、preflight、merge 或 ancestry/squash 判断：读 references/pull-requests.md。
• 需要局部修补正文或评论：读 references/trans-gh.md。