常见问题

连接 GitHub，选好仓库，就可以发起审查：

• 使用 GitHub 登录，在选择仓库所在的账号下选择你的个人账号或组织。如果列表里没有，选择在 GitHub 上安装，然后在 GitHub 上选中它。
• 在 GitHub 上选择 Only select repositories（仅选择部分仓库），勾选要审查的仓库并确认。在组织中，除非你本人就是所有者，否则 GitHub 会请所有者批准。
• 决定是否让 HeyDeer 自动审查：保持自动审查 PR开启，每次推送都会审查，每个 PR 最多 5 次；关闭后则只在有人发起时审查。
• 在一个打开的 PR 上评论 @heydeer review。

你需要拥有仓库的写权限。新工作区从免费套餐开始，无需信用卡，发现的问题会以审查评论的形式出现在 PR 上。

连接后就能直接发起审查。HeyDeer 会结合整个仓库的上下文阅读 PR 的改动，同时参考 PR 的标题、描述和讨论，而且每次审查本来就会查找 bug 和安全问题。

最初几次审查暴露出缺口后，再把指导补充到合适的位置：

• AGENTS.md：写明代码如何运作、遵循哪些约定；编程智能体也会遵循它。
• REVIEW.md：写明审查应该关注什么、不必理会什么，以及问题有多严重。
• 仓库检查：用于 HeyDeer 必须在每个改动特定文件的 PR 中核验的要求。
• 审查指令：用于不能被 PR 修改的指导，或适用于所有仓库的指导。

只要有人发起就会开始：在 PR 上评论 @heydeer review，在审查记录页面选择发起审查，或在 HeyDeer Review 检查上选择 Re-run。新工作区默认为仅手动，完成设置后 HeyDeer 会立即询问是否自动审查。

工作区管理员可以随时在工作区设置 → 审查规则 → 何时审查中修改审查时机：

• 每个 PR 审查一次：审查符合条件的 PR，直到成功完成一次审查。
• 每次推送时审查：PR 首次符合筛选条件时审查，之后每次推送新提交后再审查，默认最多 5 次。

自动审查默认跳过草稿、fork 和依赖更新。

分阶段推行，等团队信任它的结果后，再让 HeyDeer 把关合并：

• 先在几个 PR 上试用：关闭自动审查，在几种不同类型的 PR 上评论 @heydeer review，把发现的问题和你们审查人员的意见对比一下。
• 补上这些审查暴露的缺口：约定写进 AGENTS.md，要求写进仓库检查，优先级写进审查指令。
• 先为一两个仓库开启自动审查（在仓库中选中它们，再选择修改审查时机），然后推广到整个工作区。
• 将 HeyDeer Review 检查设为必需，决定是否启用自动批准；如果使用付费套餐，再设置自动充值和用量上限。

当团队会处理大部分发现的问题、审查完成时也不再带有审查说明时，就可以进入下一阶段。设置由工作区管理员修改；任何拥有写权限的人都可以发起审查。

以下任一方式都会审查 PR 的最新提交：

• 在 PR 上评论 @heydeer review。
• 在 HeyDeer Review 检查上选择 Re-run。
• 在 HeyDeer 的审查记录页面选择发起审查，还可以在这里选择其他审查深度或反馈范围。

开启只审查新改动时，审查只覆盖上次审查以来的改动；评论 @heydeer full review 可以重新审查整个 PR。发起审查需要写权限；手动发起的审查和其他审查一样计费，但不计入每个 PR 的自动审查次数上限。

从 HeyDeer 发起审查时，可以为这一次审查单独选择审查深度和反馈范围：

• 打开审查记录，选择发起审查。
• 选择仓库和拉取请求。列表中显示你拥有写权限的仓库。
• 如需更改审查深度或反馈范围，打开审查选项；两者默认都是该仓库的默认设置。
• 选择运行审查。

之后审查的运行和发布方式与在 GitHub 上发起的审查相同。

