QuestDB 代码审查规范实战:解读 `review-pr` Agent 技能与仓库级审查流程

原创2026-09-20 15:52:331,889 阅读
文章标签:数据库时序数据库列式数据库OLAP实时分析大数据后端

QuestDB 代码审查规范实战:解读 review-pr Agent 技能与仓库级审查流程

导读

本文围绕 QuestDB 仓库中的 .claude/skills/review-pr/SKILL.md 展开,这是一份面向 AI 代码审查 Agent 的完整技能规范,定义了审查 GitHub PR 或本地 Git 范围时必须遵循的审查心态、分级策略、四步工作流、14 个专项审查 Agent 角色与一整套 QuestDB 特有检查清单(零 GC、日志链、SQL 测试断言、内存跟踪器等)。读完本文,你将掌握这套"先证伪、后定级、按证据输出"的阻断式审查方法论,并理解它如何与仓库中的 CLAUDE.md、AbstractCairoTest.java、QueryAssertion.java 等真实代码与测试基建相互印证。

一、技能定位:review-pr 是什么

SKILL.md 的 frontmatter 将技能命名为 review-pr,描述为"Review a GitHub pull request or local Git range against QuestDB coding standards"(依据 QuestDB 编码标准审查 GitHub PR 或本地 Git 范围),参数提示为 [PR number or URL | --range=<base>..<head>] [--level=0..3],允许使用的工具为 Bash、Read、Grep、Glob 与 Agent。

调用方式:/review-pr [PR number or URL | --range=<base>..<head>] [--level=0..3]。当以 /skill:review-pr <args> 运行时,<args> 会以 User: 消息形式追加,被当作 $ARGUMENTS 处理。技能要求恰好解析一个审查目标:

  • PR 编号或 URL;
  • 或 --range=<base>..<head>,其中 <head> 可省略(--range=<base>..),此时审查的是工作区,包含未提交的改动。

如果同时提供两个目标,技能要求停下来询问用户意图;如果一个都没提供,则要求用户给出一个。技能本身只做只读操作:Bash 仅用于只读的 gh 与 Git 查询,Read、Grep、Glob 用于阅读源码与搜索调用点,Agent 用于启动"全新上下文"的子审查代理;不允许编辑文件或推送。

这一点与仓库的工程文化一脉相承:QuestDB 是一个以零 GC Java 为核心、C/C++ 原生层加速、面向时序数据的高性能数据库(见 CLAUDE.md),代码合入质量直接关系到生产环境的稳定性,因此审查被设计为**阻断式(blocking)**而非走过场。

二、审查心态:先证伪,后定级

SKILL.md 用一整节定义了审查者应持有的心态,这是整套技能的灵魂,原文几乎每一条都是一条可执行的纪律:

  • 假设任何东西在被验证之前都不是正确的。不要只看 diff 本身,要读周边代码理解上下文。
  • diff 是线索,不是审查的边界。最高价值的 bug 往往位于 diff 之外、依赖了 diff 悄悄改变的契约的调用点上。
  • 发现不等于结论(Discovery is not a finding)。任何顾虑——包括多个 Agent 产出的——都只是未经证实的假设,必须通过 Step 3b 的"准入闸门"才算数;只报告被准入的问题,其余一律不写。零发现是成功结果。
  • 先证伪再解释。在构建叙事之前,去寻找缺失的生产者、不支持的配置、被遗漏的调用方、重试、守卫、下游偏移与 merge-base 行为。证伪失败不等于证据,不确定性永远不能被提升为严重级别。
  • 控制 PR 的爆炸半径。本 PR 只应修复它声称要修复的东西,加上被本次改动明确破坏的内容。既存 bug、行为与 base 未变的加固机会、只支撑另一候选命题的论断,都不算针对本 PR 的发现;唯一例外是:本 PR 明确把某个既存 bug 移上了活跃路径。但爆炸半径约束的是 PR"必须修什么",不约束审查"可以知道什么"——达到同等证据标准的既存 bug 会以 Step 4"邻近问题草稿"形式留下,而不是被丢弃。
  • 不夸代码。跳过 "looks good"、"nice work"、"clever approach",只聚焦问题与风险。
  • 对抗性思考。对每个改动追问:什么输入会击穿它?并发访问下会怎样?在 100 亿行的表上运行会怎样?列是 NULL 会怎样?分区是空的会怎样?
  • 在关键路径上要求最优算法。QuestDB 是性能优先的数据库:数据路径上"能正确工作"不够,线性扫描替换哈希查找、两次遍历替代一次遍历、扫描时每行分配对象,都是阻断性缺陷;非数据路径则运用判断力——SQL 编译、DDL、启动期的有界非扩展成本值得报为 Moderate,但不值得因此阻断合入。
  • 检查"缺了什么",不只是"有什么":缺失的测试、缺失的错误处理、缺失的边界场景、缺失的文档。
  • 未经测试的改动是覆盖风险,不是缺陷证据。仅凭缺测试不能把发现定成 Critical。
  • 紧迫性既不是证据也不是豁免。
  • 验证每一个声明。PR 标题说"fix"就验证 bug 是否真实存在且修复正确;说"improve performance"就找 benchmark 或推演算法变化;说"simplify"就验证新代码确实更简单且没有丢行为。把 PR 描述当作未经证实的假设。
  • 报告前评估可达性。对每个潜在 bug 追踪真实调用方与输入。需要物理上不可能的条件(数十亿列、被破坏的 JNI 输入、任何调用方都无法产生的值)的问题不是真实发现,直接丢弃。
  • QuestDB 以 -ea 开启 Java 断言运行。assert 是校验"表示损坏或内部 bug 的不变量"的合法守卫,不要把它标为不足;只有当该条件可能被正常(非损坏)用户操作触发时才标记 assert。

这套心态与 CLAUDE.md 的"调查失败"原则完全同构:CLAUDE.md 明确要求"绝不要把失败当作'既存''flaky''无关''已知问题'而打发掉——那是假设不是结论",直到 git log、master 复现或真实时序约束迫使得出不同结论为止。二者共同构成 QuestDB 对"证据"的苛刻标准。

三、审查级别:用 --level=0..3 控制分析广度

技能从 $ARGUMENTS 解析级别令牌:--level=N、-lN 或裸数字 0-3,未给出级别时默认 0。解析后要剥离级别令牌与 --range= 令牌,再把剩余部分(PR 编号或 URL)交给 gh 命令。

级别只裁剪分析广度,不改变审查精神(始终对抗性、阻断式、不夸赞)。级别越高 token 成本越高,级别 3 仅留给高风险的 PR(复制、JNI 边界改动、磁盘格式、公共 API、安全/ACL)。各级别实际运行的步骤见下表:

级别 运行内容
0(默认) Steps 1、2、2.4、2.6、4。跳过 Step 2.5 与 Agent fanout。内联审查 diff 的正确性、NULL 处理、算法最优性、测试与 QuestDB 规范;内联构建 Step 2.6 覆盖图;每个候选仍须以空白证据表单内联通过 Step 3b 准入门。
1 有测试代码时增加 Step 2.5a 与 2.5e。运行 Agent 1 及至多两个适用的角色(从 Agents 3、5、6、12、13 中选)。对每个存活的原子候选运行一次独立证伪任务。
2 完整 Step 2.5,其中 2.5b 限定于 public/protected 符号。运行 Agent 1 及至多四个与改动相关的角色(Agents 2-8 与 11-13)。对每个存活的原子候选运行独立证伪。
3 完整 Step 2.5 与完整准入协议。至多选择六个适用的发现角色(Agents 1-14):Agent 1 始终运行;改动符号存在 diff 外调用方时运行 Agent 9;Agents 2-8 与 11 仅在触及各自领域时运行;Agents 12-14 仅在改动测试或声明修复 bug 时运行;Agent 10 仅在需要独立的对抗性通行时运行。深度来自生产者/可达性证据与独立证伪,而非 Agent 数量。

