gemini-cli code-reviewer 技能深度解析：从本地改动到远程 PR 的 AI 代码评审流程

本文以 gemini-cli 仓库自带的 code-reviewer 技能 为主体，完整拆解这个"程序化代码评审"技能的工作流：如何判定评审对象、如何执行预检、按哪七个维度分析代码、以及输出何种结构的评审反馈。读完本文，你将理解该技能的每一步操作依据、底层加载与激活机制（frontmatter 解析、发现层级），并能在自己的项目中复用或改造这套评审流程。

1. 什么是 code-reviewer 技能

code-reviewer 是 gemini-cli 仓库放在工作区技能目录 .gemini/skills/code-reviewer/ 下的一个 Agent Skill。它不是一段可执行代码，而是一份"程序化说明书"：当用户在会话中说"Review PR #123"或"review my changes"时，模型识别到与技能描述匹配的任务，激活该技能，随后严格按照 SKILL.md 中定义的流程执行代码评审。

技能文件的头部是 YAML frontmatter，声明了名称和用途描述：

---
name: code-reviewer
description:
  Use this skill to review code. It supports both local changes (staged or working tree)
  and remote Pull Requests (by ID or URL). It focuses on correctness, maintainability,
  and adherence to project standards.
---

这段 description 不是注释，而是技能被"发现"的核心依据。如 Agent Skills 文档所述，gemini-cli 在会话开始时扫描各发现层级，仅把每个已启用技能的名称和描述注入系统提示词；当模型判断任务与描述匹配时，才调用 activate_skill 工具、弹出用户确认、再把 SKILL.md 的正文注入对话历史。这种"渐进式披露"使得仓库可以维护大量专项技能而不挤占上下文窗口——code-reviewer 正是典型代表：它把整套 PR 评审规程打包成一个目录，任何团队成员克隆仓库后即可直接使用。

2. 加载与激活机制：源码级依据

技能能被 gemini-cli 识别，依赖 skillLoader.ts 中的发现逻辑：

• 文件发现：loadSkillsFromDir 用 glob 模式 ['SKILL.md', '*/SKILL.md'] 扫描目标目录（忽略 node_modules 与 .git），因此技能必须位于某个子目录下的 SKILL.md 中，这与 .gemini/skills/code-reviewer/SKILL.md 的布局一致；
• frontmatter 解析：FRONTMATTER_REGEX（第 34-35 行）提取文件开头两个 --- 之间的内容，parseFrontmatter 先用 YAML 解析，失败时回退到简单键值解析器，以兼容"描述中含冒号"的写法；name 和 description 缺一即视为无效技能；
• 名称净化：loadSkillFromFile（第 164-191 行）会把名称中的 : \ / < > * ? " | 替换为 -，保证技能名可安全用作目录名。

发现层级（优先级从低到高）为：内置技能 → 扩展技能 → 用户技能（~/.gemini/skills/ 或 ~/.agents/skills/ 别名）→ 工作区技能（.gemini/skills/ 或 .agents/skills/ 别名）。code-reviewer 属于优先级最高的工作区层级，随版本库与团队共享；同名技能会被高优先级层级的版本覆盖。

激活后模型按文档 skills.md 描述的流程执行：用户看到包含技能名称、用途和目录路径的确认提示，批准后 SKILL.md 正文与技能目录结构被加入对话，且技能目录被加入代理的允许文件路径。管理上可用 /skills list 查看已发现技能，用 /skills enable、/skills disable 控制启停，gemini skills list --all 可在终端查看含内置技能在内的完整列表。

3. 工作流第一步：判定评审对象

SKILL.md 将评审入口分为两类，判定规则明确：

用户输入	评审对象
提供 PR 编号或 URL（如 "Review PR #123"）	远程 Pull Request
未提及具体 PR，或要求 "review my changes"	本地文件系统状态（已暂存 + 未暂存改动）

这个二分法决定了后续准备阶段的分支：远程 PR 需要 checkout 与全量预检；本地改动则以 git 状态为主，预检是可选的。

4. 工作流第二步：准备阶段

4.1 远程 PR 的三项准备

Checkout——用 GitHub CLI 检出 PR 分支：

gh pr checkout <PR_NUMBER>

Preflight——先跑项目标准验证套件，尽早暴露自动化会发现的失败，避免代理在"必然挂掉"的改动上浪费评审精力：

npm run preflight

在 gemini-cli 仓库中，这条命令并非抽象占位。package.json 第 71 行给出了真实定义：

"preflight": "npm run clean && npm ci && npm run format && npm run build && npm run lint:ci && npm run typecheck && npm run test:ci"

即一个完整串联：clean（清理产物，scripts/clean.js）→ npm ci（按 lockfile 精确装依赖）→ format（Prettier 格式化）→ build（esbuild 构建，scripts/build.js）→ lint:ci（ESLint 全量检查，--max-warnings 0 零警告策略）→ typecheck（TypeScript 全工作区 + 测试目录的类型检查）→ test:ci（各 workspace 的单元测试）。这解释了技能为何强调"catch automated failures early"：机械性问题（格式、类型、单测）已由自动化闭环覆盖，代理的评审应聚焦自动化覆盖不到的判断性维度。