首次审查之后，HeyDeer 会把重点放在新内容上。只审查新改动默认开启，此时后续审查只会在 PR 自身的提交自上次成功审查以来改动的内容中寻找新问题，并复查之前发现的问题。从目标分支合并进来的提交不在审查范围内，但解决冲突的改动会被审查。

以下情况下，HeyDeer 会审查整个 PR：

• 有人评论了 @heydeer full review，或者该设置已关闭。
• 自上次审查以来，目标分支发生了变化。
• 上次审查带有审查说明，或提出了需要澄清的问题。

检查的摘要会显示某次审查覆盖的是新改动还是整个 PR。

之后的每次审查都会对照当前代码，复查 HeyDeer 此前提出且尚未关闭的问题：

• 仍然存在的问题列在此前仍需处理的问题下。
• HeyDeer 无法核实的问题列在此前仍需确认的问题下，并附上它需要的信息。
• 将已处理的 HeyDeer 讨论标记为已解决默认开启，此时一旦代码修复了问题、证明问题并不成立，或者有人决定不处理，HeyDeer 就会将对应讨论标记为已解决。

必须由代码体现修复；仅回复说已经修好是不够的。未处理或未确认的问题会阻止自动批准；如果开启了发现问题时将检查标记为失败，还会导致检查失败。

HeyDeer 会发布在你的反馈范围内的问题。反馈范围决定了对于每种严重程度（严重、高、中或低），HeyDeer 需要有多大把握才会报告：

• 精简：严重问题大概率存在时报告，高和中严重程度的问题只在确信时报告，低严重程度的问题只报告来自仓库检查的。适合每条评论都会细读的团队。
• 平衡（默认）：严重问题在怀疑时就报告，高严重程度的问题大概率存在时报告，中和低严重程度的问题在确信时报告。
• 详尽：严重和高严重程度的问题在怀疑时就报告，中和低严重程度的问题大概率存在时报告。适合由编程智能体在修复前先核实每个问题的团队。

反馈范围之外的问题不会被报告，不会导致检查失败，也不会阻止自动批准。想比较不同范围，可以在切换前先在 HeyDeer 中对一次已完成的审查进行预览。

可以。“用 HeyDeer 修复”会把你选中的问题变成一个可以检查并合并的 PR：

• 在审查评论中选择用 HeyDeer 修复，或在 HeyDeer 的审查页面选择修复发现的问题。
• 选择要修复的问题；需要补充背景的，用添加指令说明，比如要采用的方案或需要保留的行为。
• 选择显示所选数量的按钮，例如修复 2 个问题。

HeyDeer 会修改代码，在沙箱中运行你的测试，并另开一个以你的 PR 分支为目标的 PR。合并它之后，你的 PR 的下一次审查会复查这些问题。所有套餐都包含“用 HeyDeer 修复”。

Autopilot 会把 PR 交给 HeyDeer 处理，直到它可以合并或需要你介入。每一轮中，HeyDeer 会修复待处理的问题，推送到 PR 自己的分支，并审查新的提交，直到达到轮数上限（默认 5 轮，可按工作区或仓库调整）。它会处理：

• 在你的反馈范围内发现的问题，以及此前尚未关闭的问题。
• 拥有写权限的人在未解决的审查讨论和新评论中提出的请求。
• 失败的检查：必需的检查，或除 HeyDeer Review 之外的所有检查。
• 合并冲突：通过合并目标分支来解决，绝不会变基或强制推送。

可以通过审查页面或 HeyDeer 审查评论中的 Autopilot 按钮启动，也可以评论 @heydeer autopilot。Autopilot 停止后，HeyDeer 会发布它的审查，并列出仍待处理的事项。Autopilot 需要付费套餐，每一轮都会像普通的修复和审查一样消耗积分。

在 HeyDeer 中 Autopilot 的页面上选择停止 Autopilot，或评论 @heydeer autopilot stop；任何拥有写权限的人都可以停止它。以下情况下 Autopilot 也会自行停止：

• 没有需要修复的内容了，或者需要你回答一个问题。
• 其他人向该分支推送了提交，包括使用 GitHub 的 Update branch 按钮。
• 已达到轮数上限，或者几轮下来没有进展。
• 检查一小时后仍在运行、PR 已进入合并队列，或者 GitHub 拒绝了它的推送。
• PR 已关闭或合并，或者工作区的积分已用完、不再使用付费套餐。

