---
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

UniDesk 受控 GitHub 操作入口，底层 issue/PR REST 读写走 `bun scripts/cli.ts gh <subcommand>`，不依赖原生 `gh` binary，不手写 `curl`/GraphQL。Issue/PR 正文局部修补的人工首选入口是 `trans gh:/owner/repo/issue/<number> apply-patch` 或 `trans gh:/owner/repo/pr/<number> apply-patch`，底层 `gh issue patch` 只作为受控底座或兼容入口。

**固定入口前缀**: `cd /root/unidesk && bun scripts/cli.ts gh ...`

## 实现边界

GitHub 受控入口的长期架构权威是 `project-management/PJ2026-01/specs/PJ2026-010606-github-controlled-entry.md`。`scripts/src/gh.ts` 只保留兼容 re-export；新增或修改 GitHub 子命令必须落到 `scripts/src/gh/` 下对应职责模块（client/options/refs/body/issue/pr/board/attachments/escape-scan/help/index 等），不得把业务实现重新堆回根入口。

拆分后的 gh 模块文件头应保留 `SPEC: PJ2026-010606 GitHub入口 <实现引用版本>` 追溯，单个模块超过 3000 行时继续拆分。PR closeout 除常规 smoke 外，应覆盖至少一条 `trans gh:/... apply-patch --dry-run` 或等价写回路径，证明虚拟正文仍走同一 guard。

CLI 自检使用 `bun scripts/cli.ts check --syntax-only`、针对被改模块的 `bun --check <file>` 和必要 `gh ... --dry-run`/read smoke。不要把 `bun --check scripts/cli.ts` 当作低噪声自检；它可能执行根 help 并触发 dump。需要 scripts 类型检查时走 `bun scripts/cli.ts check --scripts-typecheck ...`，让 CLI 输出 heartbeat 和 bounded timeout 结果。

## 写入语言

- Issue/PR 的正式写入一律使用中文，包括标题、正文、评论、关闭/重开说明、PR 描述、PR 评论和 merge closeout 说明。
- 命令、路径、trace/session/job id、API path、代码标识符、英文专有名词、原始日志摘录和外部错误原文可以保留原样；解释性文字、结论、风险、计划和验收说明必须中文。
- 除非用户明确要求外文，不要用英文撰写 issue/PR closeout、进展评论或阻塞说明。
- Markdown 正文、issue/PR 正文和评论里的 issue/PR 引用必须写成 `[#<number>](https://github.com/<owner>/<repo>/issues/<number>)` 或 `[#<number>](https://github.com/<owner>/<repo>/pull/<number>)`，显示短号、链接目标保留完整 URL；不要显示裸长链接、裸井号编号或 `owner/repo` 加井号编号。`owner/repo#number` 只允许作为 CLI 命令参数 shorthand。

---

## Issue 目标分支 / Lane

- 创建 issue、补充正式 issue 评论、关闭/重开说明或把 trace 发现的问题登记成 issue 时，正文必须显式写明目标合并分支或运行 lane。
- 推荐固定字段：`目标合并分支: <repo> <branch/lane>`；例如 `目标合并分支: HWLAB v0.2`、`目标合并分支: AgentRun v0.1`、`目标合并分支: UniDesk master`。
- 如果该 issue 只记录外部依赖、运维观察或不需要代码合并，仍必须写 `目标合并分支: 不适用`，并用一句话说明原因。
- 看到用户或上下文已明确目标 lane 时必须照写；不明确时按目标仓库长期 source truth 选择：HWLAB 按当前 runtime lane（如 `v0.2`/`v0.3`）、AgentRun 默认 `v0.1`、UniDesk 默认 `master`。不能确定时写 `目标合并分支: 待确认` 并说明待确认点，不能省略字段。

---

## 计划与评论分流

- 大计划、改进计划、后续工作拆解、独立验收标准或会形成多阶段执行的内容，必须创建新的 issue 承载；不要在已有 issue 评论区开长计划。
- 既有 issue 评论只写短进展、关键证据、当前结论、阻塞和新 issue 链接；评论用于串联时间线，不承载新的大范围计划正文。
- 如果调查中发现了独立改进方向，应先用 `gh issue create --body-stdin` 创建新 issue，标题和正文写清目标合并分支/lane、背景、计划、验收标准；然后在原 issue 评论中用 1-3 句说明已拆出，并链接到新 issue。
- 只有用户明确要求把计划写回当前 issue 正文，或当前 issue 本身就是唯一的专题计划 issue，才允许更新当前 issue 正文；即便如此，评论仍保持短小，不复制整篇计划。

