docs: add code queue PR preflight template
This commit is contained in:
Codex
@@ -35,6 +35,7 @@ CLI 可以从 `master` 快速演进，但必须兼容 `deploy.json` 固定的 CI
|
||||
- `gh issue update <number> --mode replace|append --body-file <file>` 是正文更新主入口，`edit` 保留为兼容别名。`replace` 用文件正文替换现有 body；`append` 先读取当前 body，再按 UTF-8 文件字节追加，保留真实换行、反引号和 Markdown 表格。更新默认拒绝字面量 `null`、空白正文和过短正文；只有真实需要写短正文时才允许显式加 `--allow-short-body`，返回 JSON 会报告该风险。#20 总看板和 #24 指挥简报是长期 body-only issue，`--body-profile auto` 会按 issue number 自动启用结构 guard：#20 必须包含 `## 看板（OPEN）`，#24 必须包含 `## 常驻观察与长期建议`；也可显式使用 `--body-profile code-queue-board|commander-brief`。`--dry-run` 不 PATCH GitHub，输出新正文长度、SHA、关键标题检查结果、字面量 `\n`、反引号、Markdown 表格和 shell 污染信号；若环境里有 `GH_TOKEN` 或 `GITHUB_TOKEN`，dry-run 还会只读抓取旧正文长度、SHA 和 `updatedAt` 作为更新前对照。正式写入可带 `--expect-updated-at <updated_at>` 或 `--expect-body-sha <sha256>`，CLI 会先读当前 issue，匹配后才 PATCH，防止旧缓存覆盖新正文。
|
||||
- `gh issue edit 24 --body-file <file> --notify-claudeqq-brief-diff [--dry-run]` 是指挥简报 #24 的通知入口。正式执行会先读取 GitHub 上 #24 旧正文并通过 #24 body profile guard，再从 `--body-file` 读取新正文；随后先 PATCH issue 主体，再把本次新增的 `## 更新 YYYY-MM-DD HH:MM 北京时间` 段落发送给 ClaudeQQ，ClaudeQQ 失败不会回滚 issue 正文，失败只体现在返回 JSON 的 `claudeqq.ok=false` 和结构化 `degradedReason`。带通知 flag 的 `--dry-run` 不 PATCH、不发送；它按新正文做发送预览，并在输出中标明非 dry-run 才会读取旧正文做可靠 diff。默认 ClaudeQQ 目标是私聊 `645275593`，默认 base URL 是 UniDesk 受控入口 `http://backend-core:8080/api/microservices/claudeqq/proxy`，可用 `UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_ENABLED`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_BASE_URL`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_TARGET_TYPE`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_USER_ID`、`UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_GROUP_ID` 和 `UNIDESK_COMMANDER_BRIEF_CLAUDEQQ_TIMEOUT_MS` 覆盖。
|
||||
- `gh issue scan-escape [--repo owner/name] [--limit N]` 只读扫描 issue 主体和 comments 中的字面量 `\n`、可疑 `\t`、shell newline escape 和 ANSI escape 字符串，输出 issue/comment id、url、kind、snippet，不自动修复。`gh pr list|view [--json ...]` 提供 REST 列表和详情，PR 字段白名单是 `body,title,state,number,url,author,head,base,draft,createdAt,updatedAt`。`gh pr create --title <title> --body-file <file>|--body <text> --base <branch> --head <branch> [--draft] [--dry-run]`、`gh pr update <number> --mode replace|append --body-file <file>|--body <text> [--title ...] [--dry-run]`、`gh pr comment create <number> --body-file <file>|--body <text> [--dry-run]`、`gh pr comment delete <commentId> [--dry-run]`、`gh pr close|reopen <number> [--dry-run]` 是 PR CRUD/生命周期入口。`pr create --dry-run` 只输出 planned operation，不访问 GitHub；非 dry-run 创建前会校验 repo、base、head 和 compare ahead 状态，成功时返回 PR number/url。`pr update --mode append` 会先读取当前 PR body 再追加正文。`gh pr delete <number>` 和 `gh pr merge` 本阶段不开放，始终结构化返回 `unsupported-command`；PR 生命周期删除语义请使用 `close`。
|
||||
- PR dry-run/probe 的最小手动序列是：`bun scripts/cli.ts gh auth status --repo pikasTech/unidesk` 只读检查 token 来源、GitHub REST egress、repo 可见性和 issue read；`bun scripts/cli.ts gh pr create --repo pikasTech/unidesk --title <title> --body-file <file> --base master --head <head> --dry-run` 检查创建计划；`bun scripts/cli.ts gh pr list --repo pikasTech/unidesk --limit 5 --json number,title,state,url,head,base` 和 `bun scripts/cli.ts gh pr view <number> --repo pikasTech/unidesk --json body,title,state,head,base` 做只读 PR 观察；`bun scripts/cli.ts gh pr comment <number> --repo pikasTech/unidesk --body-file <file> --dry-run` 检查评论计划；`bun scripts/cli.ts gh pr merge <number> --repo pikasTech/unidesk` 必须失败并返回结构化 `unsupported-command`。Code Queue runner 可用 `bun scripts/code-queue-pr-preflight-example.ts --repo pikasTech/unidesk --base master --head <head> --comment-pr <number>` 一次性跑只读 auth status 与 PR create/comment dry-run；该脚本不得输出 token 值，也不会创建、评论或 merge PR。
|
||||
- `ci install|status|run|publish-backend-core|publish-user-service|run-dev-e2e|logs` 管理 D601 原生 k3s 上的 Tekton CI。`run` 手动创建每 commit 检查和 Code Queue 只读性能门禁；`publish-backend-core` 与 `publish-user-service` 从 pushed Git commit 构建并发布 `127.0.0.1:5000/unidesk/<service>:<commit>` commit-pinned artifacts，输出 `artifactSummary`（含 `serviceId`、`sourceCommit`、`sourceRepo`、`dockerfile`、`imageRef`、`tag`、`digest`、`digestRef`），但不部署生产；`run-dev-e2e` 的 Git 控制 runner、短 launcher、host fetch 边界、临时 smoke namespace 和 no-CD 规则只在 `docs/reference/dev-ci-runner.md` 定义；Tekton CI 通用规则见 `docs/reference/ci.md`。
|
||||
- `schedule list|get|runs|run|retry-run|delete|upsert-pgdata-backup` 管理 backend-core 定时任务和运行历史。`schedule runs --limit N` 是全局历史视图，返回 `scope=global` 和 `scheduleId=null`；`schedule runs <scheduleId> --limit N` 是指定 schedule 历史视图，返回 `scope=schedule` 和对应 `scheduleId`。CLI 必须拒绝 `schedule runs 50` 这类纯数字位置参数，并提示使用 `schedule runs --limit 50`，避免把空数组误判成“没有历史 run”。`schedule run <id> --wait-ms N` 触发同一 schedule，并且即使 wait 超时也必须返回 `newRunId` 和 `observeCommand`；`schedule retry-run <failedRunId>` 只接受 failed run，从原 run 反查 `scheduleId` 后重触发同一 schedule，并输出 `originalRunId`、`scheduleId`、`newRunId` 和 `observeCommand`。
|
||||
- `codex deploy <commitId>` 是旧 Code Queue 兼容部署入口，已禁用以防止维护通道直连 D601 部署 Code Queue；当前 dev 自动化只做 `ci run-dev-e2e` smoke，不提供 Code Queue CD，详细规则见 `docs/reference/codex-deploy.md`。
|
||||
|
||||
@@ -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