---
name: unidesk-subagent
description: UniDesk 主代理调度子代理的必读技能。用户提到子代理、subagent、并行代理、Artificer、原生子代理、主代理调度、gpt-5.5、让子代理调查 issue、提交 PR、上线验证、结合 gh 的子代理工作流时必须使用。
---

# UniDesk 子代理调度

主代理调度子代理时先读本 skill，再读对应 reference。子代理可以并行推进低耦合任务，但主代理必须保留架构判断、PR 审核、合并顺序、上线 closeout 和最终结论的责任。

## 高频规则

- 主代理与子代理必须按用户明确目标控制实现范围：
  - 未经用户明确要求，禁止新增或扩展通用合同、租约、安全机制、围栏及其配套门禁；
  - 既有权限、Secret 脱敏、不可逆操作和损害预防边界继续生效，本规则不授权绕过既有安全底线；
  - 发现衍生问题时，只能创建独立 issue 或记录待办，不得扩大当前 prompt、PR、合并范围或验收前置；
  - 现有机制阻碍原始目标时，先寻找既有架构内的最小实现路径；确需架构扩展时，必须向用户说明与原始目标的关系并取得明确授权。
- 执行型和调研型委派默认优先使用 AgentRun `Artificer`：
  - Artificer 的 `create task`、`apply` 和 `dispatch` 必须以下文“子 issue + MDTODO”登记为 fail-closed 前置；禁止先创建 task 或派单再补登记；
  - 原生子代理和 Artificer 每次派单前都必须已有对应 MDTODO ITEM 或 SUBITEM；派单 prompt 与最终报告必须写明同一个 MDTODO ID；
  - Artificer 协调状态只复用 MDTODO 与 AgentRun 已有的 task/run/command/session 资源：
    - 普通派单、续跑、重试和 closeout 不得另建锁、租约、证明链、第二状态库或配套围栏；
    - 审查证据只保留 issue/PR/commit、验证摘要和必要下钻链接，不复制无界日志或构造额外实证体系；
    - 只有直接保护真实业务资源、不可逆操作或明确损害风险时才允许最小 guard，且只覆盖实际风险窗口并在风险解除后立即释放；
  - Artificer 的 `create task` 外层入口：
    - 必须按 owning YAML 选中 Target；
    - 必须通过 `trans <Target>:<unideskWorkspace>` 重入目标节点；
    - 预检、创建、自动派发和观察都在重入后完成；
  - Artificer 的任务 Target 操作必须继续使用 `trans <Target>:<targetWorkspace>`：
    - `targetWorkspace` 必须是任务专属 worktree；
    - 现场探测、Git、编辑、验证和运行面观察都不得在 runner primary workspace 冒充完成；
    - runner primary workspace 只承载默认 UniDesk resource bundle、工具、skill 和轻量准备；
  - 未显式选模时，不由主代理注入客户端模型默认值；使用 owning AipodSpec 的默认模型，当前为 `gpt-5.6-sol`，默认 reasoning effort 为 `medium`；
  - Artificer 的 API credential：
    - 只允许由 UniDesk owning YAML 将 `/root/.codex/auth.json.pika` 与 `/root/.codex/config.toml.pika` 投影为 `gpt-pika` SecretRef；
    - 任务 prompt、task payload、日志和 issue 不携带 credential value；
    - 模型或 reasoning override 不能切换 provider/SecretRef；
  - 只有 Artificer 已通过有界 readiness、最短真实派单或同 session 续跑证据，才判定为可用；单个业务任务失败必须先按 typed reason 判断，不能直接宣告 Artificer 不可用；
  - Artificer 禁止递归修复自身：
    - 影响派单、AipodSpec、provider/model、credential 投影、session/workspace、Runner、AgentRun runtime 或其 CI/CD 可用性的故障，调查与实现必须交给原生子代理；
    - Artificer 只能在修复自动上线后作为被测对象，执行最短 canary、原 session 续跑或业务验收；
  - Artificer 可用时，新任务和可安全接续的剩余任务必须优先交给 Artificer，原生子代理只用于管理性主代理职责以外、且 Artificer 本身修复或恢复所必需的工作；
  - Artificer 已被证明确实不可用时，先创建独立 issue 和泛化问题域 MDTODO，再派一个原生子代理修复 Artificer；紧急且边界独立的业务任务可以暂时派原生子代理，但不得把临时 fallback 固化为长期调度入口；
  - Artificer 恢复后，原生子代理必须在 clean commit、PR 或只读报告 checkpoint 停止继续扩展；主代理通过原 issue、MDTODO 和 session 传递接续上下文，再由 Artificer 接替尚未完成的工作；禁止两个执行面共享可写 worktree、重复提交或并发修改同一任务；
  - 管理性、决策性文档仍由主代理负责，不为了满足 Artificer 优先规则而外包治理决策。