审查开始时必须以一行说明所选级别(例如 "Reviewing PR #1234 at level 2"),让用户清楚得到的是什么;若级别是默认的,应提及级别 3 可提供完整审查。

四、四步工作流:从上下文到输出

Step 1:收集 PR 上下文——一切审查的前提是确定 $BASE

每个模式都必须以设置 $BASE 收尾——即改动所对照的提交。$BASE 是 Step 2.4 和每个行为发现的"同触发器 base 检查"的前提;从未建立 base 的审查无法把任何东西归因到本 PR。

GitHub PR 模式:剥离级别令牌后把 PR 标识存入 $PR,然后抓取元数据、diff、评论与 base 修订:

PR='<PR number or URL from $ARGUMENTS, with any level token removed>'
gh pr view "$PR" --json number,title,body,labels,state
gh pr diff "$PR"
gh pr view "$PR" --comments
BASE=$(gh pr view "$PR" --json baseRefOid --jq .baseRefOid)

本地范围模式(--range):没有 PR、没有描述、没有标签,直接取 Git diff:

BASE='<base from --range>'
HEAD='<head from --range, or empty for the working tree>'
git diff "$BASE"${HEAD:+"...$HEAD"} --stat
git diff "$BASE"${HEAD:+"...$HEAD"}
git diff "$BASE"${HEAD:+"...$HEAD"} --name-only

当 <head> 为空时,diff 包含未提交的工作区改动——这正是审查 fix-pr 结果推上去之前的常态。未跟踪文件不会出现在 git diff 中,必须用 git status --porcelain 列出并读取其中属于本次改动的部分(尤其是新测试文件),否则 Step 2.6 的覆盖图会悄悄漏掉它们。

范围模式下跳过 Step 2 并在报告中说明(没有标题/描述可查),其余每步照常运行:diff 仍是入口,调用点分析仍向外扩展到变更文件之外,发现仍按同一套规则分类。把审查限制在变更文件内会废掉"diff 外破坏分析"——这是本技能最有价值的部分。

Step 2:PR 标题与描述核对

范围模式下跳过此步。对照 CLAUDE.md 的约定核查:

  • 标题遵循 Conventional Commits:type(scope): description;
  • 描述重复动词并说明对用户的影响;
  • 修复 issue 时 body 顶部写 Fixes #NNN;
  • 语气冷静、分析式,不使用最高级或对数字加粗强调;
  • 标签与 PR 范围匹配(SQL、Performance、Core 等);
  • 允许捆绑相关修复,不要求拆分。

这些约定在 CLAUDE.md 中均有原文依据:例如 PR 标题必须遵循 Conventional Commits 格式、描述必须面向终端用户讲述正面影响、语气需冷静分析并同等呈现正负效果、修复 issue 的 PR 必须用 Fixes #NNN 引用、常用标签清单(Bug、CI、Core、Performance、SQL、Security、WAL 等)也已列出。

Step 2.4:子模块溯源——每个级别都强制执行

子模块指针的变动不等于本 PR 作出的变动。在审查子模块内任何内容之前,先对指针移动分类。这一步成本低、在包括级别 0 在内的每个级别都运行,并且决定了"整个仓库的 diff 是否在范围内"——跳过它就会把上游数月的已发布工作错误地归因到眼前的 PR。

先列出指针移动,再对每个指针解析子模块默认分支并测试新提交是否已在上面:

git diff "$BASE...HEAD" --submodule=short | grep -E '^(diff --git|[+-]Subproject commit)'

cd <submodule path>
git fetch origin --quiet
DEF=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')   # e.g. main, master
git merge-base --is-ancestor <new-sha> "origin/$DEF" && echo UPSTREAM-SYNC || echo OFF-DEFAULT
git branch -r --contains <new-sha>

每个指针移动必须分类为恰好一种:

  • UPSTREAM-SYNC——新提交是子模块默认分支的祖先,其内部工作已在上游落地,本 PR 只是推进指针去取它。其内容不在 diff 内、也不是本 PR 的责任:不要当作改动审查,不要将其行为变化归因于本 PR,不要基于它构建发现。唯一合法的发现是真正的集成缺陷:本 diff 的代码错误调用了新同步的代码——该发现位于本 diff 内的调用点,而非子模块内部。
  • OFF-DEFAULT——新提交只存在于功能分支或 PR 分支,子模块改动属于本次逻辑改动,按 diff 内审查。
  • UNRESOLVED——无法确定分支(无网络、浅克隆、缺 remote)。在报告中明确说明,按 OFF-DEFAULT 保守处理,并声明范围决策是在无溯源的情况下作出的。

嵌套子模块独立分类:一个 OFF-DEFAULT 的 OSS 指针不能说明嵌套其中的 client 指针——同一个 PR 里后者经常是 UPSTREAM-SYNC。此判断对本仓库尤为重要:java-questdb-client/ 是独立 git 仓库(子模块),CLAUDE.md 专门强调必须 cd 进去独立提交,不能只在父仓库里改指针。

Step 2.5:映射变更面

启动审查 Agent 之前,先产出结构化的变更面映射。此步强制使用 Grep 与 Glob,不允许凭记忆推断调用点;其输出是 Step 3 每个 Agent 的必需输入。

  • 2.5a 每个变更符号的语义增量:对每个被修改/新增的函数、方法、trait、struct 字段、SQL 操作符/函数或公共常量,写清 Symbol(全限定名)、Before/After(签名、返回类型、错误/异常行为、panic 行为、可变性、排序/幂等保证、分配行为、线程安全)与 Delta(一行说明语义变化)。“refactored”“cleaned up”“improved”“simplified”不是可接受的 delta;写不出实际行为差异就写 "no behavioral change"——但必须先检查,不能当作默认值。
  • 2.5b 调用点清单:对每个 public/protected/包私有或导出的变更符号,在整个仓库跑 rg 找全部 diff 外的调用点、实现、覆写与引用。Java 还要搜子类覆写、声明它的接口、反射调用(getMethod、getDeclaredField、Class.forName)、SQL 函数/操作符注册(FunctionFactory、OperatorRegistry)、service loader 条目;Rust 还要搜 trait 实现、宏展开、JNI 导出及 Java 调用方、extern "C" 边界。变更的 pub/protected/包私有符号在审查痕迹里没有一条 rg 搜索记录就是违反技能——模型不允许不展示搜索就说"这里只有这一处使用"。
  • 2.5c 隐式契约清单:对每个变更符号逐项核对——在哪些输入上 panic/抛异常、错误变体及传播链、迭代顺序/排序稳定性/NULL 排序、幂等与重入、锁获取顺序与返回时持有哪些锁、热路径 vs 编译期路径上的分配、Send/Sync/线程亲和/JFR/JNI 线程附着要求、null 与哨兵 NULL(Numbers.LONG_NULL、Numbers.INT_NULL 等)是否仍被区分、取消/关闭行为、以及 SQL 上该符号是否出现在此前未出现的新子句中(WHERE、GROUP BY、JOIN ON、ORDER BY、窗口帧、分区谓词、物化视图定义)。
  • 2.5d 跨上下文暴露清单:以显式列表结束本步——"本变更可见但 diff 未触及的地方"。这是 Step 3 bug 猎手子代理的最高优先级输入。按执行上下文分组:热数据路径、SQL 编译、异步运行时、JNI 边界、复制、物化视图、并行执行 worker 等,清单上每一项都必须在 Step 3 被审查。
  • 2.5e 测试面与辅助工具清单:仅当 PR 新增或改动测试代码时运行。用真实 Grep/Glob 搜索(不凭记忆)盘点变更测试文件所在包/模块的既有测试基建——基础测试类、共享 @Before/@After、辅助方法、fixture、断言工具(搜索 extends Abstract.*Test、class .*TestUtils、assertMemoryLeak、assertQuery、assertSql、基类中的共享 protected 辅助)。这份清单是 Agent 13 标记"重造轮子"发现的基线——"你复制了样板而不是复用辅助 X"这类发现要求 X 出现在清单里。若 PR 改动了共享测试基类/辅助/fixture,也要对它们跑 2.5b 调用点清单——改测试基类可能静默破坏所有子类化测试。最后产出被练习符号映射:每个新测试实际练习了 2.5a 中的哪些生产符号。

