技能使用指南

pr-shepherd（PR守护者）Skill 是什么？如何自动守护 PR 直到合并？

PR守护者（pr-shepherd）Skill 让 AI 代理自动监控 PR 直到合并：60 秒轮询 CI 与评论、自动修复 lint 与类型错误、迭代处理评审线程、完成前强制校验状态，合并后沉淀知识。本文讲清安装前提、调用方式、竞品对比与常见坑，帮你把 PR 从创建守到合并。

PR守护者Skillpr-shepherd
8 个章节 约 17 分钟阅读 AI 智能生成

PR守护者（pr-shepherd）：让 AI 代理自动守着你的 PR，直到全部变绿、评论闭环

  • 它是谁：PR守护者（英文名 pr-shepherd，技能ID 13658）是一个专门给 AI 编程代理使用的技能，负责在 PR 创建之后持续监控，直到合并。
  • 它做什么：自动轮询 CI/CD 状态与评审评论，自动修复 lint、Prettier、类型错误和自己写的测试失败，把评论交给配套技能处理，直到「所有检查通过 + 所有线程解决」才宣布完成。
  • 它像一个状态机：监控 → 修复 → 处理评论 → 等待用户 → 完成，每 60 秒用确定性工具 gtg 拉一次真实状态，靠 JSON 的 status 字段决定下一步。
  • 它有边界感：简单问题自己修；测试失败、基础设施故障、模糊错误等复杂问题会停下来，给出 2-4 个选项让你决策，绝不闷头乱改。
  • 它不止管到合并：合并后还会创建知识提取任务、做 RAM 清理，把一次 PR 的经验沉淀下来。

该技能叫什么？如何下载安装 AI 技能提升开发效率？

基本信息

项目 内容
技能中文名 PR守护者Skill
技能英文名 pr-shepherd
技能ID 13658
核心定位 面向「在工作树中工作的 AI 代理」的 PR 全生命周期守护技能

它解决什么问题

在用 AI 代理写代码的工作流里，PR 创建只是开始，真正消耗人力的是后面这一段：CI 挂了要去翻日志、lint 报错要手改、评审机器人（详情中提到的 CodeRabbit、Cursor 等）每个提交都会追加新评论、线程还得一个个回复并 resolve。人一旦离开，PR 就卡在那里。PR守护者把这个「守着 PR」的活交给代理自己：代理拥有自己的 PR 生命周期，协调器（Coordinator）可以放心去干别的任务。

一键安装 AI 技能的思路与步骤

  1. 确认安装前提：你需要一个支持技能（Skill）机制的 AI 代理运行环境，并具备 gh（GitHub CLI，用于 gh pr view、gh repo view、gh pr create）、gtg（PR 状态检查工具，支持 --format json 与 -q 语义退出码）以及项目侧的 pnpm lint、pnpm typecheck、pnpm test 脚本。缺少这些工具时，技能无法完成确定性的状态判定与本地验证。
  2. 在技能库中检索并安装：用技能中文名「PR守护者」或英文名「pr-shepherd」检索，也可用技能ID 13658 精确匹配；安装入口、依赖声明与授权方式以官方说明为准。
  3. 按需配合两个相邻技能：goodtogo:handling-pr-comments（评论处理）与 superpowers:test-driven-development（TDD 修复）；详情中还提到复杂调试可调用 superpowers:systematic-debugging。这些配套技能的安装方式同样以官方说明为准。
  4. 验证是否生效：进入任意已有 PR 的分支，手动调用 /project:pr-shepherd <pr-number>；若技能生效，代理会先宣布「我正在使用 pr-shepherd 技能来监控此 PR 直到合并。我将监视 CI/CD、处理评论，并在问题出现时修复。」随后你会看到它读取 PR 编号、仓库 owner 与 name，并开始 60 秒轮询。
  5. 可选：用包装脚本自动激活：bin/create-pr-with-shepherd.sh 在创建 PR 后会输出守护指令横幅（含 PR 编号与手动调用方式），看到该输出即刻调用技能即可，无需记忆编号。