## 多阶段 Issue 与 SPEC-First

- 形成多阶段实施、跨模块架构、新能力、长期 API/数据模型、平台运维能力或用户可见工作流的规划型 issue 时，第一阶段必须是 `P0 SPEC 先行`，并按 `$unidesk-oa` 的 SPEC 管理模式处理。
- `P0 SPEC 先行` 必须在 issue 正文列出 SPEC 编号、SPEC 文档路径、上级规格、关联规格、实现引用版本、目标架构图/数据流图/关键时序图完成项，以及源码文件头部 `SPEC: <编号> <短名> <实现引用版本>` 标注规则。
- issue 正文只能承载执行计划、阶段状态和证据索引，不能替代 `project-management/PJ2026-01/specs/` 中的长期 SPEC 正文。若稳定需求、数据流、接口或验收口径变化，先更新 SPEC，再更新 issue 阶段计划。
- P0 未完成前，不得把代码实现、部署、CI/CD、测试补充或验收收口列为已可执行阶段；这些只能作为后续 P1+ 阶段。

---

## 认证探测

```bash
bun scripts/cli.ts gh auth status [--repo owner/name]
```

探测 token 来源（`GH_TOKEN`/`GITHUB_TOKEN`/`gh auth token`）、GitHub REST egress、repo 可见性、issue 可读性。不打印 token。

## 聚焦帮助

具体子命令用法优先直接查 scoped help，不要先打开顶层长 help 再人工搜索：

```bash
bun scripts/cli.ts gh issue close --help
bun scripts/cli.ts gh issue comment --help
bun scripts/cli.ts gh pr merge --help
```

`gh <subcommand> --help`、`gh <subcommand> -h` 和 `gh <subcommand> help` 只输出匹配命令或命令组的 bounded JSON，包括相关 usage、短 notes 和完整 help 入口；`gh --help` / `gh help` 才输出完整顶层命令索引。

---

## Issue 命令

### 列表

```bash
bun scripts/cli.ts gh issue list [owner/repo] \
  [--state open|closed|all] [--limit N] [--search text] [--title-prefix text] \
  [--label label[,label...]] [--repo owner/name] \
  [--json number,title,state,url,updatedAt,createdAt,author,labels] [--raw|--full]
```

默认 `state=open`、`limit=30`。`owner/repo` 位置参数等价 `--repo`。`--search` 走 GitHub Search API 做查重。`--title-prefix` 在当前有界结果内按 issue 标题前缀做本地过滤，输出 `titleFilter` 的输入/输出/过滤数量，适合 `[FEEDBACK]` 去重：

```bash
bun scripts/cli.ts gh issue list --repo pikasTech/unidesk --state all \
  --search "[FEEDBACK]" --title-prefix "[FEEDBACK]" \
  --json number,title,state,url
```

### 查看

```bash
bun scripts/cli.ts gh issue view <number|url|owner/repo#number> \
  [--repo owner/name] [--json body,title,state,closed,closedAt,comments,commentCount] [--raw|--full]
```

`read` 是兼容别名。支持 `owner/repo#number` shorthand（如 `pikasTech/HWLAB#1024`）。
人工读取 issue/PR 正文优先走 `trans gh:/owner/repo/issue/<number> cat|rg` 或 `trans gh:/owner/repo/pr/<number> cat|rg`；`gh issue view/read` 主要保留为结构化 JSON 底座、metadata 读取和兼容入口。
`--json comments` 默认只返回 comment id、URL、作者、时间、正文字符数、body SHA 和短 preview；`--full` 仍保持评论列表有界，只有 `--raw` 会显式展开所有评论正文。读取单条完整 comment body 使用 `gh issue comment view <commentId> --full`，显式 `--json` 路径的 comments 位于 `.data.json.comments`，不要依赖顶层重复 comments。

### 创建

```bash
bun scripts/cli.ts gh issue create \
  --repo owner/name \
  --title "标题" \
  --label "bug,v0.2" \
  --body-stdin <<'EOF'
目标合并分支: HWLAB v0.2

正文（Markdown，支持换行、反引号、表格）
EOF
```

`--body-stdin` 是 heredoc/stdin 第一等入口。`--dry-run` 只输出计划不写 GitHub。

### 更新正文

