docs: add code queue PR preflight template
This commit is contained in:
Codex
@@ -80,6 +80,48 @@ PR 是审查型交付入口，不是所有 Code Queue 任务的默认出口。
|
||||
|
||||
PR 支持本身是 Code Queue 能力的一部分。当前 UniDesk CLI 支持 `gh pr list|view|create|update|comment create|comment delete|close|reopen`，其中 create 需要显式 `--title`、`--base`、`--head` 和正文来源，update 需要显式 PR number、正文来源和 `--mode replace|append`，comment create 需要显式 PR number 和正文来源，且推荐使用 `--body-file`。`pr create --dry-run`、`pr update --dry-run` 与 `pr comment create --dry-run` 只返回 planned operation，不创建 PR、不更新正文、不写评论；非 dry-run 创建前会校验 repo、base、head 和 compare ahead 状态，append 更新会先读取当前 PR body。`gh pr delete` 和 `gh pr merge` 仍是后续范围，本阶段没有 `--confirm` 可以启用真实 merge，也不能伪造硬删除；需要移除活跃 PR 时使用 `gh pr close`。普通 worker 不应隐式依赖未实现的 PR 合并能力；需要 PR 交付时，prompt 必须明确允许的人工或后续工具路径，并报告未覆盖范围。
|
||||
|
||||
### PR 驱动派单模板
|
||||
|
||||
PR 驱动是 Code Queue 协作的未来默认方向：worker 在独立 head branch 上提交，创建面向目标分支的 PR，指挥官审查后再合并并更新 issue/#20/#24。当前仍处于 runner GitHub 可达性补齐阶段；在 #19 的 runner GitHub 可达性未验收前，派单 prompt 必须自包含完整需求、约束、写入范围和验收标准，不能只贴 GitHub issue 链接。issue URL 只能作为辅助引用。
|
||||
|
||||
PR 型派单 prompt 至少包含以下字段：
|
||||
|
||||
- `目标 issue`：写明 issue 编号、URL 和本次任务要关闭或推进的验收点；不要假设 runner 能读取 issue。
|
||||
- `目标分支`：明确 `master` 或经批准的维护分支；普通开发集成使用 `master`。
|
||||
- `head branch`：使用可追踪命名，例如 `code-queue/issue-35-pr-dry-run-probe`、`code-queue/issue-<number>-<short-topic>` 或包含 task id 的等价短名；head branch 必须从最新 `origin/<目标分支>` 创建。
|
||||
- `禁止动作`：禁止直接 push 目标分支，禁止 merge PR，禁止改 release/v1 运行态服务，禁止输出 token，禁止跑本任务未要求的重型 check/e2e/Playwright。
|
||||
- `必须动作`：提交前运行轻量自测；push head branch；创建面向目标分支的 PR；PR body 写清关联 issue、修改文件、验证命令和风险；若创建 PR 前需要探测，先运行只读或 dry-run preflight。
|
||||
- `final response 字段`：实际分支、目标分支、head branch、PR URL、远端 head commit、是否已创建 PR、是否未 merge、修改文件、验证命令和结果、遗留风险；如果 PR 未能创建，报告结构化原因和 runnerDisposition。
|
||||
|
||||
PR 型 prompt 可直接嵌入以下 Git 指令约束：
|
||||
|
||||
```text
|
||||
Git/PR 交付要求：
|
||||
- 目标分支：master。
|
||||
- 从最新 origin/master 创建 head branch：code-queue/issue-<number>-<short-topic>。
|
||||
- 不得直接 push master 或 release/v1。
|
||||
- 必须 push head branch 并创建 PR 到 master；不得 merge PR。
|
||||
- 创建 PR 前先运行只读/dry-run preflight，确认 GH_TOKEN/GITHUB_TOKEN、GitHub egress 和 repo 可见性，不得打印 token。
|
||||
- final response 必须报告 head branch、PR URL、远端 head commit、修改文件、验证命令、是否未 merge。
|
||||
```
|
||||
|
||||
Runner preflight 示例：
|
||||
|
||||
```bash
|
||||
bun scripts/code-queue-pr-preflight-example.ts --repo pikasTech/unidesk --base master --head code-queue/issue-35-pr-dry-run-probe --comment-pr 1
|
||||
```
|
||||
|
||||
该脚本只读调用 `gh auth status`，并执行 `gh pr create --dry-run` 与 `gh pr comment --dry-run`。它检查 `GH_TOKEN/GITHUB_TOKEN` 是否存在、GitHub REST egress 是否可达、repo 是否可见，并且只输出 token 来源和存在性，不输出 token 值。`--comment-pr` 只是 dry-run 计划中的 PR number，不会写评论。
|
||||
|
||||
指挥官审查 checklist：
|
||||
|
||||
- PR base 是声明的目标分支，head branch 命名可追踪，远端 head commit 可 fetch。
|
||||
- diff 只覆盖派单 ownership，未混入 release/v1 运行态服务或无关 dirty worktree。
|
||||
- PR body 和 final response 都包含关联 issue、修改文件、验证证据、未完成风险和未 merge 状态。
|
||||
- contract/dry-run 证据覆盖本次 PR 能力：`pr create --dry-run`、`pr list/view`、`pr comment --dry-run`，并确认 `gh pr merge` 返回结构化 unsupported。
|
||||
- 没有 token、凭证、临时日志或构建产物进入 commit、PR body 或评论。
|
||||
- 合并前由指挥官审查并决定是否 merge；合并后再验证目标分支远端 commit 可见，并按态势更新 issue/#20/#24。
|
||||
|
||||
## 监控
|
||||
|
||||
指挥官必须用 task 级和 queue 级证据监控 Code Queue，不能只看单一状态字段。
|
||||
|
||||
Reference in New Issue
Block a user