yy-review

name	yy-review
description	审核 git 变动文件或用户指定范围内的代码质量。 用于：用户要求审核代码、代码 review、检查代码质量时触发。 不用于：用户要求直接修改代码、询问代码问题、生成提交信息或运行构建测试。

yy-review

描述

通用代码审核技能。对 git 变动文件或用户指定范围内的代码进行审核，优先审查变更行及必要上下文，按严重程度输出问题描述、影响和修复建议。

按目标文件所属子项目的角色与主要语言/框架自动路由：通用层规则 + 匹配到的语言/框架专项层规则叠加适用，冲突时专项层优先；未匹配到专项规则时，仅使用通用层规则。

核心原则：默认只审核，不修改代码；只有用户明确要求修复时，才进入代码修改流程。

使用场景

• 用户要求审核代码、代码 review、代码检查
• 用户提到“审核改动”、“review 代码”、“检查代码质量”
• 提交前检查、合并前审核、PR 审核
• 用户指定文件或目录范围，要求检查其中的代码质量

不应触发：

• 用户要求直接修改代码而非检查代码质量
• 用户只是询问某个代码问题
• 用户要求生成 git 提交信息
• 用户要求运行构建、测试、部署或自动修复流程

指令

步骤 1. 识别项目角色与语言

为后续分组路由建立"子项目路径 → { 角色, 主要语言/框架 }"的映射。本步骤只识别、不委托。

识别产物

输出一个映射表，每一项形如：

• 路径：根目录或 monorepo 子项目目录
• 角色：前端 / 后端 / 客户端 / 脚本 / 混合 之一；当一个子项目同时承担多种角色（如 SSR、前后端一体）时记为 混合
• 主要语言/框架：如 Vue3、Vue2、React、Node.js、Rust、Python、Go、Java/Kotlin 等；可同时记录多个

monorepo 中的多个子项目分别建立映射；单一项目只建立一条根目录映射。

信息来源优先级

按以下顺序判定，前一来源已能给出明确结论时不再向下查找：

1. 根目录与各子项目下的 README.md / AGENTS.md：从中提取项目角色与所用语言/框架。子项目级文档的描述优先于根目录文档
2. AI 凭项目结构和明显特征自由判断：文档缺失或描述不足以判定时，不再走具体的依赖关键词清单或文件后缀启发式规则；由 AI 根据项目实际内容自行判断
3. 向用户询问：上述两步仍判不出时，必须向用户询问该项目/子项目的角色与主要语言，禁止静默猜测

文档与实际冲突的处理

当文档描述与实际代码明显矛盾（例如文档说"Vue 项目"但已迁到 React，或新增了 server/ 目录但 README 未更新）时，以实际代码为准；同时在步骤 7 的最终审核结果中标注"项目类型与文档描述不一致"，便于用户感知文档过时风险。

步骤 2. 获取审核目标

按以下规则获取需要审核的文件。

决策分支：

• 用户指定文件或目录：优先使用用户指定范围，递归收集支持的代码文件。
• 用户未指定范围：使用 git 命令获取未暂存和已暂存的变更文件，并合并去重。
• 无匹配代码文件：回复“当前没有需要审核的代码变更文件。”并终止。

默认使用以下命令获取 git 变更：

git diff --name-only HEAD
git diff --cached --name-only

支持的文件范围：

作为通用代码审核技能，默认收录所有可读的纯文本源文件，包括但不限于：

• 各类编程语言的源代码文件（如 .js、.ts、.vue、.py、.go、.rs、.java、.kt、.cs、.php、.rb、.swift、.c、.cpp、.dart、.scala、.lua、.sql 等）
• 样式与模板文件（如 .css、.scss、.less、.html、.tsx、.jsx）
• 配置与脚本文件（如 .json、.yaml、.toml、.sh、.ps1、Dockerfile、Makefile、.tf）

以上仅为示例。未列出但属于源代码、配置或脚本类的纯文本文件同样在收录范围内；具体语言/框架的审核规则由步骤 1、3 的路由结果决定，未匹配到专项规则时仅使用通用层规则。

默认排除以下文件和目录：

• 依赖与构建产物：node_modules/、dist/、build/、coverage/、.next/、.nuxt/、.output/、target/、Cargo.lock
• 锁文件与生成文件：package-lock.json、pnpm-lock.yaml、yarn.lock、*.min.js、*.generated.*
• 二进制文件、图片、字体、压缩包、快照文件
• 当前仓库 .gitignore 匹配的文件和目录（含嵌套 .gitignore）

覆盖规则：用户显式指定的文件路径优先级高于上述默认排除——即使该文件被 .gitignore 匹配或属于上述排除类型，只要用户显式指定，仍纳入审核。

