agents24 agent-teams 插件的评审维度检查清单：为并行代码审查建立可执行的多维评审标准

本文以 review-dimensions.md 中的五大评审维度检查清单为主体，结合 agents24 仓库中 agent-teams 插件的 team-reviewer 智能体定义 与 /team-review 命令编排，讲解多智能体并行代码审查中每个维度“查什么、按什么顺序查、发现如何结构化上报”。读完本文，你可以理解该插件如何把 Security、Performance、Architecture、Testing、Accessibility 五个维度的审查拆解为可逐项核销的 Checklist，并与发现去重、严重度校准机制配合，产出一份可追溯的合并评审报告。

检查清单在并行评审流程中的位置

agents24 仓库的 agent-teams 插件基于 Claude Code 的实验性 Agent Teams 能力，把一次代码审查拆成多个专职评审员并行执行。其分工链条是：

• team-reviewer.md 定义了单一维度的评审员：它被分配一个维度（security / performance / architecture / testing / accessibility），只在该维度内深挖，产出带 file:line 定位、严重度等级和修复建议的结构化发现；
• team-review.md 定义了编排流程：解析目标（文件、目录、git diff 区间或 PR 号）→ 为每个维度生成一个 {dimension}-reviewer → 收集各维度的结构化发现 → 去重、按严重度归并 → 输出合并报告并清理团队资源；
• 本文的主题文件 review-dimensions.md 则是这套流程的“执行手册”：它把每个维度展开为带 - [ ] 复选框的详细检查清单，供评审员在并行评审时逐项核对。

也就是说，team-reviewer.md 描述的是“每个维度关注哪些主题”（如 Security 维度关注输入校验、认证授权、SQL 注入/XSS/CSRF、密钥暴露、依赖 CVE 等），而检查清单文件进一步把这些主题落成可逐项打勾的具体验证点。下面逐维度完整介绍这些清单及其设计意图。

安全评审检查清单（Security）

安全维度覆盖输入处理、认证授权、密钥与配置、依赖四个子域，是评审用户输入或涉及认证的代码时必查的维度。

输入处理

• [ ] 所有用户输入都经过验证与净化
• [ ] SQL 查询使用参数化语句（禁止字符串拼接）
• [ ] HTML 输出正确转义以防止 XSS
• [ ] 文件路径经过校验以防止路径穿越
• [ ] 强制限制请求体大小

认证与授权

• [ ] 所有受保护端点都要求认证
• [ ] 授权检查验证用户是否有权执行该操作
• [ ] JWT 令牌经过完整校验（签名、过期时间、签发者）
• [ ] 密码哈希使用 bcrypt/argon2（而非 MD5/SHA）
• [ ] 会话管理遵循最佳实践

密钥与配置

• [ ] 无硬编码的密钥、API Key 或密码
• [ ] 密钥从环境变量或密钥管理器加载
• [ ] .gitignore 包含敏感文件模式
• [ ] 生产环境中禁用调试/开发端点

依赖

• [ ] 直接依赖中无已知 CVE
• [ ] 依赖锁定到具体版本
• [ ] 无增大攻击面的不必要依赖

与 team-reviewer.md 中 Security 维度的主题描述对照可见，清单把“不安全的加密使用”“API 安全（限流、输入边界）”等主题细化成了可操作的核对点，例如“请求大小限制”“依赖版本锁定”。按该插件的严重度校准规则（见 multi-reviewer-patterns 的 SKILL.md），可被外部用户利用的安全漏洞一律定为 Critical 或 High，因此这一维度产出的发现天然排在报告前列。

性能评审检查清单（Performance）

性能维度覆盖数据库、内存与资源、计算三个子域，适合在修改数据访问层或热路径代码时启用。

数据库

• [ ] 不存在 N+1 查询模式
• [ ] 查询使用合适的索引
• [ ] 大表上不做 SELECT *
• [ ] 列表端点实现了分页
• [ ] 配置了连接池

内存与资源

• [ ] 无内存泄漏（事件监听器被清理、流被关闭）
• [ ] 大数据集采用流式处理，而非整体载入内存
• [ ] 文件句柄与连接被正确关闭
• [ ] 昂贵操作使用了缓存

计算

