shepherd

Shepherd

核心原则

通过证据而非噪声，推动已获授权的 PR 或 MR 持续进行：轮询、处理新出现的可执行事项，将每个目标的本地修复合并为一次推送，然后解决已处理的讨论串。修复时运行受影响的本地检查，并在有意义的集成候选版本上运行必要的完整检查；将 CI 作为确认。未经明确授权，绝不合并。

如果只是一次性检查、没有待处理目标，或需要人工判断的操作，不要启动持续轮询；报告状态后停止。

流程

1. 使用 git remote get-url origin 检测平台：GitHub 使用 gh，GitLab 使用 glab。如果无法确定或不可用，请停止并询问。如果主机提供会在 PR 事件发生时唤醒本会话的 PR 监控工具，例如 Claude 桌面版的 ccd_pr 工具，请先加载已列出但被延后的工具，然后遵循 主机管理的监控，而不是轮询。项目控制器及其工单 Agent 仍遵循 Project 的等待规则，因为一个会话只能绑定一个 PR。
2. 确定目标并建立已处理 ID 快照。快照中不存在的每条外部评论、审查或讨论串都是新的，包括会话开始前的反馈。每次轮询后，记录反馈 ID、CI 状态以及此控制器的评论。确定每个目标的报告和修复责任归属。复用提供的交付记录和保留的实施责任人。对于没有交付记录的独立 PR，使用其现有 PR/报告上下文和 shepherd 快照；从经过验证的 PR 和仓库证据中补充源代码范围、base/head、先前结论、发现和处理情况，并将缺失的证据标记为未知。若不存在保留的工作流责任人，经授权的控制器可在核实目标检出版本/head 且不存在竞争写入者后，负责范围内的修复；在写入代码或移交实施修复前，记录此回退安排。如果责任归属或写入者状态尚未明确，只读审计仍可检查已验证的冻结候选版本；应将这些缺口报告为重大不确定性，不得因此授予写入权限或解除发布门槛。不得根据提交作者身份推断责任人账号。保留已记录的责任人；若责任人不可用、现有责任声明不确定或写入者状态未知，则暂停代码写入，直到问题得到协调；任何明确的责任重新分配前，都必须先确保写入者停止写入。此回退安排既不能补足缺失的范围，也不能授予额外权限。获取目标以及相关唤醒时，即使没有修复，也要根据 PR 审查时机核实当前 head 适用的审查启动情况；一次性检查保持只读。
3. 在控制器中读取常规 PR/MR 证据。仅当需要回答有关大型失败 CI 日志的某个具体诊断问题时，才使用只读辅助 Agent。按照共用的 选择与交接参考选择并向其说明任务。提供确切目标、head、失败的作业和日志、待回答的问题以及有界的结果格式：诊断、支持结论的日志引用和不确定性。它不得执行变更，也不得接管轮询。由经授权的控制器负责分流、修复、回复、推送、解决、重试和合并。
4. 使用平台 CLI 轮询，并按照提供方命令操作，然后将完整的审查、评论和 CI 状态与快照进行比较。仅在必要时检查失败日志。不要重新处理旧反馈，也不要仅为更新状态而发布评论。在主机管理的监控模式下，每次唤醒只读取一次；绝不启动计时器、循环或重复轮询。
5. 执行远程变更前，先对新证据进行分流。修复明确提出的要求以及范围较窄的格式、lint、编译或测试失败；在讨论串中回答明确的问题。对于相关边界情况、两轮收敛审计、审查覆盖范围和浏览器失败证据，遵循行为审查与修复。使用第 2 步确定的报告上下文和修复责任人；远程变更仍由经授权的控制器负责。 对架构性或相互矛盾的反馈、陌生的失败、不明显的修复以及范围外的冲突，进行升级处理。除非另有指示，否则 GitLab 手动作业不构成阻塞条件。
6. 在各自的 head 检出目录中处理每个目标，并批量处理已知的可操作事项。修复前检查失败日志，并根据实际的工作流/检查配置确定适用的本地等效检查。如果缺少证据，应先获取证据，再决定修复方案；如实报告此主机上不可用的检查。修复期间运行有针对性的检查，并复用仍然有效的证据；推送前，应在具有实际意义的集成候选版本上运行所需的完整检查，但以下情况除外：PR 所需的 CI 会运行相同的完整套件，且仓库或提供方规则不要求本地运行；此时，在接受交付或合并前，已推送 head 上的 CI 将提供该证据。推送前，根据 PR 审查时机获取或更新适用的独立审查。遵守更严格的仓库/提供方规则；如果影响未知，则重新运行受影响的检查，或扩大检查范围。 不要将 CI 用作迭代式测试运行器，也不要要求每个切片提交都运行完整检查。推送前所需检查失败或缺少证据时，应暂缓推送；由 CI 提供的完整套件则作为接受或合并的门槛。每次 head 变更后，都要根据 PR 审查时机重新评估证据；推送修复前，更新受影响的独立审查。 变更得到处理或问题得到回答后再回复；只有在回复和所需推送成功后，才解决相应讨论串。不要合并多个 head，不要在每条评论后都推送，不要解决仅在本地修复的问题，也不要在没有变更时发表评论。
7. 确认修复已推送后，重新检查 CI；如再次出现与代码相关的失败，则返回第 6 步。怀疑 GitLab 作业为间歇性失败时，在不改动代码的情况下重试一次；若再次失败，则报告该失败。每隔 2–5 分钟轮询待处理检查，每隔 30–60 秒轮询进行中的修复；连续三轮或更多轮没有变化后，改为每隔 10 分钟或更久轮询。连续两轮无变化时，仍按正常的 2–5 分钟间隔轮询。在主机管理的监控模式下，推送后立即结束本轮。
8. 刷新并核实确切的 head；仅当所有必需检查、审查和发现处理均通过且适用于该 head、不存在冲突，且用户已授予明确或长期有效的合并权限时，才进行合并。不要根据批准推断合并权限。在主机管理的监控模式下，绿色 CI 永远不会唤醒本会话，因此对于待处理的远程门槛，应使用 PR 审查时机中经验证的执行规则；升级处理时，禁用此控制器启用的自动合并。

完成或升级处理

继续执行，直到用户停止监控、所有目标都已合并或关闭，或需要升级处理。报告目标、当前 CI／审查状态、已采取的操作、实际运行的检查（如果没有运行任何检查，请说明）、无法使用或未知的检查，以及下一步需要人工做出的决定。在由主机管理的监控下，还要列出监控不会因哪些事件而唤醒。描述修复周期时，按以下顺序进行：检查失败日志（如果日志缺失，请索要确切的检查名称、日志、PR 差异、分支头和检查配置，并说明哪些本地等效检查尚未确定）；将修复与该 PR 中明确的审查请求一并处理；在所需主机上运行受影响的 CI 等效检查；复用仍然有效的证据；按照第 6 步完成集成候选检查；仅推送一次；以 CI 作为确认。不要声称执行过未运行的步骤。遇到平台／目标选择含糊、存在未解决的冲突、需要重大人工判断、审查者意见冲突，或问题在三轮修复后仍未解决时，立即升级处理。