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 和最终结论的责任。

高频规则

• 涉及 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。