它在 PR 上的评论会说明停止原因和仍需你处理的事项，需要启动者介入时还会提及对方。再次启动会重置轮数，并读取新的回答和评论。

在 PR 或 issue 评论、行内审查评论，或者新 PR、新 issue 的描述中提及 @heydeer，就可以向它提问或交给它一项工作。例如：

• @heydeer what does this function do?：在回复中解释这段代码。
• @heydeer fix the first issue and open an issue for the second：创建一个包含修复的 PR，并新建一个 issue。
• @heydeer do the latest Next.js docs recommend this?：在网上查阅文档。

HeyDeer 会阅读对话，在可以运行你的测试的沙箱中工作，并在你提问的地方回答；除非你另有要求，代码改动会提交到一个新的 PR。任何拥有写权限的人都可以提出请求，每个请求都会消耗工作区积分，并显示在 HeyDeer 的任务下。

所有套餐都包含“用 HeyDeer 修复”，免费套餐也不例外。一次修复需要：

• 一个打开的 PR，且它的分支位于同一仓库，而不是 fork。
• 该仓库的写权限。
• HeyDeer 对 Contents、Pull requests 和 Workflows 拥有读写权限。如果 HeyDeer 是在它申请 Workflows 权限之前安装的，需要先由安装管理员在 GitHub 上批准更新后的权限。

每个 PR 一次只运行一个修复，每次最多包含 100 个问题。

会。把约定写进仓库根目录的 AGENTS.md，HeyDeer 就会按照这些约定审查每个 PR；支持 AGENTS.md 的编程智能体在写代码时也会遵循同一个文件。写下新同事需要知道的内容，比如代码如何组织、命名方式、该用哪些辅助函数和库，以及错误处理和测试的做法。每条约定写成一个要点，不够直观的地方附上原因。

需要单独约定的目录可以有自己的文件，例如 src/payments/AGENTS.md，它会补充上级目录的约定，冲突时以它为准。在没有 AGENTS.md 的目录中，HeyDeer 会读取 CLAUDE.md。请把约定直接写在文件里，因为 HeyDeer 不会跟随导入的文件。

放在 REVIEW.md 中，可以放在仓库根目录，也可以放在任何需要单独指导的目录中。它适合写：

• HeyDeer 无法从代码中得知、但需要检查的内容，比如哪些日志字段属于个人数据。
• 不必理会的内容，范围要尽量窄，并写明涉及的路径。
• 某类问题有多严重，使用严重、高、中、低来表示。
• 某类问题屡次被证明有误时，这类问题需要什么样的证据。

为 Claude Code Review 编写的 REVIEW.md 可以直接使用。PR 可以修改 REVIEW.md，所以不能被 PR 修改的指导请放在审查指令中。

仓库检查是你以 Markdown 文件形式保存在仓库 .agents/checks/ 中的一项要求，它涵盖的文件列在 frontmatter 的 files 下。只要 PR 改动了这些文件，HeyDeer 就会核验这项要求，并为它分配一名专门的审查员，所以检查比一般性指导更彻底，消耗的积分也更多。

检查适合那些一旦漏掉代价很高、又容易被忽视的要求，比如 API 路由的访问控制。来自检查的问题会注明对应的文件，并计入 HeyDeer Review 检查和自动批准的判断。如果希望由 HeyDeer 代为编写检查，可以在仪表盘上选择设置仓库检查：HeyDeer 会阅读仓库和过去的 PR，然后创建一个添加检查的 PR，不消耗积分。

通常是因为这些指导没有覆盖到被改动的文件。对照下面找出符合的原因：

• 仓库检查必须是直接位于 .agents/checks/ 中的 .md 文件，且它的 files 模式要能匹配到被改动的文件。
• AGENTS.md 或 REVIEW.md 必须位于覆盖被改动文件的目录中。
• 审查指令只对保存之后发起的审查生效，并且与工作区指令冲突时以仓库指令为准。
• 这个问题可能在你的反馈范围之外；可以试试平衡或详尽。
• HeyDeer 无法通过阅读代码核实的要求，需要改写成针对代码的条件。
• 生成文件和目标分支中已有的锁文件会被跳过。

