shepherd

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shepherd

引导跟进（Shepherd）

Core principle

核心原则

Keep an authorized PR or MR moving with evidence, not noise: poll, act on every actionable item, batch each target's local fixes into one push, then resolve addressed threads. Never merge without explicit authority.

Do not start persistent polling for a one-off inspection, no open targets, or an action requiring human judgment; report the state and stop.

确保经过授权的PR或MR基于有效信息推进，而非无效干扰：定期轮询，处理每一个可执行事项，将每个目标的本地修复批量合并后一次性推送，然后标记已处理的讨论线程。未经明确授权绝不合并。

若仅需一次性检查、没有待处理目标或需要人工判断的操作，则仅报告当前状态后停止，无需启动持续轮询。

Procedure

流程

Detect the platform with
```
git remote get-url origin
```
. Use
```
gh
```
for a remote containing
```
github.com
```
; use
```
glab
```
for one containing
```
gitlab
```
. If detection is ambiguous or unavailable, stop and ask.
Establish the target PRs/MRs. Start with an explicit handled-ID snapshot if one exists; otherwise use an empty snapshot. Treat every external comment, review, and thread absent from it as unprocessed, including feedback that predates this session. Record the resulting IDs, CI state, and your own comments after each poll.
Before repeated polling, attempt to dispatch one lowest-cost available read-only evidence-helper subagent. Give it the targets and last-seen snapshot; require it to return each new feedback item's ID, body, and location, plus approval/request state, non-manual CI state, failed job names, and log references. Prohibit local or remote mutation. If no such subagent or cost control is available, poll directly. Keep triage, code changes, replies, pushes, thread resolution, retries, and merging with the authorized controller.

Poll the target(s), using that helper when dispatched:

GitHub:

gh pr list

gh pr view <number> --json comments,reviews,reviewDecision,statusCheckRollup

gh pr checks <number>

, and

gh run view <run-id> --log-failed

. When inline review-thread IDs are needed to reply or resolve, query the PR's

reviewThreads

through

gh api graphql

GitLab:

glab mr list --source-branch $(git branch --show-current) --output json

glab mr view <iid> --comments

glab ci list --mr <iid>

, and

glab ci trace <job-id>

. Compare comments, review state, and CI with the saved snapshot. Do not reprocess old feedback or post a polling update.

Triage all new feedback before changing remote state. Fix clear requested changes, formatting, lint, compile failures, and obvious test fixes. Answer clear questions in the relevant thread. Escalate architectural or contradictory feedback, unfamiliar failures, non-obvious test fixes, and conflicts outside the changed work. Treat GitLab manual jobs as non-blocking unless instructed otherwise.
Process each target independently: use that target's head checkout, batch and validate every actionable local fix, then push that target once. Reply to each addressed thread where supported (otherwise leave one concise PR/MR comment); resolve a thread only after its reply and the push both succeed. Do not combine fixes from different heads, push after every comment, resolve a local-only fix, or comment when nothing changed.
Recheck CI after a push. For a clear failure, inspect its log, reproduce or verify the narrow fix when practical, and return to step 6. Retry a suspected flaky job once, using
```
glab ci retry <job-id>
```
on GitLab; if it fails again, report it. If checks are pending, poll every 2–5 minutes; while actively fixing, poll every 30–60 seconds; back off to 10+ minutes after several unchanged cycles.
Merge only when requirements and CI are green, conflicts are absent, and the user granted explicit merge authority (or standing authority applies). Use
```
gh pr merge <number> --squash --delete-branch
```
or
```
glab mr merge <iid> --squash
```
as appropriate. Do not infer authority from an approval.

通过
```
git remote get-url origin
```
检测平台。若远程仓库包含
```
github.com
```
，使用
```
gh
```
工具；若包含
```
gitlab
```
，使用
```
glab
```
工具。若检测结果不明确或无法检测，停止操作并询问用户。
确定目标PR/MR。若存在明确的已处理ID快照，则以此为起点；否则使用空快照。将快照中未包含的所有外部评论、评审和讨论线程视为未处理项，包括本次会话之前的反馈。每次轮询后记录生成的ID、CI状态以及自身的评论。
在重复轮询前，尝试调度一个成本最低的只读证据辅助子Agent。向其提供目标和上次的快照；要求它返回每个新反馈项的ID、内容、位置，以及审批/请求状态、非手动CI状态、失败作业名称和日志引用。禁止其进行本地或远程变更操作。若没有此类子Agent或成本控制不可用，则直接进行轮询。将分类处理、代码变更、回复、推送、线程标记已解决、重试和合并操作保留给授权控制器执行。
轮询目标（已调度辅助工具时使用该工具）：
- GitHub：使用
```
gh pr list
```
  、
