企业官网建设流程全解析

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 流程传入两个关键输入：

pr-review.md 引用了一组配套参考文件，构成完整的 PR 审查知识体系：

整个 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 失败并提示couldn't find remote ref，说明本地origin很可能是 fork（贡献者的典型场景）。检查远程并回退到upstream：

git 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_REVIEWS）

gh api --paginate "repos/{OWNER_REPO}/pulls/{number}/reviews?per_page=100"

2. 普通 PR 对话评论（PR_CONVERSATION_COMMENTS）

gh api --paginate "repos/{OWNER_REPO}/issues/{number}/comments?per_page=100"

3. 审查线程（REVIEW_THREADS）——包含线程状态与每个根/回复 review-comment 节点：

gh api graphql --paginate \ -f owner="{OWNER}" -f repo="{REPO}" -F number={number} \ -f query='query($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_page=100"

待提交的审查/评论可能只有其作者可见。必须把当前审查者可访问的草稿与已提交的审查摘要、线程分开保存；没有草稿不代表其他审查者也没有草稿。

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.md（A 正确性/安全 → 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：

• 无待提交草稿→ 新建并使用其id：

  gh 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 或 PR；
• Persisted：已接受规则被写入 .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 Demand（stage 1，门禁）→ Consumer（stage 2，涉及新增/扩展共享表面的变更，按 consumer-review.md 做"消费者考古"）→ Architecture-First（stage 3，按 cherry-review-guidance.md，核心是"通用引擎 + 声明面"配对模式与实体泄漏识别）→ Implementation（stage 4，代码走 code-checklist.md 的 A/B 级，文档走 doc-checklist.md 的 A/B 级）→ Style/conventions（stage 5，C 级）。后一阶段只审查在前一阶段存活的变更。
• Authority model：审查请求只授权分析与汇报。Report-only 是默认；fix（仅本地目标）与submit（PR 流程）都必须由调用显式授予；批准（APPROVE）与合并（merge）始终需要各自的显式请求。
• Risk 分级：按 judgment-matrix.md 的 Low/Medium/High 分级，风险按问题判定而非按类别；报告模式下所有级别都只报告，授权修复模式下仅 Low 风险自动修复，Medium/High 报告选项与权衡。
• 引擎关系：PR 流程在引擎选择契约之外，额外增加了 worktree 设置与 GitHub 提交层（即本文主题）；小型 diff 走单智能体 local-review.md，大型 diff 在具备独立子代理能力时走多智能体 teams-review.md（reviewer 发现问题、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