pikasTech-unidesk/docs/reference/code-queue-supervision.md

Code Queue 指挥监督策略

本文定义在人工或 lead-agent 指挥官监督下，把 Code Queue 作为并行交付基础设施使用的长期运行模型。本文是协同策略，不替代 docs/reference/microservices.md、docs/reference/observability.md、docs/reference/user-service-delivery.md 或 Code Queue runtime 合同。

范围

当一个交付目标过大，无法由单个 Code Queue 任务完成，并且必须拆分到多个队列、服务或基础设施 lane 时，使用本策略。

本策略适用于：

• 用户服务 CI/CD 推广；
• 需要多个隔离 worktree 的跨服务修复；
• 用户服务开发过程中暴露出来的基础设施缺陷；
• 后续验证、retry、验收和任务接力协调；
• 指挥官为了保持 Code Queue 任务推进而做的手动监督工作，但不接管 worker 的具体实现。

本文不授权绕过正常部署、Git 或生产安全规则。

运行原则

指挥官对最终结果负责，Code Queue task 对边界明确的执行负责。

指挥官应维护交付目标、活跃队列、阻塞点、证据缺口和下一步恢复动作的实时地图。Code Queue worker 应收到自包含 prompt，prompt 中必须有足够上下文，不能依赖 GitHub issue 可见性或聊天历史。

集中指挥的目标是提升交付吞吐和可用性，而不是把每个缺陷都变成一次性的人工修补。

指挥官的最终目标是推动整体开发波次持续前进：跟踪队列进展、及时纠偏、审查完成质量，并安排下一轮任务，让交付计划持续复利式推进，而不是一批任务结束后停滞。

任务设计

每个 Code Queue task 都必须有清晰且狭窄的 ownership 边界。

• 尽量每个任务只负责一个服务、模块或基础设施缺陷。
• 每个任务使用共享 workspace 下自己的 detached worktree。
• 在 prompt 中直接写明写入范围、验证范围、提交/推送要求和禁止动作。
• 相关背景必须写进 prompt；issue 链接只能作为辅助引用，不能作为必要上下文。
• 优先复用已有队列；只有现有 lane 无法表达 ownership 边界时，才创建新队列。
• 队列并发必须受真实执行能力约束。通常目标是约 5 条并发 lane；当活跃任务写入范围彼此独立、heartbeat/trace 证据健康、成功率可接受时，指挥官可以把并发提高到约 10。若完成质量下降，应先降并发再继续扩张。

靠近生产的任务 prompt 必须明确禁止在 master server 上跑已知可能 OOM 的重型本地检查，并说明哪些验证应在 D601 CI、dev env 或目标服务容器中执行。

当一个指挥机需要突发创建大量 Code Queue 任务时，submit 默认应串行或接近串行。为了避免控制面在确认任务前被打爆，可以使用短本地锁或短延迟，尤其是在低内存主机上。目标是保持任务创建可观测且稳定，而不是最大化瞬时入队吞吐。

GitHub Issue 和 PR 使用

GitHub issue 是长期需求、缺陷、阻塞和决策的 source of record。聊天上下文、Code Queue final response 和过程简报可以帮助恢复现场，但不能替代 issue 中的可检索记录。

指挥官应在以下情况创建或更新 GitHub issue：

• 新需求需要跨多个 Code Queue task、跨服务或跨部署阶段推进；
• 运行中发现可复用的基础设施缺陷，例如 CLI 能力缺口、凭证注入缺口、runner 局部观测误导、部署路径不可达；
• 任务完成但缺少远端 commit、live verification、dev/prod 部署证据等验收闭环；
• 某个手动临时绕行暴露出长期产品化需求；
• 战略、流程、发布线或 CI/CD 规则发生需要后续任务遵循的决策。

issue 内容必须自包含，至少写清楚背景、外部收益、当前观察、需求范围、非目标、验收标准和关联任务。不要只贴聊天摘要或只写“见某任务”；Code Queue worker 可能看不到 issue，也可能无法访问完整历史，因此 issue 是人类和指挥官恢复全局态势的记录，不是 worker prompt 的替代品。

如果某个 worker 任务需要依赖 GitHub issue 内容，但 runner 的 issue 可达性尚未被单独验证，指挥官不能默认 worker 已能读取该 issue。此时 worker prompt 必须直接内嵌完整需求、约束和验收点，issue URL 只能作为辅助引用。若要把 issue 作为任务输入源，先单独做可达性探测，再决定是否把 issue 作为常规前置条件。

如果 gh issue create 的 GraphQL 路径因为 token scope 或 repository metadata 查询失败，允许使用 GitHub REST API 创建 issue。CLI 或脚本应避免在日志中打印 token；失败原因应归类为 GitHub 凭证/CLI 兼容问题，而不是业务任务失败。

