Cline SDK 代码审查技能（code-review skill）：Agent Squad 插件中结构化评审流程的深度解析

在 Cline SDK 的 agents-squad 示例插件中，code-review 是一个内置的可加载技能（skill）：它把一次代码评审拆解为范围界定、正确性、安全性、性能、可维护性五个检查通道，并规定按 Critical/Major/Minor/Positive 四级严重度输出带文件行号、成因分析和具体修复建议的评审报告。本文以 code-review 技能文件 为主体，逐节解读该评审流程的完整规则，并结合 agents-squad 插件源码 说明技能是如何被发现、加载和注入到子代理会话中的，帮助你在多智能体工作流中稳定产出可执行的审查结果。

1. code-review 技能是什么，在插件体系中处于什么位置

从 技能文件 的 YAML frontmatter 看，它只有两个元数据字段：

---
name: code-review
description: Structured code review — security, correctness, performance, and maintainability analysis with severity-ranked findings.
---

这个技能属于 agents-squad 插件 的捆绑技能（bundled skills）之一。该插件的定位是"从任意 Cline SDK 代理中拉起后台子代理"，每个子代理拥有独立的会话、provider、模型与系统提示词。插件捆绑了 7 个技能：code-review、test-generation、refactoring、debugging、api-design、migration、documentation，均位于 skills 目录 下，以带 frontmatter 的 Markdown 文件形式存放。

技能与代理的关系值得说明：在典型的编排链路中，inquisitor（对抗式审查代理）是最直接消费 code-review 技能的预设。inquisitor.md 的系统提示词要求它以"对上线后所有问题负责"的姿态压力测试变更，并明确"所有发现必须按 critical（必须修复）/ major（应当修复）/ minor（值得记录）分级，除非真有非显而易见的好设计，否则不要赞美"——这与 code-review 技能报告的四级严重度模型高度一致。而 oracle 负责产出可执行的实施计划（见 oracle.md）、anvil 负责按外科手术式精度执行实现（见 anvil.md）、phantom 负责快速侦察代码库（见 phantom.md）。README 中给出的典型编排正是"侦察 → 规划 → 实现 → 审查"的流水线，code-review 技能服务于最后的审查环节。

2. 评审流程第一步：范围界定（Scope the Review）

技能文件的第一节要求在动手评审之前先完成三件事：

• 识别所有变更文件及其相互关系。不是逐文件孤立审查，而是理解文件间的调用与依赖关系；
• 理解变更意图：这次改动要解决什么问题？意图不清时，"看起来合理"的改动也可能是错的；
• 记录"本应变更却没有变更"的文件。这是最容易漏掉的一类问题：改了接口签名却没更新某个调用方、改了 schema 却没同步迁移脚本、加了功能却没更新测试夹具等。

从源码结构看，子代理会话启动时会把任务文本作为第一条用户消息注入（见 index.ts 中 start_subagent 的实现：void runSubagentTurn(subagent, input.task, ...)），因此"任务描述 + 技能指令"共同构成子代理的评审输入。评审范围的质量高度依赖父代理在 task 中给出的信息量——这也是插件 README 中建议用 save_handoff 先把侦察结论（如 auth/recon.md）落盘、再让审查代理基于该上下文工作的原因。

3. 正确性通道（Correctness Pass）

技能文件要求对"每一条被修改的路径"做数据流追踪，并逐项检查以下问题：

• 边界条件：null/undefined、空集合、边界值；
• 错误处理：错误是否被捕获、传播并正确地向用户/上层暴露；
• 典型缺陷模式：差一错误（off-by-one）、竞态条件、状态突变（mutation）类 bug；
• 类型与运行时假设的匹配：特别点名 any、强制类型转换（casts）和断言（assertions）——这三者是类型系统失效的高发区。

这一节的核心思想是"沿路径追踪"而非"逐行阅读"：先画出数据从入口到出口的流动路径，再在每个路径上寻找违反上述规则的具体位置。

4. 安全通道（Security Pass）

安全通道的检查清单覆盖了注入、越权、泄露与协议配置四类风险：

• 未经验证的用户输入到达敏感操作：SQL、shell 命令、文件路径、URL 构造；
• 认证与授权：每一个新端点或处理器都要检查；
• 密钥泄露：检查密钥是否出现在代码、日志或错误消息中；
• 安全头：如适用，验证 CORS、CSP 等配置；
• 时序攻击：检查比较操作（如 token、HMAC 校验）是否使用了常量时间比较。

