heydeer
开始使用

HeyDeer CLI

在打开拉取请求之前,从终端审查你的分支和未提交的改动。HeyDeer CLI 会在你工作的地方输出发现的问题,编程代理也能运行它。

安装并登录

CLI 需要 Node.js 22 或更高版本、一个安装了 HeyDeer 的 GitHub 仓库,以及你对该仓库的写入权限。

npm install -g heydeer
heydeer login

heydeer login 会输出一个链接和一个代码。打开链接,用 GitHub 登录 HeyDeer 并输入代码。页面会显示登录请求来自哪里,允许之前请确认是你自己的电脑。

命令作用
heydeer login在这台电脑上登录 HeyDeer。
heydeer status显示 CLI 以谁的身份操作。
heydeer logout在这台电脑上退出登录。
heydeer --version显示已安装的 CLI 版本。

CLI 把登录信息保存在 ~/.config/heydeer/credentials.json,Windows 上则在 %APPDATA%\heydeer。登录在最后一次使用后 30 天内有效,最长 90 天;过期后重新运行 heydeer login。

审查你的改动

在仓库目录中运行审查,并用一句话说明这些改动的目的:

heydeer review "Retry failed uploads. Fixes #123."

HeyDeer 审查你分支上的提交和已跟踪文件的未提交改动,对比的是与 origin 默认分支的合并基点。它会像读拉取请求描述一样读你的说明,包括其中提到的 issue,并对照说明检查代码。说明较长时,可以写进文件并传入 --description-file。

CLI 会显示仓库、基准、分支和审查深度,列出要发送的文件,并跟进审查进度。审查完成后,它会输出每个发现的问题,以及严重程度、文件和行号。

选项

选项作用
--description-file <path>从文件读取说明,而不是从命令行。
--base <ref>与另一个分支或提交对比,适用于以它为目标的工作。
--include-untracked同时审查还没加入 Git 的新文件,被 gitignore 忽略的除外。
--depth standard|deep这次审查使用与仓库不同的审查深度。深度审查适用于付费方案。
--full审查所有改动,而不仅是该分支上次审查之后的改动。
--dry-run列出会发送的文件和留在本机的文件,不需要登录,也不会开始审查。
--json以 JSON 输出完成的审查,供脚本和编程代理使用。

哪些内容留在本机

离开你电脑的只有相对合并基点的 diff 和你的说明;其余代码 HeyDeer 从 GitHub 读取。CLI 会把以下文件排除在审查之外,并在 Left on this machine 下列出:

  • 凭证文件,例如 .env 文件和私钥。
  • 包含已知格式凭证的改动。
  • 二进制文件。
  • 单个文件超过 1 MB 的改动。

所有改动合计最多 32 MB 的 diff。超出时,传入更近的 --base,或在拉取请求中审查这些改动。运行 --dry-run 可以在发送前看到确切的清单。

修复后再运行一次

每次审查分支时,都会复查上一次审查留下的未解决问题,所以下一次运行会告诉你修复解决了哪些。

如果仓库开启了只审查新改动,之后对该分支的审查只覆盖上次完整审查以来的改动。连续三次这样的审查之后,或者大部分改动都是那次审查之后的新改动时,下一次会重新审查全部改动。随时传入 --full 都可以审查全部内容。如果自上次审查以来没有任何改动,CLI 会提示并且不会开始审查。

在脚本和编程代理中使用

使用 --json 时,完成的审查会作为一个 JSON 对象输出到标准输出,进度则输出到标准错误。每个发现的问题都包含严重程度、标题、文件和行号,以及解释它的正文。

要让 Claude Code、Codex 或 Cursor 在打开拉取请求前审查自己的工作,可以在 AGENTS.md 中加入这样的指令:

Before opening a pull request, run `heydeer review --json "<what the change does>"`
from the repository root, fix the findings you agree with, and run it again.

CLI 会以下列代码之一退出:

退出码含义
0审查完成,无论是否有发现的问题。
1审查失败,或所有改动的文件都必须留在本机。
2命令或其选项无效。
130你按了 Ctrl+C 取消。

完成的审查无论有没有发现问题都以 0 退出,所以要从 JSON 中读取发现的问题,来判断分支是否就绪。

积分

本地审查使用安装覆盖该仓库的工作区的积分,并且在所有仓库中都按私有代码计费。试运行,以及自上次审查以来没有改动的运行,不消耗积分。每人每小时最多可以发起 30 次本地审查。Ctrl+C 也会在 HeyDeer 上取消审查;连按两次可立即停止 CLI。