Step 2.6:测试覆盖图——每个级别都必须构建

此步在每个审查级别、对每个触及生产代码的 PR 运行——尤其包括"零测试改动"的 PR:没有测试改动不会跳过测试审查,而是把审查集中到这里。级别 0 直接从 diff 推导行为变化行(跳过 2.5a),级别 1+ 使用 2.5a 的语义增量。

覆盖表每个行为变化一行:每个 delta 非 "no behavioral change" 的变更符号,再按其中每个新增/变更的分支、错误路径、NULL/边界情况细分。每行记录:Change(符号+具体行为/分支/路径)、Test(跨测试树用真实 rg/fd 搜索找到的精确测试类与方法——搜符号名、SQL 函数/操作符名、错误消息文本、配置键;未记录搜索命令就引用测试同样是违反技能,"既有测试大概覆盖了"被禁止)、Failure link(该测试断言什么、行为回归时断言为何失败,"测试调用了方法"不是 failure link)、Reachability / population(到达变更路径的支持的操作/配置/事件,及受影响的用户/运维人群,"public"或"用户可见"不是人群)、Credible regression consequence(具体的可信突变或复发及人群会观察到什么,区分实质伤害与表面输出)、Change risk、Stable test design、Effort / fragility evidence、Dimensions(happy/error/NULL/边界/并发/资源清理各维度,标注 covered/uncovered/N-A 及理由)、Disposition rationale。

无有效测试的行标记为 UNTESTED,再按证据而非类别分类:

  • Critical gap(阻断):仅当变更路径与受影响人群受支持且可达、可信回归会产生实质 Critical 后果(数据丢失/损坏、安全失败、宕机/挂起、兼容性破坏、无界资源损失等)、既有控制无法兜住风险、且该行通过 Step 3b 时。"bug fix""public API""user-visible""concurrency""security"这些标签本身永远不会让 gap 变成 Critical。
  • Moderate gap:有意义但有界的回归暴露——大多数没有回归测试的 bug fix、有独立但非 Critical 后果的内部/错误路径、未达到 Critical 举证责任的实质不确定性。
  • Accepted gap:低风险、局部或机械性改动,记录的分析表明最轻量而有意义的测试比被测代码更不成比例或更脆弱,且既有保障使残留用户风险很小。
  • Exempt:已验证无行为变化的行(纯重命名、死代码删除、仅注释/文档/CI 改动)。

覆盖图是 Agent 5、Agents 12-14 与 Step 4 测试门的必需内部证据。只发布被准入的 gap;COVERED、ACCEPTED、EXEMPT 与省略行保持私有(除非用户询问)。级别 0 可按符号粒度建行以控制成本,但新增错误/异常与 NULL/边界路径仍需独立成行。

Step 3:变更专属候选发现——14 个角色的 Agent 编目

本步使用 Agent 工具启动"全新上下文"代理。只选择领域被实质触及的角色,遵守级别的发现上限,以只读 reviewer 任务启动。Agent 数量从来不是证据,未使用的角色跳过。

每个被选中的 Agent 收到:(1) PR 或本地范围 diff;(2) Step 2.5 的完整变更面映射(语义增量、调用点清单、隐式契约、跨上下文暴露清单);(3) Step 2.6 的测试覆盖图。diff 加面映射可能很大——写入共享文件(如 temp/chain 目录)并通过任务的 reads/任务文本指向它,而不是把整个载荷粘进每个任务;Agents 10 与 11 是刻意减上下文的例外。

候选发现指令(适用于所有 Agent):你是假设生成器,不是有权发布发现的权威。输出供独立证伪的原子命题,不分配严重级别、不提修复建议、不写说服性标题、不使用 "verified"/"proved"/"confirmed"。为每个候选引用确切的变更 hunk 或据称被破坏的未变调用点契约;命名支持状态的生产者(创建每个触发条件的精确用户操作、配置、writer/版本、事件源或代码路径,找不到就写 producer: unknown,不要发明部署或状态);给出可达链、头部观察、同触发器 merge-base 观察、用户可见症状与原始证据路径/命令,任何未实际检查的都标 unknown;主动寻求证伪并记录最强反证。含 never、only、exactly one、no retry 等全称否定词的声明需要穷举的调用方/事件源清单,而非一条追踪路径。没有独立后果的命题只是其父候选的证据,父候选倒则依赖命题跟着倒。两个 Agent 重复同样的推理只算一个假设,佐证需要独立证据类型且仍不能绕过 Step 3b。返回零候选是合法且优于返回投机候选的。

14 个 Agent 角色职责摘要:

