diff --git a/AGENTS.md b/AGENTS.md index 35ee73d3..a62af560 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -115,6 +115,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台;本文 - P0: 对 GitHub issue/PR 做正式写入时必须优先使用 `bun scripts/cli.ts gh ...`;禁止用原生 `gh issue edit/create/comment` 直接写 UniDesk/HWLAB 长期看板、指挥简报或用户反馈 issue。事故和 CLI 补强需求见 [pikasTech/unidesk#142](https://github.com/pikasTech/unidesk/issues/142)。 - P0: GitHub PR/issue 读写、PR 合并、评论、状态观察和收口动作必须走 UniDesk `gh` 子命令;禁止绕过为原生 `gh`、手写 `curl`/GraphQL/REST 请求或临时脚本直连 GitHub。若 `bun scripts/cli.ts gh ...` 不顺手、字段不够、merge 不支持或可见性不足,必须先改进 UniDesk `gh` 子命令并用它完成任务,不能跳过该入口。 - #20、HWLAB #7 和指挥简报类正文不得使用原生 `gh issue edit --body-file -`、手写 GitHub API 或无 guard 的整篇替换;需要管道化写入时使用 UniDesk `gh issue update|comment create --body-file -`,由 CLI 读取 stdin、执行 body guard、自动读取当前 issue 元数据并输出 old/new body SHA。 +- 长任务和跨回合排障应把专题 issue 评论区作为进展锚点;调查、计划、rollout、阻塞、复测 trace 和最终验收结论都追加到同一个 issue 评论中,细则见 `docs/reference/code-queue-supervision.md`。 ## Critical Git / Multi-Repo Sync Rule diff --git a/docs/reference/code-queue-supervision.md b/docs/reference/code-queue-supervision.md index 9121b5f6..ca8b70ad 100644 --- a/docs/reference/code-queue-supervision.md +++ b/docs/reference/code-queue-supervision.md @@ -163,6 +163,8 @@ GitHub issue 是长期需求、缺陷、阻塞和决策的 source of record。 issue 内容必须自包含,至少写清楚背景、外部收益、当前观察、需求范围、非目标、验收标准和关联任务。不要只贴聊天摘要或只写“见某任务”;Code Queue worker 可能看不到 issue,也可能无法访问完整历史,因此 issue 是人类和指挥官恢复全局态势的记录,不是 worker prompt 的替代品。 +长任务和跨回合排障应把专题 issue 的评论区作为进展锚点。调查结论、细化方案、阶段性修复、rollout 状态、阻塞原因、复测 trace、最终验收和后续风险都应追加到同一个专题 issue 评论中,并引用相关 PR、commit、job、trace 或 runtime revision;正文只保留稳定背景、范围、验收标准和当前摘要,不写成每一步流水账。上下文压缩、切换指挥官或恢复中断后,先读取专题 issue 最新评论,再继续执行,避免只依赖聊天记忆或本地临时文件。写评论必须使用 `bun scripts/cli.ts gh issue comment create ... --body-file `,长正文不得用 shell 参数拼接。 + 如果某个 worker 任务需要依赖 GitHub issue 内容,但 runner 的 issue 可达性尚未被单独验证,指挥官不能默认 worker 已能读取该 issue。此时 worker prompt 必须直接内嵌完整需求、约束和验收点,issue URL 只能作为辅助引用。若要把 issue 作为任务输入源,先单独做可达性探测,再决定是否把 issue 作为常规前置条件。 ### 长期总看板治理