shepherd

Shepherd 技能

VCS 提供商

此技能通过 Exarchos MCP 操作（check_ci、list_prs、merge_pr、get_pr_comments、add_pr_comment 等）执行 VCS 操作。 这些操作会自动检测并路由到正确的 VCS 提供商（GitHub、GitLab、Azure DevOps）。 无需使用 gh/glab/az 命令——MCP 服务会处理提供商分派。

此处调用的 merge_pr 是远程 PR 合并原语（synthesize 阶段）。它不同于上游 merge-pending 子状态期间执行的集成合并：在那里，serialize_merge（@skills/merge-orchestrator/SKILL.md）是集成合并路径，会持有单写者租约并组合本地 git merge（原始的 merge_orchestrate 是该组合执行器／非集成路径）。此技能绝不会调用 serialize_merge 或 merge_orchestrate。

通过迭代循环，推动已发布的 PR 通过 CI 检查和代码评审，直至达到可合并状态。所有 PR 健康检查都使用 assess_stack 组合操作，并持续修复失败项、处理反馈，直到整个堆栈通过检查。

注意： Shepherd 不是独立的 HSM 阶段，而是在 synthesize 阶段内运行的循环。在整个 shepherd 迭代周期中，工作流阶段始终为 synthesize。事件（shepherd.iteration、ci.status）和 shepherd_status 视图会跟踪循环进度，无需阶段转换。

在工作流中的位置：

synthesize → shepherd (assess → fix → resubmit → loop) → cleanup
              ^^^^^^^^^ runs within synthesize phase

默认目标

默认情况下，shepherd 致力于 处理 PR 上的每一条反馈——在调用中附加“处理所有反馈”是多余的，因为这是默认行为，并非可选项。每次迭代都力求让以下三个反馈渠道中未处理的事项归零：

• CI／检查 — 修复或解决每项失败或待处理的检查。
• 正式评审 — 处理每个 CHANGES_REQUESTED 评审。
• 行内评论 — 对每条行内评审评论（来自人工、CodeRabbit、Sentry 或机器人）都进行修复和／或回复，不论严重程度如何。轻微或细枝末节的评论仍然是反馈：应予以处理，或回复说明为何有意不采纳。目标是让查看 PR 的人看到每条讨论串都有回复。

assess_stack 仅提供建议：其 computeRecommendation 只会针对严重／主要事项强制要求 fix-and-resubmit，因此即使仍有轻微的 comment-reply 事项，也可能返回 request-approval。不要把这视为跳过这些事项的许可——只有在处理完每一项 comment-reply 行动项（修复或回复）后，才能请求批准。“处理所有反馈”始终是默认要求。

流水线卫生

当流水线积累了过时的工作流（非活动状态超过 7 天）时，在开始新的 shepherd 周期前，运行 @skills/prune/SKILL.md，批量取消已放弃的工作流。使用 exarchos:exarchos_view({ action: "pipeline", scope: "all" }) 查找过时工作流——默认视图仅显示调用者所在仓库的工作流，并隐藏 legacy 行（即在记录仓库身份之前启动的工作流），而这正是本次清理要处理的过时工作流。保护措施会跳过存在未关闭 PR 或近期提交的工作流，因此不会触及活跃的 shepherd 目标。保持流水线整洁，可以让 shepherd 迭代报告更易于阅读，并减少过时数量视图中的干扰。

触发条件

在以下情况下激活：

• 用户运行 shepherd，或说“shepherd”“跟进 PR”“检查 CI”
• PR 已发布，需要持续监控 CI／评审流程
• synthesize 完成且 PR 已进入队列后

前提条件

• 存在已发布 PR 的活跃工作流（PR URL 位于 synthesis.prUrl 或 artifacts.pr 中）
• PR 已创建并推送（已运行 create_pr）
• 可使用 Exarchos MCP 工具执行 VCS 操作

流程

