Review Frontend

前端专家评审 (Expert Frontend Review)

概述

本技能通过模拟多个专业审查角色，对前端 Pull Request 进行全方位审计，不仅检查语法错误，更关注架构合规性、静默失败预防、测试质量及项目特定规范。

铁律 (Iron Rules)

必须依次执行所有 8 个角色，禁止跳过任何一个。每个角色的检查必须显式验证，没有完成全部检查不得提交评审总结。

违反字面规则就是违反精神规则。 这条原则禁止"我虽然跳过了某个角色，但是达到了精神要求"这类合理化。

核心原则：评审过程中严禁修改本地文件，所有修改建议必须通过 GitHub API 或脚本提交到 PR；所有评论必须使用中文。

何时使用

digraph when_to_use {
    "用户请求评审 PR?" [shape=diamond];
    "前端代码质量检查?" [shape=diamond];
    "需要多维度分析?" [shape=diamond];
    "使用本技能" [shape=box];
    "不需要本技能" [shape=box];

    "用户请求评审 PR?" -> "使用本技能" [label="是"];
    "用户请求评审 PR?" -> "前端代码质量检查?" [label="否"];
    "前端代码质量检查?" -> "使用本技能" [label="是"];
    "前端代码质量检查?" -> "需要多维度分析?" [label="否"];
    "需要多维度分析?" -> "使用本技能" [label="是"];
    "需要多维度分析?" -> "不需要本技能" [label="否"];
}

使用本技能，当：

• 用户请求对前端 PR 进行代码评审
• 需要对前端代码进行质量检查
• 需要多维度、多角色的全面审计
• 需要通过 GitHub API 提交行级修改建议
• 需要生成结构化的评审总结

不使用本技能，当：

• 审查非前端代码（如后端、DevOps 配置）
• 只需要简单的语法检查
• 评审目标是代码合并而非质量审计

快速参考

评审角色

本技能使用 8 个专业审查角色进行全方位审计。评审时必须依次读取并应用以下角色的视角。

注意：每个角色的详细定义和检查项位于 $WORK_HOME/CodeAgent/prompt/front_end_review/ 或 ~/CodeAgent/prompt/front_end_review/ 目录下的独立文件中。

角色清单：

1. general-coding-standards-checker 文件：general-coding-standards-checker.md

2. code-reviewer 文件：code-reviewer.md

3. project-structure-check 文件：project-structure-check.md

4. javascript-reviewer 文件：javascript-reviewer.md

5. frontend-spec-check 文件：frontend-spec-check.md

6. silent-failure-hunter 文件：silent-failure-hunter.md

7. pr-test-analyzer 文件：pr-test-analyzer.md

8. comment-analyzer 文件：comment-analyzer.md

任务执行流程

第一步：初始化与上下文获取

使用以下命令获取 PR 的基本信息及当前最新的 Commit SHA：

# 获取 PR 详情 (必须使用完整 URL)
gh pr view {pr_url} --json number,headRefOid,repository,baseRefName,headRefName

# 验证仓库一致性
# 检查 repository.nameWithOwner 是否与 {pr_url} 中的仓库匹配

# 获取代码差异
gh pr diff {pr_url}

注意：headRefOid 将用于后续提交评论，确保指向的是最新的代码。

第二步：多维度深度评审（强制执行）

强制步骤 0：读取角色定义 使用 read 工具读取 $WORK_HOME/CodeAgent/prompt/front_end_review/{角色文件名}.md 或 ~/CodeAgent/prompt/front_end_review/{角色文件名}.md。 禁止跳过此步骤：必须完整阅读每个角色文件中的检查项，禁止凭印象或简要说明进行检查。

必须按照以下顺序依次执行所有 8 个角色：

1. general-coding-standards-checker

   • 读取 general-coding-standards-checker.md
   • 按照文件中的检查项逐一验证

2. code-reviewer

   • 读取 code-reviewer.md
   • 按照文件中的检查项逐一验证

3. project-structure-check

   • 读取 project-structure-check.md
   • 按照文件中的检查项逐一验证