其中"错误消息中泄露密钥"一点与插件生态中的其他示例互为印证：env-blocker.ts 通过 beforeTool 钩子硬性阻断对 .env 的读取，而 code-review 技能则要求在人工/代理评审层面检查密钥是否已进入代码与日志——两者是运行期防护与评审期检查的互补关系。

5. 性能通道（Performance Pass）

性能通道关注的是"随输入规模恶化"的操作，技能文件列出的检查点包括：

• N+1 查询、无界循环、不必要的内存分配；
• 新增数据库查询是否缺少索引；
• 热路径上的阻塞操作（阻塞 I/O、同步等待）；
• 列表类操作是否有分页与上限（pagination 和 limits）；
• 任何随输入规模扩展性差（scale poorly）的操作。

注意这一节的措辞是"identify / note / verify"——它要求评审产出的是可定位的性能疑点，而不是泛泛的"这里可能慢"。这与技能报告的输出格式（见第 8 节）配合：每个性能发现同样需要文件行号、影响说明和具体修复方案。

6. 可维护性通道（Maintainability Pass）

可维护性通道从五个角度评估代码的长期成本：

• 命名：名称是否传达了意图？
• 抽象边界：这次改动是引入了新的耦合，还是降低了耦合？
• 重复逻辑：是否有应当共享却复制粘贴的逻辑？
• 测试覆盖：测试是否覆盖了新行为和边界情况？
• 文档：公共 API 是否缺少文档。

值得强调的是，该技能把"测试是否覆盖新行为和边界情况"放在可维护性通道而非单列一节——这呼应了 inquisitor 代理 中"Missing tests"条目的要求：指出未测试的场景时要"建议具体的测试用例，而不是只说'多写测试'"。

7. 报告格式：四级严重度 + 四要素发现结构

技能文件的最后一节规定了评审产出的组织方式，这是整个流程中约束力最强的部分。

按严重度分组：

级别	判定标准
Critical	合并前必须修复：bug、安全问题、数据丢失风险
Major	应当修复：设计问题、错误处理缺失、性能问题
Minor	值得记录：风格、命名、小的改进点
Positive	非显而易见的好决策（保持简短）

每条发现必须包含四要素：

1. 文件和行号引用；
2. 问题是什么；
3. 为什么重要（影响面、风险）；
4. 建议的修复方案——要求"具体，不能含糊"（concrete, not vague）。

这套格式实际上约束了 LLM 输出的可用性：带行号的发现可以直接被父代理转发给 anvil 之类的实现代理去修复，"为什么重要"一栏为修复优先级排序提供了依据，而"具体修复"一栏把评审结论从描述性文字变成了可执行指令。在 agents-squad 的编排模型下，这正是评审结果能被流水线下游消费的关键。

8. 技能的加载机制：从磁盘到 get_skill

理解了流程本身后，再看插件如何把这个文件变成运行时能力。从 index.ts 的源码可以确认以下机制：

三级发现与覆盖。readSkillDefinitions 按固定顺序扫描三个目录，后加载的同名技能会覆盖先加载的：

来源	目录
bundled	插件包内 skills/（即本文档所在目录）
global	~/.cline/data/settings/skills/
project	<cwd>/.cline/skills/

因此项目级同名技能可以覆盖捆绑的 code-review，实现"按团队定制评审清单"而不必改动插件本身。

frontmatter 解析。parseFrontmatter 先用 stripUtf8Bom 去除 BOM 再匹配 ---...--- 块并用 yaml 库解析，name 缺失时回退为去掉 .md 后缀的文件名；YAML 解析失败时整个文件被视为无元数据的纯 Markdown 跳过（源码中 if (!body) continue）。这解释了为什么技能文件必须保持"frontmatter + 正文"的结构：正文（body）就是 get_skill 返回给代理的 instructions 内容，frontmatter 中的 description 则供 list_skills 展示。

