docs: observe subagents via child issue comments

2026-07-04 05:47:39 +00:00
parent de95cfc5fc
commit 01a2fcfd5e
2 changed files with 5 additions and 3 deletions
@@ -14,6 +14,7 @@ description: UniDesk 主代理调度子代理的必读技能。用户提到子
 - 主代理和子代理必须通过 issue/PR/comment 链接传递可复用上下文、调查结论、证据链接和下一步边界；派发前先读既有评论，prompt 中只引用链接和增量任务，不复述长结论，避免不同子代理重复调查同一事实。
 - 主代理派发执行型子代理前必须先创建子 issue，并把主要任务、接续上下文、目标分支/worktree、范围、禁止项和验收入口写入子 issue 正文；子代理 prompt 只给子 issue 链接和极短边界，不塞大段任务正文。每个执行型子代理维护自己的子 issue 和评论作为接续上下文；主 issue 评论区只由主代理写入主线 anchor、阶段汇总、调度决策和最终 closeout。
 - 子代理不得把过程日志、单步证据、长调查和 post-task 反馈直接堆到主 issue 评论区，只能在主 issue 需要可见时由主代理引用子 issue/PR/comment 链接。
+- 主代理跟踪子代理进度时优先读取子 issue 评论区、关联 PR 更新和 bounded issue/PR 状态；不要为了普通进度查询主动 `send_input interrupt` 打断子代理主线。只有子 issue/PR 长时间无更新且只读 worktree 也无推进时，才进入问询、关闭和重开流程。
 - 每个子代理 prompt 必须写清 repo、目标分支、独立 worktree、issue/PR、禁止触碰范围、验收命令、证据字段和是否允许部署；不要让多个子代理共享同一可写 worktree。
 - 用户指定模型（例如 `gpt-5.5`）时，主代理调度子代理必须在任务描述或调度参数中显式遵守。
 - 用户要求或授权“按任务难度分配模型”时，主代理必须按复杂度选择模型与 reasoning effort，并在 prompt 中写明选择理由；默认继承主模型，只有任务难度、风险或延迟收益明确时才显式覆盖。
@@ -32,6 +32,7 @@
 - 主 issue 评论区由主代理独占维护：只写主线 anchor、阶段汇总、调度决策、已采纳结论、下一批边界和最终 closeout。子代理不得直接在主 issue 评论区堆过程、日志、单步证据或 post-task 反馈；需要让主线可见时，由主代理在主 issue 引用子 issue/PR/comment 链接。
 - 主代理派发执行型子代理前必须先创建子 issue，不能把主要任务正文直接塞进 subagent prompt。子 issue 标题应能反映父 issue、运行面/模块和子任务；正文必须引用父 issue、目标分支/worktree、允许范围、禁止范围、验收入口、模型/思考等级选择理由和当前接续链接。子代理的调查、单步证据、阻塞、post-task 和后续接力评论都写在自己的子 issue 或关联 PR 中。
 - 子代理 prompt 只传子 issue 链接、模型要求和“不写父 issue 评论区”等极短边界；不要在 prompt 里复述长任务、历史结论、日志或完整证据。主代理通过观察子 issue 评论区跟踪进度。
+- 主代理跟踪进度时优先读子 issue 评论区、关联 PR body/comment 和 bounded issue/PR 状态；不要用主动问讯替代评论区观察，因为 `send_input interrupt` 会打断子代理主线任务。普通进度跟踪不使用 `interrupt=true`；只有纠偏、停止、权限/边界变更或多轮无更新后的接续处理才直接发消息给子代理。
 - issue/PR/comment 是子代理之间传递上下文的稳定介质。主代理派发前必须先读取父 issue 的主线 anchor 和相关子 issue/PR/comment，在 prompt 中用链接引用已确认事实、证据、阻塞点和禁止重复范围；不要复制粘贴或复述长结论。子代理开始前也要打开这些链接复用结论，除非评论已过期、与新证据冲突或主代理要求复核。
 - 调查型子代理优先把结论写入自己的子 issue comment 或子 issue 正文的调查段；主代理再根据调查结论决定修复子任务，而不是让调查子代理直接扩大 scope。
 - 调查评论要写成可接力格式：结论、证据来源、未覆盖范围、下一步建议和可直接复用的命令/对象名。不要只写口头判断，也不要把无界日志或大 JSON 贴进评论；长证据放 artifact/drill-down，评论只放 bounded 摘要和链接。
@@ -79,9 +80,9 @@ Prompt 至少包含以下字段，按任务裁剪：

 ## 无响应接续

- 子代理超过当前任务合理等待窗口未回复时，先发一次明确的进度快照请求，要求返回当前 gate/文件/PR/阻塞和下一步；不要立即重复派发同一任务。
- 第一次问询仍无结果时，主代理可以只读检查该子代理声明或可推断的 worktree、分支、PR 和 issue comment：只看 `git status`、`git log`、`git diff --stat`、PR body 和最近 comment，不改文件、不抢实现、不重跑运行面验证。
- 只读检查后再发一次更窄的问询，把已观察到的 worktree/branch/diff 事实告诉子代理，并要求它确认或继续最小下一步。
+- 子 issue/PR 超过当前任务合理等待窗口没有新评论或更新时，先只读检查子 issue 评论区、关联 PR、声明或可推断的 worktree 和分支：只看 `git status`、`git log`、`git diff --stat`、PR body 和最近 comment，不改文件、不抢实现、不重跑运行面验证。
+- 只读检查显示仍在推进时，继续通过子 issue/PR 观察，不主动打断子代理。只读检查也无推进时，再发一次明确且短的进度快照请求，要求返回当前 gate/文件/PR/阻塞和下一步。
+- 第一次问询仍无结果时，再发一次更窄的问询，把已观察到的 worktree/branch/diff 事实告诉子代理，并要求它确认或继续最小下一步。
 - 多次问询仍无响应时，关闭旧子代理，避免长期占用并发和上下文；随后在原 worktree/原分支/原 issue/原 PR 边界上重开新子代理接续。若原 worktree 已被 merge closeout 清理，新子代理应从最新目标分支创建同任务名 worktree；若原 worktree 仍在且有未提交改动，新子代理必须先读取并保护这些改动，不得 reset、checkout 或删除。
 - 重开的子代理 prompt 必须引用旧子代理的子 issue、最后 PR/comment 链接、原 worktree 路径、当前分支/HEAD 和主代理只读观察结论；不要复述长日志，也不要让新子代理重复已经由子 issue/comment 确认的调查。