qt-qml-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Qt QML Code Review

Qt QML代码审查

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

这是针对Qt6 QML代码的结构化只读代码审查技能，结合了确定性代码检查与针对六个重点领域的并行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 QML code
When the user asks to validate Qt6 QML code quality

当用户提及审查相关任务时：例如"review"、"check"、"audit"、"look over"、"code review"、"sanity check"
建议在提交QML代码前运行此技能
当用户要求验证Qt6 QML代码质量时

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.

由以下表述触发："this commit"、"these changes"、"the diff"、"what I changed"、"my changes"、"staged changes"、"outstanding changes"、"before I commit"

操作：运行

git diff

（未暂存）和

git diff --cached

（已暂存）获取变更集。如果用户说"this commit"，则使用

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

*.qml

files in the specified scope. Review all matched files.

由以下表述触发："review the codebase"、"audit the project"、"check the repository"、"review src/"，或当用户给出特定文件/目录路径但未提及提交相关表述时。

操作：在指定范围内匹配

*.qml

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

Execution order

执行顺序

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

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

Phase 1: Deterministic linting (Python script)

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

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 1b.

bash

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

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

bash

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

If python3 is not found, fall back to:

如果未找到python3， fallback到：

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


This single-pass scanner encodes all mechanically-checkable rules
from the QML review checklist. It reads each file once and evaluates
all rules per line, plus block-level structural checks. Output is
deterministic and repeatable. The linter is authoritative -- do not
second-guess its output.

Collect all output before proceeding.

**Rule categories** (47+ checks):
- **IMP** (Imports) -- ordering, versioning, redundancy, deprecation
- **ORD** (Ordering) -- QML attribute ordering convention
- **BND** (Bindings) -- property var, imperative =, Qt.binding style
- **LAY** (Layout) -- anchors/Layout mixing, sizing in layouts
- **LDR** (Loader) -- status guards, createComponent, createQmlObject
- **DEL** (Delegates) -- required properties, reuse safety, connect()
- **STA** (States) -- PropertyChanges syntax, transitions, StateGroup
- **IMG** (Images) -- sourceSize, asynchronous loading
- **PRF** (Performance) -- transparent rect, opacity, clip, layer
- **STY** (Style) -- id:root, camelCase, group notation
- **SIG** (Signals) -- Connections target, handler syntax
- **ERR** (Error/Security) -- hardcoded http://, non-portable paths
- **JS** (JavaScript) -- var/let/const, loose equality

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


这个单遍扫描工具编码了QML审查清单中所有可机械检查的规则。它读取每个文件一次，逐行评估所有规则，同时进行块级结构检查。输出结果具有确定性和可重复性。该检查工具的结果具有权威性——请勿质疑其输出。

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

**规则类别**（47+项检查）：
- **IMP**（导入）——排序、版本控制、冗余、废弃
- **ORD**（排序）——QML属性排序规范
- **BND**（绑定）——property var、命令式赋值、Qt.binding风格
- **LAY**（布局）——anchors/Layout混用、布局内尺寸设置
- **LDR**（加载器）——状态守卫、createComponent、createQmlObject
- **DEL**（委托）——必填属性、复用安全性、connect()
- **STA**（状态）——PropertyChanges语法、过渡效果、StateGroup
- **IMG**（图片）——sourceSize、异步加载
- **PRF**（性能）——透明矩形、透明度、裁剪、图层
- **STY**（风格）——id:root、驼峰命名、组表示法
- **SIG**（信号）——Connections目标、处理器语法
- **ERR**（错误/安全）——硬编码http://、非可移植路径
- **JS**（JavaScript）——var/let/const、松散相等判断

Phase 1b: System qmllint (optional)

阶段1b：系统qmllint（可选）

Attempt to run

qmllint

if available on the system. Detection order:

```
$QT_HOST_PATH/bin/qmllint
```
```
which qmllint
```
/
```
where qmllint
```
Skip if not found (warn user)

If found, run with JSON output:

bash

qmllint --json - -I <import-paths> <files...>

Parse the JSON output and merge with Python linter findings. Deduplicate by file+line+issue. qmllint is authoritative for type- level checks (unresolved types, incompatible assignments, alias cycles). The Python linter is authoritative for style, ordering, and performance patterns that qmllint does not cover.

尝试运行系统中可用的

qmllint

。检测顺序：

```
$QT_HOST_PATH/bin/qmllint
```
```
which qmllint
```
/
```
where qmllint
```
如果未找到则跳过（向用户发出警告）

如果找到，以JSON格式输出运行：

bash

qmllint --json - -I <import-paths> <files...>

