qt-cpp-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Qt Code Review

Qt6 C++代码审查

A structured, read-only code review skill for Qt6 C++ code that combines deterministic linting with parallel agent-driven deep analysis across six focused domains.

这是一个针对Qt6 C++代码的结构化、只读代码审查技能，结合了确定性代码检查与并行Agent驱动的深度分析，覆盖六个重点领域。

When to use this skill

使用场景

When the user mentions review-related tasks: "review", "check", "audit", "look over", "code review", "sanity check"
Suggest running this skill before committing code
When the user asks to validate Qt6 C++ code quality

当用户提及与审查相关的任务时："review"、"check"、"audit"、"look over"、"代码审查"、"合理性检查"
建议在提交代码前运行此技能
当用户要求验证Qt6 C++代码质量时

Arguments

参数

```
/qt-cpp-review
```
— review using universal Qt6 C++ rules only
```
/qt-cpp-review framework
```
— also apply Qt framework/module development rules (BC, exports, d-pointers, qdoc, QML versioning)

```
/qt-cpp-review
```
— 仅使用通用Qt6 C++规则进行审查
```
/qt-cpp-review framework
```
— 同时应用Qt框架/模块开发规则（BC、导出、d指针、qdoc、QML版本控制）

Framework mode detection

框架模式检测

$ARGUMENTS

contains "framework", enable framework mode.

If the argument is not passed, auto-detect by scanning the first few files in scope for framework signals. If two or more of the following are found, suggest to the user: "This looks like Qt framework/module code. Run

/qt-cpp-review framework

to also apply framework-specific rules (BC, exports, qdoc, QML versioning)?"

Framework signals (any two = likely framework code):

```
QT_BEGIN_NAMESPACE
```
/
```
QT_END_NAMESPACE
```

Q_CORE_EXPORT

Q_GUI_EXPORT

Q_WIDGETS_EXPORT

, or any

Q_*_EXPORT

macro

```
#include <QtModule/private/*_p.h>
```
(private headers)
```
Q_DECLARE_PRIVATE
```
,
```
Q_D()
```
,
```
Q_Q()
```
```
qt_internal_add_module
```
or
```
qt_add_module
```
in CMakeLists.txt
```
sync.profile
```
or
```
.qmake.conf
```
in the repository root

Do not auto-enable framework mode — only suggest it. Let the user confirm.

When framework mode is enabled:

Pass
```
--framework
```
to the linter (if supported)
Load
```
references/qt-framework-checklist.md
```
alongside the universal checklist
Include framework rules in each agent's mission context

如果

$ARGUMENTS

包含"framework"，则启用框架模式。

如果未传入该参数，则通过扫描范围内的前几个文件来自动检测框架特征。如果发现以下两个或更多特征，向用户建议： "这看起来像是Qt框架/模块代码。运行

/qt-cpp-review framework

以同时应用框架特定规则（BC、导出、qdoc、QML版本控制）？"

框架特征（任意两个=大概率是框架代码）：

```
QT_BEGIN_NAMESPACE
```
/
```
QT_END_NAMESPACE
```

Q_CORE_EXPORT

Q_GUI_EXPORT

Q_WIDGETS_EXPORT

, 或任何

Q_*_EXPORT

宏

```
#include <QtModule/private/*_p.h>
```
（私有头文件）
```
Q_DECLARE_PRIVATE
```
,
```
Q_D()
```
,
```
Q_Q()
```
CMakeLists.txt中的
```
qt_internal_add_module
```
或
```
qt_add_module
```
仓库根目录下的
```
sync.profile
```
或
```
.qmake.conf
```

请勿自动启用框架模式——仅提供建议，由用户确认。

启用框架模式时：

向代码检查工具传递
```
--framework
```
参数（如果支持）
加载
```
references/qt-framework-checklist.md
```
与通用检查清单一起使用
在每个Agent的任务上下文中包含框架规则

Scope detection

范围检测

Detect the user's intended scope from their language:

