pikasTech-unidesk/.agents/skills/unidesk-subagent/SKILL.md

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

# UniDesk 子代理调度

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

## 高频规则

- 涉及 PK01 的派单默认只允许只读调查：
  - 只有用户在当前请求中明确要求修改 PK01，子 issue、TaskTree Task 或代理 prompt 才能授权修改其版本、配置、Secret 绑定、边缘路由、容器或运行面；
  - 泛化的修复、恢复、部署和排障目标不构成 PK01 变更授权。
- 派单元数据不得使用白名单式阻塞校验：
  - issue、TaskTree、遗留 MDTODO、标题、仓库标签和其他治理字段只作为关联与可见性元数据；
  - CLI 可以记录缺失、未知或非推荐格式并输出非阻塞 warning，但不得按允许值、前缀、正则或枚举白名单拒绝核心派单；
  - 只有用户明确要求某个白名单成为门禁，或认证、权限、目标唯一性与不可逆损害预防确实要求时，才允许阻断；
  - 新增白名单式阻塞前必须取得用户对该具体门禁的明确授权，禁止以治理便利、历史格式或测试断言自行扩大。
- 主代理与子代理必须按用户明确目标控制实现范围：
  - 未经用户明确要求，禁止新增或扩展通用合同、租约、安全机制、围栏及其配套门禁；
  - 既有权限、Secret 脱敏、不可逆操作和损害预防边界继续生效，本规则不授权绕过既有安全底线；
  - 发现衍生问题时，只能创建独立 issue 或记录待办，不得扩大当前 prompt、PR、合并范围或验收前置；
  - 现有机制阻碍原始目标时，先寻找既有架构内的最小实现路径；确需架构扩展时，必须向用户说明与原始目标的关系并取得明确授权。
  - bug fix 不得擅自改变 event authority、transport、persistence、replay 或 source of truth；发现现有架构可能是根因时，也必须先完成证据和规格裁决。
  - 涉及事件、投影、实时、回放或持久化的派单，主代理必须在子 issue 中先写出 current data flow 和 desired data flow；两者存在架构变化时，先更新长期 SPEC 并取得用户明确授权，再允许实施。
  - 新增测试只能验证已经授权的合同，不能用测试通过把未经授权的架构变化、迁移依赖或新 authority 合法化。
  - 主代理审核顺序固定为：先比较用户最新目标、适用 SPEC 和 current/desired data flow，再审核代码内部一致性、测试和实现质量；后者通过不能覆盖前者偏离。
  - 发现整个 PR 的授权目标、架构方向、data flow 或 source of truth 错误时，禁止在该 PR 上继续补丁：
    - 未合并 PR 直接关闭并停止其 writer，从最新目标分支创建新分支、新 worktree 和新 PR；
    - 已合并 PR 先创建只做精确回滚的独立 revert PR，合并回滚后再从恢复后的目标分支开始正确实现；
    - 局部实现缺陷不冒充整 PR 方向错误；判定依据必须是用户最新目标、适用 SPEC 和 current/desired data flow。
