From 3c2ac0771611cbd9405ef8295a5075cf9027bae2 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 9 Jun 2026 10:20:59 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=20GitHub=20=E8=AF=84?= =?UTF-8?q?=E8=AE=BA=E7=BC=96=E8=BE=91=E5=85=A5=E5=8F=A3=E5=8F=82=E8=80=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/reference/code-queue-supervision.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/code-queue-supervision.md b/docs/reference/code-queue-supervision.md index 23df2834..40ca0f2d 100644 --- a/docs/reference/code-queue-supervision.md +++ b/docs/reference/code-queue-supervision.md @@ -183,7 +183,7 @@ issue 内容必须自包含，至少写清楚背景、外部收益、当前观 `#20` 当前仍受 body profile 保护，正文必须保留 `## 看板（OPEN）` heading；该 heading 可用于承载紧凑的 P0/P1 直达表或当前活跃入口，不再要求恢复旧式 OPEN/CLOSED 全覆盖明细表。`gh issue board-audit` 只做只读结构审计，不再负责检查 GitHub open/closed issue 是否被表格完全覆盖；维护旧式表格时才使用 `board-row` 系列命令。 -GitHub issue/PR 操作应优先使用 UniDesk CLI 的安全入口：`bun scripts/cli.ts gh auth status`、`gh issue list/read/view/create/update/comment create/comment delete/close/reopen/scan-escape/cleanup-plan/board-audit/board-row list/board-row get/board-row update`、`gh pr list/read/view/create/update/comment create/comment delete/close/reopen`。该入口默认 repo 是 `pikasTech/unidesk`，支持 `--repo owner/name`，输出稳定 JSON，并把 `missing-binary`、`missing-token`、`auth-failed`、`github-transient`、`network-proxy-failed`、`permission-denied`、`repo-not-found`、`repo-forbidden`、`issue-not-found`、`pr-not-found`、`scope-insufficient`、`validation-failed`、`invalid-response`、`unsupported-command` 等失败原因结构化。失败对象必须包含 `runnerDisposition=infra-blocked|business-failed`，runner 应用它区分基础设施阻塞和业务/参数失败。`github-transient` 专指 GitHub DNS 或 API 连接在收到 HTTP 状态前失败，例如 `Temporary failure in name resolution`、`Could not resolve host: github.com/api.github.com` 或 `error connecting to api.github.com`；它必须带 `retryable=true` 或等价 retry/backoff 指示，并且不是 `missing-token`、`auth-failed`、`scope-insufficient`、`validation-failed` 或 PR 语义失败。指挥官看到这类结果时，优先重试或退避；如果对应 Code Queue 任务 heartbeat/trace 仍新鲜，应保持任务运行并继续监督，不要立即 close/requeue 业务工作。runner 不应直接运行系统 `gh auth status` 并把输出贴入 Code Queue 日志；系统 `gh` 的 masked token 行仍会暴露 token 前缀和 scope 片段。需要验证当前 runner GitHub auth 时使用 `bun scripts/cli.ts gh auth status --repo pikasTech/unidesk` 或 `bun scripts/cli.ts codex pr-preflight --remote`，输出只能保留 token 是否存在、来源、长度和掩码，不得打印 token 值或 token 片段。Code Queue 输出层必须在保留 command output、trace、raw output 页面和 commander 摘要前 redaction `gh auth status` 风格 token 行，并给出 UniDesk CLI wrapper 提示。`gh issue list --state open --limit N --json number,title,state,closed,closedAt,url` 是有界 issue 发现入口，`--state` 只接受 `open|closed|all`，list 字段白名单是 `number,title,state,closed,closedAt,url,updatedAt,createdAt,author,labels`；未知 state 或未知字段必须失败，不能静默返回空数组。`gh issue view --json body,title,state,closed,closedAt` 是 canonical 入口，`read` 只保留为兼容别名，正文仍应从 `.data.issue.body` 读取。单 issue/PR/comment 数字目标命令兼容 `--number N`，但成功响应必须带 `standardSyntaxHint` 提示标准位置参数写法；comment delete 中的 `--number` 表示 commentId。未知 `--json` 字段必须失败，不得让调用方把空正文或缺失生命周期字段误判为读取成功。`gh issue scan-escape --limit N [--dry-run]` 与 `gh issue cleanup-plan` 只读扫描 issue body/comments 的字面量 `\n`、shell escape、短 body、blank/null body，输出 `classification=suspected-pollution|explanatory-mention|risk`、body/comment id、预览和清理建议；说明性提到 `\n` 不应被当成污染，cleanup-plan 永远不真实清理历史评论。`gh issue board-audit --board-issue 20 --limit N --dry-run` 只读审计目标 board issue 正文结构，返回正文长度、行数、body SHA、可解析 Markdown board sections、section 行数和 parser warnings；它不再拉取 GitHub open/closed issue 列表，也不再校验 OPEN/CLOSED 表覆盖关系。兼容字段 `missingOpenIssues`、`closedInOpenRows`、`missingClosedRows`、`rowValidationWarnings`、`ignoredIssues` 和 `recommendedActions` 仍保留为空数组或 0。显式 `gh issue update --body-profile commander-brief` 可用于 #24 legacy 简报和每日滚动简报 issue；每日简报 issue 应用标题 `YYYY-MM-DD 指挥简报（北京时间）` 或在既有正文首行/关键 heading 中标明简报身份，且新正文必须包含 `## 常驻观察与长期建议`。对非简报 issue 使用该 profile 应失败为 `profile-issue-mismatch`。需要维护旧式 OPEN/CLOSED 明细表时，继续使用 `gh issue board-row list --board-issue 20 --state open|closed|all`、`gh issue board-row get --board-issue 20` 和 `gh issue board-row update --board-issue 20 --field progress|status|validation|branch|tasks|focus --value `；`board-row update` 只替换一行一个单元格，输出 old/new row、body SHA、body guard 和 request plan，且默认 dry-run，正式写入必须带 `--expect-body-sha` 或 `--expect-updated-at`。字段映射中 `status`/`validation` 都指向 `验收状态`，`tasks` 指向 `相关 Code Queue 任务`，`focus` 指向 `当前关注点`；单元格管道会转义、真实换行会折叠为空格，避免新增字面量 `\n`。`gh issue board-row upsert` 可更新既有行或按 section 生成完整新行；`board-row add/move/delete` 已支持行级新增、OPEN/CLOSED 迁移和删除，全部默认 dry-run，正式 PATCH 必须带 `--expect-body-sha` 或 `--expect-updated-at`。`gh pr list --json ...` 支持 `body,title,state,number,url,author,head,base,draft,createdAt,updatedAt` 字段白名单；`gh pr read|view --json ...` 还支持 `stateDetail,closed,closedAt,merged,mergedAt,mergeCommit,headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup`。`stateDetail=open|closed|merged` 用于区分 REST `state=closed` 中的普通关闭和已合并；`closed*`、`merged*`、`mergeCommit` 和分支名字段都来自 REST。只有 mergeability/check rollup 需要请求 GraphQL，适合 PR 收口前判断可合并性和检查汇总。GraphQL 权限不足、网络失败、GitHub 仍返回 `UNKNOWN`/null、或需要 UniDesk CLI 尚未开放的官方字段、review/merge 操作时，回退系统 `gh` 只读观察或 GitHub UI；不要把缺失元数据当成已可合并。issue/PR 创建、更新、评论、评论删除、关闭和重开使用 GitHub REST API；只要有 `GH_TOKEN` 或 `GITHUB_TOKEN`，就不依赖系统 `gh` binary。`gh` binary 只作为状态探测和 `gh auth token` fallback，不是写操作的主路径。GitHub 不支持 issue/PR 硬删除，`gh issue delete` 和 `gh pr delete` 必须结构化返回 `unsupported-command`；生命周期删除语义使用 `close`。`gh pr merge` 是 guarded write：先执行 closeout preflight，只在 open、非 draft、无冲突、merge state CLEAN 且 checks 无失败/pending 时调用 GitHub REST merge；`--dry-run` 只输出计划不写远端。 +GitHub issue/PR 操作应优先使用 UniDesk CLI 的安全入口：`bun scripts/cli.ts gh auth status`、`gh issue list/read/view/create/update/comment create/comment update/comment edit/comment delete/close/reopen/scan-escape/cleanup-plan/board-audit/board-row list/board-row get/board-row update`、`gh pr list/read/view/create/update/comment create/comment update/comment edit/comment delete/close/reopen`。该入口默认 repo 是 `pikasTech/unidesk`，支持 `--repo owner/name`，输出稳定 JSON，并把 `missing-binary`、`missing-token`、`auth-failed`、`github-transient`、`network-proxy-failed`、`permission-denied`、`repo-not-found`、`repo-forbidden`、`issue-not-found`、`pr-not-found`、`scope-insufficient`、`validation-failed`、`invalid-response`、`unsupported-command` 等失败原因结构化。失败对象必须包含 `runnerDisposition=infra-blocked|business-failed`，runner 应用它区分基础设施阻塞和业务/参数失败。`github-transient` 专指 GitHub DNS 或 API 连接在收到 HTTP 状态前失败，例如 `Temporary failure in name resolution`、`Could not resolve host: github.com/api.github.com` 或 `error connecting to api.github.com`；它必须带 `retryable=true` 或等价 retry/backoff 指示，并且不是 `missing-token`、`auth-failed`、`scope-insufficient`、`validation-failed` 或 PR 语义失败。指挥官看到这类结果时，优先重试或退避；如果对应 Code Queue 任务 heartbeat/trace 仍新鲜，应保持任务运行并继续监督，不要立即 close/requeue 业务工作。runner 不应直接运行系统 `gh auth status` 并把输出贴入 Code Queue 日志；系统 `gh` 的 masked token 行仍会暴露 token 前缀和 scope 片段。需要验证当前 runner GitHub auth 时使用 `bun scripts/cli.ts gh auth status --repo pikasTech/unidesk` 或 `bun scripts/cli.ts codex pr-preflight --remote`，输出只能保留 token 是否存在、来源、长度和掩码，不得打印 token 值或 token 片段。Code Queue 输出层必须在保留 command output、trace、raw output 页面和 commander 摘要前 redaction `gh auth status` 风格 token 行，并给出 UniDesk CLI wrapper 提示。`gh issue list --state open --limit N --json number,title,state,closed,closedAt,url` 是有界 issue 发现入口，`--state` 只接受 `open|closed|all`，list 字段白名单是 `number,title,state,closed,closedAt,url,updatedAt,createdAt,author,labels`；未知 state 或未知字段必须失败，不能静默返回空数组。`gh issue view --json body,title,state,closed,closedAt` 是 canonical 入口，`read` 只保留为兼容别名，正文仍应从 `.data.issue.body` 读取。单 issue/PR/comment 数字目标命令兼容 `--number N`，但成功响应必须带 `standardSyntaxHint` 提示标准位置参数写法；comment update/edit/delete 中的 `--number` 表示 commentId。未知 `--json` 字段必须失败，不得让调用方把空正文或缺失生命周期字段误判为读取成功。`gh issue scan-escape --limit N [--dry-run]` 与 `gh issue cleanup-plan` 只读扫描 issue body/comments 的字面量 `\n`、shell escape、短 body、blank/null body，输出 `classification=suspected-pollution|explanatory-mention|risk`、body/comment id、预览和清理建议；说明性提到 `\n` 不应被当成污染，cleanup-plan 永远不真实清理历史评论。`gh issue board-audit --board-issue 20 --limit N --dry-run` 只读审计目标 board issue 正文结构，返回正文长度、行数、body SHA、可解析 Markdown board sections、section 行数和 parser warnings；它不再拉取 GitHub open/closed issue 列表，也不再校验 OPEN/CLOSED 表覆盖关系。兼容字段 `missingOpenIssues`、`closedInOpenRows`、`missingClosedRows`、`rowValidationWarnings`、`ignoredIssues` 和 `recommendedActions` 仍保留为空数组或 0。显式 `gh issue update --body-profile commander-brief` 可用于 #24 legacy 简报和每日滚动简报 issue；每日简报 issue 应用标题 `YYYY-MM-DD 指挥简报（北京时间）` 或在既有正文首行/关键 heading 中标明简报身份，且新正文必须包含 `## 常驻观察与长期建议`。对非简报 issue 使用该 profile 应失败为 `profile-issue-mismatch`。需要维护旧式 OPEN/CLOSED 明细表时，继续使用 `gh issue board-row list --board-issue 20 --state open|closed|all`、`gh issue board-row get --board-issue 20` 和 `gh issue board-row update --board-issue 20 --field progress|status|validation|branch|tasks|focus --value `；`board-row update` 只替换一行一个单元格，输出 old/new row、body SHA、body guard 和 request plan，且默认 dry-run，正式写入必须带 `--expect-body-sha` 或 `--expect-updated-at`。字段映射中 `status`/`validation` 都指向 `验收状态`，`tasks` 指向 `相关 Code Queue 任务`，`focus` 指向 `当前关注点`；单元格管道会转义、真实换行会折叠为空格，避免新增字面量 `\n`。`gh issue board-row upsert` 可更新既有行或按 section 生成完整新行；`board-row add/move/delete` 已支持行级新增、OPEN/CLOSED 迁移和删除，全部默认 dry-run，正式 PATCH 必须带 `--expect-body-sha` 或 `--expect-updated-at`。`gh pr list --json ...` 支持 `body,title,state,number,url,author,head,base,draft,createdAt,updatedAt` 字段白名单；`gh pr read|view --json ...` 还支持 `stateDetail,closed,closedAt,merged,mergedAt,mergeCommit,headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup`。`stateDetail=open|closed|merged` 用于区分 REST `state=closed` 中的普通关闭和已合并；`closed*`、`merged*`、`mergeCommit` 和分支名字段都来自 REST。只有 mergeability/check rollup 需要请求 GraphQL，适合 PR 收口前判断可合并性和检查汇总。GraphQL 权限不足、网络失败、GitHub 仍返回 `UNKNOWN`/null、或需要 UniDesk CLI 尚未开放的官方字段、review/merge 操作时，回退系统 `gh` 只读观察或 GitHub UI；不要把缺失元数据当成已可合并。issue/PR 创建、更新、评论创建、评论编辑、评论删除、关闭和重开使用 GitHub REST API；只要有 `GH_TOKEN` 或 `GITHUB_TOKEN`，就不依赖系统 `gh` binary。`gh` binary 只作为状态探测和 `gh auth token` fallback，不是写操作的主路径。GitHub 不支持 issue/PR 硬删除，`gh issue delete` 和 `gh pr delete` 必须结构化返回 `unsupported-command`；生命周期删除语义使用 `close`。`gh pr merge` 是 guarded write：先执行 closeout preflight，只在 open、非 draft、无冲突、merge state CLEAN 且 checks 无失败/pending 时调用 GitHub REST merge；`--dry-run` 只输出计划不写远端。 CLI 是短 shout 的需求原语，不是长驻服务器进程。CLI 功能不好用、兼容性不足、安全 guard 不够或输出不利于 runner/指挥官使用时，应默认创建 GitHub issue 并用 Code Queue 推进；这类 CLI 问题走 `master`、remote commit、轻量 contract test 和文档更新，不套用 backend-core、Code Queue runtime 这类运行态服务的重部署门禁。若 CLI 缺陷已经阻塞当前指挥，可以先做最小安全绕行，同时把长期修复写入 issue 并派单。 @@ -193,7 +193,7 @@ PR 是审查型交付入口，不是所有 Code Queue 任务的默认出口。 PR handoff 的职责默认分开：runner 实现、测试、提交、push head branch 并创建 PR；指挥官监督并发、steer、审阅、确认 checks 和合并裁决。短期内 GPT-5.5 runner 如果收到明确 PR 收口授权，并且 PR 是普通 UniDesk source 变更、checks 满足任务要求、无冲突且不涉及 prod/runtime/release/security/database/破坏性回滚，可以自行用 repo-owned GitHub merge/close 路径完成收口并报告 SHA。高风险、边界不清、checks 失败或用户/指挥官保留 final action 的 PR 仍必须交回 commander 审查。host commander 也不把直接编辑业务代码当成常规 PR 替代路径。 -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 收口观察应使用 `gh pr view --json state,stateDetail,closed,closedAt,merged,mergedAt,mergeCommit,headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup` 获取普通关闭/已合并区分、merge commit、目标分支、源分支、mergeability 和检查汇总；该路径仍是只读元数据，不执行 merge，且 `closeoutMetadata.ok=false`、`missingOrUnknownFields` 或 GraphQL failure 都只能作为“需要人工复核/重试”的信号。`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 list` 不开放 mergeability/statusCheckRollup 列表字段，避免默认拉取 noisy/raw 状态汇总。`gh pr delete` 在 UniDesk REST CLI 中返回 `unsupported-command`，不能伪造硬删除；需要移除活跃 PR 时使用 `gh pr close`。`gh pr merge` 是 guarded REST write，没有 `--confirm` 可以绕过 preflight；获得收口授权的 GPT-5.5 runner 可使用 UniDesk `gh pr merge`、GitHub UI 或等价 repo-owned GitHub merge path 处理普通 PR，并报告结果 SHA。需要 PR 交付时，prompt 必须明确允许的人工、runner 或后续工具路径，并报告未覆盖范围。 +PR 支持本身是 Code Queue 能力的一部分。当前 UniDesk CLI 支持 `gh pr list|view|create|update|comment create|comment update|comment edit|comment delete|close|reopen`，其中 create 需要显式 `--title`、`--base`、`--head` 和正文来源，update 需要显式 PR number、正文来源和 `--mode replace|append`，comment create/update/edit 需要显式 commentId 或目标 shorthand 和正文来源，且推荐使用 `--body-stdin` 或 `--body-file`。PR 收口观察应使用 `gh pr view --json state,stateDetail,closed,closedAt,merged,mergedAt,mergeCommit,headRefName,baseRefName,mergeable,mergeStateStatus,statusCheckRollup` 获取普通关闭/已合并区分、merge commit、目标分支、源分支、mergeability 和检查汇总；该路径仍是只读元数据，不执行 merge，且 `closeoutMetadata.ok=false`、`missingOrUnknownFields` 或 GraphQL failure 都只能作为“需要人工复核/重试”的信号。`pr create --dry-run`、`pr update --dry-run` 与 `pr comment create/update/edit --dry-run` 只返回 planned operation，不创建 PR、不更新正文、不写评论；非 dry-run 创建前会校验 repo、base、head 和 compare ahead 状态，append 更新会先读取当前 PR body。`gh pr list` 不开放 mergeability/statusCheckRollup 列表字段，避免默认拉取 noisy/raw 状态汇总。`gh pr delete` 在 UniDesk REST CLI 中返回 `unsupported-command`，不能伪造硬删除；需要移除活跃 PR 时使用 `gh pr close`。`gh pr merge` 是 guarded REST write，没有 `--confirm` 可以绕过 preflight；获得收口授权的 GPT-5.5 runner 可使用 UniDesk `gh pr merge`、GitHub UI 或等价 repo-owned GitHub merge path 处理普通 PR，并报告结果 SHA。需要 PR 交付时，prompt 必须明确允许的人工、runner 或后续工具路径，并报告未覆盖范围。 ### PR 驱动派单模板