GitHub 子代理工作流

本 reference 记录 UniDesk 主代理调度子代理、并结合 GitHub issue/PR 的稳定工作流。它约束的是协作方式，不替代 $unidesk-gh 的具体命令参数，也不替代各业务 skill 的验收标准。

调度原则

执行型任务默认且必须交给 Artificer。用户泛称“子代理”“并行代理”或“派代理”不等于授权原生子代理；只有用户明确指定原生子代理，或 Artificer 经有界 readiness、最短真实派单或 typed failure 证明不可用时，才允许原生执行面。
主代理不能以方便、速度、空闲槽、已有 worktree、任务较短或历史习惯作为原生降级理由。Artificer 故障修复可由原生子代理承担；管理性与决策性工作仍由主代理直接完成。
主代理先明确总目标、目标 repo/branch/lane、架构方向和不可倒退边界，再拆任务。不能把“决定架构是否倒退”“是否关闭用户问题”“是否合并 PR”整体外包给子代理。
主代理直接审核子代理产出的 diff、验证证据和 PR。允许子代理实施、要求并行或多轮审查都不授权审核子代理；只有用户明确要求子代理审核时，才建立独立审核任务。
只有低耦合任务才并行：不同 worktree、不同模块或不同 issue，产物可以独立 review，失败不会阻塞其他任务继续产出证据。
高耦合任务先串行定锚：公共类型/契约、source-of-truth、请求治理 authority、共享 runtime policy、同一大文件或同一状态机的修改，应先由主代理或一个子代理形成基线，其他子代理基于基线继续。
任务要按成功率分层：调查、工具增强、业务修复、验证、PR review、上线 closeout 可以并行，但“修同一个根因的两套实现”通常不应并行。
重复失败与基础设施不可靠的停止条件：
- 同一验证或修复连续重复失败且没有新证据时，停止继续试错；
- 派单、构建、测试、部署或观测基础设施不可靠时也必须停止；
- 在子 issue 留下已验证证据、影响范围和恢复条件；
- 不得以人工补跑或更深任务层级掩盖阻塞。
主代理需要持续调度，而不是把多个子任务排队串行执行。用户明确要求并行且任务在不同 worktree 时，应同时派发能并行的子任务，并通过 issue/PR 状态汇总。
主代理必须维护可安全并发窗口：
- 从原始任务建立依赖图，区分串行定锚、已就绪任务和等待依赖任务；
- 每次定锚完成、子代理终态或依赖变化后重新计算已就绪集合，并立即补派低耦合任务；
- 并发目标是 min(已就绪独立任务数, 可用执行槽, 运行面安全容量)，不硬编码固定数量；
- 当两个及以上任务已就绪却长期只有一个活跃子代理时，必须视为调度缺口并补派，不能把主代理活动计入子代理并发；
- 只有具名依赖、共享文件冲突、权限或运行面容量阻塞时才降低并发，并把原因和下一次重算触发点写入主线 anchor。
并发不能靠重复调查、同根因的多套实现、无独立验收价值的日志采集或默认审核代理虚增；每条并发线都必须有独立 issue、worktree、交付物和验收入口。
派发 CI/CD 或运行面调优子任务时，主代理不要在 prompt 或评论里反复解释历史；用 issue/comment 链接引用既有结论，把下一步限定为可由子代理自主真实触发的单步 gate，并要求子代理在该 gate 内小闭环调优到通过后再提交 PR。

恢复优先与工程化并发