- 执行型和调研型委派必须使用 AgentRun `Artificer`：
  - 只有用户明确指定原生子代理，或 Artificer 经有界 readiness、最短真实派单或 typed failure 证明确实不可用时，才允许改用原生子代理；
  - Artificer 的 `create task`、`apply` 和 `dispatch` 必须以下文“子 issue + TaskTree”登记为 fail-closed 前置；禁止先创建 task 或派单再补登记；
  - 原生子代理和 Artificer 每次派单前都必须已有对应 TaskTree Task；派单 prompt 与最终报告必须写明同一个 Task ID；
  - 新执行任务和 review 返工默认创建新的 task/session：
    - 除非用户在当前请求中明确要求继续、恢复或复用指定 session，禁止用 `agentrun send`、return 或 turn 把任务派给已有 session；
    - 旧 session 只作为只读上下文和证据来源，新 session 通过 issue、PR、TaskTree 和 commit 接续；
    - 新 writer 开始前必须确认旧 writer 已终态，禁止两个 session 并发写同一 worktree。
  - Artificer 协调状态只复用 TaskTree 与 AgentRun 已有的 task/run/command/session 资源：
    - 普通派单、新 session 接续、重试和 closeout 不得另建锁、租约、证明链、第二状态库或配套围栏；
    - 审查证据只保留 issue/PR/commit、验证摘要和必要下钻链接，不复制无界日志或构造额外实证体系；
    - 只有直接保护真实业务资源、不可逆操作或明确损害风险时才允许最小 guard，且只覆盖实际风险窗口并在风险解除后立即释放；
  - Artificer 的 `create task` 外层入口：
    - 必须使用与子 issue / TaskTree 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 只能在修复自动上线后作为被测对象，执行最短新 session canary 或业务验收；
  - 用户只说“子代理”“并行代理”或“派代理”时，不构成原生子代理例外，仍必须使用 Artificer；
  - 主代理不得因为方便、速度、空闲并发槽、已有原生 worktree、历史习惯或预计任务较短而自行降级到原生子代理；管理性、决策性工作由主代理直接完成，不构成原生子代理例外；
  - Artificer 已被证明确实不可用时，先创建独立 issue 和 TaskTree Task，再派一个原生子代理修复 Artificer；只有与故障修复解耦且用户明确要求继续的紧急业务任务，才允许临时使用原生子代理，并必须在 Artificer 恢复后交接；不得把临时 fallback 固化为长期调度入口；
  - Artificer 恢复后，原生子代理必须在 clean commit、PR 或只读报告 checkpoint 停止继续扩展；主代理通过原 issue、TaskTree 和 session 传递接续上下文，再由 Artificer 接替尚未完成的工作；禁止两个执行面共享可写 worktree、重复提交或并发修改同一任务；
  - 管理性、决策性文档仍由主代理负责，不为了满足 Artificer 优先规则而外包治理决策。
- 子代理并发必须从用户原始任务的依赖图出发主动扩展：
  - 主代理先识别串行定锚项、已就绪任务和后续依赖，再计算当前可安全派发集合；
  - 串行定锚完成后，应立即并发派出所有低耦合、可独立验收且具备独立 worktree/branch/issue/PR 的已就绪任务，直到达到可用执行槽、运行面资源预算或真实依赖边界；
  - 存在两个及以上已就绪任务时，长期只运行一个子代理属于调度失败：
    - 主代理必须补派；
    - 无法补派时，在当前 anchor 中写明具名依赖、共享文件冲突、运行面容量或权限阻塞；
    - 每个任务终态和依赖变化后重新计算可安全派发集合；
  - 主代理自己的审核、规划和等待不计入子代理并发量；不得用一个长期任务加主代理活动宣称已经并行；
  - 不得为了凑并发拆出无独立价值的日志采集、重复调查、重复实现或审核代理；并发量服从原始任务边界和成功率，不服从固定数字。
- 运行面故障、用户原入口不可用，或凭据/配置变更导致服务退化时，必须先恢复运行面，再完成工程化：
  - 主代理先冻结恢复判定标准，并保留恢复关键路径的控制权；
  - 优先用既有受控入口实施最小、可逆、可验证的恢复，只有受控入口本身缺失并直接阻塞恢复时，才在关键路径修改工具；
  - 调试或临时恢复需要运行面 patch 时，按 `$unidesk-daddev` P2 执行：
    - 先冻结对象、影响范围、预期与回退方式；
    - patch 只用于验证或临时恢复，不得伪造 source/ref、GitOps 或交付终态；
    - 最终必须写回 owning YAML、源码或 renderer，走正常 PR 与自动 CI/CD，
      并撤销 patch 或确认其已被声明式交付覆盖；
  - 通用抽象、输出优化、skill、报告和长期治理不得成为恢复门禁；
  - 恢复达到用户原入口可用的标准后，主代理不得把临时恢复当作任务完成，必须继续完成用户明确要求的根因修复、工程化、PR、验证和治理；
  - 与恢复根因解耦且具备独立 issue、TaskTree Task、worktree 和验收入口的工程化任务，必须在恢复期间立即并行派发，不得全部排到恢复之后串行执行。