4. javascript-reviewer

   • 读取 javascript-reviewer.md
   • 按照文件中的检查项逐一验证

5. frontend-spec-check

   • 读取 frontend-spec-check.md
   • 按照文件中的检查项逐一验证

6. silent-failure-hunter

   • 读取 silent-failure-hunter.md
   • 按照文件中的检查项逐一验证

7. pr-test-analyzer

   • 读取 pr-test-analyzer.md
   • 按照文件中的检查项逐一验证

8. comment-analyzer

   • 读取 comment-analyzer.md
   • 按照文件中的检查项逐一验证

强制要求：

• 每个角色都必须读取对应的角色定义文件，不得省略
• 按照文件中的检查项逐一验证，禁止只看简要说明
• 检查结果必须记录到评审总结中
• 交叉验证：确保一个角色的修复不会违反另一个角色的规范（例如：修复静默失败时不要引入不规范的变量命名）

第三步：提交行级修改建议 (Suggestions)

对于识别出的每个高置信度问题，构造 suggestion 评论。

单行修改：

gh api repos/{owner}/{repo}/pulls/{pr_number}/comments \
  -f body='[角色名] 发现违反规范：{具体原因}' \
  -f commit_id='{headRefOid}' \
  -f path='{file_path}' \
  -F line={line_number} \
  -f side='RIGHT' \
  -f subject_type='line'

多行修改：添加 start_line 和 start_side 参数。

第四步：提交评审总结

使用内置脚本提交整体 Review 总结。

操作步骤：

1. 生成评审总结文件 REVIEW_SUMMARY.md，包含完整的评审总结内容（参考 assets/REVIEW_SUMMARY_EXAMPLE.md）
2. 运行脚本（必须使用完整 PR URL）：

   python skills/review-frontend/scripts/post_review_summary.py {pr_url} REVIEW_SUMMARY.md
   

3. 删除临时文件

脚本特性：

• 自动清理本地路径等敏感信息
• 保持 Markdown 格式，直接展示完整内容
• 自动验证评审总结的基本格式
• 内容超过 60000 字符时自动截断

第五步：反馈 PR 链接

输出 PR URL 以便用户查阅：

gh pr view {pr_url} --json url -q .url

脚本使用详解

基本用法

# 使用 PR 编号
python skills/review-frontend/scripts/post_review_summary.py 123 REVIEW_SUMMARY.md

# 使用 PR URL
python skills/review-frontend/scripts/post_review_summary.py https://github.com/owner/repo/pull/123 REVIEW_SUMMARY.md

# 指定仓库（非仓库目录下使用）
python skills/review-frontend/scripts/post_review_summary.py 123 REVIEW_SUMMARY.md --repo owner/repo

# 跳过格式验证
python skills/review-frontend/scripts/post_review_summary.py 123 REVIEW_SUMMARY.md --skip-validation

参数说明

常见错误

常见合理化与反驳

红色警报 - 立即停止并重做

如果出现以下情况，立即停止当前评审，删除所有工作成果，重新开始：

• 没有读取角色定义文件就开始检查
• 只看 SKILL.md 中的简要说明而不读取详细的角色定义
• 使用"我记得"、"我印象中"代替读取角色文件
• 以"角色文件太长"为理由跳过读取
• 跳过任何一个角色（8 个角色必须全部执行）
• 没有按照定义的顺序执行角色
• 使用"我觉得"、"快速过一遍"、"覆盖了"等模糊表述代替显式检查
• 以"代码很简单"、"特殊情况"、"太繁琐"为理由省略检查
• 没有完成全部 8 个角色就提交评审总结

所有以上情况都意味着：停止并重做。不允许有任何例外。

异常处理

• Commit 冲突：如果 API 报错显示 commit 不存在，请重新获取 headRefOid
• 行号偏移：在 gh pr diff 输出中仔细确认行号
• 脚本提交失败：检查 gh 命令是否已安装并配置、是否有 PR 的读写权限、仓库路径是否正确
• Suggestion 失败：如果无法提交行级 Suggestion，请将所有建议以 Markdown 列表形式输出在对话中，但仍尝试通过脚本提交评审总结