提示：详情未提供具体的安装命令、市场链接或价格信息，请以官方说明为准。

该技能的主要功能和特点

  • 自动监控 CI/CD：后台每 60 秒调用 gtg <pr> --repo <owner/repo> --format json，解析 .status、.ci_status.state、.threads.unresolved、.actionable_comments 等字段，得到确定性的 PR 状态，而不是靠感觉判断。
  • 状态机驱动，行为可预期：监控 → 修复 → 监控 → 等待用户 → 修复 → 监控 → 完成；每个状态都有明确退出条件，避免代理「瞎忙」或提前收工。
  • 分级自动修复：lint 失败跑 pnpm lint，格式问题跑 pnpm prettier --write，类型错误直接修，自己写的代码测试失败用 TDD 修——这些都无需用户批准；而涉及他人代码的测试失败、基础设施/配置故障、模糊错误，则必须请示。
  • 修复纪律严格：必须本地跑通 pnpm lint && pnpm typecheck && pnpm test --run 才允许推送，绝不推未验证的代码；推送后回到监控状态让 CI 跑。
  • 评论处理不遗漏：新评论到达时委派给 goodtogo:handling-pr-comments，并强制走完该技能阶段 1-7 的迭代循环；推送修复后要检查是否又冒出自动评审机器人的新评论，未确认前不得退出。
  • 范围外评论也有章法：默认把范围外评论当范围内处理；用 ultrathink 评估修复成本，小于 30 分钟、少于 3 个文件的立即修，复杂的开 GitHub Issue 并在线程里链接，且始终回复并解决线程。
  • 完成前强制校验：宣布「可合并」之前必须跑一次 gtg 确认 READY，否则逐条解决 action_items，不允许静默忽略任何顶层评论。
  • 软超时与交接：4 小时后自动打检查点，给出「继续监控 / 退出并交接 / 缩短检查间隔」三选项，交接时输出可恢复的状态报告与 /project:pr-shepherd [编号] 恢复命令。
  • 合并后闭环：创建带 knowledge-extraction 标签的 BEADS 任务并阻塞 Epic，追加 /project:curate-pr-learnings、/project:extract-learnings，最后跑 /project:auto-ram-cleanup 释放测试运行器、构建监视器、重复语言服务器等资源（Docker 容器与基础 IDE 进程保留）。

如何使用该技能？

方式一：手动调用（最直接）

/project:pr-shepherd 123

代理开始守护 PR #123，先播报开场说明，再取 PR_NUMBER、OWNER、REPO，进入监控循环。

方式二：创建 PR 后自动激活

执行 bin/create-pr-with-shepherd.sh 创建 PR，脚本会打印形如「PR守护者活动：PR #123」的横幅并列出将要做的事（监控 CI/CD、自动修复 lint/类型/测试、处理评论、解决线程、报告可合并）。看到横幅立即调用技能，编号直接用横幅里的数字。

方式三：协调器派活

在生成代理的任务提示中写明：在某个工作树的分支上完成实现，创建 PR 后使用 pr-shepherd 技能监控直到合并、自主处理 CI 失败和评论、只把需要用户输入的复杂问题上报、准备好或受阻时汇报，并让它在后台运行。

分步使用指南

  1. 初始化：PR_NUMBER=$(gh pr view --json number -q .number)；若当前分支没有 PR，技能会提示「当前分支未找到 PR。提供 PR 编号。」并退出，此时改用手动传编号。
  2. 拉取状态：gtg "$PR_NUMBER" --repo "$OWNER/$REPO" --format json > /tmp/gtg-status.json，再用 jq -r '.status' 取状态。也可以用 gtg ... -q，靠语义退出码判断：0=READY、1=ACTION_REQUIRED、2=UNRESOLVED_THREADS、3=CI_FAILING、4=ERROR。
  3. 按状态分派：READY 直接收工；ACTION_REQUIRED 打印 action_items 后进入处理评论；UNRESOLVED_THREADS 处理线程；CI_FAILING 打印失败检查名，判断简单就修复、复杂就请示；ERROR 等待用户。
  4. 修复与验证：改完后本地跑 pnpm lint && pnpm typecheck && pnpm test --run，全绿才 git add -A && git commit -m "fix: <描述>" && git push。
  5. 处理评论：进入处理评论状态后交给 goodtogo:handling-pr-comments，走完阶段 1-7，包括推送后迭代复查；不允许手动跳过阶段 7。
  6. 需要决策时：按模板给出 2-4 个选项（含利弊与推荐项），等用户选择后执行再回到修复。
  7. 完成后汇报：输出「PR #[编号] 准备好合并 ✅」以及 CI 状态、线程解决数、提交数；合并后再做知识提取与 RAM 清理。

