SuperAPI AI 工具集

code-review

编程与开发

查看项目

更新于 11-06 18:11

技能介绍

这是一个面向 DevTools CL(变更列表)的代码评审检查清单,整理自评审者对已合入变更的反复反馈,既可用于上传前自检,也可用于在 Gerrit 上评审他人的变更。

一、用途与定位

清单的核心目标是帮助评审者系统性地检查变更,覆盖从收集上下文、加载专项规则,到审查测试、代码清晰度和 CL 元数据的完整流程。它本身是一份文本指南,不包含自动化执行逻辑;文中出现的 Git、curl 等命令需在本地 CLI 或交互式会话中运行。

二、主要环节

  1. 收集上下文:先读 CL 描述,再确认 diff 是否只做描述所说的事、没有额外改动。本地变更可用 git diff origin/main...HEAD 或 git show HEAD 查看;Gerrit CL 可用 git cl diff 获取 diff,并通过 curl 访问 comments 与 messages 接口(需去掉每行开头的 )]}' 前缀以得到 JSON)。若在自动评审代理环境中 diff 已在提示中,则应使用 read_file 和 search_files 工具,不运行 shell 命令。

  2. 加载专项技能与规则:根据 diff 触及的范围匹配对应技能或 .agents/rules/ 文件,例如涉及 import 或跨模块依赖时加载 devtools-imports,涉及 UI.Widget、Lit 视图、组件或 CSS 时加载 ui-widgets,涉及测试时加载 devtools-testing-guidance 及 .agents/rules/tests/*.md,涉及模型、BUILD.gn、grd 文件或入口点时加载 devtools-model-management 等。

  3. 边界与内部实现:严格强制模块边界不变量,包括模块入口点(foo.ts、foo-meta.ts)、GN 可见性与依赖边、core -> models -> ui -> panels 的分层、SettingDescriptor 放置在最低使用层、公共组件 API 的输入输出契约、CDP 协议契约以及测试有效性。对于模块内部的主观风格偏好,除非有 lint 规则或 .agents/rules/ 明确规则支持,否则不应提出。

  4. 共享误报防护:在报告任何问题前先检查这些防护,避免误报。例如,对于基于 eventMixin 与 UI.Widget 构建的子组件,Lit 的 @SomeEvent=${handler} 绑定会保留原始大小写并注册正确的事件名,且事件通过 widget.element(即 <devtools-widget> 宿主元素)派发;若事件源直接继承 ObjectWrapper 或组合持有它、监听器挂在宿主元素之上的祖先元素、或处理器读取 (event as any).data 而非 (event as CustomEvent<T>).detail,则应标记为问题。多行 html 模板中表达式与内联元素之间的换行和缩进空白,会由自定义 html 标签在运行时剥离,不应误报。生成 .css.js 文件导出的是普通 CSS 字符串而非 CSSStyleSheet 对象,将其插值进 <style>${styles}</style> 也不应误报。

  5. 测试正确性(最常见的评审反馈):关注同义反复测试(mock 直接完成被断言的行为,测试只验证了 mock 本身)、空测试(本地 promise 或数据从未接入 DevTools 逻辑,或 stub 跳过被测路径)、断言检查 setup 而非行为、测试是否放在正确文件、是否覆盖其声称的场景、E2E 选择器是否匹配真实 UI 文案、是否 fail fast、以及迁移前遗留组件的测试是否将 DOM 树检查封装在本地辅助函数中并具备截图金样测试。

  6. 测试卫生与清理:beforeEach 中创建单例须在 afterEach 中清理;fake timers 应在 try/finally 中恢复或使用测试运行器提供的 sandbox;不要重复 stub 同一方法而不先 restore;移除无意义的复制守卫。

  7. 代码清晰度:不要绕路取值,直接调用 TextUtils.TextRange.TextRange.fromObject(...);检查死代码、遗留调试代码、注释块和无关格式化改动;确认变更范围不越界;检查生命周期问题,如添加未移除的监听器与观察者、组件 detach 后仍继续的异步工作。

  8. CL 卫生:描述需说明原因及外部依赖;包含 Bug: / Fixed: trailer 或 Bug: None,行宽不超过 72 字符;迁移与堆叠系列需列出覆盖的遗留测试或文件并编号;对于 UI Eng Vision 迁移,若目标文件中仍存在核心违规(如遗留 UI.TreeOutline、UI.ListControl、非 MVP 构造函数、缺失 INJECT、绕过 performUpdate 的 #renderView、构造函数绑定监听器、presenter 中的同步 performUpdate 等),不应标记 Fixed:,多 CL 迁移的中间 CL 应使用 Bug: <id>。此外,预提交、lint 和格式化需通过。

  9. 编写评审意见:具体到文件与行,说明具体失败模式(如泄漏、挂起、空泛通过)并建议修复,必要时附代码片段;区分阻塞问题与细枝末节或提问;当评审者担忧并非真实缺陷时,回复理由而非静默修改。

三、适用场景与限制

适用于 Chrome DevTools 前端仓库的代码评审与自检。限制包括:清单依赖具体仓库结构与技能文件,不能直接套用于其他项目;不提供自动化执行或检查功能;文中涉及的命令需本地环境配合;缺失的自动化功能、平台支持、收费等信息暂未提供。