从用户的表述中检测其预期的审查范围：

Diff/commit scope (narrow)

差异/提交范围（窄范围）

Triggered by language like: "this commit", "these changes", "the diff", "what I changed", "my changes", "staged changes", "outstanding changes", "before I commit"

Action: Run

git diff

(unstaged) and

git diff --cached

(staged) to obtain the changeset. If the user says "this commit", use

git diff HEAD~1..HEAD

. Review only the changed lines plus sufficient surrounding context (±50 lines) for understanding. Only report issues found in the changed lines — do not report issues in unchanged surrounding context.

由以下表述触发："本次提交"、"这些更改"、"差异"、"我修改的内容"、"我的更改"、"暂存的更改"、"未提交的更改"、"提交前"

操作：运行

git diff

（未暂存）和

git diff --cached

（已暂存）获取变更集。如果用户说"本次提交"，则使用

git diff HEAD~1..HEAD

。仅审查变更行及足够的上下文（±50行）以理解代码。仅报告变更行中发现的问题——不报告未变更上下文中的问题。

Codebase scope (wide)

代码库范围（宽范围）

Triggered by language like: "review the codebase", "audit the project", "check the repository", "review src/", or when a specific file/directory path is given without commit language.

Action: Glob for

*.cpp

*.h

*.hpp

files in the specified scope. Review all matched files.

由以下表述触发："审查代码库"、"审核项目"、"检查仓库"、"审查src/"，或当用户给出特定文件/目录路径但未提及提交相关表述时

操作：在指定范围内匹配

*.cpp

*.h

*.hpp

文件。审查所有匹配的文件。

Execution order

执行顺序

The review proceeds in three phases. Never skip a phase.

审查分为三个阶段。绝不能跳过任何阶段。

Phase 1: Deterministic linting (scripts)

阶段1：确定性代码检查（脚本）

Run the unified Python linter against the target files. Requires Python 3.6+ (no external dependencies). If Python is not available, warn the user and skip to Phase 2.

bash

python3 references/lint-scripts/qt_review_lint.py <files...>

针对目标文件运行统一的Python代码检查工具。需要Python 3.6+（无外部依赖）。如果Python不可用，向用户发出警告并跳至阶段2。

bash

python3 references/lint-scripts/qt_review_lint.py <files...>

If python3 is not found, fall back to:

如果找不到python3，回退到:

python references/lint-scripts/qt_review_lint.py <files...>


This single-pass scanner encodes all mechanically-checkable rules
from the Qt review guidelines. It reads each file once and
evaluates all rules per line. Output is deterministic and
repeatable. The linter is authoritative — do not second-guess
its output.

Collect all output before proceeding to Phase 2.

**Rule categories** (60+ checks):
- **INC** (Includes) — ordering, qglobal.h, qNN duplication
- **DEP** (Deprecated) — obsolete Qt/std class usage
- **PAT** (Patterns) — anti-patterns (min/max, std::optional,
  NRVO, COW detach, etc.)
- **MDL** (Model) — QAbstractItemModel contract (begin/end
  balance, dataChanged roles, flags, default: in data())
- **ERR** (Error Handling) — QFile::open, QJsonDocument::isNull,
  QNetworkReply::error, SSL, timeouts, arg() mismatch
- **LCY** (Lifecycle) — deleteLater, Q_ASSERT side effects,
  null guards, unbounded containers, qDeleteAll depth
- **API** (Naming) — get-prefix, enum hygiene, QList<QString>
- **HDR/TMO/CND/VAL/TRN** — headers, timeouts, conditionals,
  value classes, ternary operator

python references/lint-scripts/qt_review_lint.py <files...>


这个单遍扫描工具编码了Qt审查指南中所有可机械检查的规则。它读取每个文件一次，并逐行评估所有规则。输出具有确定性和可重复性。该检查工具具有权威性——不要质疑其输出。

收集所有输出后再进入阶段2。