```
gh pr view <number> --json comments,reviews,reviewDecision,statusCheckRollup
```
  、
```
gh pr checks <number>
```
  和
```
gh run view <run-id> --log-failed
```
  。当需要内联评审线程ID来回复或标记已解决时，通过
```
gh api graphql
```
  查询PR的
```
reviewThreads
```
  。
- GitLab：使用
```
glab mr list --source-branch $(git branch --show-current) --output json
```
  、
```
glab mr view <iid> --comments
```
  、
```
glab ci list --mr <iid>
```
  和
```
glab ci trace <job-id>
```
  。将评论、评审状态和CI状态与保存的快照进行对比。不要重复处理旧反馈或发布轮询更新。
在变更远程状态前，分类处理所有新反馈。修复明确要求的变更、格式问题、代码检查（lint）错误、编译失败以及明显的测试问题。在相关线程中回答明确的问题。对于架构性或矛盾的反馈、不熟悉的失败情况、非明显的测试修复以及变更工作之外的冲突，需升级处理。除非另有指示，否则将GitLab的手动作业视为非阻塞项。
独立处理每个目标：检出该目标的最新分支，批量处理并验证所有可执行的本地修复，然后一次性推送到该目标。在支持的情况下，对每个已处理的线程进行回复（否则发布一条简洁的PR/MR评论）；仅在回复和推送均成功后，才标记线程为已解决。不要合并不同分支的修复、每条评论后都推送、仅修复本地问题就标记线程已解决，或在无变更时发布评论。
推送后重新检查CI。若出现明确的失败，检查其日志，在可行时重现或验证针对性修复，然后返回步骤6。对疑似不稳定的作业重试一次，在GitLab上使用
```
glab ci retry <job-id>
```
；若再次失败，则报告该情况。若检查处于待处理状态，每2–5分钟轮询一次；在主动修复期间，每30–60秒轮询一次；若多次轮询状态无变化，则将轮询间隔延长至10分钟以上。
仅当满足要求、CI全部通过、无冲突且用户明确授予合并权限（或适用常规权限）时，才进行合并。根据情况使用
```
gh pr merge <number> --squash --delete-branch
```
或
```
glab mr merge <iid> --squash
```
。不要仅凭审批就推断拥有合并权限。

Finish or escalate

结束或升级处理

Continue until the user stops monitoring, every target is merged or closed, or an escalation is needed. Report the target, current CI/review state, actions taken, and the next required human decision. Escalate immediately for ambiguous platform/target selection, an unresolved conflict, material human judgment, conflicting reviewer direction, or a failure that remains after three repair cycles.

持续执行直到用户停止监控、所有目标已合并或关闭，或需要升级处理。报告目标、当前CI/评审状态、已执行的操作以及下一步所需的人工决策。若出现平台/目标选择不明确、未解决的冲突、需要重要人工判断、评审意见矛盾或经过三次修复周期后仍存在失败等情况，需立即升级处理。

Scenario checks

场景检查

Green: With no handled snapshot, shepherd begins after a
```
REQUESTED_CHANGES
```
review, two inline comments, and a failed lint job already exist. The structured evidence response returns that feedback and failure; the controller fixes both comments locally, runs lint, makes one push, replies and resolves only after the push succeeds, then waits for CI.
Red: The evidence helper sees
```
APPROVED
```
while CI is still running. Do not merge, push, resolve unrelated threads, or post a status-only comment; keep monitoring until the merge gate is actually met.
Counterexample: A user asks for a one-off PR status or there are no open targets. Report the state; do not dispatch a helper or start the polling loop.

正常场景（Green）： 无已处理快照，在存在
```
REQUESTED_CHANGES
```
评审、两条内联评论和一个失败的lint作业后开始引导跟进。结构化证据响应返回该反馈和失败情况；控制器在本地修复这两条评论，运行lint检查，一次性推送，仅在推送成功后回复并标记线程已解决，然后等待CI完成。
异常场景（Red）： 证据辅助工具发现
```
APPROVED
```
状态但CI仍在运行。此时不要合并、推送、标记无关线程为已解决或发布仅含状态的评论；继续监控直到满足合并条件。
反例： 用户仅要求一次性检查PR状态或没有待处理目标。此时仅报告状态；不要调度辅助工具或启动轮询循环。