PR 是审查型交付入口，不是所有 Code Queue 任务的默认出口。默认 master-only 交付仍按项目 Git 规则执行；当变更风险高、跨模块、需要人工审查、或任务目标明确要求 PR 交付时，worker 可以创建 PR。PR 型任务必须报告源分支、目标分支、PR URL、关联 issue、测试证据和未完成风险。禁止把 PR 当成隐藏分支仓库；PR 分支必须来自最新目标线，保持小而可审查，并在合并后确认目标分支远端 commit 可 fetch。

PR 支持本身是 Code Queue 能力的一部分。实现前，指挥官可以先把“支持 PR 交付”的需求拆成独立 infra issue 和 task；在能力未完成前，不应让普通 worker 隐式依赖 PR 机制。

监控

指挥官必须用 task 级和 queue 级证据监控 Code Queue，不能只看单一状态字段。

常用入口：

• bun scripts/cli.ts codex tasks --view supervisor --limit N：查看默认有界监督视图，包括 running、完成未读、最近完成、queued/runnable、execution diagnostics 和下一步 drill-down 命令。
• bun scripts/cli.ts codex queues：查看低噪声队列计数、active task id、完成未读队列、runnable 队列和控制面诊断；只有需要完整队列行时才加 --full。
• bun scripts/cli.ts codex tasks --unread --limit N：查看完成未读审阅积压；--unread 与 --unread-only 等价，不能被静默忽略。
• bun scripts/cli.ts codex tasks --status succeeded --unread --limit N：按具体终态过滤监督结果；不支持的 status filter 必须显式失败，不能扩大为未过滤结果。
• bun scripts/cli.ts codex task <taskId>：查看 attempt、最后 assistant message、最后错误、cancel flag 和当前状态。
• 当摘要不足时，再使用 bun scripts/cli.ts codex task <taskId> --trace --limit N 或 codex output。
• 当 master 控制面状态和 D601 scheduler 状态看起来分裂时，使用 docs/reference/observability.md 中的活性规则判断。

默认 supervisor 视图必须保持低噪声。每个任务应带 commands.show、commands.trace、commands.output、commands.full 和 commands.read，让下一步渐进披露动作明确；默认不得嵌入完整 queue 列表、完整 final response、raw output 页或完整 trace 行。commands.read 只是在人工审阅后的建议命令，listing 命令绝不能自动执行。

队列诊断中的 split-brain 表示控制面/执行面观测分裂，不自动证明任务已经死亡。如果任务 heartbeat 新鲜且 trace 仍在推进，应把任务视为 live，继续监督，而不是 interrupt 或替换。队列摘要应显示 effectiveLiveness=live、splitBrainLive=true 和 recommendedAction=continue-supervision；如果 heartbeat expired/missing 或满足 stale-recovery 条件，应显示 effectiveLiveness=at-risk。

对于 trace 或 heartbeat 新鲜的长任务，通常应保持运行。每几分钟轮询一次优于反复 interrupt/retry。

对于大规模 CI/CD 迁移波次，除非发生事故，否则使用固定监督节奏。默认是 5 分钟轮询循环：读取 codex queues，读取 terminal 或可疑任务摘要，然后决定接受、retry、拆分 blocker，或让健康任务继续运行。循环期间指挥官可以做不重叠的有用工作，例如文档或 issue 梳理，但这些辅助工作不能接管 worker 已分配的实现。

当任务离开 running 或 judging 后，其结果仍然是未读工作。指挥官必须检查 final response 和 judge 记录，然后再决定是否补充并发窗口。

禁止在检查前用批量 read 动作清空完成未读任务。每个完成任务必须先单独审阅，再用 bun scripts/cli.ts codex read <taskId> 单独标记已读，使未读状态继续代表“仍需审阅”。

每次新增 Code Queue 任务、补发 follow-up task，或处理一批完成未读任务后，都必须同步更新 GitHub 总看板 issue #20 的正文主表。看板更新应反映当前任务分布、关键 blocker 和粗略进度，不要只改聊天上下文或只改单个 issue，而让总态势图落后于实际调度状态。

指挥工作流

对每个活跃任务，按顺序评估四件事：

1. 完成质量：是否真的满足任务验收边界；
2. 完成状态：是否已经终态、可 retry，或仍在推进；
3. 自阻塞风险：任务是否卡在它自己无法解决的问题上；
4. 下一步动作：接受、继续、替换为更窄任务，或上报基础设施问题。

如果 blocker 是可复用的基础设施问题，不要盲目反复重跑业务任务。应先把基础设施缺陷记录到 issue，再在 Code Queue 无法越过时手动修复基础设施，然后恢复交付波次。

指挥官应优先做只读分析和派发新的窄范围任务，而不是本地接管实现。手动工作只保留给基础设施 blocker、live recovery，以及队列无法安全自解的问题。

干预规则

只有存在明确理由时才干预。