- 子代理并行只用于成功率高、耦合度低、能放进独立 worktree/branch/issue/PR 的任务；共享架构方向、公共契约和同文件高冲突修改先串行定锚。
- 管理性、决策性文档由主代理直接完成，不把决策权或治理写入外包给子代理：
  - 主代理负责 `AGENTS.md`、skill 核心规则、长期 reference 规范、架构决策、主 issue anchor/closeout，以及 MDTODO FILE 的领域划分、ITEM 结构和状态治理；
  - 子代理可以在已明确的 issue、MDTODO ITEM 和验收边界内独立调研，并编写对应任务报告、验证记录、实现说明和证据附件；
  - 子代理报告只承载其任务事实与结论，不能自行改写上层目标、架构取舍、优先级、主线状态或跨任务治理规则；
  - 主代理审阅子代理报告后，亲自把被采纳的结论写入管理性、决策性文档。
- 纯文档交付可以按 `$git-spec` 的稳定分支快路径由主代理直接 commit/push，不要求临时 branch、`.worktree` 或 PR；发现本地分叉、并行改动、分支保护或运行面影响时必须保留状态并回到隔离交付。
- 正式 GitHub issue/PR/comment/merge 仍走 `$unidesk-gh`；子代理可以提交 PR 和写调查结论，主代理负责 review/preflight/merge，除非用户明确授权某个子代理自上线自验证。
- 主代理和子代理必须通过 issue/PR/comment 链接传递可复用上下文、调查结论、证据链接和下一步边界；派发前先读既有评论，prompt 中只引用链接和增量任务，不复述长结论，避免不同子代理重复调查同一事实。
- 主代理派发任何执行型子代理前必须完成以下登记；对 Artificer，全部步骤必须早于 AgentRun `create task`、`apply` 和 `dispatch`：
  - 创建子 issue，把主要任务、接续上下文、目标分支/worktree、范围、禁止项和验收入口写入正文；
  - 使用 `$mdtodo-edit` 在对应泛化问题域的 MDTODO ITEM 或 SUBITEM 中登记子 issue 链接，并把任务标记为进行中；不得为单个 issue 创建窄范围 MDTODO FILE；
  - 任一登记缺失或写入失败时不得创建 AgentRun task；派单后补写 MDTODO 不计为合规登记。
  - 派单 prompt 必须写入 MDTODO ITEM/SUBITEM ID；子代理的阶段报告、PR 说明和最终报告必须回链同一 ID。