Agent 职责
1 — 正确性与 bug NULL 处理、边界、逻辑错误、off-by-one、操作符优先级、错误路径;对照调用点清单交叉核对每个变更符号。QWP 入口/角色门控、就地切换或故障转移相关改动还须验证"Store-and-forward & pool startup invariants"清单。
2 — 并发 竞态、共享可变状态、缺 volatile、锁顺序、数据结构线程安全。
3 — 性能与算法最优性 强制"必须用已知最优算法"而非"别搞 O(n²)":时间复杂度陈述、最优算法追问、多趟合并、冗余计算、数据结构选择、不必要拷贝/转换、零 GC 违规(java.util.* 替代 io.questdb.std、热路径字符串拼接、捕获型 lambda、自动装箱)、SIMD 机会、编译期 vs 数据路径区分,且每个性能发现都必须给出量级(乘数或固定上界)。
4 — 资源管理 全路径泄漏(尤其错误路径)、try-with-resources、原生内存、池管理;新增原生分配点还须套用 per-query memory tracker 集成清单。
5 — 测试审查与覆盖 覆盖 gap、错误路径/NULL/边界/回归测试、assertMemoryLeak() 使用;消费 Step 2.6 覆盖图并变异抽查(对 3-5 个最危险变更行问"哪条测试会在该行出错时失败");强制 SQL 测试断言(builder API)硬规则。
6 — 代码质量与规范 坏味道、成员排序、命名、现代 Java 特性、死代码、第三方依赖;重点检查未闭合的 LOG 语句(详见第八节)。
7 — PR 元数据与约定 标题格式、描述质量、提交消息、标签、测试中的 SQL 风格。
8 — Rust 安全(仅含 .rs 文件时) 一切可运行时 panic 的点:unwrap()、expect()、无界数组索引、panic!、unreachable!、todo!、release 模式整数溢出、非法输入下的 slice::from_raw_parts——JNI/FFI 里 panic 会无恢复地终止整个 JVM。
9 — 跨上下文调用方影响 逐调用点(而非逐失败模式)输出,每个调用点判定 SAFE / CANDIDATE / INSUFFICIENT_EVIDENCE。
10 — 全新上下文对抗 只收 diff 与变更文件名,不收面映射/契约清单/检查清单,逃避清单锚定,输出可证伪的错误方式并先尝试自证伪。
11 — 对抗性性能 收 diff 加完整源文件,不收性能清单,对每个新增/修改函数问"理论最快实现是什么,代码做到了吗",自底向上追踪数据流。
12 — 测试效力与正确性(对抗) 证明每个测试真的练习了生产变更且能在回归时失败:空断言、够不到变更代码的测试、仅 happy path、并发测试自身竞态、setup/teardown 资源泄漏。
13 — 测试代码质量与可维护性 反射滥用、无复用/样板复制(须用 2.5e 清单定位既有辅助)、javadoc 膨胀、残留坏味道;零 GC 与 io.questdb.std 规则不适用于测试代码,成员排序、is/has 命名、SQL 风格适用。
14 — 回归测试效力验证 对声称修 bug 的 PR:回退生产 hunk 后新测试必须变红;测试在修复回退后仍通过就不是回归测试。

各 Agent 输出合并进私有候选台账(candidate ledger):把复合叙事拆成原子命题,按命题加证据去重并记录依赖。不起草报告行文、严重级别或修复建议。候选不是发现。

Step 3b:独立证伪、证明与准入候选

状态机无捷径:HYPOTHESIS → FALSIFYING → PROVEN → ADMITTED。任何缺失证明、未解决的矛盾、复现失败、不支持的生产者、依赖被省略的前提,都以 OMITTED 结束。没有 DOWNGRADED 状态,"无法证伪"永远不等于 PROVEN。

级别 1-3 为每个原子候选启动一个全新上下文证伪者。证伪者只收到:(a) 中立命题、(b) 目标仓库与 base/head 修订身份(commit SHA,或未提交工作区的捕获 diff 哈希)及相关文件名、(c) 原始证据/工件路径。不要发送发现叙事、建议严重级别、建议修复、作者身份、其他 Agent 的投票或"该声明已被验证"的说法。级别 0 时父进程在同一协议下用空白证据表单内联执行,之后再写任何报告行文。

证伪者的首要任务是构造最强反驳:找缺失的状态生产者、不支持的部署、不可能的版本/格式配对、被省略的调用方或事件源、重试、守卫、锁、校验、下游偏移,或相同/更好的 base 行为。只有候选幸存后才组装肯定性证明。

行为候选只有在以下每个字段都有引用证据支撑时才被准入:Attribution(确切变更 hunk,或确切未变调用点加本 PR 变更的契约)、Supported-state producer、Reachability(完整生产者到症状路径,含调用方、事件源、重试、守卫、锁、偏移)、Head observation(在审查修订上执行触发器并观察输出/状态)、Base observation(同一触发器在 $BASE 上的观察,或附证明的 "N/A — genuinely new surface")、User symptom、Counterevidence search、Artifact(精确命令/测试、输出、环境/配置、修订身份)。竞态、顺序、重试、重启、文件系统状态、兼容性、磁盘格式声明总是需要运行时证据;仅静态读源码不能准入它们。

静态发现(编译错误、直接规范违反、畸形 LOG 链)可标 producer/head/base/runtime 为 N/A — static 并引用完整源码证明。覆盖 gap 的搜索只能静态证明"不存在有效测试",永远不能把生产者、可达性、受影响人群、可信回归后果或用户影响标为 N/A。只要承载前提涉及运行时形态、可达性或影响,N/A 就被禁止。

特殊举证责任:格式/版本/状态兼容声明必须指出在受支持部署中写出所述状态的真实生产者;含全称否定的声明须穷举清单加执行探针;并发/顺序声明必须强制或观察到交错,时序散文不是证据;回归测试声明必须在 head 与回退生产 hunk 上各跑一次;若父前提被省略,所有依赖它的候选一并省略,不得把支撑命题保留为 Moderate 发现。

准入后还有 16 条逐项核验:亲自读源码精确行号、追踪完整代码路径(基类引用上的方法可能派发到子类覆写,如 PartitionDescriptor.clear() 与 OwnedMemoryPartitionDescriptor.clear())、检查 JNI/FFI 两侧、资源泄漏声明的每条分配必须有对应释放、Rust panic 声明要倒推可达性、数值溢出要按真实规模判断(QuestDB 处理数十亿到数万亿行、数千表、数千列——不是数十亿列或亿亿行)、性能声明要核实复杂度与量级、跨上下文发现要重读两层调用方、测试效力声明要用 git worktree(绝不用主工作树)在审查修订上跑绿、回退后跑红、"吞异常→静默错误/泄漏/状态损坏"声明要同时命名异常类型、确切抛出语句、该类型确实被特定 catch 捕获、且语句在调用方实参下可达(还须检查非抛出的兄弟形态:void 方法在早返回时静默释放参数)、验证合取而非各环节、准入后才推导修复并验证其编译且闭合窗口、最后做净用户影响判定。

净用户影响判定(3b.16(a))按顺序回答五点:Population(谁能到达它:每个用户、某命名特性的每个用户、特定查询/DDL/摄取形态、或仅运维路径——"原则上任何用户"不是人群;无受支持用户/运维人群能执行生产者则省略行为候选)、Delta vs base(同一执行触发器下该人群相对 merge base 观察到什么不同)、Magnitude and frequency(多大、多频繁:每行/每查询/每次重启/仅一次)、Offsets(下游什么在本 PR 前就恢复了:后续校验、重试、校验和、丢弃值的调用方、同 PR 别处加的守卫,以及流程级偏移:团队既定流程、合入/发布约定、CI 门、部署步骤;命名偏移或写 "none found, searched ")、Net(恰好一种:net-negative 才可准入;net-neutral 从 PR 发现中省略;net-positive 省略)。

随后把台账条目分类为:ADMITTED in-diff、ADMITTED out-of-diff-breakage、OMITTED pre-existing/not-attributed(base 行为相同或更差且本 PR 未暴露新路径)、OMITTED false、OMITTED unverified。枚举候选逐项准入——绝不抽样 N 个实例后发布未验证的余下部分;每个渲染条目都要有自己的生产者/触发器与证据。

Step 4:输出——只呈现被准入的发现

只呈现 ADMITTED 发现。被省略的候选、反驳、撤回、Agent 数量、候选数量、私有台账永远不出现在公开审查中。不先发布假设再撤回——先完成证伪。零发现是合法输出。唯一例外是 Adjacent findings(邻近问题) 小节:携带已证明的既存 bug 的问题草稿——不是针对本 PR 的发现,在所有门中零权重。