• 如果任务还在运行且 trace 或 scheduler heartbeat 新鲜，应引导而不是 interrupt。
• 对运行中任务的引导应优先使用正式 CLI。若源码或 runtime 已有 steer 能力但 CLI 尚未暴露，临时通过受控 microservice proxy 调用可以作为现场恢复手段；这类临时绕行必须记录到指挥简报头部的常驻观察，并创建正式 issue 补齐 CLI 能力，避免长期依赖隐式 API。
• 如果任务进入终态但缺少必要验收证据，应使用聚焦 continuation prompt retry 同一任务。
• 如果任务被可复用基础设施缺陷阻塞，应把该缺陷分配给合适的空闲或低风险队列，让原业务任务等待，或在修复后 retry。
• 如果基础设施缺陷影响 Code Queue 控制面可用性，指挥官可以执行恢复队列所需的最小受控部署，然后验证原任务能继续。
• 如果 retry、cancel、move 或 scheduler 行为错误，不要把手动 patch PostgreSQL 当作最终修复。应修复代码路径，必要时部署，然后通过正常 API 恢复受影响任务。

手动干预应尽可能保留原任务身份，以保持上下文连续。创建重复替代任务是 fallback，不是默认动作。

完成标准

Code Queue task 不是只要 push 代码就算完成。

对于 CI/CD 交付任务，验收必须包含目标交付策略要求的证据。对用户服务 artifact 交付，这意味着：

• CI artifact producer 从已推送 commit 运行；
• artifact ref 和 digest 已记录；
• dev 环境消费同一个 artifact；
• production CD 消费 artifact，且没有源代码 rebuild；
• live health、live commit 或 image label 证据与请求 commit 匹配。

对于基础设施任务，验收必须证明原本被阻塞的 workflow 可以继续，或明确说明 live 系统消费该修复还缺哪个部署步骤。

完成未读任务仍然是指挥官工作。它们必须被阅读、分类，并被接受、retry，或转成新的窄范围 follow-up task。

基础设施缺陷处理

交付计划中发现的基础设施缺陷，只要拆分后能提高吞吐或减少混乱，就应从用户服务工作中拆出来。

基础设施缺陷示例：

• retry API 遗留 stale cancellation state；
• healthcheck 不再匹配 runtime image；
• CLI 可观测性无法快速看到 running、最近完成或完成未读任务；
• WebUI 和 CLI 的 proxy 路径不一致；
• deploy job 报失败但服务 API 实际健康；
• 指挥侧突发 submit 打满 Code Queue manager 或低内存主机，导致队列还没确认任务就被压垮；
• Code Queue 容器缺少监督所需的基础工具或凭证路径，例如 gh、hub 或 GitHub token 注入路径。

这些缺陷应分配给基础设施队列，prompt 中要包含具体观测失败、期望长期合同，以及原交付任务继续所需的恢复动作。

如果缺陷只存在于 Code Queue 执行环境，且服务可以在 dev 中安全热修而不触碰 prod，应先做最小临时 live remedy。然后把修复持久化到相关 Dockerfile、容器镜像或凭证传播路径，并在 dev 验证持久化修复后再关闭问题。

如果业务任务发现缺少工具或凭证路径，指挥官应把它拆成独立 infra task，而不是埋在业务任务 prompt 中。业务任务在 bridge 存在时应继续推进。

指挥边界

指挥官可以：

• 读取 task、queue、health、job 和 service 状态；
• 通过正常 Code Queue 和 microservice proxy API submit、retry、interrupt 或 cancel；
• 创建自包含 follow-up task；
• 在用户允许生产修复且部署路径已验证时，为基础设施恢复执行受控生产部署；
• 当 main worktree 有无关并行变更时，为文档或受控部署动作使用干净 detached worktree。

指挥官自己的 UniDesk 指挥仓库必须保持在单一根 worktree 的最新 master checkout 上。不要为指挥、队列判断或日常监督创建额外 worktree，这样指挥官始终看到当前仓库头和生产协调依赖的同一份实时状态。如果 worker 或受控一次性操作需要隔离 worktree，该 worktree 属于 worker 或具体操作，不属于指挥官的常驻环境。

每个由指挥官派发的 worker prompt，都必须在 Git 指令前明确写明目标线。master 用于主动开发和集成工作；release/v1 只用于明确批准的稳定维护修复。worker 的 final response 必须报告实际推送分支、远端 commit hash，以及该 commit 是否可从 origin/<target-branch> 获取。如果 final response 引用的 commit 不能被指挥官从声明的目标分支 fetch 到，该任务不得验收为完成。

指挥官不得：

• 本地重做 worker 已分配的实现，除非用户明确要求手动接管；
• 在 master server 上跑已知可能 OOM 的 full check、full e2e 或 Playwright；
• 回滚无关 dirty worktree 变更；
• 在 Git 远端是 source of truth 时，把本地部署状态当作 source of truth；
• 在缺少验收证据时宣布交付完成。

文档反馈回路

每个重复出现或阻塞交付的问题，都应反馈到以下至少一个位置：

• 修复该缺陷的 Code Queue task；
• 记录阻塞条件和恢复依赖的 GitHub issue 或 issue comment；
• 当经验具有长期复用价值时，写入长期参考文档。

长期参考文档应记录可复用规则，而不是完整事故流水账。过程知识应降低未来监督成本，而不是变成又一个一次性日志。