操作手册： 每次 shepherd 迭代都遵循 shepherd-iteration 操作手册： exarchos_orchestrate({ action: "runbook", id: "shepherd-iteration" }) 如果操作手册不可用，请使用 describe 获取操作架构：exarchos_orchestrate({ action: "describe", actions: ["assess_stack"] })

shepherd 循环会持续进行，直到所有 PR 状态正常或满足升级条件。默认：5 次迭代。

步骤 0 — 获取质量信号

每次迭代开始时，查询质量提示以辅助评估：

exarchos:exarchos_view({ action: "code_quality", workflowId: "<featureId>" })

• 如果 regressions 非空，请在状态报告中包含回归情况
• 如果任何提示的 confidenceLevel: 'actionable'，请在迭代摘要中列出 suggestedAction
• 如果任何技能的 gatePassRate < 0.80，请标记质量趋势恶化

此步骤可确保 Agent 在轮询各个 PR 之前，先根据累积的质量信息采取行动。

步骤 1 — 评估

调用 assess_stack 组合操作，一次性检查所有 PR 维度：

exarchos:exarchos_orchestrate({
  action: "assess_stack",
  featureId: "<id>",
  prNumbers: [123, 124, 125]
})

组合操作会在内部处理：

• 检查所有 PR 的 CI 状态
• 检查正式评审状态（APPROVED / CHANGES_REQUESTED）
• 轮询行内评审评论并解决讨论串（Sentry、CodeRabbit、人类评审者）
• 验证堆栈健康状况
• 发送事件：针对每项 CI 检查发送 ci.check_observed 事件（供 CodeQualityView 使用），并针对每个 PR 发送 ci.status 事件（供 ShepherdStatusView 使用）。事件格式请参阅 references/gate-event-emission.md。

查看返回的 actionItems 和 recommendation：

建议	操作
request-approval	仅当每个 comment-reply 条目都已处理时，才跳至步骤 4。如果任何行内评论仍未处理，请按 fix-and-resubmit 处理，并先解决该评论（参见默认目标）。
fix-and-resubmit	继续步骤 2
wait	告知用户，暂停，并在延迟一段时间后重新评估
escalate	请参阅 references/escalation-criteria.md

步骤 2 — 修复

将每项更改锚定到不变量目录（评估时约束）。 在编写任何代码修复之前，加载 .exarchos/invariants.md（标记为 cost-of-load: always-load 的条目），并列出一个 约束 部分，指出修复必须保留的不变量，然后逐一检查每项拟议更改是否符合这些约束。这相当于 shepherd 在评估时执行 ideate 的 Phase 0，并使用同一个共享的事实来源来决定选择规则和目录注册门控：@skills/ideate/references/constraint-anchoring.md。受目录注册门控： 如果 .exarchos.yml: invariants.catalogs 下没有注册目录，则不列出约束部分，直接修复。这样一来，“评估更改时应用 .exarchos/invariants.md”就是默认行为——无需在每次调用时另行请求。

在逐项处理操作项之前，先对它们进行分类，以便循环判断哪些应当直接修复，哪些应当委派。对评估结果的 actionItems 调用 classify_review_items（分类器按文件分组的只是评论回复子集；CI 修复和审查处理项则原样传递）：

exarchos:exarchos_orchestrate({
  action: "classify_review_items",
  featureId: "<id>",
  actionItems: <actionItems from assess_stack>
})

结果会返回 groups: ClassificationGroup[]，每个组都有一个 recommendation：direct（直接处理）、delegate-fixer（为批量／高严重性工作启动修复子 Agent）或 delegate-scaffolder（用于文档细节的小型子 Agent）。按顺序遍历各组，应用相应的组级策略，然后查阅 references/fix-strategies.md，了解各问题类型的详细说明。

修复事件协议（FLYWHEEL）：

1. 应用修复之前，发出 remediation.attempted：

   exarchos:exarchos_event({
     action: "append",
     stream: "<featureId>",
     event: {
       type: "remediation.attempted",
       data: { taskId: "<taskId>", skill: "shepherd", gateName: "<failing-gate>", attemptNumber: <N>, strategy: "direct-fix" }
     }
   })
   