成比例原则:报告要能一次坐下处理完。普通规模 PR 若发现超过约七条,就重跑准入门,移除依赖、重复、未归因与低价值行文。审查深度由证据体现,不由报告长度。

每个发现——无论什么级别——都必须以三行一句话摘要开头,再写正文:

  • Problem:哪里错了。≤12 词。不含机制或修复。
  • Net impact:受支持人群与量级。≤12 词。无净回归的行为项被省略。
  • Evidence:决定性工件或静态证明,含被审查修订身份。

这三行必须从已完成的准入表单最后写出,绝不先凭直觉写。然后只给最小化的生产者→路径→症状追踪、base 对比与建议修复。格式示例:

Problem: Symbol column read twice per scanned row.
Net impact: ~2x column IO on every filtered scan.
Evidence: benchmark.sh output at abc123; base 8ms, head 16ms.

Problem: WAL segment leaks a file descriptor on the error path.
Net impact: Ingestion stalls after ~1k failed commits.
Evidence: WalLeakTest red at abc123, green at base def456.

严重级别分类(影响优先):严重级别是"用户失去什么"的函数,不是发现来自哪条清单的函数。按可达路径上最坏的用户可见后果分类。"用户"指 QuestDB 数据库用户或生产运维人员——跑查询、摄取数据或运维部署的人;不是开发者、CI 任务或发布流程。只影响团队的人群(构建变慢、本地环境坏了、别扭的合入)永远不会是 Critical——开发者体验问题至多是 Moderate,多数是 Minor。

Critical 检验——说出症状:只有当你能完成"因为这个,用户看到___"才成立,合法补全为:错误或缺失数据、崩溃/挂起/不可用(panic、死锁、活锁、无界循环、OOM、fd/线程/连接耗尽、可重复操作下无界增长的泄漏)、安全或 ACL 失败、损坏或误导的失败模式(无错失败、错误错误、无法行动的报错、异常被吞使失败看起来像成功、丢失/未记录故障)、兼容性破坏(磁盘格式、线协议、公共/SQL/JNI API、配置语义)、用户能感知的性能/IO 回归、或被准入的 Critical 覆盖 gap。每个补全都需要触发器:症状句必须命名用户/运维可运行的具体查询形态、摄取模式、API 调用、配置值或操作序列。

性能与 IO 的量级规则:成本只在用户可观察时才阻断。问两个问题:成本是否随数据扩展(每行/每值/每页/每分区/每扫描块),是否在用户等待或重复的路径上?Critical 要求陈述量级(乘数加被乘物,如"每扫描行多读一个 4KB 页""对分区做第二次完整遍历""O(n²) 于分区数")。无陈述量级的 Critical 性能发现是错归档。

配置分歧规则:"同一语句在配置 A 下被接受、配置 B 下被拒绝"本身就是发现(运维可在跨节点观察到的矛盾),按分歧本身后果分类,不继承更宽松配置可达的最坏情况的级别。

三类不算发现:合并机制(子模块 pin 位置、仓库间合并顺序、分支存在、标签等"如何落地"的性质)、同义反复("这个发现会出现在每个这种形状的 PR 上吗"——是则它描述的是工作流而非本次改动)、被覆盖的项目决策(项目自身工具明确允许的东西——CI 检查按设计通过、文档化例外、PR body 已点名的约定——除非有证据证明决策是错的)。加上第四类:上游子模块内容(Step 2.4 判定 UPSTREAM-SYNC 的子模块内任何东西,本 PR 未写、未审、也不能被要求修;唯一例外是本 diff 内调用点的集成缺陷,按该调用点自带症状与触发器提交)。

Moderate:被准入、可归因、有界或开发者可见的缺陷:具体变更行的规范违反、被证明的弱测试、缺失的内部路径覆盖、文档缺陷、有界的非数据路径成本。不可达的运行时理论、未变的残留加固机会、只支撑另一候选的命题不算 Moderate——省略。

Minor:外观问题:成员排序、命名、格式、注释措辞、import 顺序。

Adjacent findings(不阻断——作为 GitHub issue 提交):在 merge base 上已存在、在本审查访问过的代码(变更文件、调用点清单中的调用方、跨上下文暴露)里发现的 bug,本 PR 未引入、未破坏、未恶化。它们不是针对本 PR 的发现:永远不出现在 Critical/Moderate/Minor 下,永远不影响结论,永远不被提议为本 PR 的改动。与已发布发现同一证据标准;草稿只能来自达到 OMITTED pre-existing/not-attributed 且生产者、可达性、观察均被证明的候选。按可直接归档的 issue 草稿格式报告:Problem(≤12 词,兼作 issue 标题)、Net impact、Location(文件路径+行号)、Symptom(用户会观察到什么,或 "latent: no user-visible impact today" 并点名阻止它的守卫)、Reachability、Suggested fix、Severity if filed standalone。主动提议代开 issue,但未被要求就不归档任何东西。若某邻近问题严重到"不带它发布本 PR 真的不安全"(因为本 PR 把代码移上了该既存 bug 现在会触发的路径),那它就不是邻近问题:它是 out-of-diff-breakage,属于 Critical,且要明确陈述该论点。

Coverage map:只陈述测试门结果与被准入覆盖 gap 的数量。渲染被准入 gap 行时带记录的搜索与 failure link。不暴露被省略候选或私有 UNTESTED 行的计数。

Summary:结论恰好一种——approve(无未闭合 Critical 且测试门通过;Moderate/Minor 可保留并照批)、approve with comments(两门通过,你希望特定 Moderate 被处理但不阻断)、request changes(至少一个 Critical 未闭合或测试门失败)、needs discussion(需要评审者单独无法作出的产品/架构/兼容性决策)。正确性门(硬规则):存在任何被准入的 Critical 发现(含被准入的 Critical 覆盖 gap)时结论不能是 "approve"。定稿前按证据字段重跑准入审计:证伪、生产者、独立性(准入验证者未收到发现叙事/级别/修复/投票)、动态证据(竞态/顺序/重试/重启/文件系统/兼容性声明有执行工件与同触发器 base 结果)、依赖(删除父前提被省略的项)、严重级别(只在准入后分类)。测试门(硬规则):仅当存在被准入的 Critical 覆盖 gap 时失败;零测试改动、bug fix 标签或缺回归覆盖会触发 Step 2.6 分析但从不自动强制 request changes。报告还要:单行陈述 Step 2.4 子模块溯源结论(如 "questdb: OFF-DEFAULT — in scope; java-questdb-client: UPSTREAM-SYNC — out of scope")、只陈述被准入的 in-diff / out-of-diff-breakage 拆分(级别 0-1 描述受限的调用点分析而非暗示清白)、陈述严重级别分布、绝不报告 Agent/候选/被拒计数或撤回历史。

五、QuestDB 特有检查清单:从零 GC 到日志链

SKILL.md 用大量篇幅给出 QuestDB 专属审查清单,这些条目在通用代码审查之外定义了"QuestDB 标准"的具体内容。