输入输出示例

输入：/project:pr-shepherd 123。 可能的中途输出：💬 未解决的线程：2 或 ❌ CI失败： - unit-tests。 最终输出：CI：所有检查通过 / 审阅：所有线程解决 / 提交：3 总计（2 修复提交）。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
PR守护者（pr-shepherd） AI 代理侧的 PR 全生命周期守护技能 60 秒轮询 CI 与评论、分级自动修复、评论迭代处理、完成前 gtg 强制校验、合并后知识沉淀与 RAM 清理 需代理环境 + gh + gtg + 项目 lint/typecheck/test 脚本；调用一条 /project:pr-shepherd <编号> 代理自主开发、多人协作仓库、评审机器人频繁留评的项目 优势：状态机清晰、修复有纪律、能理解评论语义并真正改代码；不足：依赖本地工具链与技能生态，复杂问题仍需人工介入
通用 CI 流水线（如自动合并机器人） 仓库侧的自动化规则执行 满足条件自动合并、打标签、触发通知 需编写工作流配置，规则以 YAML 表达 规则稳定、变更简单的仓库 优势：无需代理、稳定可预测；不足：不会读评论、不会改代码，规则之外的失败一律卡住
代码评审机器人（详情提到的 CodeRabbit、Cursor 等） 评审侧自动评论 逐提交生成评审意见与建议 安装应用并授权仓库 需要自动化代码评审的团队 优势：评审覆盖面广；不足：只提问题不解决问题，且每个新提交都会追加评论，反而加重「线程未解决」负担
人工值守 人盯着 PR 手动看 CI、回评论、点重跑 零门槛 低频、关键 PR 优势：判断最灵活；不足：占用人力、响应慢、容易在等待中遗忘

可以看出，PR守护者的差异点在于：它处在「评审机器人」和「自动合并机器人」之间——既读得懂评论，又真的会去改代码，并用 gtg 的确定性状态作为唯一裁判标准。

该技能的典型应用场景与实际体验情况

场景一：独立开发者的深夜提交

个人开发者晚上把功能交给代理实现，代理用包装脚本创建 PR 后自动进入守护。CI 因 prettier 报错挂掉，代理自己跑 pnpm prettier --write、验证、推送，几分钟后 CI 转绿；评审机器人追加了两条评论，代理委派 handling-pr-comments 处理并回复、解决线程。 体验：上手成本主要在于工具链准备（gh、gtg、脚本齐备），配齐后基本是「发出去就不管」。注意点是 60 秒轮询会持续占用代理资源，长任务建议配合 4 小时检查点。

场景二：协调器 + 多代理并行

协调器生成多个代理在不同工作树并行开发，每个代理自行守护自己的 PR，只把复杂问题上报。协调器用 AgentOutputTool 按需查看进度。 体验：这是技能设计的主场——「代理拥有其 PR 生命周期，协调器生成后忘记」。注意事项：务必在任务提示里写清「创建 PR 后使用 pr-shepherd 监控直到合并」，否则代理可能交完代码就结束。

场景三：评审意见密集的开源仓库

评审者留下大量评论，其中部分涉及 PR 差异之外的代码。代理默认视为范围内，先评估成本：简单的立即修并注明原范围外，复杂的开 Issue 并在线程里链接。 体验：详情特别强调「始终回复并解决」，这一点比「改完就算」的机器人体验好很多。注意点：不确定时应当请示，而不是硬改别人的代码。