Context——阅读 PR 描述与已有评论，理解改动目标与历史，避免重复指出已讨论过的问题。

4.2 本地改动的两项准备

识别改动——区分未暂存与已暂存两条 diff 线索：

git status
git diff              # 工作区（未暂存）
git diff --staged     # 暂存区

可选 Preflight——与远程 PR 不同，本地改动只有在"改动较大"时才建议预检，且技能明确要求先询问用户是否执行 npm run preflight，由开发者决定成本与收益的权衡。这一设计体现了该技能对执行代价的敏感：preflight 在本仓库中是构建 + 全量 lint + 全量测试的长链路，不适合对每一次小改动盲目执行。

5. 工作流第三步：七维度深度分析

分析阶段是技能的核心。SKILL.md 要求按以下七个"支柱"逐一检视改动，每个维度都是明确的问题式判据：

1. Correctness（正确性）：代码是否实现了其声称的目标，是否存在缺陷或逻辑错误？
2. Maintainability（可维护性）：代码是否干净、结构良好、易于未来理解和修改？需考察清晰度、模块化以及对既有设计模式的遵循。
3. Readability（可读性）：是否按需注释、并按项目编码风格指南保持格式一致？
4. Efficiency（效率）：改动是否引入明显的性能瓶颈或资源低效？
5. Security（安全性）：是否存在潜在安全漏洞或不安全的编码实践？
6. Edge Cases and Error Handling（边界与错误处理）：是否恰当处理了边界条件与潜在错误？
7. Testability（可测试性）：新增或修改的代码是否有足够的测试覆盖——即使 preflight 已通过？并建议能提升覆盖率或鲁棒性的额外测试用例。

值得注意的是第 7 条与第 4.1 节 preflight 的呼应：预检通过只说明"现有测试没坏"，而 Testability 维度追问的是"测试够不够"。这七维组合覆盖了自动化流水线（对应 lint/typecheck/test 能发现的格式、类型、回归问题）之外的人工判断空间（意图正确性、设计权衡、安全、边界），恰好是 LLM 代理评审的合适分工。

6. 工作流第四步：结构化反馈输出

评审结论必须遵循固定骨架，保证输出可预期、可被他人快速扫读：

结构

• Summary：评审的高层概览；
• Findings，按严重性分三级：
  • Critical：Bug、安全问题或破坏性变更（breaking changes）；
  • Improvements：代码质量或性能方面的改进建议；
  • Nitpicks：格式或轻微风格问题（可选）；
• Conclusion：明确结论——Approved（通过）或 Request Changes（要求修改）。

语气规范

• 建设性、专业、友好；
• 必须解释为什么要求某处修改，而不是只给结论；
• 对通过（approval）的评审，要具体肯定贡献的价值，而非空泛称赞。

这套"三级 Findings + 二值结论"的设计与 PR 平台的评审模型（approve / request changes）对齐，使得技能输出可以直接映射到 GitHub 上的 PR 评审操作，无需人工转译。

7. 工作流第五步：清理（仅远程 PR）

远程 PR 评审会改变本地检出分支，因此技能要求在评审结束后主动询问用户是否切回默认分支（如 main 或 master），避免代理静默地把工作区留在 PR 分支上。此步骤不适用于本地改动评审——那是唯一带条件分支的步骤。

8. 实战触发与周边评审生态

在 gemini-cli 仓库会话中，以下说法都会命中该技能的描述并触发激活：

• "Review PR #123"——进入远程 PR 分支，执行 checkout + preflight 全流程；
• "review my changes"——进入本地改动分支，先 git status / git diff，改动较大时询问是否跑 npm run preflight。

该技能并非孤例。同一工作区技能目录下还有面向不同评审场景的配套技能：async-pr-review（附带评审脚本 async-review.sh）、review-duplication（评审重复问题）、string-reviewer（面向文案与字符串）；commands/ 目录下另有 pr-review.toml 等评审相关命令定义。code-reviewer 承担的是最通用的"本地 + 远程 PR 通用评审"角色，其余技能则在其基础上做特化，体现了技能库"一场景一技能"的组织方式。

9. 设计要点小结

从 code-reviewer 这一具体技能中，可以提炼出 gemini-cli 技能体系的几条通用设计原则，对自研技能有直接参考价值：

1. 描述即触发器：frontmatter 的 description 决定了技能何时被模型选中，应写明适用输入形态（如 "by ID or URL"）与关注点，而不是泛泛的能力宣称；
2. 判定先行：先用第一步把请求路由到互斥的分支（远程 PR / 本地），后续步骤才有确定语义；
3. 验证优先：把 preflight 放在分析之前，让自动化消化机械失败，代理只做判断性评审，同时明确预检的"可询问、可跳过"边界；
4. 输出契约：固定 Summary/Findings/Conclusion 骨架与语气规范，把开放式 LLM 输出约束成可被流程消费的评审报告；
5. 状态收尾：对改变工作区状态的流程（checkout）配套清理步骤，且明确其适用条件。

完整的技能原文见 .gemini/skills/code-reviewer/SKILL.md，技能框架的更多背景可参考 creating-skills.md 与 skills-best-practices.md。