• [ ] 无不必要的重复计算或冗余操作
• [ ] 算法复杂度与数据规模匹配
• [ ] I/O 密集场景使用了异步操作
• [ ] 主线程上无阻塞操作

对照 team-reviewer.md 中 Performance 维度的主题（N+1/缺索引/全表扫描、内存分配与潜在泄漏、缓存机会与失效、异步正确性、资源清理、算法复杂度、包体大小与懒加载），检查清单将其中后端相关部分展开为具体核对点；而“包体大小与懒加载”这类前端性能主题则由该维度的描述兜底，体现了“清单为主、维度描述为辅”的分工。性能发现按校准规则在热路径上至少定为 Medium。

架构评审检查清单（Architecture）

架构维度覆盖设计原则、结构、模式三个子域，适合结构性变更或新增模块时使用。

设计原则

• [ ] 单一职责：每个模块/类只有一个变更原因
• [ ] 开闭原则：不修改即可扩展
• [ ] 依赖倒置：依赖抽象而非具体实现
• [ ] 模块之间无循环依赖

结构

• [ ] 关注点分离清晰（UI、业务逻辑、数据层）
• [ ] 全代码库的错误处理策略一致
• [ ] 配置外部化而非硬编码
• [ ] API 契约定义清晰且带版本管理

模式

• [ ] 全代码库模式使用一致（无模式混用）
• [ ] 抽象层级合适（不过度设计也不欠设计）
• [ ] 模块边界与领域边界对齐
• [ ] 共享工具真正被共享（无重复实现）

值得注意的是，清单把“配置外部化”放在架构维度，而安全维度同时检查“密钥从环境变量/密钥管理器加载”——两个维度从不同角度覆盖同一处代码，这正是并行评审后需要发现去重的原因。

测试评审检查清单（Testing）

测试维度覆盖覆盖率、质量、可维护性三个子域，适合新增功能时启用。

覆盖率

• [ ] 关键路径有测试覆盖
• [ ] 边界情况有测试（空输入、null、边界值）
• [ ] 错误路径有测试（失败时发生什么）
• [ ] 集成点有集成测试

质量

• [ ] 测试是确定性的（无 flaky 测试）
• [ ] 测试是隔离的（测试间无共享状态）
• [ ] 断言足够具体（不满足于“没抛异常”）
• [ ] 测试命名清晰描述测试内容

可维护性

• [ ] 测试没有复制实现逻辑
• [ ] Mock/Stub 最少化且准确
• [ ] 测试数据清晰且相关
• [ ] 不看实现也能读懂测试

与 team-reviewer.md 中 Testing 维度的八项主题（关键路径覆盖缺口、测试隔离与确定性、Mock 恰当性、边界条件、集成测试完整性、命名与文档、断言质量、测试可维护性与脆弱性）逐项对应，可以推断该清单是由维度描述“落地化”而来，每项主题都能找到对应的可勾选项。

无障碍评审检查清单（Accessibility）

无障碍维度覆盖结构、交互、内容三个子域，适合 UI/前端变更时启用。该维度是五个维度中唯一有明确量化阈值的：

结构

• [ ] 使用语义化 HTML 元素（nav、main、article、button）
• [ ] 标题层级逻辑正确（h1 → h2 → h3）
• [ ] ARIA role 与属性使用正确
• [ ] 地标（Landmarks）标识页面区域

交互

• [ ] 全部功能可通过键盘访问
• [ ] 焦点顺序逻辑且可见
• [ ] 无键盘陷阱
• [ ] 触摸目标至少 44x44px

内容

• [ ] 图片具备有意义的 alt 文本
• [ ] 颜色不是传达信息的唯一手段
• [ ] 文本对比度充足（正文 4.5:1，大字 3:1）
• [ ] 内容在 200% 缩放下仍可读

其中 44x44px 触摸目标、4.5:1 / 3:1 对比度阈值与 team-reviewer.md 中“WCAG 2.1 AA 合规”的要求一致，使评审员可以直接对照 WCAG 级别给出结论。按严重度校准规则，核心功能的无障碍违规至少定为 Medium。

从清单到报告：发现格式、去重与严重度校准

检查清单的价值最终体现在合并报告中。三个机制保证多评审员结果不会互相矛盾或重复：

结构化发现格式

