@@ -1,453 +0,0 @@
---
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: <编号> <短名> <实现引用版本>` 标注规则。
- `P0 SPEC 先行` 只能定义语义、状态机、接口字段、数据流、配置字段族和验收读取方式；不得把阈值、采样周期、重试次数、并发数、超时窗口等可调参数写成硬编码常量。此类参数必须引用指定 YAML/source-of-truth 路径控制，例如 `config/hwlab-node-lanes.yaml` 中目标 node/lane 的配置段。
- 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]` 去重：
默认 stdout 是有界表格和短摘要；`--json` 、`--full` 或 `--raw` 是显式结构化/全量披露入口。
``` 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` ）。
默认 stdout 是 issue 元数据表格、短摘要、body chars/SHA/preview 和 Next 命令，不输出完整 body。人工读取 issue/PR 正文优先走 `trans gh:/owner/repo/issue/<number> cat|rg` 或 `trans gh:/owner/repo/pr/<number> cat|rg` ；脚本消费或字段读取使用 `--json <fields>` ，全量排障才用 `--full` /`--raw` 。
Issue 理解、拆解、执行、调度子代理、PR review 归因或 closeout 前必须读完整正文；compact summary、body preview、body SHA、comment count 和 dump metadata 只能用于定位，不能作为需求理解依据。若 `gh issue view ... --json body|comments|--full|--raw` 触发 stdout dump wrapper，必须跟随 `data.dump.path` 读取完整 payload，或改用 `trans gh:/owner/repo/issue/<number> cat` 读取完整一楼正文。需要评论上下文时，继续读取完整 comments；默认 comments preview 不足以支持结论。
`--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]
```
默认 stdout 是 PR 表格和短摘要，不输出 PR body 或 closeout metadata。脚本消费字段用 `--json` ，全量排障用 `--full` /`--raw` 。
### 查看
``` 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]
```
默认 stdout 是 PR 元数据表格、短摘要、body chars/SHA/preview 和 Next 命令，不输出完整 body。`stateDetail` 归一化为 `open|closed|merged` 。`mergeable` /`mergeStateStatus` /`statusCheckRollup` 走 GraphQL，且仅在显式请求相关 `--json` 字段或 `--full` /`--raw` 时读取。
### 文件变更
``` bash
bun scripts/cli.ts gh pr files <number> [ --repo owner/name] [ --limit N]
bun scripts/cli.ts gh pr review-plan <number| url| owner/repo#number> [ --repo owner/name] [ --limit N]
bun scripts/cli.ts gh pr diff <number| url| owner/repo#number> --file <path> [ --hunk N] [ --repo owner/name] [ --limit N] [ --full| --raw]
```
默认 stdout 是 changed files 统计表格，不输出 raw diff。`gh pr diff <number> --stat` 是兼容别名。
`review-plan` 是主代理 review PR 的 bounded patch index：默认输出 changed files、add/del、hunk 数、patch line 数、默认 patch drill-down 是否会截断，以及每个返回文件的 `gh pr diff --file` 命令。它不创建本地 review worktree，也不输出 patch body。
`gh pr diff --file <path>` 读取单个 changed file 的 GitHub REST patch，默认只显示 bounded patch excerpt； `--hunk N` drill-down 到单个 hunk， `--limit N` 调整默认显示行数。只有显式 `--full` /`--raw` 才在结构化输出里包含完整 file patch。
### 收口预检
``` 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` ； `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` ； `/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'` （ `--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 等。
Codex