**规则类别**（60+项检查）：
- **INC**（头文件包含）——顺序、qglobal.h、qNN重复包含
- **DEP**（已废弃）——过时的Qt/std类使用
- **PAT**（模式）——反模式（min/max、std::optional、NRVO、COW分离等）
- **MDL**（模型）——QAbstractItemModel契约（begin/end平衡、dataChanged角色、flags、data()中的默认值）
- **ERR**（错误处理）——QFile::open、QJsonDocument::isNull、QNetworkReply::error、SSL、超时、arg()不匹配
- **LCY**（生命周期）——deleteLater、Q_ASSERT副作用、空指针防护、无界容器、qDeleteAll深度
- **API**（命名）——get前缀、枚举规范、QList<QString>
- **HDR/TMO/CND/VAL/TRN**——头文件、超时、条件语句、值类、三元运算符

Phase 2: Agent-driven deep analysis (6 parallel agents)

阶段2：Agent驱动的深度分析（6个并行Agent）

Launch six focused review agents in parallel. Name each agent descriptively when launching (e.g. "Agent 1: Model Contracts") to provide progress visibility. Each agent has a tight scope and a specific checklist. Agents are READ-ONLY — they must never edit or write files.

Tool-agnostic agent contract: Each agent described below is a self-contained review mission. In Claude Code, launch them as general-purpose subagents. In other tools, implement each as whatever subprocess, prompt chain, or analysis pass the tool supports. The key requirement is that each agent:

Has read access to all source files in scope
Can search/grep the codebase to trace symbols
Reports findings in the structured format below
Applies confidence thresholds: >80 = confirmed finding, 60–79 = investigation target (max 10 total across all agents), <60 = suppress
Does NOT duplicate findings from Phase 1 lint output (pass lint output as context to each agent)

See Agent missions below for the six agents.

并行启动六个专注的审查Agent。启动时为每个Agent指定描述性名称（例如"Agent 1: 模型契约"）以提供进度可见性。每个Agent的范围严格，并有特定的检查清单。Agent为只读——绝不能编辑或写入文件。

与工具无关的Agent契约：下面描述的每个Agent都是一个独立的审查任务。在Claude Code中，将它们作为通用子Agent启动。在其他工具中，根据工具支持的方式将每个Agent实现为子进程、提示链或分析过程。核心要求是每个Agent：

有权限读取范围内的所有源文件
可以搜索/grep代码库以追踪符号
以下面的结构化格式报告发现的问题
应用置信度阈值：>80 = 已确认的问题，60–79 = 待调查目标（所有Agent最多总计10个），<60 = 忽略
不重复阶段1代码检查输出中的发现（将代码检查输出作为上下文传递给每个Agent）

请参阅下面的Agent任务了解六个Agent的具体内容。

Phase 3: Consolidation and reporting

阶段3：合并与报告

Merge lint script output and all agent findings. Deduplicate (same file+line+issue = one finding). Apply confidence scoring. Format the final report using the output format below.

合并代码检查脚本输出和所有Agent的发现。去重（相同文件+行+问题=一个发现）。应用置信度评分。使用下面的输出格式格式化最终报告。

Agent missions

Agent任务

Launch all six agents in parallel. Pass each agent:

The list of files in scope
The Phase 1 lint output (so they skip already-flagged issues)
Their specific mission below

Each agent should read all files in scope, then focus on its assigned categories.

并行启动所有六个Agent。向每个Agent传递：

范围内的文件列表
阶段1的代码检查输出（以便它们跳过已标记的问题）
下面的特定任务

每个Agent应读取范围内的所有文件，然后专注于其分配的类别。

Agent 1: Model Contracts

Agent 1: 模型契约

Scope: QAbstractItemModel signal protocol, role system, index validity, proxy model correctness.

Check for:

```
beginInsertRows
```
/
```
endInsertRows
```
balance — every structural model change (add/remove/move) must use the correct begin/end pairs.
```
layoutChanged
```
is NOT a substitute for insert/remove.
```
roleNames()
```
returning roles that
```
data()
```
does not handle (missing switch cases, fall-through to default)
```
dataChanged
```
emitted with empty roles vector (forces full refresh instead of targeted update)
```
beginRemoveRows
```
called with
```
first > last
```
(edge case when container is empty — QAIM contract violation)
```
flags()
```
returning inappropriate flags (e.g.
```
ItemIsEditable
```
for non-editable items)
```
setData()
```
returning true without emitting
```
dataChanged
```
Proxy models accessing source model internals instead of going through
```
data()
```
/
```
index()
```
API
Filter/proxy models using source-model indices to index into filtered containers (wrong index space)

References:

references/qt-review-checklist.md

§ Model Contracts

范围：QAbstractItemModel信号协议、角色系统、索引有效性、代理模型正确性。

检查内容：

```
beginInsertRows
```
/
```
endInsertRows
```
平衡——每个结构性模型变更（添加/删除/移动）必须使用正确的begin/end对。
```
layoutChanged
```
不能替代insert/remove。
```
roleNames()
```
返回的角色未被
```
data()
```
处理（缺少switch分支、fall-through到default）
发出
```
dataChanged
```
时使用空角色向量（强制全量刷新而非定向更新）
调用
```
beginRemoveRows
```
时
```
first > last
```
（容器为空时的边缘情况——违反QAIM契约）
```
flags()
```
返回不恰当的标志（例如非可编辑项返回
```
ItemIsEditable
```
）
```
setData()
```
返回true但未发出
```
dataChanged
```
代理模型访问源模型内部而非通过
```
data()
```
/
```
index()
```
API
过滤/代理模型使用源模型索引来索引过滤后的容器（错误的索引空间）

参考：

references/qt-review-checklist.md

§ 模型契约

Agent 2: Ownership & Lifecycle

Agent 2: 所有权与生命周期

Scope: Memory ownership, parent-child, resource cleanup, Rule of Five, RAII correctness.

Check for:

Structs/classes with raw pointers where
```
new
```
is visible and no corresponding
```
delete
```
/
```
deleteLater
```
/smart-pointer wrapping exists (Rule of Five violation)
Missing
```
deleteLater()
```
on QNetworkReply in finished handlers
```
Q_ASSERT
```
wrapping side-effectful expressions (compiled out in release builds — the side effect disappears)
```
Q_ASSERT
```
as the sole null guard (crashes in release)
Polymorphic QObject subclasses missing
```
Q_DISABLE_COPY_MOVE
```
Polymorphic classes missing virtual destructor
QTimer/QObject created with
```
new
```
but no parent and no other lifecycle management (scope, smart pointer, explicit delete)
```
QObject::connect()
```
called with potentially null sender/receiver outside a null guard (runtime warning)
```
m_recentlyAccessed
```
-style tracking lists that maintain pointers to objects that may be deleted elsewhere (dangling)
Unbounded container growth (append without cap or trim)
Destructor not cleaning up owned children recursively
Abstract interfaces with no implementations beyond one class (YAGNI violation — codebase scope only)

References:

references/qt-review-checklist.md

§ Ownership & Lifecycle, § Polymorphic Classes, § RAII Classes

范围：内存所有权、父子关系、资源清理、五法则、RAII正确性。

检查内容：

结构体/类包含原始指针，且可见
```
new
```
但无对应的
```
delete
```
/
```
deleteLater
```
/智能指针包装（违反五法则）
完成处理程序中缺少对QNetworkReply的
```
deleteLater()
```
调用
```
Q_ASSERT
```
包装有副作用的表达式（在发布版本中会被编译掉——副作用消失）
将
```
Q_ASSERT
```
作为唯一的空指针防护（在发布版本中会崩溃）
多态QObject子类缺少
```
Q_DISABLE_COPY_MOVE
```
多态类缺少虚析构函数
使用
```
new
```
创建的QTimer/QObject但无父对象且无其他生命周期管理（作用域、智能指针、显式delete）
在空指针防护外调用
```
QObject::connect()
```
，sender/receiver可能为空（运行时警告）
```
m_recentlyAccessed
```
类的跟踪列表维护指向可能在别处被删除的对象的指针（悬空指针）
无界容器增长（仅追加无限制或修剪）
析构函数未递归清理所有子对象
抽象接口除一个类外无其他实现（违反YAGNI原则——仅代码库范围适用）