依赖图必须先标出运行面恢复关键路径和用户原入口恢复标准。主代理控制恢复关键路径，避免多个代理同时修改同一生产对象、恢复状态机或共享配置。
恢复优先指先让用户原入口通过既有受控路径恢复到可验证状态，不表示工程化任务整体串行：
- 恢复关键路径上的最小诊断、配置修正和复测按真实依赖顺序执行；
- 必要的运行面 patch 由 $unidesk-daddev P2 约束，只证明方向或临时恢复；不得把 patch 状态当作 source authority、自动交付成功或最终验收；
- 与根因解耦的 CLI、reference、报告、独立仓库修复和长期治理，在具备独立 issue、TaskTree Task、worktree、PR 与验收入口时立即并行；
- 只有缺少受控恢复入口直接阻塞恢复时，才允许把工具修改放到恢复关键路径。
运行面恢复后，主代理继续完成根因修复、持久化配置、自动交付、原入口复测和治理收口；不得以临时恢复或单次手工成功代替用户要求的终态。
P2 patch 验证成立后，主代理必须把变化收敛到 owning YAML、源码或 renderer，通过正常 PR 与自动 CI/CD/GitOps 交付，并撤销 patch 或确认其已被声明式交付覆盖。
恢复期间降低并发必须有具名原因，例如共享生产对象、同一状态机、权限边界或运行面容量；原因解除后立即重新计算可安全并发窗口。

模型与思考等级

Artificer 默认不显式覆盖模型：
- 使用 owning AipodSpec 的默认模型，当前为 gpt-5.6-sol，默认 reasoning effort 为 medium；
- API credential 只来自 UniDesk owning YAML 声明的 /root/.codex/auth.json.pika 与 /root/.codex/config.toml.pika，运行时 identity 为 gpt-pika SecretRef；
- 显式 model/reasoning override 只改变模型参数，不改变 provider、SecretRef 或 API 来源；
- 禁止把 credential value、宿主 sourceRef 或 provider 切换约定写入 prompt。
原生子代理默认继承主代理当前模型；只有用户要求/授权按任务难度分配，或任务风险与复杂度明确需要时，才在原生调度参数中指定模型、reasoning effort 和必要的 service tier。
gpt-5.4 / medium 适合边界清楚、低风险、可独立完成的任务：bounded grep、单文件/单模块源码定位、issue 评论整理、已知命令验证和窄范围文档更新。
gpt-5.4 / high 适合需要跨多个文件或 YAML source-of-truth 判断但仍是只读或单模块边界的任务：源码/YAML 路径追踪、单运行面只读分析、低耦合实现设计和 PR bounded review。
gpt-5.5 / high 适合跨运行面、CI/CD 状态机、共享契约、架构倒退风险或根因不明的任务：branch-follower/Tekton/Argo/runtime 联合分析、复杂可见性设计、高风险 PR review 和需要主代理后续决策的方案比较。
gpt-5.5 / xhigh 只用于需要全局架构取舍、多个 repo/运行面同时受影响、错误成本高且等待时间可以接受的任务；不要把 routine 状态查询、机械重命名、普通 issue 评论或单文件修改派给 5.5/xhigh。
子代理 prompt 必须写明“模型/思考等级选择理由”。如果多个子任务并行，低风险采集类用较轻模型，架构边界和共享状态机判断用较强模型；不要让高成本模型重复做已经由低成本子代理能可靠完成的采集工作。

Worktree 和边界

每个写代码的子代理使用独立 .worktree/<task>，从最新目标分支创建；不得共用主 worktree 或其他子代理 worktree。
子代理 prompt 必须写明禁止范围：不能回滚他人改动，不能触碰无关运行面，不能用 destructive git 命令，不能绕过项目受控 CLI。
主代理发现子代理 worktree clean 且提交已被目标分支祖先吸收后，才可清理该 worktree；并行 worker 未合入、脏改或归属不明时保留。
大于项目阈值的文件、共享状态机或高风险运行面修改，主代理必须单独 review 是否满足当前项目结构规则，不能只看 PR 绿灯。

GitHub Issue 协作