按需加载（progressive disclosure）。list_skills 只返回所有技能的 name、description、source 三元组，不返回正文；代理确认需要某个技能后再调用 get_skill，此时才把完整正文作为 instructions 返回。这与 官方 Skills 文档 描述的渐进式加载模型一致：元数据始终可见，指令正文仅在技能被触发时进入上下文，从而避免无关技能占用 token。对 code-review 这种约 60 行的技能而言，"先 list 后 get"的两次调用开销很小，但机制保证了 7 个捆绑技能并存时上下文成本可控。

错误处理。get_skill 在技能名不存在时会抛出 Unknown skill 错误并附带上可用技能名列表，方便代理自纠正。

9. 实战接入：配置、运行与典型编排

安装插件。agents-squad 是一个带 package.json 的目录型插件，README 中给出的安装方式是：

cline plugin install ./examples/plugins/agents-squad

CLI 会从 .cline/plugins（工作区）、~/.cline/plugins 等位置自动发现插件；目录型插件由加载器读取 package.json，并从其中的 cline.plugins 字段发现入口 ./index.ts（capabilities 声明为 hooks 与 tools）。

SDK 方式启动。README 的 Quick start 展示了最小可运行配置：

import { ClineCore } from "@cline/core";

const cline = await ClineCore.create({ backendMode: "auto" });

await cline.start({
  config: {
    providerId: "cline",
    modelId: "anthropic/claude-sonnet-4.6",
    cwd: process.cwd(),
    enableTools: true,
    systemPrompt: "You are a coding assistant with access to subagents.",
    pluginPaths: ["./examples/plugins/agents-squad"],
  },
  prompt: "Use subagents to investigate and refactor this repo.",
  interactive: true,
});

可调参数。子代理行为受以下环境变量控制（全部可选，见 README 配置表，默认值在 index.ts 中通过 envOr 解析）：

变量	默认值
CLINE_SUBAGENT_PROVIDER_ID	cline
CLINE_SUBAGENT_MODEL_ID	anthropic/claude-sonnet-4.6
CLINE_SUBAGENT_DEFAULT_PRESET	phantom
CLINE_SUBAGENTS_BACKEND_MODE	auto（auto | hub | local）
CLINE_SUBAGENT_CWD	process.cwd()
CLINE_DATA_DIR	~/.cline/data

触发 code-review 的编排。结合 README 的典型编排 与工具清单（start_subagent、message_subagent、get_subagent、list_agent_presets、list_skills / get_skill、save_handoff / read_handoff），一次完整的评审流水线可以这样组织：

1. start_subagent(preset: "inquisitor", task: "Review the auth module changes") 启动审查代理；
2. 审查代理调用 list_skills 看到 code-review，调用 get_skill({ name: "code-review" }) 拉取完整评审流程指令；
3. 代理按技能文件的五通道流程执行，产出严重度分级的评审报告；
4. 结果通过 notifyParent（默认开启）以 steer 消息推回父会话，或经 read_handoff 共享给后续的实现代理。

需要说明的前提：捆绑预设各自声明了模型（phantom 用 google/gemini-3-flash-preview、inquisitor 用 openai/gpt-5.5 等），实际运行这些编排需要相应 provider 的访问凭证；技能文件本身不依赖任何特定模型。

10. 小结与可借鉴的设计要点

回看 code-review.md 全文，它的工程价值在于三个设计决策，均可从仓库中其他文件得到印证：

1. 流程固定、结论开放：五个检查通道和报告格式是硬约束，但具体发现完全取决于被审查的代码——这种"检查表式"的指令最适合 LLM 代理，因为检查表可以逐条执行，而开放式提示容易漏项；
2. 输出面向下游消费：文件行号 + 具体修复要求，使评审报告能被实现类子代理直接执行，这与插件整体"多代理流水线"的定位一致；
3. 按需加载控制上下文成本：技能正文只在 get_skill 时被注入，元数据常驻，这与 Skills 文档 描述的三级加载模型（元数据 / 指令 / 资源）在插件层面落地。

如果你想在自己的项目中定制评审规则，最稳妥的方式是把修改后的技能文件放入项目级目录 <cwd>/.cline/skills/code-review.md（或全局目录 ~/.cline/data/settings/skills/）以覆盖捆绑版本，利用源码中"project 覆盖 global、global 覆盖 bundled"的优先级规则，而不改动插件本身。

相关源码与文档路径汇总：code-review 技能、插件入口、插件 README、inquisitor 预设、插件示例总览、Skills 官方文档。