feat: add skill health size check
This commit is contained in:
Codex
@@ -5,430 +5,33 @@ description: UniDesk GitHub CLI - 通过 `bun scripts/cli.ts gh ...` 管理 GitH
|
||||
|
||||
# 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` 只作为受控底座或兼容入口。
|
||||
GitHub issue/PR 正式读写必须走 `bun scripts/cli.ts gh ...` 或 `trans gh:/... apply-patch`，不依赖原生 `gh` binary，不手写 GitHub API。
|
||||
|
||||
**固定入口前缀**: `cd /root/unidesk && bun scripts/cli.ts gh ...`
|
||||
## 高频规则
|
||||
|
||||
## 实现边界
|
||||
- Issue/PR 正文、评论、关闭/重开、PR 描述和 merge closeout 默认中文。
|
||||
- 新 issue 正文必须包含 `目标合并分支: <repo branch/lane>`；不需要合并时写 `目标合并分支: 不适用`。
|
||||
- 大计划、后续阶段和独立改进方向创建新 issue；已有 issue 评论只写短进展、证据、阻塞和链接。
|
||||
- 多行正文使用 quoted heredoc：`--body-stdin <<'EOF'`；不要把长 Markdown 塞进 shell 参数。
|
||||
- PR merge 只走 guarded `gh pr merge`；`gh pr create` 的 Next 默认是 `--merge --delete-branch`，只有确认 ancestry 可丢弃时才显式 `--squash`。
|
||||
|
||||
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 正文；即便如此，评论仍保持短小，不复制整篇计划。
|
||||
|
||||
---
|
||||
|
||||
## 认证探测
|
||||
## 常用入口
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts gh auth status [--repo owner/name]
|
||||
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 --json body,title,state
|
||||
bun scripts/cli.ts gh issue create --repo pikasTech/unidesk --title "标题" --body-stdin
|
||||
bun scripts/cli.ts gh pr create --repo pikasTech/unidesk --title "标题" --body-stdin --base master --head <branch>
|
||||
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
|
||||
```
|
||||
|
||||
探测 token 来源（`GH_TOKEN`/`GITHUB_TOKEN`/`gh auth token`）、GitHub REST egress、repo 可见性、issue 可读性。不打印 token。
|
||||
完整 issue/PR CRUD、comment、patch、stale-close、scan-escape、PR files/preflight/merge、看板命令和 `trans gh:` 虚拟文件系统见 [references/full.md](references/full.md)。
|
||||
|
||||
## 聚焦帮助
|
||||
## 何时读取 reference
|
||||
|
||||
具体子命令用法优先直接查 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 等。
|
||||
- 需要具体 issue/PR/comment 命令参数、`--json` 字段或 body guard：读 [references/full.md](references/full.md) 的 Issue/PR 命令段。
|
||||
- 需要局部修补正文或评论：读 `trans gh:` 和 apply-patch 段。
|
||||
- 需要维护总看板 [#20](https://github.com/pikasTech/unidesk/issues/20)：读看板命令段。
|
||||
- 需要 closeout、preflight、merge 或 ancestry/squash 判断：读 PR 命令和关键约定段。
|
||||
|
||||
@@ -0,0 +1,434 @@
|
||||
---
|
||||
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 正文；即便如此，评论仍保持短小，不复制整篇计划。
|
||||
|
||||
---
|
||||
|
||||
## 认证探测
|
||||
|
||||
```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 等。
|
||||
Reference in New Issue
Block a user