- 子代理并行只用于成功率高、耦合度低、能放进独立 worktree/branch/issue/PR 的任务；共享架构方向、公共契约和同文件高冲突修改先串行定锚。
- 子代理产出的审核默认由主代理直接完成：
  - 用户允许子代理实施、要求并行或启用多轮审查，不等于允许调度审核子代理；
  - 只有用户明确要求子代理审核、独立审核代理或多代理交叉审核时，才允许派发审核型子代理；
  - 主代理发现问题后，直接形成纠偏要求；实现返工默认派给新的 task/session，不新增审核代理，也不把返工 send 给原执行 session。
- 子代理执行必须遵守停止条件：
  - 只有每次定位、修复或复测都产生新证据，且所依赖基础设施保持可靠时，才继续小闭环；
  - 同一失败连续重复且没有新证据时，停止继续试错、叠加补丁或拆更深任务；
  - 发现派单、构建、测试、部署或观测基础设施不可靠时：
    - 停止业务任务；
    - 报告已验证证据、影响范围和恢复条件；
    - 不得用人工补跑伪造成功；
  - 停止后由主代理判断是等待基础设施恢复、建立独立基础设施 issue，还是在用户新增授权后改走其他路径。
- 管理性、决策性文档由主代理直接完成，不把决策权或治理写入外包给子代理：
  - 主代理负责 `AGENTS.md`、skill 核心规则、长期 reference 规范、架构决策、主 issue anchor/closeout，以及 TaskGroup/Task 结构和状态治理；
  - 子代理可以在已明确的 issue、TaskTree Task 和验收边界内独立调研，并编写对应 ExecutionReport、验证记录、实现说明和证据附件；
  - 子代理报告只承载其任务事实与结论，不能自行改写上层目标、架构取舍、优先级、主线状态或跨任务治理规则；
  - 主代理审阅子代理报告后，亲自把被采纳的结论写入管理性、决策性文档。
- 纯文档交付可以按 `$git-spec` 的稳定分支快路径由主代理直接 commit/push，不要求临时 branch、`.worktree` 或 PR；发现本地分叉、并行改动、分支保护或运行面影响时必须保留状态并回到隔离交付。
- 正式 GitHub issue/PR/comment/merge 仍走 `$unidesk-gh`；子代理可以提交 PR 和写调查结论，主代理负责 bounded review 和 guarded merge，独立 preflight 只用于定点排障，除非用户明确授权某个子代理自上线自验证。
- 主代理和子代理必须通过 issue/PR/comment 链接传递可复用上下文、调查结论、证据链接和下一步边界；派发前先读既有评论，prompt 中只引用链接和增量任务，不复述长结论，避免不同子代理重复调查同一事实。
- 主代理派发任何执行型子代理前必须完成以下登记；对 Artificer，全部步骤必须早于 AgentRun `create task`、`apply` 和 `dispatch`：
  - 创建子 issue，把主要任务、接续上下文、目标分支/worktree、范围、禁止项和验收入口写入正文；
  - 使用 `$unidesk-tasktree` 在对应 TaskGroup 中创建或更新 Task、登记子 issue 链接，并把任务标记为进行中；
  - 任一登记缺失或写入失败时不得创建 AgentRun task；派单后补写 TaskTree 不计为合规登记。
  - 派单 prompt 必须写入 Task 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，不等待主代理逐步批准；
  - 只有每轮产生新证据且基础设施可靠时才继续；
  - 同一失败重复无新证据、基础设施不可靠、架构边界、权限缺失或需要主代理合并/取舍时立即停止并报告；
  - 不得把每个单步验证退回主代理做无界大回环。