步骤 3. 按语言分组与专项技能委托

将步骤 2 收集到的目标文件按所属子项目的角色与语言分组，并对每个分组独立决定是否委托给专项审核技能。委托发生在文件分组层面，而非整个审核任务层面，避免全栈项目中识别到前端角色后忽略其他角色或语言的文件。

文件分组规则

对每个目标文件按以下顺序判定所属分组：

1. 按子项目映射归组：根据文件路径，查步骤 1 中最近的子项目映射，按其 角色 + 主要语言/框架 归到对应分组（如 Vue3 前端组、Node.js 后端组、Rust 后端组）
2. 混合角色子项目内部细分：当所在子项目角色为 混合（例如同一 package.json 既是前端又是 Node 服务端、或 Vue SSR 项目）时，按文件后缀进一步细分：
   • .vue / .jsx / .tsx / .css / .scss / .less / 主要在前端目录下的 .js / .ts → 该子项目的前端语言分组
   • 主要在服务端目录下的 .js / .ts / 含 Node 内置模块导入或服务端框架导入 → 该子项目的 Node.js 分组
   • 仍无法判定时：归入"通用组"，仅用本技能通用规则审核，不委托给前端专项技能（避免越权）
3. 配置/脚本文件（.json、.yaml、.toml、.sh 等）：归入其所在子项目映射对应的分组；无法归类时进入通用组
4. 不在任何已识别子项目下的文件：归入"通用组"

分组结果可能为：单一分组（典型纯语言项目），或多个分组（典型全栈/monorepo 项目）。

分组级专项技能委托

对每个文件分组按以下决策分支处理：

• 分组类型为前端，且当前环境已安装 yy-frontend-review：将该分组的文件委托给 yy-frontend-review
• 分组类型为其他语言，且当前环境已安装对应语言的专项审核技能：将该分组的文件委托给该专项技能
• 未安装对应专项技能 / 通用组 / 未匹配语言：该分组文件由本技能在步骤 5 中按"通用层 + resources/<language>.md"流程审核

委托执行时，仅传入对应分组的文件清单，被委托技能不得越界审核其他分组的文件。各分组的审核结果在步骤 7 输出时合并。

快速通道（Fast Track）

无论文件归属哪个分组、是否委托给专项技能，都先对全部目标文件统一执行一次快速通道检查：

• 优先使用 grep、正则表达式等可绕过 LLM 全文解析的方式加速定位缺陷；无更高效方式时才使用 LLM 全文解析
• 发现的缺陷直接纳入审核结果，按原有严重程度分级，并在末尾标注 [FastTrack]
• 各分组（含被委托给专项技能的分组）完成审核后，将快速通道结果与各分组结果合并；按 文件路径:行号 + 问题类型 去重排序后输出

步骤 4. 确定审核范围

优先审查 diff 变更行，并按需读取上下文。

决策分支：

• 变更行可独立判断问题：只基于变更行和相邻上下文（上下各 3 行）输出结论
• 问题依赖函数/组件上下文：读取完整函数或组件后再判断
• 问题依赖跨文件调用链：追踪相关调用链后再判断
• 历史遗留问题未被本次改动引入：不作为本次审核阻断项，在"补充观察"中简要说明
• 上下文不足无法确认：标记为"需人工确认"，说明缺失信息，不编造结论

上下文读取规则：

• 单行改动：读取前后各 3 行
• 函数级改动：读取完整函数定义
• 组件级改动：读取完整组件文件
• 跨文件影响：读取相关依赖文件

步骤 5. 按维度审核代码

对未在步骤 3 委托给专项技能的分组，按以下规则在本技能内审核。已委托给专项技能的分组遵循专项技能的审核维度，不在此处重复。

规则分层与路由

审核规则采用"通用 + 专项"分层结构，按目标文件的语言或项目类型动态路由：

• 通用层：resources/general.md，对所有代码文件始终适用
• 特定层：按目标文件的语言/框架，匹配 resources/<language>.md（如 resources/vue3.md、resources/rust.md）；规则文件名采用语言或框架的小写名
• fallback：未在 resources/ 中找到对应专项规则文件时，仅使用通用层规则
• 优先级：特定层规则与通用层规则冲突时，以特定层为准

规则冲突处理：

• 通用层与特定层冲突：特定层优先
• 多个特定层之间冲突：按目标文件实际涉及的最具体语言/框架优先（如 .vue 文件优先用 vue3.md）
• 专项规则中引用了其他技能，且其他技能内容与本技能规则冲突：以本技能为准

子代理调度策略