正确性、并发与性能

  • 正确性:区分哨兵 NULL 与实际 NULL;SqlException 位置指向出错字符而非表达式起点;边界、off-by-one、错误操作符优先级;对每个变更符号列出其现在可出现但此前没有的 SQL 子句、异步上下文、错误路径、并行 worker 与持锁状态并逐一验证。
  • 并发:未同步共享可变状态、缺 volatile、不安全发布;可致死锁的锁顺序;跨线程数据结构线程安全。
  • 算法最优性(最高优先级):每个新循环/遍历给出时间复杂度并追问更优算法——O(n) 线性扫描可用 O(1) 哈希/直接索引是发现;O(n log n) 排序有 O(n) 替代是发现;多趟 vs 单趟(可融合则融合,除非每趟结构依赖前趟完整输出);冗余计算;数据结构契合度;不必要的拷贝与转换(String ↔ CharSequence、byte[] ↔ DirectByteCharSequence)。
  • 零 GC 与分配纪律:数据路径上哪怕每行一个 GC 分配也是发现;用 java.util.* 集合替代 io.questdb.std 中 QuestDB 自己的零 GC 集合是发现;热路径字符串创建/拼接(应使用 CharSink、StringSink 或直接 char[]);热路径捕获型 lambda(非捕获型被 JVM 缓存,安全);热路径自动装箱。
  • 向量化与原生加速:QuestDB 原生层可批量处理列数据时缺失 SIMD/向量化机会;QuestDB 已提供优化替代时用了低效算法。
  • 编译期路径:SQL 编译期 GC 分配可接受;但编译期算法低效仍是发现——随输入扩展的编译成本(O(n²) 于列/项数、每次调用重解析、每行重复工作)是 Critical;每次编译一次的有界固定成本是 Moderate。
  • 代码质量:坏味道、过度复杂方法、深嵌套、死代码;数据路径无第三方 Java 依赖。
  • QuestDB 编码规范:类成员按种类(静态 vs 实例)与可见性分组;布尔命名用 is.../has... 前缀;现代 Java 特性(enhanced switch、多行字符串、instanceof 模式变量)。这些在 CLAUDE.md 中有完全一致的表述,且强调 java-questdb-client 模块目标 Java 11 只能用传统特性。

日志链:QuestDB 独有的硬规则

QuestDB 日志使用 builder 模式(LOG.info().$("msg").$()),三条规则在 SKILL.md 中被标为必须检查:

  • 每条 LOG 链必须以 .$() 或 .I$() 结尾——缺失闭合会永远占住 ring buffer 槽位,导致其他日志生产线程在 nextBully() 中忙等,logging_0 消费线程也无法前进。
  • 注意链中误用 .put() 代替 .$()——.put() 返回 Utf16Sink 而非 LogRecord,会破坏链。
  • LOG 链内禁止可抛异常表达式(LOG.info().$(func()).$())——参数在取得 ring 槽之后求值,func() 抛异常会越过终结符泄漏槽位;必须先提升到局部变量再开始链(var a = func(); LOG.info().$(a).$();)。

CLAUDE.md 补充了一条相关约定:日志消息必须严格使用 ASCII 字符,QuestDB 日志基础设施不能可靠渲染非 ASCII(如长破折号、弯引号、Unicode 符号),所有 LOG.info()/LOG.error() 调用只用纯 ASCII 标点。

资源管理与 per-query 内存跟踪器

  • 资源管理:所有路径(尤其错误路径)正确关闭资源;适用处用 try-with-resources;原生内存正确释放。测试必须用 assertMemoryLeak() 包裹任何分配原生内存的内容——这一条也出现在 CLAUDE.md:所有测试用 assertMemoryLeak() 编写,资源泄漏是 QuestDB 痛点,要仔细考虑所有可能路径尤其错误路径。

  • Per-query memory tracker 集成(PR 新增/改动原生内存分配点时适用):QuestDB 通过 per-query MemoryTracker 限制单个有界工作负载(用户 SQL 查询、物化视图刷新、WAL apply 批次)可分配的原生内存。tracker 绑定在 SqlExecutionContext(getMemoryTracker() / setMemoryTracker(...)),穿进 tracker-aware 的 Unsafe.malloc/realloc/free/getNativeAllocator(tag, tracker) 重载(及 Rust QdbAllocator);null tracker 退化为全局 RSS 记账。决策规则是"tracker 只用于大型、可能无界的分配"——过度接线本身就是发现。

    应接线的:随数据或查询基数增长且无结构上限的分配——map/哈希表背衬、sort/tree/record chains、hash-join key(及 match-id)map、group-by 分配器与聚合函数状态、LATEST BY rowid 列表与 map、集合操作 map、编码与 top-K ORDER BY ... LIMIT N 排序缓冲、secondary/markout-horizon 交叉连接缓冲、window-join 与 horizon-join 聚合 map、窗口分区 map 与 RANGE-frame ring buffer、SAMPLE BY fill、parquet 解码缓冲——这些正是上限要抓的失控向量。无界站点传 null(或完全省略 tracker 重载)是覆盖 gap 候选。

    应仅留在全局计数器的:结构上有界、自封顶或进程/会话生命周期——page-frame 缓冲、JIT 缓冲、string_agg、固定大小堆(如单列 long top-K 堆)、ROWS-frame 窗口缓冲、table reader/writer 列、符号表、连接缓冲、内存映射页。接线这些反而是发现:每次 malloc/free 在 Java 与 Rust 路径各加两次原子计数更新而无保护收益,且 tracker-aware 池化类放弃跨查询背衬保留。

    逐站点核验:malloc 与匹配 free 用同一 tracker(不同步会使计数器失配并触发 live recordPerQueryMemAlloc 余额断言——追踪每条 free/close 路径含错误路径与 toTop()/clear()/cursor-close 复用);嵌套 SQL 继承外层 tracker(子查询、物化视图刷新内层 SELECT、WAL apply 内层 SQL 必须继承已绑定 tracker,新获取点只有在无外层 tracker 时才获取,否则双计);覆盖有测试(新接线的分配器需要 *MemoryTrackerTest 证明超限抛出 per-query OOM 消息、限内运行成功、getCursor() 到 close 的泄漏循环保持平衡)。

SQL 测试断言(builder API——严格、阻断)

这是 SKILL.md 中最"硬"的规则之一,与仓库测试基建直接对应。核心事实:QuestDB 已将 SQL 测试断言迁移到流畅的 AbstractCairoTest.assertQuery(query) builder——即 AbstractCairoTest.java 中的 protected QueryAssertion assertQuery(CharSequence query)(见其 javadoc 示例 "assertQuery("select * from x").returns(expected)"),builder 本体是独立的 QueryAssertion.java("Standalone fluent query-assertion builder",链式读作 query → options → expectation)。CLAUDE.md 也明确记载:旧的 assertSql(...)/TestUtils.assertSql(...) 查询结果辅助已被移除。