- 需要提交 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，并优先派回提出该反馈的子代理执行。
- post-task 派单与去重必须限制在同一 canonical logical operation：
  - identity 至少同时绑定 tenant/project、Aipod、TaskTree Task、Target、repository/ref、绝对 targetWorkspace、源码提交和最终 payload hash；同一 operation 重放只复用原 task；
  - 不得按同一 post-task dispatch、时间窗口、session、标题、Issue 前缀或列表邻近关系把多个 task 归为重复；
  - 不同 payload 复用 idempotency key 必须输出 typed conflict，保留所有 task，禁止通过 cancel 猜测性收敛；
  - identity 不完整、task input 不可读、投影陈旧或终态事实不一致时只输出 warning，并停止 destructive cancellation；
  - post-task cleanup 不得取消 sibling task；取消只用于用户明确授权的目标，或同一 task/attempt 的受控终止。
- post-task 反馈明确有助于达到“下次同类任务可以减少不必要工具调用”时，主代理可以直接创建对应 issue、登记 TaskTree，并派后续子代理改进工具、文档或 skill，无需再次等待用户确认：
  - 仍须遵守子 issue、TaskTree、独立 worktree、目标分支、受控 GitHub 入口和主代理审核要求；
  - 改进任务必须与原业务主线隔离并优先并发推进，不得成为当前业务交付、合并或上线门禁；
  - 不得借反馈扩展业务功能、安全机制、权限契约、审计门禁或其他未经授权的范围。
- 主代理结束条件：
  - 当前用户任务只要派出过子代理：
    - 主代理就必须保持任务进行中；
    - 等待本轮全部子代理进入真实终态；
    - 不得把 task 创建成功、dispatch 成功、`running`、已提交 commit 或已创建 PR 当作主代理可以结束的交付点；
    - 等待期间仍要维护并发窗口：
      - 任一子代理终态、依赖解除或新任务就绪后，立即重新计算可安全派发集合；
      - 还有独立已就绪任务时及时补派，避免并发窗口退化为长期单任务等待；
      - 只有具名依赖、共享写入边界、运行面容量或权限阻塞时才允许保持较低并发，并把理由写入主线 anchor。
  - 子代理返回后，主代理必须继续完成职责范围内的收尾：
    - 完成必要的纠偏和 post-task；
    - 审核 PR 并执行获授权的合并；
    - 同步目标分支；
    - 完成任务要求的自动交付、线上验证或原入口复测。
  - 主代理还必须完成治理收尾：
    - 完成对应 issue closeout；
    - 写入 ExecutionReport 并更新 Task 状态；
    - 清理已吸收的 worktree 和分支；
    - 确认没有本轮子代理遗留的必要收尾后，才可以向用户结束当前任务。
  - 不得以“异步派发”“非阻塞支线”或“后续再观察”为由提前结束。
  - 只有满足以下任一条件时才可停止等待：
    - 用户明确取消或暂停；
    - 出现需要用户新增授权且无法继续的外部阻塞。
  - 因取消、暂停或外部阻塞停止等待时，不得把任务报告为已完成。

## 主线与支线隔离

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

## 常用配合技能

- GitHub issue/PR 正式读写、preflight、merge：`$unidesk-gh`。
- AgentRun / Code Queue / AipodSpec 任务派发：`$unidesk-agentrun`。
- CI/CD、rollout、PipelineRun、Argo closeout：`$unidesk-cicd`。
- WebProbe、Workbench、浏览器复测：`$unidesk-webdev`。
- 子代理完成后的反馈收口和反馈 issue 判定：`$post-task`。
- Artificer 和其他执行型子代理派单前的任务登记必须使用 `$unidesk-tasktree`；遗留 MDTODO 的处理也统一遵循该 skill。

## 何时读取 reference

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