docs: add subagent orchestration skill
This commit is contained in:
Codex
@@ -0,0 +1,28 @@
|
||||
---
|
||||
name: unidesk-subagent
|
||||
description: UniDesk 主代理调度子代理的必读技能。用户提到子代理、subagent、并行代理、主代理调度、gpt-5.5、让子代理调查 issue、提交 PR、上线验证、结合 gh 的子代理工作流时必须使用。
|
||||
---
|
||||
|
||||
# UniDesk Subagent Orchestration
|
||||
|
||||
主代理调度子代理时先读本 skill，再读对应 reference。子代理可以并行推进低耦合任务，但主代理必须保留架构判断、PR 审核、合并顺序、上线 closeout 和最终结论的责任。
|
||||
|
||||
## 高频规则
|
||||
|
||||
- 子代理并行只用于成功率高、耦合度低、能放进独立 worktree/branch/issue/PR 的任务；共享架构方向、公共契约和同文件高冲突修改先串行定锚。
|
||||
- 正式 GitHub issue/PR/comment/merge 仍走 `$unidesk-gh`；子代理可以提交 PR 和写调查结论，主代理负责 review/preflight/merge，除非用户明确授权某个子代理自上线自验证。
|
||||
- 每个子代理 prompt 必须写清 repo、目标分支、独立 worktree、issue/PR、禁止触碰范围、验收命令、证据字段和是否允许部署；不要让多个子代理共享同一可写 worktree。
|
||||
- 用户指定模型（例如 `gpt-5.5`）时，主代理调度子代理必须在任务描述或调度参数中显式遵守。
|
||||
- 子代理完成后必须留下可审查工件：PR、issue comment、commit、验证输出摘要、部署/observer/trace 证据或阻塞说明；主代理不能只凭口头结论合并。
|
||||
|
||||
## 常用配合技能
|
||||
|
||||
- GitHub issue/PR 正式读写、preflight、merge：`$unidesk-gh`。
|
||||
- AgentRun / Code Queue / AipodSpec 任务派发：`$unidesk-code-queue`。
|
||||
- CI/CD、rollout、PipelineRun、Argo closeout：`$unidesk-cicd`。
|
||||
- WebProbe、Workbench、浏览器复测：`$unidesk-webdev`。
|
||||
- 需要 MDTODO 记录和执行-审查循环时再用 `$mdtodo-loop`；不要把普通 GitHub PR 并行工作强行塞进 MDTODO。
|
||||
|
||||
## 何时读取 reference
|
||||
|
||||
- 任何“主代理调度子代理 + GitHub issue/PR”的工作流，必须读 [references/gh-workflow.md](references/gh-workflow.md)。
|
||||
@@ -0,0 +1,72 @@
|
||||
# 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 状态汇总。
|
||||
|
||||
## Worktree 和边界
|
||||
|
||||
- 每个写代码的子代理使用独立 `.worktree/<task>`，从最新目标分支创建；不得共用主 worktree 或其他子代理 worktree。
|
||||
- 子代理 prompt 必须写明禁止范围：不能回滚他人改动，不能触碰无关运行面，不能用 destructive git 命令，不能绕过项目受控 CLI。
|
||||
- 主代理发现子代理 worktree clean 且提交已被目标分支祖先吸收后，才可清理该 worktree；并行 worker 未合入、脏改或归属不明时保留。
|
||||
- 大于项目阈值的文件、共享状态机或高风险运行面修改，主代理必须单独 review 是否满足当前项目结构规则，不能只看 PR 绿灯。
|
||||
|
||||
## GitHub Issue 协作
|
||||
|
||||
- 大任务先有 GitHub issue 或在既有 issue 中补并行计划：列出子任务、负责人/子代理、目标分支、预期 PR、验证入口、依赖关系和哪些任务可并行。
|
||||
- 调查型子代理优先把结论写入 issue comment 或 issue 正文的调查段；主代理再根据调查结论决定修复子任务，而不是让调查子代理直接扩大 scope。
|
||||
- 修复型子代理提交 PR，并在 PR body 写明目标合并分支、关联 issue、变更范围、验证命令、风险和证据。除非用户明确授权，子代理不合并自己的 PR。
|
||||
- 需要修改 issue/PR 正文时使用 `$unidesk-gh` 或 `trans gh:/... apply-patch`；不得用原生 `gh` 或手写 GitHub API 绕过。
|
||||
- issue closeout 必须由主代理核对真实入口证据。代码合并、测试通过或子代理口头报告不能替代用户入口/原入口验证。
|
||||
|
||||
## 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 至少包含以下字段，按任务裁剪：
|
||||
|
||||
```text
|
||||
任务：<一句话目标>
|
||||
模型要求：<如用户指定 gpt-5.5 则写明>
|
||||
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、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：长期参考、反馈去重、清理已吸收 worktree。
|
||||
|
||||
## 常见错误
|
||||
|
||||
- 把能并行的不同 worktree 子任务排成串行，导致总体等待被单个任务拖住。
|
||||
- 让多个子代理改同一 worktree、同一分支或同一大状态机，最后靠主代理手工冲突合并。
|
||||
- 子代理只写“已完成”，没有 PR、issue comment、验证命令和证据字段。
|
||||
- 主代理只凭 preflight 合并，不做架构倒退 review。
|
||||
- 子代理为了通过验证降低 WebProbe/哨兵/CI/CD 能力，或绕过 `$unidesk-gh`、`$unidesk-cicd`、`$unidesk-webdev` 受控入口。
|
||||
- 用户要求子代理自上线自验证时，主代理完全不审计运行面证据。
|
||||
Reference in New Issue
Block a user