```bash
# 替换正文
bun scripts/cli.ts gh issue update <number> --repo owner/name \
  --mode replace --body-stdin <<'EOF'
新正文
EOF

# 追加正文
bun scripts/cli.ts gh issue update <number> --repo owner/name \
  --mode append --body-stdin <<'EOF'
追加内容
EOF
```

`edit` 是 `update --mode replace` 的兼容别名。正式写入默认先读当前 issue 做 body guard。

### 局部修补正文（优先走 `trans gh:`）

```bash
# Issue 正文：route 未写 /1 时默认一楼正文
trans gh:/owner/name/issue/<number> apply-patch <<'PATCH'
*** Begin Patch
*** Update File: body.md
@@
-old text
+new text
*** End Patch
PATCH

# PR 正文同样使用 body.md
trans gh:/owner/name/pr/<number> apply-patch <<'PATCH'
*** Begin Patch
*** Update File: body.md
@@
-old text
+new text
*** End Patch
PATCH
```

GitHub issue/PR 正文局部修补必须优先走 `trans gh:/owner/repo/issue/<number> apply-patch` 或 `trans gh:/owner/repo/pr/<number> apply-patch`；虚拟文件固定是 `body.md`，`apply_patch` 和 `patch-apply` 仅作为兼容别名。底层 `bun scripts/cli.ts gh issue patch ... --body-patch-stdin` 是受控写回底座或兼容入口，不作为人工首选。`trans gh:` 会先读取当前正文，把 Codex `apply_patch` envelope 应用到 `body.md`，再通过现有 `gh issue/pr update` guard 写回；普通小补丁不需要固定先跑 `--dry-run`，高风险正文预览时才加 `--dry-run`。

### 评论

```bash
# 创建评论
bun scripts/cli.ts gh issue comment create <number|owner/repo#number> \
  --repo owner/name --body-stdin <<'EOF'
评论正文
EOF

# 读取单条评论
bun scripts/cli.ts gh issue comment view <commentId> \
  --repo owner/name [--full|--raw]

# 原地修正评论
bun scripts/cli.ts gh issue comment update <commentId> \
  --repo owner/name --body-stdin <<'EOF'
新的评论正文
EOF

# 局部修补评论
bun scripts/cli.ts gh issue comment patch <commentId> \
  --repo owner/name --body-patch-stdin <<'PATCH'
*** Begin Patch
*** Update File: comment.md
@@
-old text
+new text
*** End Patch
PATCH

# 删除评论
bun scripts/cli.ts gh issue comment delete <commentId>
```

`view` 默认返回 comment id、URL、作者、时间、正文字符数、body SHA 和短 preview；`--full` 只展开这一条 comment body。`edit` 是 `comment update` 的兼容别名。`--body <short-text>` 仅适合短单行。日常修正文案优先用 `patch` 或 `update/edit` 保留评论 ID 和时间线；`delete` 只用于确实需要删除的评论。`comment patch` 会先读取 comment id 对应的当前正文，把 envelope 应用到虚拟文件 `comment.md`，再 PATCH 单条评论；上下文不匹配时失败且不写入。

评论区不要写新的大计划。若评论草稿已经包含多阶段计划、改进清单或验收标准，改为创建新 issue，并在评论中只留下新 issue 链接和短结论。

### 关闭/重开

```bash
bun scripts/cli.ts gh issue close <number|owner/repo#number> \
  --repo owner/name [--comment "关闭原因"]

bun scripts/cli.ts gh issue reopen <number|owner/repo#number> \
  --repo owner/name [--comment "重开原因"]
```

附长证据时先用 `comment create` 写证据评论，再用 `close --comment <短引用>` 关闭。不支持 `delete`（走 `close`）。

### 批量过期关闭

```bash
bun scripts/cli.ts gh issue stale-close \
  --repo owner/name [--inactive-hours 48] [--limit N] \
  [--label label] [--dry-run]
```

关闭 `updatedAt < observedAt - inactiveHours` 的 open issue。先 `--dry-run` 观察，再正式执行。

### 转义扫描

```bash
bun scripts/cli.ts gh issue scan-escape \
  --repo owner/name [--limit N] [--dry-run]
```

只读扫描 issue 正文/评论中的字面量 `\n`、`\t`、ANSI escape 等污染。

---

## PR 命令

### 列表

```bash
bun scripts/cli.ts gh pr list [owner/repo] \
  [--state open|closed|all] [--json ...] [--raw|--full]
```

### 查看

```bash
bun scripts/cli.ts gh pr view <number|url|owner/repo#number> \
  [--repo owner/name] \
  [--json body,title,state,stateDetail,headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup] \
  [--raw|--full]
```

