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

name, description

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

UniDesk 子代理调度

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

高频规则

• 主代理与子代理必须按用户明确目标控制实现范围：
  • 未经用户明确要求，禁止新增或扩展通用合同、租约、安全机制、围栏及其配套门禁；
  • 既有权限、Secret 脱敏、不可逆操作和损害预防边界继续生效，本规则不授权绕过既有安全底线；
  • 发现衍生问题时，只能创建独立 issue 或记录待办，不得扩大当前 prompt、PR、合并范围或验收前置；
  • 现有机制阻碍原始目标时，先寻找既有架构内的最小实现路径；确需架构扩展时，必须向用户说明与原始目标的关系并取得明确授权。
• 执行型和调研型委派默认优先使用 AgentRun Artificer：
  • 未显式选模时，不由主代理注入客户端模型默认值；使用 owning AipodSpec 的默认模型，当前为 gpt-5.6-terra；
  • 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 中只引用链接和增量任务，不复述长结论，避免不同子代理重复调查同一事实。
• 主代理派发执行型子代理前必须先创建子 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。
• 用户指定模型时，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，并优先派回提出该反馈的子代理执行。

主线与支线隔离

• 主线执行中遇到可临时缓解的非主线问题时，固定按以下顺序处理：
  • 先创建边界独立的 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。
• 需要 MDTODO 记录和执行-审查循环时再用 $mdtodo-loop；不要把普通 GitHub PR 并行工作强行塞进 MDTODO。

何时读取 reference

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