解决原因后，评论 @heydeer review。

按下面的顺序逐项处理，越靠前的改动花的力气越少、效果越明显：

• 先在 HeyDeer 中对最近的一次审查预览效果，再把反馈范围切换为精简。
• 在 .gitattributes 中把生成的代码标记为 linguist-generated。
• 用自动审查筛选条件跳过机器人或临时的 PR，例如使用 skip-review 标签。
• 对已经决定不修的问题，明确表示不处理，这样它们就不会再被提出。
• 对于没人处理的某类评论，添加一条范围明确并附有原因的审查指令。
• 如果某个仓库检查对无关的文件也提出问题，就收窄它的 files 模式。

连接器是远程 MCP 服务器，让审查和任务能够核实单看代码无法得知的信息：某个功能是怎么被使用的、日志里写了什么、某张表里的数据，或者某个库的文档。付费套餐包含连接器，由该 GitHub 组织或个人账号的所有者管理。

要添加连接器，打开工作区设置 → 连接器，选择添加连接器，填写服务器的 HTTPS 端点和所需的请求头，然后选择加载工具。选择允许使用的工具和适用的仓库，再选择保存连接器。一开始只允许使用只读工具；默认情况下连接器只在私有仓库中使用；工具调用会计入相应工作的积分消耗。

使用工作区设置 → 审查规则中何时审查下的自动审查筛选条件，或者某个仓库审查规则标签页中的同名设置。每一行可以按标签、作者、作者所在团队、作者与仓库的关系或账号类型、草稿状态或来源进行筛选，PR 必须符合所有行才会被审查。一些常用的行：

• 跳过所有机器人：作者账号类型 → 不是以下任意一项 → 机器人。
• 只审查带标签的 PR：PR 标签 → 是以下任意一项 → ai-review。
• 允许作者选择不审查：PR 标签 → 不是以下任意一项 → skip-review。

默认情况下，筛选条件会跳过草稿、fork 和依赖更新。它们只对自动审查生效，所以你仍然可以对任何 PR 发起审查。

按积分计费，根据每次审查或修复所做的工作量计算，所以改动越大或使用深度审查，消耗的积分就比小规模的标准审查更多。整个工作区共用一个套餐和积分余额，开发者和仓库数量不限，也没有席位费，因此增加队友不会改变价格。

• 每个套餐都包含每月积分。免费套餐第一个月有 1,000 积分，之后每月 300 积分。
• 任何套餐，包括免费套餐，都可以购买加购积分，基础价格为每 1,000 积分 $10，购买量越大折扣越多。
• 公开仓库的审查在合理用量上限内免费。

付费套餐提供更多每月积分和并行审查，还包含深度审查、Autopilot 和连接器。

在工作区重新有积分之前，HeyDeer 不会再开始新的审查。已经在运行的审查会完成，未支付的用量由 HeyDeer 承担；正在运行的修复则会停止。自动审查无法开始时，HeyDeer Review 检查会说明原因，HeyDeer 还会每天在每个仓库中第一个受影响的 PR 上评论一次，附上套餐和积分选项的链接。

要继续使用，可以在用量与账单 → 概览中购买积分、等待下一次每月积分刷新，或选择付费套餐，然后重新发起审查；之后的自动审查会照常开始。使用付费套餐时，HeyDeer 会在积分不足和用完时给工作区发送邮件，自动充值也可以在这之前补充积分。

工作区选择套餐后，工作区管理员可以在用量与账单 → 概览 → 消费控制中设置这两项：

• 自动充值默认关闭。开启后，每当余额低于你设定的阈值，就会按你的批量折扣购买固定数量的加购积分，让审查持续运行。它需要有效的付费套餐，费用从你的订阅卡中扣除。
• 用量上限限制审查和修复在一个自然周或自然月内合计消耗的积分。达到上限后，新的审查和修复不会开始，直到上限重置或你调高上限，正在运行的则会完成。