team-reviewer.md 要求每条发现使用固定结构：标题含严重度前缀（如 ### [SEVERITY] Finding Title），并包含 Location（path/to/file.ts:42 形式）、Dimension、Severity、Evidence（含代码片段）、Impact、Recommended Fix 六个字段。行为准则还要求：严格停留在被分配维度内、每条发现必须引用具体 file:line、严重度基于证据而非印象、区分“已确认问题”与“潜在隐患”、对无发现的维度如实报告而非凑数。

发现去重规则

当多个评审员在同一位置报告问题时，multi-reviewer-patterns 的 SKILL.md 定义了合并规则：

1. 同 file:line、同问题 — 合并为一条发现，署名所有评审员；
2. 同 file:line、不同问题 — 保留为两条独立发现；
3. 同问题、不同位置 — 分开保留但互相交叉引用；
4. 严重度冲突 — 采用更高等级；
5. 修复建议冲突 — 两条都保留并标注来源评审员。

去重流程逐条检查各报告中的 file:line 是否重合，重合时判断是否描述同一问题：同一问题则合并并保留更详细的描述，不同问题则都保留并打上 “co-located” 标签，合并后的严重度取最高值。/team-review 命令 的 Phase 4 正是按这套规则执行：去重 → 冲突取更高等级 → 按 Critical/High/Medium/Low 分组 → 交叉引用跨维度出现的发现。

严重度校准标准

严重度	影响	可能性	典型示例
Critical	数据丢失、安全入侵、完全失效	确定或极有可能	SQL 注入、认证绕过、数据损坏
High	显著功能影响、性能退化	很可能	内存泄漏、缺失校验、流程中断
Medium	部分影响、存在绕过方案	有可能	N+1 查询、缺失边界用例、错误信息不清晰
Low	影响极小、外观问题	不太可能	风格问题、次要优化、命名

配套的校准规则把检查清单中常见命中项直接映射到等级：可被外部用户利用的漏洞一律 Critical/High；热路径性能问题至少 Medium；关键路径缺测试至少 Medium；核心功能无障碍违规至少 Medium；无功能影响的风格问题为 Low。这解释了为何清单把“N+1 查询”放在性能维度、“缺失边界用例”放在测试维度——它们在合并报告中的起始等级都已预设。

合并报告模板与实操方式

评审完成后，按 SKILL.md 中的报告模板输出：头部包含 Target、Reviewers（各维度）、Date、Files Reviewed；正文按 Critical/High/Medium/Low 分节，每条发现带编号（如 [CR-001]）及 Location/Dimension/Description/Impact/Fix 字段；结尾是一张按维度 x 严重度交叉统计的 Summary 表加总体建议。

实操层面，README 给出了完整的启动方式：先设置环境变量 export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1，在 ~/.claude/settings.json 中配置 teammateMode（推荐 "tmux"，可选 "iterm2" 或默认的 "in-process"），安装插件后直接运行：

/team-review src/ --reviewers security,performance,architecture

该命令的 argument-hint 为 <target> [--reviewers security,performance,architecture,testing,accessibility] [--base-branch main]，其中 target 可以是文件路径、目录、git diff 区间（如 main...HEAD）或 PR 号（如 #123）；--reviewers 缺省为 security,performance,architecture，即 team-spawn 的 review 预设默认组合。针对特定变更类型，SKILL.md 还给出了推荐组合：API 端点变更选 Security + Performance + Architecture；前端组件选 Architecture + Testing + Accessibility；数据库迁移选 Performance + Architecture；认证变更选 Security + Testing；完整功能评审则启用除 Accessibility 外的全部维度。

小结

review-dimensions.md 把 agent-teams 插件的多维评审从“维度主题描述”推进到了“逐项可核销的检查点”：安全维度 18 项核对点覆盖输入、认证、密钥、依赖四层纵深；性能维度 14 项聚焦数据库、资源与计算；架构维度 12 项约束 SOLID、结构与模式一致性；测试维度 12 项兼顾覆盖、质量与可维护；无障碍维度 12 项以 WCAG 量化阈值收口。配合 team-reviewer 智能体的结构化发现格式与 SKILL.md 的去重、校准规则，这套清单使并行评审的产出收敛为一份按严重度排序、可追溯到人（评审员）和位置（file:line）的合并报告，这正是该插件“多维度并行审查”能力的执行层保障。