适用场景
适合已经用 GitHub / GitLab 做主干开发、但 Code Review 靠人肉盯、经常漏掉空指针、资源未释放、SQL 拼接、并发竞态这类"模板型 Bug"的团队。这套方案用 Greptile 负责仓库级上下文索引和 PR 交互，用 GPT-6 Astra 负责逐段推理和给出修改建议，目标是把"能自动判定的 Bug"从人工评审里剥离出来，让人只审查设计、边界和业务语义。适合 5～50 人的研发团队，也适合个人维护的中型仓库。
环境与前置条件
- 代码托管：GitHub（组织或个人仓库）或 GitLab，需要仓库管理员权限来安装 App、配置分支保护。
- 账号与权限：Greptile 侧需要能读取目标仓库的授权；模型侧需要一个兼容 OpenAI 接口协议的网关地址与 API Key。
- 模型：GPT-6 Astra 的模型 ID、上下文长度、计费方式以官方文档当前版本为准；如果暂时拿不到该模型，可以先用同网关下任意可用的代码模型跑通链路，最后再替换模型 ID。
- 本地工具：
git、gh（GitHub CLI）或glab（GitLab CLI）、jq、curl。CI 侧建议 Ubuntu 22.04 以上或等效的 Linux 运行器。 - 资源建议：仓库索引是服务端完成的，本地不占资源；但 CI 里的网关脚本建议 2 核 4 GB 起步。首次全量索引大型单体仓库（十万文件级别）在服务端可能耗时较久，建议先用 3～5 个中等规模仓库试点。
- 磁盘：本地只需要放规则文件和脚本，几十 MB 足够；如果要在 CI 里缓存评审结果，预留 1～2 GB。
分步骤部署
第 1 步：接入仓库并完成首次索引
在 Greptile 控制台里安装对应平台的 App，选择要纳管的仓库范围。只勾选需要评审的仓库，不要图省事授权全组织——授权面越大，后续误报排查越难定位。
安装完成后，进仓库设置页确认索引状态。索引完成的标志是仓库页面显示已索引的文件数、分支和最近一次索引时间。此时可以在控制台里对一个已存在的 PR 手动触发一次评审，确认能拿到评论。
> 如果仓库里有大量生成代码（vendor/、dist/、*.min.js、锁文件），先在第 3 步的排除规则里把它们挡掉，再让索引跑第二遍，能显著减少噪音。
第 2 步：把模型接入评审链路
评审的推理层通过环境变量注入，不要把 Key 写进仓库。在本地或 CI 的密钥管理里配置：
```bash
export REVIEW_BASE_URL="https://<your-gateway>/v1"
export REVIEW_API_KEY="<your-key>"
export REVIEW_MODEL="gpt-6-astra" # 具体模型 ID 以官方文档当前版本为准
export REVIEW_MAX_FILES="40" # 单次 PR 最多评审的文件数
export REVIEW_TIMEOUT="180" # 单文件超时秒数
```
先用 curl 验证网关连通性和模型可用性：
```bash
curl -sS "$REVIEW_BASE_URL/chat/completions" \
-H "Authorization: Bearer $REVIEW_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"model\":\"$REVIEW_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"reply with ok\"}],\"max_tokens\":16}" \
| jq -r '.choices[0].message.content'
```
预期输出是 ok 之类的短回复。如果这里返回 401 或 404，先解决凭证和模型 ID，不要往下走——后面的规则调试都会被这个错误掩盖。
第 3 步：编写检测规则
规则文件放在仓库根目录并纳入版本管理，这样做的好处是规则变更也能被 Review。下面是示例结构，具体字段名以 Greptile 官方文档当前版本为准：
```json
{
"review": {
"paths": {
"include": ["src/", "services/", "packages/**"],
"exclude": ["**/*.lock", "vendor/", "/*.min.js", "dist/", "migrations/"]
},
"severity": {
"blocker": "request_changes",
"warning": "comment",
"nit": "off"
}
}
}
```
规则正文建议按"分级 + 可判定"来写，不要写"注意代码质量"这种无法执行的句子：
```markdown
blocker（必须修改）
- 用户输入或外部参数直接拼接进 SQL / shell 命令
- 数据库同一请求内多次写入，但未开启事务
- catch 块中既不记录日志也不重新抛出异常
- 打开的文件、连接、锁在异常路径上没有释放
warning（建议修改）
- 循环体内发起网络请求或数据库查询（N+1）
- 新增公开函数缺少参数校验或返回类型说明
- 时间处理未显式指定时区
不评论
- 命名风格、空行、import 排序、注释措辞
- 已在下文 ignore 列表中的历史遗留文件
```
实践建议：nit 级别默认关闭。评审工具一旦开始评论格式问题，团队就会形成"看到机器人评论就折叠"的条件反射，真正的 blocker 反而被忽略。
第 4 步：接进 PR 流程
先跑两周"影子模式"：只评论、不阻塞合并。等误报率降到团队可接受的水平，再把它设为必过检查。
在 GitHub 上，进入仓库 Settings → Branches → 分支保护规则，把 Greptile 的检查项加入 required status checks。GitLab 侧则在 Settings → Merge requests → Status checks 里做同样的事。
如果需要在 CI 里做一层兜底（比如评审超时就不许合并），可以用 gh 查询检查状态：
```bash
#!/usr/bin/env bash
scripts/wait_review.sh
set -euo pipefail
PR="${1:?usage: wait_review.sh <pr-number>}"
for i in $(seq 1 30); do
state=$(gh pr checks "$PR" --json name,state \
| jq -r '.[] | select(.name|test("greptile";"i")) | .state' | head -n1)
case "$state" in
SUCCESS) echo "review passed"; exit 0 ;;
FAILURE) echo "review blocked"; exit 1 ;;
*) echo "waiting... ($i)"; sleep 20 ;;
esac
done
echo "review timeout"; exit 1
```
对应的 workflow：
```yaml
name: ai-review-gate
on: pull_request
jobs:
gate:
runs-on: ubuntu-latest
permissions:
pull-requests: read
checks: read
steps:
- uses: actions/checkout@v4
- name: wait for review
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: bash scripts/wait_review.sh ${{ github.event.pull_request.number }}
```
第 5 步：建立误报治理闭环
这一步决定方案能不能长期活下去。做法是三步：
收纳：给每条被判定为误报的评论打上 ai-review:false-positive 标签，并在评论下回复一句原因。不要只点"踩"，原因才是后续规则的输入。
归因：每周把标签捞出来分类，常见四类——规则写得太宽、代码上下文没给够、历史遗留代码被反复报、模型对某个框架的惯用写法不熟。
```bash
gh pr list --label "ai-review:false-positive" --state all --limit 50 \
--json number,title,url | jq -r '.[] | "\(.number)\t\(.title)"'
```
固化：把每条误报转成一条可执行的修改——要么收窄规则措辞，要么把对应路径加进 exclude，要么把该模式写进"不评论"清单。同时把典型误报样本整理成一个小型回归集，规则改动后在测试仓库里跑一遍再合并。
一个具体例子：规则写"未校验返回值"，结果每个 print() 都被报。收窄成"调用返回 error 的函数后未检查 error 且继续使用返回值"，噪音立刻降下来。
验证部署是否成功
准备两个 PR 做对照验证。
正例 PR：故意引入一个可判定的 Bug，例如读文件后没有 defer close，或者拼接 SQL 字符串：
```go
func LoadUser(db *sql.DB, name string) (*User, error) {
row := db.QueryRow("SELECT id FROM users WHERE name = '" + name + "'")
// ...
}
```
预期结果：PR 上出现一条 blocker 级评论，明确指出注入风险和修改方向，且检查状态为失败。
反例 PR：纯格式化改动，只调整空行和 import 顺序。
预期结果：没有 blocker 或 warning 评论，检查状态为通过。
再用命令核对检查状态：
```bash
gh pr checks <PR编号>
```
预期能看到评审检查项出现在列表里，正例 PR 为 fail、反例 PR 为 pass。两项都符合，说明链路通了。
常见报错与解决
报错信息：PR 上没有任何评审评论，但控制台显示已连接
→ 原因：多半是索引未覆盖当前分支，或 PR 来自 fork 而 App 没有该 fork 的读取权限。
→ 解决：
```bash
确认分支在索引范围内，并从内部分支重新提一个 PR 验证
git checkout -b test/ai-review-probe
git commit --allow-empty -m "chore: probe ai review"
git push -u origin test/ai-review-probe
```
同时在控制台对该仓库手动触发一次重新索引，等索引状态变为完成后重试。
报错信息：401 Unauthorized 或 model_not_found
→ 原因：网关 Key 过期、模型 ID 拼写不一致，或该 Key 没有该模型权限。
→ 解决：
```bash
curl -sS "$REVIEW_BASE_URL/models" -H "Authorization: Bearer $REVIEW_API_KEY" | jq -r '.data[].id'
```
用返回列表里的 ID 覆盖 REVIEW_MODEL，并确认 CI 密钥里的值和本地一致（常见坑是只在本地导出过）。
报错信息：429 Too Many Requests / 评审排队超时
→ 原因：同时开启了多个大 PR 的评审，并发超过网关配额。
→ 解决：降低并发、把 REVIEW_MAX_FILES 调小，并对超大 PR 拆分。可在 workflow 里加并发限制：
```yaml
concurrency:
group: ai-review-${{ github.event.pull_request.number }}
cancel-in-progress: true
```
报错信息：评论内容空泛，或指向与改动无关的历史代码
→ 原因：规则太宽，或索引里塞进了大量生成代码和历史文件。
→ 解决：把 vendor/、dist/、*.min.js、锁文件加进 exclude；把规则从"注意错误处理"改写为可判定的具体句式；对历史遗留目录单独设 exclude 并在规则里注明"仅评审本次 diff 涉及的文件"。
报错信息：同一个问题在每个 PR 上重复出现
→ 原因：缺少去重与基线机制，历史问题被反复检出。
→ 解决：把该文件加入 exclude 清单，或在规则中加一条"以下已知问题不再评论"，并在团队内单独开一个技术债任务收敛。
后续维护
配置备份：greptile.json、规则文件、scripts/wait_review.sh 全部纳入 Git 管理，改动走 PR。这样规则变更本身也有 Review 记录，出问题能 git revert。
规则升级节奏：建议双周一次规则回顾，输入是这两周的误报标签和漏报（人工发现但工具没报的 Bug）。漏报比误报更值得投入，因为它直接决定团队是否信任这套工具。
日志与监控：在 CI 里保留每次评审的耗时、文件数、模型调用次数，汇总成周报。重点看三个指标——blocker 采纳率、误报率、平均评审时长。采纳率长期低于某个阈值，说明规则需要重写；平均时长突然上涨，通常是仓库体积变大或网关限流。
密钥轮换：网关 Key 定期轮换，只放在平台的 Secrets 里，不在 workflow 里 echo 出来。轮换后跑一次验证用的小 PR，确认链路没断。
成本控制：对大 PR 设置文件数上限，跳过生成目录，nit 级别保持关闭。这些手段对结论质量影响很小，但能明显减少调用量。
灰度推广：先在 1～2 个仓库跑一个月，把规则打磨到团队认可，再横向复制到其他仓库。复制时只搬规则文件和 exclude 清单，模型配置按各仓库实际调整——不同技术栈的误报模式差别很大，直接照搬往往会把噪音一起搬过去。