review-changes

审查变更

审查变更的代码，并明确标注严重程度和置信度。

流程

按以下顺序进行，以完成全面、高效的审查：

1. 了解意图。 阅读 PR 描述、提交消息、关联的问题和现有审查反馈。在判断变更的实现质量之前，先了解它_试图_实现什么。
2. 必要时加载先前反馈指南。 如果审查中已有评论或备注，请在审查差异之前阅读 references/reviewer-feedback.md，以便确认这些反馈是否仍然适用，以及应如何回应。当用户要求处理现有的 GitHub 审查反馈时，先收集仍有效的评论，将每个仍然成立的问题对应到相关技术视角，并在决定如何回复或解决之前，按常规问题格式列出。在 GitHub 拉取请求中，还要阅读 references/github-pr-reviews.md，了解讨论串状态、回复和解决问题的指南。
3. 扫描范围。 浏览完整差异，了解涉及哪些文件、模块和层。这将决定需要加载哪些视角。
4. 选择视角。 使用下表选择相关的技术视角。只加载适用的视角，其余跳过。可读性是基础视角。
5. 逐个审查文件。 按文件逐一检查差异。只有在解释影响或确认问题是否真实存在时，才查看相邻的未更改代码。重新检查先前的审查反馈是否仍与最新代码相符，再重复或认可这些反馈。
6. 综合分析。 逐文件检查后，寻找可以归并的根本原因。不同文件中的多个症状可能源自同一个问题——应将其作为一个归并的问题呈现，而不是拆成多个条目。
7. 撰写审查报告，使用下方的报告结构：一级标题、简短介绍、## 概述、## 问题 和 ## 结论。
8. 给出结论，并放在最后一节。

视角选择

根据差异涉及的内容，使用此表决定要加载哪些视角。可读性始终是基础视角。

如果差异涉及……	加载这些视角
用户输入、身份验证、网络、机密	安全
公共 API、模块边界	架构
CLI 输出、错误消息、默认值	UX
热路径、循环、查询、大型数据	性能
新功能、错误修复、分支逻辑	测试
文档、README、文档字符串、示例	文档
其他任何内容	可读性（始终启用）

范围

重点关注变更的代码以及差异引入的行为。只有在解释影响或确认问题是否真实存在时，才查看相邻的未更改代码。

评级

分别评定影响程度和确定性。

严重程度	表情	含义
P1	🔴	严重：安全漏洞、数据丢失、崩溃或发布阻碍
P2	🟠	重要：功能失效、严重回归或重大正确性缺陷
P3	🟡	应修复：较小的错误、覆盖缺口或易用性问题
P4	⚪	可改进：影响较小的润色或一致性问题

仅报告置信度 ≥ 80 的问题。对于置信度在 60–79 之间的问题，请在末尾的“低置信度观察”一节中简要提及，并明确标注为不确定。低于 60 的问题直接省略。

报告结构

使用以下格式：

1. # Code Review
2. 一到两句背景说明
3. ## Overview
4. ## Findings
5. ## Verdict
6. 可选的 ## Lower-confidence observations

优先采用下面的示例，而不是添加额外说明。

问题格式

每个问题必须包含：

• File：包含行号的位置
• Issue：用一句话说明问题
• Reasoning：说明行为为何错误或有风险
• Evidence：具体代码、类型或行为
• Suggestion：具体的修复方案或后续操作

如果问题来自之前的评审反馈，请添加 Source。对于 GitHub 评审，请直接链接到评审评论。

使用以下标题格式：

### 🟠 P2 · 🛡️ SEC-1 · Missing authorization check · 92%

使用以下前缀：

• SEC：安全
• ARC：架构
• TST：测试
• UXD：用户体验
• RDY：可读性
• DOC：文档
• PRF：性能

使用以下类别图标：

Prefix	Emoji	Category
SEC	🛡️	安全
ARC	🏗️	架构
TST	🧪	测试
UXD	🎨	用户体验
RDY	👁️	可读性
DOC	📖	文档
PRF	🚀	性能
GRP	📦	分组问题

评审呈现方式

在 ## Overview 中按以下格式列出问题：

- {severity_emoji} {severity} · {category_emoji} {id} · {title} ({confidence}%) · {file}:{line}

先按严重程度排序，再按置信度排序。只有在问题具有相同根因时才将其分组。

可操作性

优先指出具体、可复现且在当前更改中易于处理的问题。对于常规规模的差异，问题数量最多约为 8 个。

避免：

• 没有具体证据的推测性问题
• 已由工具检查强制执行的风格细节
• 没有明确风险的重写建议
• 差异之外的既有问题
• 无关的范围蔓延

示例布局

# Code Review

I reviewed the BITZ parser changes with a focus on payload validation and test
coverage. I found one P2 issue and one P3 gap.

## Overview

- 🟠 P2 · 🛡️ SEC-1 · Corrupted BITZ frames are accepted if garbage follows a valid Arrow stream (96%) · libtenzir/builtins/formats/bitz.cpp:209
- 🟡 P3 · 🧪 TST-1 · The new tests miss payload-corruption and compatibility coverage (93%) · test/tests/operators/bitz/round_trip.tql:1

## Findings

### 🟠 P2 · 🛡️ SEC-1 · Corrupted BITZ frames are accepted if garbage follows a valid Arrow stream · 96%

- File: libtenzir/builtins/formats/bitz.cpp:209-247
- Issue: ...
- Reasoning: ...
- Evidence: ...
- Suggestion: ...

### 🟡 P3 · 🧪 TST-1 · The new tests miss payload-corruption and compatibility coverage · 93%

- File: test/tests/operators/bitz/round_trip.tql:1-6
- Issue: ...
- Reasoning: ...
- Evidence: ...
- Suggestion: ...

## Verdict

**Needs changes**

| 🔴 P1 | 🟠 P2 | 🟡 P3 | ⚪ P4 |
| :---: | :---: | :---: | :---: |
|   0   |   1   |   1   |   0   |

- Reject BITZ frames that contain unread tail bytes after the embedded Feather stream.
- Add a regression test for malformed message payloads and a mixed legacy/new compatibility fixture.
- Merge after the parser validation bug is fixed.

结论标签应为以下之一：

• Ship it：没有问题，或只有 P4 级的小问题。
• Ship with fixes：问题为 P3 级或更低；没有阻碍合并的问题。
• Needs changes：至少有一个应在合并前解决的 P2 级问题。
• Blocked：至少有一个 P1 级问题；不要合并。

结论中的项目应写成具体的后续步骤。

技术视角

仅加载与当前差异相关的视角：

• 架构
• 文档
• 性能
• 可读性
• 安全
• 测试
• 用户体验

之前的评审反馈

如果更改已有评审评论，或用户询问如何回复，请阅读 评审者反馈。利用这些反馈进一步完善问题，核实评论是否仍然适用，并在完成技术评审后起草简洁的回复。将之前的反馈纳入评审，把每个仍然有效的问题转化为相应的技术问题。

GitHub 拉取请求

评审 GitHub 拉取请求时，请先检查现有评审评论和未解决的讨论串。如果存在，请在评审差异前阅读 评审者反馈 和 GitHub 拉取请求评审。将每个仍然有效的问题作为相应的技术问题提出，并添加一个 Source 行，直接链接到 GitHub 评论。参照 GitHub 专用文档，决定是回复、解决、进一步讨论，还是让讨论串保持开放。