1. 项目概述reviewd你的本地AI代码审查助手如果你和我一样每天都要面对GitHub或BitBucket上堆积如山的Pull RequestPR同时还得兼顾手头的开发任务那你一定懂那种分身乏术的疲惫感。传统的CI/CD流水线集成AI审查工具往往意味着复杂的配置、额外的云服务订阅以及将代码暴露给第三方平台的安全顾虑。今天要聊的这个工具——reviewd它选择了一条截然不同的路把AI代码审查这件事彻底搬回你的本地终端。reviewd的核心定位非常清晰一个完全运行在你本地的、利用你已有AI CLI工具Claude Code、Gemini CLI或Codex CLI的自动化PR审查助手。它不引入任何新的云服务不要求你创建新账户也不依赖CI流水线。它的工作模式是直接读取你已经克隆到本地的Git仓库通过你本地安装并认证好的AI CLI工具来分析PR的代码变更然后将结构化的审查意见包括行内评论和总结直接发布到GitHub或BitBucket的PR页面上。整个过程你的代码从未离开过你的工作站。这个工具特别适合那些对代码质量和安全有较高要求但又希望审查流程能更智能、更高效的开发团队或个人。它无缝衔接了你现有的工作流你依然用git管理代码用GitHub/BitBucket协作只是现在多了一个24小时在线的、知识渊博的“虚拟同事”帮你做第一轮代码审查。对于开源项目维护者、中小型技术团队或者任何希望提升代码审查效率但不想增加复杂基础设施的开发者来说reviewd提供了一个极其轻量且强大的解决方案。2. 核心设计思路与架构解析2.1 为什么选择“完全本地化”的路径在决定采用reviewd之前我深入思考过市面上几种主流的AI代码审查方案。云服务方案如集成在GitHub Actions或BitBucket Pipelines中的第三方AI服务看似方便但存在几个无法回避的问题网络延迟、潜在的代码泄露风险、额外的订阅费用以及对完整代码库上下文访问的局限性CI环境通常是浅克隆。而reviewd的“完全本地化”设计恰恰精准地击中了这些痛点。它的设计哲学建立在几个关键假设上开发者已经拥有强大的本地计算资源现代开发者的机器性能足够运行大型语言模型LLM的推理。代码安全是最高优先级源代码是核心资产最安全的存放地点就是开发者的本地环境。现有工具链的复用价值最高开发者已经熟练使用git、claude/gemini/codexCLI等工具新工具应该无缝嵌入而非替代。完整的上下文至关重要高质量的代码审查需要理解整个项目的结构、依赖关系和编码规范这只有在完整的本地代码库中才能实现。基于这些假设reviewd的架构变得非常简洁高效它本质上是一个智能的调度器和协调器。它负责与代码托管平台Provider通信获取PR元数据在本地通过git worktree创建隔离的代码快照然后调用你本地的AI CLI工具去分析这个快照最后将AI输出的结构化结果翻译成平台API调用发布为评论。整个过程中reviewd自身不包含任何AI模型它只是你已有AI能力的“管道工”。2.2 核心工作流程拆解reviewd的工作流程是一个精心设计的管道每一步都考虑了效率、安全和幂等性。检查API - 状态检查 (SQLite) - 获取PR并创建工作树 - AI审查 - 解析JSON - 发布评论 - 清理检查APIPollingreviewd以可配置的时间间隔默认60秒轮询GitHub或BitBucket的API获取指定仓库的所有开放PR列表。这是一个无状态的拉取操作不需要配置复杂的Webhook降低了部署复杂度。状态检查SQLite这是避免重复劳动和垃圾评论的关键。每个获取到的PRreviewd会查询一个本地的SQLite数据库。这个数据库记录了(仓库名, PR ID, 最新审查的提交哈希)三元组。如果当前PR的最新提交哈希与数据库记录一致则跳过审查。同时这里还会应用其他过滤规则如是否为草稿PR、是否在冷却期内、差异行数是否过小等。获取PR并创建工作树Git Worktree对于需要审查的PRreviewd会使用git worktree命令。这是git的一个强大功能它允许你在不克隆新仓库的情况下为同一个仓库创建多个独立的、链接到同一.git目录的工作目录。这意味着速度极快无需重新下载整个仓库历史创建工作树几乎是瞬间完成的。空间高效多个工作树共享对象存储大大节省磁盘空间。完美隔离每个PR的审查都在独立的工作树中进行互不干扰审查结束后该工作树会被删除不会污染主工作区。reviewd会将PR对应的分支检出到这个独立的工作树中。AI审查这是核心环节。reviewd会在这个工作树目录中调用你配置的AI CLI如claude。它会构建一个包含完整上下文的提示词Prompt其中包含PR的元数据标题、描述、作者、完整的代码差异diff以及来自项目配置文件.reviewd.yaml的自定义审查指令。AI CLI会分析代码并按照预定义的JSON格式输出审查结果。解析JSONreviewd解析AI返回的JSON数据。这个结构通常包括一个总体摘要和一系列具体的“发现项”Findings每个发现项都有严重性等级如critical, suggestion, nitpick、关联的文件和行号、问题描述以及修复建议。发布评论reviewd将解析后的结果通过GitHub或BitBucket的API以行内评论针对特定代码行和总结评论针对整个PR的形式发布出去。清理发布完成后reviewd会删除为该PR创建的临时git worktree并更新SQLite数据库记录本次审查的提交哈希确保下次轮询时不会重复审查。这个流程确保了审查是增量式和资源友好的。只有发生变化的PR才会被处理并且每次审查都在一个干净的、临时的环境中进行。2.3 安全架构深度剖析让一个AI代理在本地运行并能执行命令听起来有点吓人。reviewd的设计者在安全方面做了层层设防这是我非常欣赏的一点。它遵循了“最小权限原则”和“深度防御”策略。第一层防御工作树隔离所有审查操作都在临时的git worktree中进行。即使AI在审查过程中意外或被恶意引导执行了rm -rf或写入垃圾文件受影响的也仅仅是这个即将被删除的临时目录你的原始工作副本和Git历史毫发无损。这是最物理、最彻底的一层隔离。第二层防御AI CLI的沙箱配置reviewd针对不同的AI CLI启用了最严格的默认沙箱选项对于Claude CLI使用--disallowedTools Write,Edit参数明确禁止了文件写入和编辑类工具。同时通过--mcp-config {mcpServers:{}} --strict-mcp-config禁用了所有外部模型上下文协议MCP服务器切断了AI访问外部工具如数据库、网络的可能。它运行在--print模式下只进行分析和输出。对于Gemini CLI安全模型相对较弱使用--approval-mode yolo无需确认直接执行命令。作为补偿reviewd通过-e none参数禁用了所有扩展功能并完全依赖第一层的工作树隔离来保证安全。对于Codex CLI使用codex exec并在--sandbox workspace-write模式下运行这是一个操作系统级别的沙箱将进程限制在工作目录内活动。第三层防御提示词安全指令在发送给AI的提示词最开头reviewd会插入一段强制的安全范围声明明确告知AI“你正在一个安全审查环境中禁止写入文件、禁止进行网络访问、禁止尝试访问密钥或敏感信息。”这虽然依赖AI的合规性但为意图良好的模型设置了明确的行为边界。第四层防御配置来源控制项目级的审查指令.reviewd.yaml和测试命令test_commands是从主仓库的默认分支读取的而不是从PR分支的工作树中读取。这意味着PR的提交者无法通过修改项目配置文件来注入恶意指令或改变AI的行为只有仓库所有者或拥有合并权限的人定义的规则才会生效。一个重要的安全共识reviewd在文档中明确强调它只应用于你信任其贡献者的仓库。这是一个社会层面的安全约定。工具提供了强大的技术保障但最终审查你代码的“人”即使是AI应该建立在信任的基础上。不要用它去审查来源不明或高度敏感的项目PR。3. 从零开始详细配置与实操指南3.1 环境准备与安装reviewd是一个Python工具要求Python 3.12或更高版本。安装非常简单推荐使用现代Python包管理工具uv它能更好地处理依赖隔离。# 使用pip安装确保在正确的虚拟环境中 pip install reviewd # 或者更推荐使用uv速度更快依赖管理更干净 uv tool install reviewd安装完成后在终端输入reviewd --help应该能看到命令列表这表示安装成功。核心依赖AI CLI工具reviewd本身不包含AI能力它需要调用以下三者之一Claude CLI: 需要从Anthropic官网下载安装并完成claude login认证。这是目前集成度最高、沙箱最严格的选项。Gemini CLI: Google的Gemini命令行工具同样需要安装和登录。Codex CLI: 这个选项可能更多用于特定场景或历史项目。请确保你选择的AI CLI已经在你的系统PATH中并且通过其自身的认证流程通常是交互式的浏览器登录。这是reviewd能工作的前提。无头服务器Headless Server部署注意事项如果你打算在服务器上运行reviewd例如团队共用的审查机器人Claude CLI的交互式登录会是个问题因为服务器没有浏览器。解决方案是生成一个长期有效的OAuth令牌# 在一台有浏览器的机器上每年只需一次 claude setup-token # 命令会输出一个令牌。 # 在你的服务器上设置环境变量 export CLAUDE_CODE_OAUTH_TOKEN你生成的令牌 # 然后就可以正常运行 reviewd watch 了这个令牌会使用你现有的Claude订阅Pro/Max/Team等有效期长达1年。或者你也可以直接设置ANTHROPIC_API_KEY环境变量来使用API计费模式这种方式没有过期时间。3.2 交互式初始化与配置详解最快捷的入门方式是使用交互式初始化向导reviewd init这个向导会做以下几件事扫描本地Git仓库它会搜索你机器上的常见代码目录如~/code,~/repos,~/projects等找出所有的Git仓库。检测远程仓库提供商自动识别仓库的remote URL是GitHub还是BitBucket。引导凭证配置根据检测到的提供商引导你创建并配置访问令牌Token。验证连通性测试令牌是否有效能否访问对应的仓库。生成配置文件根据你的选择生成全局配置文件~/.config/reviewd/config.yaml和/或项目级的配置文件.reviewd.yaml。如果你更喜欢直接编辑YAML文件可以运行reviewd init --sample来生成一个带有详细注释的配置模板。GitHub配置实战对于GitHub你需要一个Fine-grained Personal Access Token细粒度个人访问令牌。访问 GitHub Settings - Developer settings - Personal access tokens - Fine-grained tokens - Generate new token。给令牌起个名字如reviewd-local。**资源所有者Resource owner**选择你需要审查的仓库或个人账户。在权限Permissions部分找到Pull requests勾选Read and write。这是reviewd发布评论所必需的。生成令牌并复制。然后在你的全局配置中这样设置# ~/.config/reviewd/config.yaml github: token: ghp_your_generated_token_here # 或者使用环境变量替换${GITHUB_TOKEN} repos: - name: my-awesome-api # 你给这个仓库起的别名用于命令行 repo_slug: your-org/awesome-api # GitHub上的仓库路径 path: /home/you/code/awesome-api # 本地克隆的绝对路径 provider: githubBitBucket配置实战BitBucket的配置稍复杂因为它有Workspace工作空间的概念。推荐使用Workspace Access Token权限范围清晰。进入你的BitBucket工作空间点击设置齿轮 - Workspace settings - Security - Access tokens。创建新令牌在Permissions中选择Pull requests的Read和Write。生成令牌并复制。配置如下# ~/.config/reviewd/config.yaml bitbucket: your-workspace-name: ATCTT3xFx...your_token_here # Bearer认证方式 repos: - name: bb-frontend path: /home/you/code/frontend provider: bitbucket workspace: your-workspace-name # 与上面的key对应 repo_slug: your-team/frontend-repo # BitBucket仓库slug一个配置多仓库的示例你可以在一个配置文件中管理来自不同提供商、使用不同AI后端的多个仓库。# ~/.config/reviewd/config.yaml poll_interval_seconds: 120 # 每2分钟检查一次新PR max_concurrent_reviews: 2 # 同时最多审查2个PR避免资源耗尽 github: token: ${GITHUB_TOKEN} # 从环境变量读取 bitbucket: my-company: ${BITBUCKET_TOKEN} cli: claude # 全局默认使用Claude model: claude-3-5-sonnet-20241022 # 指定模型 # 全局审查指令 instructions: | 请以专业、建设性的态度进行代码审查。 重点关注意图是否清晰、是否有潜在bug、性能问题和代码风格一致性。 对于发现的问题请提供具体的修改建议。 repos: - name: backend-service repo_slug: my-company/backend path: ~/projects/backend provider: github # 继承全局cli和model - name:># .reviewd.yaml # 项目特定的审查指令会覆盖全局指令 instructions: | 本项目使用Python 3.12和FastAPI。 审查时请特别注意 1. 异步函数是否正确使用async/await避免阻塞调用。 2. Pydantic模型字段定义是否准确有无遗漏Optional。 3. 数据库查询是否使用了异步Session有无N1查询问题。 4. 遵循项目内的ruff和mypy配置。 # 在AI审查前运行的测试命令列表 # 这些命令运行在PR代码的临时工作树中 test_commands: - uv run ruff check . --fix # 先自动修复可修复的风格问题 - uv run ruff check . --output-formatconcise # 再次检查输出剩余问题 - uv run mypy . --strict - uv run pytest tests/ -v --tbshort # 严重性过滤与展示控制 skip_severities: [nitpick] # 完全忽略标记为“nitpick”吹毛求疵的发现项 inline_comments_for: [critical, suggestion] # 只有“关键”和“建议”级问题发布为行内评论 # max_inline_comments: 10 # 如果行内评论超过10条则全部转为总结评论避免刷屏 # 触发审查的阈值 min_diff_lines: 10 # 差异少于10行的PR跳过审查可用于忽略仅修改文档的PR min_diff_lines_update: 5 # 对于已有评论的PR新推送的提交至少要有5行差异才触发重新审查 review_cooldown_minutes: 45 # 对同一个PR两次审查之间至少间隔45分钟 # BitBucket专属为“关键”发现项创建PR任务Task阻塞合并 critical_task: true # 自动批准配置见下文详解 auto_approve: enabled: true max_diff_lines: 100 max_severity: suggestion # 允许最高到“建议”级别如果出现“关键”则阻塞批准 max_findings: 5 # “良好”发现项不计入此数 rules: | 仅批准安全、简单的变更 - 拼写错误修正、注释更新、日志信息改进 - 简单的依赖版本升级非主要版本 - 不影响逻辑的重命名、常量提取 - 明确的、独立的bug修复有测试覆盖为佳 以下情况绝不自动批准 - 涉及数据库迁移migrations的更改 - 核心业务逻辑的修改 - 新增外部API调用或第三方服务集成 - 权限或身份验证相关的变更。test_commands的威力这是reviewd一个非常强大的功能。AI在审查代码前会先在你的PR代码上运行这些命令。如果ruff检查出风格错误或者pytest测试失败了这些执行结果会被自动捕获并包含在送给AI的上下文里。这意味着AI在分析时已经知道了“代码的静态检查不过”或“测试挂了”这个事实它的审查意见会结合这些实际运行结果变得更加精准和有针对性。这相当于把自动化测试和静态分析工具的结果作为先验知识喂给了AI审查员。4. 核心功能实战命令详解与应用场景4.1 单次审查与持续监控reviewd提供了两种主要的工作模式适应不同的使用场景。1. 单次审查On-demand Review当你只想针对某个特定的PR进行审查时使用pr命令。# 审查别名为“backend-service”的仓库中编号为123的PR reviewd pr backend-service 123 # 干跑模式Dry-run预览AI会生成什么评论但不会真正发布到PR上 # 这是调试配置和审查指令的绝佳方式 reviewd pr backend-service 123 --dry-run # 强制审查Force忽略冷却时间、已审查状态等所有限制强制重新审查 # 适用于PR经过重大修改后你想立即获得新的AI反馈 reviewd pr backend-service 123 --force单次审查模式非常灵活适合集成到你的个人工作流中。例如你可以在本地修改代码后先让reviewd审查一下自己的PR提前发现潜在问题。2. 持续监控模式Daemon Mode这是reviewd作为“自动化助手”的核心模式。运行watch命令后它会作为一个常驻进程持续扫描你配置的所有仓库。# 启动监控使用全局配置 reviewd watch # 详细模式输出更多日志便于观察运行状态和调试 reviewd watch -v # 干跑模式下的监控只模拟不发布用于安全测试 reviewd watch -v --dry-run # 启动时顺便审查所有当前已打开但尚未被reviewd审过的PR reviewd watch -v --review-existing # 提高并发度同时审查更多PR需确保机器性能和AI API限额足够 reviewd watch --concurrency 6持续监控模式通常部署在团队共用的开发机或服务器上作为一个后台服务运行。它可以确保团队内每一个新开的PR都能在几分钟内获得初步的AI审查意见大大缩短代码等待审查的周期。4.2 自动批准Auto-Approve信任但验证auto_approve功能是reviewd走向“智能化决策”的关键一步。它不仅仅是根据规则过滤而是让AI参与决策过程。工作原理分步解析常规审查AI首先对PR进行完整的代码审查生成一系列发现项Findings并为每个发现项标记严重性。AI评估reviewd会将你在配置中定义的auto_approve.rules规则作为额外指令再次提交给AI。AI需要基于刚刚完成的审查结果结合这些规则判断“这个PR是否应该被自动批准”。AI需要输出一个布尔值的approve和一个文本的reason理由。硬性关卡检查在AI说“可以批准”之后reviewd还会用三个硬性指标进行复核max_diff_lines: PR的代码差异总行数是否超过阈值超过则否决。max_severity: PR中所有发现项的最高严重性是否超过允许级别如出现了critical超过则否决。max_findings: 排除good正面评价后发现项总数是否超过阈值超过则否决。最终决策与执行只有当AI建议批准且所有硬性关卡都通过时reviewd才会调用GitHub/BitBucket的API代表你或配置的机器人账户批准Approve这个PR。同时AI提供的批准理由会被添加到总结评论中让其他开发者了解自动批准的原因。这个设计巧妙在哪它结合了AI的语义理解能力和工具的确定性规则。规则rules是模糊的、需要理解的比如“简单的bug修复”这部分交给AI判断。而代码行数、问题数量是明确的、可量化的这部分由工具严格把关。两者结合既避免了AI的“随意发挥”又赋予了工具处理复杂情况的能力。配置心得规则rules要具体不要写“批准好的代码”。要像给新人写审查指南一样列举出具体场景。例如“批准仅修改了README或文档字符串的PR”、“批准只更新了.gitignore或配置文件注释的PR”。阈值max_*要保守自动批准应该只用于那些风险极低、变更极小的PR。建议初始设置非常严格例如max_diff_lines: 30,max_severity: nitpick,max_findings: 1运行一段时间观察效果后再逐步放宽。理由reason是黄金一定要让AI提供批准理由。这不仅是审计日志更是对团队其他成员的沟通。当大家看到一个PR被自动批准时能立刻明白为什么这能建立对自动化流程的信任。4.3 状态管理与数据查看reviewd使用SQLite数据库来记录状态也提供了命令来查看这些信息。# 列出所有已配置的仓库及其状态 reviewd ls # 输出示例 # Repo: backend-service (github:your-org/backend) ~/projects/backend # Open PRs: 3 # * #123: feat: add user auth [unreviewed] # * #122: fix: typo in config [reviewed a1b2c3d] # * #121: chore: update deps [cooldown until 14:30] # 查看某个仓库的审查历史 reviewd status backend-service这些命令帮你快速了解哪些PR待审哪些已审以及工具的运行概况。5. 高级技巧与避坑指南在实际使用和与团队推广reviewd的过程中我积累了一些宝贵的经验和需要避开的“坑”。5.1 审查指令Instructions的编写艺术instructions是控制AI审查行为的核心。写得好AI就是你的得力助手写得不好它可能只会说一些正确的废话。反面教材过于空泛instructions: | 请检查代码质量。这种指令几乎没用AI不知道你的“质量”具体指什么。正面教材具体、可操作instructions: | 你是一个经验丰富的Python后端工程师正在审查一个FastAPI项目的PR。 审查重点 1. **安全性**检查是否有SQL注入风险字符串拼接、敏感信息硬编码、缺少输入验证。 2. **性能**检查循环内是否有重复的数据库查询N1问题、是否使用了不当的数据结构如列表代替集合进行成员检查。 3. **可维护性**函数是否过长50行、是否有清晰的命名、注释是否解释了“为什么”而不是“是什么”。 4. **API设计**端点路径是否符合RESTful约定、状态码使用是否恰当、响应模型定义是否完整。 5. **错误处理**是否有未捕获的异常、错误信息是否对用户友好、是否有适当的日志记录。 对于每个发现的问题 - 必须使用以下严重性标签之一[critical, suggestion, nitpick, good]。 - 必须指明具体的文件路径和行号。 - 必须提供**具体的、可执行的修改建议或代码示例**。 - 如果是“good”发现项请指出代码的优秀之处以资鼓励。好的指令就像一份清晰的工作说明书它设定了角色、明确了优先级、给出了具体的检查清单和输出格式要求。5.2 处理大型PR与性能优化默认情况下reviewd会将整个PR的diff和相关的文件内容发送给AI。对于大型PR修改文件多、行数多这可能导致上下文超长超出AI模型的上下文窗口导致分析不完整或被截断。API调用缓慢且昂贵处理大量tokens需要更长时间和更高费用。审查质量下降AI可能难以在庞杂的变更中抓住重点。应对策略设置min_diff_lines阈值在.reviewd.yaml中设置一个较大的值比如200自动跳过过于庞大的PR要求人工介入。可以在指令中说明“本工具适用于中小型PR大型重构请进行人工深度审查。”分而治之鼓励开发者将大型功能拆分成多个逻辑独立的小型PR。这不仅利于AI审查也符合优秀的代码协作实践。利用test_commands对于大型PR确保你的测试套件pytest和静态分析工具ruff,mypy足够强大。让这些工具先跑一遍把明显的错误和风格问题筛出来AI可以更专注于逻辑和设计问题。模型选择如果使用Claudeclaude-3-5-sonnet在处理长上下文和复杂代码方面通常比haiku更强但成本也更高。需要权衡。5.3 与团队工作流的整合引入一个自动化工具最大的挑战往往不是技术而是人。如何让团队接受并善用reviewd明确定位在团队内宣导reviewd是“第一轮过滤器”和“学习助手”而非“最终裁决者”。它的目的是发现显而易见的错误、统一代码风格、并提出可能被忽略的角度为人类审查者节省时间。最终合并的权力和责任仍在人类手中。从“只评论”开始初期不要启用auto_approve功能。让reviewd只发表评论让团队成员习惯阅读它的反馈并讨论这些反馈是否有价值。这有一个磨合与教育的过程。创建团队共享配置将优化后的.reviewd.yaml配置文件放在团队项目的根目录。这能确保所有成员以及CI系统使用同一套审查标准。可以将审查指令的制定过程作为团队代码规范讨论的一部分。处理误报与漏报建立一个简单的反馈机制。如果AI频繁给出无用的建议误报或者漏掉了明显问题漏报将这些案例记录下来。然后反过来优化你的instructions和test_commands。例如如果AI总在某个编码风格上纠缠而团队认为可以接受就在指令中明确说明“忽略XXX风格问题”。这是一个迭代调优的过程。善用“跳过”模式不是每个PR都需要AI审查。在PR标题中加入[no-review]、[wip]等标记通过skip_title_patterns配置可以让reviewd自动跳过。这给了开发者完全的控制权。5.4 安全与权限管理再强调令牌权限最小化无论是GitHub的Fine-grained Token还是BitBucket的Workspace Token都只授予Pull requests: Read Write权限。不要给予repo完全控制仓库或workflow等不必要的权限。环境变量存储切勿将令牌硬编码在配置文件中然后提交到Git。务必使用环境变量如${GITHUB_TOKEN}并在运行reviewd的机器上设置这些变量。审查机器隔离如果是在服务器上运行reviewd watch最好使用一个专用的、权限受限的系统账户或容器来运行它。避免使用具有高权限的个人账户。定期审计日志reviewd自身的日志输出结合GitHub/BitBucket的审计日志可以帮助你追踪自动化审查的活动。6. 故障排查与常见问题即使配置正确在实际运行中也可能遇到一些问题。以下是一些常见情况及其解决方法。6.1 AI CLI相关问题问题reviewd报错“Failed to invoke CLI: Command ‘claude’ not found”原因系统找不到claude或gemini、codex命令。解决确认AI CLI已正确安装。在终端直接输入claude --version看是否有输出。如果已安装但reviewd找不到可能是PATH问题。尝试使用绝对路径在配置中指定cli: /usr/local/bin/claude # 或你的实际安装路径如果你使用虚拟环境venv/conda确保reviewd和AI CLI在同一个环境或者AI CLI在系统PATH中。问题AI审查耗时过长或无响应原因PR过大上下文太长。AI服务API限速或网络问题。本地机器资源CPU/内存不足。解决检查PR的diff大小。考虑设置min_diff_lines过滤超大PR。查看reviewd watch -v的详细日志看卡在哪一步。如果是API调用超时可能是网络或服务商问题。降低max_concurrent_reviews默认4减少并行任务缓解资源压力。6.2 Git与仓库问题问题reviewd报告“Git repository not found at path: /some/path”原因配置文件中path指向的目录不存在或者不是一个Git仓库。解决运行reviewd ls检查配置的仓库路径是否正确。确保路径是绝对路径。使用~家目录符号有时可能解析错误建议使用完整路径如/home/username/projects/repo。手动进入该路径执行git status确认仓库状态正常。问题reviewd无法为PR创建工作树提示“git worktree add failed”原因目标目录已存在或者Git状态有冲突。解决reviewd会在临时目录如/tmp下创建工作树。如果之前运行意外中断可能残留了锁文件或目录。可以尝试清理reviewd的临时目录通常位于系统临时目录下的reviewd-*文件夹。重启reviewd进程。检查主仓库的.git目录是否完好。6.3 配置与网络问题问题reviewd能运行但无法获取PR列表或发布评论提示API错误原因令牌无效、权限不足或网络无法访问代码托管平台。解决验证令牌手动使用curl命令测试令牌。GitHub:curl -H Authorization: token ghp_yourtoken https://api.github.com/userBitBucket:curl -u your-email:your-api-token https://api.bitbucket.org/2.0/user检查权限确认令牌确实有Pull requests的读写权限。GitHub的Fine-grained Token作用范围Repository access是否包含了目标仓库检查网络如果你在公司网络可能需要配置代理。reviewd目前不直接支持代理配置你需要设置全局的HTTP代理环境变量如HTTP_PROXY,HTTPS_PROXY。问题AI的评论格式混乱或者没有出现在正确的代码行原因AI没有严格按照JSON Schema输出或者diff解析出错。解决使用--dry-run模式运行一次查看reviewd打印的、准备发送给AI的完整提示词和AI返回的原始响应。检查AI的回复是否是一个合法的JSON并且包含了file,line等必要字段。这可能与你的instructions有关。在指令中更明确地要求AI输出格式例如“你必须以严格的JSON格式输出包含findings数组每个finding必须有file, line, severity, description, suggestion字段。”确保你使用的AI模型支持可靠的JSON输出模式如Claude的--format json。在全局配置中指定model时选择一个已知的、擅长结构化输出的模型版本。6.4 数据库与状态问题问题reviewd重复审查同一个提交原因SQLite状态数据库损坏或锁定。解决reviewd的状态数据库默认位于~/.local/share/reviewd/reviewd.db遵循XDG规范。你可以停止reviewd进程。备份并删除这个数据库文件。重启reviewd。它会创建一个新的空数据库但这意味着它会重新审查所有打开的PR。对于已经处理过的PR你可以手动标记为已读或者暂时忽略。问题如何手动重置某个PR的审查状态场景PR经过重大修改你希望reviewd重新审查但又不想用--force命令每次都指定。解决可以直接操作SQLite数据库请谨慎操作sqlite3 ~/.local/share/reviewd/reviewd.db -- 查找记录 SELECT * FROM review_state WHERE repo_slug LIKE %your-repo%; -- 删除特定PR的记录 DELETE FROM review_state WHERE repo_slug owner/repo AND pr_id 123; .quit删除对应记录后下次轮询时reviewd会认为这个PR从未被审查过。经过数月的实践reviewd已经成为了我们团队开发流程中一个“沉默而高效”的成员。它不会取代深入的、富有洞察力的人工代码审查但它成功地接管了那些繁琐的、模式化的检查工作——比如拼写错误、简单的语法问题、遗漏的导入、不符合团队风格的格式等。这让人类审查者能够更专注于架构设计、算法效率和业务逻辑这些更需要创造力和经验的部分。它的配置过程虽然有一点点学习曲线但一旦跑通其带来的效率提升和代码质量保障是显而易见的。如果你也在寻找一种不增加基础设施复杂度、又能显著提升代码审查体验的方案reviewd绝对值得你花上一个下午的时间来尝试和配置。
本地AI代码审查工具reviewd：安全高效的自动化PR审查实践
发布时间：2026/7/26 13:43:11
1. 项目概述reviewd你的本地AI代码审查助手如果你和我一样每天都要面对GitHub或BitBucket上堆积如山的Pull RequestPR同时还得兼顾手头的开发任务那你一定懂那种分身乏术的疲惫感。传统的CI/CD流水线集成AI审查工具往往意味着复杂的配置、额外的云服务订阅以及将代码暴露给第三方平台的安全顾虑。今天要聊的这个工具——reviewd它选择了一条截然不同的路把AI代码审查这件事彻底搬回你的本地终端。reviewd的核心定位非常清晰一个完全运行在你本地的、利用你已有AI CLI工具Claude Code、Gemini CLI或Codex CLI的自动化PR审查助手。它不引入任何新的云服务不要求你创建新账户也不依赖CI流水线。它的工作模式是直接读取你已经克隆到本地的Git仓库通过你本地安装并认证好的AI CLI工具来分析PR的代码变更然后将结构化的审查意见包括行内评论和总结直接发布到GitHub或BitBucket的PR页面上。整个过程你的代码从未离开过你的工作站。这个工具特别适合那些对代码质量和安全有较高要求但又希望审查流程能更智能、更高效的开发团队或个人。它无缝衔接了你现有的工作流你依然用git管理代码用GitHub/BitBucket协作只是现在多了一个24小时在线的、知识渊博的“虚拟同事”帮你做第一轮代码审查。对于开源项目维护者、中小型技术团队或者任何希望提升代码审查效率但不想增加复杂基础设施的开发者来说reviewd提供了一个极其轻量且强大的解决方案。2. 核心设计思路与架构解析2.1 为什么选择“完全本地化”的路径在决定采用reviewd之前我深入思考过市面上几种主流的AI代码审查方案。云服务方案如集成在GitHub Actions或BitBucket Pipelines中的第三方AI服务看似方便但存在几个无法回避的问题网络延迟、潜在的代码泄露风险、额外的订阅费用以及对完整代码库上下文访问的局限性CI环境通常是浅克隆。而reviewd的“完全本地化”设计恰恰精准地击中了这些痛点。它的设计哲学建立在几个关键假设上开发者已经拥有强大的本地计算资源现代开发者的机器性能足够运行大型语言模型LLM的推理。代码安全是最高优先级源代码是核心资产最安全的存放地点就是开发者的本地环境。现有工具链的复用价值最高开发者已经熟练使用git、claude/gemini/codexCLI等工具新工具应该无缝嵌入而非替代。完整的上下文至关重要高质量的代码审查需要理解整个项目的结构、依赖关系和编码规范这只有在完整的本地代码库中才能实现。基于这些假设reviewd的架构变得非常简洁高效它本质上是一个智能的调度器和协调器。它负责与代码托管平台Provider通信获取PR元数据在本地通过git worktree创建隔离的代码快照然后调用你本地的AI CLI工具去分析这个快照最后将AI输出的结构化结果翻译成平台API调用发布为评论。整个过程中reviewd自身不包含任何AI模型它只是你已有AI能力的“管道工”。2.2 核心工作流程拆解reviewd的工作流程是一个精心设计的管道每一步都考虑了效率、安全和幂等性。检查API - 状态检查 (SQLite) - 获取PR并创建工作树 - AI审查 - 解析JSON - 发布评论 - 清理检查APIPollingreviewd以可配置的时间间隔默认60秒轮询GitHub或BitBucket的API获取指定仓库的所有开放PR列表。这是一个无状态的拉取操作不需要配置复杂的Webhook降低了部署复杂度。状态检查SQLite这是避免重复劳动和垃圾评论的关键。每个获取到的PRreviewd会查询一个本地的SQLite数据库。这个数据库记录了(仓库名, PR ID, 最新审查的提交哈希)三元组。如果当前PR的最新提交哈希与数据库记录一致则跳过审查。同时这里还会应用其他过滤规则如是否为草稿PR、是否在冷却期内、差异行数是否过小等。获取PR并创建工作树Git Worktree对于需要审查的PRreviewd会使用git worktree命令。这是git的一个强大功能它允许你在不克隆新仓库的情况下为同一个仓库创建多个独立的、链接到同一.git目录的工作目录。这意味着速度极快无需重新下载整个仓库历史创建工作树几乎是瞬间完成的。空间高效多个工作树共享对象存储大大节省磁盘空间。完美隔离每个PR的审查都在独立的工作树中进行互不干扰审查结束后该工作树会被删除不会污染主工作区。reviewd会将PR对应的分支检出到这个独立的工作树中。AI审查这是核心环节。reviewd会在这个工作树目录中调用你配置的AI CLI如claude。它会构建一个包含完整上下文的提示词Prompt其中包含PR的元数据标题、描述、作者、完整的代码差异diff以及来自项目配置文件.reviewd.yaml的自定义审查指令。AI CLI会分析代码并按照预定义的JSON格式输出审查结果。解析JSONreviewd解析AI返回的JSON数据。这个结构通常包括一个总体摘要和一系列具体的“发现项”Findings每个发现项都有严重性等级如critical, suggestion, nitpick、关联的文件和行号、问题描述以及修复建议。发布评论reviewd将解析后的结果通过GitHub或BitBucket的API以行内评论针对特定代码行和总结评论针对整个PR的形式发布出去。清理发布完成后reviewd会删除为该PR创建的临时git worktree并更新SQLite数据库记录本次审查的提交哈希确保下次轮询时不会重复审查。这个流程确保了审查是增量式和资源友好的。只有发生变化的PR才会被处理并且每次审查都在一个干净的、临时的环境中进行。2.3 安全架构深度剖析让一个AI代理在本地运行并能执行命令听起来有点吓人。reviewd的设计者在安全方面做了层层设防这是我非常欣赏的一点。它遵循了“最小权限原则”和“深度防御”策略。第一层防御工作树隔离所有审查操作都在临时的git worktree中进行。即使AI在审查过程中意外或被恶意引导执行了rm -rf或写入垃圾文件受影响的也仅仅是这个即将被删除的临时目录你的原始工作副本和Git历史毫发无损。这是最物理、最彻底的一层隔离。第二层防御AI CLI的沙箱配置reviewd针对不同的AI CLI启用了最严格的默认沙箱选项对于Claude CLI使用--disallowedTools Write,Edit参数明确禁止了文件写入和编辑类工具。同时通过--mcp-config {mcpServers:{}} --strict-mcp-config禁用了所有外部模型上下文协议MCP服务器切断了AI访问外部工具如数据库、网络的可能。它运行在--print模式下只进行分析和输出。对于Gemini CLI安全模型相对较弱使用--approval-mode yolo无需确认直接执行命令。作为补偿reviewd通过-e none参数禁用了所有扩展功能并完全依赖第一层的工作树隔离来保证安全。对于Codex CLI使用codex exec并在--sandbox workspace-write模式下运行这是一个操作系统级别的沙箱将进程限制在工作目录内活动。第三层防御提示词安全指令在发送给AI的提示词最开头reviewd会插入一段强制的安全范围声明明确告知AI“你正在一个安全审查环境中禁止写入文件、禁止进行网络访问、禁止尝试访问密钥或敏感信息。”这虽然依赖AI的合规性但为意图良好的模型设置了明确的行为边界。第四层防御配置来源控制项目级的审查指令.reviewd.yaml和测试命令test_commands是从主仓库的默认分支读取的而不是从PR分支的工作树中读取。这意味着PR的提交者无法通过修改项目配置文件来注入恶意指令或改变AI的行为只有仓库所有者或拥有合并权限的人定义的规则才会生效。一个重要的安全共识reviewd在文档中明确强调它只应用于你信任其贡献者的仓库。这是一个社会层面的安全约定。工具提供了强大的技术保障但最终审查你代码的“人”即使是AI应该建立在信任的基础上。不要用它去审查来源不明或高度敏感的项目PR。3. 从零开始详细配置与实操指南3.1 环境准备与安装reviewd是一个Python工具要求Python 3.12或更高版本。安装非常简单推荐使用现代Python包管理工具uv它能更好地处理依赖隔离。# 使用pip安装确保在正确的虚拟环境中 pip install reviewd # 或者更推荐使用uv速度更快依赖管理更干净 uv tool install reviewd安装完成后在终端输入reviewd --help应该能看到命令列表这表示安装成功。核心依赖AI CLI工具reviewd本身不包含AI能力它需要调用以下三者之一Claude CLI: 需要从Anthropic官网下载安装并完成claude login认证。这是目前集成度最高、沙箱最严格的选项。Gemini CLI: Google的Gemini命令行工具同样需要安装和登录。Codex CLI: 这个选项可能更多用于特定场景或历史项目。请确保你选择的AI CLI已经在你的系统PATH中并且通过其自身的认证流程通常是交互式的浏览器登录。这是reviewd能工作的前提。无头服务器Headless Server部署注意事项如果你打算在服务器上运行reviewd例如团队共用的审查机器人Claude CLI的交互式登录会是个问题因为服务器没有浏览器。解决方案是生成一个长期有效的OAuth令牌# 在一台有浏览器的机器上每年只需一次 claude setup-token # 命令会输出一个令牌。 # 在你的服务器上设置环境变量 export CLAUDE_CODE_OAUTH_TOKEN你生成的令牌 # 然后就可以正常运行 reviewd watch 了这个令牌会使用你现有的Claude订阅Pro/Max/Team等有效期长达1年。或者你也可以直接设置ANTHROPIC_API_KEY环境变量来使用API计费模式这种方式没有过期时间。3.2 交互式初始化与配置详解最快捷的入门方式是使用交互式初始化向导reviewd init这个向导会做以下几件事扫描本地Git仓库它会搜索你机器上的常见代码目录如~/code,~/repos,~/projects等找出所有的Git仓库。检测远程仓库提供商自动识别仓库的remote URL是GitHub还是BitBucket。引导凭证配置根据检测到的提供商引导你创建并配置访问令牌Token。验证连通性测试令牌是否有效能否访问对应的仓库。生成配置文件根据你的选择生成全局配置文件~/.config/reviewd/config.yaml和/或项目级的配置文件.reviewd.yaml。如果你更喜欢直接编辑YAML文件可以运行reviewd init --sample来生成一个带有详细注释的配置模板。GitHub配置实战对于GitHub你需要一个Fine-grained Personal Access Token细粒度个人访问令牌。访问 GitHub Settings - Developer settings - Personal access tokens - Fine-grained tokens - Generate new token。给令牌起个名字如reviewd-local。**资源所有者Resource owner**选择你需要审查的仓库或个人账户。在权限Permissions部分找到Pull requests勾选Read and write。这是reviewd发布评论所必需的。生成令牌并复制。然后在你的全局配置中这样设置# ~/.config/reviewd/config.yaml github: token: ghp_your_generated_token_here # 或者使用环境变量替换${GITHUB_TOKEN} repos: - name: my-awesome-api # 你给这个仓库起的别名用于命令行 repo_slug: your-org/awesome-api # GitHub上的仓库路径 path: /home/you/code/awesome-api # 本地克隆的绝对路径 provider: githubBitBucket配置实战BitBucket的配置稍复杂因为它有Workspace工作空间的概念。推荐使用Workspace Access Token权限范围清晰。进入你的BitBucket工作空间点击设置齿轮 - Workspace settings - Security - Access tokens。创建新令牌在Permissions中选择Pull requests的Read和Write。生成令牌并复制。配置如下# ~/.config/reviewd/config.yaml bitbucket: your-workspace-name: ATCTT3xFx...your_token_here # Bearer认证方式 repos: - name: bb-frontend path: /home/you/code/frontend provider: bitbucket workspace: your-workspace-name # 与上面的key对应 repo_slug: your-team/frontend-repo # BitBucket仓库slug一个配置多仓库的示例你可以在一个配置文件中管理来自不同提供商、使用不同AI后端的多个仓库。# ~/.config/reviewd/config.yaml poll_interval_seconds: 120 # 每2分钟检查一次新PR max_concurrent_reviews: 2 # 同时最多审查2个PR避免资源耗尽 github: token: ${GITHUB_TOKEN} # 从环境变量读取 bitbucket: my-company: ${BITBUCKET_TOKEN} cli: claude # 全局默认使用Claude model: claude-3-5-sonnet-20241022 # 指定模型 # 全局审查指令 instructions: | 请以专业、建设性的态度进行代码审查。 重点关注意图是否清晰、是否有潜在bug、性能问题和代码风格一致性。 对于发现的问题请提供具体的修改建议。 repos: - name: backend-service repo_slug: my-company/backend path: ~/projects/backend provider: github # 继承全局cli和model - name:># .reviewd.yaml # 项目特定的审查指令会覆盖全局指令 instructions: | 本项目使用Python 3.12和FastAPI。 审查时请特别注意 1. 异步函数是否正确使用async/await避免阻塞调用。 2. Pydantic模型字段定义是否准确有无遗漏Optional。 3. 数据库查询是否使用了异步Session有无N1查询问题。 4. 遵循项目内的ruff和mypy配置。 # 在AI审查前运行的测试命令列表 # 这些命令运行在PR代码的临时工作树中 test_commands: - uv run ruff check . --fix # 先自动修复可修复的风格问题 - uv run ruff check . --output-formatconcise # 再次检查输出剩余问题 - uv run mypy . --strict - uv run pytest tests/ -v --tbshort # 严重性过滤与展示控制 skip_severities: [nitpick] # 完全忽略标记为“nitpick”吹毛求疵的发现项 inline_comments_for: [critical, suggestion] # 只有“关键”和“建议”级问题发布为行内评论 # max_inline_comments: 10 # 如果行内评论超过10条则全部转为总结评论避免刷屏 # 触发审查的阈值 min_diff_lines: 10 # 差异少于10行的PR跳过审查可用于忽略仅修改文档的PR min_diff_lines_update: 5 # 对于已有评论的PR新推送的提交至少要有5行差异才触发重新审查 review_cooldown_minutes: 45 # 对同一个PR两次审查之间至少间隔45分钟 # BitBucket专属为“关键”发现项创建PR任务Task阻塞合并 critical_task: true # 自动批准配置见下文详解 auto_approve: enabled: true max_diff_lines: 100 max_severity: suggestion # 允许最高到“建议”级别如果出现“关键”则阻塞批准 max_findings: 5 # “良好”发现项不计入此数 rules: | 仅批准安全、简单的变更 - 拼写错误修正、注释更新、日志信息改进 - 简单的依赖版本升级非主要版本 - 不影响逻辑的重命名、常量提取 - 明确的、独立的bug修复有测试覆盖为佳 以下情况绝不自动批准 - 涉及数据库迁移migrations的更改 - 核心业务逻辑的修改 - 新增外部API调用或第三方服务集成 - 权限或身份验证相关的变更。test_commands的威力这是reviewd一个非常强大的功能。AI在审查代码前会先在你的PR代码上运行这些命令。如果ruff检查出风格错误或者pytest测试失败了这些执行结果会被自动捕获并包含在送给AI的上下文里。这意味着AI在分析时已经知道了“代码的静态检查不过”或“测试挂了”这个事实它的审查意见会结合这些实际运行结果变得更加精准和有针对性。这相当于把自动化测试和静态分析工具的结果作为先验知识喂给了AI审查员。4. 核心功能实战命令详解与应用场景4.1 单次审查与持续监控reviewd提供了两种主要的工作模式适应不同的使用场景。1. 单次审查On-demand Review当你只想针对某个特定的PR进行审查时使用pr命令。# 审查别名为“backend-service”的仓库中编号为123的PR reviewd pr backend-service 123 # 干跑模式Dry-run预览AI会生成什么评论但不会真正发布到PR上 # 这是调试配置和审查指令的绝佳方式 reviewd pr backend-service 123 --dry-run # 强制审查Force忽略冷却时间、已审查状态等所有限制强制重新审查 # 适用于PR经过重大修改后你想立即获得新的AI反馈 reviewd pr backend-service 123 --force单次审查模式非常灵活适合集成到你的个人工作流中。例如你可以在本地修改代码后先让reviewd审查一下自己的PR提前发现潜在问题。2. 持续监控模式Daemon Mode这是reviewd作为“自动化助手”的核心模式。运行watch命令后它会作为一个常驻进程持续扫描你配置的所有仓库。# 启动监控使用全局配置 reviewd watch # 详细模式输出更多日志便于观察运行状态和调试 reviewd watch -v # 干跑模式下的监控只模拟不发布用于安全测试 reviewd watch -v --dry-run # 启动时顺便审查所有当前已打开但尚未被reviewd审过的PR reviewd watch -v --review-existing # 提高并发度同时审查更多PR需确保机器性能和AI API限额足够 reviewd watch --concurrency 6持续监控模式通常部署在团队共用的开发机或服务器上作为一个后台服务运行。它可以确保团队内每一个新开的PR都能在几分钟内获得初步的AI审查意见大大缩短代码等待审查的周期。4.2 自动批准Auto-Approve信任但验证auto_approve功能是reviewd走向“智能化决策”的关键一步。它不仅仅是根据规则过滤而是让AI参与决策过程。工作原理分步解析常规审查AI首先对PR进行完整的代码审查生成一系列发现项Findings并为每个发现项标记严重性。AI评估reviewd会将你在配置中定义的auto_approve.rules规则作为额外指令再次提交给AI。AI需要基于刚刚完成的审查结果结合这些规则判断“这个PR是否应该被自动批准”。AI需要输出一个布尔值的approve和一个文本的reason理由。硬性关卡检查在AI说“可以批准”之后reviewd还会用三个硬性指标进行复核max_diff_lines: PR的代码差异总行数是否超过阈值超过则否决。max_severity: PR中所有发现项的最高严重性是否超过允许级别如出现了critical超过则否决。max_findings: 排除good正面评价后发现项总数是否超过阈值超过则否决。最终决策与执行只有当AI建议批准且所有硬性关卡都通过时reviewd才会调用GitHub/BitBucket的API代表你或配置的机器人账户批准Approve这个PR。同时AI提供的批准理由会被添加到总结评论中让其他开发者了解自动批准的原因。这个设计巧妙在哪它结合了AI的语义理解能力和工具的确定性规则。规则rules是模糊的、需要理解的比如“简单的bug修复”这部分交给AI判断。而代码行数、问题数量是明确的、可量化的这部分由工具严格把关。两者结合既避免了AI的“随意发挥”又赋予了工具处理复杂情况的能力。配置心得规则rules要具体不要写“批准好的代码”。要像给新人写审查指南一样列举出具体场景。例如“批准仅修改了README或文档字符串的PR”、“批准只更新了.gitignore或配置文件注释的PR”。阈值max_*要保守自动批准应该只用于那些风险极低、变更极小的PR。建议初始设置非常严格例如max_diff_lines: 30,max_severity: nitpick,max_findings: 1运行一段时间观察效果后再逐步放宽。理由reason是黄金一定要让AI提供批准理由。这不仅是审计日志更是对团队其他成员的沟通。当大家看到一个PR被自动批准时能立刻明白为什么这能建立对自动化流程的信任。4.3 状态管理与数据查看reviewd使用SQLite数据库来记录状态也提供了命令来查看这些信息。# 列出所有已配置的仓库及其状态 reviewd ls # 输出示例 # Repo: backend-service (github:your-org/backend) ~/projects/backend # Open PRs: 3 # * #123: feat: add user auth [unreviewed] # * #122: fix: typo in config [reviewed a1b2c3d] # * #121: chore: update deps [cooldown until 14:30] # 查看某个仓库的审查历史 reviewd status backend-service这些命令帮你快速了解哪些PR待审哪些已审以及工具的运行概况。5. 高级技巧与避坑指南在实际使用和与团队推广reviewd的过程中我积累了一些宝贵的经验和需要避开的“坑”。5.1 审查指令Instructions的编写艺术instructions是控制AI审查行为的核心。写得好AI就是你的得力助手写得不好它可能只会说一些正确的废话。反面教材过于空泛instructions: | 请检查代码质量。这种指令几乎没用AI不知道你的“质量”具体指什么。正面教材具体、可操作instructions: | 你是一个经验丰富的Python后端工程师正在审查一个FastAPI项目的PR。 审查重点 1. **安全性**检查是否有SQL注入风险字符串拼接、敏感信息硬编码、缺少输入验证。 2. **性能**检查循环内是否有重复的数据库查询N1问题、是否使用了不当的数据结构如列表代替集合进行成员检查。 3. **可维护性**函数是否过长50行、是否有清晰的命名、注释是否解释了“为什么”而不是“是什么”。 4. **API设计**端点路径是否符合RESTful约定、状态码使用是否恰当、响应模型定义是否完整。 5. **错误处理**是否有未捕获的异常、错误信息是否对用户友好、是否有适当的日志记录。 对于每个发现的问题 - 必须使用以下严重性标签之一[critical, suggestion, nitpick, good]。 - 必须指明具体的文件路径和行号。 - 必须提供**具体的、可执行的修改建议或代码示例**。 - 如果是“good”发现项请指出代码的优秀之处以资鼓励。好的指令就像一份清晰的工作说明书它设定了角色、明确了优先级、给出了具体的检查清单和输出格式要求。5.2 处理大型PR与性能优化默认情况下reviewd会将整个PR的diff和相关的文件内容发送给AI。对于大型PR修改文件多、行数多这可能导致上下文超长超出AI模型的上下文窗口导致分析不完整或被截断。API调用缓慢且昂贵处理大量tokens需要更长时间和更高费用。审查质量下降AI可能难以在庞杂的变更中抓住重点。应对策略设置min_diff_lines阈值在.reviewd.yaml中设置一个较大的值比如200自动跳过过于庞大的PR要求人工介入。可以在指令中说明“本工具适用于中小型PR大型重构请进行人工深度审查。”分而治之鼓励开发者将大型功能拆分成多个逻辑独立的小型PR。这不仅利于AI审查也符合优秀的代码协作实践。利用test_commands对于大型PR确保你的测试套件pytest和静态分析工具ruff,mypy足够强大。让这些工具先跑一遍把明显的错误和风格问题筛出来AI可以更专注于逻辑和设计问题。模型选择如果使用Claudeclaude-3-5-sonnet在处理长上下文和复杂代码方面通常比haiku更强但成本也更高。需要权衡。5.3 与团队工作流的整合引入一个自动化工具最大的挑战往往不是技术而是人。如何让团队接受并善用reviewd明确定位在团队内宣导reviewd是“第一轮过滤器”和“学习助手”而非“最终裁决者”。它的目的是发现显而易见的错误、统一代码风格、并提出可能被忽略的角度为人类审查者节省时间。最终合并的权力和责任仍在人类手中。从“只评论”开始初期不要启用auto_approve功能。让reviewd只发表评论让团队成员习惯阅读它的反馈并讨论这些反馈是否有价值。这有一个磨合与教育的过程。创建团队共享配置将优化后的.reviewd.yaml配置文件放在团队项目的根目录。这能确保所有成员以及CI系统使用同一套审查标准。可以将审查指令的制定过程作为团队代码规范讨论的一部分。处理误报与漏报建立一个简单的反馈机制。如果AI频繁给出无用的建议误报或者漏掉了明显问题漏报将这些案例记录下来。然后反过来优化你的instructions和test_commands。例如如果AI总在某个编码风格上纠缠而团队认为可以接受就在指令中明确说明“忽略XXX风格问题”。这是一个迭代调优的过程。善用“跳过”模式不是每个PR都需要AI审查。在PR标题中加入[no-review]、[wip]等标记通过skip_title_patterns配置可以让reviewd自动跳过。这给了开发者完全的控制权。5.4 安全与权限管理再强调令牌权限最小化无论是GitHub的Fine-grained Token还是BitBucket的Workspace Token都只授予Pull requests: Read Write权限。不要给予repo完全控制仓库或workflow等不必要的权限。环境变量存储切勿将令牌硬编码在配置文件中然后提交到Git。务必使用环境变量如${GITHUB_TOKEN}并在运行reviewd的机器上设置这些变量。审查机器隔离如果是在服务器上运行reviewd watch最好使用一个专用的、权限受限的系统账户或容器来运行它。避免使用具有高权限的个人账户。定期审计日志reviewd自身的日志输出结合GitHub/BitBucket的审计日志可以帮助你追踪自动化审查的活动。6. 故障排查与常见问题即使配置正确在实际运行中也可能遇到一些问题。以下是一些常见情况及其解决方法。6.1 AI CLI相关问题问题reviewd报错“Failed to invoke CLI: Command ‘claude’ not found”原因系统找不到claude或gemini、codex命令。解决确认AI CLI已正确安装。在终端直接输入claude --version看是否有输出。如果已安装但reviewd找不到可能是PATH问题。尝试使用绝对路径在配置中指定cli: /usr/local/bin/claude # 或你的实际安装路径如果你使用虚拟环境venv/conda确保reviewd和AI CLI在同一个环境或者AI CLI在系统PATH中。问题AI审查耗时过长或无响应原因PR过大上下文太长。AI服务API限速或网络问题。本地机器资源CPU/内存不足。解决检查PR的diff大小。考虑设置min_diff_lines过滤超大PR。查看reviewd watch -v的详细日志看卡在哪一步。如果是API调用超时可能是网络或服务商问题。降低max_concurrent_reviews默认4减少并行任务缓解资源压力。6.2 Git与仓库问题问题reviewd报告“Git repository not found at path: /some/path”原因配置文件中path指向的目录不存在或者不是一个Git仓库。解决运行reviewd ls检查配置的仓库路径是否正确。确保路径是绝对路径。使用~家目录符号有时可能解析错误建议使用完整路径如/home/username/projects/repo。手动进入该路径执行git status确认仓库状态正常。问题reviewd无法为PR创建工作树提示“git worktree add failed”原因目标目录已存在或者Git状态有冲突。解决reviewd会在临时目录如/tmp下创建工作树。如果之前运行意外中断可能残留了锁文件或目录。可以尝试清理reviewd的临时目录通常位于系统临时目录下的reviewd-*文件夹。重启reviewd进程。检查主仓库的.git目录是否完好。6.3 配置与网络问题问题reviewd能运行但无法获取PR列表或发布评论提示API错误原因令牌无效、权限不足或网络无法访问代码托管平台。解决验证令牌手动使用curl命令测试令牌。GitHub:curl -H Authorization: token ghp_yourtoken https://api.github.com/userBitBucket:curl -u your-email:your-api-token https://api.bitbucket.org/2.0/user检查权限确认令牌确实有Pull requests的读写权限。GitHub的Fine-grained Token作用范围Repository access是否包含了目标仓库检查网络如果你在公司网络可能需要配置代理。reviewd目前不直接支持代理配置你需要设置全局的HTTP代理环境变量如HTTP_PROXY,HTTPS_PROXY。问题AI的评论格式混乱或者没有出现在正确的代码行原因AI没有严格按照JSON Schema输出或者diff解析出错。解决使用--dry-run模式运行一次查看reviewd打印的、准备发送给AI的完整提示词和AI返回的原始响应。检查AI的回复是否是一个合法的JSON并且包含了file,line等必要字段。这可能与你的instructions有关。在指令中更明确地要求AI输出格式例如“你必须以严格的JSON格式输出包含findings数组每个finding必须有file, line, severity, description, suggestion字段。”确保你使用的AI模型支持可靠的JSON输出模式如Claude的--format json。在全局配置中指定model时选择一个已知的、擅长结构化输出的模型版本。6.4 数据库与状态问题问题reviewd重复审查同一个提交原因SQLite状态数据库损坏或锁定。解决reviewd的状态数据库默认位于~/.local/share/reviewd/reviewd.db遵循XDG规范。你可以停止reviewd进程。备份并删除这个数据库文件。重启reviewd。它会创建一个新的空数据库但这意味着它会重新审查所有打开的PR。对于已经处理过的PR你可以手动标记为已读或者暂时忽略。问题如何手动重置某个PR的审查状态场景PR经过重大修改你希望reviewd重新审查但又不想用--force命令每次都指定。解决可以直接操作SQLite数据库请谨慎操作sqlite3 ~/.local/share/reviewd/reviewd.db -- 查找记录 SELECT * FROM review_state WHERE repo_slug LIKE %your-repo%; -- 删除特定PR的记录 DELETE FROM review_state WHERE repo_slug owner/repo AND pr_id 123; .quit删除对应记录后下次轮询时reviewd会认为这个PR从未被审查过。经过数月的实践reviewd已经成为了我们团队开发流程中一个“沉默而高效”的成员。它不会取代深入的、富有洞察力的人工代码审查但它成功地接管了那些繁琐的、模式化的检查工作——比如拼写错误、简单的语法问题、遗漏的导入、不符合团队风格的格式等。这让人类审查者能够更专注于架构设计、算法效率和业务逻辑这些更需要创造力和经验的部分。它的配置过程虽然有一点点学习曲线但一旦跑通其带来的效率提升和代码质量保障是显而易见的。如果你也在寻找一种不增加基础设施复杂度、又能显著提升代码审查体验的方案reviewd绝对值得你花上一个下午的时间来尝试和配置。