规则细节:

  • assertSql(...) 已删除——任何新增/改动的测试代码若用 assertSql(...)/TestUtils.assertSql(...) 断言查询结果是 Critical 发现(它甚至无法针对当前基类编译);必须用 builder:数据用 assertQuery(sql).returns(expected),可按需链 .timestamp(...)、.expectSize()、.noRandomAccess()、.sizeMayVary()、.ddl(...)、.mutateWith(...)、.withEngine(...)、.withContext(...);计划用 .assertsPlan(plan)/.assertsPlanContaining(...)/.assertsPlanNotContaining(...),或用 .withPlan(...)/.withPlanContaining(...)/.withPlanNotContaining(...) 并入数据断言。assertPlanNoLeakCheck(...)、getPlan(...)、assertPlanDoesNotContain(...) 与直接 TestUtils.assertSql(...) 同样标记。唯一合法存活的 assertSql 是 live-ServerMain 包装器 TestServerMain.assertSql(sql, expected)——运行服务器上下文专用,内部经 returnsOnce() 驱动 builder(单遍,因为 live 服务器状态在两次读取间会变)。
  • .returnsOnce(...) 是正确性坏味道——每个新增使用都要标记。它只跑单遍 cursor,故意跳过 .returns(...) 会做的第二次读取、calculateSize() 遍、可变列检查与工厂属性断言(supportsRandomAccess、expectSize)——这些跳过项能抓住真实 bug(toTop() 上 cursor 重置不正确、两次间 size() 不一致、recordAt() 返回错误值的随机访问记录)。只有查询输出在两次读取间确实不稳定才可用——如未播种的 rnd_* 投影、now()/sysdate()/systimestamp() 式时变输出、或本质非确定的行序。对确定性查询用 .returnsOnce(...) 是 Critical 发现,要求作者说明查询为何不稳定;"更简单"不是理由。
  • 反模式:assertMemoryLeak(() -> { ... }) 里只包一条 assertQuery(...)。builder 默认自带内存泄漏检查(内部包裹,除非设 .noLeakCheck())。当 lambda 里唯一有意义的语句就是一条 assertQuery(...) 链时,外层包裹冗余且几乎总逼着 builder 用 .noLeakCheck()——关掉 builder 的泄漏检查换成手写的,事与愿违。正确做法:去掉 assertMemoryLeak 包裹与 .noLeakCheck(),让 builder 自检。只有 lambda 真的含多条语句(DDL + insert + 若干断言)需共享一个泄漏检查作用域时,包裹才合法。

这些规则在 QueryAssertion.java 中逐方法可查:returns(CharSequence)(L534)、returns(CharSequence, CharSequence)(L545)、returnsOnce(CharSequence)(L133)、assertsPlan(...)(L192)、assertsPlanContaining(...)(L212)、ddl(...)(L272/L284)、expectSize()(L315/L324)、mutateWith(...)(L457/L469)、noRandomAccess()(L512)、timestamp(CharSequence)(L627)、withContext(...)(L677)、withEngine(...)(L686)、withPlan(...)(L697)——均可作为读者深入验证的锚点。

权限钩子、SQL 约定与测试审查

  • 权限钩子(PR 新增 ALTER 操作或其他变更表状态的 SQL 时):新 ALTER TABLE 操作或任何变更表状态的语句需要在执行路径上有 SecurityContext.authorize*() 调用——引用调用点(ALTER 的 AlterOperation.apply() 分发,其余为 op 或 compiler 类)。缺失是可证明的发现而非推测:证据是"找到新操作的搜索"加"找不到覆盖它的 authorize* 调用的搜索"。变更表状态的操作无安全上下文可拒绝对照严重级别表即是权限绕过(Critical)。新 authorize*() 方法必须在所有抽象处实现:AllowAllSecurityContext 与 ReadOnlySecurityContext(DenyAllSecurityContext 继承后者),加编译器未捕获的测试 SecurityContext 实现。若 PR 用宽松的 default 体添加方法,每个不覆写它的实现(含本 checkout 看不见的企业实现)都静默授权。企业接线(Permission.java 注册、PermissionParser GRANT/REVOKE 解析、EntSecurityContextBase/AdminSecurityContext、replica deniedOnReplica() 门控)在单独仓库,本 checkout 无法验证——作为企业后续事项注明一次即可,不当作发现、不影响结论。
  • SQL 约定:关键字大写;expr::TYPE 强转优先于 CAST();5 位以上数字用下划线(1_000_000);复杂查询用多行字符串;无 DELETE 语句(建议 DROP PARTITION 或软删除);测试用 assertQuery(...) builder 做 SQL 断言、execute() 做 DDL;多行用单条 INSERT。
  • 测试审查:覆盖 gap 按影响与成比例评估(缺测试本身不阻断);执行模式维度(WAL vs 非 WAL 表、O3 乱序写 vs append-only、JIT vs 解释执行过滤器、并行 vs 单线程、分区 vs 非分区表——只测一种模式的 SQL 引擎改动在其余模式是覆盖 gap,要命名未测模式);模糊覆盖(parser、编解码器、摄取协议、O3/WAL 合并改动要在测试树搜 rg -l Fuzz,存在但未扩展或未声明运行则加 UNTESTED 行);跨上下文覆盖;错误路径覆盖;NULL 测试;边界条件(空表、空分区、单行表、最大值输入、零长度字符串);并发测试;资源泄漏测试(分配原生内存必须 assertMemoryLeak());测试质量与回归测试。
  • 测试代码质量:无空断言(每个断言必须能失败——assertTrue(true)、assertFalse(false)、assertEquals(x, x)、字面量对字面量、无断言且无 expected=/assertThrows 的 @Test 体);反射是最后手段(setAccessible(true)、getDeclaredField/getDeclaredMethod、Field.set、Class.forName 在有公共 API/既有辅助/构造器可达时标记并命名非反射路径);先复用再重造(搜索既有辅助/基类/fixture,重复的 setup/assert 块是发现并命名辅助);无 javadoc 膨胀(@Test 方法不要多段 javadoc、不要复述测试名的 javadoc、不要堆叠 javadoc;意图放进精确测试名加至多一行注释);测试适用标准(零 GC 与 io.questdb.std 优先规则不适用于测试——不要在那里标记 java.util 集合或分配;成员排序、is/has 命名、SQL 风格适用);无调试残留(System.out.println、注释掉的代码、无票据引用的 @Ignore)。

TODO/FIXME 与提交消息

扫描 diff 中的 TODO、FIXME、HACK、XXX、WORKAROUND:是移动/重排的既存注释还是本次新引入?新引入的——代表应阻断合入的未完成工作还是可接受的已知限制?引用了票据/issue 编号的要验证引用存在。提交消息规范:纯英文标题(无 Conventional Commits 前缀)、50 字符内;完整长文 body、72 字符折行;主动语态、点明动作主体——与 CLAUDE.md 的提交规范一致(标题不含前缀、含完整长描述、主动语态并点名主体,如 "The ring queue passes the factory to the exporter" 而非被动式)。

Store-and-forward 与连接池启动不变量(QWP client 契约)

