---
name: unidesk-gh
description: 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](references/issues.md)。
- `P0 SPEC 先行` 段不得写入硬编码阈值、采样周期、重试次数、并发数等可调参数；必须写明这些参数由指定 YAML/source-of-truth 控制，issue 只列配置路径、字段族和验收读取方式。
- `gh` 默认输出是 k8s 风格 text/table/summary/Next/Disclosure；脚本消费或全量排障必须显式用 `--json`、`--full` 或 `--raw`。
- `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 merge 只走 guarded `gh pr merge`；主代理按 `$unidesk-subagent` 完成 review/preflight/merge 授权判断后再执行，不把“禁止默认 Next”理解成“PR 永远不能由主代理受控合并”；只有确认 ancestry 可丢弃时才显式 `--squash`。

## 常用入口

```bash
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 pr list --repo pikasTech/unidesk --state all --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
```

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

```bash
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](references/issues.md)；PR files/review-plan/diff/preflight/merge 见 [references/pull-requests.md](references/pull-requests.md)；`trans gh:` 虚拟文件系统见 [references/trans-gh.md](references/trans-gh.md)。

## 何时读取 reference

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