- 子代理 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。
- 用户指定模型时，Artificer 通过正式 model/reasoning 调度参数显式覆盖；原生子代理才在任务描述或原生调度参数中遵守。两类调度都不得用 prompt 约定 API credential。
- 用户要求或授权“按任务难度分配模型”时，主代理必须按复杂度选择模型与 reasoning effort，并在 prompt 中写明选择理由；默认继承主模型，只有任务难度、风险或延迟收益明确时才显式覆盖。
- 执行型子代理必须能在自己负责的边界内完成“单步验证 -> 定位 -> 最小修复 -> 复测 -> PR/issue 证据”的闭环；这里的“单步验证”必须是可独立触发、独立执行、独立复测的入口，不是在端到端大循环中被动观察某个阶段。子代理不应停留在解释历史数据或等待主代理逐步批准；在授权边界内应自主真实触发目标侧独立单步 gate 做小闭环调优，测不通就继续细分/修复/复测，直到该单步通过或遇到明确越界阻塞。除非遇到架构边界、权限缺失或需要主代理合并/取舍，不要把每个单步验证都退回主代理通过 issue 大回环推进。
- 需要提交 PR 的子代理必须在 PR 前自行用相关独立单步跑通目标运行面验证并保存 bounded 证据；测不通就继续定位和修改，直到该单步在目标侧通过。只有权限、外部依赖、架构取舍或明确越界时才写 issue 阻塞/缺口，不得先提交 PR 让主代理或自动 follower 替自己联调。
- 主代理 review 子代理 PR 时直接信任子代理对运行结果、target-side gate 和 evidence 的描述；主代理只审核 diff、架构边界、受控入口、YAML-first、职责拆分和是否违反长期规则。除非描述自相矛盾、缺失关键字段或涉及安全/生产高风险，不要重复拉运行面证据或替子代理重跑 gate。
- 子代理完成后必须留下可审查工件：PR、issue comment、commit、验证输出摘要、部署/observer/trace 证据或阻塞说明；主代理不能只凭口头结论合并。
- 子代理长时间无响应时，主代理按“问询 -> 只读检查 worktree/PR/issue -> 再窄问询”的顺序处理；多次问询仍无回复时，可以关闭旧子代理，并在原 worktree/原分支/原 issue 边界上重开新子代理接续。重开前不得删除或重置旧 worktree；新子代理必须先读取原 worktree 状态和既有 issue/PR/comment 链接，再继续最小下一步。
- 子代理完成任务后，主代理必须再给该子代理发送 post-task 收口要求；若主代理要求子代理纠偏或补验证，则等纠偏完成后再发 post-task。post-task 反馈由子代理按 `$post-task` 自行给出判断，主代理不负责反馈池去重；主代理只从子代理提好的反馈中挑选适合工程化的项转成正式 FEATURE/BUG issue，并优先派回提出该反馈的子代理执行。
- 主代理结束条件：
  - 当前用户任务只要派出过子代理：
    - 主代理就必须保持任务进行中；
    - 等待本轮全部子代理进入真实终态；
    - 不得把 task 创建成功、dispatch 成功、`running`、已提交 commit 或已创建 PR 当作主代理可以结束的交付点。
  - 子代理返回后，主代理必须继续完成职责范围内的收尾：
    - 完成必要的纠偏和 post-task；
    - 审核 PR 并执行获授权的合并；
    - 同步目标分支；
    - 完成任务要求的自动交付、线上验证或原入口复测。
  - 主代理还必须完成治理收尾：
    - 完成对应 issue closeout；
    - 写入 MDTODO 任务报告并更新状态；
    - 清理已吸收的 worktree 和分支；
    - 确认没有本轮子代理遗留的必要收尾后，才可以向用户结束当前任务。
  - 不得以“异步派发”“非阻塞支线”或“后续再观察”为由提前结束。
  - 只有满足以下任一条件时才可停止等待：
    - 用户明确取消或暂停；
    - 出现需要用户新增授权且无法继续的外部阻塞。
  - 因取消、暂停或外部阻塞停止等待时，不得把任务报告为已完成。

## 主线与支线隔离

- 主线执行中遇到可临时缓解的非主线问题时，固定按以下顺序处理：
  - 先创建边界独立的 GitHub issue，并在语义化 MDTODO 中引用 issue 链接、根因假设、临时缓解和最终验收入口；
  - 主代理仅通过受控入口执行有界、可逆、可验证的临时缓解，同时保存缓解前后证据和回退方式；
  - 将根因修复交给独立子代理、worktree、branch 和 PR，禁止让支线继续占用主代理主线；
  - 缓解达到继续主线的最低条件后，主代理立即恢复用户原始目标，不等待支线完成。
- 临时缓解不得标记为根因已修复，不得用于关闭支线 issue，也不得引入第二套长期 authority、fallback 或隐藏状态。
- 涉及数据丢失、Secret 暴露、安全边界、不可逆迁移或无法证明影响范围的问题，不属于可直接缓解范围；主代理必须先停止扩大影响，再按对应专项技能处理。

## 常用配合技能

- 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`。
- 子代理完成后的反馈收口和反馈 issue 判定：`$post-task`。
- Artificer 和其他执行型子代理派单前的任务登记必须使用 `$mdtodo-edit`；只有用户明确要求多轮审查或循环修复时才使用 `$mdtodo-loop`。

## 何时读取 reference

- 任何“主代理调度子代理 + GitHub issue/PR”的工作流，必须读 [references/gh-workflow.md](references/gh-workflow.md)。