2. 应用修复（CI 失败、回复审查评论、重新整理堆栈）。

3. 下一次评估确认修复解决了门控问题之后，发出 remediation.succeeded：

   exarchos:exarchos_event({
     action: "append",
     stream: "<featureId>",
     event: {
       type: "remediation.succeeded",
       data: { taskId: "<taskId>", skill: "shepherd", gateName: "<gate>", totalAttempts: <N>, finalStrategy: "direct-fix" }
     }
   })
   

这些事件会为 CodeQualityView 中的 selfCorrectionRate 和 avgRemediationAttempts 指标提供数据。

操作项类型：

类型	策略
ci-fix	阅读日志，在本地复现，修复，并提交到堆栈分支
comment-reply	使用 actionItem.reviewer、normalizedSeverity、file、line 和 raw（完整原始评论）撰写回复。servers/exarchos-mcp/src/review/providers/ 下的提供方适配器会填充输入字段——无需手动解析层级。发布： PR 级摘要评论和逐线程内联回复均使用与提供方无关的 add_pr_comment 编排操作——传入 threadId，即可将回复发到特定内联线程中（通过 VcsProvider.addReply）。GitHub 支持内联线程回复；GitLab 和 Azure DevOps 则会明确返回“尚不支持”的能力信号。
review-address	为 CHANGES_REQUESTED 修复代码，并回复每个线程
restack	运行 git rebase origin/<base>，并通过 exarchos_orchestrate({ action: "list_prs" }) 验证
escalate	查阅 references/escalation-criteria.md

每条内联审查评论都必须得到回复。目标是让查看 PR 的人员看到每个线程都有回复。

步骤 3 — 重新提交

应用修复后，重新提交堆栈：

git push --force-with-lease

如有需要，重新启用自动合并：

exarchos_orchestrate({ action: "merge_pr", prId: "<number>", strategy: "squash" })

返回步骤 1，开始下一轮迭代。记录迭代次数，并与上限（默认为 5）对照。如果达到上限时仍未进入 request-approval，请按照 references/escalation-criteria.md 升级处理。

步骤 4 — 请求审批

当 assess_stack 返回 recommendation: 'request-approval'（所有检查均通过，所有评论均已处理）时：

守卫： 请求审批前，确认没有剩余的 comment-reply 操作项。根据默认目标，必须先处理所有行内评论，包括轻微问题和细枝末节。如果还有未处理的评论，请返回步骤 2，而不是请求审批。

不变量一致性检查提示（仅在注册目录时适用，合并前）： 当 .exarchos.yml: invariants.catalogs 中注册了目录时，请在请求审批／合并前，针对 PR 差异运行限定于评审阶段的 check_invariant_conformance 操作，以确保合并关卡读取的架构不变量与即将合入的差异相符。这只是一个提示／辅助功能，并非硬性关卡——该操作不会阻塞（gate: { blocking: false }）；它会显示一致性检查结果，供纳入评审结论，但不会阻止合并。它不是设计时的 Constraints 部分（shepherd 在综合／合并阶段运行，而不是设计阶段）——步骤 2 中的 Constraints 锚定用于组合修复；此处的提示则用于评审／合并关卡上对差异与不变量进行核对。未注册目录时，请跳过此步骤。

exarchos:exarchos_orchestrate({
  action: "check_invariant_conformance",
  featureId: "<id>",
  phase: "review",
  diff: "<PR diff>"
})

1. 通过 GitHub MCP 请求评审：

   mcp__plugin_github_github__update_pull_request({
     owner: "<owner>", repo: "<repo>", pullNumber: <number>,
     reviewers: ["<approver>"]
   })
   

   后备方案（如果 MCP 令牌没有写入权限）：gh pr edit <number> --add-reviewer <approver>

2. 向用户报告：

   ## Ready for Approval
   
   All CI checks pass. All review comments addressed.
   Approval requested from: <approvers>
   
   PRs:
   - #123: <url>
   - #124: <url>
   
   Run `cleanup` after merge completes.
   

