GitHub Subagent Workflow

本 reference 记录 UniDesk 主代理调度子代理、并结合 GitHub issue/PR 的稳定工作流。它约束的是协作方式，不替代 $unidesk-gh 的具体命令参数，也不替代各业务 skill 的验收标准。

调度原则

主代理先明确总目标、目标 repo/branch/lane、架构方向和不可倒退边界，再拆任务。不能把“决定架构是否倒退”“是否关闭用户问题”“是否合并 PR”整体外包给子代理。
只有低耦合任务才并行：不同 worktree、不同模块或不同 issue，产物可以独立 review，失败不会阻塞其他任务继续产出证据。
高耦合任务先串行定锚：公共类型/契约、source-of-truth、请求治理 authority、共享 runtime policy、同一大文件或同一状态机的修改，应先由主代理或一个子代理形成基线，其他子代理基于基线继续。
任务要按成功率分层：调查、工具增强、业务修复、验证、PR review、上线 closeout 可以并行，但“修同一个根因的两套实现”通常不应并行。
主代理需要持续调度，而不是把多个子任务排队串行执行。用户明确要求并行且任务在不同 worktree 时，应同时派发能并行的子任务，并通过 issue/PR 状态汇总。

模型与思考等级

默认不显式覆盖模型，继承主代理当前模型；只有用户要求/授权按任务难度分配，或任务风险与复杂度明确需要时，才在子代理调度参数中指定模型、reasoning effort 和必要的 service tier。
gpt-5.4 / medium 适合边界清楚、低风险、可独立完成的任务：bounded grep、单文件/单模块源码定位、issue 评论整理、已知命令验证和窄范围文档更新。
gpt-5.4 / high 适合需要跨多个文件或 YAML source-of-truth 判断但仍是只读或单模块边界的任务：源码/YAML 路径追踪、单运行面只读分析、低耦合实现设计和 PR bounded review。
gpt-5.5 / high 适合跨运行面、CI/CD 状态机、共享契约、架构倒退风险或根因不明的任务：branch-follower/Tekton/Argo/runtime 联合分析、复杂可见性设计、高风险 PR review 和需要主代理后续决策的方案比较。
gpt-5.5 / xhigh 只用于需要全局架构取舍、多个 repo/运行面同时受影响、错误成本高且等待时间可以接受的任务；不要把 routine 状态查询、机械重命名、普通 issue 评论或单文件修改派给 5.5/xhigh。
子代理 prompt 必须写明“模型/思考等级选择理由”。如果多个子任务并行，低风险采集类用较轻模型，架构边界和共享状态机判断用较强模型；不要让高成本模型重复做已经由低成本子代理能可靠完成的采集工作。

Worktree 和边界

每个写代码的子代理使用独立 .worktree/<task>，从最新目标分支创建；不得共用主 worktree 或其他子代理 worktree。
子代理 prompt 必须写明禁止范围：不能回滚他人改动，不能触碰无关运行面，不能用 destructive git 命令，不能绕过项目受控 CLI。
主代理发现子代理 worktree clean 且提交已被目标分支祖先吸收后，才可清理该 worktree；并行 worker 未合入、脏改或归属不明时保留。
大于项目阈值的文件、共享状态机或高风险运行面修改，主代理必须单独 review 是否满足当前项目结构规则，不能只看 PR 绿灯。

GitHub Issue 协作

大任务先有 GitHub issue 或在既有 issue 中补并行计划：列出子任务、负责人/子代理、目标分支、预期 PR、验证入口、依赖关系和哪些任务可并行。
主 issue 评论区由主代理独占维护：只写主线 anchor、阶段汇总、调度决策、已采纳结论、下一批边界和最终 closeout。子代理不得直接在主 issue 评论区堆过程、日志、单步证据或 post-task 反馈；需要让主线可见时，由主代理在主 issue 引用子 issue/PR/comment 链接。
每个执行型子代理必须有自己的子 issue 作为上下文容器。子 issue 标题应能反映父 issue、运行面/模块和子任务；正文必须引用父 issue、目标分支/worktree、允许范围、验收入口和当前接续链接。子代理的调查、单步证据、阻塞、post-task 和后续接力评论都写在自己的子 issue 或关联 PR 中。
issue/PR/comment 是子代理之间传递上下文的稳定介质。主代理派发前必须先读取父 issue 的主线 anchor 和相关子 issue/PR/comment，在 prompt 中用链接引用已确认事实、证据、阻塞点和禁止重复范围；不要复制粘贴或复述长结论。子代理开始前也要打开这些链接复用结论，除非评论已过期、与新证据冲突或主代理要求复核。
调查型子代理优先把结论写入自己的子 issue comment 或子 issue 正文的调查段；主代理再根据调查结论决定修复子任务，而不是让调查子代理直接扩大 scope。
调查评论要写成可接力格式：结论、证据来源、未覆盖范围、下一步建议和可直接复用的命令/对象名。不要只写口头判断，也不要把无界日志或大 JSON 贴进评论；长证据放 artifact/drill-down，评论只放 bounded 摘要和链接。
主代理每轮阶段切换时在 issue 中留下短 anchor comment，说明哪些结论已经被采纳、哪些路径不再重复查、下一批子代理只需要补哪一段；后续子代理必须以该 anchor 链接为上下文起点，prompt 里引用该链接即可。
修复型子代理提交 PR，并在 PR body 写明目标合并分支、关联 issue、变更范围、验证命令、风险和证据。除非用户明确授权，子代理不合并自己的 PR。
需要修改 issue/PR 正文时使用 $unidesk-gh 或 trans gh:/... apply-patch；不得用原生 gh 或手写 GitHub API 绕过。
issue closeout 必须由主代理核对真实入口证据。代码合并、测试通过或子代理口头报告不能替代用户入口/原入口验证。
每个子代理完成主任务后，主代理必须发送 post-task 收口要求；如果主代理发现需要纠偏、补证据或返工，应先让子代理完成纠偏，再发送 post-task。post-task 只收集反馈和后续问题线索，不应让子代理自行扩大代码修改范围。
子代理按 $post-task 自行输出已判断的 feedback 候选、疑似归属和是否建议转正式 issue；主代理不负责反馈池去重，不代替子代理维护 [FEEDBACK] issue。主代理只从子代理提好的 feedback 中挑选适合直接工程化的项，另起正式 FEATURE/BUG issue 后继续调度。
feedback 转正式 issue 后，优先派回提出该 feedback 的子代理执行，使调查上下文和修复上下文保持连续；只有该子代理不可用或任务边界已变化时才派给其他子代理。