解析JSON输出并与Python代码检查工具的结果合并。按文件+行号+问题去重。qmllint在类型级检查（未解析类型、不兼容赋值、别名循环）方面具有权威性。Python代码检查工具在qmllint未覆盖的风格、排序和性能模式检查方面具有权威性。

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: Bindings & Properties") 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, qmllint output (if available), and all agent findings. Deduplicate (same file+line+issue = one finding). Apply confidence scoring. Format the final report using the output format below.

合并代码检查脚本输出、qmllint输出（如果可用）以及所有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)
The Phase 1b qmllint output if available
Their specific mission below

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

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

范围内的文件列表
阶段1的代码检查输出（以便跳过已标记的问题）
阶段1b的qmllint输出（如果可用）
其具体任务描述

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

Agent 1: Bindings & Properties

Agent 1: 绑定与属性

Scope: Binding correctness, property types, alias chains, qualified lookup, binding loops.

Check for:

Multi-cycle binding loops (A changes B via handler, B's binding updates A) -- runtime only detects single-cycle
Property alias chains (alias to alias) where intermediate components may not be initialized
Unqualified property access (bare
```
someProperty
```
instead of
```
root.someProperty
```
) -- complements qmllint
```
unqualified
```
warning with semantic context
```
Qt.binding()
```
closures capturing loop variables by reference (use
```
let
```
not
```
var
```
)
```
pragma ComponentBehavior: Bound
```
missing on files with delegates that access outer-scope ids
Missing
```
readonly
```
on properties that are bound but never imperatively assigned

References:

references/qt-qml-review-checklist.md

sections 3 (Bindings & Properties)

范围：绑定正确性、属性类型、别名链、限定查找、绑定循环。

检查内容：

多循环绑定（A通过处理器修改B，B的绑定更新A）——运行时仅能检测单循环
属性别名链（别名指向别名），其中中间组件可能未初始化
非限定属性访问（直接使用
```
someProperty
```
而非
```
root.someProperty
```
）——补充qmllint的
```
unqualified
```
警告并提供语义上下文
```
Qt.binding()
```
闭包通过引用捕获循环变量（应使用
```
let
```
而非
```
var
```
）
使用委托且访问外部作用域id的文件缺少
```
pragma ComponentBehavior: Bound
```
已绑定但从未被命令式赋值的属性缺少
```
readonly
```
修饰符

参考：

references/qt-qml-review-checklist.md

第3节（绑定与属性）

Agent 2: Layout & Anchoring

Agent 2: 布局与锚定

Scope: Anchoring correctness, layout sizing, visual tree structure.

Check for:

Anchoring to items with
```
visible: false
```
(resolve the target id, check its
```
visible
```
property)
Anchoring across unrelated visual tree branches (not sharing a common parent)
Items in Layouts using
```
implicitWidth
```
/
```
implicitHeight
```
bindings that could create feedback loops
Missing
```
Layout.fillWidth
```
/
```
Layout.fillHeight
```
on items that should stretch
Nested Layouts without clear sizing policy (ambiguous size negotiation)

References:

references/qt-qml-review-checklist.md

section 4 (Layout & Anchoring)

范围：锚定正确性、布局尺寸、视觉树结构。

检查内容：

锚定到
```
visible: false
```
的项目（解析目标id，检查其
```
visible
```
属性）
在不共享公共父级的无关视觉树分支之间进行锚定
布局中的项目使用
```
implicitWidth
```
/
```
implicitHeight
```
绑定，可能导致反馈循环
应拉伸的项目缺少
```
Layout.fillWidth
```
/
```
Layout.fillHeight
```
嵌套布局缺少明确的尺寸策略（尺寸协商模糊）

参考：

references/qt-qml-review-checklist.md

第4节（布局与锚定）

Agent 3: Component Loading & Lifecycle

Agent 3: 组件加载与生命周期

Scope: Loader patterns, dynamic object creation, Connections lifecycle, C++ integration.

Check for:

```
Component.createObject()
```
return values not tracked or destroyed (memory leak)
Loader switching between
```
source
```
and
```
sourceComponent
```
at runtime (unsupported)
Image with dynamic/network source missing
```
Image.status
```
error handling
```
Connections
```
with dynamically-changing
```
target
```
not handling
```
null
```
target state
Context properties (
```
rootContext()->setContextProperty()
```
) in C++ integration code
Object ownership issues at QML/C++ boundary (parentless objects returned from invokable functions)

References:

references/qt-qml-review-checklist.md

sections 5 (Loader), 8 (Images), 13 (C++ Integration)

范围：Loader模式、动态对象创建、Connections生命周期、C++集成。

检查内容：

```
Component.createObject()
```
的返回值未被跟踪或销毁（内存泄漏）
Loader在运行时切换
```
source
```
和
```
sourceComponent
```
（不支持此操作）
使用动态/网络源的Image缺少
```
Image.status
```
错误处理
```
Connections
```
的
```
target
```
动态变化但未处理
```
null
```
目标状态
C++集成代码中的上下文属性（
```
rootContext()->setContextProperty()
```
）
QML/C++边界处的对象所有权问题（可调用函数返回无父对象）

参考：

references/qt-qml-review-checklist.md

第5节（Loader）、第8节（图片）、第13节（C++集成）

Agent 4: ListView & Delegate Correctness

Agent 4: ListView与委托正确性

Scope: Model-view patterns, delegate lifecycle, reuse safety, required properties.

Check for:

Missing
```
required property int index
```
when
```
index
```
is used in a delegate that declares other required properties
Delegate accessing
```
model.roleName
```
for roles not defined in the model's
```
roleNames()
```
Complex delegates (nested Repeaters, multiple Loaders, heavy bindings) that will degrade scroll performance
```
currentIndex
```
usage without guards for known Qt bugs (QTBUG-48633, QTBUG-93293)
```
DelegateChooser
```
patterns that could fail on non-QAbstractItemModel (choice made once at creation, not re-evaluated)
Pooled delegates remaining visible (missing
```
onPooled: visible = false
```
pattern)

References:

references/qt-qml-review-checklist.md

section 6 (ListView & Delegates)

范围：模型-视图模式、委托生命周期、复用安全性、必填属性。

检查内容：

当委托中使用
```
index
```
且声明了其他必填属性时，缺少
```
required property int index
```
委托访问模型
```
roleNames()
```
中未定义的
```
model.roleName
```
复杂委托（嵌套Repeater、多个Loader、大量绑定）会降低滚动性能
使用
```
currentIndex
```
时未针对已知Qt漏洞添加防护（QTBUG-48633、QTBUG-93293）
```
DelegateChooser
```
模式在非QAbstractItemModel上可能失效（创建时仅选择一次，不会重新评估）
池化委托仍保持可见（缺少
```
onPooled: visible = false
```
模式）

参考：

references/qt-qml-review-checklist.md

第6节（ListView与委托）

Agent 5: States, Transitions & Structure

Agent 5: 状态、过渡与结构

Scope: State machine correctness, migration patterns, component structure.

Check for:

```
PropertyChanges.restoreEntryValues
```
surprises (properties reverting on state exit when developer expects them to persist)
```
Binding.restoreMode
```
mismatch from Qt 5 migration (default changed from
```
RestoreNone
```
to
```
RestoreBindingOrValue
```
)
Deprecated
```
Connections
```
handler syntax (
```
onFoo:
```
) vs modern
```
function onFoo()
```
in migrated code
```
QtGraphicalEffects
```
imports that should be migrated to
```
MultiEffect
```
(Qt 6.5+)
Top-level component states that should use
```
StateGroup
```
for reusability
Missing
```
from
```
/
```
to
```
on transitions that could fire unexpectedly when new states are added

References:

references/qt-qml-review-checklist.md

sections 7 (States), 14 (Migration)

范围：状态机正确性、迁移模式、组件结构。

检查内容：

```
PropertyChanges.restoreEntryValues
```
的意外行为（开发者期望属性在状态退出后保持不变，但实际会恢复）

Qt 5迁移中

Binding.restoreMode

不匹配（默认值从

RestoreNone

改为

RestoreBindingOrValue

）

已废弃的
```
Connections
```
处理器语法（
```
onFoo:
```
）与迁移代码中的现代语法
```
function onFoo()
```
混用
应迁移到
```
MultiEffect
```
的
```
QtGraphicalEffects
```
导入（Qt 6.5+）
应使用
```
StateGroup
```
以提高复用性的顶级组件状态
过渡效果缺少
```
from
```
/
```
to
```
，添加新状态时可能意外触发

参考：

references/qt-qml-review-checklist.md

第7节（状态）、第14节（迁移）

Agent 6: Performance & Code Quality

Agent 6: 性能与代码质量

Scope: Performance anti-patterns, rendering cost, JavaScript quality, style consistency.

Check for:

Expensive expressions in property bindings (function calls that should be cached as
```
readonly property
```
)
```
QRegularExpression
```
or complex computation inside loops
Missing
```
Text.PlainText
```
when rich text is not needed (default
```
textFormat
```
incurs parsing overhead)
```
font.preferShaping: false
```
opportunity (when text shaping features are unused)
Signals that communicate down (should be functions) or functions that communicate up (should be signals)
Unnecessary
```
id
```
assignments on objects never referenced
Custom properties scattered across items instead of consolidated in
```
QtObject { id: privates }
```
Singletons used for data (should use property injection for testability)
Pointer handler opportunities (MouseArea that should be TapHandler/DragHandler for multi-touch)
Reusable components with explicit
```
width
```
/
```
height
```
instead of
```
implicitWidth
```
/
```
implicitHeight
```
(prevents consumer resizing)
```
parent
```
used without null-check in delegates or Loader items (can be null during creation/destruction)
Missing
```
pragma ComponentBehavior: Bound
```
on files with delegates that access outer-scope ids

References:

references/qt-qml-review-checklist.md

sections 9 (Performance), 10 (Style), 11 (Signals), 12 (JavaScript), 13 (C++ Integration)

范围：性能反模式、渲染成本、JavaScript质量、风格一致性。

检查内容：

属性绑定中的昂贵表达式（应缓存为
```
readonly property
```
的函数调用）
循环内使用
```
QRegularExpression
```
或复杂计算
不需要富文本时缺少
```
Text.PlainText
```
（默认
```
textFormat
```
会产生解析开销）
可设置
```
font.preferShaping: false
```
的场景（未使用文本整形功能时）
向下传递的信号（应使用函数）或向上传递的函数（应使用信号）
从未被引用的对象上不必要的
```
id
```
赋值
分散在各个项目中的自定义属性未整合到
```
QtObject { id: privates }
```
中
用于数据存储的单例（应使用属性注入以提高可测试性）
可使用指针处理器的场景（应将MouseArea替换为TapHandler/DragHandler以支持多点触控）
可复用组件使用显式
```
width
```
/
```
height
```
而非
```
implicitWidth
```
/
```
implicitHeight
```
（限制使用者调整尺寸）
委托或Loader项目中使用
```
parent
```
但未做空值检查（创建/销毁期间可能为null）
使用委托且访问外部作用域id的文件缺少
```
pragma ComponentBehavior: Bound
```

参考：

references/qt-qml-review-checklist.md

第9节（性能）、第10节（风格）、第11节（信号）、第12节（JavaScript）、第13节（C++集成）

Confidence scoring guidelines

置信度评分指南

Confidence	Meaning	Action
90-100	Certain: direct rule violation with full 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. 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识别出但无法完全验证的问题。这些问题会单独列出供人工验证。每份报告最多10个，按60-79区间内的置信度排序。

Output format

输出格式

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

undefined

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

undefined

QML Code Review Report

QML代码审查报告

Scope: [diff:

git diff HEAD~1..HEAD

| files: <paths>] Files reviewed: N Issues found: N (M from lint, K from deep analysis) qmllint: [ran / not available]

范围：[diff:

git diff HEAD~1..HEAD

| 文件: <路径>] 审查文件数：N 发现问题数：N（其中M个来自代码检查，K个来自深度分析） qmllint：[已运行 / 不可用]

Lint findings

代码检查发现

For each lint finding:

每个代码检查发现的格式：

[L-NNN] <Short title>

[L-NNN] <简短标题>

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

文件：
```
path/to/file.qml:42
```
规则：<检查清单中的规则ID>
发现：<脚本检测到的内容>
修复建议：<具体操作说明，无需代码补丁>

Deep analysis findings

深度分析发现

For each agent finding:

每个Agent发现的格式：

[D-NNN] <Short title>

[D-NNN] <简短标题>

File:
```
path/to/file.qml:42
```
Category: <agent name: Bindings & Properties | Layout & Anchoring | Component Loading & Lifecycle | ListView & Delegates | States & Structure | 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.qml:42
```
类别：<Agent名称：绑定与属性 | 布局与锚定 | 组件加载与生命周期 | ListView与委托 | 状态与结构 | 性能与质量>
置信度：NN/100
发现：<问题描述>
跟踪记录：<问题的确认过程——跟踪了哪些符号、检查了哪些内容>
修复建议：<具体操作说明，无需代码补丁>

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.qml:42
```
Category: <agent name>
Confidence: NN/100
Finding: <what the agent suspects>
Unverified because: <what the agent could not confirm>
How to verify: <specific action for the reviewer>

文件：
```
path/to/file.qml: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:

```
references/qt-qml-review-checklist.md
```
-- Complete QML review rules (lint + agent rules, always loaded)
```
references/lint-scripts/qt_qml_lint.py
```
-- Single-pass Python linter (runs all 47+ checks in <1s)

以下参考文件包含详细的检查清单：

```
references/qt-qml-review-checklist.md
```
—— 完整的QML审查规则（代码检查+Agent规则，始终加载）
```
references/lint-scripts/qt_qml_lint.py
```
—— 单遍Python代码检查工具（可在1秒内完成47+项检查）