状态管理

通过工作流状态跟踪 shepherd 进度：

初始化：

exarchos:exarchos_workflow({
  action: "update",
  featureId: "<id>",
  updates: {
    "shepherd": {
      "startedAt": "<ISO8601>",
      "currentIteration": 0,
      "maxIterations": 5,
      "approvalRequested": false
    }
  }
})

**每轮迭代后：**更新 currentIteration，记录评估摘要和已采取的操作。审批通过后：将 approvalRequested: true 与时间戳和审批者列表一并设置。

阶段转换与守卫

完整的转换表请参阅 @skills/checkpoint/references/phase-transitions.md。

shepherd 技能在 synthesize 阶段内运行，不会直接驱动阶段转换。

架构发现

使用 exarchos_workflow({ action: "describe", actions: ["update", "init"] }) 获取参数架构，使用 exarchos_workflow({ action: "describe", playbook: "feature" }) 获取阶段转换、守卫和剧本指导。发送事件前，使用 exarchos_event({ action: "describe", eventTypes: ["shepherd.iteration", "ci.status", "remediation.attempted"] }) 获取事件数据架构。

事件发送

发送任何 shepherd 事件前，请参阅 references/shepherd-event-schemas.md，了解完整的 Zod 架构、类型约束和示例载荷。使用 exarchos_event({ action: "describe", eventTypes: ["shepherd.iteration", "ci.status"] }) 在运行时发现必填字段。

事件	时机	用途
shepherd.started	技能启动时（由 assess_stack 发送）	审计跟踪
shepherd.iteration	每轮评估后	跟踪进度
ci.check_observed	每项 CI 检查（由 assess_stack 发送）	CodeQualityView — 按技能统计的通过率
ci.status	每项 CI 检查结果	ShepherdStatusView — 跟踪 PR 健康状况
remediation.attempted	应用修复前	selfCorrectionRate 指标
remediation.succeeded	确认修复后	avgRemediationAttempts 指标
shepherd.approval_requested	请求评审时	审计跟踪
shepherd.completed	检测到合并时（由 assess_stack 发送）	审计跟踪

领域知识

请参考以下文档，了解详细指导：

• references/fix-strategies.md — 各类问题的修复方法、响应模板以及补救事件发出的详细说明
• references/escalation-criteria.md — 何时停止迭代并升级给用户
• references/gate-event-emission.md — ci.check_observed 的事件格式（由 assess_stack 发出）
• references/shepherd-event-schemas.md — 全部四种 shepherd 生命周期事件的完整 Zod 对齐模式

决策运行手册

达到迭代次数上限或 CI 反复失败时，请参考升级运行手册： exarchos_orchestrate({ action: "runbook", id: "shepherd-escalation" })

此运行手册根据迭代次数、CI 稳定性和审核状态，提供结构化标准，帮助判断是继续迭代、升级给用户，还是中止 shepherd 循环。

反模式

不要	应改为
直接轮询 CI／审核	使用 assess_stack 组合操作
在 CI 失败时强行合并	先修复失败项
忽略内联评论	通过回复处理每个讨论串
因为 assess_stack 建议 request-approval，就跳过次要／吹毛求疵的评论	先处理每个 comment-reply 项目——该建议仅供参考（参见默认目标）
未检查不变量就编写修复	将每项更改依据 .exarchos/invariants.md（步骤 2，仅在已注册目录时启用）
已注册目录时，未对照不变量检查差异就合并	在批准／合并前，对 PR 差异运行 check_invariant_conformance（步骤 4 的说明，仅在已注册目录时启用，非阻断性）
无限循环	遵守迭代次数限制，并升级处理
跳过补救事件	每次修复都发出 remediation.attempted／remediation.succeeded
直接推送到 main	所有修复都通过堆栈分支进行

转换

获得批准并合并 PR 后，运行 cleanup，将工作流状态解决为已完成。