Cherry Studio 的 gh-pr-review 远程 PR 审查全流程Worktree 隔离模式、审查引擎选择与 GitHub 提交指南【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio本指南围绕 Cherry Studio 仓库内置的gh-pr-reviewAgent 技能SKILL.md中针对 PR 目标的完整审查流程pr-review.md展开系统讲解 Worktree 隔离审查模式、PR 会话数据采集、审查引擎路由、结果汇报与gh-pr-review扩展提交等核心技术细节。读完本文你将掌握如何在本地精确复刻远程 PR 分支、按四类会话数据采集审查上下文、依据作用域大小与运行时能力选择审查引擎并安全合规地向 GitHub 提交结构化审查结论。一、为什么 PR 审查必须使用 Worktree 模式gh-pr-review技能支持对本地分支、PR、commit、文件、架构文档与仓库技能等多种目标进行审查见 SKILL.md 的技能声明。其中 PR 目标之所以特殊是因为它采用Worktree 模式在本地拉取 PR 分支让审查程序能够跨模块读取相关代码并且读取的是PR 分支对应版本的精确快照。这一设计对审查准确性至关重要。如果直接在调用方当前的工作目录里审查工作区里可能混有调用方未提交的本地改动导致看到的内容与远程 PR 不一致当前分支的 HEAD 与 PR 分支的 HEAD 未必相同跨模块引用关系可能错位。因此 pr-review.md 明确规定永远创建隔离的 detached worktree绝不复用调用方当前的工作树即使其分支和 HEAD 与 PR 一致也不行——审查必须读取精确的远程 PR 快照不能掺入调用侧未提交的改动。整个 PR 审查流程遵循 SKILL.md 定义的Interaction and interruption contract交互与中断契约正常审查全程免打扰不询问模式选择、修复确认、发现项挑选或提交预览。该流程不引入任何额外提示类别只声明以下安全拦截点safety blocker脏的/不匹配的审查工作树缺少 canonical 远程仓库upstream清理含未解释改动的 worktree存在本次运行未确认过内容的待提交审查草稿pending review draft。二、PR 审查的输入参数与参考文件进入 PR 审查流程前SKILL.md § Route 会先剥离$ARGUMENTS中的权限修饰符fix、submit剩余部分作为REVIEW_TARGET并向 PR 流程传入两个关键输入输入语义默认值AUTHORIZED_SUBMIT仅当调用显式要求发布审查submit修饰符或等价用户措辞时为truefalse——发现项只汇报给用户不写入 GitHubHAS_SUBAGENTS运行时能力由 SKILL.md § Route 判定仅当能启动独立的 reviewer 与 verifier 代理时为true不要求并行执行依运行时而定pr-review.md 引用了一组配套参考文件构成完整的 PR 审查知识体系文件用途consumer-review.mdConsumer 审查阶段涉及新增/扩展共享表面的变更code-checklist.md代码审查检查清单doc-checklist.md文档审查检查清单cherry-review-guidance.mdCherry Studio 项目专属审查边界与参考路由judgment-matrix.md值得修复的标准与特殊规则checklist-evolution.md检查清单更新流程与规则整个 PR 流程共五个步骤创建 worktree → 收集 diff 与上下文 → 执行审查 → 清理与汇报 → 检查清单演进。下面逐一展开。三、Step 1创建隔离的审查工作树3.1 PR 目标校验如果REVIEW_TARGET是 URL先从其中提取 PR 编号然后校验 PR 目标并记录关键元数据gh repo view --json nameWithOwner --jq .nameWithOwner gh pr view {number} --json headRefName,baseRefName,headRefOid,state,body记录OWNER_REPO并拆分为OWNER与REPO同时提取PR_BRANCH、BASE_BRANCH、HEAD_SHA、STATE、PR_BODY。此处的校验规则包括任一命令失败 → 告知用户并中止若REVIEW_TARGET是含{owner}/{repo}的 URL必须与OWNER_REPO匹配否则告知用户不支持跨仓库 PR 审查并中止若STATE不是OPEN→ 告知用户并退出。3.2 创建工作树工作树路径按PR 编号 HEAD 短 SHA命名/tmp/pr-review-{number}-{short_HEAD_SHA}记录为REVIEW_DIR并记录调用方仓库git rev-parse --show-toplevel的结果为MAIN_REPO_DIR存入协调器状态。这样设计的好处是PR 与 SHA 专属路径可确保无关的审查工作树永远不会被误清理或误删除同时不要依赖跨工具调用持续存在的 shell 变量或cd——后续所有命令都要显式传入REVIEW_DIR。添加工作树前先检查该精确路径是否已注册git worktree list --porcelain若该路径已存在仅当它指向HEAD_SHA且git -C {REVIEW_DIR} status --porcelain为空时才可复用脏的、不匹配的或无关的工作树一律视为安全拦截点绝不删除或覆盖。交互式会话中请求用户批准具体操作自动化会话中保留原状、中止并报告所需决策。否则按以下命令创建git fetch origin pull/{number}/head git worktree add --detach {REVIEW_DIR} {HEAD_SHA}3.3 Fork 场景回退到 upstream如果 fetch 失败并提示couldnt find remote ref说明本地origin很可能是 fork贡献者的典型场景。检查远程并回退到upstreamgit remote -v # 如果 origin 指向你的 fork、upstream 指向 canonical 仓库则从 upstream 拉取 git fetch upstream pull/{number}/head git worktree add --detach {REVIEW_DIR} {HEAD_SHA}如果upstream未配置将缺少 canonical 远程仓库视为环境拦截点交互式会话中先询问其 URL 再重试自动化会话中中止并报告缺失配置。不要猜测。若工作树创建因其他任何原因失败告知用户并中止。后续所有审查与验证的文件系统/命令调用都以记录的绝对REVIEW_DIR作为显式工作目录无法设置工作目录的 shell 片段使用git -C {REVIEW_DIR} ...。清理是唯一例外清理必须从MAIN_REPO_DIR执行绝不能在被移除的工作树内部执行。平台注意Windows如果当前运行时无法读取 Git Bash 的/tmp/...路径先用cygpath -w转换记录的REVIEW_DIR再传给文件系统工具macOS/Linux 上直接使用原路径。四、Step 2收集 Diff 与审查上下文4.1 计算 merge-base 差异git -C {REVIEW_DIR} fetch origin {BASE_BRANCH} git -C {REVIEW_DIR} merge-base origin/{BASE_BRANCH} HEAD git -C {REVIEW_DIR} diff merge-base-sha若 diff 超过 200 行先运行git diff --stat获取概览再用git -C {REVIEW_DIR} diff -- {file}按文件阅读避免输出被截断。若 diff 为空 → 清理工作树并退出。4.2 四类 PR 会话数据状态与可见性语义各不相同文档强调收集完整的可访问 PR 对话并将以下四个来源分开保存因为它们的状态和可见性语义不同1. 审查摘要与状态PR_REVIEWSgh api --paginate repos/{OWNER_REPO}/pulls/{number}/reviews?per_page1002. 普通 PR 对话评论PR_CONVERSATION_COMMENTSgh api --paginate repos/{OWNER_REPO}/issues/{number}/comments?per_page1003. 审查线程REVIEW_THREADS——包含线程状态与每个根/回复 review-comment 节点gh api graphql --paginate \ -f owner{OWNER} -f repo{REPO} -F number{number} \ -f queryquery($owner:String!, $repo:String!, $number:Int!, $endCursor:String) { repository(owner:$owner, name:$repo) { pullRequest(number:$number) { reviewThreads(first:100, after:$endCursor) { nodes { id isResolved isOutdated path line originalLine comments(first:100) { nodes { id databaseId url body createdAt updatedAt author { login } replyTo { id databaseId } pullRequestReview { id databaseId state author { login } } } pageInfo { hasNextPage endCursor } } } pageInfo { hasNextPage endCursor } } } } }对reviewThreads和每个嵌套的commentsconnection 分页直到其hasNextPage为 false对于被截断的嵌套 connection用返回的 comment 游标查询其线程node(id: ...)直到完整。回复是 review-comment 节点通过replyTo关联不是 issue comments必须按顺序保留每个根评论及其所有回复。4. 当前审查者的待提交草稿CURRENT_REVIEWER_PENDING_REVIEWS与CURRENT_REVIEWER_PENDING_COMMENTS先用gh api user --jq .login获取 viewer 登录名从PR_REVIEWS中选出该 viewer 的PENDING条目再抓取每份草稿的评论gh api --paginate \ repos/{OWNER_REPO}/pulls/{number}/reviews/{review_id}/comments?per_page100待提交的审查/评论可能只有其作者可见。必须把当前审查者可访问的草稿与已提交的审查摘要、线程分开保存没有草稿不代表其他审查者也没有草稿。4.3 CI 状态与作用域派生gh pr checks {number} --repo {OWNER_REPO}记录失败、待定、成功的检查项作为审查的验证信号。不要用本地 lint、test 或 format 代替 CI参见 SKILL.md § Validation after applied fixes未编辑任何内容的审查绝不运行本地检查。只有在 worktree、PR_BODY、完整可访问的会话状态和 CI 状态全部收集完毕之后才依据完整的 merge-base diff 计算CHANGED_LINES、CHANGED_FILES、二进制状态和SMALL_SCOPE。SMALL_SCOPE的权威定义在 SKILL.md § Scope derivation只有当CHANGED_LINES 1000、CHANGED_FILES 20且作用域内无二进制文件时SMALL_SCOPE true。不要用 GitHub 的汇总计数或模块合并启发式来替代。五、Step 3执行审查5.1 审查引擎选择只选择一个审查引擎SMALL_SCOPE true→ 走 local-review.md单智能体审查SMALL_SCOPE false且HAS_SUBAGENTS true→ 走 teams-review.md多智能体 reviewer–verifier 对抗式审查SMALL_SCOPE false且HAS_SUBAGENTS false→ 走 local-review.md并置LIMITED_SINGLE_AGENT true在报告中显式披露限制。在REVIEW_DIR内以AUTHORIZED_FIX false运行所选引擎——PR 审查永不修改代码。对 local-review复用已收集的作用域并运行其 Review 与 Filter 步骤对 teams-review按其 Phase 1 Module partition 划分作用域再运行 Phase 2 及 Phase 3 的去重、存在性与风险评估部分。当HAS_SUBAGENTS false时绝不进入 teams-review协调器自我验证不能替代独立的 reviewer–verifier 对。无论哪个引擎最终报告与提交打包都由 PR 包装流程的 Step 4 负责。5.2 协调器职责围绕所选引擎协调器承担以下职责0. Product Demand 门禁在实现审查之前先按 SKILL.md § Review Stages 的 stage 1 运行依据PR_BODY、diff 及其引用的权威决策产物精确应用 no-impact、established-direction、open-decision 三种状态。PR body 本身只表明作者意图不构成产品批准。只有 open decision 才能在交互式运行中提示或在显式自动化运行中使用 record-only 行为后者的 impact、direction 和 open product questions 要带入 Step 4 报告提交时写入审查正文并标注 awaiting human confirmation。该协调器门禁即满足所选引擎的 stage 1不要在 local-review 或 teams-review 内二次运行。1. 阅读PR_BODY理解作者声明的动机并将其纳入审查上下文验证实现是否真正达到了作者的描述。2. 应用引擎的检查清单与参考加载规则包括 cherry-review-guidance.md 以及从 worktree 读取的强制性基线文档遵循架构优先architecture-first原则审查。该文档要求对数据系统、服务边界、IPC/preload、生命周期/窗口/路径、主进程架构、渲染器架构、共享层、渲染器数据 hooks、React UI、网络下载、命名/模块形状等区域执行 Scope Triage并依据 code-checklist.mdA 正确性/安全 → B 重构/优化 → C 约定/文档与 doc-checklist.md 的分级检查。3. 线程级先验问题验证以审查线程而非单个评论作为先验问题验证的单元。完整读取根评论与所有回复保留isResolved/isOutdated状态再把线程的当前结论对照精确代码验证。审查摘要和普通对话评论仍是各自带作者、正文和状态的上下文输入。teams-review 中由额外的 PR-conversation reviewer 执行local-review 中由单一审查者直接执行。4. 语义去重验证后将每个确认的问题对照整个现有线程进行语义去重绝不把回复当作独立先验问题同时对照当前审查者的待提交草稿避免重复添加草稿评论——但绝不把该草稿描述为已提交或对他人可见。输出规则只向用户呈现最终确认的问题。不输出分析过程、排除理由或曾考虑但被否决的问题。六、Step 4清理与汇报6.1 工作树清理git -C {MAIN_REPO_DIR} worktree remove {REVIEW_DIR}清理是 best-effort 的。如果git worktree remove失败如 Windows 上文件句柄仍被占用导致Permission denied审查结果依然有效——不要因清理而阻塞。从主仓库运行git worktree prune清除过期的工作树引用之后可手动删除目录。绝不强制删除含未解释改动的工作树将其视为安全拦截点检查后在交互式会话中请求批准具体清理动作自动化会话中保持原状并报告所需决策。6.2 结果汇报格式向用户呈现Summary一段话描述变更的目的与范围Overall assessment代码质量评估与关键改进方向Issue list无问题则报告 no issues found当LIMITED_SINGLE_AGENT true时显式披露——非小型 PR 因运行时无子代理能力而接受了单智能体审查未经过独立对抗验证自动化会话中存在 open product decision 时附上 Product Demand 摘要impact、direction、需人工确认的点明确标注 awaiting a product decision绝不表述为已批准Checklist candidates将有效的重复模式候选标记为proposed常规 PR 审查从不接受、插入或声称持久化检查清单规则。问题呈现格式{N}. [{priority}] {file}:{line} — {description and fix guidance}其中{priority}是检查清单条目 ID如 A2、B1、C7。对 Medium/High 风险修复指引列出可行选项、关键权衡与可选审查者建议绝不把某个选项呈现为已被选定。授权与提交的关系AUTHORIZED_SUBMIT false默认到此为止——不写入 GitHub。若用户随后要求提交即授予授权继续下面的流程AUTHORIZED_SUBMIT true按下面流程提交全部确认问题不做逐条选择询问。6.3 安装 gh-pr-review 扩展提交审查前必须先安装gh-pr-review扩展gh extension install EurFelux/gh-pr-review提交审查必须使用该扩展以实现结构化的待提交审查与行内评论不要使用gh pr comment或裸gh api提交审查。6.4 通过 gh-pr-review 提交审查1. 获取REVIEW_ID优先复用当前审查者已有的草稿绝不发布本次运行未确认的内容检查 Step 2 收集的CURRENT_REVIEWER_PENDING_REVIEWS无待提交草稿→ 新建并使用其idgh pr-review review start --repo {OWNER_REPO} --pr {number}有待提交草稿且无评论→ 复用其 GraphQL node id 作为REVIEW_ID待提交草稿中带有本次运行未产生的评论→ 提交它将发布未经验证的内容这超出AUTHORIZED_SUBMIT的授权范围。将其视为 SKILL.md § Interaction and interruption contract 下的安全拦截点保持草稿原样、不写入任何内容、向用户汇报发现。交互式会话中只问一个问题是提交合并后的草稿说明其中携带多少条既有评论还是全部保持待定自动化会话中不提交任何内容并报告发布既有草稿需要单独授权。绝不删除或编辑其评论。复用草稿并获授权后把本次运行的问题对照CURRENT_REVIEWER_PENDING_COMMENTS去重避免重复已草拟的点。2. 为每个选定问题添加行内评论gh pr-review review add-comment --repo {OWNER_REPO} --pr {number} \ --review-id {REVIEW_ID} \ --path {file_path} \ --line {line_number} \ --body **[{priority}]** {description and suggested fix}多行范围gh pr-review review add-comment --repo {OWNER_REPO} --pr {number} \ --review-id {REVIEW_ID} \ --path {file_path} \ --line {end_line} --start-line {start_line} \ --body **[{priority}]** {description and suggested fix}3. 提交前预览。review preview只接受--repo、--pr和--thread-id——它没有--review-id因此预览 PR 的待提交评论必要时收窄到单个线程gh pr-review review preview --repo {OWNER_REPO} --pr {number}将预览作为自检每条评论都锚定到有效的 diff 行评论集合与确认问题一致含随附的既有草稿评论。不要向用户征求确认。4. 提交审查gh pr-review review submit --repo {OWNER_REPO} --pr {number} \ --review-id {REVIEW_ID} \ --event COMMENT|REQUEST_CHANGES \ --body {review summary}根据严重性选择事件COMMENT— 观察与建议无阻塞项REQUEST_CHANGES— 必须解决的关键或重大缺陷。6.5 行号规则与评论体规范行号规则决定评论能否锚定到 diff--line是新文件RIGHT 侧中的绝对行号必须在 Step 3 通过读取 worktree 中的实际文件确定——不要从 diff hunk 偏移推导行号必须落在 diff hunk 范围内。检查 hunk 头 -oldStart,oldCount newStart,newCount ——RIGHT 侧合法范围是newStart到newStart newCount - 1对删除行的评论使用--side LEFT和旧文件的行号。评论体规范以加粗的严重性/优先级标签开头如**[A2]**、**[B1]**清晰解释问题尽量给出带代码片段的具体建议使用用户对话所用的语言书写。最后附上本次发现/提交问题的摘要。6.6 无问题时的处理若无问题 → 报告审查未发现问题并停止。不要提交批准、不要合并只有在用户之后明确要求时才运行# 复用 viewer 已有的 PENDING review id否则新建一个 gh pr-review review start --repo {OWNER_REPO} --pr {number} gh pr-review review submit --repo {OWNER_REPO} --pr {number} \ --review-id review-id --event APPROVE --body LGTM gh pr merge {number} --squash --delete-branch七、Step 5检查清单演进审查完本会话所有确认问题后若其中存在当前检查清单未覆盖的重复模式阅读 checklist-evolution.md 并按其步骤处理。该参考文件定义了三个状态模型Proposed从重复且未被覆盖的模式起草的有效候选记录在审查报告中不编辑任何检查清单文件此状态仅会话内有效报告不是持久载体候选不会存活到后续会话Accepted用户在单独授权的检查清单维护流程中显式选择某个 proposed 候选。接受只授权规则选择不隐含 commit、push 或 PRPersisted已接受规则被写入 .agents/skills/gh-pr-review/references/ 下受追踪的规范检查清单通常是code-checklist.md或doc-checklist.md并以 commit 或 PR 等持久仓库记录捕获。只有此状态才能被描述为对后续审查可用。候选条目必须同时满足一条断言式短语描述期望状态非问句通用跨文件适用原子每条只检查一个关注点不重叠若为既有条目的具体案例则不添加归入最具体的既有类别每个类别保持在 3–8 条倾向于更少更宽的条目。常规审查只用 Step 1起草候选并标为proposed从不提示选择、编辑清单或声称持久化。八、PR 审查在整体审查体系中的定位PR 审查并非孤立的流程它与技能内其他引擎共享 SKILL.md 定义的统一契约Review Stages所有审查按阶段顺序运行——Product Demandstage 1门禁→ Consumerstage 2涉及新增/扩展共享表面的变更按 consumer-review.md 做消费者考古→ Architecture-Firststage 3按 cherry-review-guidance.md核心是通用引擎 声明面配对模式与实体泄漏识别→ Implementationstage 4代码走 code-checklist.md 的 A/B 级文档走 doc-checklist.md 的 A/B 级→ Style/conventionsstage 5C 级。后一阶段只审查在前一阶段存活的变更。Authority model审查请求只授权分析与汇报。Report-only 是默认fix仅本地目标与submitPR 流程都必须由调用显式授予批准APPROVE与合并merge始终需要各自的显式请求。Risk 分级按 judgment-matrix.md 的 Low/Medium/High 分级风险按问题判定而非按类别报告模式下所有级别都只报告授权修复模式下仅 Low 风险自动修复Medium/High 报告选项与权衡。引擎关系PR 流程在引擎选择契约之外额外增加了 worktree 设置与 GitHub 提交层即本文主题小型 diff 走单智能体 local-review.md大型 diff 在具备独立子代理能力时走多智能体 teams-review.mdreviewer 发现问题、verifier 对抗性挑战二者会话隔离、不共享对话历史否则回退到单智能体并披露限制。这套 PR 审查流程在 Cherry Studio 仓库中承担着代码与文档变更的质量守门角色通过 Worktree 模式保证审查基于精确的 PR 快照通过四类会话数据的分治采集保证不丢失任何既有结论与草稿通过引擎选择与安全拦截点保证审查既充分又安全。若要查看完整的技能入口与所有参考文件可继续阅读 .agents/skills/gh-pr-review/ 目录下的 SKILL.md 与 references/ 各文档。【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考