`stateDetail` 归一化为 `open|closed|merged`。`mergeable`/`mergeStateStatus`/`statusCheckRollup` 走 GraphQL。

### 文件变更

```bash
bun scripts/cli.ts gh pr files <number> [--repo owner/name] [--limit N]
```

返回 changed files 统计，不输出 raw diff。`gh pr diff <number> --stat` 是兼容别名。

### 收口预检

```bash
bun scripts/cli.ts gh pr preflight <number|owner/repo#number> \
  [--repo owner/name] [--full|--raw]
```

`preflight`/`closeout` 是别名。只读检查 state/draft/conflict/mergeable/statusCheck，不写 GitHub。默认只给 status check 计数与失败预览。

### 创建

```bash
bun scripts/cli.ts gh pr create \
  --repo owner/name \
  --title "标题" \
  --body-stdin --base master --head <branch> \
  [--draft] [--dry-run] <<'EOF'
PR 正文
EOF
```

`pr create` 成功后的 Next 默认提示使用 `gh pr merge ... --merge --delete-branch`。只有确认不需要保留 ancestry 或 merge parent history 时，才显式改用 `--squash`。

### 合并

```bash
bun scripts/cli.ts gh pr merge <number> \
  [--repo owner/name] [--merge|--squash|--rebase] \
  [--delete-branch] [--dry-run]
```

一键 guarded merge：`gh pr merge` 自己读取 closeout metadata、mergeability、mergeStateStatus 和 status checks，不要求用户先跑 `gh pr preflight`。`preflight`/`closeout` 只作为只读诊断入口保留。

当 GitHub GraphQL 返回 `mergeable=UNKNOWN/null`、`mergeStateStatus=UNKNOWN/null` 或 status rollup unknown 且没有明确 blockers 时，`gh pr merge` 会按 `config/unidesk-cli.yaml` 的 `github.prMerge.unknownRetry` 做指数退避重试，并在默认表格 `RETRY` 列显示 `1/5`、`2/5` 等尝试次数。重试耗尽仍 unknown 时，命令自动停止且不合并；冲突、draft、失败检查、pending check 等不可合并状态不会无意义重试。已 merged 返回 `alreadyMerged=true`。

### 开发任务收口

完成开发任务后必须完整收口：创建 PR、通过受控 `gh pr merge` 合并 PR、删除远程任务分支、删除本地任务 worktree，并把主 worktree 快进到最新 `master`。远程分支优先通过 `gh pr merge ... --delete-branch` 删除；若合并后远端分支仍存在，再显式 `git push origin --delete <branch>`。

删除本地 worktree 前先确认工作区 clean，且任务变更已经进入 `origin/master`；squash merge 场景下不能只看本地分支是否是 `origin/master` 祖先，还要用 PR merged 状态、`git cherry` 等价补丁或关键文件 diff 确认语义已吸收。确认后执行 `git worktree remove .worktree/<task>`；如本地任务分支仅用于该 worktree 且已语义合入，可同步删除本地分支。

最后在主 worktree 执行 `git fetch origin master` 和 `git pull --ff-only origin master`，让主 worktree 回到最新 `master`。如果主 worktree 存在并行脏改、非 `master` 分支或其他原因导致不能安全 fast-forward，禁止 `reset`、`stash`、`checkout --` 或清理他人改动；改用干净 `origin/master` worktree 继续后续工具命令，并在最终回复中明确说明主 worktree 未更新的原因。

### 编辑 / 评论 / 关闭 / 重开

```bash
bun scripts/cli.ts gh pr update <number> --mode replace|append --body-stdin [--title ...]
bun scripts/cli.ts gh pr comment create <number> --body-stdin
bun scripts/cli.ts gh pr comment update <commentId> --body-stdin
bun scripts/cli.ts gh pr comment edit <commentId> --body-stdin
bun scripts/cli.ts gh pr comment delete <commentId>
bun scripts/cli.ts gh pr close <number> [--comment ...]
bun scripts/cli.ts gh pr reopen <number> [--comment ...]
```

`pr comment edit` 是 `pr comment update` 的兼容别名。与 issue 对应命令行为一致；PR 评论也是 GitHub issue comment，更新目标使用 commentId。

---

## 虚拟文件系统 (`trans gh:`)