场景四：一次 Epic 收尾

PR 关闭了 Epic 的最后一个阻塞任务，代理检测到 Epic 完成，创建对话提取任务并阻塞 Epic，提示运行 /project:extract-learnings --historical --recent 10 后依次关闭任务与 Epic，最后执行 /project:auto-ram-cleanup。 体验：把「架构决策、调试发现、集成怪癖」这些不在评审评论里的知识捞了出来。注意点：详情说明该 Epic 检测模式假设单 Epic 工作流，多 Epic 并行时需手动把 PR 任务关联到对应 Epic。

整体上手难度：中等偏低。调用门槛只有一条命令，真正的门槛在环境准备和「不要跳过阶段 7」的纪律上。详情里明确列了几类常见错误：推送前不做本地验证、自动修复复杂问题、忘记调用 handling-pr-comments、不给用户选项、过早离开修复状态、跳过迭代循环——这些都是实操中最容易踩的坑。

该技能能为用户带来的价值

  • 把「等待」变成「自动推进」：从「CI 挂了 → 人看到 → 人去修」变成「CI 挂了 → 代理 60 秒内发现 → 自动修复并推送」，尤其适合 lint、格式、类型这类高频低难度问题。
  • 消除「假完成」：完成前必须跑 gtg 并确认 READY，且要逐条处理顶层评论，杜绝「看起来绿了其实还有未解决线程」的误判，合并前的返工显著减少。
  • 释放协调器与人力：代理自治 PR 生命周期后，协调器可以继续派发其他任务，人只在真正需要决策的复杂问题上出现——且拿到的不是「我该怎么办」，而是带利弊分析的 2-4 个选项。
  • 降低协作门槛：范围外评论有明确的「先尊重、再评估、必须回复」流程，新人和 AI 代理都不会因为怕改别人的代码而让线程悬空。
  • 长期资产沉淀：合并后自动创建知识提取任务、阻塞 Epic，把评审评论与对话中的架构决策、根因分析固化为可检索的知识；再配合 RAM 清理，让环境保持干净，为下一个任务让路。

常见问题 FAQ

Q1：怎么安装 PR守护者Skill？我只有技能ID 13658。 A：在支持技能的代理环境中，用中文名「PR守护者」、英文名「pr-shepherd」或技能ID 13658 检索并安装；同时确认已具备 gh、gtg 与项目的 lint/typecheck/test 脚本。具体安装入口与依赖说明以官方说明为准。安装后用 /project:pr-shepherd <pr-number> 验证，能看到开场播报即为生效。

Q2：这个技能收费吗？ A：提供的技能详情中没有涉及任何价格、订阅或授权费用信息，因此无法确认收费模式，请以官方说明为准。可以确定的是它依赖 gh、gtg、pnpm 等本地工具与你的代码托管平台账号。

Q3：它会不会擅自改我的代码？ A：不会乱改。它把问题分成两类：lint、Prettier、类型错误、自己写的代码测试失败属于「简单问题」，直接修；他人代码的测试失败、基础设施/配置失败、模糊错误属于「复杂问题」，必须先向你请示。而且任何推送前都要通过 pnpm lint && pnpm typecheck && pnpm test --run。

Q4：和自动合并机器人、代码评审机器人怎么选？ A：三者互补。评审机器人负责「提意见」，自动合并机器人负责「按规则放行」，PR守护者负责中间那段最耗人的「改到能过、把意见闭环」。如果你的痛点是「评论太多处理不完、CI 反复红」，选 PR守护者；如果只是想要规则化的自动合并，轻量的流水线方案就够。

Q5：为什么它强调「4 小时检查点」和「不要跳过阶段 7」？ A：4 小时检查点是为了避免代理长期占用资源，给你继续监控、退出交接、缩短间隔三个选择；阶段 7 是推送修复后复查新评论的迭代环节——自动评审机器人会在每个提交后 1-2 分钟内追加评论，跳过阶段 7 就会漏评论并过早宣布完成，这也是详情里标注的「第1错误」。