每周上限在每周一重置，每月上限在每月 1 日重置，时间均为 UTC 00:00。购买积分不会解除用量上限。

工作区管理员可以在用量与账单 → 概览中管理套餐：

• 升级：使用更改套餐。付款后立即生效：你只需支付本周期剩余时间的差价，获得相应比例的额外每月积分，续订日期保持不变。
• 降级：同样使用更改套餐。在下次续订时生效，选择保留当前套餐可以撤销。
• 取消：打开账单管理。套餐会保留到已付费周期结束，之后工作区回到免费套餐；在此之前选择恢复订阅即可继续保留。

控制审查的次数和深度：

• 把默认审查深度保持为标准，只在代码确实需要时使用深度审查。
• 把审查时机设为每个 PR 审查一次，或调低每个 PR 的自动审查次数上限。
• 保持只审查新改动开启。
• 用自动审查筛选条件跳过不需要审查的 PR，并标记生成文件。

使用付费套餐时，可以用每周或每月的用量上限控制支出。用量与账单 → 用量会按仓库、PR、审查和任务显示积分消耗。

每个成员都能看到自己在 GitHub 上有权访问的仓库的审查；对某个仓库拥有写权限的成员，还可以在该仓库发起和取消审查。管理员还可以：

• 修改审查规则和审查时机（成员可以查看）。
• 管理工作区设置和用量与账单。
• 修改成员的角色。

连接器只能由标记为 GitHub 所有者或账号所有者的管理员管理，手动审查权限则可以限定谁能发起审查。

洞察会汇总你选定的时间段和仓库中，审查发现了什么，以及团队如何处理这些问题：

• 已审查的 PR 数、发现的问题数、每个 PR 的问题数，以及决定不处理的比例。
• 各严重程度的问题随时间的变化，以及后续审查发现每个问题是已修复、仍在代码中，还是已决定不处理。
• 每个仓库的同类统计；工作区管理员还能看到每位 PR 作者的统计。

每个问题只计一次，即使后续审查再次报告它。如果某个仓库决定不处理的比例很高，往往说明 HeyDeer 在那里缺少上下文，可以通过审查指令、REVIEW.md 或仓库检查来补充。

关于工作区积分、付款和 GitHub 访问权限的邮件，绝不包含营销内容：

• 积分不足（使用付费套餐且未开启自动充值时，余额降至套餐每月积分的 20%）以及积分已用完。
• 订阅付款失败、银行要求你确认付款，或宽限期过后续订仍未付款。
• 自动充值失败或因达到购买上限而暂停，以及处理账单问题期间暂停付款。
• GitHub 组织所有者批准了连接 HeyDeer 的请求。

HeyDeer 以 GitHub App 的形式安装，选择 Only select repositories（仅选择部分仓库）即可将它限制在你想审查的仓库中。主要权限如下：

• Contents 读写：读取代码和历史记录，并为修复和 @heydeer 请求推送提交，绝不会覆盖分支上已有的提交。
• Pull requests 读写：发布审查和评论，以及按你的要求创建、更新或合并 PR。
• Checks 读写：显示 HeyDeer Review 检查。
• Workflows：在修复改动 GitHub Actions 工作流文件时更新这些文件。

其他较小的权限用于命令、Autopilot 读取 Actions 日志、筛选条件所需的组织成员信息，以及发送账单通知所需的邮箱。HeyDeer 不会申请 Administration 权限，每个令牌都只限于一个仓库和对应步骤所需的权限。

只保存维护审查记录和运行工作区所需的数据：

• 审查和修复结果、选中的问题和指令，其中可能引用所评论的代码行。
• 仓库和 PR 的标识符。
• 账号和工作区信息，以及设置。
• 账单记录。

你的仓库本身在临时克隆上处理，工作结束后即被销毁。对于连接器调用，HeyDeer 会记录工具、时间、时长和结果，但不保存发送或返回的内容。

最新提交上的 HeyDeer Review 检查会在标题中写明原因。常见原因按出现频率排列如下：