```bash
# 列出 repo
trans gh:/pikasTech/HWLAB ls

# 列出 PR / Issue
trans gh:/pikasTech/HWLAB/pr ls [--state open|closed|all] [--limit N] [--full]
trans gh:/pikasTech/HWLAB/issue ls [--state open|closed|all] [--limit N] [--search TEXT] [--label L] [--full]

# 读取 / 检索正文
trans gh:/pikasTech/HWLAB/issue/1236 cat
trans gh:/pikasTech/HWLAB/issue/1236 rg 'API_KEY|YAML-first'

# 查看单个条目
trans gh:/pikasTech/HWLAB/pr/507 ls
trans gh:/pikasTech/HWLAB/505/1 cat

# apply-patch 写回正文（走 gh issue/pr update）
trans gh:/pikasTech/HWLAB/pr/507 apply-patch <<'PATCH'
*** Begin Patch
*** Update File: body.md
@@
 old line
-old line
+new line
 more context
*** End Patch
PATCH
```

正文一楼映射为 `body.md`；route 未写 `/1` 时默认一楼正文。`issue ls --search/--state` 用于替代常见 `bun scripts/cli.ts gh issue list ... --search/--state` 读取；单条正文优先用 `cat` 或 `rg`，不要为了看 body 再走 `gh issue view --json body --full`。写回走 `gh issue/pr update` 的 guard 规则。`apply-patch` 是首选 operation，`apply_patch` 与 `patch-apply` 只作为兼容别名；普通小补丁在已读取上下文后可以直接 apply，`--dry-run` 只作为高风险正文的可选预览。`rm` 对正文结构化拒绝。

---

## 看板命令 ([#20](https://github.com/pikasTech/unidesk/issues/20) 总看板)

```bash
# 结构审计
bun scripts/cli.ts gh issue board-audit \
  --repo pikasTech/unidesk --board-issue 20 [--dry-run]

# 行列表
bun scripts/cli.ts gh issue board-row list \
  --board-issue 20 [--state open|closed|all]

# 行查看
bun scripts/cli.ts gh issue board-row get <issueNumber> --board-issue 20

# 行更新（单字段）
bun scripts/cli.ts gh issue board-row update <issueNumber> \
  --board-issue 20 \
  --field progress|status|validation|branch|tasks|focus \
  --value <text> \
  [--expect-body-sha <sha>|--expect-updated-at <ts>]

# 行新增/插入（upsert）
bun scripts/cli.ts gh issue board-row upsert <issueNumber> \
  --board-issue 20 --section open|closed \
  --branch <branch> --tasks <task> --summary <text> \
  --focus <text> --validation <text> --progress <text> \
  [--expect-body-sha <sha>|--expect-updated-at <ts>]

# 行移动 / 删除
bun scripts/cli.ts gh issue board-row move <issueNumber> \
  --board-issue 20 --to open|closed [--status OPEN|CLOSED]
bun scripts/cli.ts gh issue board-row delete <issueNumber> \
  --board-issue 20
```

写操作默认 dry-run，正式 PATCH 必须带 `--expect-body-sha` 或 `--expect-updated-at`。

---

## 关键约定

### heredoc 优先

多行正文/评论一律用 `--body-stdin <<'EOF'`（quoted heredoc），不用 `--body` 内联长文本、不用临时文件、不用 `gh api -f body=...`：

```bash
bun scripts/cli.ts gh issue create --repo pikasTech/HWLAB \
  --title "标题" --body-stdin <<'EOF'
正文，支持 `code`、**bold**、表格等 Markdown
EOF
```

### owner/repo#number shorthand

所有接受 issue/PR number 的命令都支持：

```bash
bun scripts/cli.ts gh issue view pikasTech/HWLAB#1024
bun scripts/cli.ts gh pr preflight pikasTech/HWLAB#1020
bun scripts/cli.ts gh issue comment create pikasTech/HWLAB#1024 --body-stdin <<'EOF'
...
EOF
```

shorthand 与显式 `--repo` 冲突时结构化失败。

### 高风险写入预览

整篇 replace、批量 lifecycle、PR merge 或并发敏感正文写入可先 `--dry-run`；`trans gh:/... apply-patch` 的普通小补丁在已读取上下文后不需要固定 dry-run：

```bash
bun scripts/cli.ts gh issue update 20 --mode append --body-stdin --dry-run <<'EOF'
...
EOF
```

### debug 任务入口

```bash
bun scripts/cli.ts codex pr-preflight [--remote] [--push-dry-run ...] [--pr-create-dry-run ...] [--issue N] [--full|--raw]
```

用于 PR 型派单 admission，检查 scheduler auth、runner GH token、git worktree、GitHub egress 等。