参考：

references/qt-review-checklist.md

§ 所有权与生命周期、§ 多态类、§ RAII类

Agent 3: Thread Safety

Agent 3: 线程安全

Scope: Cross-thread QObject access, mutex consistency, signal emission from worker threads.

Check for:

QObject member variables written from
```
QtConcurrent::run()
```
or
```
QThread
```
worker without synchronization (mutex, atomic, queued connection, or other thread-safe primitive)
Signals emitted from worker threads connected with
```
Qt::DirectConnection
```
(or explicit non-queued connections) to main-thread receivers
Model mutations (
```
addNote
```
,
```
removeRows
```
, etc.) from background threads
Shared containers (
```
QList
```
,
```
QHash
```
) modified from multiple threads without consistent synchronization
Non-atomic increment/decrement of shared counters (
```
m_operationCount++
```
from multiple threads)
QTimer or other QObject operations from non-owner thread

References:

references/qt-review-checklist.md

§ Thread Safety

范围：跨线程QObject访问、互斥一致性、工作线程信号发射。

检查内容：

QObject成员变量在
```
QtConcurrent::run()
```
或
```
QThread
```
工作线程中被写入但无同步（互斥锁、原子操作、队列连接或其他线程安全原语）
工作线程发出的信号使用
```
Qt::DirectConnection
```
（或显式非队列连接）连接到主线程接收器
从后台线程进行模型变更（
```
addNote
```
,
```
removeRows
```
等）
共享容器（
```
QList
```
,
```
QHash
```
）在多线程中被修改但无一致同步
共享计数器的非原子增减（多线程中的
```
m_operationCount++
```
）
从非所有者线程操作QTimer或其他QObject

参考：

references/qt-review-checklist.md

§ 线程安全

Agent 4: API, Naming & C++ Correctness

Agent 4: API、命名与C++正确性

Scope: Qt naming conventions, const-correctness, move semantics, enum hygiene, noexcept correctness.

Check for:

```
get
```
-prefix on mere getters (Qt reserves
```
get
```
for user interaction or out-parameter decomposition)
Non-const getter methods (especially Q_PROPERTY READ accessors — UB via meta-object system)
Missing
```
std::forward<T>()
```
on forwarding/universal references
```
return std::move(localVar)
```
preventing NRVO
```
const
```
local variable preventing implicit move on return (e.g.
```
const QJsonDocument doc(...); return doc;
```
forces copy)
```
const
```
method returning mutable pointer through raw pointer indirection (
```
findById() const
```
returning
```
T*
```
lets callers mutate via a const accessor — const doesn't propagate through raw pointers)
```
noexcept
```
on functions containing
```
Q_ASSERT
```
(incompatible — Q_ASSERT may throw for testing, noexcept terminates)
Unscoped enums without explicit underlying type
Missing trailing comma on last enumerator
```
switch
```
over enum with
```
default:
```
label (suppresses -Wswitch)
```
QList<QString>
```
instead of
```
QStringList
```
Missing
```
const
```
on methods that don't modify state
Case-sensitive string comparison for user-facing sort
Duplicated validation logic across classes
```
const QMetaObject::Connection
```
preventing handle cleanup

References:

references/qt-review-checklist.md

§ API & Naming, § Enums, § Methods, § Move Semantics, § Operators

范围：Qt命名规范、const正确性、移动语义、枚举规范、noexcept正确性。

检查内容：

普通getter使用
```
get
```
前缀（Qt保留
```
get
```
用于用户交互或输出参数分解）
非const getter方法（尤其是Q_PROPERTY READ访问器——元对象系统导致未定义行为）
转发/通用引用缺少
```
std::forward<T>()
```
```
return std::move(localVar)
```
阻止NRVO
const局部变量阻止返回时的隐式移动（例如
```
const QJsonDocument doc(...); return doc;
```
强制复制）
const方法通过原始指针间接返回可变指针（
```
findById() const
```
返回
```
T*
```
允许调用者通过const访问器修改——const不会通过原始指针传播）
包含
```
Q_ASSERT
```
的函数使用
```
noexcept
```
（不兼容——Q_ASSERT在测试中可能抛出，noexcept会终止程序）
未指定底层类型的未作用域枚举
最后一个枚举值缺少尾随逗号
枚举的
```
switch
```
语句带有
```
default:
```
标签（抑制-Wswitch警告）
使用
```
QList<QString>
```
而非
```
QStringList
```
不修改状态的方法缺少
```
const
```
用户可见排序使用区分大小写的字符串比较
跨类重复的验证逻辑
```
const QMetaObject::Connection
```
阻止句柄清理

参考：

references/qt-review-checklist.md

§ API与命名、§ 枚举、§ 方法、§ 移动语义、§ 运算符

Agent 5: Error Handling & Validation

Agent 5: 错误处理与验证

Scope: Missing error checks, input validation, security.

Check for:

```
QFile::open()
```
return value ignored

QJsonDocument::fromJson()

result not checked for

isNull()

isObject()

before use

```
QNetworkReply::error()
```
not checked before
```
readAll()
```
XML writer
```
hasError()
```
not checked after writing
Hardcoded
```
http://
```
instead of
```
https://
```
in URLs
No SSL error handling (
```
QNetworkAccessManager::sslErrors
```
)
No timeout on network requests (
```
setTransferTimeout
```
)
Negative values accepted where only positive are valid (e.g. timer intervals, font sizes)
No schema/version validation on imported data
No input length validation on imported/downloaded data (unbounded strings from untrusted sources)
```
QString::arg()
```
with wrong placeholder count
```
saveToFile()
```
returning true regardless of I/O errors
Inconsistent error reporting patterns across methods

References:

references/qt-review-checklist.md

§ Error Handling & Validation

范围：缺少错误检查、输入验证、安全性。

检查内容：

忽略
```
QFile::open()
```
的返回值

使用

QJsonDocument::fromJson()

的结果前未检查

isNull()

isObject()

调用
```
readAll()
```
前未检查
```
QNetworkReply::error()
```
写入后未检查XML写入器的
```
hasError()
```
URL中硬编码
```
http://
```
而非
```
https://
```
无SSL错误处理（
```
QNetworkAccessManager::sslErrors
```
）
网络请求无超时设置（
```
setTransferTimeout
```
）
接受仅允许正值的负数值（例如定时器间隔、字体大小）
导入数据无模式/版本验证
导入/下载数据无输入长度验证（来自不可信源的无界字符串）
```
QString::arg()
```
的占位符数量不匹配
```
saveToFile()
```
无论I/O错误如何都返回true
跨方法的错误报告模式不一致

参考：

references/qt-review-checklist.md

§ 错误处理与验证

Agent 6: Performance & Code Quality

Agent 6: 性能与代码质量

Scope: Performance anti-patterns, dead code, unnecessary copies, code smells.

Check for:

```
QRegularExpression
```
constructed inside a loop (expensive compilation on every iteration)
```
roleNames()
```
rebuilding QHash on every call (should cache)
Non-const range-for over COW-shared QList/QHash triggering unnecessary detach/deep-copy
Non-const
```
operator[]
```
on shared QHash (triggers detach) — use
```
.value()
```
for reads
Expensive operation before cheap early-exit check (wasted allocation)
Dead/unreachable code (functions never called, branches that are always true/false given preconditions)
Magic numbers without named constants
God classes violating Single Responsibility
Copy-pasted validation/logic across classes
Stale member caches not invalidated on model changes (e.g. search cache surviving data edits)
```
QMap
```
/
```
QHash
```
iteration order nondeterminism when selecting a "best" or "first" entry (
```
.first()
```
changes if keys are added; use deterministic tie-breaking)
```
QMap
```
for small fixed-size constant data (use array/switch)
Returning QList/container by value from frequently-called methods (implicit deep copy on every call — return const ref or cache)
Member variables maintained (appended, capped) but never read by any method (dead state — wasted CPU and memory)
Missing re-entrancy guard on methods that emit signals which could trigger re-entry
Setter silently resetting unrelated state without signal
Early return skipping status/signal updates

References:

references/qt-review-checklist.md

§ Performance & Code Quality

范围：性能反模式、死代码、不必要的复制、代码异味。

检查内容：

在循环内构造
```
QRegularExpression
```
（每次迭代都要进行昂贵的编译）
```
roleNames()
```
每次调用都重建QHash（应缓存）
对COW共享的QList/QHash使用非const范围for循环，触发不必要的分离/深拷贝
对共享QHash使用非const
```
operator[]
```
（触发分离）——读取时使用
```
.value()
```
在廉价的提前退出检查前执行昂贵操作（浪费内存分配）
死代码/不可达代码（从未被调用的函数、给定前置条件下始终为真/假的分支）
无命名常量的魔法数字
违反单一职责原则的上帝类
跨类复制粘贴的验证/逻辑
模型变更时未失效的陈旧成员缓存（例如搜索缓存在数据编辑后仍保留）
选择“最佳”或“第一个”条目时
```
QMap
```
/
```
QHash
```
迭代顺序不确定（添加键时
```
.first()
```
会变化；使用确定性平局规则）
小型固定大小常量数据使用
```
QMap
```
（使用数组/switch）
频繁调用的方法按值返回QList/容器（每次调用都会隐式深拷贝——返回const引用或缓存）
维护（追加、限制大小）但从未被任何方法读取的成员变量（死状态——浪费CPU和内存）
可能触发重入的信号发射方法缺少重入防护
Setter静默重置无关状态且无信号通知
提前返回跳过状态/信号更新

参考：

references/qt-review-checklist.md

§ 性能与代码质量

Confidence scoring guidelines

置信度评分指南

Confidence	Meaning	Action
90–100	Certain: direct rule violation with full symbol trace	Report as finding
80–89	High: rule violation confirmed but edge case possible	Report as finding
60–79	Medium: likely issue but cannot fully verify	Report as investigation target
<60	Low: suspicion only	Suppress entirely

Investigation targets are findings the agent believes are real but cannot fully verify — e.g. noexcept correctness requiring whole-program analysis, dead code that may have callers outside scope, or design-intent judgments like virtual access levels. These are presented in a separate section for human verification. Maximum 10 investigation targets per report, prioritized by confidence within the 60–79 band.

置信度	含义	操作
90–100	确定：直接违反规则，且有完整符号追踪	作为问题报告
80–89	高：已确认违反规则，但可能存在边缘情况	作为问题报告
60–79	中：可能存在问题，但无法完全验证	作为待调查目标报告
<60	低：仅为怀疑	完全忽略

待调查目标是Agent识别但无法完全验证的问题——例如需要全程序分析的noexcept正确性、范围外可能有调用者的死代码，或虚拟访问级别等设计意图判断。这些将在单独的部分呈现，供人工验证。每份报告最多10个待调查目标，按60–79区间内的置信度排序。

Output format

输出格式

Present the final report as follows. Use exactly this structure.

undefined

按以下格式呈现最终报告。严格遵循此结构。

undefined

Qt Code Review Report

Qt代码审查报告

Scope: [diff:

git diff HEAD~1..HEAD

| files: <paths>] Files reviewed: N Issues found: N (M from lint, K from deep analysis)

范围：[差异:

git diff HEAD~1..HEAD

| 文件: <路径>] 审查文件数：N 发现问题数：N（M来自代码检查，K来自深度分析）

Lint findings

代码检查发现

For each lint finding:

每个代码检查发现按以下格式呈现：

[L-NNN] <Short title>

[L-NNN] <简短标题>

File:
```
path/to/file.cpp:42
```
Rule: <rule ID from checklist>
Finding: <what the script detected>
Mitigation: <what to do, in prose — no code patches>

文件：
```
path/to/file.cpp:42
```
规则：<检查清单中的规则ID>
发现：<脚本检测到的内容>
缓解方案：<具体操作建议，用 prose 描述——不提供代码补丁>

Deep analysis findings

深度分析发现

For each agent finding:

每个Agent发现按以下格式呈现：

[D-NNN] <Short title>

[D-NNN] <简短标题>

File:
```
path/to/file.cpp:42
```
Category: <agent name: Model Contracts | Ownership & Lifecycle | Thread Safety | API & C++ Correctness | Error Handling | Performance & Quality>
Confidence: NN/100
Finding: <description of the issue>
Trace: <how the issue was confirmed — which symbols were followed, what was checked>
Mitigation: <what to do, in prose — no code patches>

文件：
```
path/to/file.cpp:42
```
类别：<Agent名称: 模型契约 | 所有权与生命周期 | 线程安全 | API与C++正确性 | 错误处理 | 性能与质量>
置信度：NN/100
发现：<问题描述>
追踪：<问题确认方式——追踪了哪些符号，检查了哪些内容>
缓解方案：<具体操作建议，用 prose 描述——不提供代码补丁>

Investigation targets (human verification needed)

待调查目标（需人工验证）

Findings the agent identified but could not fully verify. Maximum 10, sorted by confidence. These require human judgment.

For each investigation target:

Agent识别但无法完全验证的问题。最多10个，按置信度排序。这些需要人工判断。

每个待调查目标按以下格式呈现：

[I-NNN] <Short title>

[I-NNN] <简短标题>

File:
```
path/to/file.cpp:42
```
Category: <agent name>
Confidence: NN/100
Finding: <what the agent suspects>
Unverified because: <what the agent could not confirm — e.g. "cannot trace all callees for throw potential", "only one implementation visible in scope">
How to verify: <specific action for the reviewer>

文件：
```
path/to/file.cpp:42
```
类别：<Agent名称>
置信度：NN/100
发现：<Agent怀疑的问题>
未验证原因：<Agent无法确认的内容——例如“无法追踪所有可能抛出异常的调用者”、“范围内仅可见一个实现”>
验证方式：<审查者的具体操作建议>

Summary

摘要

Category	Lint	Deep	Investigate	Total
...	N	N	N	N
Total	M	K	I	N

Findings below confidence 60 are suppressed entirely.

undefined

类别	代码检查	深度分析	待调查	总计
...	N	N	N	N
总计	M	K	I	N

置信度低于60的发现已被完全忽略。

undefined

References

参考文件

The following reference files contain detailed checklists extracted from the Qt wiki "Things To Look Out For In Reviews":

```
references/qt-review-checklist.md
```
— Universal Qt6 C++ review rules (always loaded)
```
references/qt-framework-checklist.md
```
— Qt framework/module development rules (loaded only in framework mode)
```
references/qt-deprecated-classes.md
```
— Classes and patterns that should no longer be used in Qt implementation
```
references/lint-scripts/qt_review_lint.py
```
— Single-pass Python linter (runs all 60+ checks in <1s)

以下参考文件包含从Qt wiki“审查中需要注意的事项”提取的详细检查清单：

```
references/qt-review-checklist.md
```
— 通用Qt6 C++审查规则（始终加载）
```
references/qt-framework-checklist.md
```
— Qt框架/模块开发规则（仅在框架模式下加载）
```
references/qt-deprecated-classes.md
```
— Qt实现中不应再使用的类和模式
```
references/lint-scripts/qt_review_lint.py
```
— 单遍Python代码检查工具（<1秒内完成60+项检查）