大任务先有 GitHub issue 或在既有 issue 中补并行计划：列出子任务、负责人/子代理、目标分支、预期 PR、验证入口、依赖关系和哪些任务可并行。
Artificer 派单采用 fail-closed 登记顺序：
- 先创建子 issue，冻结目标分支、工作区、范围、禁止项和验收入口；
- 再使用 $unidesk-tasktree 在对应 TaskGroup 中创建或更新 Task、登记子 issue 链接并标记进行中；
- 只有上述写入成功后，才允许 AgentRun create task、apply 或 dispatch；
- 缺少 TaskGroup、Task、进行中状态或子 issue 链接时不得派单，派单后补写不算合规。
派单后的协调状态直接复用 TaskTree 与 AgentRun task/run/command/session；普通新 session 接续、重试和 closeout 不新增锁、租约、第二状态库、证明链或围栏。证据保持为有界摘要与稳定链接；只有直接保护业务资源、不可逆操作或明确损害风险的最小 guard 才属于例外。
执行派单和 review 返工默认创建新 task/session：
- 用户未在当前请求中明确要求继续、恢复或复用指定 session 时，不得用 agentrun send、return 或 turn 触发已有 session；
- 新 session 从子 issue、TaskTree、PR、commit 和旧 session 的只读结果接续，不复制无界上下文；
- 复用原 worktree 前必须确认旧 writer 已终态，避免两个 session 并发写入。
主 issue 评论区由主代理独占维护：只写主线 anchor、阶段汇总、调度决策、已采纳结论、下一批边界和最终 closeout。子代理不得直接在主 issue 评论区堆过程、日志、单步证据或 post-task 反馈；需要让主线可见时，由主代理在主 issue 引用子 issue/PR/comment 链接。
主代理派发执行型子代理前必须先创建子 issue，不能把主要任务正文直接塞进 subagent prompt。子 issue 标题应能反映父 issue、运行面/模块和子任务；正文必须引用父 issue、目标分支/worktree、允许范围、禁止范围、验收入口、模型/思考等级选择理由和当前接续链接。子代理的调查、单步证据、阻塞、post-task 和后续接力评论都写在自己的子 issue 或关联 PR 中。
子代理 prompt 只传子 issue 链接、模型要求和“不写父 issue 评论区”等极短边界；不要在 prompt 里复述长任务、历史结论、日志或完整证据。主代理通过观察子 issue 评论区跟踪进度。
主代理跟踪进度时优先读子 issue 评论区、关联 PR body/comment 和 bounded issue/PR 状态；不要用主动问讯替代评论区观察，因为 send_input interrupt 会打断子代理主线任务。普通进度跟踪不使用 interrupt=true；只有纠偏、停止、权限/边界变更或多轮无更新后的接续处理才直接发消息给子代理。
issue/PR/comment 是子代理之间传递上下文的稳定介质。主代理派发前必须先读取父 issue 的主线 anchor 和相关子 issue/PR/comment，在 prompt 中用链接引用已确认事实、证据、阻塞点和禁止重复范围；不要复制粘贴或复述长结论。子代理开始前也要打开这些链接复用结论，除非评论已过期、与新证据冲突或主代理要求复核。
调查型子代理优先把结论写入自己的子 issue comment 或子 issue 正文的调查段；主代理再根据调查结论决定修复子任务，而不是让调查子代理直接扩大 scope。
调查评论要写成可接力格式：结论、证据来源、未覆盖范围、下一步建议和可直接复用的命令/对象名。不要只写口头判断，也不要把无界日志或大 JSON 贴进评论；长证据放 artifact/drill-down，评论只放 bounded 摘要和链接。
主代理每轮阶段切换时在 issue 中留下短 anchor comment，说明哪些结论已经被采纳、哪些路径不再重复查、下一批子代理只需要补哪一段；后续子代理必须以该 anchor 链接为上下文起点，prompt 里引用该链接即可。
修复型子代理提交 PR，并在 PR body 写明目标合并分支、关联 issue、变更范围、验证命令、风险和证据。除非用户明确授权，子代理不合并自己的 PR。
需要修改 issue/PR 正文时使用 $unidesk-gh 或 trans gh:/... apply-patch；不得用原生 gh 或手写 GitHub API 绕过。
issue closeout 必须由主代理核对真实入口证据。代码合并、测试通过或子代理口头报告不能替代用户入口/原入口验证。
每个子代理完成主任务后，主代理必须发送 post-task 收口要求；如果主代理发现需要纠偏、补证据或返工，应先让子代理完成纠偏，再发送 post-task。post-task 只收集反馈和后续问题线索，不应让子代理自行扩大代码修改范围。
子代理按 $post-task 自行输出已判断的 feedback 候选、疑似归属和是否建议转正式 issue；主代理不负责反馈池去重，不代替子代理维护 [FEEDBACK] issue。主代理只从子代理提好的 feedback 中挑选适合直接工程化的项，另起正式 FEATURE/BUG issue 后继续调度。
feedback 转正式 issue 后，优先派回提出该 feedback 的子代理执行，使调查上下文和修复上下文保持连续；只有该子代理不可用或任务边界已变化时才派给其他子代理。
feedback 明确能减少下次同类任务不必要工具调用时，主代理可以直接建立正式 issue、登记 TaskTree 并派后续子代理改进工具、文档或 skill，无需再次等待用户确认。该任务使用独立 worktree/PR 并与业务主线并发，不能成为当前业务交付门禁，也不能借机扩展未经授权的业务或安全范围。
post-task 派单只按完整 logical operation 做幂等重放：
- tenant/project、Aipod、TaskTree Task、Target、repository/ref、绝对 targetWorkspace、源码提交和最终 payload hash 任一不同都不是重复任务；
- 显式 key 与 canonical fingerprint 冲突时保留全部 task 并输出 typed evidence；
- identity 缺失、投影陈旧或权威终态不确定时只 warning，不允许按 dispatch/session/时间窗口批量取消 task。

