Code Review Principles（代码评审规范）

评审假设

提交的代码已经能编译，基本语法不是评审目标。评审的是：改动是否破坏内核行为、架构、可维护性、可调试性，特别是在并发与失败条件下。

评审范围限定在请求的文件/子系统/patch，除非证据显示风险跨界。具体结论必须指向代码路径、不变量、日志、测试或外部可见行为。

四级问题分级

级别	含义	处理
Apollyon	错误结果、数据损坏、安全问题、崩溃、严重不可恢复状态	必须修复
Keter	今天不爆炸，但明确阻塞后续开发：模块边界错位、状态所有权混乱、核心抽象方向错误	必须修复
Euclid	值得修但不阻塞主线：不优雅设计、局部耦合、命名平庸、可重构代码	通常修
Safe	纯风格偏好、理论洁癖、为抽象而抽象、只影响推测性未来	只记录，默认不修

级别标准必须严格：Keter 级结论必须点名具体证据（当前形状已经混淆 owner/真相源、泄漏 ABI 或私有表示、使生命周期/协议不可审计、阻塞已命名的当前或下一阶段路径）。仅凭"未来可能有维护问题"是 Euclid 或 Safe。

评审维度清单

1. 系统架构

• 改动是否符合当前子系统边界、所有权模型、分层？
• 子系统间是否通过显式接口通信，而不是摸另一子系统的私有类型/锁/内部状态？
• 跨域交接是否有一个协议 owner、每个可变状态一个 owner、显式的交接点与最终 cleanup owner？
• 文件持续膨胀时，是"一个 owner 干一件事"还是多角色混装（应拆分）？

2. 并发与竞态

• 共享可变状态由哪个锁/原子规则/中断规则/所有权转移保护？
• 锁顺序、跨解锁生命周期、唤醒与取消路径、TOCTOU 窗口。
• 错误路径、早返回、部分初始化是否留下 waiters/引用/映射/标志不一致？
• "常见路径能跑"对可抢占、可中断、可重入、可被另一线程观察的内核代码不够。

3. ABI 包含与兼容语义

• syscall/用户可见 API：flag 校验、errno 映射、信号行为、结构体布局、对齐、边界用例。
• Linux ABI 表示只允许出现在 syscall/兼容边界，进入核心子系统前必须转换为内部领域类型。
• 区分"不支持的功能"与"非法输入/权限失败"——返回错误码错误会破坏测试与用户态。
• 检查边界：零大小、最大大小、溢出、未对齐地址、空指针、重复 flag、未知 flag、混合模式。

4. 资源生命周期与清理

• 追踪内存、frame、fd、dentry、inode、task、wait queue、mapping、设备状态的所有权。
• 每个 acquire 在成功/失败/取消/拆除路径上都有匹配的 release。
• 查找泄漏、双重释放、悬垂引用、发布早于初始化完成。

5. 安全与信任边界

• 用户指针、设备数据、文件系统元数据、外部输入一律视为不可信。
• 检查 copy-in/out 顺序、边界、整数溢出、权限检查、内核数据暴露。
• 验证先于不可逆副作用（除非 ABI 要求相反）。

6. 失败路径与降级

• 分配失败、I/O 失败、部分拷贝、中断等待、无效句柄、不支持平台路径。
• 失败后状态要么不变，要么有文档地前滚。
• 优先显式错误而非静默回退（当调用者/测试需要区分行为时）。

7. 清晰度与本地语义

• 小函数 + 显式不变量 + 让非法状态难以表示的命名与数据结构。
• 避免聪明控制流、隐藏副作用、宽泛 catch-all helper、重复兼容逻辑。
• 可推导字段不缓存（除非性能/快照/诊断理由成立并注释）。
• 诊断字段标注"不参与行为决策"；缺失这类注释属于维护风险，不是风格问题。
• 注释解释非显然的不变量/ABI 取舍/锁顺序/临时桥/移除条件，不重复代码表面。

评审输出格式

结论：<是否批准 / 需修改 / 需停止>，对应当前边界
Apollyon/Keter 发现：
  - <级别> <代码路径>：证据 + 影响 + 最小修复方向
Euclid 发现：<仅列出值得修的>
Safe 发现：<仅记录>
验证缺口：<哪些声明缺 agent-run/user-run 证据>

• 剩余观测全是 Safe 时停止收集问题，不为保持评审而升级。
• 发现授权"整改"，不授权"自动重构"：建议的修复必须留在当前 Implementation Boundary 内；修复会跨边界时，停下请求 owner/ABI/契约决策。