• 审查时机为仅手动，这是新工作区的默认设置：请选择每个 PR 审查一次或每次推送时审查。
• 筛选条件跳过了它，默认会跳过草稿、fork 和依赖更新：请将 PR 标记为可供审查、修改筛选条件，或评论 @heydeer review。
• 由于并行额度已被占用，审查正在排队：有空位时就会开始。
• 在每个 PR 审查一次下已经有一次成功的审查，或者 PR 已达到每个 PR 的自动审查次数上限：请评论 @heydeer review。
• 工作区积分已用完或已达到用量上限：请购买积分或调高上限，然后发起审查。
• 该 PR 的自动审查已暂停：请评论 @heydeer resume。

通常是因为该仓库还没有被审查过，或者检查发布已关闭。请按顺序检查：

• 仓库处于仅手动且从未被审查过：发起一次审查，之后的修订就会有检查。
• 发布 GitHub 检查已关闭：在审查规则的发布结果下开启它。
• HeyDeer 缺少 Checks 权限或无法访问该仓库：由 GitHub 所有者在工作区设置 → GitHub 连接中选择查看权限请求或添加仓库。
• PR 已关闭：重新打开它。

HeyDeer 在某个仓库中发布检查后，PR 的每次更新都会得到检查结果，所以必需的检查不会无限期等待。

HeyDeer 接受的每条命令都会加上 👀。如果没有，请检查以下几点：

• 命令要以纯文本形式发布在一条新的 PR 评论或行内审查评论中，不能放在代码、引用、HTML 注释里，也不能通过编辑发布，并且要用个人账号而不是机器人发布。
• 你需要拥有写权限；如果手动审查权限有限制，你还需要在名单中。
• 工作区可能积分已用完或已达到用量上限。
• HeyDeer 可能需要 Issues 或 Pull requests 权限：由 GitHub 所有者在工作区设置 → GitHub 连接中选择查看权限请求。
• pause 和 resume 只对打开的 PR 有效。

解决原因后，在一条新评论中重新发布命令。

将 HeyDeer Review 检查设为必需，并让发现的问题导致它失败：

• 让 HeyDeer 至少审查仓库中的一个 PR，这样检查才会存在。
• 在目标分支的 GitHub 分支保护规则或规则集中，开启必需的状态检查，添加 HeyDeer Review，并选择 HeyDeer 作为来源。
• 在 HeyDeer 中，开启工作区设置 → 审查规则 → 发布结果中的发现问题时将检查标记为失败。

这样，PR 只有在发现的问题和此前的问题都已修复或决定不处理后才能合并。HeyDeer 没有自动审查的提交，比如超过每个 PR 的自动审查次数上限之后的提交，也会阻止合并，直到有人发起审查。

检查的摘要会统计导致该结果的发现的问题、尚未关闭的此前问题和失败的仓库检查。以下情况检查会失败：

• 开启了发现问题时将检查标记为失败，并且审查中有反馈范围内的问题、尚未关闭或未确认的此前问题，或者审查说明。
• 无论该设置如何：有仓库检查没有运行、有此前的问题没有被复查，或者 HeyDeer 无法开始或完成审查。

修复问题后推送，或者在对应讨论中表明不处理并评论 @heydeer review。对于不完整的审查，请再发起一次；除非失败的审查调用过连接器，否则 HeyDeer 会退回它消耗的积分。

自动批准默认关闭；可以在审查规则的发布结果下开启。开启后，HeyDeer 中该审查的页面会显示未自动批准及原因，例如：

• 仍有发现的问题或此前的问题：修复它们或决定不处理，或者选择允许低严重程度问题，在只剩低严重程度问题时也批准。
• PR 的风险等级高于可自动批准的 PR设置，因此需要由人来批准。
• 有问题停留在待澄清下，或者审查带有审查说明。
• PR 修改了 HeyDeer 会从中读取的指导，比如 AGENTS.md 或仓库检查，或者这个 PR 是 HeyDeer 创建的。
• 审查之后有新的提交，或者目标分支有了变化。