当 diff 触及 QWP 入口路径(升级/角色门控、就地降级/生命周期切换、角色变更时的连接处理)、复制故障转移、携带 client(java-questdb-client)或入口改动的 questdb 子模块升级、或驱动 producer 穿过故障转移/切换窗口的测试时应用。这是 client 的 store-and-forward 保证,违反即 Critical 发现。

  • Drainer(稳态):连接池运行后,异步 drainer 线程把缓冲的 SF 数据送往服务器。它绝不能把服务器/传输错误传回 client(Sender producer 调用、flush()、池化句柄)——唯一允许暴露给调用方的是 SF 空间不足。任何其他失败类别(connect-refused、DNS、不可达/黑洞、TLS/证书、认证、角色拒绝、升级/协议超时、reset)从 drainer 逃逸到 producer 或 borrow 调用都标记。主重连必须完全封在 drainer 线程内且无时间限制——没有 reconnect_max_duration_millis 式预算、无截止时间、无 "N ms 后放弃并锁存 terminal"。有界重连循环、deadlineNanos/while (now < deadline)、或运行中 drainer 重连路径可达的 terminal SenderError 都是 Critical(丢弃了 store-and-forward 承诺保持存活的 producer)。drainer 必须以指数退避重试并优雅处理每种连接失败类别,不退硬失败;每次尝试的退避可设上限,但重试循环本身必须无界。有界总重试时长或尝试次数上限都标记。
  • 受制裁的 terminal(仅孤儿槽 drainer):BackgroundDrainer 可在设计上终端的条件上隔离槽位(.failed 哨兵、人工介入):认证失败、非 421 升级拒绝、真正集群级持久确认能力缺口耗尽文档化 settle 预算(连续 16 次能力缺口扫描,或以该 episode 首次能力缺口错误锚定的墙钟预算,先到者为准)。这些不违反上述无预算规则。settle 预算只适用于连续能力缺口尝试:瞬态类别(角色拒绝、传输错误)绝不能累计或烧掉其墙钟——瞬态消耗终端预算(共享尝试计数器、条目锚定截止时间)是本清单的 Critical 违反。
  • 流中服务器 NACK(无丢弃策略):NACK 策略必须镜像连接时分层的逻辑。瞬态集群状态可产生的拒绝类别(WRITE_ERROR、INTERNAL_ERROR、UNKNOWN——及任何未来状态字节)是 RETRIABLE:回收线路并从 ackedFsn+1 重放。绝不丢批、绝不一见即锁存 terminal/隔离槽位。只有字节级一致重放下确定性的拒绝(可写节点上的 SCHEMA_MISMATCH、PARSE_ERROR、SECURITY_ERROR)可走 TERMINAL。client 把 ack 水位推进过 NACK 帧就是在静默丢数据——Critical。被反复拒绝且无 ack 进展的帧必须经 poison-frame 检测器升级(同一头部 FSN 上有界连续 strike),不通过 WS 关闭码列表——关闭码不携带策略语义。UNKNOWN 必须 fail OPEN(重试)而非 closed(terminal):新版本服务器的状态字节应降级为重试,而不是死 sender。
  • 连接池启动——两种模式:lazy_connect=true 时 build() 必须在无服务器时也成功,producer Sender 立即可用(写经 SF 缓冲),服务器起来后读侧也必须连接并读取(读被延迟而非禁用)。lazy_connect=false(默认)时 build()/初始连接必须把连接问题暴露给调用方——DNS 错误、connect-refused/不可达、TLS/证书、认证/授权、连接/升级超时都必须作为启动时抛出的异常浮现,不被吞。两种模式边界相同:连接错误只在初始化期间是调用方的问题;一旦 client 连接并越过初始化,运行中的 drainer 回归稳态契约——绝暴露传输问题、绝设重连时间预算、绝在瞬态中断时硬失败。
  • 服务端与测试应用(本仓库):服务端不得依赖 producer 可见的角色错误:就地降级关闭 QWP 入口连接(不对 SF sender 逐写发 SECURITY_ERROR)。重新引入逐写角色错误的服务器改动破坏上述封闭契约。用 QWP producer 可见角色错误作为 REPLICA 写门证据的测试要标记——封闭契约下 producer 按设计静默;写门证据应放在 pg-wire 探针、settled replica 的冻结提交计数与提升后 SF drain(持久确认等待屏障 + 稠密 oracle)上。通过 SF sender 生产的行的稠密/计数 oracle 必须考虑至少一次重放:扰动前持久确认(await)种子行,或用 DEDUP 表——否则 oracle 会把重放重复报告为数据损坏。

模糊覆盖与测试执行模式

对 parser、编码器/解码器、摄取协议、O3/WAL 合并改动,用 rg -l Fuzz 搜测试树中覆盖变更面的既有模糊测试;若存在却既未扩展也未声明对其运行,加 UNTESTED Step 2.6 行,按常规成比例与准入门分类发布。

六、技能如何落到仓库实处:证据路径一览

SKILL.md 并非空中楼阁,其规则在仓库中都有可验证的实现锚点:

  • 审查对象与工程文化:CLAUDE.md 全文是"QuestDB 编码标准"的权威来源,技能中 Step 2 的标题/描述/标签核查、代码质量清单、SQL 约定、提交消息规范直接引用它;其"PR 是 squash-merge、捆绑相关修复、~20 PR/天、CI 约 40 分钟"等流水线现实解释了为何技能要求审查成比例、不滥用阻断。
  • SQL 测试断言硬规则:AbstractCairoTest.java 提供 assertQuery(CharSequence) 与 assertMemoryLeak(...) 系列方法;QueryAssertion.java 实现完整 fluent builder,其类 javadoc 明确声明不依赖测试基类、returns(...) 执行严格更强的断言电池(第二次 cursor 遍、calculateSize() 交叉核对、可变列检查、工厂属性断言),与技能对 .returnsOnce(...) 的禁令互为表里。
  • 测试辅助工具:TestUtils.java 提供 assertMemoryLeak 等核心测试工具(技能中 2.5e 清单、Agent 13 的"复用辅助"检查都指向它)。
  • 零 GC 集合:技能反复要求用 io.questdb.std 替代 java.util.*,仓库中 ObjList.java 等自定义集合即为该规范的产物;CLAUDE.md 明确要求用 ObjList<T> 替代 T[] 对象数组并配合 Misc.freeObjList() 做资源清理。
  • 日志链规则:QuestDB 日志采用 builder 模式(LOG.info().$("msg").$()),技能中"未闭合 LOG 链占住 ring buffer 槽位"的机制描述对应 io.questdb.log 包(如 LogRecordUtf8Sink.java)的实现约束。
  • Rust 安全:技能对 Rust panic 的零容忍(JNI/FFI 中 panic 会终止整个 JVM)与 CLAUDE.md 的 Rust 指引一致:绝不对文件内容或外部输入派生的数据用 unwrap()/expect(),用 Result/Option 加 ? 传播;Rust 代码位于 core/rust/qdbr/,须通过 cargo fmt、cargo check --all-targets、cargo clippy --all-targets(零警告)、cargo test --lib 四项检查。

七、总结:这套技能教给审查者的三件事

第一,证据高于叙事。SKILL.md 反复出现的主题是:发现必须经历"发现 → 独立证伪 → 证明 → 准入"的状态机,任何未经证伪尝试、无生产者、无 base 对比、无工件的命题都不能进入报告;"无法证伪"不是证据,不确定性不能被提升为严重级别。第二,严重级别是用户后果的函数。Critical 必须能说出"用户做 X → 看到 Y"的症状句与触发器,性能发现必须陈述量级(乘数或被乘物),只影响开发者的成本至多是 Moderate。第三,审查与 QuestDB 的工程现实严格对齐:零 GC 数据路径、io.questdb.std 集合、闭合的日志链、per-query 内存跟踪器、builder 式 SQL 断言、Java 断言开启运行——技能把仓库 CLAUDE.md 中的编码规范、QueryAssertion.java 中的测试基建与 Agent 审查流程焊成一个整体。

对希望贡献 QuestDB 或构建同类"阻断式代码审查"流程的开发者,SKILL.md 是一份可复用的方法论模板:从 $BASE 的确定、子模块溯源、变更面映射、覆盖图,到 14 个角色的并行发现、独立证伪与三级严重级别输出,每一步都强调"可以被证据支持"而非"看起来合理"。审查者的最终目标不是堆砌发现,而是在证据充分时干脆地给出 approve——正如技能原文所说,"零发现是正确改动的预期结果"。

登录后查看全文
questdb