mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
13d0a3ec8d263894f281b3395f48533499ba6d47
pikasTech-unidesk/.agents/skills/unidesk-gh/references/full.md
T
Codex 92d332e26c docs: require full issue body reads
2026-07-02 12:36:15 +00:00

22 KiB
Raw Blame History

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

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+ 阶段。

认证探测

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 再人工搜索：

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

列表

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 是显式结构化/全量披露入口。

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

查看

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。

创建

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。

更新正文

# 替换正文
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:）

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

评论

# 创建评论
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 链接和短结论。

关闭/重开

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

批量过期关闭

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 观察，再正式执行。

转义扫描

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

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

PR 命令

列表

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。

查看

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 时读取。

文件变更

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。

收口预检

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 计数与失败预览。

创建

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。

合并

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 未更新的原因。

编辑 / 评论 / 关闭 / 重开

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

# 列出 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 总看板)

# 结构审计
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=...：

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 的命令都支持：

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：

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

debug 任务入口

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

Reference in New Issue View Git Blame Copy Permalink