PR 工作流

子代理 PR 应小而可审：一个根因、一个模块边界、一个目标 issue；跨模块架构 PR 必须在 body 中写明为什么不是局部修补。
主代理一旦确认整个 PR 的授权目标、架构方向、data flow 或 source of truth 错误，不得要求原 PR 继续修补：
- PR 未合并时，先关闭 PR 并停止旧 writer；保留有界证据后，从最新目标分支创建新分支、新 worktree、新 task/session 和新 PR；
- PR 已合并时，先创建只包含该 PR 精确反向变更的 revert PR；回滚合并并恢复目标分支后，再创建正确实现 PR；
- 不在同一个 PR 中混合“回滚错误架构”和“实现新架构”，避免无法独立验证恢复基线；
- 只有局部实现缺陷时才在原 PR 内修正，不能把方向性错误降级成普通 review comment。
主代理本人 review：
- 先看架构约束和倒退风险，再看实现细节；
- 重点检查是否重新引入旧 authority、并行请求源、裸 API 绕过、隐藏默认、阈值硬编码或降低探针能力；
- 默认不再派审核子代理。
合并前使用 $unidesk-gh 的 bounded review 和 guarded merge 入口；pr merge 已内建 preflight，普通已审 PR 不机械重复执行独立 pr preflight。独立 PR 可以并行 review；有依赖的 PR 按契约基线、实现、验证工具、closeout 的顺序合并。
子代理 PR 合并后，主代理负责同步目标 worktree、触发受控 CI/CD、执行原入口复测，并把 PipelineRun、GitOps revision、observer、trace、report SHA 等证据写回 issue。
若用户明确让子代理“自己上线自己验证”，子代理可以执行受控 CI/CD 和原入口验证，但必须在 issue/PR 留下完整证据；主代理仍要抽查并最终汇总。

子代理 Prompt 模板

Prompt 至少包含以下字段，按任务裁剪：

任务：阅读并执行 <子 issue URL>
模型要求：<用户指定模型或按难度选择的模型/思考等级；写明选择理由>
边界：只在子 issue 和关联 PR 维护上下文，不写父 issue 评论区；按子 issue 正文的 worktree/范围/验收执行
交付：返回子 issue comment URL、PR/commit URL、验证摘要、风险、阻塞

