From de95cfc5fc96115be6db4db76706cc8b59756744 Mon Sep 17 00:00:00 2001 From: Codex Date: Sat, 4 Jul 2026 05:45:45 +0000 Subject: [PATCH] docs: route subagent tasks through child issues --- .agents/skills/unidesk-subagent/SKILL.md | 3 +- .../references/gh-workflow.md | 33 +++++++++---------- 2 files changed, 17 insertions(+), 19 deletions(-) diff --git a/.agents/skills/unidesk-subagent/SKILL.md b/.agents/skills/unidesk-subagent/SKILL.md index 6284ac5a..26fba6c1 100644 --- a/.agents/skills/unidesk-subagent/SKILL.md +++ b/.agents/skills/unidesk-subagent/SKILL.md @@ -12,7 +12,8 @@ description: UniDesk 主代理调度子代理的必读技能。用户提到子 - 子代理并行只用于成功率高、耦合度低、能放进独立 worktree/branch/issue/PR 的任务；共享架构方向、公共契约和同文件高冲突修改先串行定锚。 - 正式 GitHub issue/PR/comment/merge 仍走 `$unidesk-gh`；子代理可以提交 PR 和写调查结论，主代理负责 review/preflight/merge，除非用户明确授权某个子代理自上线自验证。 - 主代理和子代理必须通过 issue/PR/comment 链接传递可复用上下文、调查结论、证据链接和下一步边界；派发前先读既有评论，prompt 中只引用链接和增量任务，不复述长结论，避免不同子代理重复调查同一事实。 -- 每个执行型子代理必须维护自己的子 issue 和该子 issue 的评论作为接续上下文；主 issue 评论区只由主代理写入主线 anchor、阶段汇总、调度决策和最终 closeout。子代理不得把过程日志、单步证据、长调查和 post-task 反馈直接堆到主 issue 评论区，只能在主 issue 需要可见时由主代理引用子 issue/PR/comment 链接。 +- 主代理派发执行型子代理前必须先创建子 issue，并把主要任务、接续上下文、目标分支/worktree、范围、禁止项和验收入口写入子 issue 正文；子代理 prompt 只给子 issue 链接和极短边界，不塞大段任务正文。每个执行型子代理维护自己的子 issue 和评论作为接续上下文；主 issue 评论区只由主代理写入主线 anchor、阶段汇总、调度决策和最终 closeout。 +- 子代理不得把过程日志、单步证据、长调查和 post-task 反馈直接堆到主 issue 评论区，只能在主 issue 需要可见时由主代理引用子 issue/PR/comment 链接。 - 每个子代理 prompt 必须写清 repo、目标分支、独立 worktree、issue/PR、禁止触碰范围、验收命令、证据字段和是否允许部署；不要让多个子代理共享同一可写 worktree。 - 用户指定模型（例如 `gpt-5.5`）时，主代理调度子代理必须在任务描述或调度参数中显式遵守。 - 用户要求或授权“按任务难度分配模型”时，主代理必须按复杂度选择模型与 reasoning effort，并在 prompt 中写明选择理由；默认继承主模型，只有任务难度、风险或延迟收益明确时才显式覆盖。 diff --git a/.agents/skills/unidesk-subagent/references/gh-workflow.md b/.agents/skills/unidesk-subagent/references/gh-workflow.md index 11cc6c22..176d857e 100644 --- a/.agents/skills/unidesk-subagent/references/gh-workflow.md +++ b/.agents/skills/unidesk-subagent/references/gh-workflow.md @@ -30,7 +30,8 @@ - 大任务先有 GitHub issue 或在既有 issue 中补并行计划：列出子任务、负责人/子代理、目标分支、预期 PR、验证入口、依赖关系和哪些任务可并行。 - 主 issue 评论区由主代理独占维护：只写主线 anchor、阶段汇总、调度决策、已采纳结论、下一批边界和最终 closeout。子代理不得直接在主 issue 评论区堆过程、日志、单步证据或 post-task 反馈；需要让主线可见时，由主代理在主 issue 引用子 issue/PR/comment 链接。 -- 每个执行型子代理必须有自己的子 issue 作为上下文容器。子 issue 标题应能反映父 issue、运行面/模块和子任务；正文必须引用父 issue、目标分支/worktree、允许范围、验收入口和当前接续链接。子代理的调查、单步证据、阻塞、post-task 和后续接力评论都写在自己的子 issue 或关联 PR 中。 +- 主代理派发执行型子代理前必须先创建子 issue，不能把主要任务正文直接塞进 subagent prompt。子 issue 标题应能反映父 issue、运行面/模块和子任务；正文必须引用父 issue、目标分支/worktree、允许范围、禁止范围、验收入口、模型/思考等级选择理由和当前接续链接。子代理的调查、单步证据、阻塞、post-task 和后续接力评论都写在自己的子 issue 或关联 PR 中。 +- 子代理 prompt 只传子 issue 链接、模型要求和“不写父 issue 评论区”等极短边界；不要在 prompt 里复述长任务、历史结论、日志或完整证据。主代理通过观察子 issue 评论区跟踪进度。 - issue/PR/comment 是子代理之间传递上下文的稳定介质。主代理派发前必须先读取父 issue 的主线 anchor 和相关子 issue/PR/comment，在 prompt 中用链接引用已确认事实、证据、阻塞点和禁止重复范围；不要复制粘贴或复述长结论。子代理开始前也要打开这些链接复用结论，除非评论已过期、与新证据冲突或主代理要求复核。 - 调查型子代理优先把结论写入自己的子 issue comment 或子 issue 正文的调查段；主代理再根据调查结论决定修复子任务，而不是让调查子代理直接扩大 scope。 - 调查评论要写成可接力格式：结论、证据来源、未覆盖范围、下一步建议和可直接复用的命令/对象名。不要只写口头判断，也不要把无界日志或大 JSON 贴进评论；长证据放 artifact/drill-down，评论只放 bounded 摘要和链接。 @@ -55,30 +56,26 @@ Prompt 至少包含以下字段，按任务裁剪： ```text -任务：<一句话目标> +任务：阅读并执行 <子 issue URL> 模型要求：<用户指定模型或按难度选择的模型/思考等级；写明选择理由> -Repo/Branch： -Worktree：从最新 创建独立 .worktree/；不得使用主 worktree -Issue/PR：关联 ；修复完成后提交 PR；调查完成后评论 issue -范围：允许修改 ；禁止修改 -架构边界：不得回退 ; 遵守 <相关 issue/spec> -验证：运行 <最小命令>; 需要原入口证据时使用 -交付：返回 PR/commit/issue comment URL、验证摘要、风险、阻塞 +边界：只在子 issue 和关联 PR 维护上下文，不写父 issue 评论区；按子 issue 正文的 worktree/范围/验收执行 +交付：返回子 issue comment URL、PR/commit URL、验证摘要、风险、阻塞 ``` -Prompt 应足够明确，但不要塞入无界日志、长 JSON、完整 issue dump 或大段调查复述。长证据和既有结论用 issue/comment/PR 链接、artifact path 或 bounded collect/analyze 命令引用。 +主要任务、背景、范围和验收写在子 issue 正文；prompt 应足够短，只引用子 issue 和必要边界，不塞入无界日志、长 JSON、完整 issue dump 或大段调查复述。长证据和既有结论用 issue/comment/PR 链接、artifact path 或 bounded collect/analyze 命令引用。 ## 主代理调度循环 1. 建立计划：列出可并行任务、串行依赖和每个子代理交付物。 -2. 同时派发低耦合子任务；共享契约先派一个基线任务。 -3. 轮询子代理结果：PR、issue comment、验证摘要、阻塞。 -4. 对每个 PR 做架构 review、bounded diff、preflight 和必要本地验证。 -5. 按依赖顺序合并；合并后同步目标 worktree。 -6. 触发受控 CI/CD 或让明确授权的子代理上线；主代理核对 closeout。 -7. 用原入口复测；把剩余问题拆到新 issue 或追加既有 issue。 -8. 对每个已完成或已纠偏完成的子代理发送 post-task 收口要求，读取其已判断 feedback；主代理只挑选适合工程化的项转正式 FEATURE/BUG issue，并优先派回原子代理执行。 -9. 主代理 post-task：长期参考、清理已吸收 worktree；不代替子代理做 feedback 池去重。 +2. 为每个执行型子代理先创建子 issue，把任务正文写进子 issue。 +3. 同时派发低耦合子任务；prompt 只引用子 issue 链接和极短边界；共享契约先派一个基线任务。 +4. 轮询子代理结果：子 issue comment、PR、验证摘要、阻塞。 +5. 对每个 PR 做架构 review、bounded diff、preflight 和必要本地验证。 +6. 按依赖顺序合并；合并后同步目标 worktree。 +7. 触发受控 CI/CD 或让明确授权的子代理上线；主代理核对 closeout。 +8. 用原入口复测；把剩余问题拆到新 issue 或追加既有 issue。 +9. 对每个已完成或已纠偏完成的子代理发送 post-task 收口要求，读取其已判断 feedback；主代理只挑选适合工程化的项转正式 FEATURE/BUG issue，并优先派回原子代理执行。 +10. 主代理 post-task：长期参考、清理已吸收 worktree；不代替子代理做 feedback 池去重。 ## 无响应接续