PR 工作流

子代理 PR 应小而可审：一个根因、一个模块边界、一个目标 issue；跨模块架构 PR 必须在 body 中写明为什么不是局部修补。
主代理 review 时先看架构约束和倒退风险，再看实现细节。重点检查是否重新引入旧 authority、并行请求源、裸 API 绕过、隐藏默认、阈值硬编码或降低探针能力。
合并前使用 $unidesk-gh 的 review/preflight/merge 入口。独立 PR 可以并行 review；有依赖的 PR 按契约基线、实现、验证工具、closeout 的顺序合并。
子代理 PR 合并后，主代理负责同步目标 worktree、触发受控 CI/CD、执行原入口复测，并把 PipelineRun、GitOps revision、observer、trace、report SHA 等证据写回 issue。
若用户明确让子代理“自己上线自己验证”，子代理可以执行受控 CI/CD 和原入口验证，但必须在 issue/PR 留下完整证据；主代理仍要抽查并最终汇总。

子代理 Prompt 模板

Prompt 至少包含以下字段，按任务裁剪：

任务：<一句话目标>
模型要求：<用户指定模型或按难度选择的模型/思考等级；写明选择理由>
Repo/Branch：<repo> <target branch/lane>
Worktree：从最新 <target branch> 创建独立 .worktree/<task>；不得使用主 worktree
Issue/PR：关联 <issue>；修复完成后提交 PR；调查完成后评论 issue
范围：允许修改 <paths/modules>；禁止修改 <paths/runtime/配置>
架构边界：不得回退 <authority/contract/runtime>; 遵守 <相关 issue/spec>
验证：运行 <最小命令>; 需要原入口证据时使用 <web-probe/cicd/etc>
交付：返回 PR/commit/issue comment URL、验证摘要、风险、阻塞

Prompt 应足够明确，但不要塞入无界日志、长 JSON、完整 issue dump 或大段调查复述。长证据和既有结论用 issue/comment/PR 链接、artifact path 或 bounded collect/analyze 命令引用。

主代理调度循环

建立计划：列出可并行任务、串行依赖和每个子代理交付物。
同时派发低耦合子任务；共享契约先派一个基线任务。
轮询子代理结果：PR、issue comment、验证摘要、阻塞。
对每个 PR 做架构 review、bounded diff、preflight 和必要本地验证。
按依赖顺序合并；合并后同步目标 worktree。
触发受控 CI/CD 或让明确授权的子代理上线；主代理核对 closeout。
用原入口复测；把剩余问题拆到新 issue 或追加既有 issue。
对每个已完成或已纠偏完成的子代理发送 post-task 收口要求，读取其已判断 feedback；主代理只挑选适合工程化的项转正式 FEATURE/BUG issue，并优先派回原子代理执行。
主代理 post-task：长期参考、清理已吸收 worktree；不代替子代理做 feedback 池去重。

无响应接续

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

常见错误

把能并行的不同 worktree 子任务排成串行，导致总体等待被单个任务拖住。
让多个子代理改同一 worktree、同一分支或同一大状态机，最后靠主代理手工冲突合并。
子代理只写“已完成”，没有 PR、issue comment、验证命令和证据字段。
主代理只凭 preflight 合并，不做架构倒退 review。
子代理为了通过验证降低 WebProbe/哨兵/CI/CD 能力，或绕过 $unidesk-gh、$unidesk-cicd、$unidesk-webdev 受控入口。
用户要求子代理自上线自验证时，主代理完全不审计运行面证据。

12 KiB Raw Blame History Unescape Escape