主要任务、背景、范围和验收写在子 issue 正文；prompt 应足够短，只引用子 issue 和必要边界，不塞入无界日志、长 JSON、完整 issue dump 或大段调查复述。长证据和既有结论用 issue/comment/PR 链接、artifact path 或 bounded collect/analyze 命令引用。

主代理调度循环

建立计划：列出可并行任务、串行依赖和每个子代理交付物。
为每个执行型子代理先创建子 issue，把任务正文写进子 issue。
使用 $unidesk-tasktree 把子 issue 登记到对应 TaskGroup/Task 并标记进行中；登记失败时停止派单。
计算当前可安全并发窗口并同时派发全部已就绪的低耦合子任务；共享契约先派一个基线任务。
- Artificer 的 create task、apply 和 dispatch 均只能发生在 TaskTree 登记之后。
轮询子代理结果：子 issue comment、PR、验证摘要、阻塞；任一任务终态或依赖变化后立即重新计算窗口并补派，不能退化为长期单任务等待。
对每个 PR 做架构 review、bounded diff 和必要本地验证；方向错误时按“关闭或精确 revert 后重建”处理，只有局部实现缺陷才进入新 session 返工；只有定点排障时单独执行 preflight，正常收口直接使用内建 readiness 的 guarded merge。
按依赖顺序合并；合并后同步目标 worktree。
触发受控 CI/CD 或让明确授权的子代理上线；主代理核对 closeout。
用原入口复测；把剩余问题拆到新 issue 或追加既有 issue。
对每个已完成或已纠偏完成的子代理发送 post-task 收口要求，读取其已判断 feedback；主代理只挑选适合工程化的项转正式 FEATURE/BUG issue，并优先派回原子代理执行。
主代理 post-task：长期参考、清理已吸收 worktree；不代替子代理做 feedback 池去重。

无响应接续

子 issue/PR 超过当前任务合理等待窗口没有新评论或更新时，先只读检查子 issue 评论区、关联 PR、声明或可推断的 worktree 和分支：只看 git status、git log、git diff --stat、PR body 和最近 comment，不改文件、不抢实现、不重跑运行面验证。
只读检查显示仍在推进时，继续通过子 issue/PR 观察，不主动打断子代理。只读检查也无推进时，再发一次明确且短的进度快照请求，要求返回当前 gate/文件/PR/阻塞和下一步。
第一次问询仍无结果时，再发一次更窄的问询，把已观察到的 worktree/branch/diff 事实告诉子代理，并要求它确认或继续最小下一步。
多次问询仍无响应时，关闭旧子代理，避免长期占用并发和上下文；随后在原 worktree/原分支/原 issue/原 PR 边界上重开新子代理接续。若原 worktree 已被 merge closeout 清理，新子代理应从最新目标分支创建同任务名 worktree；若原 worktree 仍在且有未提交改动，新子代理必须先读取并保护这些改动，不得 reset、checkout 或删除。
重开的子代理 prompt 必须引用旧子代理的子 issue、最后 PR/comment 链接、原 worktree 路径、当前分支/HEAD 和主代理只读观察结论；不要复述长日志，也不要让新子代理重复已经由子 issue/comment 确认的调查。

常见错误

把能并行的不同 worktree 子任务排成串行，导致总体等待被单个任务拖住。
让多个子代理改同一 worktree、同一分支或同一大状态机，最后靠主代理手工冲突合并。
子代理只写“已完成”，没有 PR、issue comment、验证命令和证据字段。
主代理只凭 preflight 合并，不做架构倒退 review。
子代理为了通过验证降低 WebProbe/哨兵/CI/CD 能力，或绕过 $unidesk-gh、$unidesk-cicd、$unidesk-webdev 受控入口。
用户要求子代理自上线自验证时，主代理完全不审计运行面证据。

20 KiB Raw Blame History Unescape Escape