当委托子代理执行专项技能审查时，优先按文件分组调度，而非按维度分组调度：

1. 按文件分组：将目标文件按数量均分为 N 组（N ≤ 3），每组分配给一个子代理
2. 全维度检查：每个子代理对自己负责的文件执行全部维度的剩余检查
3. 跳过已覆盖项：子代理跳过已在快速通道中覆盖的检查项
4. 去重规则：按 文件路径:行号 + 问题类型 两个维度去重。快速通道发现的缺陷与子代理结果重复时，以快速通道结果为准

此调度策略优先级高于被委托技能自身的调度方案。当两者冲突时，以本规则为准。

报告口径：

• 优先关注本次改动引入、放大或未收敛的问题
• 优先使用可跨项目复用的工程原则，不把单个项目的习惯直接当成通用阻断项
• 只有在项目约定已经形成明确契约、并且本次改动触发了该契约时，才按项目约定报告问题
• 所有问题都要说明可验证影响，不因个人偏好、代码风格偏好或 UI 审美偏好直接报问题

审核执行规则：

• 严重问题：发现即审核不通过，必须修复。
• 中等问题：发现则审核不通过，建议修复后再合并。
• 轻微问题：发现则列出，不影响审核通过结论。
• catch 块中用于记录异常的 console.warn 不视为问题。

步骤 6. 处理边界条件

场景	处理方式
删除文件	只评估删除是否影响引用、路由、导出、配置或测试，不审查已删除内容
重命名文件	按新路径和实际 diff 审查，必要时检查引用路径是否同步更新
大型文件	优先审查 diff hunk；超过 1000 行时按相关函数或模块分段读取
仅文档改动	只检查明显错误、无效链接、命令错误和与代码不一致的说明
仅格式化改动	不报告业务问题，除非格式化引入语法或运行时风险
配置文件改动	重点检查语法、环境差异、安全暴露和构建行为变化
新增模块或入口	检查路由、导航、权限、导出、类型、配置、文档和依赖接入是否同步完成
无法确认的问题	标记为“需人工确认”，说明原因和建议确认方式

步骤 7. 输出审核结果

决策分支：

• 无问题：输出审核通过格式。
• 只有轻微问题：输出审核通过格式，并列出轻微问题。
• 存在严重或中等问题：输出审核不通过格式，按严重程度和文件分组列出问题。

输出要求：

• 问题位置必须使用 文件路径:行号 格式，使用相对于项目根目录的路径
• 每个问题必须包含问题类型、描述、影响和修复建议
• 问题按严重、中等、轻微顺序排列，同级别按文件路径排序
• 代码片段使用语言标签（如 typescript、javascript、rust）
• 不要直接修改代码
• 多分组合并输出：当步骤 3 产生了多个文件分组时，最终结果合并所有分组的问题，按统一严重程度排序输出，问题统计为各分组之和；如委托给专项技能的分组已自带"通过/不通过"结论，将其汇总为本技能整体结论（任一分组不通过即整体不通过）
• 文档与实际不一致提示：若步骤 1 在识别项目角色与语言时发现文档（README.md / AGENTS.md）与实际代码冲突，需在审核结果开头追加一条提示，说明哪个子项目的角色或语言与文档描述不一致，便于用户感知文档过时风险

通过格式：

## 审核结果：通过

### 问题统计

- 审核文件数：N
- 严重：0 个
- 中等：0 个
- 轻微：Z 个

### 轻微问题

[如无轻微问题，写“未发现轻微问题。”]

不通过格式：

## 审核结果：不通过

### 问题统计

- 审核文件数：N
- 严重：X 个
- 中等：Y 个
- 轻微：Z 个

### 问题详情

#### 严重问题

1. **问题类型**：[类型]
   - **位置**：文件路径:行号
   - **描述**：[问题说明]
   - **影响**：[可能造成的后果]
   - **代码片段**：
     ```语言
     [相关代码]
     ```
   - **修复建议**：[具体可执行建议]

#### 中等问题

[同上]

#### 轻微问题

[同上，可简化代码片段]

### 修复优先级

1. 先修复严重问题。
2. 再修复中等问题。
3. 轻微问题可按团队规范决定是否处理。

安全边界

允许执行的操作：

• 读取代码文件内容
• 执行 git diff 命令获取变更信息
• 输出审核结果报告

禁止主动执行的操作：

• 修改代码、格式化代码或自动修复代码
• 编译命令、构建命令、部署命令
• 自动执行测试命令
• 会改变 git 状态的命令（如 commit、push、merge、rebase）
• 删除文件、重置分支、清理工作区等破坏性操作
• 网络请求命令（除特定 API 外）